From 4d17befb0d5e5110bfb8fd209c341e867036861a Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 11:39:00 +0300
Subject: [PATCH 01/28] feat(editor): footnotes (reference + definitions model)

Adds footnotes: a superscript marker in the text linked to an editable
definition in a Footnotes section at the end of the page, with auto-numbering
and a read-only hover popover. Chose the reference+definitions model (3 plain
nodes) over an inline atom with a sub-editor specifically for collaboration
safety.

editor-ext (packages/editor-ext/src/lib/footnote/):
- footnoteReference (inline atom, id), footnotesList (block, last child),
  footnoteDefinition (paragraph+, id). renderHTML emits sup[data-footnote-ref]
  / section[data-footnotes] / div[data-footnote-def]; parse-rule priority makes
  the empty reference win over the Superscript mark (else it is dropped on the
  server save).
- numbering: a decoration-only plugin (pure function of doc order) -> every
  client computes identical numbers, no document mutation, Yjs-safe.
- sync plugin: single-pass, always SYNC_META-tagged and skipping remote txns
  (terminates, no loop), idempotent; canonicalizes to one trailing footnotesList
  (merging duplicates), creates missing definitions, drops orphans, and
  coexists with TrailingNode. Disabled in read-only.
- commands setFootnote (one tx: reference + definition at the matching index +
  focus) / removeFootnote (cascade, one undo) / scrollTo*. slash /footnote.

client: superscript NodeView + floating-ui read-only popover; bottom-list and
definition NodeViews; registered in mainExtensions.

server: the three nodes registered in tiptapExtensions so collab/save/export
keep them. Round-trip regression spec guards the Superscript parse-priority.

markdown: turndown/marked round-trip to pandoc/GFM [^id] (+ a code-fence guard
so footnote-like lines inside code blocks are not extracted).

MCP mirror: schema + markdown-converter + commentsToFootnotes rewritten to real
footnote nodes + diff marker counting; NUL sentinels written as \u0000 escapes.

v2 follow-ups (per plan): definition reordering on reference move, id-collision
regeneration on paste, multiple references to one footnote.

Implements docs/footnotes-plan.md (variant B).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../public/locales/ru-RU/translation.json     |   7 +
 .../footnote/footnote-definition-view.tsx     |  47 ++
 .../footnote/footnote-reference-view.tsx      | 145 +++++
 .../components/footnote/footnote.module.css   | 106 ++++
 .../footnote/footnotes-list-view.tsx          |  20 +
 .../components/slash-menu/menu-items.ts       |   9 +
 .../features/editor/extensions/extensions.ts  |  19 +
 .../features/editor/readonly-page-editor.tsx  |  13 +-
 .../src/collaboration/collaboration.util.ts   |   6 +
 .../footnote-superscript-roundtrip.spec.ts    |  61 ++
 packages/editor-ext/package.json              |   3 +-
 packages/editor-ext/src/index.ts              |   1 +
 .../src/lib/footnote/footnote-definition.ts   |  72 +++
 .../lib/footnote/footnote-markdown.test.ts    |  56 ++
 .../src/lib/footnote/footnote-numbering.ts    |  75 +++
 .../src/lib/footnote/footnote-reference.ts    | 328 +++++++++++
 .../src/lib/footnote/footnote-sync.ts         | 197 +++++++
 .../src/lib/footnote/footnote-util.ts         |  77 +++
 .../src/lib/footnote/footnote.test.ts         | 536 ++++++++++++++++++
 .../src/lib/footnote/footnotes-list.ts        |  56 ++
 packages/editor-ext/src/lib/footnote/index.ts |   6 +
 .../src/lib/markdown/utils/footnote.marked.ts | 115 ++++
 .../src/lib/markdown/utils/marked.utils.ts    |  24 +-
 .../src/lib/markdown/utils/turndown.utils.ts  |  89 ++-
 packages/editor-ext/tsconfig.json             |   3 +-
 packages/editor-ext/vitest.config.ts          |   8 +
 packages/mcp/build/lib/collaboration.js       |  67 ++-
 packages/mcp/build/lib/diff.js                |  31 +-
 packages/mcp/build/lib/docmost-schema.js      |  75 +++
 packages/mcp/build/lib/markdown-converter.js  |  21 +
 packages/mcp/build/lib/transforms.js          | 176 ++++--
 packages/mcp/src/lib/collaboration.ts         |  77 ++-
 packages/mcp/src/lib/diff.ts                  |  31 +-
 packages/mcp/src/lib/docmost-schema.ts        |  80 +++
 packages/mcp/src/lib/markdown-converter.ts    |  24 +
 packages/mcp/src/lib/transforms.ts            | 192 +++++--
 packages/mcp/test/unit/footnotes.test.mjs     | 120 ++++
 packages/mcp/test/unit/transforms.test.mjs    |  84 ++-
 38 files changed, 2906 insertions(+), 151 deletions(-)
 create mode 100644 apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
 create mode 100644 apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
 create mode 100644 apps/client/src/features/editor/components/footnote/footnote.module.css
 create mode 100644 apps/client/src/features/editor/components/footnote/footnotes-list-view.tsx
 create mode 100644 apps/server/src/collaboration/footnote-superscript-roundtrip.spec.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-definition.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-numbering.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-reference.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-sync.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote-util.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnote.test.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/footnotes-list.ts
 create mode 100644 packages/editor-ext/src/lib/footnote/index.ts
 create mode 100644 packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
 create mode 100644 packages/editor-ext/vitest.config.ts
 create mode 100644 packages/mcp/test/unit/footnotes.test.mjs

diff --git a/apps/client/public/locales/ru-RU/translation.json b/apps/client/public/locales/ru-RU/translation.json
index 25ff2530..414e75b8 100644
--- a/apps/client/public/locales/ru-RU/translation.json
+++ b/apps/client/public/locales/ru-RU/translation.json
@@ -391,6 +391,13 @@
   "Toggle block": "Сворачиваемый блок",
   "Callout": "Выноска",
   "Insert callout notice.": "Вставить выноску с сообщением.",
+  "Footnote": "Сноска",
+  "Insert a footnote reference.": "Вставить ссылку на сноску.",
+  "Footnotes": "Примечания",
+  "Footnote {{number}}": "Сноска {{number}}",
+  "Go to footnote": "Перейти к сноске",
+  "Back to reference": "Вернуться к ссылке",
+  "Empty footnote": "Пустая сноска",
   "Math inline": "Строчная формула",
   "Insert inline math equation.": "Вставить математическое выражение в строку.",
   "Math block": "Блок формулы",
diff --git a/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx b/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
new file mode 100644
index 00000000..b5aa5486
--- /dev/null
+++ b/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
@@ -0,0 +1,47 @@
+import { NodeViewContent, NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { useTranslation } from "react-i18next";
+import { computeFootnoteNumbers } from "@docmost/editor-ext";
+import classes from "./footnote.module.css";
+
+/**
+ * NodeView for a single footnote definition: a decorative number marker, the
+ * editable content (NodeViewContent), and a "↩" back-link to its reference.
+ * The number is derived from the document (not stored).
+ */
+export default function FootnoteDefinitionView(props: NodeViewProps) {
+  const { node, editor } = props;
+  const { t } = useTranslation();
+  const id = node.attrs.id as string;
+
+  const numbers = computeFootnoteNumbers(editor.state.doc);
+  const number = numbers.get(id) ?? "?";
+
+  const handleBack = (e: React.MouseEvent) => {
+    e.preventDefault();
+    editor.commands.scrollToReference(id);
+  };
+
+  return (
+    <NodeViewWrapper
+      data-footnote-def=""
+      data-id={id}
+      className={classes.definition}
+      style={{ ["--footnote-number" as any]: `"${number}"` }}
+    >
+      <span className={classes.definitionMarker} contentEditable={false}>
+        {number}.
+      </span>
+      <NodeViewContent className={classes.definitionContent} />
+      <span
+        className={classes.backLink}
+        contentEditable={false}
+        onClick={handleBack}
+        role="button"
+        aria-label={t("Back to reference")}
+        title={t("Back to reference")}
+      >
+        ↩
+      </span>
+    </NodeViewWrapper>
+  );
+}
diff --git a/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx b/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
new file mode 100644
index 00000000..c75766da
--- /dev/null
+++ b/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
@@ -0,0 +1,145 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { createPortal } from "react-dom";
+import { useTranslation } from "react-i18next";
+import {
+  autoUpdate,
+  computePosition,
+  flip,
+  offset,
+  shift,
+} from "@floating-ui/dom";
+import {
+  FOOTNOTE_DEFINITION_NAME,
+  computeFootnoteNumbers,
+} from "@docmost/editor-ext";
+import { ActionIcon } from "@mantine/core";
+import { IconArrowDown } from "@tabler/icons-react";
+import classes from "./footnote.module.css";
+
+/**
+ * Read the plain text of the footnote definition with `id` directly from the
+ * editor state. No sub-editor: the popover is read-only.
+ */
+function getDefinitionText(editor: NodeViewProps["editor"], id: string): string {
+  let text = "";
+  editor.state.doc.descendants((node) => {
+    if (
+      node.type.name === FOOTNOTE_DEFINITION_NAME &&
+      node.attrs.id === id
+    ) {
+      text = node.textContent;
+      return false;
+    }
+    return undefined;
+  });
+  return text;
+}
+
+export default function FootnoteReferenceView(props: NodeViewProps) {
+  const { node, editor, selected } = props;
+  const { t } = useTranslation();
+  const id = node.attrs.id as string;
+
+  const anchorRef = useRef<HTMLElement | null>(null);
+  const popoverRef = useRef<HTMLDivElement | null>(null);
+  const [open, setOpen] = useState(false);
+
+  // Number is derived (not stored) — recompute from the current doc.
+  const numbers = computeFootnoteNumbers(editor.state.doc);
+  const number = numbers.get(id) ?? "?";
+  const defText = open ? getDefinitionText(editor, id) : "";
+
+  const position = useCallback(() => {
+    const anchor = anchorRef.current;
+    const popup = popoverRef.current;
+    if (!anchor || !popup) return;
+    computePosition(anchor, popup, {
+      placement: "top",
+      middleware: [offset(6), flip(), shift({ padding: 8 })],
+    }).then(({ x, y }) => {
+      popup.style.left = `${x}px`;
+      popup.style.top = `${y}px`;
+    });
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    const popup = popoverRef.current;
+    if (!anchor || !popup) return;
+
+    const cleanup = autoUpdate(anchor, popup, position);
+
+    const onPointerDown = (e: PointerEvent) => {
+      if (
+        popup.contains(e.target as Node) ||
+        anchor.contains(e.target as Node)
+      ) {
+        return;
+      }
+      setOpen(false);
+    };
+    document.addEventListener("pointerdown", onPointerDown, true);
+
+    return () => {
+      cleanup();
+      document.removeEventListener("pointerdown", onPointerDown, true);
+    };
+  }, [open, position]);
+
+  const handleGoTo = (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setOpen(false);
+    editor.commands.scrollToFootnote(id);
+  };
+
+  return (
+    <NodeViewWrapper as="span" style={{ display: "inline" }}>
+      <sup
+        ref={(el) => (anchorRef.current = el)}
+        data-footnote-ref=""
+        data-id={id}
+        className={`${classes.reference} ${selected ? classes.selected : ""}`}
+        onMouseEnter={() => setOpen(true)}
+        onClick={(e) => {
+          e.preventDefault();
+          setOpen((v) => !v);
+        }}
+        // The decoration sets --footnote-number; provide a fallback inline.
+        style={{ ["--footnote-number" as any]: `"${number}"` }}
+        aria-label={t("Footnote {{number}}", { number })}
+        role="button"
+      />
+      {open &&
+        createPortal(
+          <div
+            ref={popoverRef}
+            className={classes.popover}
+            role="tooltip"
+            onMouseLeave={() => setOpen(false)}
+          >
+            <div className={classes.popoverHeader}>
+              <span className={classes.popoverNumber}>
+                {t("Footnote {{number}}", { number })}
+              </span>
+              <ActionIcon
+                variant="subtle"
+                size="sm"
+                color="gray"
+                onClick={handleGoTo}
+                aria-label={t("Go to footnote")}
+              >
+                <IconArrowDown size={16} />
+              </ActionIcon>
+            </div>
+            <div className={classes.popoverBody}>
+              {defText || t("Empty footnote")}
+            </div>
+          </div>,
+          document.body,
+        )}
+    </NodeViewWrapper>
+  );
+}
diff --git a/apps/client/src/features/editor/components/footnote/footnote.module.css b/apps/client/src/features/editor/components/footnote/footnote.module.css
new file mode 100644
index 00000000..11c391bd
--- /dev/null
+++ b/apps/client/src/features/editor/components/footnote/footnote.module.css
@@ -0,0 +1,106 @@
+/* Superscript reference marker. The visible number comes from the numbering
+   plugin decoration which sets the --footnote-number CSS variable. */
+.reference {
+  cursor: pointer;
+  color: var(--mantine-color-blue-6);
+  font-weight: 500;
+  vertical-align: super;
+  font-size: 0.75em;
+  line-height: 0;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.reference::after {
+  content: var(--footnote-number, "");
+}
+
+.reference:hover {
+  text-decoration: underline;
+}
+
+.reference.selected {
+  background-color: var(--mantine-color-blue-1);
+  border-radius: 2px;
+}
+
+/* Read-only popover shown on hover/click of a reference. */
+.popover {
+  position: absolute;
+  z-index: 1000;
+  max-width: 360px;
+  padding: var(--mantine-spacing-sm);
+  background: var(--mantine-color-body);
+  color: var(--mantine-color-default-color);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-md);
+  box-shadow: var(--mantine-shadow-md);
+  font-size: var(--mantine-font-size-sm);
+  line-height: 1.4;
+}
+
+.popoverHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-xs);
+  margin-bottom: 4px;
+}
+
+.popoverNumber {
+  font-weight: 600;
+  color: var(--mantine-color-dimmed);
+}
+
+.popoverBody {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* Bottom footnotes container. */
+.list {
+  margin-top: var(--mantine-spacing-lg);
+  padding-top: var(--mantine-spacing-md);
+  border-top: 1px solid var(--mantine-color-default-border);
+}
+
+.listHeading {
+  font-weight: 600;
+  font-size: var(--mantine-font-size-sm);
+  color: var(--mantine-color-dimmed);
+  margin-bottom: var(--mantine-spacing-xs);
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+.definition {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--mantine-spacing-xs);
+  padding: 2px 0;
+}
+
+.definitionMarker {
+  flex: 0 0 auto;
+  min-width: 1.5em;
+  font-variant-numeric: tabular-nums;
+  color: var(--mantine-color-dimmed);
+  user-select: none;
+}
+
+.definitionContent {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.backLink {
+  flex: 0 0 auto;
+  cursor: pointer;
+  color: var(--mantine-color-blue-6);
+  user-select: none;
+  font-size: 0.9em;
+}
+
+.backLink:hover {
+  text-decoration: underline;
+}
diff --git a/apps/client/src/features/editor/components/footnote/footnotes-list-view.tsx b/apps/client/src/features/editor/components/footnote/footnotes-list-view.tsx
new file mode 100644
index 00000000..7b2eb51b
--- /dev/null
+++ b/apps/client/src/features/editor/components/footnote/footnotes-list-view.tsx
@@ -0,0 +1,20 @@
+import { NodeViewContent, NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { useTranslation } from "react-i18next";
+import classes from "./footnote.module.css";
+
+/**
+ * NodeView for the bottom footnotes container. Renders a visual separator and a
+ * localized heading, then the editable list of definitions via NodeViewContent.
+ */
+export default function FootnotesListView(_props: NodeViewProps) {
+  const { t } = useTranslation();
+
+  return (
+    <NodeViewWrapper>
+      <div className={classes.list} contentEditable={false}>
+        <div className={classes.listHeading}>{t("Footnotes")}</div>
+      </div>
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}
diff --git a/apps/client/src/features/editor/components/slash-menu/menu-items.ts b/apps/client/src/features/editor/components/slash-menu/menu-items.ts
index 7f856755..12a5639c 100644
--- a/apps/client/src/features/editor/components/slash-menu/menu-items.ts
+++ b/apps/client/src/features/editor/components/slash-menu/menu-items.ts
@@ -28,6 +28,7 @@ import {
   IconTag,
   IconMoodSmile,
   IconRotate2,
+  IconSuperscript,
 } from "@tabler/icons-react";
 import {
   CommandProps,
@@ -366,6 +367,14 @@ const CommandGroups: SlashMenuGroupedItemsType = {
       command: ({ editor, range }: CommandProps) =>
         editor.chain().focus().deleteRange(range).setDetails().run(),
     },
+    {
+      title: "Footnote",
+      description: "Insert a footnote reference.",
+      searchTerms: ["footnote", "note", "reference", "сноска", "примечание"],
+      icon: IconSuperscript,
+      command: ({ editor, range }: CommandProps) =>
+        editor.chain().focus().deleteRange(range).setFootnote().run(),
+    },
     {
       title: "Callout",
       description: "Insert callout notice.",
diff --git a/apps/client/src/features/editor/extensions/extensions.ts b/apps/client/src/features/editor/extensions/extensions.ts
index 87c7b9e5..9c78ffb0 100644
--- a/apps/client/src/features/editor/extensions/extensions.ts
+++ b/apps/client/src/features/editor/extensions/extensions.ts
@@ -61,6 +61,9 @@ import {
   TransclusionSource,
   TransclusionReference,
   TableView,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
 } from "@docmost/editor-ext";
 import {
   randomElement,
@@ -91,6 +94,9 @@ import PdfView from "@/features/editor/components/pdf/pdf-view.tsx";
 import SubpagesView from "@/features/editor/components/subpages/subpages-view.tsx";
 import TransclusionView from "@/features/editor/components/transclusion/transclusion-view.tsx";
 import TransclusionReferenceView from "@/features/editor/components/transclusion/transclusion-reference-view.tsx";
+import FootnoteReferenceView from "@/features/editor/components/footnote/footnote-reference-view.tsx";
+import FootnotesListView from "@/features/editor/components/footnote/footnotes-list-view.tsx";
+import FootnoteDefinitionView from "@/features/editor/components/footnote/footnote-definition-view.tsx";
 import { common, createLowlight } from "lowlight";
 import plaintext from "highlight.js/lib/languages/plaintext";
 import powershell from "highlight.js/lib/languages/powershell";
@@ -381,6 +387,19 @@ export const mainExtensions = [
   TransclusionReference.configure({
     view: TransclusionReferenceView,
   }),
+  FootnoteReference.configure({
+    view: FootnoteReferenceView,
+    // Skip orphan-cleanup on remote/collaboration steps so collaborating
+    // clients never fight over footnote integrity (deterministic numbering
+    // decorations handle the rest).
+    isRemoteTransaction: (tr: any) => isChangeOrigin(tr),
+  }),
+  FootnotesList.configure({
+    view: FootnotesListView,
+  }),
+  FootnoteDefinition.configure({
+    view: FootnoteDefinitionView,
+  }),
   MarkdownClipboard.configure({
     transformPastedText: true,
   }),
diff --git a/apps/client/src/features/editor/readonly-page-editor.tsx b/apps/client/src/features/editor/readonly-page-editor.tsx
index cd4878a9..e2912893 100644
--- a/apps/client/src/features/editor/readonly-page-editor.tsx
+++ b/apps/client/src/features/editor/readonly-page-editor.tsx
@@ -48,9 +48,16 @@ export default function ReadonlyPageEditor({
   }, []);
 
   const extensions = useMemo(() => {
-    const filteredExtensions = mainExtensions.filter(
-      (ext) => ext.name !== "uniqueID",
-    );
+    const filteredExtensions = mainExtensions
+      .filter((ext) => ext.name !== "uniqueID")
+      // Read-only must only DECORATE footnotes (numbering), never mutate the
+      // doc. Disable the footnote sync/integrity plugin so a programmatic
+      // setContent on a doc the viewer can't edit is never rewritten.
+      .map((ext) =>
+        ext.name === "footnoteReference"
+          ? ext.configure({ enableSync: false })
+          : ext,
+      );
 
     return [
       ...filteredExtensions,
diff --git a/apps/server/src/collaboration/collaboration.util.ts b/apps/server/src/collaboration/collaboration.util.ts
index 554aa43b..0d91d676 100644
--- a/apps/server/src/collaboration/collaboration.util.ts
+++ b/apps/server/src/collaboration/collaboration.util.ts
@@ -44,6 +44,9 @@ import {
   htmlToMarkdown,
   TransclusionSource,
   TransclusionReference,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -109,6 +112,9 @@ export const tiptapExtensions = [
   Status,
   TransclusionSource,
   TransclusionReference,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
 ] as any;
 
 export function jsonToHtml(tiptapJson: any) {
diff --git a/apps/server/src/collaboration/footnote-superscript-roundtrip.spec.ts b/apps/server/src/collaboration/footnote-superscript-roundtrip.spec.ts
new file mode 100644
index 00000000..c496ed66
--- /dev/null
+++ b/apps/server/src/collaboration/footnote-superscript-roundtrip.spec.ts
@@ -0,0 +1,61 @@
+import { htmlToJson, jsonToHtml } from './collaboration.util';
+
+const findFirst = (json: any, type: string): any | undefined => {
+  if (!json || typeof json !== 'object') return undefined;
+  if (json.type === type) return json;
+  if (Array.isArray(json.content)) {
+    for (const child of json.content) {
+      const found = findFirst(child, type);
+      if (found) return found;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Guards the fragile parse-priority approach that lets a `footnoteReference`
+ * NODE win over the `Superscript` MARK for `<sup>` elements. In the server
+ * `tiptapExtensions` list, Superscript is registered BEFORE the footnote nodes,
+ * so without the priority guard a `<sup data-footnote-ref>` would be parsed as
+ * an (empty) superscript mark and the footnote reference would be lost.
+ */
+describe('footnote reference vs superscript mark (server schema round-trip)', () => {
+  const HTML =
+    '<p>Water' +
+    '<sup data-footnote-ref data-id="fn1"></sup>' +
+    ' here.</p>' +
+    '<section data-footnotes>' +
+    '<div data-footnote-def data-id="fn1"><p>First note.</p></div>' +
+    '</section>';
+
+  it('parses <sup data-footnote-ref> into a footnoteReference NODE (not a superscript mark)', () => {
+    const json = htmlToJson(HTML);
+
+    const ref = findFirst(json, 'footnoteReference');
+    expect(ref).toBeDefined();
+    expect(ref.attrs.id).toBe('fn1');
+
+    // It must NOT have been swallowed as a superscript mark on text.
+    const superscriptText = JSON.stringify(json).includes('"superscript"');
+    expect(superscriptText).toBe(false);
+
+    // The matching definition survives too.
+    const def = findFirst(json, 'footnoteDefinition');
+    expect(def).toBeDefined();
+    expect(def.attrs.id).toBe('fn1');
+  });
+
+  it('round-trips an empty footnoteReference back to <sup data-footnote-ref>', () => {
+    const json = htmlToJson(HTML);
+    const html = jsonToHtml(json);
+
+    expect(html).toContain('data-footnote-ref');
+    expect(html).toContain('data-id="fn1"');
+
+    // And a second parse still yields the node (stable round-trip).
+    const json2 = htmlToJson(html);
+    const ref2 = findFirst(json2, 'footnoteReference');
+    expect(ref2).toBeDefined();
+    expect(ref2.attrs.id).toBe('fn1');
+  });
+});
diff --git a/packages/editor-ext/package.json b/packages/editor-ext/package.json
index 23ddcaff..3ada7a59 100644
--- a/packages/editor-ext/package.json
+++ b/packages/editor-ext/package.json
@@ -4,7 +4,8 @@
   "private": true,
   "scripts": {
     "build": "tsc --build",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "vitest run"
   },
   "main": "dist/index.js",
   "module": "./src/index.ts",
diff --git a/packages/editor-ext/src/index.ts b/packages/editor-ext/src/index.ts
index 003d2288..c629c904 100644
--- a/packages/editor-ext/src/index.ts
+++ b/packages/editor-ext/src/index.ts
@@ -33,4 +33,5 @@ export * from "./lib/status";
 export * from "./lib/pdf";
 export * from "./lib/page-break";
 export * from "./lib/resizable-nodeview";
+export * from "./lib/footnote";
 
diff --git a/packages/editor-ext/src/lib/footnote/footnote-definition.ts b/packages/editor-ext/src/lib/footnote/footnote-definition.ts
new file mode 100644
index 00000000..819adb70
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-definition.ts
@@ -0,0 +1,72 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { FOOTNOTE_DEFINITION_NAME } from "./footnote-util";
+
+export interface FootnoteDefinitionOptions {
+  HTMLAttributes: Record<string, any>;
+  view: any;
+}
+
+/**
+ * A single footnote definition: an editable block (paragraphs only, no nested
+ * footnotes) keyed by `id` to its reference. Lives only inside `footnotesList`.
+ */
+export const FootnoteDefinition = Node.create<FootnoteDefinitionOptions>({
+  name: FOOTNOTE_DEFINITION_NAME,
+
+  // paragraph+ keeps definitions simple. Note this does NOT block nested
+  // footnote references on its own: a footnoteReference is inline and the
+  // paragraphs here accept inline content, so the schema would permit one.
+  // Nested references are instead prevented by the setFootnote command and the
+  // sync plugin (which refuse to create/keep a reference inside a definition).
+  content: "paragraph+",
+  defining: true,
+  isolating: true,
+  selectable: false,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      view: null,
+    };
+  },
+
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (element) => element.getAttribute("data-id"),
+        renderHTML: (attributes) => {
+          if (!attributes.id) return {};
+          return { "data-id": attributes.id };
+        },
+      },
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: "div[data-footnote-def]",
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      mergeAttributes(
+        { "data-footnote-def": "", class: "footnote-def" },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+      0,
+    ];
+  },
+
+  addNodeView() {
+    if (!this.options.view) return null;
+    this.editor.isInitialized = true;
+    return ReactNodeViewRenderer(this.options.view);
+  },
+});
diff --git a/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts b/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
new file mode 100644
index 00000000..a6f3d4ab
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { htmlToMarkdown } from "../markdown/utils/turndown.utils";
+import { markdownToHtml } from "../markdown/utils/marked.utils";
+
+// HTML the editor-ext nodes render (sup[data-footnote-ref], section/div).
+const HTML =
+  `<p>Water<sup data-footnote-ref data-id="fn1"></sup> and clay<sup data-footnote-ref data-id="fn2"></sup>.</p>` +
+  `<section data-footnotes>` +
+  `<div data-footnote-def data-id="fn1"><p>First note.</p></div>` +
+  `<div data-footnote-def data-id="fn2"><p>Second note.</p></div>` +
+  `</section>`;
+
+describe("footnote markdown round-trip", () => {
+  it("HTML -> Markdown produces pandoc footnote syntax", () => {
+    const md = htmlToMarkdown(HTML);
+    expect(md).toContain("[^fn1]");
+    expect(md).toContain("[^fn2]");
+    expect(md).toContain("[^fn1]: First note.");
+    expect(md).toContain("[^fn2]: Second note.");
+  });
+
+  it("Markdown -> HTML rebuilds the footnote nodes' HTML", async () => {
+    const md = htmlToMarkdown(HTML);
+    const html = await markdownToHtml(md);
+    expect(html).toContain('data-footnote-ref data-id="fn1"');
+    expect(html).toContain('data-footnote-ref data-id="fn2"');
+    expect(html).toContain("data-footnotes");
+    expect(html).toContain('data-footnote-def data-id="fn1"');
+    expect(html).toContain("First note.");
+    expect(html).toContain("Second note.");
+  });
+
+  it("preserves a [^id]: line shown inside a fenced code block (not a definition)", async () => {
+    // A document that DOCUMENTS footnote syntax inside a code fence. The
+    // `[^demo]: ...` line is example text, not a real definition, and must
+    // survive the Markdown -> HTML conversion verbatim.
+    const md = [
+      "Here is how footnotes look:",
+      "",
+      "```markdown",
+      "Some text[^demo]",
+      "",
+      "[^demo]: this is the definition",
+      "```",
+      "",
+      "End of doc.",
+    ].join("\n");
+
+    const html = await markdownToHtml(md);
+    // The example definition line is kept inside the rendered code block.
+    expect(html).toContain("[^demo]: this is the definition");
+    // It did NOT get pulled out into a real footnotes section.
+    expect(html).not.toContain("data-footnotes");
+    expect(html).not.toContain("data-footnote-def");
+  });
+});
diff --git a/packages/editor-ext/src/lib/footnote/footnote-numbering.ts b/packages/editor-ext/src/lib/footnote/footnote-numbering.ts
new file mode 100644
index 00000000..f93a3b08
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-numbering.ts
@@ -0,0 +1,75 @@
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+import {
+  FOOTNOTE_DEFINITION_NAME,
+  FOOTNOTE_REFERENCE_NAME,
+  computeFootnoteNumbers,
+} from "./footnote-util";
+
+export const footnoteNumberingPluginKey = new PluginKey("footnoteNumbering");
+
+/**
+ * Build the decoration set for footnote numbers. Pure function of the document:
+ * walk references in document order, assign 1-based numbers, then attach a
+ * node decoration (carrying the number via a CSS variable + data attribute) to
+ * every reference and to every matching definition. Because it is deterministic
+ * from the document alone, all collaborating clients compute identical numbers
+ * with no document mutation.
+ */
+export function buildFootnoteDecorations(doc: ProseMirrorNode): DecorationSet {
+  const numbers = computeFootnoteNumbers(doc);
+  const decorations: Decoration[] = [];
+
+  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}";`,
+          }),
+        );
+      }
+    }
+  });
+
+  return DecorationSet.create(doc, decorations);
+}
+
+/**
+ * ProseMirror plugin that renders footnote numbers as decorations. It never
+ * mutates the document (safe in read-only / share and in collaboration) — it
+ * only recomputes decorations from the current doc on each transaction.
+ */
+export function footnoteNumberingPlugin(): Plugin {
+  return new Plugin({
+    key: footnoteNumberingPluginKey,
+    state: {
+      init(_, { doc }) {
+        return buildFootnoteDecorations(doc);
+      },
+      apply(tr, old) {
+        if (!tr.docChanged) return old;
+        return buildFootnoteDecorations(tr.doc);
+      },
+    },
+    props: {
+      decorations(state) {
+        return this.getState(state);
+      },
+    },
+  });
+}
diff --git a/packages/editor-ext/src/lib/footnote/footnote-reference.ts b/packages/editor-ext/src/lib/footnote/footnote-reference.ts
new file mode 100644
index 00000000..90f5e109
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-reference.ts
@@ -0,0 +1,328 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { TextSelection, Transaction } from "@tiptap/pm/state";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import {
+  FOOTNOTE_DEFINITION_NAME,
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTES_LIST_NAME,
+  generateFootnoteId,
+} from "./footnote-util";
+import { footnoteNumberingPlugin } from "./footnote-numbering";
+import { footnoteSyncPlugin } from "./footnote-sync";
+
+export interface FootnoteReferenceOptions {
+  HTMLAttributes: Record<string, any>;
+  view: any;
+  /**
+   * Optional predicate identifying remote/collaboration transactions so the
+   * sync plugin skips them (orphan cleanup must run only on local changes).
+   */
+  isRemoteTransaction?: (tr: Transaction) => boolean;
+  /**
+   * When false, the footnote sync/integrity plugin is fully disabled — it never
+   * appends a transaction. Numbering decorations stay active. Set this in
+   * read-only / share editors so a viewer's doc is decorated (numbered) but
+   * never mutated (e.g. by a programmatic setContent). Defaults to true.
+   */
+  enableSync?: boolean;
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    footnote: {
+      /**
+       * Insert a footnote reference at the cursor and create the matching
+       * (empty) definition in the bottom footnotes list, in one transaction.
+       */
+      setFootnote: () => ReturnType;
+      /**
+       * Remove a footnote reference and cascade-delete its definition (one
+       * transaction so a single undo restores both).
+       */
+      removeFootnote: (id: string) => ReturnType;
+      /** Scroll to (and focus) a footnote definition by id. */
+      scrollToFootnote: (id: string) => ReturnType;
+      /** Scroll to (and select) a footnote reference by id. */
+      scrollToReference: (id: string) => ReturnType;
+    };
+  }
+}
+
+/**
+ * Inline atom that marks a footnote reference in the body text. It holds only
+ * an `id` linking it to its `footnoteDefinition`; the visible number is NOT
+ * stored — it is rendered by the numbering plugin as a decoration (see
+ * footnote-numbering.ts). Modeled on mention.ts (inline atom).
+ *
+ * The reference is forbidden inside code blocks and inside footnote definitions
+ * (no nested footnotes); those restrictions are enforced by the `setFootnote`
+ * command and the sync plugin rather than by schema content expressions, since
+ * an inline group node cannot express "not inside X" declaratively.
+ */
+export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
+  name: FOOTNOTE_REFERENCE_NAME,
+
+  // Higher than the default (100) so its parse rule is considered before the
+  // Superscript mark's <sup> rule.
+  priority: 101,
+
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      view: null,
+      isRemoteTransaction: undefined,
+      enableSync: true,
+    };
+  },
+
+  addProseMirrorPlugins() {
+    const plugins = [footnoteNumberingPlugin()];
+    // Numbering always runs (decoration-only). The sync/integrity plugin is
+    // skipped entirely when sync is disabled (read-only / share) so the viewer's
+    // doc is never mutated.
+    if (this.options.enableSync !== false) {
+      plugins.push(footnoteSyncPlugin(this.options.isRemoteTransaction));
+    }
+    return plugins;
+  },
+
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (element) => element.getAttribute("data-id"),
+        renderHTML: (attributes) => {
+          if (!attributes.id) return {};
+          return { "data-id": attributes.id };
+        },
+      },
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        // High priority so the Superscript mark (which also matches <sup>) does
+        // not claim a footnote reference and drop it as empty content.
+        tag: "sup[data-footnote-ref]",
+        priority: 100,
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "sup",
+      mergeAttributes(
+        { "data-footnote-ref": "", class: "footnote-ref" },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+    ];
+  },
+
+  // Plain-text representation (used by generateText / markdown text fallbacks).
+  renderText({ node }) {
+    return `[^${node.attrs.id ?? ""}]`;
+  },
+
+  addNodeView() {
+    if (!this.options.view) return null;
+    // Force the react node view to render immediately using flush sync.
+    this.editor.isInitialized = true;
+    return ReactNodeViewRenderer(this.options.view);
+  },
+
+  addCommands() {
+    return {
+      setFootnote:
+        () =>
+        ({ state, tr, dispatch, editor }) => {
+          const { schema, selection } = state;
+          const refType = schema.nodes[FOOTNOTE_REFERENCE_NAME];
+          const listType = schema.nodes[FOOTNOTES_LIST_NAME];
+          const defType = schema.nodes[FOOTNOTE_DEFINITION_NAME];
+          if (!refType || !listType || !defType) return false;
+
+          const { $from } = selection;
+
+          // Forbid references inside code blocks and inside footnote definitions
+          // (no nested footnotes).
+          for (let depth = $from.depth; depth > 0; depth--) {
+            const node = $from.node(depth);
+            if (
+              node.type.spec.code ||
+              node.type.name === FOOTNOTE_DEFINITION_NAME ||
+              node.type.name === FOOTNOTES_LIST_NAME
+            ) {
+              return false;
+            }
+          }
+
+          // Make sure the parent accepts an inline atom here.
+          const insertPos = selection.from;
+          if (!$from.parent.type.spec.content?.includes("inline") &&
+              !$from.parent.isTextblock) {
+            return false;
+          }
+
+          const id = generateFootnoteId();
+
+          // 1) Count references that occur strictly before the insertion point;
+          //    the new definition goes at that index in the bottom list so the
+          //    list order matches reference order.
+          let refsBefore = 0;
+          state.doc.nodesBetween(0, insertPos, (node) => {
+            if (node.type.name === FOOTNOTE_REFERENCE_NAME) refsBefore++;
+          });
+
+          // 2) Insert the reference at the cursor.
+          tr.insert(insertPos, refType.create({ id }));
+
+          // 3) Locate (or create) the footnotes list, then insert the new
+          //    definition at index `refsBefore`.
+          const emptyParagraph = schema.nodes.paragraph.create();
+          const definition = defType.create({ id }, emptyParagraph);
+
+          // Find existing list (always the last top-level child if present).
+          let listPos: number | null = null;
+          let listNode: any = null;
+          tr.doc.forEach((child, offset) => {
+            if (child.type.name === FOOTNOTES_LIST_NAME) {
+              listPos = offset;
+              listNode = child;
+            }
+          });
+
+          let defInsidePos: number | null = null;
+          if (listNode == null) {
+            // Create a new list at the very end of the document.
+            const list = listType.create(null, definition);
+            const end = tr.doc.content.size;
+            tr.insert(end, list);
+            // Cursor target: inside the new definition's first paragraph.
+            // end -> list open, +1 definition open, +1 paragraph open.
+            defInsidePos = end + 3;
+          } else {
+            // Insert at the right index within the existing list.
+            const listStart = listPos! + 1; // position of the first definition
+            let pos = listStart;
+            let index = 0;
+            listNode.forEach((defChild: any, defOffset: number) => {
+              if (index < refsBefore) {
+                pos = listStart + defOffset + defChild.nodeSize;
+                index++;
+              }
+            });
+            tr.insert(pos, definition);
+            defInsidePos = pos + 2; // +1 enter definition, +1 enter paragraph
+          }
+
+          if (dispatch) {
+            // Move the cursor into the new definition's paragraph so the user
+            // can immediately type the footnote text.
+            try {
+              const resolved = tr.doc.resolve(
+                Math.min(defInsidePos!, tr.doc.content.size),
+              );
+              tr.setSelection(TextSelection.near(resolved));
+            } catch {
+              // Selection placement is best-effort; ignore failures.
+            }
+            tr.scrollIntoView();
+            dispatch(tr);
+          }
+
+          return true;
+        },
+
+      removeFootnote:
+        (id: string) =>
+        ({ state, tr, dispatch }) => {
+          if (!id) return false;
+
+          // Collect: reference range(s), the definition range, and the list.
+          const refRanges: Array<{ from: number; to: number }> = [];
+          let defRange: { from: number; to: number } | null = null;
+          let listInfo: { pos: number; size: number; count: number } | null =
+            null;
+
+          state.doc.descendants((node, pos) => {
+            if (
+              node.type.name === FOOTNOTE_REFERENCE_NAME &&
+              node.attrs.id === id
+            ) {
+              refRanges.push({ from: pos, to: pos + node.nodeSize });
+            }
+            if (
+              node.type.name === FOOTNOTE_DEFINITION_NAME &&
+              node.attrs.id === id
+            ) {
+              defRange = { from: pos, to: pos + node.nodeSize };
+            }
+            if (node.type.name === FOOTNOTES_LIST_NAME) {
+              listInfo = {
+                pos,
+                size: node.nodeSize,
+                count: node.childCount,
+              };
+            }
+          });
+
+          if (refRanges.length === 0 && !defRange) return false;
+
+          // Build the list of ranges to delete. If removing this definition
+          // would empty the list (it is the list's only child), delete the
+          // entire list instead — an empty footnotesList is invalid schema and
+          // a leftover empty list would be ugly.
+          const ranges: Array<{ from: number; to: number }> = [...refRanges];
+          if (defRange) {
+            if (listInfo && (listInfo as any).count <= 1) {
+              const li = listInfo as { pos: number; size: number };
+              ranges.push({ from: li.pos, to: li.pos + li.size });
+            } else {
+              ranges.push(defRange);
+            }
+          }
+
+          // Delete from the end so earlier positions stay valid.
+          ranges
+            .sort((a, b) => b.from - a.from)
+            .forEach(({ from, to }) => tr.delete(from, to));
+
+          if (dispatch) dispatch(tr);
+          return true;
+        },
+
+      scrollToFootnote:
+        (id: string) =>
+        ({ editor }) => {
+          if (!id) return false;
+          const dom = editor.view.dom.querySelector(
+            `[data-footnote-def][data-id="${id}"]`,
+          ) as HTMLElement | null;
+          if (!dom) return false;
+          dom.scrollIntoView({ behavior: "smooth", block: "center" });
+          return true;
+        },
+
+      scrollToReference:
+        (id: string) =>
+        ({ editor }) => {
+          if (!id) return false;
+          const dom = editor.view.dom.querySelector(
+            `sup[data-footnote-ref][data-id="${id}"]`,
+          ) as HTMLElement | null;
+          if (!dom) return false;
+          dom.scrollIntoView({ behavior: "smooth", block: "center" });
+          return true;
+        },
+    };
+  },
+});
diff --git a/packages/editor-ext/src/lib/footnote/footnote-sync.ts b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
new file mode 100644
index 00000000..ffd2e136
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
@@ -0,0 +1,197 @@
+import { Plugin, PluginKey, Transaction } from "@tiptap/pm/state";
+import { Node as ProseMirrorNode, Fragment } from "@tiptap/pm/model";
+import {
+  FOOTNOTE_DEFINITION_NAME,
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTES_LIST_NAME,
+} from "./footnote-util";
+
+export const footnoteSyncPluginKey = new PluginKey("footnoteSync");
+
+const SYNC_META = "footnoteSyncApplied";
+
+interface FootnoteScan {
+  /** Reference ids in document order, first occurrence only, de-duplicated. */
+  referenceIds: string[];
+  /** definition id -> node (last occurrence wins, matching scan order). */
+  definitions: Map<string, ProseMirrorNode>;
+  /** Every top-level footnotesList node, in document order. */
+  lists: Array<{ pos: number; node: ProseMirrorNode }>;
+}
+
+function scan(doc: ProseMirrorNode): FootnoteScan {
+  const referenceIds: string[] = [];
+  const seenRefs = new Set<string>();
+  const definitions = new Map<string, ProseMirrorNode>();
+  const lists: Array<{ pos: number; node: ProseMirrorNode }> = [];
+
+  doc.descendants((node, pos) => {
+    if (node.type.name === FOOTNOTE_REFERENCE_NAME) {
+      const id = node.attrs.id;
+      if (id && !seenRefs.has(id)) {
+        seenRefs.add(id);
+        referenceIds.push(id);
+      }
+    }
+    if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
+      const id = node.attrs.id;
+      if (id) definitions.set(id, node);
+    }
+    if (node.type.name === FOOTNOTES_LIST_NAME) {
+      lists.push({ pos, node });
+    }
+  });
+
+  return { referenceIds, definitions, lists };
+}
+
+/**
+ * Idempotent integrity pass for footnotes. Runs only on LOCAL document changes
+ * (skips remote/collaboration steps and — crucially — its own appended meta) so
+ * the plugin can never re-trigger itself, guaranteeing termination.
+ *
+ * Everything is computed against the CURRENT document in a SINGLE invocation and
+ * emitted as AT MOST ONE transaction, always tagged with SYNC_META (and
+ * addToHistory:false). The strategy is "rebuild the canonical footnotes section
+ * from the desired end-state" rather than running several self-triggering
+ * passes:
+ *
+ *  1. Collect every footnote reference id in document order (the source of
+ *     truth for which definitions must exist and in what order).
+ *  2. Compute the desired list of definitions: one per referenced id, in
+ *     reference order, reusing the existing definition node when present or
+ *     creating an empty one when missing. Orphan definitions (no matching
+ *     reference) are dropped.
+ *  3. Compare against the actual footnotesList state:
+ *       - no references           -> there must be NO list (remove any);
+ *       - references present       -> there must be exactly ONE list, holding
+ *                                     exactly the desired definitions, and it
+ *                                     must sit after all real body content.
+ *  4. If the document already matches the desired end-state, return null (no
+ *     transaction) — this idempotence is what stops oscillation.
+ *
+ * Placement note: the list is considered correctly placed when nothing but
+ * EMPTY paragraphs follow it. This is deliberate so the plugin coexists with a
+ * trailing-node plugin (which keeps an empty paragraph at the very end of the
+ * doc): the footnote list does not need to be the literal last child, only the
+ * last block of meaningful content. Without this, the two plugins would
+ * ping-pong forever (list moved to end -> trailing paragraph appended -> list
+ * no longer last -> moved again ...).
+ *
+ * Paste id-collision regeneration is left to the paste handler / v2; the common
+ * cases (orphans, missing definitions, multiple/empty/misplaced lists) are
+ * covered here.
+ */
+export function footnoteSyncPlugin(
+  isRemoteTransaction?: (tr: Transaction) => boolean,
+): Plugin {
+  return new Plugin({
+    key: footnoteSyncPluginKey,
+    appendTransaction(transactions, _oldState, newState) {
+      // Only react to document changes.
+      if (!transactions.some((t) => t.docChanged)) return null;
+      // Skip our OWN appended transaction. This is the guard that makes the
+      // plugin loop-safe: the transaction we emit carries SYNC_META, so when
+      // ProseMirror feeds it back to appendTransaction we bail out immediately
+      // and never produce a follow-up. (Termination invariant.)
+      if (transactions.some((t) => t.getMeta(SYNC_META))) return null;
+      // Skip remote/collab steps (orphan cleanup must run only on local edits).
+      if (
+        isRemoteTransaction &&
+        transactions.some((t) => isRemoteTransaction(t))
+      ) {
+        return null;
+      }
+
+      const { doc, schema } = newState;
+      const defType = schema.nodes[FOOTNOTE_DEFINITION_NAME];
+      const listType = schema.nodes[FOOTNOTES_LIST_NAME];
+      const paragraphType = schema.nodes.paragraph;
+      if (!defType || !listType || !paragraphType) return null;
+
+      const info = scan(doc);
+
+      // 1) Desired definitions: one per referenced id, in reference order,
+      //    reusing existing definition nodes (preserving their content) and
+      //    synthesizing empty ones for references that lack a definition.
+      const desiredDefs: ProseMirrorNode[] = info.referenceIds.map((id) => {
+        const existing = info.definitions.get(id);
+        if (existing) return existing;
+        return defType.create({ id }, paragraphType.create());
+      });
+
+      // 2) Determine whether the document already matches the desired end-state.
+      const hasRefs = desiredDefs.length > 0;
+
+      // Is the existing single list already exactly the desired list, placed
+      // after all meaningful content (nothing but empty paragraphs after it)?
+      const isEmptyParagraph = (node: ProseMirrorNode) =>
+        node.type === paragraphType && node.content.size === 0;
+
+      let alreadyCanonical = false;
+      if (!hasRefs) {
+        // Canonical when there is no footnotesList at all.
+        alreadyCanonical = info.lists.length === 0;
+      } else if (info.lists.length === 1) {
+        const { pos, node } = info.lists[0];
+        // Same definitions, same order, same identity (no rewrite needed)?
+        const sameDefs =
+          node.childCount === desiredDefs.length &&
+          desiredDefs.every((d, i) => node.child(i) === d);
+
+        // Placement: only empty paragraphs may follow the list.
+        const listEnd = pos + node.nodeSize;
+        let onlyEmptyParasAfter = true;
+        doc.nodesBetween(listEnd, doc.content.size, (child, childPos) => {
+          // Only inspect top-level children that start at/after the list end.
+          if (childPos >= listEnd && child !== node) {
+            if (!isEmptyParagraph(child)) onlyEmptyParasAfter = false;
+          }
+          return false; // do not descend
+        });
+
+        alreadyCanonical = sameDefs && onlyEmptyParasAfter;
+      }
+
+      if (alreadyCanonical) return null;
+
+      // 3) Rebuild: produce exactly ONE transaction that reaches the end-state.
+      const tr = newState.tr;
+
+      // Delete every existing footnotesList (from the end so earlier positions
+      // stay valid while we mutate).
+      [...info.lists]
+        .sort((a, b) => b.pos - a.pos)
+        .forEach(({ pos, node }) => {
+          tr.delete(pos, pos + node.nodeSize);
+        });
+
+      if (hasRefs) {
+        // Insert a single canonical list holding the desired definitions. Place
+        // it after the last meaningful (non-empty-paragraph) top-level block, so
+        // it lands before any trailing empty paragraph the trailing-node plugin
+        // maintains. This keeps both plugins idempotent.
+        const mappedDoc = tr.doc;
+        let insertPos = mappedDoc.content.size;
+        for (let i = mappedDoc.childCount - 1; i >= 0; i--) {
+          const child = mappedDoc.child(i);
+          if (isEmptyParagraph(child)) {
+            // skip trailing empty paragraphs; insert before them
+            insertPos -= child.nodeSize;
+          } else {
+            break;
+          }
+        }
+
+        const merged = listType.create(null, Fragment.fromArray(desiredDefs));
+        tr.insert(insertPos, merged);
+      }
+
+      if (!tr.docChanged) return null;
+
+      tr.setMeta(SYNC_META, true);
+      tr.setMeta("addToHistory", false);
+      return tr;
+    },
+  });
+}
diff --git a/packages/editor-ext/src/lib/footnote/footnote-util.ts b/packages/editor-ext/src/lib/footnote/footnote-util.ts
new file mode 100644
index 00000000..41698686
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote-util.ts
@@ -0,0 +1,77 @@
+import { Node as ProseMirrorNode } from "@tiptap/pm/model";
+
+/**
+ * Node type names for the footnote feature. Centralized so every part of the
+ * feature (nodes, plugins, commands) references the same string.
+ */
+export const FOOTNOTE_REFERENCE_NAME = "footnoteReference";
+export const FOOTNOTES_LIST_NAME = "footnotesList";
+export const FOOTNOTE_DEFINITION_NAME = "footnoteDefinition";
+
+/**
+ * Generate a uuidv7-style id (time-ordered). Implemented locally so editor-ext
+ * does not need a runtime dependency on the `uuid` package; matches the
+ * lexicographically-sortable layout uuidv7 produces.
+ */
+export function generateFootnoteId(): string {
+  const now = Date.now();
+  const timeHex = now.toString(16).padStart(12, "0");
+
+  const rand = (length: number) => {
+    let out = "";
+    for (let i = 0; i < length; i++) {
+      out += Math.floor(Math.random() * 16).toString(16);
+    }
+    return out;
+  };
+
+  // version 7 nibble, then variant (8..b) nibble.
+  const versioned = "7" + rand(3);
+  const variantNibble = (8 + Math.floor(Math.random() * 4)).toString(16);
+  const variant = variantNibble + rand(3);
+
+  return (
+    timeHex.slice(0, 8) +
+    "-" +
+    timeHex.slice(8, 12) +
+    "-" +
+    versioned +
+    "-" +
+    variant +
+    "-" +
+    rand(12)
+  );
+}
+
+/**
+ * Collect every `footnoteReference` id in document order. This is the single
+ * source of truth for numbering and ordering — a pure function of the document
+ * so every collaborating client computes the same result.
+ */
+export function collectReferenceIds(doc: ProseMirrorNode): string[] {
+  const ids: string[] = [];
+  doc.descendants((node) => {
+    if (node.type.name === FOOTNOTE_REFERENCE_NAME) {
+      const id = node.attrs.id;
+      if (id) ids.push(id);
+    }
+  });
+  return ids;
+}
+
+/**
+ * Build a map of `referenceId -> displayNumber` (1-based) from document order.
+ * Pure function — the basis for the numbering decorations and any test.
+ */
+export function computeFootnoteNumbers(
+  doc: ProseMirrorNode,
+): Map<string, number> {
+  const numbers = new Map<string, number>();
+  let n = 0;
+  for (const id of collectReferenceIds(doc)) {
+    if (!numbers.has(id)) {
+      numbers.set(id, ++n);
+    }
+  }
+  return numbers;
+}
diff --git a/packages/editor-ext/src/lib/footnote/footnote.test.ts b/packages/editor-ext/src/lib/footnote/footnote.test.ts
new file mode 100644
index 00000000..a68685a3
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnote.test.ts
@@ -0,0 +1,536 @@
+import { describe, it, expect } from "vitest";
+import { Editor, Extension, getSchema } from "@tiptap/core";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { Superscript } from "@tiptap/extension-superscript";
+import { Plugin, PluginKey } 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 { TrailingNode } from "../trailing-node";
+import {
+  computeFootnoteNumbers,
+  collectReferenceIds,
+  FOOTNOTE_REFERENCE_NAME,
+  FOOTNOTES_LIST_NAME,
+  FOOTNOTE_DEFINITION_NAME,
+} from "./footnote-util";
+
+const extensions = [
+  Document,
+  Paragraph,
+  Text,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+];
+
+function makeEditor(content?: any) {
+  return new Editor({
+    extensions,
+    content: content ?? { type: "doc", content: [{ type: "paragraph" }] },
+  });
+}
+
+function countType(doc: PMNode, name: string): number {
+  let n = 0;
+  doc.descendants((node) => {
+    if (node.type.name === name) n++;
+  });
+  return n;
+}
+
+describe("footnote numbering (pure function)", () => {
+  it("numbers references in document order", () => {
+    const schema = getSchema(extensions);
+    const doc = PMNode.fromJSON(schema, {
+      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" }],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(collectReferenceIds(doc)).toEqual(["x", "y"]);
+    const numbers = computeFootnoteNumbers(doc);
+    expect(numbers.get("x")).toBe(1);
+    expect(numbers.get("y")).toBe(2);
+  });
+});
+
+describe("setFootnote command", () => {
+  it("inserts a reference and a matching definition in the footnotes list", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "Hello" }] },
+      ],
+    });
+    // Cursor at end of the word.
+    editor.commands.setTextSelection(6);
+    const ok = editor.commands.setFootnote();
+    expect(ok).toBe(true);
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTE_REFERENCE_NAME)).toBe(1);
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(1);
+
+    // The reference id and the definition id match.
+    let refId: string | null = null;
+    let defId: string | null = null;
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_REFERENCE_NAME) refId = node.attrs.id;
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME) defId = node.attrs.id;
+    });
+    expect(refId).toBeTruthy();
+    expect(refId).toBe(defId);
+    editor.destroy();
+  });
+
+  it("inserts the definition at the correct position matching reference order", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "AAAA" }] },
+        { type: "paragraph", content: [{ type: "text", text: "BBBB" }] },
+      ],
+    });
+
+    // First footnote: place inside the SECOND paragraph (after "BBBB").
+    editor.commands.setTextSelection(11); // end of BBBB
+    editor.commands.setFootnote();
+
+    // Second footnote: place inside the FIRST paragraph (after "AAAA"),
+    // which is BEFORE the first reference in document order.
+    editor.commands.setTextSelection(5); // end of AAAA
+    editor.commands.setFootnote();
+
+    const doc = editor.state.doc;
+    // Reference order in document.
+    const refOrder = collectReferenceIds(doc);
+    // Definition order in the list.
+    const defOrder: string[] = [];
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
+        defOrder.push(node.attrs.id);
+      }
+    });
+
+    expect(defOrder).toEqual(refOrder);
+    expect(defOrder.length).toBe(2);
+    editor.destroy();
+  });
+});
+
+describe("removeFootnote command (cascade)", () => {
+  it("removes both the reference and its definition, and drops the empty list", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "Hello" }] },
+      ],
+    });
+    editor.commands.setTextSelection(6);
+    editor.commands.setFootnote();
+
+    let id: string | null = null;
+    editor.state.doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_REFERENCE_NAME) id = node.attrs.id;
+    });
+    expect(id).toBeTruthy();
+
+    editor.commands.removeFootnote(id!);
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTE_REFERENCE_NAME)).toBe(0);
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(0);
+    // empty list removed
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(0);
+    editor.destroy();
+  });
+});
+
+describe("footnote sync plugin (orphans)", () => {
+  it("creates an empty definition for a reference pasted without one", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "x" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "orphan-ref" } },
+          ],
+        },
+      ],
+    });
+    // Trigger a doc change so appendTransaction runs.
+    editor.commands.insertContentAt(1, " ");
+
+    const doc = editor.state.doc;
+    let defFound = false;
+    doc.descendants((node) => {
+      if (
+        node.type.name === FOOTNOTE_DEFINITION_NAME &&
+        node.attrs.id === "orphan-ref"
+      ) {
+        defFound = true;
+      }
+    });
+    expect(defFound).toBe(true);
+    editor.destroy();
+  });
+
+  it("merges multiple footnotesList nodes into one, preserving all definitions, as the last child", () => {
+    const editor = makeEditor({
+      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" } },
+          ],
+        },
+        // First (stray) footnotes list, e.g. from a paste/collab merge.
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "x" },
+              content: [{ type: "paragraph", content: [{ type: "text", text: "X note" }] }],
+            },
+          ],
+        },
+        { type: "paragraph", content: [{ type: "text", text: "tail" }] },
+        // Second footnotes list (the "real" trailing one).
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "y" },
+              content: [{ type: "paragraph", content: [{ type: "text", text: "Y note" }] }],
+            },
+          ],
+        },
+      ],
+    });
+    // Trigger a local doc change so appendTransaction runs.
+    editor.commands.insertContentAt(1, " ");
+
+    const doc = editor.state.doc;
+    // Converged to exactly ONE list.
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    // Both definitions preserved (no tracking lost).
+    const defIds: string[] = [];
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME) defIds.push(node.attrs.id);
+    });
+    expect(defIds.sort()).toEqual(["x", "y"]);
+    // The single list is the LAST child of the document.
+    const lastChild = doc.child(doc.childCount - 1);
+    expect(lastChild.type.name).toBe(FOOTNOTES_LIST_NAME);
+    editor.destroy();
+  });
+
+  it("leaves a correct doc (single trailing list) unchanged — no merge loop", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "a" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "x" } },
+          ],
+        },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "x" },
+              content: [{ type: "paragraph", content: [{ type: "text", text: "X note" }] }],
+            },
+          ],
+        },
+      ],
+    });
+    const before = editor.state.doc.toJSON();
+    // A change that doesn't touch footnote structure.
+    editor.commands.insertContentAt(1, "z");
+    const doc = editor.state.doc;
+    // Still exactly one list, still last, definition preserved.
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    const lastChild = doc.child(doc.childCount - 1);
+    expect(lastChild.type.name).toBe(FOOTNOTES_LIST_NAME);
+    // The footnotes list subtree is identical to before (no spurious rewrite).
+    const beforeList = before.content.find(
+      (n: any) => n.type === FOOTNOTES_LIST_NAME,
+    );
+    const afterList = doc
+      .toJSON()
+      .content.find((n: any) => n.type === FOOTNOTES_LIST_NAME);
+    expect(afterList).toEqual(beforeList);
+    editor.destroy();
+  });
+
+  it("removes an orphan definition with no matching reference", () => {
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        { type: "paragraph", content: [{ type: "text", text: "x" }] },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "orphan-def" },
+              content: [{ type: "paragraph" }],
+            },
+          ],
+        },
+      ],
+    });
+    editor.commands.insertContentAt(1, "y");
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(0);
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(0);
+    editor.destroy();
+  });
+});
+
+/**
+ * Live-editor regression tests for the sync-plugin infinite loop (the hard
+ * freeze when activating /footnote). These drive a REAL Tiptap editor through
+ * the same plugin pipeline the browser uses — including the TrailingNode plugin,
+ * which is what turned the "move list to the end" pass into an infinite
+ * ping-pong (list moved last -> trailing paragraph appended after it -> list no
+ * longer last -> moved again -> ...).
+ *
+ * If the loop regresses, ProseMirror's appendTransaction round loop never
+ * terminates and these tests HANG (the vitest timeout fails them). The
+ * transaction counter additionally fails fast with a bounded iteration cap, so
+ * a regression surfaces as an explicit error instead of only a slow timeout.
+ */
+describe("footnote sync plugin (no infinite loop — live editor)", () => {
+  // Hard cap on how many doc-changing appendTransaction rounds we tolerate for a
+  // single user action. Convergence takes a couple of rounds at most; anything
+  // approaching this means the plugins are oscillating.
+  const MAX_ROUNDS = 50;
+
+  // The production editor wires FootnoteReference alongside TrailingNode and
+  // Superscript; both participate in the loop the bug exhibited, so we mirror
+  // that here.
+  function makeLiveEditor(content?: any) {
+    let rounds = 0;
+    // A guard plugin that counts doc-changing appendTransaction rounds and
+    // throws if they exceed the cap, converting a would-be infinite loop into a
+    // deterministic failure instead of a wall-clock hang.
+    const LoopGuard = Extension.create({
+      name: "footnoteLoopGuard",
+      // Run last so it observes every other plugin's appended transaction.
+      priority: -1000,
+      addProseMirrorPlugins() {
+        return [
+          new Plugin({
+            key: new PluginKey("footnoteLoopGuard"),
+            appendTransaction(transactions) {
+              if (transactions.some((t) => t.docChanged)) {
+                rounds += 1;
+                if (rounds > MAX_ROUNDS) {
+                  throw new Error(
+                    `footnote sync did not converge: exceeded ${MAX_ROUNDS} appendTransaction rounds (infinite loop)`,
+                  );
+                }
+              }
+              return null;
+            },
+          }),
+        ];
+      },
+    });
+
+    const editor = new Editor({
+      extensions: [
+        Document,
+        Paragraph,
+        Text,
+        Superscript,
+        TrailingNode,
+        LoopGuard,
+        FootnoteReference,
+        FootnotesList,
+        FootnoteDefinition,
+      ],
+      content: content ?? { type: "doc", content: [{ type: "paragraph" }] },
+    });
+    return { editor, getRounds: () => rounds, resetRounds: () => (rounds = 0) };
+  }
+
+  function lastFootnotesListIsTrailing(doc: PMNode): boolean {
+    // Canonical placement: the list is the last meaningful block — only empty
+    // paragraphs (the trailing-node) may follow it.
+    let listIndex = -1;
+    for (let i = 0; i < doc.childCount; i++) {
+      if (doc.child(i).type.name === FOOTNOTES_LIST_NAME) listIndex = i;
+    }
+    if (listIndex === -1) return false;
+    for (let i = listIndex + 1; i < doc.childCount; i++) {
+      const child = doc.child(i);
+      if (!(child.type.name === "paragraph" && child.content.size === 0)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  it("setFootnote() RETURNS (no hang) and produces one ref + one def in a trailing list", () => {
+    const { editor } = makeLiveEditor({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text: "Hi" }] }],
+    });
+    editor.commands.setTextSelection(3);
+    const ok = editor.commands.setFootnote();
+    expect(ok).toBe(true);
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTE_REFERENCE_NAME)).toBe(1);
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(1);
+    expect(lastFootnotesListIsTrailing(doc)).toBe(true);
+    editor.destroy();
+  });
+
+  it("a second setFootnote() does not hang: two refs + two defs in one list", () => {
+    const { editor } = makeLiveEditor({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text: "Hi" }] }],
+    });
+    editor.commands.setTextSelection(3);
+    editor.commands.setFootnote();
+    editor.commands.setTextSelection(3);
+    editor.commands.setFootnote();
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTE_REFERENCE_NAME)).toBe(2);
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(2);
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    expect(lastFootnotesListIsTrailing(doc)).toBe(true);
+    editor.destroy();
+  });
+
+  it("converges and stabilizes: an unrelated edit does not keep producing transactions", () => {
+    const { editor, getRounds, resetRounds } = makeLiveEditor({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text: "Hi" }] }],
+    });
+    editor.commands.setTextSelection(3);
+    editor.commands.setFootnote();
+
+    // Now the doc is canonical. Dispatch an unrelated edit (insert text) and
+    // assert the sync plugin converges in a bounded number of rounds and the
+    // document is stable (one ref/def/list, list trailing).
+    resetRounds();
+    editor.commands.insertContentAt(1, "Z");
+    const afterFirst = editor.state.doc.toJSON();
+    const roundsAfterEdit = getRounds();
+    expect(roundsAfterEdit).toBeLessThan(MAX_ROUNDS);
+
+    // A follow-up no-op-ish edit must not re-trigger structural rewrites: the
+    // footnotes section is identical before and after a further unrelated edit.
+    editor.commands.insertContentAt(2, "Y");
+    const afterSecond = editor.state.doc.toJSON();
+
+    const listOf = (json: any) =>
+      json.content.find((n: any) => n.type === FOOTNOTES_LIST_NAME);
+    expect(listOf(afterSecond)).toEqual(listOf(afterFirst));
+    expect(countType(editor.state.doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    editor.destroy();
+  });
+
+  it("two footnotesList nodes converge to one (merge) without looping", () => {
+    const { editor } = makeLiveEditor({
+      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", content: [{ type: "text", text: "X" }] },
+              ],
+            },
+          ],
+        },
+        { type: "paragraph", content: [{ type: "text", text: "tail" }] },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "y" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "Y" }] },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    // Trigger a local doc change so appendTransaction runs (must not hang).
+    editor.commands.insertContentAt(1, " ");
+
+    const doc = editor.state.doc;
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    const defIds: string[] = [];
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME)
+        defIds.push(node.attrs.id);
+    });
+    expect(defIds.sort()).toEqual(["x", "y"]);
+    expect(lastFootnotesListIsTrailing(doc)).toBe(true);
+    editor.destroy();
+  });
+});
diff --git a/packages/editor-ext/src/lib/footnote/footnotes-list.ts b/packages/editor-ext/src/lib/footnote/footnotes-list.ts
new file mode 100644
index 00000000..516fcf45
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/footnotes-list.ts
@@ -0,0 +1,56 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { FOOTNOTES_LIST_NAME } from "./footnote-util";
+
+export interface FootnotesListOptions {
+  HTMLAttributes: Record<string, any>;
+  view: any;
+}
+
+/**
+ * Block container that holds all footnote definitions. There is a single
+ * instance per document and it is always the last child of the doc (enforced by
+ * the sync plugin). Modeled on the callout block node.
+ */
+export const FootnotesList = Node.create<FootnotesListOptions>({
+  name: FOOTNOTES_LIST_NAME,
+
+  group: "block",
+  content: "footnoteDefinition+",
+  isolating: true,
+  selectable: false,
+  defining: true,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      view: null,
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: "section[data-footnotes]",
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "section",
+      mergeAttributes(
+        { "data-footnotes": "", class: "footnotes" },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+      0,
+    ];
+  },
+
+  addNodeView() {
+    if (!this.options.view) return null;
+    this.editor.isInitialized = true;
+    return ReactNodeViewRenderer(this.options.view);
+  },
+});
diff --git a/packages/editor-ext/src/lib/footnote/index.ts b/packages/editor-ext/src/lib/footnote/index.ts
new file mode 100644
index 00000000..02defff1
--- /dev/null
+++ b/packages/editor-ext/src/lib/footnote/index.ts
@@ -0,0 +1,6 @@
+export * from "./footnote-util";
+export * from "./footnote-reference";
+export * from "./footnotes-list";
+export * from "./footnote-definition";
+export * from "./footnote-numbering";
+export * from "./footnote-sync";
diff --git a/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts b/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
new file mode 100644
index 00000000..ad47cc52
--- /dev/null
+++ b/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
@@ -0,0 +1,115 @@
+import { marked } from "marked";
+
+/**
+ * Pandoc/GFM footnote support for the marked (Markdown -> HTML) pipeline.
+ *
+ * Two pieces:
+ *  - an INLINE tokenizer for `[^id]` references -> <sup data-footnote-ref
+ *    data-id="id"> (matches the editor-ext FootnoteReference renderHTML);
+ *  - a document hook (`preprocess`/`walkTokens` is awkward for collecting +
+ *    removing definitions, so we use a regex preprocessing step instead) that
+ *    pulls every `[^id]: text` definition line out of the body and appends a
+ *    single <section data-footnotes> with one <div data-footnote-def> per
+ *    definition, so the round-trip rebuilds footnotesList + footnoteDefinition.
+ *
+ * Only definitions that have a matching reference are emitted (and vice-versa
+ * the sync plugin fills any gaps on the editor side), keeping the output valid.
+ */
+
+const DEFINITION_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+const REFERENCE_RE = /\[\^([^\]\s]+)\]/;
+
+interface FootnoteRefToken {
+  type: "footnoteRef";
+  raw: string;
+  id: string;
+}
+
+export const footnoteReferenceExtension = {
+  name: "footnoteRef",
+  level: "inline" as const,
+  start(src: string) {
+    return src.match(/\[\^/)?.index ?? -1;
+  },
+  tokenizer(src: string): FootnoteRefToken | undefined {
+    const match = REFERENCE_RE.exec(src);
+    // Only match at the very start of the remaining inline source.
+    if (match && match.index === 0) {
+      return {
+        type: "footnoteRef",
+        raw: match[0],
+        id: match[1],
+      };
+    }
+    return undefined;
+  },
+  renderer(token: FootnoteRefToken) {
+    return `<sup data-footnote-ref data-id="${escapeAttr(token.id)}"></sup>`;
+  },
+};
+
+function escapeAttr(value: string): string {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
+/**
+ * Extract `[^id]: text` definition lines from the markdown body, returning the
+ * cleaned body plus a rendered <section data-footnotes> (empty string when no
+ * definitions). Call this BEFORE marked.parse and append the section to the
+ * resulting HTML.
+ */
+export function extractFootnoteDefinitions(markdown: string): {
+  body: string;
+  section: string;
+} {
+  const lines = markdown.split("\n");
+  const bodyLines: string[] = [];
+  const definitions: Array<{ id: string; text: string }> = [];
+
+  // Track fenced-code state so a `[^id]: ...` line that merely SHOWS footnote
+  // syntax inside a ``` / ~~~ code block is left in the body verbatim and not
+  // mistaken for a real definition.
+  let fence: string | null = null;
+
+  for (const line of lines) {
+    const fenceMatch = /^(\s*)(`{3,}|~{3,})/.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[2][0];
+      if (fence === null) {
+        fence = marker; // opening fence
+      } else if (marker === fence) {
+        fence = null; // closing fence (matching delimiter type)
+      }
+      bodyLines.push(line);
+      continue;
+    }
+
+    const m = fence === null ? DEFINITION_RE.exec(line) : null;
+    if (m) {
+      definitions.push({ id: m[1], text: m[2] });
+    } else {
+      bodyLines.push(line);
+    }
+  }
+
+  if (definitions.length === 0) {
+    return { body: markdown, section: "" };
+  }
+
+  const defsHtml = definitions
+    .map((d) => {
+      // Render the definition text as inline markdown so emphasis/links inside
+      // a footnote survive the round-trip; wrap in a paragraph (the node's
+      // content is paragraph+).
+      const inner = marked.parseInline(d.text || "");
+      return `<div data-footnote-def data-id="${escapeAttr(
+        d.id,
+      )}"><p>${inner}</p></div>`;
+    })
+    .join("");
+
+  return {
+    body: bodyLines.join("\n"),
+    section: `<section data-footnotes>${defsHtml}</section>`,
+  };
+}
diff --git a/packages/editor-ext/src/lib/markdown/utils/marked.utils.ts b/packages/editor-ext/src/lib/markdown/utils/marked.utils.ts
index 7556aa4f..82de5761 100644
--- a/packages/editor-ext/src/lib/markdown/utils/marked.utils.ts
+++ b/packages/editor-ext/src/lib/markdown/utils/marked.utils.ts
@@ -2,6 +2,10 @@ import { marked } from "marked";
 import { calloutExtension } from "./callout.marked";
 import { mathBlockExtension } from "./math-block.marked";
 import { mathInlineExtension } from "./math-inline.marked";
+import {
+  footnoteReferenceExtension,
+  extractFootnoteDefinitions,
+} from "./footnote.marked";
 
 marked.use({
   renderer: {
@@ -34,7 +38,12 @@ marked.use({
 });
 
 marked.use({
-  extensions: [calloutExtension, mathBlockExtension, mathInlineExtension],
+  extensions: [
+    calloutExtension,
+    mathBlockExtension,
+    mathInlineExtension,
+    footnoteReferenceExtension,
+  ],
 });
 
 marked.setOptions({ breaks: true });
@@ -48,5 +57,16 @@ export function markdownToHtml(
     .replace(YAML_FONT_MATTER_REGEX, "")
     .trimStart();
 
-  return marked.parse(markdown).toString();
+  // Pull `[^id]: ...` definition lines out of the body, render the body, then
+  // append a single <section data-footnotes> so the round-trip rebuilds the
+  // footnotesList + footnoteDefinition nodes.
+  const { body, section } = extractFootnoteDefinitions(markdown);
+
+  const parsed = marked.parse(body);
+  if (!section) return parsed;
+
+  if (typeof parsed === "string") {
+    return parsed + section;
+  }
+  return parsed.then((html) => html + section);
 }
diff --git a/packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts b/packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts
index ebfc3423..75d923ba 100644
--- a/packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts
+++ b/packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts
@@ -12,12 +12,44 @@ function sanitizeMdLinkText(value: string): string {
     .replace(/[\r\n]+/g, ' ');
 }
 
+// Tags turndown treats as void (self-closing). Footnote references render as an
+// empty <sup data-footnote-ref> whose meaning lives entirely in its data-id;
+// without marking it void, turndown's blank-node removal drops it before our
+// rule runs, losing the `[^id]` marker. Mirrors turndown's built-in list.
+const TURNDOWN_VOID_ELEMENTS = [
+  'AREA', 'BASE', 'BR', 'COL', 'COMMAND', 'EMBED', 'HR', 'IMG', 'INPUT',
+  'KEYGEN', 'LINK', 'META', 'PARAM', 'SOURCE', 'TRACK', 'WBR',
+];
+
+function isVoidNode(node: any): boolean {
+  const name = node?.nodeName?.toUpperCase?.();
+  if (!name) return false;
+  if (name === 'SUP' && node.hasAttribute?.('data-footnote-ref')) {
+    return true;
+  }
+  return TURNDOWN_VOID_ELEMENTS.indexOf(name) !== -1;
+}
+
+/**
+ * An empty <sup data-footnote-ref> is "blank" to turndown, which removes blank
+ * inline nodes (RootNode/Node use a module-level isVoid the options cannot
+ * override). To survive, inject the id as text content so the node is non-blank;
+ * the footnoteReference rule then reads data-id and emits `[^id]`.
+ */
+function fillEmptyFootnoteRefs(html: string): string {
+  return html.replace(
+    /<sup\b([^>]*\bdata-footnote-ref\b[^>]*)>\s*<\/sup>/gi,
+    (_m, attrs) => `<sup${attrs}>​</sup>`,
+  );
+}
+
 export function htmlToMarkdown(html: string): string {
   const turndownService = new TurndownService({
     headingStyle: 'atx',
     codeBlockStyle: 'fenced',
     hr: '---',
     bulletListMarker: '-',
+    isVoid: isVoidNode,
   });
 
   turndownService.use([
@@ -34,8 +66,12 @@ export function htmlToMarkdown(html: string): string {
     iframeEmbed,
     image,
     video,
+    footnoteReference,
+    footnotesList,
   ]);
-  return turndownService.turndown(html).replaceAll('<br>', ' ');
+  return turndownService
+    .turndown(fillEmptyFootnoteRefs(html))
+    .replaceAll('<br>', ' ');
 }
 
 function listParagraph(turndownService: _TurndownService) {
@@ -203,6 +239,57 @@ function image(turndownService: _TurndownService) {
   });
 }
 
+/**
+ * Footnote reference (inline atom) -> pandoc/GFM marker `[^id]`.
+ * The visible number is derived (not stored), so the id is the stable anchor.
+ */
+function footnoteReference(turndownService: _TurndownService) {
+  turndownService.addRule('footnoteReference', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'SUP' && node.hasAttribute('data-footnote-ref')
+      );
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      const id = node.getAttribute('data-id') || '';
+      return id ? `[^${id}]` : '';
+    },
+  });
+}
+
+/**
+ * Footnotes container -> the list of `[^id]: text` definitions at the end of
+ * the document (one per line). Each footnoteDefinition inside emits its own
+ * `[^id]: ...` line; turndown joins them with the surrounding block spacing.
+ */
+function footnotesList(turndownService: _TurndownService) {
+  turndownService.addRule('footnoteDefinition', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'DIV' && node.hasAttribute('data-footnote-def')
+      );
+    },
+    replacement: function (content: string, node: HTMLInputElement) {
+      const id = node.getAttribute('data-id') || '';
+      // Collapse internal newlines so the definition stays a single MD line;
+      // continuation lines are a v2 refinement.
+      const text = content.replace(/\s*\n+\s*/g, ' ').trim();
+      return id ? `\n[^${id}]: ${text}\n` : '';
+    },
+  });
+
+  turndownService.addRule('footnotesList', {
+    filter: function (node: HTMLInputElement) {
+      return (
+        node.nodeName === 'SECTION' && node.hasAttribute('data-footnotes')
+      );
+    },
+    replacement: function (content: string) {
+      return `\n\n${content.trim()}\n`;
+    },
+  });
+}
+
 function video(turndownService: _TurndownService) {
   turndownService.addRule('video', {
     filter: function (node: HTMLInputElement) {
diff --git a/packages/editor-ext/tsconfig.json b/packages/editor-ext/tsconfig.json
index 974fea06..062c97f5 100644
--- a/packages/editor-ext/tsconfig.json
+++ b/packages/editor-ext/tsconfig.json
@@ -19,5 +19,6 @@
     "strictBindCallApply": false,
     "forceConsistentCasingInFileNames": false,
     "noFallthroughCasesInSwitch": false
-  }
+  },
+  "exclude": ["**/*.test.ts", "vitest.config.ts", "dist"]
 }
diff --git a/packages/editor-ext/vitest.config.ts b/packages/editor-ext/vitest.config.ts
new file mode 100644
index 00000000..c13f7bd6
--- /dev/null
+++ b/packages/editor-ext/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.ts"],
+  },
+});
diff --git a/packages/mcp/build/lib/collaboration.js b/packages/mcp/build/lib/collaboration.js
index 7b47b9e9..d5e68a21 100644
--- a/packages/mcp/build/lib/collaboration.js
+++ b/packages/mcp/build/lib/collaboration.js
@@ -263,10 +263,75 @@ function bridgeTaskLists(html) {
     }
     return document.body.innerHTML;
 }
+// Mirror of packages/editor-ext footnote markdown handling. A `[^id]` inline
+// marker becomes <sup data-footnote-ref data-id="id">, and `[^id]: text`
+// definition lines are collected into a single <section data-footnotes>.
+const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+const FOOTNOTE_REF_RE = /\[\^([^\]\s]+)\]/;
+function escapeFootnoteAttr(value) {
+    return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+const footnoteRefMarkedExtension = {
+    name: "footnoteRef",
+    level: "inline",
+    start(src) {
+        return src.match(/\[\^/)?.index ?? -1;
+    },
+    tokenizer(src) {
+        const match = FOOTNOTE_REF_RE.exec(src);
+        if (match && match.index === 0) {
+            return { type: "footnoteRef", raw: match[0], id: match[1] };
+        }
+        return undefined;
+    },
+    renderer(token) {
+        return `<sup data-footnote-ref data-id="${escapeFootnoteAttr(token.id)}"></sup>`;
+    },
+};
+marked.use({ extensions: [footnoteRefMarkedExtension] });
+/**
+ * Pull `[^id]: text` definition lines out of the body and render a single
+ * <section data-footnotes> for them (or "" when there are none).
+ */
+function extractFootnotes(markdown) {
+    const lines = markdown.split("\n");
+    const bodyLines = [];
+    const defs = [];
+    // Track fenced-code state so a `[^id]: ...` line shown inside a ``` / ~~~ code
+    // block is preserved verbatim and not treated as a footnote definition.
+    let fence = null;
+    for (const line of lines) {
+        const fenceMatch = /^(\s*)(`{3,}|~{3,})/.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[2][0];
+            if (fence === null)
+                fence = marker;
+            else if (marker === fence)
+                fence = null;
+            bodyLines.push(line);
+            continue;
+        }
+        const m = fence === null ? FOOTNOTE_DEF_RE.exec(line) : null;
+        if (m)
+            defs.push({ id: m[1], text: m[2] });
+        else
+            bodyLines.push(line);
+    }
+    if (defs.length === 0)
+        return { body: markdown, section: "" };
+    const inner = defs
+        .map((d) => `<div data-footnote-def data-id="${escapeFootnoteAttr(d.id)}"><p>${marked.parseInline(d.text || "")}</p></div>`)
+        .join("");
+    return {
+        body: bodyLines.join("\n"),
+        section: `<section data-footnotes>${inner}</section>`,
+    };
+}
 /** Convert markdown to a ProseMirror doc using the full Docmost schema. */
 export async function markdownToProseMirror(markdownContent) {
     const withCallouts = await preprocessCallouts(markdownContent);
-    const html = await marked.parse(withCallouts);
+    const { body, section } = extractFootnotes(withCallouts);
+    const html = (await marked.parse(body)) + section;
     const bridged = bridgeTaskLists(html);
     return generateJSON(bridged, docmostExtensions);
 }
diff --git a/packages/mcp/build/lib/diff.js b/packages/mcp/build/lib/diff.js
index f5e7ab44..516a3c81 100644
--- a/packages/mcp/build/lib/diff.js
+++ b/packages/mcp/build/lib/diff.js
@@ -79,10 +79,26 @@ function countUniqueLinks(doc) {
     visit(doc);
     return hrefs.size;
 }
+/** Count footnoteReference nodes anywhere under a node (reading order). */
+function countFootnoteRefs(node) {
+    if (!node || typeof node !== "object")
+        return 0;
+    let n = node.type === "footnoteReference" ? 1 : 0;
+    if (Array.isArray(node.content)) {
+        for (const child of node.content)
+            n += countFootnoteRefs(child);
+    }
+    return n;
+}
 /**
- * Parse the ordered list of integers from `[N]` footnote markers found in the
- * BODY only (every top-level block before the first "Примечания..." notes
- * heading; if no such heading, the whole doc). Returned in reading order.
+ * Ordered list of footnote marker numbers found in the BODY only (every
+ * top-level block before the first "Примечания..." notes heading; if no such
+ * heading, the whole doc), in reading order.
+ *
+ * Supports BOTH representations:
+ *  - real `footnoteReference` nodes (the current footnote feature) — numbered
+ *    1..n by reading position, since their visible number is derived;
+ *  - legacy `[N]` text markers (older translated docs) — the literal N.
  */
 function footnoteMarkers(doc, notesHeading) {
     const top = Array.isArray(doc?.content) ? doc.content : [];
@@ -90,6 +106,15 @@ function footnoteMarkers(doc, notesHeading) {
         n.type === "heading" &&
         plainText(n).trim() === notesHeading);
     const bodyBlocks = notesIdx >= 0 ? top.slice(0, notesIdx) : top;
+    // Real footnoteReference nodes take precedence: when present, number them by
+    // reading position (their displayed number is not stored).
+    let refCount = 0;
+    for (const block of bodyBlocks)
+        refCount += countFootnoteRefs(block);
+    if (refCount > 0) {
+        return Array.from({ length: refCount }, (_, i) => i + 1);
+    }
+    // Fallback: legacy `[N]` text markers.
     const markers = [];
     const re = /\[(\d+)\]/g;
     for (const block of bodyBlocks) {
diff --git a/packages/mcp/build/lib/docmost-schema.js b/packages/mcp/build/lib/docmost-schema.js
index 97cdcafd..e89ed5a0 100644
--- a/packages/mcp/build/lib/docmost-schema.js
+++ b/packages/mcp/build/lib/docmost-schema.js
@@ -342,6 +342,78 @@ const Mention = Node.create({
         return ["span", { "data-type": "mention", ...HTMLAttributes }, 0];
     },
 });
+/**
+ * Footnote feature (mirror of packages/editor-ext/src/lib/footnote). Three
+ * nodes connected by `id`:
+ *  - FootnoteReference: inline atom marker in the body (<sup data-footnote-ref>);
+ *  - FootnotesList:     a single bottom container (<section data-footnotes>);
+ *  - FootnoteDefinition: one editable note keyed by id (<div data-footnote-def>).
+ * The visible number is not stored; it is derived from reference order.
+ *
+ * priority 101 so this node's <sup> parse rule beats the Superscript mark's
+ * <sup> rule (otherwise an empty reference is parsed as an empty superscript
+ * mark and dropped). Keep in sync with editor-ext.
+ */
+const FootnoteReference = Node.create({
+    name: "footnoteReference",
+    priority: 101,
+    group: "inline",
+    inline: true,
+    atom: true,
+    selectable: true,
+    draggable: false,
+    addAttributes() {
+        return {
+            id: {
+                default: null,
+                parseHTML: (el) => el.getAttribute("data-id"),
+                renderHTML: (attrs) => attrs.id ? { "data-id": attrs.id } : {},
+            },
+        };
+    },
+    parseHTML() {
+        return [{ tag: "sup[data-footnote-ref]", priority: 100 }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ["sup", { "data-footnote-ref": "", ...HTMLAttributes }];
+    },
+});
+const FootnotesList = Node.create({
+    name: "footnotesList",
+    group: "block",
+    content: "footnoteDefinition+",
+    isolating: true,
+    selectable: false,
+    defining: true,
+    parseHTML() {
+        return [{ tag: "section[data-footnotes]" }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ["section", { "data-footnotes": "", ...HTMLAttributes }, 0];
+    },
+});
+const FootnoteDefinition = Node.create({
+    name: "footnoteDefinition",
+    content: "paragraph+",
+    defining: true,
+    isolating: true,
+    selectable: false,
+    addAttributes() {
+        return {
+            id: {
+                default: null,
+                parseHTML: (el) => el.getAttribute("data-id"),
+                renderHTML: (attrs) => attrs.id ? { "data-id": attrs.id } : {},
+            },
+        };
+    },
+    parseHTML() {
+        return [{ tag: "div[data-footnote-def]" }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ["div", { "data-footnote-def": "", ...HTMLAttributes }, 0];
+    },
+});
 /** Inline KaTeX expression. Carries the LaTeX source in `text`. */
 const MathInline = Node.create({
     name: "mathInline",
@@ -978,6 +1050,9 @@ export const docmostExtensions = [
     TableCell,
     TableHeader,
     Mention,
+    FootnoteReference,
+    FootnotesList,
+    FootnoteDefinition,
     MathInline,
     MathBlock,
     Details,
diff --git a/packages/mcp/build/lib/markdown-converter.js b/packages/mcp/build/lib/markdown-converter.js
index 477dee5d..d5d47400 100644
--- a/packages/mcp/build/lib/markdown-converter.js
+++ b/packages/mcp/build/lib/markdown-converter.js
@@ -388,6 +388,27 @@ export function convertProseMirrorToMarkdown(content) {
                 // carry the real values), so escape it for the text context, not attrs.
                 return `<span ${parts.join(" ")}>@${escapeHtmlText(mentionLabel)}</span>`;
             }
+            case "footnoteReference": {
+                // Pandoc/GFM inline marker. The number is derived (not stored), so the
+                // id is the stable anchor.
+                const fnId = node.attrs?.id || "";
+                return fnId ? `[^${fnId}]` : "";
+            }
+            case "footnotesList":
+                // The container renders its definitions, each on its own `[^id]: ...`
+                // line. A blank line separates the body from the notes block.
+                return nodeContent.map(processNode).join("\n");
+            case "footnoteDefinition": {
+                const defId = node.attrs?.id || "";
+                // Collapse the definition's paragraphs into a single line; multi-line
+                // footnotes are a v2 refinement.
+                const defText = nodeContent
+                    .map(processNode)
+                    .join(" ")
+                    .replace(/\s*\n+\s*/g, " ")
+                    .trim();
+                return defId ? `[^${defId}]: ${defText}` : "";
+            }
             case "attachment": {
                 // BUG FIX: the old code read node.attrs.fileName / node.attrs.src, but
                 // the schema stores name/url (plus mime/size/attachmentId). Emit the
diff --git a/packages/mcp/build/lib/transforms.js b/packages/mcp/build/lib/transforms.js
index 98079f72..2fc5d37b 100644
--- a/packages/mcp/build/lib/transforms.js
+++ b/packages/mcp/build/lib/transforms.js
@@ -223,6 +223,59 @@ export function noteItem(inlineNodes) {
         ],
     };
 }
+/**
+ * Wrap inline ProseMirror nodes in a real footnoteDefinition node keyed by id:
+ *   { type:"footnoteDefinition", attrs:{id}, content:[{ type:"paragraph", content }] }
+ * (mirrors the editor-ext / docmost-schema FootnoteDefinition node).
+ */
+export function footnoteDefinition(id, inlineNodes) {
+    const content = Array.isArray(inlineNodes) ? clone(inlineNodes) : [];
+    return {
+        type: "footnoteDefinition",
+        attrs: { id },
+        content: [{ type: "paragraph", attrs: { id: freshId() }, content }],
+    };
+}
+/**
+ * Replace every `[N]` body marker and `\u0000FN<i>\u0000` comment placeholder in
+ * an inline content array with a real `footnoteReference` node, in reading
+ * order. `onMarker` is called for each replaced marker (with the original `[N]`
+ * number or the placeholder index) and returns the fresh footnote id to attach
+ * to the inserted node. Mutates `inline` in place.
+ */
+function replaceMarkersWithReferences(inline, onMarker) {
+    const re = /\[(\d+)\]|\u0000FN(\d+)\u0000/g;
+    for (let i = 0; i < inline.length; i++) {
+        const n = inline[i];
+        if (!isObject(n) || n.type !== "text" || typeof n.text !== "string") {
+            continue;
+        }
+        if (!re.test(n.text))
+            continue;
+        re.lastIndex = 0;
+        const marks = Array.isArray(n.marks) ? n.marks : [];
+        const parts = [];
+        let last = 0;
+        let m;
+        while ((m = re.exec(n.text)) !== null) {
+            if (m.index > last) {
+                parts.push({ ...n, text: n.text.slice(last, m.index), marks: [...marks] });
+            }
+            const oldNum = m[1] != null ? Number(m[1]) : undefined;
+            const phIdx = m[2] != null ? Number(m[2]) : undefined;
+            const fnId = onMarker({ oldNum, phIdx });
+            parts.push({ type: "footnoteReference", attrs: { id: fnId } });
+            last = m.index + m[0].length;
+        }
+        if (last < n.text.length) {
+            parts.push({ ...n, text: n.text.slice(last), marks: [...marks] });
+        }
+        // Drop any zero-length text runs the slicing may have produced.
+        const cleaned = parts.filter((p) => p.type !== "text" || (typeof p.text === "string" && p.text.length > 0));
+        inline.splice(i, 1, ...cleaned);
+        i += cleaned.length - 1;
+    }
+}
 /**
  * Convert a comment's markdown (e.g. `**Lead.** body...`) into inline
  * ProseMirror nodes.
@@ -321,85 +374,100 @@ export function commentsToFootnotes(doc, comments, opts = {}) {
         throw new Error("notes orderedList not found");
     }
     const consumed = [];
-    const noteByPh = new Map();
+    const noteInlineByPh = new Map();
     (Array.isArray(comments) ? comments : []).forEach((c, i) => {
         if (!c || !c.selection)
             return;
         // Collision-proof sentinel delimited by NUL control chars, which never occur
-        // in real Docmost prose — so the renumber regex below cannot mistake any body
-        // text (e.g. "Press F1 for help", model "FN2") for a placeholder. The NUL is
-        // transient: the placeholder round-trips within this function (insertMarkerAfter
-        // inserts it, the renumber pass replaces it with "[N]"), so it never persists
-        // in a returned/pushed document.
+        // in real Docmost prose - so the marker regex cannot mistake any body text
+        // (e.g. "Press F1 for help", model "FN2") for a placeholder. The NUL is
+        // transient: the placeholder is inserted here and replaced by a
+        // footnoteReference node below; it never persists in a returned document.
         const ph = `\u0000FN${i}\u0000`;
-        // insertMarkerAfter returns a NEW cloned doc; reassign `working` and refresh
-        // the `top` / `notesList` references that point into it.
+        // insertMarkerAfter returns a NEW cloned doc; reassign `working`.
         const r = insertMarkerAfter(working, c.selection.trimEnd(), ph, {
             beforeBlock: notesIdx,
         });
         if (!r.inserted)
             return;
         working = r.doc;
-        noteByPh.set(ph, noteItem(mdToInlineNodes(c.content)));
+        noteInlineByPh.set(ph, mdToInlineNodes(c.content));
         consumed.push(c.id);
     });
     // Re-resolve references into the (possibly re-cloned) working doc.
     const top2 = Array.isArray(working.content) ? working.content : [];
-    const notesList2 = top2
-        .slice(notesIdx)
-        .find((n) => isObject(n) && n.type === "orderedList");
+    const notesIdx2 = top2.findIndex((n) => isObject(n) && n.type === "heading" && blockText(n).trim() === notesHeading);
+    const oldListIndex = top2.findIndex((n) => isObject(n) && n.type === "orderedList");
+    const notesList2 = oldListIndex >= 0 ? top2[oldListIndex] : null;
     if (!notesList2) {
         throw new Error("notes orderedList not found");
     }
-    const oldNotes = Array.isArray(notesList2.content)
+    // Inline content of each existing note (listItem -> paragraph -> inline).
+    const oldNoteInline = (Array.isArray(notesList2.content)
         ? notesList2.content
-        : [];
-    const newNotes = [];
-    let seq = 0;
-    // Match either an existing "[N]" marker or a NUL-delimited "\u0000FN<i>\u0000"
-    // placeholder, in reading order across the body (blocks before the notes heading).
-    const re = /\[(\d+)\]|\u0000FN(\d+)\u0000/g;
-    // Same range regex setCalloutRange uses to detect the disclaimer callout's
-    // "[1]…[K]" range; used here to decide whether a top-level callout is the
-    // disclaimer (skip) or an ordinary callout (renumber normally).
+        : []).map((item) => {
+        const para = isObject(item) && Array.isArray(item.content)
+            ? item.content.find((c) => isObject(c) && c.type === "paragraph")
+            : null;
+        return para && Array.isArray(para.content) ? para.content : [];
+    });
+    // Walk the body in reading order, turning each "[N]" / placeholder marker into
+    // a real footnoteReference node and collecting its definition inline content.
+    const definitions = [];
     const disclaimerRangeRe = /(\[1\]\s*(?:…|\.\.\.)\s*\[)\d+(\])/;
-    for (let i = 0; i < notesIdx; i++) {
-        // Skip ONLY the disclaimer callout: its "[1]…[K]" range is NOT a footnote
-        // marker and is synced separately by setCalloutRange. Renumbering it here
-        // would consume note slots and corrupt the sequence. Other top-level
-        // callouts may carry legitimate "[N]" body markers and are renumbered.
+    // Recursively visit inline arrays inside a block (paragraph, heading, callout
+    // child paragraphs, table cells, ...), preserving document reading order.
+    const visitInlineArrays = (container) => {
+        if (!isObject(container) || !Array.isArray(container.content))
+            return;
+        const hasText = container.content.some((n) => isObject(n) && n.type === "text");
+        if (hasText) {
+            replaceMarkersWithReferences(container.content, ({ oldNum, phIdx }) => {
+                const fnId = freshId();
+                if (oldNum != null) {
+                    const inline = oldNoteInline[oldNum - 1];
+                    // Every existing body marker MUST map to a real note. An out-of-range
+                    // marker means the document is internally inconsistent; fail loudly.
+                    if (inline === undefined) {
+                        throw new Error(`footnote [${oldNum}] has no matching note (notes list has ${oldNoteInline.length} items); document is inconsistent`);
+                    }
+                    definitions.push(footnoteDefinition(fnId, inline));
+                }
+                else {
+                    const inline = noteInlineByPh.get(`\u0000FN${phIdx}\u0000`) || [];
+                    definitions.push(footnoteDefinition(fnId, inline));
+                }
+                return fnId;
+            });
+        }
+        else {
+            for (const child of container.content)
+                visitInlineArrays(child);
+        }
+    };
+    const notesBoundary = notesIdx2 >= 0 ? notesIdx2 : oldListIndex;
+    for (let i = 0; i < notesBoundary; i++) {
+        // Skip ONLY the disclaimer callout: its "[1]...[K]" range is NOT a footnote
+        // marker and is synced separately by setCalloutRange.
         if (isObject(top2[i]) &&
             top2[i].type === "callout" &&
             disclaimerRangeRe.test(blockText(top2[i]))) {
             continue;
         }
-        walk(top2[i], (node) => {
-            if (node.type !== "text" || typeof node.text !== "string")
-                return;
-            node.text = node.text.replace(re, (_m, oldNum, phIdx) => {
-                if (oldNum != null) {
-                    const note = oldNotes[Number(oldNum) - 1];
-                    // Every existing body marker MUST map to a real note. An out-of-range
-                    // marker means the document is internally inconsistent; fail loudly
-                    // rather than silently dropping the note and desyncing the callout.
-                    if (note === undefined) {
-                        throw new Error(`footnote [${oldNum}] has no matching note (notes list has ${oldNotes.length} items); document is inconsistent`);
-                    }
-                    newNotes.push(note);
-                }
-                else {
-                    newNotes.push(noteByPh.get(`\u0000FN${phIdx}\u0000`));
-                }
-                return `[${++seq}]`;
-            });
-        });
+        visitInlineArrays(top2[i]);
     }
-    // Reorder the notes list IN PLACE on `working` first, THEN sync the callout
-    // range. setCalloutRange clones `working`, so the reordered notes (mutated
-    // before the clone) are carried into its result automatically. No null-filter
-    // here: marker count and note count must stay exactly equal (the out-of-range
-    // guard above guarantees no undefined entry is ever pushed).
-    notesList2.content = newNotes;
-    const synced = setCalloutRange(working, notesList2.content.length);
+    // Replace the old orderedList with a real footnotesList of the collected
+    // definitions (reading order). If there are no definitions, drop the list.
+    if (definitions.length > 0) {
+        top2[oldListIndex] = {
+            type: "footnotesList",
+            content: definitions,
+        };
+    }
+    else {
+        top2.splice(oldListIndex, 1);
+    }
+    // Sync the disclaimer callout range to the new note count.
+    const synced = setCalloutRange(working, definitions.length);
     return { doc: synced.doc, consumed };
 }
diff --git a/packages/mcp/src/lib/collaboration.ts b/packages/mcp/src/lib/collaboration.ts
index ca2114d9..0e6e80a3 100644
--- a/packages/mcp/src/lib/collaboration.ts
+++ b/packages/mcp/src/lib/collaboration.ts
@@ -296,12 +296,87 @@ function bridgeTaskLists(html: string): string {
   return document.body.innerHTML;
 }
 
+// Mirror of packages/editor-ext footnote markdown handling. A `[^id]` inline
+// marker becomes <sup data-footnote-ref data-id="id">, and `[^id]: text`
+// definition lines are collected into a single <section data-footnotes>.
+const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
+const FOOTNOTE_REF_RE = /\[\^([^\]\s]+)\]/;
+
+function escapeFootnoteAttr(value: string): string {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
+const footnoteRefMarkedExtension = {
+  name: "footnoteRef",
+  level: "inline" as const,
+  start(src: string) {
+    return src.match(/\[\^/)?.index ?? -1;
+  },
+  tokenizer(src: string) {
+    const match = FOOTNOTE_REF_RE.exec(src);
+    if (match && match.index === 0) {
+      return { type: "footnoteRef", raw: match[0], id: match[1] };
+    }
+    return undefined;
+  },
+  renderer(token: any) {
+    return `<sup data-footnote-ref data-id="${escapeFootnoteAttr(
+      token.id,
+    )}"></sup>`;
+  },
+};
+
+marked.use({ extensions: [footnoteRefMarkedExtension] });
+
+/**
+ * Pull `[^id]: text` definition lines out of the body and render a single
+ * <section data-footnotes> for them (or "" when there are none).
+ */
+function extractFootnotes(markdown: string): {
+  body: string;
+  section: string;
+} {
+  const lines = markdown.split("\n");
+  const bodyLines: string[] = [];
+  const defs: Array<{ id: string; text: string }> = [];
+  // Track fenced-code state so a `[^id]: ...` line shown inside a ``` / ~~~ code
+  // block is preserved verbatim and not treated as a footnote definition.
+  let fence: string | null = null;
+  for (const line of lines) {
+    const fenceMatch = /^(\s*)(`{3,}|~{3,})/.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[2][0];
+      if (fence === null) fence = marker;
+      else if (marker === fence) fence = null;
+      bodyLines.push(line);
+      continue;
+    }
+    const m = fence === null ? FOOTNOTE_DEF_RE.exec(line) : null;
+    if (m) defs.push({ id: m[1], text: m[2] });
+    else bodyLines.push(line);
+  }
+  if (defs.length === 0) return { body: markdown, section: "" };
+  const inner = defs
+    .map(
+      (d) =>
+        `<div data-footnote-def data-id="${escapeFootnoteAttr(
+          d.id,
+        )}"><p>${marked.parseInline(d.text || "")}</p></div>`,
+    )
+    .join("");
+  return {
+    body: bodyLines.join("\n"),
+    section: `<section data-footnotes>${inner}</section>`,
+  };
+}
+
 /** Convert markdown to a ProseMirror doc using the full Docmost schema. */
 export async function markdownToProseMirror(
   markdownContent: string,
 ): Promise<any> {
   const withCallouts = await preprocessCallouts(markdownContent);
-  const html = await marked.parse(withCallouts);
+  const { body, section } = extractFootnotes(withCallouts);
+  const html = (await marked.parse(body)) + section;
   const bridged = bridgeTaskLists(html);
   return generateJSON(bridged, docmostExtensions);
 }
diff --git a/packages/mcp/src/lib/diff.ts b/packages/mcp/src/lib/diff.ts
index befe047c..d0848997 100644
--- a/packages/mcp/src/lib/diff.ts
+++ b/packages/mcp/src/lib/diff.ts
@@ -101,10 +101,25 @@ function countUniqueLinks(doc: any): number {
   return hrefs.size;
 }
 
+/** Count footnoteReference nodes anywhere under a node (reading order). */
+function countFootnoteRefs(node: any): number {
+  if (!node || typeof node !== "object") return 0;
+  let n = node.type === "footnoteReference" ? 1 : 0;
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) n += countFootnoteRefs(child);
+  }
+  return n;
+}
+
 /**
- * Parse the ordered list of integers from `[N]` footnote markers found in the
- * BODY only (every top-level block before the first "Примечания..." notes
- * heading; if no such heading, the whole doc). Returned in reading order.
+ * Ordered list of footnote marker numbers found in the BODY only (every
+ * top-level block before the first "Примечания..." notes heading; if no such
+ * heading, the whole doc), in reading order.
+ *
+ * Supports BOTH representations:
+ *  - real `footnoteReference` nodes (the current footnote feature) — numbered
+ *    1..n by reading position, since their visible number is derived;
+ *  - legacy `[N]` text markers (older translated docs) — the literal N.
  */
 function footnoteMarkers(doc: any, notesHeading: string): number[] {
   const top: any[] = Array.isArray(doc?.content) ? doc.content : [];
@@ -115,6 +130,16 @@ function footnoteMarkers(doc: any, notesHeading: string): number[] {
       plainText(n).trim() === notesHeading,
   );
   const bodyBlocks = notesIdx >= 0 ? top.slice(0, notesIdx) : top;
+
+  // Real footnoteReference nodes take precedence: when present, number them by
+  // reading position (their displayed number is not stored).
+  let refCount = 0;
+  for (const block of bodyBlocks) refCount += countFootnoteRefs(block);
+  if (refCount > 0) {
+    return Array.from({ length: refCount }, (_, i) => i + 1);
+  }
+
+  // Fallback: legacy `[N]` text markers.
   const markers: number[] = [];
   const re = /\[(\d+)\]/g;
   for (const block of bodyBlocks) {
diff --git a/packages/mcp/src/lib/docmost-schema.ts b/packages/mcp/src/lib/docmost-schema.ts
index c45c275a..3d8d25d7 100644
--- a/packages/mcp/src/lib/docmost-schema.ts
+++ b/packages/mcp/src/lib/docmost-schema.ts
@@ -378,6 +378,83 @@ const Mention = Node.create({
   },
 });
 
+/**
+ * Footnote feature (mirror of packages/editor-ext/src/lib/footnote). Three
+ * nodes connected by `id`:
+ *  - FootnoteReference: inline atom marker in the body (<sup data-footnote-ref>);
+ *  - FootnotesList:     a single bottom container (<section data-footnotes>);
+ *  - FootnoteDefinition: one editable note keyed by id (<div data-footnote-def>).
+ * The visible number is not stored; it is derived from reference order.
+ *
+ * priority 101 so this node's <sup> parse rule beats the Superscript mark's
+ * <sup> rule (otherwise an empty reference is parsed as an empty superscript
+ * mark and dropped). Keep in sync with editor-ext.
+ */
+const FootnoteReference = Node.create({
+  name: "footnoteReference",
+  priority: 101,
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.id ? { "data-id": attrs.id } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "sup[data-footnote-ref]", priority: 100 }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["sup", { "data-footnote-ref": "", ...HTMLAttributes }];
+  },
+});
+
+const FootnotesList = Node.create({
+  name: "footnotesList",
+  group: "block",
+  content: "footnoteDefinition+",
+  isolating: true,
+  selectable: false,
+  defining: true,
+  parseHTML() {
+    return [{ tag: "section[data-footnotes]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["section", { "data-footnotes": "", ...HTMLAttributes }, 0];
+  },
+});
+
+const FootnoteDefinition = Node.create({
+  name: "footnoteDefinition",
+  content: "paragraph+",
+  defining: true,
+  isolating: true,
+  selectable: false,
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.id ? { "data-id": attrs.id } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "div[data-footnote-def]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-footnote-def": "", ...HTMLAttributes }, 0];
+  },
+});
+
 /** Inline KaTeX expression. Carries the LaTeX source in `text`. */
 const MathInline = Node.create({
   name: "mathInline",
@@ -1069,6 +1146,9 @@ export const docmostExtensions = [
   TableCell,
   TableHeader,
   Mention,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
   MathInline,
   MathBlock,
   Details,
diff --git a/packages/mcp/src/lib/markdown-converter.ts b/packages/mcp/src/lib/markdown-converter.ts
index cbaa7042..4e35c995 100644
--- a/packages/mcp/src/lib/markdown-converter.ts
+++ b/packages/mcp/src/lib/markdown-converter.ts
@@ -430,6 +430,30 @@ export function convertProseMirrorToMarkdown(content: any): string {
         return `<span ${parts.join(" ")}>@${escapeHtmlText(mentionLabel)}</span>`;
       }
 
+      case "footnoteReference": {
+        // Pandoc/GFM inline marker. The number is derived (not stored), so the
+        // id is the stable anchor.
+        const fnId = node.attrs?.id || "";
+        return fnId ? `[^${fnId}]` : "";
+      }
+
+      case "footnotesList":
+        // The container renders its definitions, each on its own `[^id]: ...`
+        // line. A blank line separates the body from the notes block.
+        return nodeContent.map(processNode).join("\n");
+
+      case "footnoteDefinition": {
+        const defId = node.attrs?.id || "";
+        // Collapse the definition's paragraphs into a single line; multi-line
+        // footnotes are a v2 refinement.
+        const defText = nodeContent
+          .map(processNode)
+          .join(" ")
+          .replace(/\s*\n+\s*/g, " ")
+          .trim();
+        return defId ? `[^${defId}]: ${defText}` : "";
+      }
+
       case "attachment": {
         // BUG FIX: the old code read node.attrs.fileName / node.attrs.src, but
         // the schema stores name/url (plus mime/size/attachmentId). Emit the
diff --git a/packages/mcp/src/lib/transforms.ts b/packages/mcp/src/lib/transforms.ts
index d8fba091..98269aff 100644
--- a/packages/mcp/src/lib/transforms.ts
+++ b/packages/mcp/src/lib/transforms.ts
@@ -264,6 +264,66 @@ export function noteItem(inlineNodes: any[]): any {
   };
 }
 
+/**
+ * Wrap inline ProseMirror nodes in a real footnoteDefinition node keyed by id:
+ *   { type:"footnoteDefinition", attrs:{id}, content:[{ type:"paragraph", content }] }
+ * (mirrors the editor-ext / docmost-schema FootnoteDefinition node).
+ */
+export function footnoteDefinition(id: string, inlineNodes: any[]): any {
+  const content = Array.isArray(inlineNodes) ? clone(inlineNodes) : [];
+  return {
+    type: "footnoteDefinition",
+    attrs: { id },
+    content: [{ type: "paragraph", attrs: { id: freshId() }, content }],
+  };
+}
+
+/**
+ * Replace every `[N]` body marker and `\u0000FN<i>\u0000` comment placeholder in
+ * an inline content array with a real `footnoteReference` node, in reading
+ * order. `onMarker` is called for each replaced marker (with the original `[N]`
+ * number or the placeholder index) and returns the fresh footnote id to attach
+ * to the inserted node. Mutates `inline` in place.
+ */
+function replaceMarkersWithReferences(
+  inline: any[],
+  onMarker: (info: { oldNum?: number; phIdx?: number }) => string,
+): void {
+  const re = /\[(\d+)\]|\u0000FN(\d+)\u0000/g;
+  for (let i = 0; i < inline.length; i++) {
+    const n = inline[i];
+    if (!isObject(n) || n.type !== "text" || typeof n.text !== "string") {
+      continue;
+    }
+    if (!re.test(n.text)) continue;
+    re.lastIndex = 0;
+
+    const marks = Array.isArray(n.marks) ? n.marks : [];
+    const parts: any[] = [];
+    let last = 0;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(n.text)) !== null) {
+      if (m.index > last) {
+        parts.push({ ...n, text: n.text.slice(last, m.index), marks: [...marks] });
+      }
+      const oldNum = m[1] != null ? Number(m[1]) : undefined;
+      const phIdx = m[2] != null ? Number(m[2]) : undefined;
+      const fnId = onMarker({ oldNum, phIdx });
+      parts.push({ type: "footnoteReference", attrs: { id: fnId } });
+      last = m.index + m[0].length;
+    }
+    if (last < n.text.length) {
+      parts.push({ ...n, text: n.text.slice(last), marks: [...marks] });
+    }
+    // Drop any zero-length text runs the slicing may have produced.
+    const cleaned = parts.filter(
+      (p) => p.type !== "text" || (typeof p.text === "string" && p.text.length > 0),
+    );
+    inline.splice(i, 1, ...cleaned);
+    i += cleaned.length - 1;
+  }
+}
+
 /**
  * Convert a comment's markdown (e.g. `**Lead.** body...`) into inline
  * ProseMirror nodes.
@@ -388,54 +448,91 @@ export function commentsToFootnotes(
   }
 
   const consumed: string[] = [];
-  const noteByPh = new Map<string, any>();
+  const noteInlineByPh = new Map<string, any[]>();
 
   (Array.isArray(comments) ? comments : []).forEach((c, i) => {
     if (!c || !c.selection) return;
     // Collision-proof sentinel delimited by NUL control chars, which never occur
-    // in real Docmost prose — so the renumber regex below cannot mistake any body
-    // text (e.g. "Press F1 for help", model "FN2") for a placeholder. The NUL is
-    // transient: the placeholder round-trips within this function (insertMarkerAfter
-    // inserts it, the renumber pass replaces it with "[N]"), so it never persists
-    // in a returned/pushed document.
+    // in real Docmost prose - so the marker regex cannot mistake any body text
+    // (e.g. "Press F1 for help", model "FN2") for a placeholder. The NUL is
+    // transient: the placeholder is inserted here and replaced by a
+    // footnoteReference node below; it never persists in a returned document.
     const ph = `\u0000FN${i}\u0000`;
-    // insertMarkerAfter returns a NEW cloned doc; reassign `working` and refresh
-    // the `top` / `notesList` references that point into it.
+    // insertMarkerAfter returns a NEW cloned doc; reassign `working`.
     const r = insertMarkerAfter(working, c.selection.trimEnd(), ph, {
       beforeBlock: notesIdx,
     });
     if (!r.inserted) return;
     working = r.doc;
-    noteByPh.set(ph, noteItem(mdToInlineNodes(c.content)));
+    noteInlineByPh.set(ph, mdToInlineNodes(c.content));
     consumed.push(c.id);
   });
 
   // Re-resolve references into the (possibly re-cloned) working doc.
   const top2: any[] = Array.isArray(working.content) ? working.content : [];
-  const notesList2 = top2
-    .slice(notesIdx)
-    .find((n) => isObject(n) && n.type === "orderedList");
+  const notesIdx2 = top2.findIndex(
+    (n) => isObject(n) && n.type === "heading" && blockText(n).trim() === notesHeading,
+  );
+  const oldListIndex = top2.findIndex(
+    (n) => isObject(n) && n.type === "orderedList",
+  );
+  const notesList2 = oldListIndex >= 0 ? top2[oldListIndex] : null;
   if (!notesList2) {
     throw new Error("notes orderedList not found");
   }
 
-  const oldNotes: any[] = Array.isArray(notesList2.content)
+  // Inline content of each existing note (listItem -> paragraph -> inline).
+  const oldNoteInline = (Array.isArray(notesList2.content)
     ? notesList2.content
-    : [];
-  const newNotes: any[] = [];
-  let seq = 0;
-  // Match either an existing "[N]" marker or a NUL-delimited "\u0000FN<i>\u0000"
-  // placeholder, in reading order across the body (blocks before the notes heading).
-  const re = /\[(\d+)\]|\u0000FN(\d+)\u0000/g;
-  // Same range regex setCalloutRange uses to detect the disclaimer callout's
-  // "[1]…[K]" range; used here to decide whether a top-level callout is the
-  // disclaimer (skip) or an ordinary callout (renumber normally).
+    : []
+  ).map((item: any) => {
+    const para =
+      isObject(item) && Array.isArray(item.content)
+        ? item.content.find((c: any) => isObject(c) && c.type === "paragraph")
+        : null;
+    return para && Array.isArray(para.content) ? para.content : [];
+  });
+
+  // Walk the body in reading order, turning each "[N]" / placeholder marker into
+  // a real footnoteReference node and collecting its definition inline content.
+  const definitions: any[] = [];
   const disclaimerRangeRe = /(\[1\]\s*(?:…|\.\.\.)\s*\[)\d+(\])/;
-  for (let i = 0; i < notesIdx; i++) {
-    // Skip ONLY the disclaimer callout: its "[1]…[K]" range is NOT a footnote
-    // marker and is synced separately by setCalloutRange. Renumbering it here
-    // would consume note slots and corrupt the sequence. Other top-level
-    // callouts may carry legitimate "[N]" body markers and are renumbered.
+
+  // Recursively visit inline arrays inside a block (paragraph, heading, callout
+  // child paragraphs, table cells, ...), preserving document reading order.
+  const visitInlineArrays = (container: any): void => {
+    if (!isObject(container) || !Array.isArray(container.content)) return;
+    const hasText = container.content.some(
+      (n: any) => isObject(n) && n.type === "text",
+    );
+    if (hasText) {
+      replaceMarkersWithReferences(container.content, ({ oldNum, phIdx }) => {
+        const fnId = freshId();
+        if (oldNum != null) {
+          const inline = oldNoteInline[oldNum - 1];
+          // Every existing body marker MUST map to a real note. An out-of-range
+          // marker means the document is internally inconsistent; fail loudly.
+          if (inline === undefined) {
+            throw new Error(
+              `footnote [${oldNum}] has no matching note (notes list has ${oldNoteInline.length} items); document is inconsistent`,
+            );
+          }
+          definitions.push(footnoteDefinition(fnId, inline));
+        } else {
+          const inline = noteInlineByPh.get(`\u0000FN${phIdx}\u0000`) || [];
+          definitions.push(footnoteDefinition(fnId, inline));
+        }
+        return fnId;
+      });
+    } else {
+      for (const child of container.content) visitInlineArrays(child);
+    }
+  };
+
+  const notesBoundary = notesIdx2 >= 0 ? notesIdx2 : oldListIndex;
+  for (let i = 0; i < notesBoundary; i++) {
+    // Skip ONLY the disclaimer callout: its "[1]...[K]" range is NOT a footnote
+    // marker and is synced separately by setCalloutRange.
     if (
       isObject(top2[i]) &&
       top2[i].type === "callout" &&
@@ -443,35 +540,22 @@ export function commentsToFootnotes(
     ) {
       continue;
     }
-    walk(top2[i], (node) => {
-      if (node.type !== "text" || typeof node.text !== "string") return;
-      node.text = node.text.replace(re, (_m: string, oldNum: string, phIdx: string) => {
-        if (oldNum != null) {
-          const note = oldNotes[Number(oldNum) - 1];
-          // Every existing body marker MUST map to a real note. An out-of-range
-          // marker means the document is internally inconsistent; fail loudly
-          // rather than silently dropping the note and desyncing the callout.
-          if (note === undefined) {
-            throw new Error(
-              `footnote [${oldNum}] has no matching note (notes list has ${oldNotes.length} items); document is inconsistent`,
-            );
-          }
-          newNotes.push(note);
-        } else {
-          newNotes.push(noteByPh.get(`\u0000FN${phIdx}\u0000`));
-        }
-        return `[${++seq}]`;
-      });
-    });
+    visitInlineArrays(top2[i]);
   }
 
-  // Reorder the notes list IN PLACE on `working` first, THEN sync the callout
-  // range. setCalloutRange clones `working`, so the reordered notes (mutated
-  // before the clone) are carried into its result automatically. No null-filter
-  // here: marker count and note count must stay exactly equal (the out-of-range
-  // guard above guarantees no undefined entry is ever pushed).
-  notesList2.content = newNotes;
-  const synced = setCalloutRange(working, notesList2.content.length);
+  // Replace the old orderedList with a real footnotesList of the collected
+  // definitions (reading order). If there are no definitions, drop the list.
+  if (definitions.length > 0) {
+    top2[oldListIndex] = {
+      type: "footnotesList",
+      content: definitions,
+    };
+  } else {
+    top2.splice(oldListIndex, 1);
+  }
+
+  // Sync the disclaimer callout range to the new note count.
+  const synced = setCalloutRange(working, definitions.length);
 
   return { doc: synced.doc, consumed };
 }
diff --git a/packages/mcp/test/unit/footnotes.test.mjs b/packages/mcp/test/unit/footnotes.test.mjs
new file mode 100644
index 00000000..4b1ee6ab
--- /dev/null
+++ b/packages/mcp/test/unit/footnotes.test.mjs
@@ -0,0 +1,120 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { convertProseMirrorToMarkdown } from "../../build/lib/markdown-converter.js";
+import { markdownToProseMirror } from "../../build/lib/collaboration.js";
+
+/** Recursively collect every node of `type`. */
+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;
+}
+
+const footnoteDoc = {
+  type: "doc",
+  content: [
+    {
+      type: "paragraph",
+      content: [
+        { type: "text", text: "Water" },
+        { type: "footnoteReference", attrs: { id: "fn1" } },
+        { type: "text", text: " and clay" },
+        { type: "footnoteReference", attrs: { id: "fn2" } },
+        { type: "text", text: "." },
+      ],
+    },
+    {
+      type: "footnotesList",
+      content: [
+        {
+          type: "footnoteDefinition",
+          attrs: { id: "fn1" },
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "First note." }] },
+          ],
+        },
+        {
+          type: "footnoteDefinition",
+          attrs: { id: "fn2" },
+          content: [
+            { type: "paragraph", content: [{ type: "text", text: "Second note." }] },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+test("JSON -> Markdown emits pandoc footnote syntax", () => {
+  const md = convertProseMirrorToMarkdown(footnoteDoc);
+  assert.match(md, /\[\^fn1\]/);
+  assert.match(md, /\[\^fn2\]/);
+  assert.match(md, /\[\^fn1\]: First note\./);
+  assert.match(md, /\[\^fn2\]: Second note\./);
+});
+
+test("Markdown -> JSON rebuilds footnote nodes", async () => {
+  const md = convertProseMirrorToMarkdown(footnoteDoc);
+  const json = await markdownToProseMirror(md);
+
+  const refs = findAll(json, "footnoteReference");
+  const list = findAll(json, "footnotesList");
+  const defs = findAll(json, "footnoteDefinition");
+
+  assert.equal(refs.length, 2);
+  assert.deepEqual(
+    refs.map((r) => r.attrs.id),
+    ["fn1", "fn2"],
+  );
+  assert.equal(list.length, 1);
+  assert.equal(defs.length, 2);
+  assert.deepEqual(
+    defs.map((d) => d.attrs.id),
+    ["fn1", "fn2"],
+  );
+});
+
+test("JSON -> MD -> JSON preserves footnote ids and text", async () => {
+  const md = convertProseMirrorToMarkdown(footnoteDoc);
+  const json = await markdownToProseMirror(md);
+  const md2 = convertProseMirrorToMarkdown(json);
+
+  // The second markdown serialization carries the same markers + definitions.
+  assert.match(md2, /\[\^fn1\]/);
+  assert.match(md2, /\[\^fn2\]/);
+  assert.match(md2, /\[\^fn1\]: First note\./);
+  assert.match(md2, /\[\^fn2\]: Second note\./);
+});
+
+test("a [^id]: line inside a fenced code block is NOT treated as a definition", async () => {
+  // Markdown that DOCUMENTS footnote syntax inside a code fence. The example
+  // definition line must be preserved verbatim inside the code block and not
+  // pulled out into a real footnotesList / footnoteDefinition.
+  const md = [
+    "Intro text.",
+    "",
+    "```markdown",
+    "Body[^demo]",
+    "",
+    "[^demo]: example definition",
+    "```",
+    "",
+    "Outro.",
+  ].join("\n");
+
+  const json = await markdownToProseMirror(md);
+
+  // No real footnote nodes were extracted from the code block.
+  assert.equal(findAll(json, "footnotesList").length, 0);
+  assert.equal(findAll(json, "footnoteDefinition").length, 0);
+
+  // The example definition line survives somewhere in the code block text.
+  const codeBlocks = findAll(json, "codeBlock");
+  assert.ok(codeBlocks.length >= 1, "code block present");
+  const codeText = JSON.stringify(json);
+  assert.match(codeText, /\[\^demo\]: example definition/);
+});
diff --git a/packages/mcp/test/unit/transforms.test.mjs b/packages/mcp/test/unit/transforms.test.mjs
index 3f66593c..f7999113 100644
--- a/packages/mcp/test/unit/transforms.test.mjs
+++ b/packages/mcp/test/unit/transforms.test.mjs
@@ -34,6 +34,18 @@ const li = (text) => ({
 const doc = (...children) => ({ type: "doc", content: children });
 const snapshot = (v) => JSON.parse(JSON.stringify(v));
 
+// Collect every footnoteReference id under a node, in reading order.
+const collectRefIds = (node, acc = []) => {
+  if (!node || typeof node !== "object") return acc;
+  if (node.type === "footnoteReference") acc.push(node.attrs?.id);
+  if (Array.isArray(node.content)) {
+    for (const c of node.content) collectRefIds(c, acc);
+  }
+  return acc;
+};
+// Plain text of a footnoteDefinition.
+const defText = (def) => blockText(def);
+
 // ---------------------------------------------------------------------------
 // blockText / walk / getList
 // ---------------------------------------------------------------------------
@@ -173,21 +185,30 @@ test("commentsToFootnotes anchors comments and renumbers by position", () => {
   const { doc: out, consumed } = commentsToFootnotes(d, comments);
   assert.deepEqual(consumed.sort(), ["cA", "cB"]);
 
-  // Markers in reading order: p1 "apple"->[1], p2 existing->[2], p3 "banana"->[3]
-  assert.match(blockText(out.content[1]), /\[1\]/);
-  assert.match(blockText(out.content[2]), /\[2\]/);
-  assert.match(blockText(out.content[3]), /\[3\]/);
+  // Real footnoteReference nodes were inserted at p1 (apple), p2 (existing),
+  // p3 (banana), in reading order — the old `[N]` text markers are gone.
+  const refIds = collectRefIds(out);
+  assert.equal(refIds.length, 3);
+  // Body paragraphs p1..p3 no longer carry literal [N] text markers.
+  assert.doesNotMatch(blockText(out.content[1]), /\[\d+\]/);
+  assert.doesNotMatch(blockText(out.content[2]), /\[\d+\]/);
+  assert.doesNotMatch(blockText(out.content[3]), /\[\d+\]/);
 
-  // No stray placeholders remain.
-  const allText = blockText(out);
-  assert.doesNotMatch(allText, / F\d+ /);
+  // No stray NUL placeholders remain.
+  assert.doesNotMatch(blockText(out), /\u0000/);
 
-  // Notes list reordered to [apple, existing, banana] (reading order).
-  const list = out.content.find((n) => n.type === "orderedList");
+  // The bottom footnotesList holds the definitions in reading order, each keyed
+  // by the matching reference id.
+  const list = out.content.find((n) => n.type === "footnotesList");
+  assert.ok(list, "footnotesList present");
   assert.equal(list.content.length, 3);
-  assert.equal(blockText(list.content[0]), "apple note");
-  assert.equal(blockText(list.content[1]), "existing note one");
-  assert.equal(blockText(list.content[2]), "banana note");
+  assert.deepEqual(
+    list.content.map((d) => d.attrs.id),
+    refIds,
+  );
+  assert.equal(defText(list.content[0]), "apple note");
+  assert.equal(defText(list.content[1]), "existing note one");
+  assert.equal(defText(list.content[2]), "banana note");
 
   // Callout range synced to 3 notes.
   assert.match(blockText(out.content[0]), /\[1\]…\[3\]/);
@@ -224,15 +245,16 @@ test("commentsToFootnotes leaves literal 'F1'/'FN2'/'F12' body text untouched",
   // The literal "F1"/"FN2"/"F12" prose is preserved verbatim (no bogus
   // footnotes, no eaten spaces around them).
   assert.match(bodyText, /Press F1 for help, model FN2 and F12 for tools/);
-  // Exactly one real footnote marker was produced, at the anchored word.
-  const markerCount = (bodyText.match(/\[\d+\]/g) || []).length;
-  assert.equal(markerCount, 1);
-  assert.match(bodyText, /apple \[1\]/);
+  // Exactly one real footnoteReference node was produced, at the anchored word.
+  const refIds = collectRefIds(out);
+  assert.equal(refIds.length, 1);
 
   // Exactly one note in the list — "F1"/"FN2"/"F12" did not spawn extra notes.
-  const list = out.content.find((n) => n.type === "orderedList");
+  const list = out.content.find((n) => n.type === "footnotesList");
+  assert.ok(list, "footnotesList present");
   assert.equal(list.content.length, 1);
-  assert.equal(blockText(list.content[0]), "apple note");
+  assert.equal(list.content[0].attrs.id, refIds[0]);
+  assert.equal(defText(list.content[0]), "apple note");
 
   // No stray placeholder sentinel remains anywhere: the NUL-delimited sentinel
   // is fully consumed by the renumber pass, so no raw NUL control char persists
@@ -287,17 +309,25 @@ test("commentsToFootnotes renumbers body callouts but skips the disclaimer range
   assert.deepEqual(consumed, []);
 
   // The disclaimer's "[1]…[K]" range is NOT treated as body markers: it stays
-  // a range and is synced to the note count (2), not renumbered into [1],[2].
+  // a range and is synced to the note count (2), not turned into references.
   assert.match(blockText(out.content[0]), /\[1\]…\[2\]/);
 
-  // The body callout's [1] is renumbered as a real reading-order marker.
-  assert.match(blockText(out.content[1]), /noted \[1\] above/);
-  // The following paragraph's [2] keeps reading order.
-  assert.match(blockText(out.content[2]), /with \[2\] too/);
+  // The body callout's [1] and the paragraph's [2] became footnoteReference
+  // nodes in reading order (the literal text markers are gone).
+  const refIds = collectRefIds(out);
+  assert.equal(refIds.length, 2);
+  assert.match(blockText(out.content[1]), /noted +above/); // [1] -> node, no text
+  assert.match(blockText(out.content[2]), /with +too/); // [2] -> node, no text
 
-  // Notes list still has the two original notes in order.
-  const list = out.content.find((n) => n.type === "orderedList");
+  // The footnotesList holds the two original notes in reading order, keyed to
+  // the new reference ids.
+  const list = out.content.find((n) => n.type === "footnotesList");
+  assert.ok(list, "footnotesList present");
   assert.equal(list.content.length, 2);
-  assert.equal(blockText(list.content[0]), "first note");
-  assert.equal(blockText(list.content[1]), "second note");
+  assert.deepEqual(
+    list.content.map((d) => d.attrs.id),
+    refIds,
+  );
+  assert.equal(defText(list.content[0]), "first note");
+  assert.equal(defText(list.content[1]), "second note");
 });

From 1c83a8ae15ca3b03f017ca5cc3ca6a7158283d55 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 11:39:00 +0300
Subject: [PATCH 02/28] docs: remove implemented footnotes plan

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/footnotes-plan.md | 244 -----------------------------------------
 1 file changed, 244 deletions(-)
 delete mode 100644 docs/footnotes-plan.md

diff --git a/docs/footnotes-plan.md b/docs/footnotes-plan.md
deleted file mode 100644
index 78a0e41b..00000000
--- a/docs/footnotes-plan.md
+++ /dev/null
@@ -1,244 +0,0 @@
-# Сноски (footnotes) — проект фичи
-
-> Статус: **проработанный план, готов к реализации**. Ключевые решения приняты.
-> - Архитектура: **reference + definitions** (модель Markdown/pandoc), а не «самодостаточный inline-атом со вложенным под-редактором».
-> - Объём: **полная интеграция** — редактор + коллаборация (Yjs/Hocuspocus) + Markdown round-trip + зеркало схемы в MCP + AI-хелпер.
->
-> Исходный кейс: переводы технических статей (например, про дефлокуляцию при шликерном литье) требуют сносок переводчика и ссылок на источники. Сейчас их некуда деть, кроме инлайновых комментариев или костыля `[1]` руками.
-
-## 1. Цели и требования
-
-1. **Читать сноску прямо в тексте** — навёл/кликнул на надстрочный номер → всплывающее окно с текстом сноски, не уходя со строки.
-2. **Определения внизу страницы как часть текста** — текст сносок живёт реальным редактируемым блоком в конце документа (выделяется, копируется, экспортируется), а не виртуальной отрисовкой.
-3. **Авто-нумерация** — номера проставляются и пересчитываются автоматически при вставке/удалении/перемещении.
-4. **Безопасно для совместного редактирования** — работает поверх Hocuspocus/Yjs без расхождений между клиентами.
-5. **Переживает Markdown** — экспорт/импорт страниц со сносками (формат pandoc/GFM `[^id]`).
-6. **Доступно AI-агенту и MCP** — агент и MCP-инструменты умеют читать/создавать сноски; существующий хелпер `commentsToFootnotes` переводится на настоящие ноды.
-
-## 2. Развилка (решена): почему НЕ «классический» footnote-атом
-
-Есть два принципиально разных способа хранить текст сноски в ProseMirror/Tiptap.
-
-### Вариант A — самодостаточный inline-атом (официальный пример ProseMirror)
-
-Текст сноски лежит **внутри** inline-атома (`inline: true, atom: true, content: "text*"`), редактируется во вложенном под-редакторе в тултипе. См. [prosemirror.net/examples/footnote](https://prosemirror.net/examples/footnote/) и расширение [tiptap-extension-footnote](https://github.com/LAbigael/tiptap-extension-footnote).
-
-Минусы для нашего стека:
-- **Несовместим с коллаборацией.** Вложенный под-редактор синхронизирует шаги транзакций вручную (`dispatchInner`, флаг `fromOutside`). Поверх Hocuspocus/Yjs (`TiptapTransformer`) это даёт конфликты/расхождения — известная больная точка. У нас коллаборация — это ядро ([collaboration.gateway.ts](../apps/server/src/collaboration/collaboration.gateway.ts), [yjs.util.ts](../apps/server/src/collaboration/yjs.util.ts)).
-- **Текст нельзя «положить вниз как часть текста».** Он заперт в атоме; нижний список пришлось бы рисовать виртуально (CSS/декорации) — он не выделяется и плохо экспортируется.
-- Само расширение помечено `ALPHA, DO NOT USE FOR PRODUCTION`.
-
-### Вариант B — reference + definitions (ВЫБРАН)
-
-Маркер в тексте и текст сноски — **разные обычные ноды**, связанные по `id`:
-- inline-атом-ссылка без контента (просто надстрочный номер);
-- блок определений внизу страницы из обычных редактируемых нод.
-
-Плюсы — это ровно то, что нужно:
-- **Только обычные ноды → Yjs обрабатывает их нативно**, без вложенных редакторов. Главный выигрыш для коллаборативного стека.
-- Нижний блок — **реальная часть документа**: выделяется, копируется, экспортируется (требование 2).
-- Чтение в тексте — **read-only поповер**, который просто читает определение по `id`; под-редактор не нужен (требование 1).
-- **1:1 ложится на Markdown-сноски** pandoc/GFM (`[^id]` … `[^id]: …`) → импорт/экспорт и хелпер `commentsToFootnotes` выравниваются естественно (требования 5, 6).
-
-Минусы (управляемые, см. §4–§5): нужно держать ссылки и определения в синхроне (сироты/висячие ссылки) и считать номера/порядок плагином.
-
-## 3. Модель документа
-
-Три новые ноды. Источник истины — **ссылка**: есть `footnoteReference` → есть парное `footnoteDefinition`; удаление ссылки каскадно удаляет определение в той же транзакции (один Ctrl+Z восстанавливает оба).
-
-```jsonc
-// 1) Маркер в тексте — inline atom, без контента, только id.
-//    Видимый номер НЕ хранится в документе (см. §4).
-{ "type": "footnoteReference", "attrs": { "id": "fn_a1b2c3" } }
-
-// 2) Контейнер внизу страницы — реальный блок, всегда последний в документе.
-{ "type": "footnotesList", "content": [ /* footnoteDefinition+ */ ] }
-
-// 3) Одно определение — обычный редактируемый блок с id, привязывающим к ссылке.
-{ "type": "footnoteDefinition",
-  "attrs": { "id": "fn_a1b2c3" },
-  "content": [ { "type": "paragraph", "content": [ /* текст сноски, inline */ ] } ] }
-```
-
-### Почему нода, а не mark
-
-Ссылка на сноску — это **вставляемый в точку курсора надстрочный глиф**, а не выделение существующего текста. Mark (как у комментариев в [comment.ts](../packages/editor-ext/src/lib/comment/comment.ts)) оборачивает диапазон; нам нужна точечная inline-нода-атом — образец [mention.ts](../packages/editor-ext/src/lib/mention.ts) (`inline: true, atom: true, selectable: true`).
-
-### Схемные ограничения
-
-| Нода | Параметры схемы | Где разрешена / что внутри |
-|---|---|---|
-| `footnoteReference` | `group: "inline"`, `inline: true`, `atom: true`, `selectable: true`, `draggable: false` | в любом inline-контексте, **кроме** code-block и **кроме** содержимого `footnoteDefinition` (запрет вложенных сносок) |
-| `footnotesList` | `group: "block"`, `content: "footnoteDefinition+"`, `isolating: true`, `selectable: false` | единственный экземпляр, всегда **последний** дочерний узел документа |
-| `footnoteDefinition` | `content: "paragraph+"` (или `block+` без вложенных сносок), `defining: true`, `isolating: true` | только внутри `footnotesList`; атрибут `id` обязателен |
-
-`id` генерируется как `uuidv7` (как у mention/unique-id), хранится в `data-*`-атрибуте для HTML round-trip.
-
-## 4. Нумерация и порядок — ключевая тонкость
-
-**Решение: номера НЕ хранятся в документе.** Их вычисляет ProseMirror-плагин, проходя `footnoteReference` в порядке документа, и отрисовывает декорациями (на надстрочнике и на маркере определения).
-
-Почему так:
-- Детерминированность: каждый клиент считает одинаковые номера из одного и того же документа → **никаких расхождений в коллаборации**, никаких `appendTransaction` в ответ на чужие шаги (что и есть источник конфликтов).
-- Дёшево: пересчёт на каждый рендер, без мутаций документа.
-
-### Порядок определений внизу
-
-Чтобы нижний список визуально шёл `1, 2, 3`, реальные ноды `footnoteDefinition` должны лежать в порядке ссылок (декорации не переставляют DOM). Стратегия:
-
-1. **На создании** — команда `setFootnote` вставляет определение в **правильную позицию** (считает, сколько ссылок идёт до точки вставки, и кладёт определение по этому индексу). Покрывает и добавление в конец, и вставку в середину.
-2. **Нормализация** — плагин-нормализатор приводит порядок определений к порядку ссылок, если он нарушился (например, пользователь вырезал и переставил абзац со ссылкой). Это **чистая функция от состояния документа** → все клиенты вычисляют одинаковую перестановку и сходятся. Чтобы два клиента не дёргали нормализацию одновременно, выполнять её в `appendTransaction` с guard-метой и идемпотентно (no-op, если порядок уже верный).
-
-> Главный риск реализации — именно нормализация порядка при перемещении ссылок в коллаборации. Для MVP достаточно правильной вставки на создании (п.1) + нормализации только на локальных транзакциях; перемещение ссылок между местами — редкий кейс, его можно довести во вторую очередь.
-
-Визуальные номера можно при желании продублировать CSS-счётчиками (`counter-reset`/`counter-increment`, как в alpha-расширении), но decoration-подход надёжнее в коллаборации и не зависит от порядка узлов.
-
-## 5. Жизненный цикл, команды и UX
-
-### Команды (в ноде, через `addCommands` + `declare module "@tiptap/core"`)
-
-- `setFootnote()` — в одной транзакции: вставляет `footnoteReference` с новым `id` в позицию курсора + создаёт `footnotesList` (если его нет, в самом конце документа) + добавляет туда пустое `footnoteDefinition` с тем же `id` в правильную позицию + переносит фокус в это определение, чтобы сразу печатать текст.
-- `removeFootnote(id)` — удаляет ссылку и её определение (каскад в одной транзакции). Если определений не осталось — удаляет пустой `footnotesList`.
-- `scrollToFootnote(id)` / `scrollToReference(id)` — навигация «ссылка ↔ определение» (для кнопки в поповере и «↩» в определении).
-
-### Ввод
-
-- **Slash-меню** `/footnote` (или `/сноска`) — пункт в [slash-menu](../apps/client/src/features/editor/components/slash-menu), вызывает `setFootnote`.
-- **Кнопка тулбара** и шорткат (например `Mod-Alt-F`).
-- Опционально input-rule (по образцу `wrappingInputRule` в callout) — например `[^` → вставка сноски; решить при реализации, не обязательно для MVP.
-
-### Плагин синхронизации (`addProseMirrorPlugins`)
-
-Минимальный, guard’нутый, идемпотентный:
-- **Подчистка сирот**: `footnoteDefinition` без парной ссылки — удалить (или пометить, см. §12).
-- **Вставка/коллизии при paste**: ссылка без определения → создать пустое определение; определение без ссылки → удалить; при вставке с конфликтом `id` — регенерировать `id` у пары.
-- **Пустой контейнер**: нет определений → удалить `footnotesList`.
-- **Read-only / share**: плагин **не мутирует документ** (только декорации нумерации), чтобы не трогать общий документ при простом просмотре.
-
-## 6. Чтение в тексте (поповер)
-
-NodeView надстрочника (`ReactNodeViewRenderer`, образец mention/callout) по hover/click открывает поповер через `@floating-ui/dom` — тот же паттерн, что в [render-items.ts](../apps/client/src/features/editor/components/slash-menu/render-items.ts) и [mention-suggestion.ts](../apps/client/src/features/editor/components/mention/mention-suggestion.ts) (offset/flip/shift, autoUpdate, закрытие по outside-click).
-
-Поповер показывает **read-only** текст определения, найденного по `id` прямо в `editor.state` (никакого под-редактора). Кнопка «редактировать»/«перейти» вызывает `scrollToFootnote(id)` и фокусит определение внизу. Работает и в read-only/share-режиме — там используется тот же `mainExtensions` ([extensions.ts](../apps/client/src/features/editor/extensions/extensions.ts), [readonly-page-editor.tsx](../apps/client/src/features/editor/readonly-page-editor.tsx)).
-
-## 7. Нижний блок (footnotesList)
-
-NodeView контейнера рисует визуальный разделитель: верхняя граница + заголовок («Footnotes» / «Примечания», локализуется), список `footnoteDefinition`. Каждое определение — `NodeViewContent` (редактируемый контент) + декоративный номер (из §4) + «↩» для возврата к ссылке. Стили — CSS-модули + Mantine, как у остальных NodeView ([components/callout](../apps/client/src/features/editor/components/callout)).
-
-## 8. HTML round-trip (parseHTML / renderHTML)
-
-Для лосслесс HTML↔JSON (экспорт, `generateHTML`, серверный рендер, зеркало MCP) у каждой ноды строгие `parseHTML`/`renderHTML`:
-
-| Нода | renderHTML (примерно) | parseHTML |
-|---|---|---|
-| `footnoteReference` | `<sup data-footnote-ref data-id="…">` (атом, без контента; номер ставит CSS/декорация) | `sup[data-footnote-ref]` |
-| `footnotesList` | `<section data-footnotes>…</section>` (или `<ol>`) | `section[data-footnotes]` |
-| `footnoteDefinition` | `<div data-footnote-def data-id="…">…0…</div>` (`0` — дырка под контент) | `div[data-footnote-def]` |
-
-## 9. Markdown
-
-Маппинг на сноски pandoc/GFM:
-- `footnoteReference` → `[^id]` в тексте;
-- `footnoteDefinition` → `[^id]: текст` в конце документа.
-
-Точки правки:
-- **Экспорт HTML→Markdown (клиент/сервер):** правило turndown в [turndown.utils.ts](../packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts) (образец — правило callout).
-- **Импорт Markdown→JSON:** плагин/расширение marked в [marked.utils.ts](../packages/editor-ext/src/lib/markdown/utils/marked.utils.ts), плюс ноды должны быть в схеме `generateJSON`.
-- **MCP JSON→Markdown:** case в [markdown-converter.ts](../packages/mcp/src/lib/markdown-converter.ts) (образцы — mention/callout).
-- **Fallback:** при экспорте в формат без сносок — деградация в инлайновые `[n]` + список (текущее поведение `commentsToFootnotes`).
-
-## 10. Сервер и коллаборация
-
-Новые ноды обязаны попасть в серверный список расширений `tiptapExtensions` ([collaboration.util.ts](../apps/server/src/collaboration/collaboration.util.ts)) — иначе:
-- сервер вырежет ноды при сохранении/коллаборации (`getSchema` в [yjs.util.ts](../apps/server/src/collaboration/yjs.util.ts));
-- сломается серверный рендер HTML ([generateHTML.ts](../apps/server/src/common/helpers/prosemirror/html/generateHTML.ts)) и экспорт ([export.service.ts](../apps/server/src/integrations/export/export.service.ts)).
-
-Поскольку это обычные ноды (а не атом с под-редактором), Yjs/`TiptapTransformer` обрабатывает их автоматически — отдельной регистрации в Yjs не нужно. Миграции БД не требуется (это уровень ProseMirror-документа, не схемы Postgres).
-
-## 11. MCP: зеркало схемы и конвертер
-
-`packages/mcp` **не** импортирует `editor-ext`, а держит собственное зеркало схемы. Синхронизировать вручную:
-- определения трёх нод (`parseHTML`/`renderHTML`, атрибуты) — в [docmost-schema.ts](../packages/mcp/src/lib/docmost-schema.ts);
-- сериализацию в Markdown — в [markdown-converter.ts](../packages/mcp/src/lib/markdown-converter.ts);
-- перевод существующего хелпера `commentsToFootnotes` ([transforms.ts](../packages/mcp/src/lib/transforms.ts)) с текстовых `[N]` + `orderedList` на настоящие ноды `footnoteReference`/`footnotesList`/`footnoteDefinition`; обновить подсчёт маркеров в [diff.ts](../packages/mcp/src/lib/diff.ts).
-
-> ⚠️ При любом изменении схемы документа держать `packages/mcp/src/lib/` и `packages/editor-ext` в синхроне — это явное требование CLAUDE.md.
-
-## 12. Краевые случаи и решения
-
-| Случай | Решение |
-|---|---|
-| Удалили ссылку | Каскадно удалить определение в той же транзакции (undo восстанавливает оба) |
-| Удалили последнюю ссылку | Удалить весь `footnotesList` |
-| Paste ссылки без определения | Создать пустое определение |
-| Paste определения без ссылки | Удалить (сирота) — либо v2: пометить «осиротевшим» |
-| Коллизия `id` при paste | Регенерировать `id` у вставленной пары |
-| Перемещение ссылки (cut/paste абзаца) | Нормализатор переупорядочивает определения (§4) |
-| Вложенная сноска (ссылка внутри определения) | Запретить схемой |
-| Ссылка в code-block | Запретить |
-| Несколько ссылок на одну сноску | v2 (MVP: строго 1:1) |
-| Экспорт в формат без сносок | Fallback на `[n]` + список |
-| Read-only / share | Только декорации нумерации, без мутаций документа |
-
-## 13. Затрагиваемые файлы (полный список)
-
-**Редактор (editor-ext):**
-- `packages/editor-ext/src/lib/footnote/` — новые: три ноды, плагин нумерации/нормализации, команды, NodeView’ы (новый каталог).
-- [packages/editor-ext/src/index.ts](../packages/editor-ext/src/index.ts) — экспорт.
-
-**Клиент:**
-- [apps/client/src/features/editor/extensions/extensions.ts](../apps/client/src/features/editor/extensions/extensions.ts) — регистрация в `mainExtensions`, привязка React-NodeView.
-- `apps/client/src/features/editor/components/footnote/` — NodeView надстрочника + поповер чтения, NodeView нижнего блока, CSS-модули (новый каталог).
-- [apps/client/src/features/editor/components/slash-menu](../apps/client/src/features/editor/components/slash-menu) — пункт `/footnote`.
-
-**Сервер / коллаборация:**
-- [apps/server/src/collaboration/collaboration.util.ts](../apps/server/src/collaboration/collaboration.util.ts) — добавить ноды в `tiptapExtensions`.
-
-**Markdown round-trip:**
-- [packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts](../packages/editor-ext/src/lib/markdown/utils/turndown.utils.ts)
-- [packages/editor-ext/src/lib/markdown/utils/marked.utils.ts](../packages/editor-ext/src/lib/markdown/utils/marked.utils.ts)
-
-**MCP:**
-- [packages/mcp/src/lib/docmost-schema.ts](../packages/mcp/src/lib/docmost-schema.ts)
-- [packages/mcp/src/lib/markdown-converter.ts](../packages/mcp/src/lib/markdown-converter.ts)
-- [packages/mcp/src/lib/transforms.ts](../packages/mcp/src/lib/transforms.ts) (+ [diff.ts](../packages/mcp/src/lib/diff.ts))
-
-## 14. План реализации по фазам
-
-1. **Схема (editor-ext):** три ноды + команды + input-rule + экспорт в `index.ts`. Минимальный плагин нумерации (декорации). Это фундамент, от него зависит всё.
-2. **Клиент UI:** NodeView надстрочника + поповер чтения (floating-ui), NodeView нижнего блока, slash-меню, CSS, регистрация в `extensions.ts`. Проверить read-only/share.
-3. **Сервер/коллаборация:** регистрация в `tiptapExtensions`; проверить сохранение, коллаборацию двух клиентов, серверный рендер/экспорт HTML.
-4. **Markdown round-trip:** turndown + marked; тест «JSON → MD → JSON» без потерь.
-5. **MCP:** зеркало схемы + конвертер + перевод `commentsToFootnotes` на ноды + `diff.ts`.
-6. **Шлифовка:** нормализация порядка при перемещении ссылок, edge-cases из §12, доступность (ARIA для надстрочника/поповера).
-
-## 15. Тестирование
-
-- **Unit (mcp, `node --test`):** JSON↔Markdown round-trip сносок; `commentsToFootnotes` → ноды; нумерация/нормализация как чистая функция.
-- **Unit (editor-ext):** команды `setFootnote`/`removeFootnote`, каскадное удаление, вставка определения в правильную позицию.
-- **Client (Vitest):** рендер надстрочника и поповера, навигация ссылка↔определение.
-- **Ручной/e2e:** два коллаборативных клиента (одновременная вставка сносок, отсутствие расхождений нумерации), экспорт в PDF/Markdown, публичная шара (поповер в read-only).
-
-## 16. Открытые вопросы / v2
-
-- Повторное использование одной сноски несколькими ссылками (pandoc допускает) — отложено.
-- Сноски-сироты: удалять молча или показывать предупреждение/«осиротевший» бейдж.
-- Концевые сноски (endnotes) на уровне спейса/книги vs постраничные — вне объёма.
-- Доп. форматы экспорта (DOCX и т.п.) — отдельно.
-
----
-
-### Ссылки на код
-
-- Образец inline-атома: [packages/editor-ext/src/lib/mention.ts](../packages/editor-ext/src/lib/mention.ts)
-- Образец блок-ноды с контентом + NodeView + input-rule: [packages/editor-ext/src/lib/callout/callout.ts](../packages/editor-ext/src/lib/callout/callout.ts)
-- Образец mark с id + плагин-декорация: [packages/editor-ext/src/lib/comment/comment.ts](../packages/editor-ext/src/lib/comment/comment.ts)
-- Реестр нод editor-ext: [packages/editor-ext/src/index.ts](../packages/editor-ext/src/index.ts)
-- Клиентский список расширений: [apps/client/src/features/editor/extensions/extensions.ts](../apps/client/src/features/editor/extensions/extensions.ts)
-- Поповеры через floating-ui: [slash-menu/render-items.ts](../apps/client/src/features/editor/components/slash-menu/render-items.ts), [mention/mention-suggestion.ts](../apps/client/src/features/editor/components/mention/mention-suggestion.ts)
-- Серверный список расширений: [apps/server/src/collaboration/collaboration.util.ts](../apps/server/src/collaboration/collaboration.util.ts)
-- Yjs-схема / рендер: [apps/server/src/collaboration/yjs.util.ts](../apps/server/src/collaboration/yjs.util.ts), [apps/server/src/common/helpers/prosemirror/html/generateHTML.ts](../apps/server/src/common/helpers/prosemirror/html/generateHTML.ts)
-- Markdown ↔ HTML: [packages/editor-ext/src/lib/markdown](../packages/editor-ext/src/lib/markdown)
-- Зеркало схемы MCP: [packages/mcp/src/lib/docmost-schema.ts](../packages/mcp/src/lib/docmost-schema.ts)
-- MCP конвертер / хелпер сносок: [packages/mcp/src/lib/markdown-converter.ts](../packages/mcp/src/lib/markdown-converter.ts), [packages/mcp/src/lib/transforms.ts](../packages/mcp/src/lib/transforms.ts)
-- Прообраз из примера ProseMirror: [prosemirror.net/examples/footnote](https://prosemirror.net/examples/footnote/)

From ceee2a76cacdee50edc138bfb7e5758b62abe2ec Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 13:47:10 +0300
Subject: [PATCH 03/28] fix(footnotes): survive duplicate-id definitions
 without collab divergence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Release-cycle red-team found two same-id footnoteDefinition nodes (trivially
produced by markdown import [^d]: first / [^d]: second, or paste/duplicate)
caused silent data loss: scan() used a last-wins Map and the sync rebuild
(addToHistory:false, propagated via Yjs, un-undoable) dropped all but the last.

Fix resolves collisions so BOTH survive, with a DETERMINISTIC id scheme so
collaborators converge:
- deriveFootnoteId(originalId, occurrence, taken): the k-th (k>=2) occurrence of
  id X becomes X__k, bumped with a deterministic alpha suffix only against the
  doc's own id set — a pure function of document state. No Math.random/Date.now
  on the sync or import paths (random uuid stays only in setFootnote, where a
  single user originates a brand-new id).
- footnote-sync.resolveCollisions walks refs+defs in document order, re-ids
  duplicate references via setNodeMarkup and pairs them 1:1 with definitions;
  single SYNC_META-tagged transaction, returns null when canonical (terminates).
- Markdown import (footnote.marked) + MCP mirror (collaboration.ts) dedup with
  the same deterministic scheme + marker rewrite; packages/mcp/build regenerated.
- Paste plugin remaps colliding pasted ids against the current doc.

Tests: two independent editors resolving the same duplicate-id doc produce
IDENTICAL ids (the cross-client determinism guard that the random version would
fail); both definitions survive the first edit; import dedup is deterministic.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../lib/footnote/footnote-markdown.test.ts    |  84 +++++
 .../src/lib/footnote/footnote-reference.ts    |   5 +-
 .../src/lib/footnote/footnote-sync.ts         | 349 ++++++++++++++++--
 .../src/lib/footnote/footnote-util.ts         |  55 +++
 .../src/lib/footnote/footnote.test.ts         | 154 ++++++++
 .../src/lib/markdown/utils/footnote.marked.ts |  57 ++-
 packages/mcp/build/lib/collaboration.js       |  72 +++-
 packages/mcp/src/lib/collaboration.ts         |  80 +++-
 packages/mcp/test/unit/footnotes.test.mjs     |  33 ++
 9 files changed, 864 insertions(+), 25 deletions(-)

diff --git a/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts b/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
index a6f3d4ab..844134f6 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-markdown.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { htmlToMarkdown } from "../markdown/utils/turndown.utils";
 import { markdownToHtml } from "../markdown/utils/marked.utils";
+import { extractFootnoteDefinitions } from "../markdown/utils/footnote.marked";
 
 // HTML the editor-ext nodes render (sup[data-footnote-ref], section/div).
 const HTML =
@@ -53,4 +54,87 @@ describe("footnote markdown round-trip", () => {
     expect(html).not.toContain("data-footnotes");
     expect(html).not.toContain("data-footnote-def");
   });
+
+  it("extractFootnoteDefinitions de-duplicates colliding ids and rewrites markers", () => {
+    // Two definitions share id `d`, and the body has two `[^d]` markers. The
+    // output must keep BOTH definitions with DISTINCT ids and rewrite the second
+    // marker so the (reference, definition) pairing stays 1:1.
+    const md = [
+      "See here[^d] and there[^d].",
+      "",
+      "[^d]: first",
+      "[^d]: second",
+    ].join("\n");
+
+    const { body, section } = extractFootnoteDefinitions(md);
+
+    // Pull out the def ids from the section in order.
+    const defIds = Array.from(
+      section.matchAll(/data-footnote-def data-id="([^"]+)"/g),
+    ).map((m) => m[1]);
+    expect(defIds.length).toBe(2);
+    expect(new Set(defIds).size).toBe(2); // distinct
+    expect(defIds[0]).toBe("d"); // first definition keeps the id
+
+    // Both definition texts survive.
+    expect(section).toContain("first");
+    expect(section).toContain("second");
+
+    // The body still has two markers, now pointing at the two distinct ids.
+    const refIds = Array.from(body.matchAll(/\[\^([^\]\s]+)\]/g)).map(
+      (m) => m[1],
+    );
+    expect(refIds.length).toBe(2);
+    expect(refIds.sort()).toEqual(defIds.sort());
+  });
+
+  it("extractFootnoteDefinitions dedups DETERMINISTICALLY (same input -> same ids)", () => {
+    // The derived id must be a pure function of the input markdown so importing
+    // the same source twice (or via the editor and the MCP mirror) yields
+    // identical ids — never random/time-based.
+    const md = [
+      "See[^d] one[^d] two[^d].",
+      "",
+      "[^d]: first",
+      "[^d]: second",
+      "[^d]: third",
+    ].join("\n");
+
+    const run = () => {
+      const { body, section } = extractFootnoteDefinitions(md);
+      const defIds = Array.from(
+        section.matchAll(/data-footnote-def data-id="([^"]+)"/g),
+      ).map((m) => m[1]);
+      const refIds = Array.from(body.matchAll(/\[\^([^\]\s]+)\]/g)).map(
+        (m) => m[1],
+      );
+      return { defIds, refIds };
+    };
+
+    const a = run();
+    const b = run();
+    // Identical across runs (this is what would FAIL on the random-id version).
+    expect(a.defIds).toEqual(b.defIds);
+    expect(a.refIds).toEqual(b.refIds);
+    // Deterministic derived scheme: keeper "d", duplicates "d__2", "d__3".
+    expect(a.defIds).toEqual(["d", "d__2", "d__3"]);
+    expect(a.refIds.sort()).toEqual(a.defIds.sort());
+  });
+
+  it("markdownToHtml with duplicate ids renders two distinct footnote defs", async () => {
+    const md = [
+      "See here[^d] and there[^d].",
+      "",
+      "[^d]: first",
+      "[^d]: second",
+    ].join("\n");
+    const html = await markdownToHtml(md);
+    const defIds = Array.from(
+      html.matchAll(/data-footnote-def data-id="([^"]+)"/g),
+    ).map((m) => m[1]);
+    expect(defIds.length).toBe(2);
+    expect(new Set(defIds).size).toBe(2);
+    expect(html).toContain("first");
+    expect(html).toContain("second");
+  });
 });
diff --git a/packages/editor-ext/src/lib/footnote/footnote-reference.ts b/packages/editor-ext/src/lib/footnote/footnote-reference.ts
index 90f5e109..7b47617d 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-reference.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-reference.ts
@@ -8,7 +8,7 @@ import {
   generateFootnoteId,
 } from "./footnote-util";
 import { footnoteNumberingPlugin } from "./footnote-numbering";
-import { footnoteSyncPlugin } from "./footnote-sync";
+import { footnoteSyncPlugin, footnotePastePlugin } from "./footnote-sync";
 
 export interface FootnoteReferenceOptions {
   HTMLAttributes: Record<string, any>;
@@ -88,6 +88,9 @@ export const FootnoteReference = Node.create<FootnoteReferenceOptions>({
     // doc is never mutated.
     if (this.options.enableSync !== false) {
       plugins.push(footnoteSyncPlugin(this.options.isRemoteTransaction));
+      // Regenerate colliding footnote ids on paste so a pasted reference+
+      // definition pair never clobbers/merges with an existing footnote.
+      plugins.push(footnotePastePlugin());
     }
     return plugins;
   },
diff --git a/packages/editor-ext/src/lib/footnote/footnote-sync.ts b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
index ffd2e136..33258590 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-sync.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
@@ -1,48 +1,215 @@
 import { Plugin, PluginKey, Transaction } from "@tiptap/pm/state";
-import { Node as ProseMirrorNode, Fragment } from "@tiptap/pm/model";
+import { Node as ProseMirrorNode, Fragment, Slice } from "@tiptap/pm/model";
 import {
   FOOTNOTE_DEFINITION_NAME,
   FOOTNOTE_REFERENCE_NAME,
   FOOTNOTES_LIST_NAME,
+  deriveFootnoteId,
 } from "./footnote-util";
 
 export const footnoteSyncPluginKey = new PluginKey("footnoteSync");
 
 const SYNC_META = "footnoteSyncApplied";
 
+interface RefOccurrence {
+  /** Position of the reference node in the document. */
+  pos: number;
+  /** The id the reference currently carries. */
+  id: string;
+  node: ProseMirrorNode;
+}
+
+interface DefOccurrence {
+  /** Position of the definition node in the document. */
+  pos: number;
+  /** The id the definition currently carries. */
+  id: string;
+  node: ProseMirrorNode;
+}
+
 interface FootnoteScan {
-  /** Reference ids in document order, first occurrence only, de-duplicated. */
-  referenceIds: string[];
-  /** definition id -> node (last occurrence wins, matching scan order). */
-  definitions: Map<string, ProseMirrorNode>;
+  /**
+   * Every reference occurrence in document order (NOT de-duplicated). Needed so
+   * that duplicate ids — which would otherwise be silently collapsed — can be
+   * detected and (together with their definitions) re-id'd instead of dropped.
+   */
+  refOccurrences: RefOccurrence[];
+  /**
+   * Every definition occurrence in document order (NOT de-duplicated). The old
+   * implementation used a last-wins Map here, which is exactly what caused
+   * silent data loss: two definitions sharing an id collapsed to one.
+   */
+  defOccurrences: DefOccurrence[];
   /** Every top-level footnotesList node, in document order. */
   lists: Array<{ pos: number; node: ProseMirrorNode }>;
 }
 
 function scan(doc: ProseMirrorNode): FootnoteScan {
-  const referenceIds: string[] = [];
-  const seenRefs = new Set<string>();
-  const definitions = new Map<string, ProseMirrorNode>();
+  const refOccurrences: RefOccurrence[] = [];
+  const defOccurrences: DefOccurrence[] = [];
   const lists: Array<{ pos: number; node: ProseMirrorNode }> = [];
 
   doc.descendants((node, pos) => {
     if (node.type.name === FOOTNOTE_REFERENCE_NAME) {
       const id = node.attrs.id;
-      if (id && !seenRefs.has(id)) {
-        seenRefs.add(id);
-        referenceIds.push(id);
-      }
+      if (id) refOccurrences.push({ pos, id, node });
     }
     if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
       const id = node.attrs.id;
-      if (id) definitions.set(id, node);
+      if (id) defOccurrences.push({ pos, id, node });
     }
     if (node.type.name === FOOTNOTES_LIST_NAME) {
       lists.push({ pos, node });
     }
   });
 
-  return { referenceIds, definitions, lists };
+  return { refOccurrences, defOccurrences, lists };
+}
+
+/**
+ * Result of resolving id collisions: a 1:1, de-duplicated pairing plan plus the
+ * concrete reference re-id edits that must be applied to the body so the doc no
+ * longer contains two footnotes sharing a single id.
+ *
+ * The overriding invariant is that NO definition is ever dropped here: every
+ * definition occurrence ends up with a unique id and therefore survives the
+ * canonical rebuild. Duplicate references are likewise re-id'd (and paired with
+ * a duplicate definition when one exists) so importing/pasting `[^d]` twice with
+ * two `[^d]:` definitions yields TWO distinct footnotes rather than one.
+ */
+interface CollisionPlan {
+  /**
+   * Reference ids in document order, de-duplicated AFTER re-id. This is the
+   * source of truth for definition order/numbering, exactly as before — only
+   * now collisions have been resolved so it no longer hides duplicates.
+   */
+  referenceIds: string[];
+  /** id -> definition node, after duplicates were re-id'd. One entry per id. */
+  definitions: Map<string, ProseMirrorNode>;
+  /**
+   * Body reference re-id edits to apply (position of a reference node -> the
+   * fresh id it must carry). Empty when there are no colliding references.
+   */
+  refReids: Array<{ pos: number; node: ProseMirrorNode; newId: string }>;
+  /** True when any collision required a re-id (refs and/or defs). */
+  changed: boolean;
+}
+
+/**
+ * Resolve duplicate-id collisions among references and definitions WITHOUT ever
+ * dropping a definition.
+ *
+ * Strategy:
+ *  - Walk references in document order. The FIRST reference for an id keeps it.
+ *    Any later reference sharing that id is a duplicate and gets a fresh unique
+ *    id; if a still-unclaimed duplicate definition with the original id exists,
+ *    it is re-id'd to the SAME fresh id so the (ref, def) pair stays matched.
+ *  - Walk definitions in document order. The FIRST definition for an id keeps
+ *    it; later duplicates that were not already claimed by a duplicate reference
+ *    get their own fresh unique id (surviving as a distinct footnote/orphan).
+ *
+ * Re-id determinism: every fresh id is DERIVED from document state via
+ * deriveFootnoteId (e.g. `X__2`, `X__3`, collision-bumped against the set of ids
+ * already present) — NEVER random/time-based. Because the sync plugin runs
+ * identically on every collaborating client, a deterministic re-id is the only
+ * way they can converge on the SAME ids; a random id (the previous
+ * implementation) made two clients editing the same duplicate-id document mint
+ * DIFFERENT ids for the same duplicate, causing permanent Yjs divergence.
+ */
+function resolveCollisions(scan: FootnoteScan): CollisionPlan {
+  const definitions = new Map<string, ProseMirrorNode>();
+  const refReids: Array<{
+    pos: number;
+    node: ProseMirrorNode;
+    newId: string;
+  }> = [];
+  const referenceIds: string[] = [];
+  const seenRefIds = new Set<string>();
+  let changed = false;
+
+  // `taken` is the set of every id that must be avoided when minting a derived
+  // id: all original reference + definition ids in the document PLUS every id we
+  // mint during this pass. It is pure document state, so the derivation stays
+  // deterministic across clients. Per-original occurrence counters make the k-th
+  // duplicate of `X` deterministically become `X__2`, `X__3`, ...
+  const taken = new Set<string>();
+  for (const occ of scan.refOccurrences) taken.add(occ.id);
+  for (const occ of scan.defOccurrences) taken.add(occ.id);
+  const occurrenceOf = new Map<string, number>();
+  // Mint a deterministic unique id for a duplicate of `originalId`. The first
+  // duplicate is occurrence 2 (the keeper is occurrence 1), then 3, 4, ...
+  const mintId = (originalId: string): string => {
+    const next = (occurrenceOf.get(originalId) ?? 1) + 1;
+    occurrenceOf.set(originalId, next);
+    const id = deriveFootnoteId(originalId, next, taken);
+    taken.add(id);
+    return id;
+  };
+
+  // Bucket definition occurrences by their original id so a duplicate reference
+  // can claim a matching (as-yet-unclaimed) duplicate definition and re-id the
+  // pair together. defByOriginalId[id] is consumed front-to-back.
+  const defByOriginalId = new Map<string, DefOccurrence[]>();
+  for (const occ of scan.defOccurrences) {
+    const arr = defByOriginalId.get(occ.id);
+    if (arr) arr.push(occ);
+    else defByOriginalId.set(occ.id, [occ]);
+  }
+  // The FIRST definition for each id is the canonical keeper of that id.
+  const claimed = new Set<DefOccurrence>();
+
+  for (const ref of scan.refOccurrences) {
+    if (!seenRefIds.has(ref.id)) {
+      // First reference with this id keeps it.
+      seenRefIds.add(ref.id);
+      referenceIds.push(ref.id);
+      continue;
+    }
+    // Duplicate reference: assign a deterministic derived id. Pair it with the
+    // next unclaimed duplicate definition (NOT the first keeper) carrying the
+    // same original id, if one exists, so the (ref, def) pairing is preserved
+    // 1:1.
+    const newId = mintId(ref.id);
+    refReids.push({ pos: ref.pos, node: ref.node, newId });
+    seenRefIds.add(newId);
+    referenceIds.push(newId);
+    changed = true;
+
+    const candidates = defByOriginalId.get(ref.id) ?? [];
+    // Skip the first occurrence (it keeps the original id); pick the first
+    // duplicate not already claimed.
+    for (let i = 1; i < candidates.length; i++) {
+      const cand = candidates[i];
+      if (!claimed.has(cand)) {
+        claimed.add(cand);
+        definitions.set(newId, cand.node);
+        break;
+      }
+    }
+  }
+
+  // Now place every definition under a unique id. The first occurrence of each
+  // original id keeps it; remaining duplicates either were paired with a
+  // duplicate reference above (already placed) or get a fresh standalone id.
+  const seenDefIds = new Set<string>();
+  for (const occ of scan.defOccurrences) {
+    if (claimed.has(occ)) continue; // already placed against a duplicate ref id
+    if (!seenDefIds.has(occ.id)) {
+      seenDefIds.add(occ.id);
+      definitions.set(occ.id, occ.node);
+    } else {
+      // Duplicate definition with no duplicate reference to pair with: keep it
+      // with a deterministic derived id so it is NEVER silently dropped. (It
+      // becomes an orphan and is then subject to the normal orphan policy — but
+      // only ever because it has no matching reference, never because it
+      // collided.)
+      const newId = mintId(occ.id);
+      definitions.set(newId, occ.node);
+      changed = true;
+    }
+  }
+
+  return { referenceIds, definitions, refReids, changed };
 }
 
 /**
@@ -78,9 +245,14 @@ function scan(doc: ProseMirrorNode): FootnoteScan {
  * ping-pong forever (list moved to end -> trailing paragraph appended -> list
  * no longer last -> moved again ...).
  *
- * Paste id-collision regeneration is left to the paste handler / v2; the common
- * cases (orphans, missing definitions, multiple/empty/misplaced lists) are
- * covered here.
+ * Duplicate-id collisions (two references and/or two definitions sharing one
+ * id — produced by importing `[^d]: a` / `[^d]: b`, or by pasting/duplicating a
+ * reference+definition pair) are resolved up front by resolveCollisions(): the
+ * duplicates are re-id'd to fresh unique ids so BOTH survive as distinct
+ * footnotes. This guarantees the overriding invariant — no footnoteDefinition is
+ * ever silently deleted by this automatic (addToHistory:false) transaction. A
+ * definition is only ever removed when it has NO matching reference (orphan
+ * policy), never because its id collided with another.
  */
 export function footnoteSyncPlugin(
   isRemoteTransaction?: (tr: Transaction) => boolean,
@@ -111,12 +283,33 @@ export function footnoteSyncPlugin(
 
       const info = scan(doc);
 
+      // 0) Resolve duplicate-id collisions (two references and/or two
+      //    definitions sharing one id) by re-id'ing duplicates to fresh unique
+      //    ids. This is the critical defense: the old last-wins Map silently
+      //    dropped all but the last definition for a shared id; here EVERY
+      //    definition survives with a unique id, and duplicate references are
+      //    paired with duplicate definitions so two same-id imports/pastes yield
+      //    two distinct footnotes instead of one.
+      const plan = resolveCollisions(info);
+      const referenceIds = plan.referenceIds;
+
       // 1) Desired definitions: one per referenced id, in reference order,
       //    reusing existing definition nodes (preserving their content) and
       //    synthesizing empty ones for references that lack a definition.
-      const desiredDefs: ProseMirrorNode[] = info.referenceIds.map((id) => {
-        const existing = info.definitions.get(id);
-        if (existing) return existing;
+      //    Definitions whose id has no matching reference (true orphans) are
+      //    dropped per the existing orphan policy — but a collision is NEVER the
+      //    cause of a drop, because collisions were re-id'd above.
+      const desiredDefs: ProseMirrorNode[] = referenceIds.map((id) => {
+        const existing = plan.definitions.get(id);
+        if (existing) {
+          // A definition paired to a re-id'd reference keeps its CONTENT but
+          // must carry the new id. Rewrite the id attr when it differs (cheap
+          // no-op when it already matches).
+          if (existing.attrs.id !== id) {
+            return defType.create({ id }, existing.content);
+          }
+          return existing;
+        }
         return defType.create({ id }, paragraphType.create());
       });
 
@@ -129,7 +322,12 @@ export function footnoteSyncPlugin(
         node.type === paragraphType && node.content.size === 0;
 
       let alreadyCanonical = false;
-      if (!hasRefs) {
+      if (plan.changed) {
+        // A collision was detected (duplicate ids among refs/defs). The doc must
+        // be rewritten (re-id'd references + rebuilt list); it is never already
+        // canonical in this case.
+        alreadyCanonical = false;
+      } else if (!hasRefs) {
         // Canonical when there is no footnotesList at all.
         alreadyCanonical = info.lists.length === 0;
       } else if (info.lists.length === 1) {
@@ -158,6 +356,17 @@ export function footnoteSyncPlugin(
       // 3) Rebuild: produce exactly ONE transaction that reaches the end-state.
       const tr = newState.tr;
 
+      // 3a) Re-id colliding body references FIRST. A footnoteReference is an
+      //     inline atom, so setNodeMarkup changes only its attrs (not its size),
+      //     leaving every other position valid for the list deletions/insert
+      //     that follow.
+      for (const reid of plan.refReids) {
+        tr.setNodeMarkup(reid.pos, undefined, {
+          ...reid.node.attrs,
+          id: reid.newId,
+        });
+      }
+
       // Delete every existing footnotesList (from the end so earlier positions
       // stay valid while we mutate).
       [...info.lists]
@@ -195,3 +404,101 @@ export function footnoteSyncPlugin(
     },
   });
 }
+
+export const footnotePastePluginKey = new PluginKey("footnotePaste");
+
+/**
+ * Paste id-collision guard. When pasted content carries footnote reference or
+ * definition ids that ALREADY EXIST in the current document, regenerate those
+ * ids (consistently across the pasted slice, so a pasted reference and its
+ * definition keep pointing at each other) BEFORE the slice is inserted.
+ *
+ * Without this, pasting a reference+definition pair copied from elsewhere — or
+ * duplicating one in place — would merge with (or clobber) the existing footnote
+ * of the same id. The schema-sync plugin already guarantees no definition is
+ * ever silently deleted after the fact (it re-id's collisions), but regenerating
+ * at paste time keeps the pasted footnote cleanly separate from the start and
+ * avoids any transient merge.
+ *
+ * Only COLLIDING ids are remapped: a self-paste of a lone reference whose id is
+ * not present elsewhere is left untouched (so it still resolves to its existing
+ * definition).
+ */
+export function footnotePastePlugin(): Plugin {
+  return new Plugin({
+    key: footnotePastePluginKey,
+    props: {
+      transformPasted(slice, view) {
+        // Collect ids already present in the current document.
+        const existing = new Set<string>();
+        view.state.doc.descendants((node) => {
+          if (
+            node.type.name === FOOTNOTE_REFERENCE_NAME ||
+            node.type.name === FOOTNOTE_DEFINITION_NAME
+          ) {
+            const id = node.attrs.id;
+            if (id) existing.add(id);
+          }
+        });
+        if (existing.size === 0) return slice;
+
+        // Build a remap (old id -> fresh id) for every COLLIDING id found in the
+        // pasted slice, shared by references and definitions so a pasted pair
+        // stays matched. A paste is a distinct local user action (not a
+        // shared-state convergence point), so determinism is not strictly
+        // required here — but we derive the new id deterministically anyway
+        // (deriveFootnoteId against the current doc's id set) for consistency
+        // with the sync/import paths and to keep Math.random off this code path.
+        const remap = new Map<string, string>();
+        const collectColliding = (node: ProseMirrorNode) => {
+          if (
+            node.type.name === FOOTNOTE_REFERENCE_NAME ||
+            node.type.name === FOOTNOTE_DEFINITION_NAME
+          ) {
+            const id = node.attrs.id;
+            if (id && existing.has(id) && !remap.has(id)) {
+              const newId = deriveFootnoteId(id, 2, existing);
+              remap.set(id, newId);
+              // Reserve it so a second colliding id deriving to the same base
+              // bumps instead of clashing.
+              existing.add(newId);
+            }
+          }
+          node.descendants(collectColliding);
+        };
+        slice.content.descendants(collectColliding);
+        if (remap.size === 0) return slice;
+
+        // Rewrite the colliding ids throughout the slice.
+        const rewrite = (fragment: Fragment): Fragment => {
+          const nodes: ProseMirrorNode[] = [];
+          fragment.forEach((node) => {
+            const isFootnote =
+              node.type.name === FOOTNOTE_REFERENCE_NAME ||
+              node.type.name === FOOTNOTE_DEFINITION_NAME;
+            const newId = isFootnote ? remap.get(node.attrs.id) : undefined;
+            const newContent = node.content.size
+              ? rewrite(node.content)
+              : node.content;
+            if (newId) {
+              nodes.push(
+                node.type.create(
+                  { ...node.attrs, id: newId },
+                  newContent,
+                  node.marks,
+                ),
+              );
+            } else if (newContent !== node.content) {
+              nodes.push(node.copy(newContent));
+            } else {
+              nodes.push(node);
+            }
+          });
+          return Fragment.fromArray(nodes);
+        };
+
+        return new Slice(rewrite(slice.content), slice.openStart, slice.openEnd);
+      },
+    },
+  });
+}
diff --git a/packages/editor-ext/src/lib/footnote/footnote-util.ts b/packages/editor-ext/src/lib/footnote/footnote-util.ts
index 41698686..7896595d 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-util.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-util.ts
@@ -43,6 +43,61 @@ export function generateFootnoteId(): string {
   );
 }
 
+/**
+ * Derive a DETERMINISTIC unique footnote id for the k-th (k >= 2) occurrence of
+ * an original id `X` during collision resolution. The result is a pure function
+ * of (`originalId`, `occurrence`, `taken`) so that every collaborating client —
+ * and every import path — computes the SAME new id for the same input document.
+ *
+ * CRITICAL: this MUST NOT use Math.random()/Date.now()/uuid. Two clients that
+ * each make a local edit on the same duplicate-id document have to converge on
+ * identical ids; a random id would diverge permanently over Yjs.
+ *
+ * Scheme: the base candidate is `${originalId}__${occurrence}` (e.g. `X__2`,
+ * `X__3`). If that candidate already exists in `taken` (an existing footnote id,
+ * or one we already minted in this pass), a stable alphabetic suffix is appended
+ * and bumped — `X__2b`, `X__2c`, ... — until the candidate is unique. `taken` is
+ * itself part of the document state, so the whole walk stays deterministic.
+ *
+ * `taken` is consulted but NOT mutated here; the caller adds the returned id to
+ * its own seen-set before requesting the next derived id.
+ *
+ * NOTE: this implementation is intentionally duplicated in
+ *   packages/mcp/src/lib/collaboration.ts (deriveFootnoteId)
+ * and MUST stay in sync with it so markdown imported through either path yields
+ * identical ids.
+ */
+export function deriveFootnoteId(
+  originalId: string,
+  occurrence: number,
+  taken: Set<string> | ReadonlySet<string>,
+): string {
+  let candidate = `${originalId}__${occurrence}`;
+  // Deterministic suffix bump: b, c, d, ... then aa, ab, ... if ever exhausted.
+  let n = 0;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `${originalId}__${occurrence}${suffix(n)}`;
+  }
+  return candidate;
+}
+
+/**
+ * Map 1 -> "b", 2 -> "c", ... 25 -> "z", 26 -> "ba", ... (base-25 over b..z,
+ * skipping "a" so the first bump is visibly distinct from the un-bumped base).
+ * Purely deterministic.
+ */
+function suffix(n: number): string {
+  let out = "";
+  let x = n;
+  while (x > 0) {
+    const rem = (x - 1) % 25;
+    out = String.fromCharCode(98 + rem) + out; // 98 = 'b'
+    x = Math.floor((x - 1) / 25);
+  }
+  return out;
+}
+
 /**
  * Collect every `footnoteReference` id in document order. This is the single
  * source of truth for numbering and ordering — a pure function of the document
diff --git a/packages/editor-ext/src/lib/footnote/footnote.test.ts b/packages/editor-ext/src/lib/footnote/footnote.test.ts
index a68685a3..5dfc666c 100644
--- a/packages/editor-ext/src/lib/footnote/footnote.test.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote.test.ts
@@ -304,6 +304,160 @@ describe("footnote sync plugin (orphans)", () => {
     editor.destroy();
   });
 
+  it("two definitions sharing an id (with two matching references) BOTH survive the first edit (no data loss)", () => {
+    // Reproduces the verified data-loss bug: two footnoteDefinition nodes share
+    // id "d", and there are two references with id "d". The OLD code built the
+    // definitions Map last-wins and emitted exactly one definition for the
+    // de-duplicated reference, so the very first keystroke's sync transaction
+    // deleted the whole list and rebuilt it from one definition — silently
+    // destroying "first" and keeping only "second".
+    const editor = makeEditor({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "a" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "d" } },
+            { type: "text", text: "b" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "d" } },
+          ],
+        },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "d" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "first" }] },
+              ],
+            },
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "d" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "second" }] },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    // The first local keystroke fires the sync plugin's appendTransaction.
+    editor.commands.insertContentAt(1, " ");
+
+    const doc = editor.state.doc;
+    // BOTH definitions survive.
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(2);
+    const defTexts: string[] = [];
+    const defIds: string[] = [];
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME) {
+        defIds.push(node.attrs.id);
+        defTexts.push(node.textContent);
+      }
+    });
+    // No content was lost: both "first" and "second" are still present.
+    expect(defTexts.sort()).toEqual(["first", "second"]);
+    // The colliding ids were made distinct.
+    expect(new Set(defIds).size).toBe(2);
+    // Each definition's id matches exactly one reference (1:1 pairing).
+    const refIds: string[] = [];
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_REFERENCE_NAME) refIds.push(node.attrs.id);
+    });
+    expect(refIds.sort()).toEqual(defIds.sort());
+    editor.destroy();
+  });
+
+  it("re-ids colliding duplicates DETERMINISTICALLY (two clients converge to identical ids)", () => {
+    // Cross-client determinism guard. Two collaborating clients each see the
+    // SAME duplicate-id document and each make a local edit. The sync plugin
+    // runs identically on every client, so it MUST mint the SAME new ids on both
+    // — otherwise the two clients diverge permanently over Yjs (duplicated
+    // footnotes). This is exactly the blocker the previous random-id
+    // (generateFootnoteId / Math.random) implementation caused: it would mint
+    // DIFFERENT ids on each client and this assertion would fail.
+    const duplicateDoc = {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "a" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "d" } },
+            { type: "text", text: "b" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "d" } },
+            { type: "text", text: "c" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "d" } },
+          ],
+        },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "d" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "one" }] },
+              ],
+            },
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "d" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "two" }] },
+              ],
+            },
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "d" },
+              content: [
+                {
+                  type: "paragraph",
+                  content: [{ type: "text", text: "three" }],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const idsAfterLocalEdit = () => {
+      // A fresh editor instance = an independent "client" running the same
+      // plugin pipeline on the same starting document.
+      const editor = makeEditor(structuredClone(duplicateDoc));
+      editor.commands.insertContentAt(1, " "); // local keystroke -> sync runs
+      const refIds: string[] = [];
+      const defIds: string[] = [];
+      editor.state.doc.descendants((node) => {
+        if (node.type.name === FOOTNOTE_REFERENCE_NAME)
+          refIds.push(node.attrs.id);
+        if (node.type.name === FOOTNOTE_DEFINITION_NAME)
+          defIds.push(node.attrs.id);
+      });
+      editor.destroy();
+      return { refIds, defIds };
+    };
+
+    const clientA = idsAfterLocalEdit();
+    const clientB = idsAfterLocalEdit();
+
+    // Both clients computed IDENTICAL ids (the property that makes Yjs converge).
+    expect(clientA.refIds).toEqual(clientB.refIds);
+    expect(clientA.defIds).toEqual(clientB.defIds);
+
+    // And the ids are deterministic-derived (not random uuid-style): the keeper
+    // keeps "d", the duplicates become "d__2", "d__3".
+    expect(new Set(clientA.refIds)).toEqual(new Set(["d", "d__2", "d__3"]));
+    // Every definition survived with a unique id, 1:1 with the references.
+    expect(clientA.defIds.length).toBe(3);
+    expect(new Set(clientA.defIds).size).toBe(3);
+    expect([...clientA.refIds].sort()).toEqual([...clientA.defIds].sort());
+  });
+
   it("removes an orphan definition with no matching reference", () => {
     const editor = makeEditor({
       type: "doc",
diff --git a/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts b/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
index ad47cc52..b47cf4a4 100644
--- a/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
+++ b/packages/editor-ext/src/lib/markdown/utils/footnote.marked.ts
@@ -1,4 +1,5 @@
 import { marked } from "marked";
+import { deriveFootnoteId } from "../../footnote/footnote-util";
 
 /**
  * Pandoc/GFM footnote support for the marked (Markdown -> HTML) pipeline.
@@ -52,6 +53,10 @@ function escapeAttr(value: string): string {
   return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
 
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 /**
  * Extract `[^id]: text` definition lines from the markdown body, returning the
  * cleaned body plus a rendered <section data-footnotes> (empty string when no
@@ -96,6 +101,56 @@ export function extractFootnoteDefinitions(markdown: string): {
     return { body: markdown, section: "" };
   }
 
+  // De-duplicate colliding definition ids. Two definitions sharing an id (e.g.
+  // `[^d]: first` / `[^d]: second`) would otherwise collapse into one footnote
+  // downstream (the editor's last-wins sync). Rename each colliding id to a
+  // DETERMINISTIC derived one AND rewrite the corresponding `[^id]` reference
+  // marker so the (reference, definition) pairing stays 1:1. The FIRST
+  // definition keeps the id and pairs with the FIRST `[^id]` marker; the Nth
+  // duplicate gets the derived id `${id}__${N}` and rewrites the Nth `[^id]`
+  // marker. If there are fewer markers than definitions, the surplus definition
+  // keeps a derived (orphan) id so it is never silently merged away.
+  //
+  // The id is derived (deriveFootnoteId), NOT random: importing the same
+  // markdown through two paths (here and the MCP mirror) must yield identical
+  // ids, and re-importing the same markdown twice must be stable.
+  let dedupedBody = bodyLines.join("\n");
+  // Every original definition id is reserved up front so a derived id can never
+  // collide with an unrelated original id present in the document.
+  const taken = new Set<string>(definitions.map((d) => d.id));
+  const seenDefIds = new Map<string, number>(); // original id -> how many seen
+  for (const def of definitions) {
+    const originalId = def.id;
+    const count = seenDefIds.get(originalId) ?? 0;
+    seenDefIds.set(originalId, count + 1);
+    if (count === 0) continue; // first definition keeps its id
+
+    // count is the 0-based number of PRIOR occurrences; this is occurrence
+    // (count + 1), i.e. 2 for the first duplicate, 3 for the next, ...
+    const newId = deriveFootnoteId(originalId, count + 1, taken);
+    taken.add(newId);
+    def.id = newId;
+
+    // Rewrite the NEXT still-unrewritten `[^originalId]` marker that does not
+    // belong to the keeper definition. After a prior duplicate rewrote its
+    // marker (to `[^someNewId]`), it no longer matches `[^originalId]`, so the
+    // remaining matches are: index 0 = the keeper's marker (left alone), index 1
+    // = this duplicate's marker. Rewrite index 1.
+    let occurrence = 0;
+    let rewritten = false;
+    const re = new RegExp(`\\[\\^${escapeRegExp(originalId)}\\]`, "g");
+    dedupedBody = dedupedBody.replace(re, (match) => {
+      const idx = occurrence++;
+      if (!rewritten && idx === 1) {
+        rewritten = true;
+        return `[^${newId}]`;
+      }
+      return match;
+    });
+    // If there was no second marker (more definitions than references), the
+    // duplicate simply survives as an orphan with its fresh id — no body change.
+  }
+
   const defsHtml = definitions
     .map((d) => {
       // Render the definition text as inline markdown so emphasis/links inside
@@ -109,7 +164,7 @@ export function extractFootnoteDefinitions(markdown: string): {
     .join("");
 
   return {
-    body: bodyLines.join("\n"),
+    body: dedupedBody,
     section: `<section data-footnotes>${defsHtml}</section>`,
   };
 }
diff --git a/packages/mcp/build/lib/collaboration.js b/packages/mcp/build/lib/collaboration.js
index d5e68a21..5140acee 100644
--- a/packages/mcp/build/lib/collaboration.js
+++ b/packages/mcp/build/lib/collaboration.js
@@ -271,6 +271,44 @@ const FOOTNOTE_REF_RE = /\[\^([^\]\s]+)\]/;
 function escapeFootnoteAttr(value) {
     return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
+function escapeFootnoteRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Derive a DETERMINISTIC unique footnote id for the k-th (k >= 2) occurrence of
+ * an original id `X` during definition dedup.
+ *
+ * EXACT MIRROR of editor-ext `deriveFootnoteId`
+ * (packages/editor-ext/src/lib/footnote/footnote-util.ts). These two copies MUST
+ * STAY IN SYNC: the same markdown imported through the editor and through this
+ * MCP path has to produce identical ids, and the sync plugin (which re-ids on
+ * every collaborating client) relies on the same scheme to converge. NEVER use
+ * Math.random()/Date.now()/uuid here — a random id would diverge across clients.
+ *
+ * Scheme: base candidate `${originalId}__${occurrence}` (e.g. `X__2`), bumped
+ * with a stable alphabetic suffix (`X__2b`, `X__2c`, ...) until it is not in
+ * `taken` (the set of ids already present / already minted — pure doc state).
+ */
+function deriveFootnoteId(originalId, occurrence, taken) {
+    let candidate = `${originalId}__${occurrence}`;
+    let n = 0;
+    while (taken.has(candidate)) {
+        n += 1;
+        candidate = `${originalId}__${occurrence}${footnoteSuffix(n)}`;
+    }
+    return candidate;
+}
+/** Map 1 -> "b", 2 -> "c", ... (mirror of editor-ext `suffix`). */
+function footnoteSuffix(n) {
+    let out = "";
+    let x = n;
+    while (x > 0) {
+        const rem = (x - 1) % 25;
+        out = String.fromCharCode(98 + rem) + out; // 98 = 'b'
+        x = Math.floor((x - 1) / 25);
+    }
+    return out;
+}
 const footnoteRefMarkedExtension = {
     name: "footnoteRef",
     level: "inline",
@@ -319,11 +357,43 @@ function extractFootnotes(markdown) {
     }
     if (defs.length === 0)
         return { body: markdown, section: "" };
+    // De-duplicate colliding definition ids (mirror of editor-ext
+    // extractFootnoteDefinitions). Two definitions sharing an id would otherwise
+    // collapse into one footnote downstream; rename each colliding id to a
+    // DETERMINISTIC derived one (NOT random) and rewrite the corresponding `[^id]`
+    // marker so the (reference, definition) pairing stays 1:1. Determinism lets
+    // the same markdown imported here and via the editor produce identical ids.
+    let dedupedBody = bodyLines.join("\n");
+    const taken = new Set(defs.map((d) => d.id));
+    const seenDefIds = new Map();
+    for (const def of defs) {
+        const originalId = def.id;
+        const count = seenDefIds.get(originalId) ?? 0;
+        seenDefIds.set(originalId, count + 1);
+        if (count === 0)
+            continue; // first definition keeps its id
+        const newId = deriveFootnoteId(originalId, count + 1, taken);
+        taken.add(newId);
+        def.id = newId;
+        // Remaining `[^originalId]` matches: index 0 = keeper's marker (left alone),
+        // index 1 = this duplicate's marker. Rewrite index 1.
+        let occurrence = 0;
+        let rewritten = false;
+        const re = new RegExp(`\\[\\^${escapeFootnoteRegExp(originalId)}\\]`, "g");
+        dedupedBody = dedupedBody.replace(re, (match) => {
+            const idx = occurrence++;
+            if (!rewritten && idx === 1) {
+                rewritten = true;
+                return `[^${newId}]`;
+            }
+            return match;
+        });
+    }
     const inner = defs
         .map((d) => `<div data-footnote-def data-id="${escapeFootnoteAttr(d.id)}"><p>${marked.parseInline(d.text || "")}</p></div>`)
         .join("");
     return {
-        body: bodyLines.join("\n"),
+        body: dedupedBody,
         section: `<section data-footnotes>${inner}</section>`,
     };
 }
diff --git a/packages/mcp/src/lib/collaboration.ts b/packages/mcp/src/lib/collaboration.ts
index 0e6e80a3..6f0ad011 100644
--- a/packages/mcp/src/lib/collaboration.ts
+++ b/packages/mcp/src/lib/collaboration.ts
@@ -306,6 +306,51 @@ function escapeFootnoteAttr(value: string): string {
   return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
 }
 
+function escapeFootnoteRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Derive a DETERMINISTIC unique footnote id for the k-th (k >= 2) occurrence of
+ * an original id `X` during definition dedup.
+ *
+ * EXACT MIRROR of editor-ext `deriveFootnoteId`
+ * (packages/editor-ext/src/lib/footnote/footnote-util.ts). These two copies MUST
+ * STAY IN SYNC: the same markdown imported through the editor and through this
+ * MCP path has to produce identical ids, and the sync plugin (which re-ids on
+ * every collaborating client) relies on the same scheme to converge. NEVER use
+ * Math.random()/Date.now()/uuid here — a random id would diverge across clients.
+ *
+ * Scheme: base candidate `${originalId}__${occurrence}` (e.g. `X__2`), bumped
+ * with a stable alphabetic suffix (`X__2b`, `X__2c`, ...) until it is not in
+ * `taken` (the set of ids already present / already minted — pure doc state).
+ */
+function deriveFootnoteId(
+  originalId: string,
+  occurrence: number,
+  taken: Set<string>,
+): string {
+  let candidate = `${originalId}__${occurrence}`;
+  let n = 0;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `${originalId}__${occurrence}${footnoteSuffix(n)}`;
+  }
+  return candidate;
+}
+
+/** Map 1 -> "b", 2 -> "c", ... (mirror of editor-ext `suffix`). */
+function footnoteSuffix(n: number): string {
+  let out = "";
+  let x = n;
+  while (x > 0) {
+    const rem = (x - 1) % 25;
+    out = String.fromCharCode(98 + rem) + out; // 98 = 'b'
+    x = Math.floor((x - 1) / 25);
+  }
+  return out;
+}
+
 const footnoteRefMarkedExtension = {
   name: "footnoteRef",
   level: "inline" as const,
@@ -356,6 +401,39 @@ function extractFootnotes(markdown: string): {
     else bodyLines.push(line);
   }
   if (defs.length === 0) return { body: markdown, section: "" };
+
+  // De-duplicate colliding definition ids (mirror of editor-ext
+  // extractFootnoteDefinitions). Two definitions sharing an id would otherwise
+  // collapse into one footnote downstream; rename each colliding id to a
+  // DETERMINISTIC derived one (NOT random) and rewrite the corresponding `[^id]`
+  // marker so the (reference, definition) pairing stays 1:1. Determinism lets
+  // the same markdown imported here and via the editor produce identical ids.
+  let dedupedBody = bodyLines.join("\n");
+  const taken = new Set<string>(defs.map((d) => d.id));
+  const seenDefIds = new Map<string, number>();
+  for (const def of defs) {
+    const originalId = def.id;
+    const count = seenDefIds.get(originalId) ?? 0;
+    seenDefIds.set(originalId, count + 1);
+    if (count === 0) continue; // first definition keeps its id
+    const newId = deriveFootnoteId(originalId, count + 1, taken);
+    taken.add(newId);
+    def.id = newId;
+    // Remaining `[^originalId]` matches: index 0 = keeper's marker (left alone),
+    // index 1 = this duplicate's marker. Rewrite index 1.
+    let occurrence = 0;
+    let rewritten = false;
+    const re = new RegExp(`\\[\\^${escapeFootnoteRegExp(originalId)}\\]`, "g");
+    dedupedBody = dedupedBody.replace(re, (match) => {
+      const idx = occurrence++;
+      if (!rewritten && idx === 1) {
+        rewritten = true;
+        return `[^${newId}]`;
+      }
+      return match;
+    });
+  }
+
   const inner = defs
     .map(
       (d) =>
@@ -365,7 +443,7 @@ function extractFootnotes(markdown: string): {
     )
     .join("");
   return {
-    body: bodyLines.join("\n"),
+    body: dedupedBody,
     section: `<section data-footnotes>${inner}</section>`,
   };
 }
diff --git a/packages/mcp/test/unit/footnotes.test.mjs b/packages/mcp/test/unit/footnotes.test.mjs
index 4b1ee6ab..df45a7b9 100644
--- a/packages/mcp/test/unit/footnotes.test.mjs
+++ b/packages/mcp/test/unit/footnotes.test.mjs
@@ -90,6 +90,39 @@ test("JSON -> MD -> JSON preserves footnote ids and text", async () => {
   assert.match(md2, /\[\^fn2\]: Second note\./);
 });
 
+test("duplicate-id markdown dedups DETERMINISTICALLY (same input -> same ids)", async () => {
+  // The MCP import must derive duplicate ids deterministically (NOT random) so
+  // the same markdown imported here and via the editor produces identical ids,
+  // and re-importing is stable. This is the test that would FAIL on the old
+  // Math.random()/Date.now() implementation.
+  const md = [
+    "See[^d] one[^d] two[^d].",
+    "",
+    "[^d]: first",
+    "[^d]: second",
+    "[^d]: third",
+  ].join("\n");
+
+  const idsOf = async () => {
+    const json = await markdownToProseMirror(md);
+    const refs = findAll(json, "footnoteReference").map((r) => r.attrs.id);
+    const defs = findAll(json, "footnoteDefinition").map((d) => d.attrs.id);
+    return { refs, defs };
+  };
+
+  const a = await idsOf();
+  const b = await idsOf();
+
+  // Identical across runs.
+  assert.deepEqual(a.refs, b.refs);
+  assert.deepEqual(a.defs, b.defs);
+  // Deterministic derived scheme: keeper "d", duplicates "d__2", "d__3".
+  assert.deepEqual([...a.defs].sort(), ["d", "d__2", "d__3"]);
+  // 1:1 reference <-> definition pairing, all distinct.
+  assert.equal(new Set(a.defs).size, 3);
+  assert.deepEqual([...a.refs].sort(), [...a.defs].sort());
+});
+
 test("a [^id]: line inside a fenced code block is NOT treated as a definition", async () => {
   // Markdown that DOCUMENTS footnote syntax inside a code fence. The example
   // definition line must be preserved verbatim inside the code block and not

From 587a940959acc4d1c1b5f4cc67baa6eac711f0ff Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 15:44:08 +0300
Subject: [PATCH 04/28] perf+fix(footnotes): minimal-diff sync (no
 concurrent-edit loss); cache numbering

Release-cycle review found two hardening gaps:
- The sync plugin deleted+rebuilt the WHOLE footnotesList on any reorder/orphan,
  replacing every definition's Yjs subtree -> a collaborator typing in a
  definition could lose in-flight characters on merge. Rework to targeted,
  minimal mutations: attr-only setNodeMarkup for collision re-ids, delete only
  genuine orphans, insert only genuinely-missing definitions (at the list end,
  not shifting existing subtrees), and consolidate multiple lists only in the
  abnormal paste/merge case. An unchanged (correct id, referenced) definition is
  left completely untouched. Numbering is decoration-only, so physical list order
  may drift after a reorder (accepted) while displayed numbers stay correct.
  Invariants preserved (reviewed + tested): one SYNC_META transaction, null when
  canonical (terminates), deterministic deriveFootnoteId, remote-skip -> no
  re-introduced freeze or divergence.
- computeFootnoteNumbers ran per-NodeView-render (O(n^2)/keystroke in big docs).
  The numbering plugin now caches the number map in its state (computed once per
  docChanged); NodeViews read it O(1) via getFootnoteNumber.

Tests: no-rebuild-on-reorder asserts unchanged definition node subtrees are
identity-preserved; isRemoteTransaction skip; enableSync:false read-only; cache
correctness. Browser re-smoke: insert (no freeze), number, persist across reload,
cascade delete all pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../footnote/footnote-definition-view.tsx     |   7 +-
 .../footnote/footnote-reference-view.tsx      |   9 +-
 .../src/lib/footnote/footnote-numbering.ts    |  56 +++-
 .../src/lib/footnote/footnote-sync.ts         | 284 +++++++++++++-----
 .../src/lib/footnote/footnote.test.ts         | 258 ++++++++++++++++
 5 files changed, 524 insertions(+), 90 deletions(-)

diff --git a/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx b/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
index b5aa5486..2685fbc3 100644
--- a/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
+++ b/apps/client/src/features/editor/components/footnote/footnote-definition-view.tsx
@@ -1,6 +1,6 @@
 import { NodeViewContent, NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { useTranslation } from "react-i18next";
-import { computeFootnoteNumbers } from "@docmost/editor-ext";
+import { getFootnoteNumber } from "@docmost/editor-ext";
 import classes from "./footnote.module.css";
 
 /**
@@ -13,8 +13,9 @@ export default function FootnoteDefinitionView(props: NodeViewProps) {
   const { t } = useTranslation();
   const id = node.attrs.id as string;
 
-  const numbers = computeFootnoteNumbers(editor.state.doc);
-  const number = numbers.get(id) ?? "?";
+  // Read the cached number from the numbering plugin (computed once per doc
+  // change) rather than recomputing the whole map on every render.
+  const number = getFootnoteNumber(editor.state, id) ?? "?";
 
   const handleBack = (e: React.MouseEvent) => {
     e.preventDefault();
diff --git a/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx b/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
index c75766da..7ea9e87d 100644
--- a/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
+++ b/apps/client/src/features/editor/components/footnote/footnote-reference-view.tsx
@@ -11,7 +11,7 @@ import {
 } from "@floating-ui/dom";
 import {
   FOOTNOTE_DEFINITION_NAME,
-  computeFootnoteNumbers,
+  getFootnoteNumber,
 } from "@docmost/editor-ext";
 import { ActionIcon } from "@mantine/core";
 import { IconArrowDown } from "@tabler/icons-react";
@@ -45,9 +45,10 @@ export default function FootnoteReferenceView(props: NodeViewProps) {
   const popoverRef = useRef<HTMLDivElement | null>(null);
   const [open, setOpen] = useState(false);
 
-  // Number is derived (not stored) — recompute from the current doc.
-  const numbers = computeFootnoteNumbers(editor.state.doc);
-  const number = numbers.get(id) ?? "?";
+  // Number is derived (not stored). Read it from the numbering plugin's cached
+  // map (computed once per doc change) instead of walking the whole document on
+  // every render — recomputing per NodeView per render was O(n^2) per keystroke.
+  const number = getFootnoteNumber(editor.state, id) ?? "?";
   const defText = open ? getDefinitionText(editor, id) : "";
 
   const position = useCallback(() => {
diff --git a/packages/editor-ext/src/lib/footnote/footnote-numbering.ts b/packages/editor-ext/src/lib/footnote/footnote-numbering.ts
index f93a3b08..8a487b1f 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-numbering.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-numbering.ts
@@ -1,4 +1,4 @@
-import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { EditorState, Plugin, PluginKey } from "@tiptap/pm/state";
 import { Decoration, DecorationSet } from "@tiptap/pm/view";
 import { Node as ProseMirrorNode } from "@tiptap/pm/model";
 import {
@@ -7,7 +7,23 @@ import {
   computeFootnoteNumbers,
 } from "./footnote-util";
 
-export const footnoteNumberingPluginKey = new PluginKey("footnoteNumbering");
+export const footnoteNumberingPluginKey = new PluginKey<FootnoteNumberingState>(
+  "footnoteNumbering",
+);
+
+/**
+ * Cached state of the numbering plugin. Both the displayed-number map and the
+ * decoration set are computed ONCE per doc-changing transaction (in `apply`) and
+ * cached here, so NodeViews can read a footnote's number by id without walking
+ * the whole document on every React render (which was O(n^2) per keystroke in
+ * large docs).
+ */
+interface FootnoteNumberingState {
+  /** referenceId -> 1-based display number, for the current doc. */
+  numbers: Map<string, number>;
+  /** Decorations rendering those numbers (refs + definitions). */
+  decorations: DecorationSet;
+}
 
 /**
  * Build the decoration set for footnote numbers. Pure function of the document:
@@ -18,6 +34,17 @@ export const footnoteNumberingPluginKey = new PluginKey("footnoteNumbering");
  * with no document mutation.
  */
 export function buildFootnoteDecorations(doc: ProseMirrorNode): DecorationSet {
+  return buildFootnoteNumberingState(doc).decorations;
+}
+
+/**
+ * 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.
+ */
+function buildFootnoteNumberingState(
+  doc: ProseMirrorNode,
+): FootnoteNumberingState {
   const numbers = computeFootnoteNumbers(doc);
   const decorations: Decoration[] = [];
 
@@ -46,7 +73,21 @@ export function buildFootnoteDecorations(doc: ProseMirrorNode): DecorationSet {
     }
   });
 
-  return DecorationSet.create(doc, decorations);
+  return { numbers, decorations: DecorationSet.create(doc, decorations) };
+}
+
+/**
+ * Read the cached footnote number for `id` from the numbering plugin's state.
+ * This is the source NodeViews should use instead of calling
+ * computeFootnoteNumbers() on every render (that walked the whole doc per
+ * NodeView per render = O(n^2) per keystroke). Returns undefined if the plugin
+ * is not installed or the id has no number yet.
+ */
+export function getFootnoteNumber(
+  state: EditorState,
+  id: string,
+): number | undefined {
+  return footnoteNumberingPluginKey.getState(state)?.numbers.get(id);
 }
 
 /**
@@ -59,16 +100,19 @@ export function footnoteNumberingPlugin(): Plugin {
     key: footnoteNumberingPluginKey,
     state: {
       init(_, { doc }) {
-        return buildFootnoteDecorations(doc);
+        return buildFootnoteNumberingState(doc);
       },
       apply(tr, old) {
+        // Recompute (and re-cache) only when the document actually changed, so
+        // 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;
-        return buildFootnoteDecorations(tr.doc);
+        return buildFootnoteNumberingState(tr.doc);
       },
     },
     props: {
       decorations(state) {
-        return this.getState(state);
+        return footnoteNumberingPluginKey.getState(state)?.decorations;
       },
     },
   });
diff --git a/packages/editor-ext/src/lib/footnote/footnote-sync.ts b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
index 33258590..505a60d0 100644
--- a/packages/editor-ext/src/lib/footnote/footnote-sync.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote-sync.ts
@@ -293,107 +293,237 @@ export function footnoteSyncPlugin(
       const plan = resolveCollisions(info);
       const referenceIds = plan.referenceIds;
 
-      // 1) Desired definitions: one per referenced id, in reference order,
-      //    reusing existing definition nodes (preserving their content) and
-      //    synthesizing empty ones for references that lack a definition.
-      //    Definitions whose id has no matching reference (true orphans) are
-      //    dropped per the existing orphan policy — but a collision is NEVER the
-      //    cause of a drop, because collisions were re-id'd above.
-      const desiredDefs: ProseMirrorNode[] = referenceIds.map((id) => {
-        const existing = plan.definitions.get(id);
-        if (existing) {
-          // A definition paired to a re-id'd reference keeps its CONTENT but
-          // must carry the new id. Rewrite the id attr when it differs (cheap
-          // no-op when it already matches).
-          if (existing.attrs.id !== id) {
-            return defType.create({ id }, existing.content);
-          }
-          return existing;
-        }
-        return defType.create({ id }, paragraphType.create());
-      });
+      // The set of ids that must have a definition, in reference order (after
+      // collision re-id). De-duplicated already by resolveCollisions.
+      const referenceIdSet = new Set(referenceIds);
 
-      // 2) Determine whether the document already matches the desired end-state.
-      const hasRefs = desiredDefs.length > 0;
+      // 1) For each definition occurrence, compute the id it should END UP with
+      //    (which differs from its current id only when collision resolution
+      //    re-id'd it). plan.definitions maps a FINAL id -> the chosen node, so
+      //    we invert it by node identity to recover each occurrence's target id.
+      const finalIdByNode = new Map<ProseMirrorNode, string>();
+      for (const [id, node] of plan.definitions) finalIdByNode.set(node, id);
 
-      // Is the existing single list already exactly the desired list, placed
-      // after all meaningful content (nothing but empty paragraphs after it)?
       const isEmptyParagraph = (node: ProseMirrorNode) =>
         node.type === paragraphType && node.content.size === 0;
 
-      let alreadyCanonical = false;
-      if (plan.changed) {
-        // A collision was detected (duplicate ids among refs/defs). The doc must
-        // be rewritten (re-id'd references + rebuilt list); it is never already
-        // canonical in this case.
-        alreadyCanonical = false;
-      } else if (!hasRefs) {
-        // Canonical when there is no footnotesList at all.
-        alreadyCanonical = info.lists.length === 0;
-      } else if (info.lists.length === 1) {
-        const { pos, node } = info.lists[0];
-        // Same definitions, same order, same identity (no rewrite needed)?
-        const sameDefs =
-          node.childCount === desiredDefs.length &&
-          desiredDefs.every((d, i) => node.child(i) === d);
+      // 2) Classify every existing definition occurrence:
+      //    - reId:   keep the node in place, only change its id attr (collision).
+      //    - orphan: delete it (its final id has no matching reference).
+      //    A definition that already carries the right id and is referenced is
+      //    left COMPLETELY untouched (its Yjs subtree is preserved). This is the
+      //    core of the data-loss fix: a pure reference reorder produces NO
+      //    mutation of any definition subtree.
+      interface DefReid {
+        pos: number;
+        node: ProseMirrorNode;
+        newId: string;
+      }
+      const defReids: DefReid[] = [];
+      const orphanDefs: DefOccurrence[] = [];
+      // Track which referenced ids already have a surviving (non-orphan)
+      // definition, so we can synthesize the genuinely missing ones.
+      const satisfiedIds = new Set<string>();
+      // Choose a "primary" list to receive inserts/migrated defs: the LAST list
+      // whose placement is canonical (only empty paragraphs follow it), else the
+      // last list, else none. New defs and consolidated defs land here.
+      for (const occ of info.defOccurrences) {
+        const finalId = finalIdByNode.get(occ.node) ?? occ.id;
+        if (!referenceIdSet.has(finalId)) {
+          orphanDefs.push(occ);
+          continue;
+        }
+        if (occ.id !== finalId) {
+          defReids.push({ pos: occ.pos, node: occ.node, newId: finalId });
+        }
+        satisfiedIds.add(finalId);
+      }
 
-        // Placement: only empty paragraphs may follow the list.
-        const listEnd = pos + node.nodeSize;
-        let onlyEmptyParasAfter = true;
+      // 3) Referenced ids with no surviving definition need a fresh empty one.
+      const missingIds = referenceIds.filter((id) => !satisfiedIds.has(id));
+
+      // 4) Determine list topology.
+      const hasRefs = referenceIds.length > 0;
+
+      // Pick the primary list: prefer the last canonically-placed list.
+      const listIsTrailing = (listPos: number, listNode: ProseMirrorNode) => {
+        const listEnd = listPos + listNode.nodeSize;
+        let ok = true;
         doc.nodesBetween(listEnd, doc.content.size, (child, childPos) => {
-          // Only inspect top-level children that start at/after the list end.
-          if (childPos >= listEnd && child !== node) {
-            if (!isEmptyParagraph(child)) onlyEmptyParasAfter = false;
+          if (childPos >= listEnd && child !== listNode) {
+            if (!isEmptyParagraph(child)) ok = false;
           }
           return false; // do not descend
         });
-
-        alreadyCanonical = sameDefs && onlyEmptyParasAfter;
+        return ok;
+      };
+      let primaryList: { pos: number; node: ProseMirrorNode } | null = null;
+      for (let i = info.lists.length - 1; i >= 0; i--) {
+        if (listIsTrailing(info.lists[i].pos, info.lists[i].node)) {
+          primaryList = info.lists[i];
+          break;
+        }
       }
+      if (!primaryList && info.lists.length > 0) {
+        primaryList = info.lists[info.lists.length - 1];
+      }
+      // Extra lists (everything except the primary) must be consolidated away.
+      const extraLists = info.lists.filter((l) => l !== primaryList);
+      const inExtraList = (pos: number) =>
+        extraLists.some((l) => pos > l.pos && pos < l.pos + l.node.nodeSize);
 
-      if (alreadyCanonical) return null;
+      // Definitions inside an extra list are migrated (recreated with the right
+      // id) into the primary list, so drop their in-place re-id markups — the
+      // whole extra list is deleted below and the markup would be wasted.
+      const defReidsToApply = defReids.filter((r) => !inExtraList(r.pos));
 
-      // 3) Rebuild: produce exactly ONE transaction that reaches the end-state.
+      // 5) Decide whether anything must change. The document is canonical when:
+      //    - no collisions were resolved (refs or defs), AND
+      //    - no orphan definitions, AND
+      //    - no missing definitions, AND
+      //    - exactly the right number of lists (0 when no refs, else 1) AND the
+      //      single list is canonically placed (trailing).
+      const noChangeNeeded =
+        !plan.changed &&
+        defReids.length === 0 &&
+        orphanDefs.length === 0 &&
+        missingIds.length === 0 &&
+        extraLists.length === 0 &&
+        (hasRefs
+          ? info.lists.length === 1 && primaryList !== null
+          : info.lists.length === 0);
+
+      if (noChangeNeeded) return null;
+
+      // 6) Apply the targeted, minimal mutations in ONE transaction. We never
+      //    delete-and-recreate an unchanged definition subtree; we only:
+      //      (a) re-id specific colliding references and definitions (attr-only),
+      //      (b) delete genuine orphan definitions and extra/empty lists,
+      //      (c) insert genuinely-missing empty definitions and migrate defs out
+      //          of extra lists into the primary list,
+      //      (d) create the primary list if references exist but none does yet.
       const tr = newState.tr;
 
-      // 3a) Re-id colliding body references FIRST. A footnoteReference is an
-      //     inline atom, so setNodeMarkup changes only its attrs (not its size),
-      //     leaving every other position valid for the list deletions/insert
-      //     that follow.
+      // 6a) Re-id colliding references (inline atoms: attr-only, size-stable).
       for (const reid of plan.refReids) {
-        tr.setNodeMarkup(reid.pos, undefined, {
+        tr.setNodeMarkup(tr.mapping.map(reid.pos), undefined, {
+          ...reid.node.attrs,
+          id: reid.newId,
+        });
+      }
+      // 6b) Re-id colliding definitions IN PLACE (attr-only). This preserves the
+      //     definition's content subtree — never delete+recreate it.
+      for (const reid of defReidsToApply) {
+        tr.setNodeMarkup(tr.mapping.map(reid.pos), undefined, {
           ...reid.node.attrs,
           id: reid.newId,
         });
       }
 
-      // Delete every existing footnotesList (from the end so earlier positions
-      // stay valid while we mutate).
-      [...info.lists]
-        .sort((a, b) => b.pos - a.pos)
-        .forEach(({ pos, node }) => {
-          tr.delete(pos, pos + node.nodeSize);
+      // 6c) Migrate non-orphan definitions out of every extra list into the
+      //     primary list (or, if there is no primary list, into a new one we
+      //     build), then delete the extra (now drained) lists. This is the only
+      //     path that moves a definition subtree, and it runs ONLY in the
+      //     abnormal multi-list case (paste/collab merge) — never on a plain
+      //     reorder, which keeps a single list untouched.
+      const migrated: ProseMirrorNode[] = [];
+      for (const extra of extraLists) {
+        extra.node.forEach((defChild) => {
+          if (defChild.type !== defType) return;
+          const finalId = finalIdByNode.get(defChild) ?? defChild.attrs.id;
+          if (!referenceIdSet.has(finalId)) return; // orphan: drop it
+          migrated.push(
+            defChild.attrs.id === finalId
+              ? defChild
+              : defType.create({ id: finalId }, defChild.content),
+          );
+        });
+      }
+
+      // 6c-bis) The definitions to INSERT into the primary list: migrated defs
+      //     from extra lists + freshly synthesized empty defs for references
+      //     that have no definition at all. Computed before deletions so we can
+      //     decide whether the primary list would be left empty.
+      const toInsert: ProseMirrorNode[] = [
+        ...migrated,
+        ...missingIds.map((id) =>
+          defType.create({ id }, paragraphType.create()),
+        ),
+      ];
+
+      // Does the primary list keep at least one definition after we strip its
+      // orphans AND counting the defs we are about to insert? If it ends up
+      // empty (an empty footnotesList is invalid schema), delete the WHOLE list
+      // instead of leaving a hollow shell. Only the primary list can receive
+      // inserts; extra lists are always deleted wholesale.
+      let primarySurvivors = 0;
+      if (primaryList) {
+        primaryList.node.forEach((defChild) => {
+          if (defChild.type !== defType) return;
+          const finalId = finalIdByNode.get(defChild) ?? defChild.attrs.id;
+          if (referenceIdSet.has(finalId)) primarySurvivors += 1;
+        });
+      }
+      const primaryWillBeEmpty =
+        !!primaryList && primarySurvivors === 0 && toInsert.length === 0;
+
+      // 6d) Delete orphan definitions, extra lists, and any list that would be
+      //     left empty. Sort deletions from the end so earlier positions stay
+      //     valid; map through tr.mapping to account for the (size-stable) re-id
+      //     markups and earlier deletions.
+      const deletions: Array<{ from: number; to: number }> = [];
+      const wholeListDeletes = new Set(extraLists);
+      if (primaryWillBeEmpty && primaryList) wholeListDeletes.add(primaryList);
+
+      for (const occ of orphanDefs) {
+        // Skip orphans inside a list that is being deleted wholesale.
+        const inWholeDeleted = [...wholeListDeletes].some(
+          (l) => occ.pos > l.pos && occ.pos < l.pos + l.node.nodeSize,
+        );
+        if (inWholeDeleted) continue;
+        deletions.push({ from: occ.pos, to: occ.pos + occ.node.nodeSize });
+      }
+      for (const l of wholeListDeletes) {
+        deletions.push({ from: l.pos, to: l.pos + l.node.nodeSize });
+      }
+      deletions
+        .sort((a, b) => b.from - a.from)
+        .forEach(({ from, to }) => {
+          tr.delete(tr.mapping.map(from), tr.mapping.map(to));
         });
 
-      if (hasRefs) {
-        // Insert a single canonical list holding the desired definitions. Place
-        // it after the last meaningful (non-empty-paragraph) top-level block, so
-        // it lands before any trailing empty paragraph the trailing-node plugin
-        // maintains. This keeps both plugins idempotent.
-        const mappedDoc = tr.doc;
-        let insertPos = mappedDoc.content.size;
-        for (let i = mappedDoc.childCount - 1; i >= 0; i--) {
-          const child = mappedDoc.child(i);
-          if (isEmptyParagraph(child)) {
-            // skip trailing empty paragraphs; insert before them
-            insertPos -= child.nodeSize;
-          } else {
-            break;
-          }
-        }
+      // If we deleted the primary list wholesale, it can no longer receive the
+      // inserts below — null it out so a fresh list is created when needed.
+      if (primaryWillBeEmpty) primaryList = null;
 
-        const merged = listType.create(null, Fragment.fromArray(desiredDefs));
-        tr.insert(insertPos, merged);
+      // 6e) Insert the migrated + synthesized definitions.
+      if (hasRefs) {
+        if (primaryList) {
+          if (toInsert.length > 0) {
+            // Append at the end of the (mapped) primary list, just before its
+            // closing token, so its existing definition subtrees are untouched.
+            // We only changed attrs (size-stable) and deleted OTHER nodes, so
+            // mapping the original list-end position forward lands at the same
+            // boundary; -1 puts us just inside the list's closing token.
+            const insertAt =
+              tr.mapping.map(primaryList.pos + primaryList.node.nodeSize) - 1;
+            tr.insert(insertAt, Fragment.fromArray(toInsert));
+          }
+        } else {
+          // No usable list exists yet but references do — create one holding the
+          // migrated + synthesized definitions, placed after the last meaningful
+          // (non-empty-paragraph) top-level block so it sits before any trailing
+          // empty paragraph the trailing-node plugin maintains.
+          const mappedDoc = tr.doc;
+          let insertPos = mappedDoc.content.size;
+          for (let i = mappedDoc.childCount - 1; i >= 0; i--) {
+            const child = mappedDoc.child(i);
+            if (isEmptyParagraph(child)) insertPos -= child.nodeSize;
+            else break;
+          }
+          const list = listType.create(null, Fragment.fromArray(toInsert));
+          tr.insert(insertPos, list);
+        }
       }
 
       if (!tr.docChanged) return null;
diff --git a/packages/editor-ext/src/lib/footnote/footnote.test.ts b/packages/editor-ext/src/lib/footnote/footnote.test.ts
index 5dfc666c..9ecf9a55 100644
--- a/packages/editor-ext/src/lib/footnote/footnote.test.ts
+++ b/packages/editor-ext/src/lib/footnote/footnote.test.ts
@@ -6,10 +6,13 @@ import { Text } from "@tiptap/extension-text";
 import { Superscript } from "@tiptap/extension-superscript";
 import { Plugin, PluginKey } from "@tiptap/pm/state";
 import { Node as PMNode } from "@tiptap/pm/model";
+import { EditorState } from "@tiptap/pm/state";
 import { FootnoteReference } from "./footnote-reference";
 import { FootnotesList } from "./footnotes-list";
 import { FootnoteDefinition } from "./footnote-definition";
 import { TrailingNode } from "../trailing-node";
+import { footnoteSyncPlugin } from "./footnote-sync";
+import { getFootnoteNumber } from "./footnote-numbering";
 import {
   computeFootnoteNumbers,
   collectReferenceIds,
@@ -688,3 +691,258 @@ describe("footnote sync plugin (no infinite loop — live editor)", () => {
     editor.destroy();
   });
 });
+
+/**
+ * Data-loss-window regression guard (Fix 1). A pure reference REORDER must not
+ * cause the sync plugin to delete-and-recreate any definition subtree — doing so
+ * (the previous behaviour) would, through Yjs, replace the CRDT subtree of every
+ * definition and could lose a collaborator's in-flight characters on merge.
+ *
+ * Numbering is decoration-only (footnote-numbering.ts derives numbers from
+ * reference order), so the bottom list's PHYSICAL order need not match reference
+ * order for the displayed numbers to be correct. We therefore assert: the
+ * existing definition NODE INSTANCES are preserved (identity-equal) after the
+ * sync pass, AND the derived numbers follow the new reference order.
+ */
+describe("footnote sync plugin (no rebuild on reorder — data-loss guard)", () => {
+  function reorderedDoc() {
+    // The "out of order" end-state of a reorder: references occur as [b, a] but
+    // the bottom list still physically holds definitions in [a, b] order. This
+    // is exactly the situation a reference reorder produces (decoration-only
+    // numbering keeps the displayed numbers correct without physically moving
+    // the definition subtrees). The sync plugin must leave the definitions
+    // ALONE here — no delete/recreate of any definition subtree.
+    return {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "p" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "b" } },
+            { type: "text", text: "q" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "a" } },
+          ],
+        },
+        {
+          type: FOOTNOTES_LIST_NAME,
+          content: [
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "a" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "A" }] },
+              ],
+            },
+            {
+              type: FOOTNOTE_DEFINITION_NAME,
+              attrs: { id: "b" },
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "B" }] },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  function getDefNodesById(doc: PMNode): Map<string, PMNode> {
+    const m = new Map<string, PMNode>();
+    doc.descendants((node) => {
+      if (node.type.name === FOOTNOTE_DEFINITION_NAME) m.set(node.attrs.id, node);
+    });
+    return m;
+  }
+
+  it("does NOT delete/recreate existing definition subtrees for an out-of-order list (numbers still correct)", () => {
+    const editor = makeEditor(reorderedDoc());
+
+    // Capture the exact definition NODE INSTANCES before any sync pass.
+    const before = getDefNodesById(editor.state.doc);
+    // Sanity: both carry their content right now.
+    expect(before.get("a")!.textContent).toBe("A");
+    expect(before.get("b")!.textContent).toBe("B");
+
+    // Trigger a local edit elsewhere in the body so the sync plugin runs.
+    editor.commands.insertContentAt(1, "z");
+
+    const doc = editor.state.doc;
+
+    // Reference order is [b, a]; the displayed numbers follow reference order
+    // (decoration-only numbering): b -> 1, a -> 2 — regardless of physical list
+    // order.
+    expect(collectReferenceIds(doc)).toEqual(["b", "a"]);
+    const numbers = computeFootnoteNumbers(doc);
+    expect(numbers.get("b")).toBe(1);
+    expect(numbers.get("a")).toBe(2);
+
+    // CRITICAL regression guard: both definitions still exist and are the SAME
+    // node instances as before the edit — the plugin did NOT delete/recreate the
+    // list (which would replace every definition's CRDT subtree and open the
+    // concurrent-edit data-loss window). Identity equality proves the subtree
+    // was preserved verbatim.
+    const after = getDefNodesById(doc);
+    expect(after.get("a")).toBe(before.get("a"));
+    expect(after.get("b")).toBe(before.get("b"));
+    // Content intact, exactly one list, both definitions present.
+    expect(after.get("a")!.textContent).toBe("A");
+    expect(after.get("b")!.textContent).toBe("B");
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(1);
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(2);
+
+    editor.destroy();
+  });
+});
+
+/**
+ * Sync-plugin guard paths that are awkward to exercise through a live editor:
+ * the remote-transaction skip and the enableSync:false (read-only) mode.
+ */
+describe("footnote sync plugin (guards)", () => {
+  // Build a non-canonical document (an orphan reference with no definition) so a
+  // sync pass would normally append a transaction.
+  function nonCanonicalState() {
+    const schema = getSchema(extensions);
+    const doc = PMNode.fromJSON(schema, {
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "x" },
+            { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "orphan" } },
+          ],
+        },
+      ],
+    });
+    return EditorState.create({ schema, doc });
+  }
+
+  it("isRemoteTransaction => true: appendTransaction returns null (no rebuild on remote txns)", () => {
+    // The sync plugin must SKIP remote/collab transactions so orphan cleanup and
+    // structural rewrites only ever run on local edits.
+    const plugin = footnoteSyncPlugin(() => true);
+    const state = nonCanonicalState();
+
+    // Produce a doc-changing transaction (insert a space) and feed it to the
+    // plugin's appendTransaction exactly as ProseMirror would.
+    const tr = state.tr.insertText(" ", 1);
+    const newState = state.apply(tr);
+    const result = plugin.spec.appendTransaction!(
+      [tr],
+      state,
+      newState,
+    );
+    expect(result).toBeNull();
+  });
+
+  it("isRemoteTransaction => false: appendTransaction DOES rebuild (sanity)", () => {
+    // Control: with a local (non-remote) transaction the same non-canonical doc
+    // triggers a sync transaction, proving the null above is the remote guard
+    // and not a no-op everywhere.
+    const plugin = footnoteSyncPlugin(() => false);
+    const state = nonCanonicalState();
+    const tr = state.tr.insertText(" ", 1);
+    const newState = state.apply(tr);
+    const result = plugin.spec.appendTransaction!([tr], state, newState);
+    expect(result).not.toBeNull();
+    expect(result!.docChanged).toBe(true);
+  });
+
+  it("enableSync:false: the plugin never mutates the doc (read-only viewer)", () => {
+    // Build an editor with sync disabled. An orphan reference (no definition)
+    // must NOT trigger a definition insertion — the document is left untouched.
+    const editor = new Editor({
+      extensions: [
+        Document,
+        Paragraph,
+        Text,
+        FootnoteReference.configure({ enableSync: false }),
+        FootnotesList,
+        FootnoteDefinition,
+      ],
+      content: {
+        type: "doc",
+        content: [
+          {
+            type: "paragraph",
+            content: [
+              { type: "text", text: "x" },
+              { type: FOOTNOTE_REFERENCE_NAME, attrs: { id: "orphan" } },
+            ],
+          },
+        ],
+      },
+    });
+    // A local edit that would normally trigger orphan-definition synthesis.
+    editor.commands.insertContentAt(1, "y");
+
+    const doc = editor.state.doc;
+    // No definition (and no list) was ever created — sync is disabled.
+    expect(countType(doc, FOOTNOTE_DEFINITION_NAME)).toBe(0);
+    expect(countType(doc, FOOTNOTES_LIST_NAME)).toBe(0);
+    // Numbering decorations still work: the reference is numbered 1.
+    expect(getFootnoteNumber(editor.state, "orphan")).toBe(1);
+    editor.destroy();
+  });
+});
+
+/**
+ * Numbering cache (Fix 2). NodeViews must read footnote numbers from the
+ * numbering plugin's cached map (updated once per doc change) rather than
+ * recomputing the whole map per render. We assert the cache exists, is correct,
+ * and stays current across edits.
+ */
+describe("footnote numbering cache", () => {
+  it("exposes correct numbers via getFootnoteNumber and updates on edits", () => {
+    const editor = makeEditor({
+      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" }],
+            },
+          ],
+        },
+      ],
+    });
+
+    // The cache mirrors computeFootnoteNumbers — but is read in O(1) per id.
+    expect(getFootnoteNumber(editor.state, "x")).toBe(1);
+    expect(getFootnoteNumber(editor.state, "y")).toBe(2);
+    // The cached map is the SAME values a fresh full computation would yield.
+    const fresh = computeFootnoteNumbers(editor.state.doc);
+    expect(getFootnoteNumber(editor.state, "x")).toBe(fresh.get("x"));
+    expect(getFootnoteNumber(editor.state, "y")).toBe(fresh.get("y"));
+
+    // After inserting a new earlier reference, the cache updates so the numbers
+    // shift (decoration-only numbering follows reference order).
+    editor.commands.insertContentAt(1, {
+      type: FOOTNOTE_REFERENCE_NAME,
+      attrs: { id: "z" },
+    });
+    expect(getFootnoteNumber(editor.state, "z")).toBe(1);
+    expect(getFootnoteNumber(editor.state, "x")).toBe(2);
+    expect(getFootnoteNumber(editor.state, "y")).toBe(3);
+    editor.destroy();
+  });
+});

From 859223db1a341596e32d7dd50674ff1aca43b41c Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:15:43 +0300
Subject: [PATCH 05/28] fix(page-templates): show a template marker icon in the
 page tree (#38)

Template pages were toggleable but indistinguishable in the sidebar tree.
Render an IconTemplate next to the title when node.isTemplate is true, wrapped
in a Tooltip(label='Template') with an aria-label + role='img' for AT. The
icon is a child of the row Link so clicks navigate as normal; pointer events
stay enabled so the tooltip's hover handlers fire. Adds the 'Template' i18n
key to en-US and ru-RU (other locales fall back to en-US).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../public/locales/en-US/translation.json     |  1 +
 .../public/locales/ru-RU/translation.json     |  1 +
 .../page/tree/components/space-tree-row.tsx   | 22 ++++++++++++++++++-
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/apps/client/public/locales/en-US/translation.json b/apps/client/public/locales/en-US/translation.json
index c04fc72d..651800ee 100644
--- a/apps/client/public/locales/en-US/translation.json
+++ b/apps/client/public/locales/en-US/translation.json
@@ -183,6 +183,7 @@
   "Successfully imported": "Successfully imported",
   "Successfully restored": "Successfully restored",
   "System settings": "System settings",
+  "Template": "Template",
   "Templates": "Templates",
   "Theme": "Theme",
   "To change your email, you have to enter your password and new email.": "To change your email, you have to enter your password and new email.",
diff --git a/apps/client/public/locales/ru-RU/translation.json b/apps/client/public/locales/ru-RU/translation.json
index 25ff2530..238c42fd 100644
--- a/apps/client/public/locales/ru-RU/translation.json
+++ b/apps/client/public/locales/ru-RU/translation.json
@@ -183,6 +183,7 @@
   "Successfully imported": "Успешно импортировано",
   "Successfully restored": "Успешно восстановлено",
   "System settings": "Системные настройки",
+  "Template": "Шаблон",
   "Templates": "Шаблоны",
   "Theme": "Тема",
   "To change your email, you have to enter your password and new email.": "Чтобы изменить электронную почту, вам нужно ввести пароль и новый адрес.",
diff --git a/apps/client/src/features/page/tree/components/space-tree-row.tsx b/apps/client/src/features/page/tree/components/space-tree-row.tsx
index df371498..c5c08b1c 100644
--- a/apps/client/src/features/page/tree/components/space-tree-row.tsx
+++ b/apps/client/src/features/page/tree/components/space-tree-row.tsx
@@ -2,13 +2,14 @@ import { useRef } from "react";
 import { Link, useParams } from "react-router-dom";
 import { useAtom } from "jotai";
 import { useTranslation } from "react-i18next";
-import { ActionIcon, rem } from "@mantine/core";
+import { ActionIcon, rem, Tooltip } from "@mantine/core";
 import {
   IconChevronDown,
   IconChevronRight,
   IconFileDescription,
   IconPlus,
   IconPointFilled,
+  IconTemplate,
 } from "@tabler/icons-react";
 
 import EmojiPicker from "@/components/ui/emoji-picker.tsx";
@@ -171,6 +172,25 @@ export function SpaceTreeRow({
 
       <span className={classes.text}>{node.name || t("untitled")}</span>
 
+      {node.isTemplate === true && (
+        <Tooltip label={t("Template")} withArrow>
+          <IconTemplate
+            size={14}
+            stroke={1.5}
+            // Visual-only indicator: subtle and never shrinks. Pointer events
+            // stay enabled so the Tooltip's hover handlers fire; clicks fall
+            // through to the row link since no stopPropagation is used.
+            style={{
+              flexShrink: 0,
+              marginLeft: rem(4),
+              color: "var(--mantine-color-dimmed)",
+            }}
+            aria-label={t("Template")}
+            role="img"
+          />
+        </Tooltip>
+      )}
+
       <div className={classes.actions}>
         <NodeMenu node={node} canEdit={canEdit} />
 

From c9eb495688b49c508afe423b8d77e55a436af4f6 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:21:32 +0300
Subject: [PATCH 06/28] fix(page-templates): clean up page-embed node chrome
 (#39)

Two design problems on the whole-page embed (pageEmbed) node:

- Double selection frame: the generic square cyan .ProseMirror-selectednode
  outline stacked on top of the rounded .includeWrap border. Add node-pageEmbed
  to the existing outline:none rule (already covering the transclusion nodes) so
  only the single rounded border remains.
- Redundant 'open source' controls: the floating toolbar's external-link button
  duplicated the header badge title link. Remove the toolbar button; the badge
  title is now the single way to open the source (kept Refresh + ... menu).
  Also swap the badge fallback icon IconArrowsMaximize (read as 'expand') for a
  neutral IconFileText.

Follow-ups from review: render the badge whenever the source resolves (so the
only open-source link can't vanish when title+icon are empty), and label the
link (title/aria-label) + add the 'Open source page' i18n key (en-US, ru-RU).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../public/locales/en-US/translation.json     |  1 +
 .../public/locales/ru-RU/translation.json     |  1 +
 .../components/page-embed/page-embed-view.tsx | 26 ++++++-------------
 .../transclusion/transclusion.module.css      |  3 ++-
 4 files changed, 12 insertions(+), 19 deletions(-)

diff --git a/apps/client/public/locales/en-US/translation.json b/apps/client/public/locales/en-US/translation.json
index 651800ee..0f6a1a9f 100644
--- a/apps/client/public/locales/en-US/translation.json
+++ b/apps/client/public/locales/en-US/translation.json
@@ -474,6 +474,7 @@
   "Make sub-pages public too": "Make sub-pages public too",
   "Allow search engines to index page": "Allow search engines to index page",
   "Open page": "Open page",
+  "Open source page": "Open source page",
   "Page": "Page",
   "Delete public share link": "Delete public share link",
   "Delete share": "Delete share",
diff --git a/apps/client/public/locales/ru-RU/translation.json b/apps/client/public/locales/ru-RU/translation.json
index 238c42fd..ef5d3dc7 100644
--- a/apps/client/public/locales/ru-RU/translation.json
+++ b/apps/client/public/locales/ru-RU/translation.json
@@ -472,6 +472,7 @@
   "Make sub-pages public too": "Сделать подстраницы тоже общедоступными",
   "Allow search engines to index page": "Разрешить поисковым системам индексировать страницу",
   "Open page": "Открыть страницу",
+  "Open source page": "Открыть исходную страницу",
   "Page": "Страница",
   "Delete public share link": "Удалить публичную ссылку",
   "Delete share": "Удалить общий доступ",
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
index 63890eec..707a051f 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
@@ -2,10 +2,9 @@ import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { ActionIcon, Menu, Tooltip } from "@mantine/core";
 import {
   IconAlertTriangle,
-  IconArrowsMaximize,
   IconDots,
-  IconExternalLink,
   IconEyeOff,
+  IconFileText,
   IconInfoCircle,
   IconRefresh,
   IconRepeat,
@@ -136,20 +135,6 @@ function PageEmbedBody({
           <IconRefresh size={14} />
         </ActionIcon>
       </Tooltip>
-      {sourceHref && (
-        <Tooltip label={t("Open source page")}>
-          <ActionIcon
-            component={Link}
-            to={sourceHref}
-            variant="subtle"
-            color="gray"
-            size="sm"
-            style={{ textDecoration: "none", borderBottom: "none" }}
-          >
-            <IconExternalLink size={14} />
-          </ActionIcon>
-        </Tooltip>
-      )}
       <Menu position="bottom-end" withinPortal onChange={trackOpen}>
         <Menu.Target>
           <ActionIcon variant="subtle" color="gray" size="sm">
@@ -170,13 +155,18 @@ function PageEmbedBody({
   ) : null;
 
   const header =
-    sourceTitle || sourceIcon ? (
+    // Render the badge whenever the source resolves (sourceHref), not only when
+    // it has a title/icon — the title link is now the single way to open the
+    // source, so it must not disappear when title and icon are both empty.
+    sourceTitle || sourceIcon || sourceHref ? (
       <div className={classes.transclusionBadge}>
-        {sourceIcon ? `${sourceIcon} ` : <IconArrowsMaximize size={12} />}
+        {sourceIcon ? `${sourceIcon} ` : <IconFileText size={12} />}
         {sourceHref ? (
           <Link
             to={sourceHref}
             style={{ borderBottom: "none", textDecoration: "none" }}
+            title={t("Open source page")}
+            aria-label={t("Open source page")}
           >
             {sourceTitle || t("Untitled")}
           </Link>
diff --git a/apps/client/src/features/editor/components/transclusion/transclusion.module.css b/apps/client/src/features/editor/components/transclusion/transclusion.module.css
index 4d8d321a..168da0c7 100644
--- a/apps/client/src/features/editor/components/transclusion/transclusion.module.css
+++ b/apps/client/src/features/editor/components/transclusion/transclusion.module.css
@@ -183,7 +183,8 @@
 }
 
 :global(.react-renderer.node-transclusionSource.ProseMirror-selectednode),
-:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode) {
+:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode),
+:global(.react-renderer.node-pageEmbed.ProseMirror-selectednode) {
   outline: none;
 }
 

From b8655ae52c70cf391988fc9a974fc89139421b6e Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:26:42 +0300
Subject: [PATCH 07/28] fix(page-templates): make page-embed Refresh actually
 re-render (#40)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The read-only embed renderer mounts a Tiptap EditorProvider with the looked-up
content, but Tiptap consumes the `content` option only at initial mount. After
Refresh busted the lookup cache and re-fetched fresh content, the new content
prop never reached the sub-editor, so the embed appeared not to update at all.

Key PageEmbedContent on result.sourceUpdatedAt (the source page's updatedAt,
already returned by the lookup and bumped on every persisted content change) so
the component and its EditorProvider remount and apply the refreshed content
when the source changes.

Note: server-side freshness vs. live collab edits is bounded by the 10s persist
debounce (collaboration.gateway.ts) — that separate limitation stays documented
in #40 and is out of scope here; this commit fixes the client never re-rendering.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../editor/components/page-embed/page-embed-view.tsx | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
index 707a051f..b51607db 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
@@ -214,7 +214,17 @@ function PageEmbedBody({
         sourcePageId={sourcePageId}
         hostPageId={hostPageId}
       >
-        <PageEmbedContent content={result.content} />
+        {/*
+          Tiptap's EditorProvider consumes `content` only at initial mount, so a
+          changed `content` prop (e.g. after Refresh re-fetches fresh content)
+          would not update the read-only sub-editor. Key on the source's
+          updatedAt to remount PageEmbedContent (and its inner EditorProvider)
+          whenever the source page changes, applying the refreshed content.
+        */}
+        <PageEmbedContent
+          key={result.sourceUpdatedAt}
+          content={result.content}
+        />
       </PageEmbedAncestryProvider>
     );
   } else if (result.status === "no_access") {

From a85dd607bde1e0b6b151124b2296cc6e4d7c3b89 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:29:02 +0300
Subject: [PATCH 08/28] fix(footnotes): tighten the gap between a definition's
 number and text (#44)

The footnote definition number ('1.') sat ~19px from its text because two
spacings stacked: the 1.5em (24px) marker min-width box (wider than the ~15px
glyph) plus a 10px flex gap. Reduce the flex gap to 0.4em (about one space) and
right-align the number within the 1.5em column so the period sits next to the
text and multi-digit numbers (10, 11, ...) stay aligned. Reads like '1. text'.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../editor/components/footnote/footnote.module.css         | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/apps/client/src/features/editor/components/footnote/footnote.module.css b/apps/client/src/features/editor/components/footnote/footnote.module.css
index 11c391bd..af467c5b 100644
--- a/apps/client/src/features/editor/components/footnote/footnote.module.css
+++ b/apps/client/src/features/editor/components/footnote/footnote.module.css
@@ -76,13 +76,18 @@
 .definition {
   display: flex;
   align-items: flex-start;
-  gap: var(--mantine-spacing-xs);
+  /* Tight number→text spacing (~one space) so it reads like "1. text"
+     instead of leaving a wide gap after the period. */
+  gap: 0.4em;
   padding: 2px 0;
 }
 
 .definitionMarker {
   flex: 0 0 auto;
   min-width: 1.5em;
+  /* Right-align within the narrow column so the period sits next to the text
+     and multi-digit numbers (10, 11, …) stay aligned on their right edge. */
+  text-align: right;
   font-variant-numeric: tabular-nums;
   color: var(--mantine-color-dimmed);
   user-select: none;

From 4536d27ad2834a94e945e8935e948e61452b909a Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:42:30 +0300
Subject: [PATCH 09/28] fix(page-templates): never strand a page-embed id
 in-flight (#35)

In the page-embed lookup flush(), the success branch cleared inFlightRef and
resolved waiters only for ids present in the response items. A short/partial
server response would leave a requested id stuck in inFlightRef forever (the
subscribe/refresh path is guarded by !inFlightRef.has(id)) and its refresh()
promise would never resolve. After processing returned items, also clear +
resolve any requested id that wasn't returned, mirroring the catch branch.
Cannot trigger under today's exact-mapping server contract; this is hardening.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../page-embed/page-embed-lookup-context.tsx        | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.tsx
index aa2a8caf..d29c19dc 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.tsx
@@ -55,7 +55,9 @@ export function PageEmbedLookupProvider({
 
     try {
       const { items } = await lookupTemplate({ sourcePageIds: ids });
+      const returned = new Set<string>();
       for (const r of items) {
+        returned.add(r.sourcePageId);
         resultCacheRef.current.set(r.sourcePageId, r);
         inFlightRef.current.delete(r.sourcePageId);
         const subs = subscribersRef.current.get(r.sourcePageId);
@@ -64,6 +66,17 @@ export function PageEmbedLookupProvider({
         }
         resolveWaiters(r.sourcePageId);
       }
+      // Harden against a partial/short server response: any requested id not
+      // present in `items` would otherwise stay in `inFlightRef` forever
+      // (subscribe/refresh are guarded by `!inFlightRef.has(id)`) and its
+      // refresh() promise would never resolve. Clear + resolve those ids,
+      // mirroring the catch branch, so no id can be stranded in-flight.
+      for (const id of ids) {
+        if (!returned.has(id)) {
+          inFlightRef.current.delete(id);
+          resolveWaiters(id);
+        }
+      }
     } catch (err) {
       // Surface the failure: errors must never be swallowed silently.
       console.error("[pageEmbed] template lookup failed", err);

From 22887c474a937f44163b8b986ddf3f67009057bd Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:42:30 +0300
Subject: [PATCH 10/28] chore(page-templates): tidy ts suppression in
 duplicatePage pageEmbed remap (#37)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace bare //@ts-ignore (no space, no reason) with // @ts-expect-error plus a
reason on the pageEmbed sourcePageId reassignment, matching the codebase style.
ProseMirror Attrs is read-only typed, so the reassignment genuinely errors —
@ts-expect-error is valid here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/server/src/core/page/services/page.service.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/server/src/core/page/services/page.service.ts b/apps/server/src/core/page/services/page.service.ts
index 5373801d..8e5c28b6 100644
--- a/apps/server/src/core/page/services/page.service.ts
+++ b/apps/server/src/core/page/services/page.service.ts
@@ -716,7 +716,7 @@ export class PageService {
             const sourcePageId = node.attrs.sourcePageId;
             if (sourcePageId && pageMap.has(sourcePageId)) {
               const mappedPage = pageMap.get(sourcePageId);
-              //@ts-ignore
+              // @ts-expect-error ProseMirror Attrs is read-only typed; reassigning sourcePageId to the duplicated page copy is intentional here
               node.attrs.sourcePageId = mappedPage.newPageId;
             }
           }

From a15cccf5579a2c70cfe09c92df730aafa1615326 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:42:49 +0300
Subject: [PATCH 11/28] chore(page-templates): remove dead
 findReferencePageIdsBySource (#34)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 'used in N pages' reverse-navigation method had zero callers in the merged
PR #17 — unreachable, untested code. Remove it. The reverse-navigation feature
can be (re)added with the method if/when it's actually built.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../page-template-references.repo.ts              | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts b/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
index a678422f..8493e901 100644
--- a/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
+++ b/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
@@ -22,21 +22,6 @@ export class PageTemplateReferencesRepo {
       .execute();
   }
 
-  async findReferencePageIdsBySource(
-    sourcePageId: string,
-    workspaceId: string,
-    trx?: KyselyTransaction,
-  ): Promise<string[]> {
-    const rows = await dbOrTx(this.db, trx)
-      .selectFrom('pageTemplateReferences')
-      .select('referencePageId')
-      .distinct()
-      .where('workspaceId', '=', workspaceId)
-      .where('sourcePageId', '=', sourcePageId)
-      .execute();
-    return rows.map((r) => r.referencePageId);
-  }
-
   async insertMany(
     rows: InsertablePageTemplateReference[],
     trx?: KyselyTransaction,

From 79d096ed7a091b3a7855ee9d39b9957e64fcdba5 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:42:49 +0300
Subject: [PATCH 12/28] fix(page-templates): defense-in-depth workspace checks
 (#36)

Consistency hardening from #17 review (not currently exploitable):
- toggleTemplate now explicitly rejects a page outside the caller's workspace
  (page.workspaceId !== user.workspaceId -> NotFound, avoiding existence leak)
  instead of relying solely on the space-membership model.
- PageTemplateReferencesRepo.deleteByReferenceAndSources is now workspace-scoped
  (adds a workspaceId filter + param), matching the 'scope by workspaceId
  everywhere' invariant; the sole caller threads its workspaceId.
The PAGE_TEMPLATE_THROTTLER limit is intentionally left as-is (the issue's
throttle item was 'consider only'; no change without usage data).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/core/page/transclusion/page-template.controller.ts  | 6 ++++++
 .../src/core/page/transclusion/transclusion.service.ts      | 1 +
 .../page-template-references.repo.ts                        | 3 +++
 3 files changed, 10 insertions(+)

diff --git a/apps/server/src/core/page/transclusion/page-template.controller.ts b/apps/server/src/core/page/transclusion/page-template.controller.ts
index 555a487f..db20ea42 100644
--- a/apps/server/src/core/page/transclusion/page-template.controller.ts
+++ b/apps/server/src/core/page/transclusion/page-template.controller.ts
@@ -67,6 +67,12 @@ export class PageTemplateController {
       throw new NotFoundException('Page not found');
     }
 
+    if (page.workspaceId !== user.workspaceId) {
+      // Defense-in-depth: never act on a page outside the caller's workspace.
+      // Use NotFound (not Forbidden) to avoid leaking cross-workspace existence.
+      throw new NotFoundException('Page not found');
+    }
+
     await this.pageAccessService.validateCanEdit(page, user);
 
     const isTemplate =
diff --git a/apps/server/src/core/page/transclusion/transclusion.service.ts b/apps/server/src/core/page/transclusion/transclusion.service.ts
index f8f3b464..76bb8cfb 100644
--- a/apps/server/src/core/page/transclusion/transclusion.service.ts
+++ b/apps/server/src/core/page/transclusion/transclusion.service.ts
@@ -317,6 +317,7 @@ export class TransclusionService {
     if (toDelete.length > 0) {
       await this.pageTemplateReferencesRepo.deleteByReferenceAndSources(
         referencePageId,
+        workspaceId,
         toDelete,
         trx,
       );
diff --git a/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts b/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
index 8493e901..ac358bc6 100644
--- a/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
+++ b/apps/server/src/database/repos/page-template-references/page-template-references.repo.ts
@@ -38,12 +38,15 @@ export class PageTemplateReferencesRepo {
 
   async deleteByReferenceAndSources(
     referencePageId: string,
+    workspaceId: string,
     sourcePageIds: string[],
     trx?: KyselyTransaction,
   ): Promise<void> {
     if (sourcePageIds.length === 0) return;
     await dbOrTx(this.db, trx)
       .deleteFrom('pageTemplateReferences')
+      // Defense-in-depth: scope deletes to the caller's workspace.
+      .where('workspaceId', '=', workspaceId)
       .where('referencePageId', '=', referencePageId)
       .where('sourcePageId', 'in', sourcePageIds)
       .execute();

From ada1dce73920c77a610a44c574f4562bc07ce867 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 21:57:03 +0300
Subject: [PATCH 13/28] fix(ai-chat): resolve the current page for agent
 context (#43, hardness #1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AiChatWindow derived the open page via useParams(), but it's mounted in a
pathless parent layout route where :pageSlug isn't matched, so useParams()
returned {} and openPage was ALWAYS null — the agent never received current-page
context (couldn't resolve 'this page'/'the current page'). Derive pageSlug from
useMatch('/s/:spaceSlug/p/:pageSlug') against the full pathname instead, so it
resolves regardless of where the component sits in the route tree. No-match
behavior is unchanged (undefined -> query disabled -> openPage null).

Addresses Hardness #1 of #43. Hardness #2 (proxy resilience: a get_current_page
tool / hidden user-message context so identity doesn't depend on the system
prompt surviving CLIProxyAPI) remains open.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../ai-chat/components/ai-chat-window.tsx     | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/apps/client/src/features/ai-chat/components/ai-chat-window.tsx b/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
index 1b9012c5..8e6258f3 100644
--- a/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
+++ b/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
@@ -18,7 +18,7 @@ import {
   IconX,
 } from "@tabler/icons-react";
 import { useAtom, useSetAtom } from "jotai";
-import { useParams } from "react-router-dom";
+import { useMatch } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import { useQueryClient } from "@tanstack/react-query";
 import {
@@ -140,13 +140,16 @@ export default function AiChatWindow() {
   const { data: messageRows, isLoading: messagesLoading } =
     useAiChatMessagesQuery(activeChatId ?? undefined);
 
-  // The page the user is currently viewing, derived from the route (same
-  // source the breadcrumb uses). On a non-page route `pageSlug` is undefined,
-  // so the query is disabled and `openPage` is null. This is passed to the
-  // chat thread as context so the agent knows what "this page"/"the current
-  // page" refers to; the agent still reads/writes via its CASL-enforced page
-  // tools using the id.
-  const { pageSlug } = useParams();
+  // The page the user is currently viewing. AiChatWindow lives in a pathless
+  // parent layout route, so useParams() can't see :pageSlug. Match the full
+  // pathname against the authenticated page route instead so "the current page"
+  // resolves regardless of where this component is mounted. On a non-page route
+  // the match is null, so `pageSlug` is undefined, the query is disabled and
+  // `openPage` is null. This is passed to the chat thread as context so the
+  // agent knows what "this page"/"the current page" refers to; the agent still
+  // reads/writes via its CASL-enforced page tools using the id.
+  const pageRouteMatch = useMatch("/s/:spaceSlug/p/:pageSlug");
+  const pageSlug = pageRouteMatch?.params?.pageSlug;
   const { data: openPageData } = usePageQuery({
     pageId: extractPageSlugId(pageSlug),
   });

From a6ba19f0dc1de104295ed70e29f83d142597f257 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 22:19:40 +0300
Subject: [PATCH 14/28] feat(ai-chat): add get_current_page tool for
 proxy-robust page context (#43, hardness #2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The current page id was only injected as text in the system prompt, which a
proxy (CLIProxyAPI) can rewrite/truncate, so the agent could lose track of 'this
page'. Add a getCurrentPage tool the model can call to read the open page (id +
title) from the server-side request context (forUser now takes openedPage,
threaded from body.openPage — the same value used for the system prompt). The
inline system-prompt line is kept as belt-and-suspenders. Reads/writes still go
through the CASL-enforced page tools by id, so this is strictly not worse than
the existing prompt hint — just delivered over a channel the proxy can't mangle.

User-approved on the issue. Completes #43 together with the hardness-1 fix.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/core/ai-chat/ai-chat.service.ts       |  3 +++
 .../ai-chat/tools/ai-chat-tools.service.ts    | 22 +++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/apps/server/src/core/ai-chat/ai-chat.service.ts b/apps/server/src/core/ai-chat/ai-chat.service.ts
index 4c4bc6f4..1c671bb0 100644
--- a/apps/server/src/core/ai-chat/ai-chat.service.ts
+++ b/apps/server/src/core/ai-chat/ai-chat.service.ts
@@ -257,6 +257,9 @@ export class AiChatService {
       sessionId,
       workspace.id,
       chatId,
+      // Same open-page value used by the system prompt above; exposed to the
+      // model via getCurrentPage so page identity survives prompt mangling.
+      body.openPage,
     );
 
     // Merge in admin-configured external MCP tools (web search, etc.; §6.8).
diff --git a/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts b/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts
index ef7dae56..038e2544 100644
--- a/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts
+++ b/apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts
@@ -50,6 +50,11 @@ export class AiChatToolsService {
     // agent write (REST + collab) records { actor:'agent', aiChatId } off a
     // SIGNED claim — non-spoofable, never a client body field (§6.5/§6.6).
     aiChatId: string,
+    // The page the user currently has open (from the request context), exposed
+    // to the model via getCurrentPage. Optional and last so existing callers
+    // keep compiling. Kept proxy-robust: the model can CALL for the current
+    // page instead of relying on it surviving in the system prompt text.
+    openedPage?: { id?: string; title?: string } | null,
   ): Promise<Record<string, Tool>> {
     const apiUrl =
       process.env.MCP_DOCMOST_API_URL ||
@@ -210,6 +215,23 @@ export class AiChatToolsService {
         },
       }),
 
+      getCurrentPage: tool({
+        description:
+          'Return the page the user is currently viewing — i.e. what "this page", ' +
+          '"the current page", or "here" refers to. Returns the page id and title, ' +
+          'or null if the user is not currently on a page. Call this first whenever ' +
+          'the user refers to the current page without giving an explicit id.',
+        inputSchema: z.object({}),
+        execute: async () => {
+          if (!openedPage?.id) {
+            return { page: null };
+          }
+          return {
+            page: { id: openedPage.id, title: openedPage.title ?? '' },
+          };
+        },
+      }),
+
       getPage: tool({
         description:
           'Fetch a single page as Markdown by its page id. Returns the page ' +

From 4f46f91db419536f3c45a93c4e39518c91c970fb Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 22:22:56 +0300
Subject: [PATCH 15/28] test(page-templates): fix TransclusionService spec
 constructor arity

The transclusion specs predated two added constructor params, so they failed to
compile (TS2554: expected 11 args, got 10) and the suites couldn't run. Add the
missing mock args: workspaceRepo (param 11) in the lookup/access specs, and
pageTemplateReferencesRepo (param 4, which had shifted pageRepo into the wrong
slot) in the unsync-html-embed spec. All three suites now compile and pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../core/page/transclusion/spec/page-template-access.spec.ts  | 4 +++-
 .../core/page/transclusion/spec/page-template-lookup.spec.ts  | 1 +
 .../transclusion/spec/transclusion-unsync-html-embed.spec.ts  | 1 +
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
index 3c497d80..1f16605b 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
@@ -68,6 +68,7 @@ describe('TransclusionService — template access core (real filter)', () => {
       {} as any, // attachmentRepo
       {} as any, // storageService
       {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
     return { service, db, pageRepo, spaceMemberRepo, pagePermissionRepo };
@@ -216,7 +217,8 @@ describe('TransclusionService.syncPageTemplateReferences — workspace scoping',
       {} as any,
       {} as any,
       {} as any,
-      {} as any,
+      {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
     return { service, insertMany, pageTemplateReferencesRepo };
diff --git a/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
index f62a047c..0ecd306e 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
@@ -34,6 +34,7 @@ describe('TransclusionService.lookupTemplate (access mapping)', () => {
       {} as any, // attachmentRepo
       {} as any, // storageService
       {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
     jest
diff --git a/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts b/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
index 8ad13121..4d149369 100644
--- a/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
@@ -56,6 +56,7 @@ function buildService(featureEnabled = true) {
     {} as any, // db (unused on this path)
     pageTransclusionsRepo as any,
     pageTransclusionReferencesRepo as any,
+    {} as any, // pageTemplateReferencesRepo (unused on this path)
     pageRepo as any,
     {} as any, // pagePermissionRepo (unused)
     {} as any, // spaceMemberRepo (unused)

From 98769155d3bf5efdeafdcf54286ecb92953513e9 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 22:37:35 +0300
Subject: [PATCH 16/28] test(page-templates): cover client pageEmbed
 cycle/self-embed/depth guard (#31)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cycle/self-embed/depth guard (PAGE_EMBED_MAX_DEPTH=5) lives only on the
client and is the sole protection against runaway nested rendering — and was
untested. Extract the inline predicates into pure, behavior-identical exported
helpers (isPageEmbedCycle, isPageEmbedTooDeep in the ancestry context;
filterPageEmbedOptions in the picker) so they're unit-testable without mounting
the heavy Tiptap NodeView, and add vitest coverage (20 tests): ancestry chain/
host accumulation, cycle (ancestor-in-chain + top-level self-embed), too-deep at
the cap, and picker host-exclusion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../page-embed-ancestry-context.test.tsx      | 149 ++++++++++++++++++
 .../page-embed-ancestry-context.tsx           |  23 +++
 .../page-embed/page-embed-picker.test.ts      |  44 ++++++
 .../page-embed/page-embed-picker.tsx          |  16 +-
 .../components/page-embed/page-embed-view.tsx |  14 +-
 5 files changed, 237 insertions(+), 9 deletions(-)
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-picker.test.ts

diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
new file mode 100644
index 00000000..867922d2
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
@@ -0,0 +1,149 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import {
+  PageEmbedAncestryProvider,
+  usePageEmbedAncestry,
+  isPageEmbedCycle,
+  isPageEmbedTooDeep,
+  PAGE_EMBED_MAX_DEPTH,
+} from "./page-embed-ancestry-context";
+
+/**
+ * Tiny probe that renders the current ancestry context as serialized data
+ * attributes so tests can assert the accumulated chain / threaded hostPageId
+ * without mounting the heavy Tiptap node view.
+ */
+function AncestryProbe({ testId = "probe" }: { testId?: string }) {
+  const { chain, hostPageId } = usePageEmbedAncestry();
+  return (
+    <span
+      data-testid={testId}
+      data-chain={chain.join(",")}
+      data-chain-length={String(chain.length)}
+      data-host={hostPageId ?? ""}
+    />
+  );
+}
+
+describe("PageEmbedAncestryProvider", () => {
+  it("defaults to an empty chain and null host with no provider", () => {
+    render(<AncestryProbe />);
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-chain")).toBe("");
+    expect(probe.getAttribute("data-chain-length")).toBe("0");
+    expect(probe.getAttribute("data-host")).toBe("");
+  });
+
+  it("accumulates sourcePageId into the chain across nested providers", () => {
+    render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="host">
+        <PageEmbedAncestryProvider sourcePageId="b">
+          <PageEmbedAncestryProvider sourcePageId="c">
+            <AncestryProbe />
+          </PageEmbedAncestryProvider>
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const probe = screen.getByTestId("probe");
+    // Chain is built outermost -> innermost.
+    expect(probe.getAttribute("data-chain")).toBe("a,b,c");
+    expect(probe.getAttribute("data-chain-length")).toBe("3");
+  });
+
+  it("threads the host page id from the outermost provider down the tree", () => {
+    render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="host-page">
+        <PageEmbedAncestryProvider sourcePageId="b" hostPageId="ignored">
+          <AncestryProbe />
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const probe = screen.getByTestId("probe");
+    // The first host wins (parent.hostPageId ?? hostPageId); deeper hosts are
+    // ignored so the original host is preserved for self-embed detection.
+    expect(probe.getAttribute("data-host")).toBe("host-page");
+  });
+
+  it("does not add an entry to the chain when sourcePageId is missing", () => {
+    render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="host">
+        <PageEmbedAncestryProvider sourcePageId={null}>
+          <PageEmbedAncestryProvider>
+            <AncestryProbe />
+          </PageEmbedAncestryProvider>
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const probe = screen.getByTestId("probe");
+    // null / undefined sources are pass-through: chain stays ["a"], host kept.
+    expect(probe.getAttribute("data-chain")).toBe("a");
+    expect(probe.getAttribute("data-host")).toBe("host");
+  });
+
+  it("adopts a host provided only at a deeper level when the root had none", () => {
+    render(
+      <PageEmbedAncestryProvider sourcePageId="a">
+        <PageEmbedAncestryProvider sourcePageId="b" hostPageId="late-host">
+          <AncestryProbe />
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const probe = screen.getByTestId("probe");
+    expect(probe.getAttribute("data-host")).toBe("late-host");
+  });
+});
+
+describe("isPageEmbedCycle", () => {
+  it("is false when the source is not in the chain and is not the host", () => {
+    expect(isPageEmbedCycle(["a", "b"], "host", "c")).toBe(false);
+  });
+
+  it("is true when the source is already present in the ancestor chain", () => {
+    expect(isPageEmbedCycle(["a", "b", "c"], "host", "b")).toBe(true);
+  });
+
+  it("is true for a top-level self-embed (host === source, empty chain)", () => {
+    expect(isPageEmbedCycle([], "self", "self")).toBe(true);
+  });
+
+  it("is true when the source equals the host even mid-chain", () => {
+    expect(isPageEmbedCycle(["x"], "self", "self")).toBe(true);
+  });
+
+  it("is false when there is no source id (nothing to embed yet)", () => {
+    expect(isPageEmbedCycle(["a"], "host", null)).toBe(false);
+    expect(isPageEmbedCycle([], "host", "")).toBe(false);
+  });
+
+  it("is false when host is null and source is not in the chain", () => {
+    expect(isPageEmbedCycle(["a", "b"], null, "c")).toBe(false);
+  });
+});
+
+describe("isPageEmbedTooDeep", () => {
+  it("is false below the max depth", () => {
+    expect(isPageEmbedTooDeep([])).toBe(false);
+    expect(
+      isPageEmbedTooDeep(new Array(PAGE_EMBED_MAX_DEPTH - 1).fill("x")),
+    ).toBe(false);
+  });
+
+  it("is true once the chain length reaches the max depth", () => {
+    expect(
+      isPageEmbedTooDeep(new Array(PAGE_EMBED_MAX_DEPTH).fill("x")),
+    ).toBe(true);
+  });
+
+  it("is true when the chain length exceeds the max depth", () => {
+    expect(
+      isPageEmbedTooDeep(new Array(PAGE_EMBED_MAX_DEPTH + 3).fill("x")),
+    ).toBe(true);
+  });
+
+  it("guards at exactly PAGE_EMBED_MAX_DEPTH (=5)", () => {
+    // Pin the documented constant so an accidental change is caught.
+    expect(PAGE_EMBED_MAX_DEPTH).toBe(5);
+    expect(isPageEmbedTooDeep(["1", "2", "3", "4"])).toBe(false);
+    expect(isPageEmbedTooDeep(["1", "2", "3", "4", "5"])).toBe(true);
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.tsx
index c989ee21..cdd7f109 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.tsx
@@ -51,3 +51,26 @@ export function PageEmbedAncestryProvider({
 export function usePageEmbedAncestry() {
   return useContext(PageEmbedAncestryContext);
 }
+
+/**
+ * Pure cycle predicate used by the page-embed node view. Returns true when the
+ * source page would recurse into itself: either it is already present in the
+ * ancestor chain, or it is the host page (top-level self-embed). Extracted so
+ * the anti-DoS guard can be unit-tested without mounting the Tiptap NodeView.
+ */
+export function isPageEmbedCycle(
+  chain: string[],
+  hostPageId: string | null,
+  sourcePageId: string | null,
+): boolean {
+  if (!sourcePageId) return false;
+  return chain.includes(sourcePageId) || hostPageId === sourcePageId;
+}
+
+/**
+ * Pure depth-limit predicate. Returns true once the ancestor chain has reached
+ * the hard cap, before a deeper nested editor is mounted.
+ */
+export function isPageEmbedTooDeep(chain: string[]): boolean {
+  return chain.length >= PAGE_EMBED_MAX_DEPTH;
+}
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-picker.test.ts b/apps/client/src/features/editor/components/page-embed/page-embed-picker.test.ts
new file mode 100644
index 00000000..257f09fd
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-picker.test.ts
@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { filterPageEmbedOptions } from "./page-embed-picker";
+
+type Page = { id: string; title?: string };
+
+describe("filterPageEmbedOptions", () => {
+  const pages: Page[] = [
+    { id: "p1", title: "One" },
+    { id: "host", title: "Host" },
+    { id: "p2", title: "Two" },
+  ];
+
+  it("excludes the host page from the options (self-embed guard)", () => {
+    const result = filterPageEmbedOptions(pages, "host");
+    expect(result.map((p) => p.id)).toEqual(["p1", "p2"]);
+  });
+
+  it("keeps all pages when the host id matches nothing", () => {
+    const result = filterPageEmbedOptions(pages, "other");
+    expect(result.map((p) => p.id)).toEqual(["p1", "host", "p2"]);
+  });
+
+  it("keeps all pages when no host id is provided", () => {
+    const result = filterPageEmbedOptions(pages, undefined);
+    expect(result.map((p) => p.id)).toEqual(["p1", "host", "p2"]);
+  });
+
+  it("drops nullish entries defensively", () => {
+    const dirty = [
+      { id: "p1" },
+      null as unknown as Page,
+      undefined as unknown as Page,
+      { id: "p2" },
+    ];
+    const result = filterPageEmbedOptions(dirty, "host");
+    expect(result.map((p) => p.id)).toEqual(["p1", "p2"]);
+  });
+
+  it("returns an empty array for nullish input", () => {
+    expect(
+      filterPageEmbedOptions(null as unknown as Page[], "host"),
+    ).toEqual([]);
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
index 7648b05e..5e914a57 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
@@ -9,6 +9,18 @@ import type { IPage } from "@/features/page/types/page.types";
 
 export const PAGE_EMBED_PICKER_EVENT = "open-page-embed-picker";
 
+/**
+ * Pure filter excluding the host page (and any nullish entries) from the picker
+ * results. Extracted so the self-embed guard at insertion time is unit-testable
+ * without mounting the modal/search query.
+ */
+export function filterPageEmbedOptions<T extends { id: string }>(
+  pages: T[],
+  hostPageId?: string,
+): T[] {
+  return (pages ?? []).filter((p) => p && p.id !== hostPageId);
+}
+
 type PickerDetail = {
   editor: Editor;
   range: Range;
@@ -55,9 +67,7 @@ export default function PageEmbedPicker() {
   });
 
   const hostPageId = detailRef.current?.hostPageId;
-  const pages = ((data?.pages ?? []) as IPage[]).filter(
-    (p) => p && p.id !== hostPageId,
-  );
+  const pages = filterPageEmbedOptions((data?.pages ?? []) as IPage[], hostPageId);
 
   const handleSelect = (page: IPage) => {
     const detail = detailRef.current;
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
index b51607db..a06a3063 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
@@ -20,7 +20,8 @@ import { usePageEmbedLookup } from "./page-embed-lookup-context";
 import {
   PageEmbedAncestryProvider,
   usePageEmbedAncestry,
-  PAGE_EMBED_MAX_DEPTH,
+  isPageEmbedCycle,
+  isPageEmbedTooDeep,
 } from "./page-embed-ancestry-context";
 import PageEmbedContent from "./page-embed-content";
 
@@ -100,11 +101,12 @@ function PageEmbedBody({
 
   // --- Cycle / depth guard (evaluated before any lookup is rendered) ---------
   // Self-embed or a source already present in the ancestor chain → cycle.
-  const isCycle =
-    !!sourcePageId &&
-    (ancestry.chain.includes(sourcePageId) ||
-      ancestry.hostPageId === sourcePageId);
-  const isTooDeep = ancestry.chain.length >= PAGE_EMBED_MAX_DEPTH;
+  const isCycle = isPageEmbedCycle(
+    ancestry.chain,
+    ancestry.hostPageId,
+    sourcePageId,
+  );
+  const isTooDeep = isPageEmbedTooDeep(ancestry.chain);
 
   const sourceTitle =
     result && !("status" in result) ? result.title : null;

From bc1ea792f554f745a19d2011678348bfdff83da5 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 22:37:35 +0300
Subject: [PATCH 17/28] test(page-templates): cover duplicatePage pageEmbed
 remap + reference sync (#32)

Extract the per-node pageEmbed remap decision into a shared pure helper
(remapPageEmbedSourceId) and use it BOTH in PageService.duplicatePage and the
JSON walker, so the test guards the real production path (not a mirror that
could drift). Behavior is identical: source in the copied set -> new copy id;
otherwise keep the original. Add jest coverage (16 tests): the remap helper
(in-set/out-of-set/null/nested), syncPageTemplateReferences toDelete (stale refs
removed with the right workspaceId), and insertTemplateReferencesForPages
multi-workspace grouping/filtering.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/core/page/services/page.service.ts    |  12 +-
 .../spec/page-embed-remap.util.spec.ts        | 200 +++++++++++
 .../page-template-references-sync.spec.ts     | 310 ++++++++++++++++++
 .../utils/transclusion-prosemirror.util.ts    |  58 ++++
 4 files changed, 574 insertions(+), 6 deletions(-)
 create mode 100644 apps/server/src/core/page/transclusion/spec/page-embed-remap.util.spec.ts
 create mode 100644 apps/server/src/core/page/transclusion/spec/page-template-references-sync.spec.ts

diff --git a/apps/server/src/core/page/services/page.service.ts b/apps/server/src/core/page/services/page.service.ts
index 8e5c28b6..dc17e188 100644
--- a/apps/server/src/core/page/services/page.service.ts
+++ b/apps/server/src/core/page/services/page.service.ts
@@ -62,6 +62,7 @@ import { markdownToHtml } from '@docmost/editor-ext';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
 import { TransclusionService } from '../transclusion/transclusion.service';
+import { remapPageEmbedSourceId } from '../transclusion/utils/transclusion-prosemirror.util';
 import { AuthProvenanceData } from '../../../common/decorators/auth-provenance.decorator';
 
 @Injectable()
@@ -713,12 +714,11 @@ export class PageService {
           // source page is also part of the copied set, point at its new copy;
           // otherwise leave it pointing at the original (live embed of original).
           if (node.type.name === 'pageEmbed') {
-            const sourcePageId = node.attrs.sourcePageId;
-            if (sourcePageId && pageMap.has(sourcePageId)) {
-              const mappedPage = pageMap.get(sourcePageId);
-              // @ts-expect-error ProseMirror Attrs is read-only typed; reassigning sourcePageId to the duplicated page copy is intentional here
-              node.attrs.sourcePageId = mappedPage.newPageId;
-            }
+            // @ts-expect-error ProseMirror Attrs is read-only typed; intentional remap to the duplicated copy
+            node.attrs.sourcePageId = remapPageEmbedSourceId(
+              node.attrs.sourcePageId,
+              (id) => pageMap.get(id)?.newPageId,
+            );
           }
 
           // Update internal page links in link marks
diff --git a/apps/server/src/core/page/transclusion/spec/page-embed-remap.util.spec.ts b/apps/server/src/core/page/transclusion/spec/page-embed-remap.util.spec.ts
new file mode 100644
index 00000000..47fa46c4
--- /dev/null
+++ b/apps/server/src/core/page/transclusion/spec/page-embed-remap.util.spec.ts
@@ -0,0 +1,200 @@
+import {
+  remapPageEmbedSourceId,
+  remapPageEmbedSourceIds,
+} from '../utils/transclusion-prosemirror.util';
+
+/**
+ * Unit tests for the `pageEmbed` remap used by `PageService.duplicatePage`:
+ *
+ *   - source page within the copied set  -> rewrite to the COPY's new id
+ *   - source page NOT in the copied set   -> keep the ORIGINAL id (live embed)
+ *
+ * `remapPageEmbedSourceId` is the per-node decision the production
+ * `duplicatePage` callback now calls directly, so these tests guard the real
+ * path rather than a parallel copy. `remapPageEmbedSourceIds` is the JSON
+ * walker that delegates to the same helper; its tests exercise the shared
+ * decision transitively across nested ProseMirror containers.
+ */
+describe('remapPageEmbedSourceId (shared per-node decision used by duplicatePage)', () => {
+  it('returns the new copy id when the source IS in the copied set', () => {
+    const idMap = new Map([['old-src', 'new-copy']]);
+
+    const out = remapPageEmbedSourceId('old-src', (id) => idMap.get(id));
+
+    expect(out).toBe('new-copy');
+  });
+
+  it('returns the original id when the source is NOT in the copied set', () => {
+    const idMap = new Map([['old-src', 'new-copy']]);
+
+    const out = remapPageEmbedSourceId('external', (id) => idMap.get(id));
+
+    expect(out).toBe('external');
+  });
+
+  it('returns the original id when resolveNewId yields undefined', () => {
+    const out = remapPageEmbedSourceId('some-id', () => undefined);
+
+    expect(out).toBe('some-id');
+  });
+
+  it('leaves a null source unchanged without consulting the resolver', () => {
+    const resolve = jest.fn(() => 'should-not-be-used');
+
+    const out = remapPageEmbedSourceId(null, resolve);
+
+    expect(out).toBeNull();
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it('leaves an undefined source unchanged without consulting the resolver', () => {
+    const resolve = jest.fn(() => 'should-not-be-used');
+
+    const out = remapPageEmbedSourceId(undefined, resolve);
+
+    expect(out).toBeUndefined();
+    expect(resolve).not.toHaveBeenCalled();
+  });
+});
+
+describe('remapPageEmbedSourceIds (duplicatePage pageEmbed remap)', () => {
+  const docWithEmbeds = (ids: string[]) => ({
+    type: 'doc',
+    content: ids.map((id) => ({
+      type: 'pageEmbed',
+      attrs: { sourcePageId: id },
+    })),
+  });
+
+  it('remaps a source that IS within the copied set to its new copy id', () => {
+    const doc = docWithEmbeds(['old-src']);
+    const idMap = new Map([['old-src', 'new-copy']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap);
+
+    expect(out.content[0].attrs.sourcePageId).toBe('new-copy');
+  });
+
+  it('keeps the original id for a source NOT in the copied set', () => {
+    const doc = docWithEmbeds(['external']);
+    const idMap = new Map([['old-src', 'new-copy']]); // does not contain "external"
+
+    const out = remapPageEmbedSourceIds(doc, idMap);
+
+    expect(out.content[0].attrs.sourcePageId).toBe('external');
+  });
+
+  it('handles a mixed doc: in-set remapped, out-of-set preserved', () => {
+    const doc = docWithEmbeds(['in-set', 'external']);
+    const idMap = new Map([['in-set', 'in-set-copy']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap);
+
+    expect(out.content.map((n: any) => n.attrs.sourcePageId)).toEqual([
+      'in-set-copy',
+      'external',
+    ]);
+  });
+
+  it('remaps pageEmbeds nested inside columns', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'columnList',
+          content: [
+            {
+              type: 'column',
+              content: [
+                { type: 'pageEmbed', attrs: { sourcePageId: 'nested-in' } },
+              ],
+            },
+            {
+              type: 'column',
+              content: [
+                { type: 'pageEmbed', attrs: { sourcePageId: 'nested-out' } },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    const idMap = new Map([['nested-in', 'nested-in-copy']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap) as any;
+
+    const col0 = out.content[0].content[0].content[0];
+    const col1 = out.content[0].content[1].content[0];
+    expect(col0.attrs.sourcePageId).toBe('nested-in-copy');
+    expect(col1.attrs.sourcePageId).toBe('nested-out');
+  });
+
+  it('remaps pageEmbeds nested inside a callout', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          content: [
+            { type: 'pageEmbed', attrs: { sourcePageId: 'in-callout' } },
+          ],
+        },
+      ],
+    };
+    const idMap = new Map([['in-callout', 'in-callout-copy']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap) as any;
+
+    expect(out.content[0].content[0].attrs.sourcePageId).toBe(
+      'in-callout-copy',
+    );
+  });
+
+  it('does not descend into a transclusionSource (schema-isolated)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'src' },
+          content: [
+            { type: 'pageEmbed', attrs: { sourcePageId: 'hidden' } },
+          ],
+        },
+      ],
+    };
+    const idMap = new Map([['hidden', 'should-not-apply']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap) as any;
+
+    // The embed inside a source must be left untouched.
+    expect(out.content[0].content[0].attrs.sourcePageId).toBe('hidden');
+  });
+
+  it('leaves embeds missing a sourcePageId untouched', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'pageEmbed', attrs: {} },
+        { type: 'pageEmbed', attrs: { sourcePageId: '' } },
+      ],
+    };
+    const idMap = new Map([['', 'x']]);
+
+    const out = remapPageEmbedSourceIds(doc, idMap) as any;
+
+    expect(out.content[0].attrs.sourcePageId).toBeUndefined();
+    expect(out.content[1].attrs.sourcePageId).toBe('');
+  });
+
+  it('returns the doc unchanged when idMap is empty', () => {
+    const doc = docWithEmbeds(['a', 'b']);
+
+    const out = remapPageEmbedSourceIds(doc, new Map());
+
+    expect(out.content.map((n: any) => n.attrs.sourcePageId)).toEqual([
+      'a',
+      'b',
+    ]);
+  });
+});
diff --git a/apps/server/src/core/page/transclusion/spec/page-template-references-sync.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-references-sync.spec.ts
new file mode 100644
index 00000000..4afad554
--- /dev/null
+++ b/apps/server/src/core/page/transclusion/spec/page-template-references-sync.spec.ts
@@ -0,0 +1,310 @@
+import { TransclusionService } from '../transclusion.service';
+
+/**
+ * Covers two untested, high-risk write paths around `page_template_references`:
+ *
+ *  1. `syncPageTemplateReferences` — the `toDelete` branch: stale references are
+ *     removed when the host page no longer embeds a source, while genuinely new
+ *     embeds are inserted. We assert `deleteByReferenceAndSources` /  `insertMany`
+ *     receive the correct rows and the returned `{ inserted, deleted }` counts.
+ *
+ *  2. `insertTemplateReferencesForPages` — the multi-workspace grouping/filtering
+ *     branch: candidate source ids are grouped per workspace, each workspace is
+ *     validated independently, and cross-workspace sources are dropped.
+ *
+ * Setup/mocking mirrors the existing transclusion specs (page-template-access /
+ * page-template-lookup): `new TransclusionService(...)` is built with the same
+ * 11 positional mock args; only the deps each test touches are real stubs.
+ */
+
+/**
+ * Chainable kysely `db` stub used by `filterInWorkspaceSourceIds`. Every
+ * `selectFrom(...).select(...).where(...)` returns the same builder; `.execute()`
+ * resolves whatever rows the per-call resolver returns. The resolver receives
+ * the captured `where('id','in', <ids>)` and `where('workspaceId','=', ws)`
+ * arguments so a test can decide, per workspace, which ids "exist".
+ */
+function makeWorkspaceScopedDb(
+  resolve: (ids: string[], workspaceId: string) => string[],
+) {
+  const state = { ids: [] as string[], workspaceId: '' };
+  const builder: any = {};
+  builder.selectFrom = jest.fn(() => builder);
+  builder.select = jest.fn(() => builder);
+  builder.where = jest.fn((col: string, _op: string, val: any) => {
+    if (col === 'id') state.ids = val as string[];
+    if (col === 'workspaceId') state.workspaceId = val as string;
+    return builder;
+  });
+  builder.execute = jest.fn(async () =>
+    resolve(state.ids, state.workspaceId).map((id) => ({ id })),
+  );
+  return builder;
+}
+
+function buildService(opts: {
+  db: any;
+  pageTemplateReferencesRepo: any;
+}) {
+  return new TransclusionService(
+    opts.db,
+    {} as any, // pageTransclusionsRepo
+    {} as any, // pageTransclusionReferencesRepo
+    opts.pageTemplateReferencesRepo,
+    {} as any, // pageRepo
+    {} as any, // pagePermissionRepo
+    {} as any, // spaceMemberRepo
+    {} as any, // attachmentRepo
+    {} as any, // storageService
+    {} as any, // pageAccessService
+    {} as any, // workspaceRepo
+  );
+}
+
+const pageEmbedDoc = (sourceIds: string[]) => ({
+  type: 'doc',
+  content: sourceIds.map((id) => ({
+    type: 'pageEmbed',
+    attrs: { sourcePageId: id },
+  })),
+});
+
+describe('TransclusionService.syncPageTemplateReferences — toDelete branch', () => {
+  it('deletes stale references and inserts new ones with correct args/counts', async () => {
+    // Every candidate id is treated as in-workspace by the existence query.
+    const db = makeWorkspaceScopedDb((ids) => ids);
+
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const deleteByReferenceAndSources = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = {
+      // existing refs: "keep" stays embedded, "stale-a"/"stale-b" no longer are
+      findByReferencePageId: jest.fn().mockResolvedValue([
+        { sourcePageId: 'keep' },
+        { sourcePageId: 'stale-a' },
+        { sourcePageId: 'stale-b' },
+      ]),
+      insertMany,
+      deleteByReferenceAndSources,
+    };
+
+    const service = buildService({ db, pageTemplateReferencesRepo });
+
+    // host now embeds: keep (unchanged) + fresh (new). stale-a/stale-b gone.
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      pageEmbedDoc(['keep', 'fresh']),
+    );
+
+    expect(result).toEqual({ inserted: 1, deleted: 2 });
+
+    // only the genuinely new embed is inserted (keep already existed)
+    expect(insertMany).toHaveBeenCalledTimes(1);
+    expect(insertMany.mock.calls[0][0]).toEqual([
+      { workspaceId: 'w1', referencePageId: 'host', sourcePageId: 'fresh' },
+    ]);
+
+    // stale references removed, scoped to host + workspace
+    expect(deleteByReferenceAndSources).toHaveBeenCalledTimes(1);
+    const [refPageId, workspaceId, staleSources] =
+      deleteByReferenceAndSources.mock.calls[0];
+    expect(refPageId).toBe('host');
+    expect(workspaceId).toBe('w1');
+    expect([...staleSources].sort()).toEqual(['stale-a', 'stale-b']);
+  });
+
+  it('deletes ALL existing references when the host embeds nothing anymore', async () => {
+    const db = makeWorkspaceScopedDb((ids) => ids);
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const deleteByReferenceAndSources = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = {
+      findByReferencePageId: jest
+        .fn()
+        .mockResolvedValue([{ sourcePageId: 'a' }, { sourcePageId: 'b' }]),
+      insertMany,
+      deleteByReferenceAndSources,
+    };
+
+    const service = buildService({ db, pageTemplateReferencesRepo });
+
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      pageEmbedDoc([]), // no embeds left
+    );
+
+    expect(result).toEqual({ inserted: 0, deleted: 2 });
+    expect(insertMany).not.toHaveBeenCalled();
+    const [, , staleSources] = deleteByReferenceAndSources.mock.calls[0];
+    expect([...staleSources].sort()).toEqual(['a', 'b']);
+  });
+
+  it('treats a cross-workspace embed as stale: it never survives to be kept', async () => {
+    // existence query drops "cross-ws"; so an existing ref to it must be deleted
+    const db = makeWorkspaceScopedDb((ids) => ids.filter((id) => id !== 'cross-ws'));
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const deleteByReferenceAndSources = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = {
+      findByReferencePageId: jest
+        .fn()
+        .mockResolvedValue([{ sourcePageId: 'cross-ws' }]),
+      insertMany,
+      deleteByReferenceAndSources,
+    };
+
+    const service = buildService({ db, pageTemplateReferencesRepo });
+
+    // host still "embeds" cross-ws in its doc, but it is not in-workspace
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      pageEmbedDoc(['cross-ws']),
+    );
+
+    expect(result).toEqual({ inserted: 0, deleted: 1 });
+    expect(insertMany).not.toHaveBeenCalled();
+    const [, , staleSources] = deleteByReferenceAndSources.mock.calls[0];
+    expect([...staleSources]).toEqual(['cross-ws']);
+  });
+
+  it('no-ops both repos when desired and existing already match', async () => {
+    const db = makeWorkspaceScopedDb((ids) => ids);
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const deleteByReferenceAndSources = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = {
+      findByReferencePageId: jest
+        .fn()
+        .mockResolvedValue([{ sourcePageId: 'same' }]),
+      insertMany,
+      deleteByReferenceAndSources,
+    };
+
+    const service = buildService({ db, pageTemplateReferencesRepo });
+
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      pageEmbedDoc(['same']),
+    );
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(insertMany).not.toHaveBeenCalled();
+    expect(deleteByReferenceAndSources).not.toHaveBeenCalled();
+  });
+});
+
+describe('TransclusionService.insertTemplateReferencesForPages — multi-workspace grouping', () => {
+  it('groups candidates per workspace and validates each workspace independently', async () => {
+    // Each workspace "owns" only its own source ids. The existence query is
+    // workspace-scoped, so an id from another workspace is dropped.
+    const owned: Record<string, string[]> = {
+      w1: ['s1'],
+      w2: ['s2'],
+    };
+    const executeArgs: Array<{ ids: string[]; workspaceId: string }> = [];
+    const db = makeWorkspaceScopedDb((ids, workspaceId) => {
+      executeArgs.push({ ids: [...ids], workspaceId });
+      const ownedSet = new Set(owned[workspaceId] ?? []);
+      return ids.filter((id) => ownedSet.has(id));
+    });
+
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = { insertMany };
+
+    const service = buildService({ db, pageTemplateReferencesRepo });
+
+    // page-a in w1 embeds s1 (valid) + s2 (belongs to w2 -> dropped)
+    // page-b in w2 embeds s2 (valid)
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'page-a', workspaceId: 'w1', content: pageEmbedDoc(['s1', 's2']) },
+      { id: 'page-b', workspaceId: 'w2', content: pageEmbedDoc(['s2']) },
+    ]);
+
+    expect(result).toEqual({ inserted: 2 });
+
+    expect(insertMany).toHaveBeenCalledTimes(1);
+    const rows = insertMany.mock.calls[0][0];
+    expect(rows).toEqual([
+      { workspaceId: 'w1', referencePageId: 'page-a', sourcePageId: 's1' },
+      { workspaceId: 'w2', referencePageId: 'page-b', sourcePageId: 's2' },
+    ]);
+
+    // one existence query per workspace, each scoped to that workspace's candidates
+    expect(executeArgs).toHaveLength(2);
+    const w1Call = executeArgs.find((c) => c.workspaceId === 'w1');
+    const w2Call = executeArgs.find((c) => c.workspaceId === 'w2');
+    expect(w1Call?.ids.sort()).toEqual(['s1', 's2']);
+    expect(w2Call?.ids).toEqual(['s2']);
+  });
+
+  it('drops every cross-workspace source and inserts nothing when none are in-workspace', async () => {
+    // No id is owned by its page's workspace -> all filtered out.
+    const db = makeWorkspaceScopedDb(() => []);
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const service = buildService({
+      db,
+      pageTemplateReferencesRepo: { insertMany },
+    });
+
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'page-a', workspaceId: 'w1', content: pageEmbedDoc(['x']) },
+      { id: 'page-b', workspaceId: 'w2', content: pageEmbedDoc(['y']) },
+    ]);
+
+    expect(result).toEqual({ inserted: 0 });
+    expect(insertMany).not.toHaveBeenCalled();
+  });
+
+  it('dedupes a sourceId shared by two pages in the same workspace into one validation', async () => {
+    const executeArgs: Array<{ ids: string[]; workspaceId: string }> = [];
+    const db = makeWorkspaceScopedDb((ids, workspaceId) => {
+      executeArgs.push({ ids: [...ids], workspaceId });
+      return ids; // all in-workspace
+    });
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const service = buildService({
+      db,
+      pageTemplateReferencesRepo: { insertMany },
+    });
+
+    // both pages embed the same source "shared" in w1
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'page-a', workspaceId: 'w1', content: pageEmbedDoc(['shared']) },
+      { id: 'page-b', workspaceId: 'w1', content: pageEmbedDoc(['shared']) },
+    ]);
+
+    // a row per (page, source) pair, but only one existence query for w1
+    expect(result).toEqual({ inserted: 2 });
+    expect(executeArgs).toHaveLength(1);
+    expect(executeArgs[0]).toEqual({ ids: ['shared'], workspaceId: 'w1' });
+
+    const rows = insertMany.mock.calls[0][0];
+    expect(rows).toEqual([
+      { workspaceId: 'w1', referencePageId: 'page-a', sourcePageId: 'shared' },
+      { workspaceId: 'w1', referencePageId: 'page-b', sourcePageId: 'shared' },
+    ]);
+  });
+
+  it('returns inserted:0 without querying when no page has embeds', async () => {
+    const execute = jest.fn();
+    const db = makeWorkspaceScopedDb(() => {
+      execute();
+      return [];
+    });
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const service = buildService({
+      db,
+      pageTemplateReferencesRepo: { insertMany },
+    });
+
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'page-a', workspaceId: 'w1', content: pageEmbedDoc([]) },
+    ]);
+
+    expect(result).toEqual({ inserted: 0 });
+    expect(insertMany).not.toHaveBeenCalled();
+    // filterInWorkspaceSourceIds short-circuits on empty candidates, so the
+    // existence query never runs.
+    expect(execute).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts b/apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts
index eeeea0e2..d8cdf3bf 100644
--- a/apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts
+++ b/apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts
@@ -99,6 +99,64 @@ export function collectReferencesFromPmJson(
   return out;
 }
 
+/**
+ * Decide the sourcePageId a duplicated pageEmbed should point to: the copy's new
+ * id when the embedded source is part of the copied set, otherwise the original
+ * (a live embed of the original page). Pure — shared by PageService.duplicatePage
+ * (the real path) and the JSON walker below, so both stay in lockstep.
+ */
+export function remapPageEmbedSourceId(
+  sourcePageId: string | null | undefined,
+  resolveNewId: (id: string) => string | undefined,
+): string | null | undefined {
+  if (sourcePageId) {
+    const mapped = resolveNewId(sourcePageId);
+    if (mapped) return mapped;
+  }
+  return sourcePageId;
+}
+
+/**
+ * Remap the `sourcePageId` of every `pageEmbed` node in a ProseMirror JSON doc
+ * according to `idMap` (old page id -> new page id). Delegates the per-node
+ * decision to the shared `remapPageEmbedSourceId` helper that
+ * `PageService.duplicatePage` also uses, so the production path and this walker
+ * stay in lockstep: when the embedded source page is part of the copied set
+ * (present in `idMap`) the embed is pointed at its new copy; otherwise the
+ * original `sourcePageId` is preserved so it stays a live embed of the original
+ * page. Mutates `doc` in place (and returns it) to match the service's in-place
+ * ProseMirror mutation. Recurses through arbitrary block containers (columns,
+ * callouts, etc.) the same way the collectors do, but does NOT descend into a
+ * `transclusionSource` (schema-isolated).
+ */
+export function remapPageEmbedSourceIds<T>(
+  doc: T,
+  idMap: Map<string, string>,
+): T {
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === PAGE_EMBED_TYPE) {
+      if (node.attrs) {
+        node.attrs.sourcePageId = remapPageEmbedSourceId(
+          node.attrs.sourcePageId,
+          (id) => idMap.get(id),
+        );
+      }
+      return; // atom node - no children
+    }
+
+    if (node.type === TRANSCLUSION_TYPE) return;
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(doc);
+  return doc;
+}
+
 /**
  * Walks a ProseMirror JSON document and returns one snapshot per unique
  * `sourcePageId` found on `pageEmbed` nodes (whole-page live embeds). Order

From 39f3eacf897e1365c89e8ef18bf4854c3d2f3ae5 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 22:37:35 +0300
Subject: [PATCH 18/28] test(page-templates): cover lookupTemplate anti-leak +
 edge cases (#33)

- The security-relevant catch->not_found branch in lookupTemplate (returns
  not_found instead of raw content when comment-mark stripping throws) is now
  tested by forcing the strip to throw with a malformed text node, asserting no
  content/marks leak.
- not_found for a soft-deleted source resolved through the REAL
  filterViewerAccessiblePageIds (deletedAt-excluded), not the stubbed filter.
- Rename the misleading 'honours <=50 cap' test to reflect it only exercises
  dedup (the cap lives in the DTO, never engaged in the service unit).
- Cover the onlyTemplates search filter (restricts to is_template=true).
Also fix two pre-existing failing 'should be defined' specs (search service +
controller) that couldn't resolve the @InjectKysely token via createTestingModule.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../spec/page-template-access.spec.ts         |   9 +-
 .../spec/page-template-lookup-edge.spec.ts    | 183 ++++++++++++++++++
 .../src/core/search/search.controller.spec.ts |  18 +-
 .../src/core/search/search.service.spec.ts    | 105 ++++++++--
 4 files changed, 295 insertions(+), 20 deletions(-)
 create mode 100644 apps/server/src/core/page/transclusion/spec/page-template-lookup-edge.spec.ts

diff --git a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
index 1f16605b..78707dd8 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
@@ -173,8 +173,13 @@ describe('TransclusionService — template access core (real filter)', () => {
     expect((items[2] as any).status).toBe('no_access'); // not space-visible
   });
 
-  it('honours the DTO-level ≤50 cap by deduping ids passed to the filter', async () => {
-    // The DTO enforces ArrayMaxSize(50); the service dedupes before filtering.
+  it('dedupes source ids before passing them to the access filter', async () => {
+    // NOTE: this test only covers DEDUP, not the ≤50 cap. The ArrayMaxSize(50)
+    // limit is enforced by the DTO (validation layer), so it is never engaged in
+    // the service under unit test — the service receives an already-validated
+    // array and merely dedupes it. Renamed from the old "honours ≤50 cap" title,
+    // which misleadingly implied the cap was exercised here. A real cap test would
+    // belong in a controller/DTO-validation spec, not in this service unit test.
     const ids = ['a', 'a', 'b'];
     const { service, db } = makeService({
       spaceVisibleRows: [],
diff --git a/apps/server/src/core/page/transclusion/spec/page-template-lookup-edge.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-lookup-edge.spec.ts
new file mode 100644
index 00000000..59dec763
--- /dev/null
+++ b/apps/server/src/core/page/transclusion/spec/page-template-lookup-edge.spec.ts
@@ -0,0 +1,183 @@
+import { TransclusionService } from '../transclusion.service';
+
+/**
+ * Edge-case + anti-leak coverage for `lookupTemplate` that the existing
+ * `page-template-lookup.spec.ts` (stubbed filter) and `page-template-access.spec.ts`
+ * (real filter, happy paths) do not exercise:
+ *
+ *  1. SECURITY anti-leak: when comment-mark stripping THROWS, the item must come
+ *     back as `not_found` and NEVER carry raw content (the source's comment marks
+ *     could otherwise leak to a viewer). See the `catch` branch in `lookupTemplate`.
+ *  2. A soft-deleted source page resolved through the REAL
+ *     `filterViewerAccessiblePageIds` (space-visibility query filters `deletedAt`),
+ *     asserting it maps to `not_found`/`no_access` rather than content.
+ */
+describe('TransclusionService.lookupTemplate — anti-leak catch branch', () => {
+  const now = new Date('2026-06-20T00:00:00.000Z');
+
+  function makeService(opts: {
+    accessibleIds: string[];
+    pages: Array<{
+      id: string;
+      slugId?: string;
+      title: string | null;
+      icon: string | null;
+      content: unknown;
+      updatedAt: Date;
+    }>;
+  }) {
+    const pageRepo = {
+      findManyByIds: jest.fn().mockResolvedValue(opts.pages),
+    };
+
+    const service = new TransclusionService(
+      {} as any, // db
+      {} as any, // pageTransclusionsRepo
+      {} as any, // pageTransclusionReferencesRepo
+      {} as any, // pageTemplateReferencesRepo
+      pageRepo as any,
+      {} as any, // pagePermissionRepo
+      {} as any, // spaceMemberRepo
+      {} as any, // attachmentRepo
+      {} as any, // storageService
+      {} as any, // pageAccessService
+      {} as any, // workspaceRepo
+    );
+
+    // Stub the access decision; we are testing the content-prep stage, not access.
+    jest
+      .spyOn(service, 'filterViewerAccessiblePageIds')
+      .mockResolvedValue(opts.accessibleIds);
+
+    return { service, pageRepo };
+  }
+
+  it('returns not_found (NOT raw content) when comment-mark stripping throws', async () => {
+    // An accessible, present page whose stored content is structurally invalid PM:
+    // a `text` node without a `text` field. `jsonToNode` (called inside the try
+    // block) throws "Invalid text node in JSON" on this, which exercises the
+    // service's catch -> not_found anti-leak guard. This uses a REAL malformed
+    // input (no module mocking) so the test stays faithful to production behaviour.
+    const malformedContent = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              // Missing `text` — Node.fromJSON rejects this and jsonToNode rethrows.
+              type: 'text',
+              marks: [{ type: 'comment', attrs: { commentId: 'leak-me' } }],
+            },
+          ],
+        },
+      ],
+    };
+
+    const { service } = makeService({
+      accessibleIds: ['p1'],
+      pages: [
+        {
+          id: 'p1',
+          slugId: 's1',
+          title: 'Secret',
+          icon: '📄',
+          content: malformedContent,
+          updatedAt: now,
+        },
+      ],
+    });
+
+    // Silence the expected error log so the suite output stays clean.
+    jest.spyOn((service as any).logger, 'error').mockImplementation(() => {});
+
+    const { items } = await service.lookupTemplate(['p1'], 'u1', 'w1');
+
+    expect(items).toHaveLength(1);
+    const item = items[0] as any;
+
+    // Must degrade to not_found...
+    expect(item.status).toBe('not_found');
+    expect(item.sourcePageId).toBe('p1');
+
+    // ...and must NOT leak ANY content/metadata of the source page.
+    expect(item).not.toHaveProperty('content');
+    expect(item).not.toHaveProperty('title');
+    expect(item).not.toHaveProperty('icon');
+    expect(item).not.toHaveProperty('slugId');
+    expect(item).not.toHaveProperty('sourceUpdatedAt');
+
+    // Hard guarantee: the would-be-leaked comment mark appears nowhere in output.
+    expect(JSON.stringify(item)).not.toContain('leak-me');
+    expect(JSON.stringify(item)).not.toContain('comment');
+  });
+});
+
+describe('TransclusionService.lookupTemplate — soft-deleted source via real filter', () => {
+  const now = new Date('2026-06-20T00:00:00.000Z');
+
+  /**
+   * Chainable kysely `db` stub mirroring `page-template-access.spec.ts`. The
+   * space-visibility query in `filterViewerAccessiblePageIds` filters
+   * `where('deletedAt','is',null)`; a soft-deleted page is therefore absent from
+   * the rows we resolve here, so the REAL filter is what drops it.
+   */
+  function makeDb(executeRows: Array<{ id: string }>) {
+    const builder: any = {};
+    builder.selectFrom = jest.fn(() => builder);
+    builder.select = jest.fn(() => builder);
+    builder.where = jest.fn(() => builder);
+    builder.execute = jest.fn(async () => executeRows);
+    return builder;
+  }
+
+  it('resolves a soft-deleted source to not_found/no_access through the REAL filter', async () => {
+    // The page IS soft-deleted, so the space-visibility query returns no rows for
+    // it (deletedAt filter). We let the real filter run end-to-end.
+    const db = makeDb([]); // soft-deleted -> excluded by the deletedAt='is null' clause
+
+    const spaceMemberRepo = {
+      getUserSpaceIdsQuery: jest.fn(() => ({ __subquery: true })),
+    };
+    const pagePermissionRepo = {
+      filterAccessiblePageIds: jest.fn().mockResolvedValue([]),
+    };
+    const pageRepo = {
+      // Even if it were queried, the page is gone; assert via the filter instead.
+      findManyByIds: jest.fn().mockResolvedValue([]),
+    };
+
+    const service = new TransclusionService(
+      db as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      pageRepo as any,
+      pagePermissionRepo as any,
+      spaceMemberRepo as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {} as any,
+    );
+
+    const { items } = await service.lookupTemplate(['deleted-src'], 'u1', 'w1');
+
+    // Soft-deleted source must never resolve to content.
+    expect(items).toEqual([
+      { sourcePageId: 'deleted-src', status: 'no_access' },
+    ]);
+    const item = items[0] as any;
+    expect(item).not.toHaveProperty('content');
+
+    // The real filter short-circuited before page-permission filtering because
+    // the deletedAt-filtered space-visibility query returned nothing.
+    expect(pagePermissionRepo.filterAccessiblePageIds).not.toHaveBeenCalled();
+    // And the verb on the db builder included a deletedAt 'is null' guard, proving
+    // the real path (not a stub) excluded the soft-deleted page.
+    const deletedAtCall = db.where.mock.calls.find(
+      (c: any[]) => c[0] === 'deletedAt',
+    );
+    expect(deletedAtCall).toEqual(['deletedAt', 'is', null]);
+  });
+});
diff --git a/apps/server/src/core/search/search.controller.spec.ts b/apps/server/src/core/search/search.controller.spec.ts
index 6d6bad58..1b0e42cb 100644
--- a/apps/server/src/core/search/search.controller.spec.ts
+++ b/apps/server/src/core/search/search.controller.spec.ts
@@ -1,15 +1,19 @@
-import { Test, TestingModule } from '@nestjs/testing';
 import { SearchController } from './search.controller';
 
+// Direct instantiation with stub deps. The Test.createTestingModule form failed
+// to resolve SearchService's @InjectKysely() connection token at compile() (the
+// same Nest-DI/Kysely-token issue addressed in search.service.spec), and this
+// unit only needs the controller to construct.
 describe('SearchController', () => {
   let controller: SearchController;
 
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      controllers: [SearchController],
-    }).compile();
-
-    controller = module.get<SearchController>(SearchController);
+  beforeEach(() => {
+    controller = new SearchController(
+      {} as any, // searchService
+      {} as any, // spaceAbility
+      {} as any, // environmentService
+      {} as any, // moduleRef
+    );
   });
 
   it('should be defined', () => {
diff --git a/apps/server/src/core/search/search.service.spec.ts b/apps/server/src/core/search/search.service.spec.ts
index 63fc48c0..efd4d2b8 100644
--- a/apps/server/src/core/search/search.service.spec.ts
+++ b/apps/server/src/core/search/search.service.spec.ts
@@ -1,18 +1,101 @@
-import { Test, TestingModule } from '@nestjs/testing';
 import { SearchService } from './search.service';
 
 describe('SearchService', () => {
-  let service: SearchService;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [SearchService],
-    }).compile();
-
-    service = module.get<SearchService>(SearchService);
-  });
-
   it('should be defined', () => {
+    // Construct directly with stub deps. The previous Test.createTestingModule
+    // form could not resolve the @InjectKysely() connection token and failed at
+    // compile() — manual construction mirrors the rest of these unit specs.
+    const service = new SearchService(
+      {} as any, // db
+      {} as any, // pageRepo
+      {} as any, // shareRepo
+      {} as any, // spaceMemberRepo
+      {} as any, // pagePermissionRepo
+    );
     expect(service).toBeDefined();
   });
 });
+
+/**
+ * Focused coverage for the `onlyTemplates` flag in `searchSuggestions`, which
+ * restricts page suggestions to template pages (`is_template = true`). The kysely
+ * query builder and repos are mocked the same way the access specs mock chainable
+ * builders: every builder method returns the same builder, `.execute()` resolves
+ * the supplied rows. We assert whether `.where('isTemplate', '=', true)` is added.
+ */
+describe('SearchService.searchSuggestions — onlyTemplates filter', () => {
+  function makeService(pageRows: Array<{ id: string }>) {
+    // Chainable page-search builder. Record every `.where(...)` call so we can
+    // assert on the is_template restriction.
+    const pageBuilder: any = {};
+    pageBuilder.select = jest.fn(() => pageBuilder);
+    pageBuilder.where = jest.fn(() => pageBuilder);
+    pageBuilder.orderBy = jest.fn(() => pageBuilder);
+    pageBuilder.limit = jest.fn(() => pageBuilder);
+    pageBuilder.execute = jest.fn(async () => pageRows);
+
+    const db: any = {
+      // searchSuggestions only touches `pages` here (includePages: true).
+      selectFrom: jest.fn(() => pageBuilder),
+    };
+
+    const pageRepo = {
+      // `.select((eb) => this.pageRepo.withSpace(eb))` — return value is ignored
+      // by our builder stub, so a sentinel is enough.
+      withSpace: jest.fn(() => ({ __withSpace: true })),
+    };
+    const shareRepo = {};
+    const spaceMemberRepo = {
+      getUserSpaceIds: jest.fn().mockResolvedValue(['space-1']),
+    };
+    const pagePermissionRepo = {
+      // Let every found page through page-level permission filtering.
+      filterAccessiblePageIds: jest
+        .fn()
+        .mockImplementation(async ({ pageIds }: { pageIds: string[] }) => pageIds),
+    };
+
+    const service = new SearchService(
+      db as any,
+      pageRepo as any,
+      shareRepo as any,
+      spaceMemberRepo as any,
+      pagePermissionRepo as any,
+    );
+
+    return { service, db, pageBuilder };
+  }
+
+  const isTemplateWhereCall = (pageBuilder: any) =>
+    pageBuilder.where.mock.calls.find((c: any[]) => c[0] === 'isTemplate');
+
+  it('restricts page suggestions to is_template = true when onlyTemplates is set', async () => {
+    const { service, pageBuilder } = makeService([{ id: 'tmpl-1' }]);
+
+    const result = await service.searchSuggestions(
+      { query: 'plan', includePages: true, onlyTemplates: true } as any,
+      'user-1',
+      'ws-1',
+    );
+
+    // The is_template restriction must be applied to the page query.
+    const call = isTemplateWhereCall(pageBuilder);
+    expect(call).toEqual(['isTemplate', '=', true]);
+
+    // Sanity: the (template) page made it through.
+    expect(result.pages.map((p: any) => p.id)).toEqual(['tmpl-1']);
+  });
+
+  it('does NOT restrict to templates when onlyTemplates is absent', async () => {
+    const { service, pageBuilder } = makeService([{ id: 'any-1' }]);
+
+    await service.searchSuggestions(
+      { query: 'plan', includePages: true } as any,
+      'user-1',
+      'ws-1',
+    );
+
+    // No is_template clause should be added for a normal page suggestion search.
+    expect(isTemplateWhereCall(pageBuilder)).toBeUndefined();
+  });
+});

From 1f457b060ca2dcd6ea5b9da20ad42e037109a29e Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 23:36:53 +0300
Subject: [PATCH 19/28] fix(mcp): security review follow-ups (#24)

Post-merge hardening from the #13 security review:
- isInitializeRequestBody now delegates to the SDK isInitializeRequest (same
  predicate as packages/mcp/http.ts), so a bare {method:'initialize'} with no
  id/params no longer triggers the side-effecting login() (audit-spam /
  user_sessions growth) before http.ts 400s it.
- Bind the Bearer path to the instance workspace: verifyBearerAccess rejects a
  token whose payload.workspaceId != the instance workspace (resolved via
  workspaceRepo.findFirst, consistent with the Basic path); optional param so
  it's a no-op when unset.
- Close the user-enumeration timing oracle in verifyUserCredentials: the
  missing/disabled branch now runs a bcrypt compare against a module-level dummy
  hash whose cost (12) matches production saltRounds, so both paths take one
  equal-cost bcrypt compare; the exact CREDENTIALS_MISMATCH_MESSAGE is preserved.
- Document the trusted-proxy requirement for the spoofable per-IP brute-force
  limiter in .env.example (trustProxy is on; deploy behind a trusted proxy).
- Add real-execution coverage for enforceBasicLoginGate (SSO enforced / EE-MFA
  bundled vs not / user-MFA / workspace-enforced-MFA) instead of stubbing the gate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .env.example                                  |  10 +
 .../src/core/auth/services/auth.service.ts    |  20 ++
 .../verify-user-credentials.contract.spec.ts  |  36 +++
 .../src/integrations/mcp/mcp-auth.helpers.ts  |  47 +++-
 .../mcp/mcp-basic-login-gate.spec.ts          | 253 ++++++++++++++++++
 .../src/integrations/mcp/mcp.service.spec.ts  |  80 +++++-
 .../src/integrations/mcp/mcp.service.ts       |  10 +
 7 files changed, 433 insertions(+), 23 deletions(-)
 create mode 100644 apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts

diff --git a/.env.example b/.env.example
index b04078e3..a19fd2d7 100644
--- a/.env.example
+++ b/.env.example
@@ -2,6 +2,16 @@
 APP_URL=http://localhost:3000
 PORT=3000
 
+# --- Security / reverse proxy ---
+# The app runs with Fastify `trustProxy` ENABLED, so it derives the client IP
+# (req.ip) from the `X-Forwarded-For` header. That header is client-forgeable.
+# Deploy this app behind a trusted reverse proxy that SETS/OVERWRITES (not
+# appends) `X-Forwarded-For` with the real client IP. Without such a proxy, any
+# per-IP throttling — including the /mcp Basic brute-force limiter — can be
+# bypassed by an attacker who simply spoofs `X-Forwarded-For` to rotate IPs.
+# (The /mcp limiter keeps a global per-email key as an IP-independent backstop,
+# but the per-IP and per-IP+email keys rely on a trustworthy X-Forwarded-For.)
+
 # minimum of 32 characters. Generate one with: openssl rand -hex 32
 APP_SECRET=REPLACE_WITH_LONG_SECRET
 
diff --git a/apps/server/src/core/auth/services/auth.service.ts b/apps/server/src/core/auth/services/auth.service.ts
index b27df4bc..1c952f6e 100644
--- a/apps/server/src/core/auth/services/auth.service.ts
+++ b/apps/server/src/core/auth/services/auth.service.ts
@@ -41,6 +41,20 @@ import {
 } from '../../../integrations/audit/audit.service';
 import { EnvironmentService } from '../../../integrations/environment/environment.service';
 
+// A valid bcrypt hash (cost 10, of an arbitrary throwaway string) used ONLY to
+// equalize timing in verifyUserCredentials: when the email does not exist or
+// the user is disabled, we still run ONE bcrypt comparison against this hash
+// before throwing, so the missing/disabled path takes about the same time as
+// the real-user wrong-password path. Without it, the "no bcrypt at all" branch
+// returns measurably faster, leaking whether an email is registered (a user-
+// enumeration timing oracle, now reachable via /mcp where throttling is only a
+// spoofable in-memory limiter). This is never used as a real credential.
+// The cost factor MUST match the production saltRounds (12 — see
+// common/helpers/utils.ts hashPassword), otherwise the dummy compare runs
+// faster than a real wrong-password compare and the timing oracle survives.
+const DUMMY_PASSWORD_HASH =
+  '$2b$12$q/l637TULK3vU3Cmji0y8utpJS/UiftMi3Jdm4Tsi5EIv/0FE7WV.';
+
 @Injectable()
 export class AuthService {
   constructor(
@@ -82,6 +96,12 @@ export class AuthService {
     // recognises this exact message via isCredentialsFailure.
     const errorMessage = CREDENTIALS_MISMATCH_MESSAGE;
     if (!user || isUserDisabled(user)) {
+      // Constant-time intent: run ONE bcrypt comparison (against a dummy hash)
+      // even when the user is missing/disabled, so this path takes about the
+      // same time as the real-user wrong-password path below. This closes the
+      // user-enumeration timing oracle (registered vs. not). The result is
+      // intentionally discarded — we always throw the same credentials error.
+      await comparePasswordHash(loginDto.password, DUMMY_PASSWORD_HASH);
       throw new UnauthorizedException(errorMessage);
     }
 
diff --git a/apps/server/src/core/auth/services/verify-user-credentials.contract.spec.ts b/apps/server/src/core/auth/services/verify-user-credentials.contract.spec.ts
index 30689bd6..e7b37e08 100644
--- a/apps/server/src/core/auth/services/verify-user-credentials.contract.spec.ts
+++ b/apps/server/src/core/auth/services/verify-user-credentials.contract.spec.ts
@@ -100,4 +100,40 @@ describe('AuthService no-side-effect contract (item 4)', () => {
       expect(verifyBody.includes(effect)).toBe(false);
     }
   });
+
+  // Item 4: user-enumeration timing-oracle fix. When the email is missing or the
+  // user is disabled, verifyUserCredentials must still run ONE bcrypt comparison
+  // (against a dummy hash) BEFORE throwing, so the missing/disabled path takes
+  // about the same time as the real-user wrong-password path. Asserted at the
+  // source level for the same reason as the rest of this file: AuthService cannot
+  // be imported under this jest config to spy on comparePasswordHash live.
+  describe('constant-time missing/disabled branch (item 4)', () => {
+    // Isolate the body of the `if (!user || isUserDisabled(user)) { ... }` guard.
+    const guardMatch = verifyBody.match(
+      /if \(!user \|\| isUserDisabled\(user\)\) \{([\s\S]*?)\n {4}\}/,
+    );
+
+    it('the missing/disabled guard runs a bcrypt compare before throwing', () => {
+      expect(guardMatch).not.toBeNull();
+      const guardBody = guardMatch![1];
+      // It performs the dummy bcrypt comparison...
+      expect(guardBody).toContain('comparePasswordHash');
+      // ...and only AFTER that throws the credentials error (compare precedes
+      // the throw STATEMENT — match `throw new`, not the word "throw" in a comment).
+      const compareIdx = guardBody.indexOf('comparePasswordHash');
+      const throwIdx = guardBody.indexOf('throw new');
+      expect(compareIdx).toBeGreaterThanOrEqual(0);
+      expect(throwIdx).toBeGreaterThan(compareIdx);
+    });
+
+    it('uses a module-level dummy hash constant (never a real credential)', () => {
+      // The dummy hash is a module-level constant referenced in the guard, not an
+      // inline literal recomputed per call.
+      expect(verifyBody).toContain('DUMMY_PASSWORD_HASH');
+      // Cost factor MUST be 12 to match production saltRounds, otherwise the
+      // dummy compare is faster than a real wrong-password compare and the
+      // timing oracle survives.
+      expect(source).toMatch(/const DUMMY_PASSWORD_HASH =\s*'\$2b\$12\$/);
+    });
+  });
 });
diff --git a/apps/server/src/integrations/mcp/mcp-auth.helpers.ts b/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
index 4a0b5be1..3ec8ec21 100644
--- a/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
+++ b/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
@@ -5,6 +5,7 @@
 // the Authorization header.
 import { UnauthorizedException } from '@nestjs/common';
 import { timingSafeEqual } from 'node:crypto';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { JwtType } from '../../core/auth/dto/jwt-payload';
 import { CREDENTIALS_MISMATCH_MESSAGE } from '../../core/auth/auth.constants';
 
@@ -291,6 +292,14 @@ export interface BearerVerifyDeps {
     workspaceId?: string;
     sessionId?: string;
   }>;
+  // The workspace id of THIS MCP instance, when the caller can resolve it (the
+  // community build is single-workspace, so McpService passes its default
+  // workspace's id). When provided, the token's `workspaceId` claim MUST equal
+  // it, mirroring JwtStrategy's `req.raw.workspaceId !== payload.workspaceId`
+  // guard so a valid ACCESS token from a DIFFERENT workspace cannot be replayed
+  // against this instance in a multi-workspace deployment. Optional so callers /
+  // tests that genuinely cannot resolve an instance workspace are unchanged.
+  expectedWorkspaceId?: string;
   // Load the user (or undefined) for the disabled check.
   findUser: (
     sub: string,
@@ -321,6 +330,19 @@ export async function verifyBearerAccess(
     throw new UnauthorizedException(generic);
   }
 
+  // Bind the token to THIS instance's workspace (mirrors JwtStrategy). When the
+  // caller resolved an instance workspace id, a token whose `workspaceId` claim
+  // points at another workspace is rejected, so a valid ACCESS token minted in
+  // workspace B cannot be replayed against an MCP instance serving workspace A.
+  // In the single-workspace community build expectedWorkspaceId equals the only
+  // workspace, so this is a no-op there; it only bites a multi-workspace deploy.
+  if (
+    deps.expectedWorkspaceId &&
+    payload.workspaceId !== deps.expectedWorkspaceId
+  ) {
+    throw new UnauthorizedException(generic);
+  }
+
   const user = await deps.findUser(payload.sub, payload.workspaceId);
   if (!user || user.deactivatedAt || user.deletedAt) {
     throw new UnauthorizedException(generic);
@@ -342,21 +364,24 @@ export async function verifyBearerAccess(
 
 /**
  * Detect a genuine JSON-RPC `initialize` request from an already-parsed body.
- * Mirrors the @modelcontextprotocol/sdk `isInitializeRequest` signal that
- * packages/mcp/src/http.ts uses to decide whether to mint a session, but
- * framework/SDK-free so it is unit-testable and usable from the CommonJS
- * McpService. An initialize request is a single JSON-RPC object whose `method`
- * is exactly 'initialize'; a batch (array) body is never an initialize request.
+ * Delegates to the @modelcontextprotocol/sdk `isInitializeRequest` predicate —
+ * the SAME predicate packages/mcp/src/http.ts uses to decide whether to mint a
+ * session — so the session-minting side (this server) and the session-creating
+ * side (http.ts) agree EXACTLY on what counts as an initialize request. The SDK
+ * predicate validates the full InitializeRequest shape (jsonrpc, id, method ===
+ * 'initialize', params incl. protocolVersion); a bare `{ method: 'initialize' }`
+ * with no params, a batch (array) body, etc. are NOT initialize requests.
  *
  * This is the second half of the session-INIT decision: `isSessionInit` is
- * (no `mcp-session-id` header) AND `isInitializeRequestBody(body)`. Using it
- * ensures the side-effecting login() (user_sessions insert + USER_LOGIN audit +
- * lastLoginAt) only runs for a real initialize, never for an arbitrary
- * header-less request that http.ts will subsequently 400.
+ * (no `mcp-session-id` header) AND `isInitializeRequestBody(body)`. Matching the
+ * SDK predicate exactly ensures the side-effecting login() (user_sessions insert
+ * + USER_LOGIN audit + lastLoginAt) only runs for a request http.ts will also
+ * accept as an initialize — never for an arbitrary header-less request that
+ * http.ts would subsequently 400 (which would otherwise spam the audit log /
+ * grow user_sessions without ever creating an MCP session).
  */
 export function isInitializeRequestBody(body: unknown): boolean {
-  if (!body || typeof body !== 'object' || Array.isArray(body)) return false;
-  return (body as { method?: unknown }).method === 'initialize';
+  return isInitializeRequest(body);
 }
 
 /** Extract a Bearer token from an Authorization header (case-insensitive). */
diff --git a/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts b/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts
new file mode 100644
index 00000000..b9eb7a0c
--- /dev/null
+++ b/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts
@@ -0,0 +1,253 @@
+import { UnauthorizedException } from '@nestjs/common';
+
+// ---------------------------------------------------------------------------
+// These tests exercise the REAL McpService.enforceBasicLoginGate (the pre-token
+// SSO/MFA gate on the /mcp HTTP-Basic path). Unlike the resolveMcpSessionConfig
+// tests in mcp.service.spec.ts — which STUB the gate and only assert it runs
+// before login()/verifyCredentials — here the gate logic is instantiated for
+// real and only its LEAF dependencies are mocked:
+//   - the workspace object (plain object with/without enforceSso),
+//   - the user credentials (plain object),
+//   - the lazily-required EE MFA module (jest.mock with { virtual: true } so we
+//     can simulate BOTH "bundled" and "not bundled" community-build states),
+//   - the injected MfaService instance (via a stub moduleRef).
+//
+// McpService cannot normally be imported under jest because it imports
+// AuthService, which drags in the React email-template graph
+// (@docmost/transactional/emails/*) that the jest moduleNameMapper does not
+// resolve. We therefore mock the heavy collaborator modules (auth.service,
+// token.service, the @docmost/db repos and mcp-auth.helpers) at the module
+// level so importing mcp.service.ts succeeds. None of those are touched by the
+// gate itself, so the gate runs unmodified against the real code path.
+// ---------------------------------------------------------------------------
+
+// The EE MFA module specifier the jest.mock below intercepts MUST be
+// byte-for-byte the specifier that mcp.service.ts lazily require()s
+// ('./../../ee/mfa/services/mfa.service'). jest.mock is hoisted above all
+// non-hoisted code, so the path is inlined as a literal in the call below
+// rather than referenced through a const (which would not yet be initialised).
+// `{ virtual: true }` is required because the EE module does not exist in this
+// OSS build (there is no src/ee directory) — without it jest cannot register a
+// mock for a path it cannot resolve on disk.
+
+// Mutable handle the virtual mock factory reads, so each test can decide whether
+// the EE module is "bundled" (factory returns a MfaService class) or "not
+// bundled" (factory throws, mimicking the require() failing on a community
+// build). jest.mock is hoisted, so the factory must close over this lazily.
+let mfaModuleState: { bundled: boolean; checkMfaRequirements?: jest.Mock } = {
+  bundled: false,
+};
+
+jest.mock(
+  './../../ee/mfa/services/mfa.service',
+  () => {
+    if (!mfaModuleState.bundled) {
+      // Simulate a community/fork build with no EE MFA module: the real
+      // require() throws, which the gate catches as the "no MFA gate" path.
+      throw new Error('Cannot find module (EE MFA not bundled)');
+    }
+    // "Bundled" build: expose a MfaService class token. The actual instance the
+    // gate calls is resolved through moduleRef.get(MfaModule.MfaService), which
+    // our stub moduleRef returns regardless of the token identity.
+    class MfaService {}
+    return { MfaService };
+  },
+  { virtual: true },
+);
+
+// --- Mock the heavy collaborator modules so importing mcp.service succeeds. ---
+// The gate never calls into these; they exist only to satisfy the import graph.
+jest.mock('../../core/auth/services/auth.service', () => ({
+  AuthService: class AuthService {},
+}));
+jest.mock('../../core/auth/services/token.service', () => ({
+  TokenService: class TokenService {},
+}));
+jest.mock('@docmost/db/repos/workspace/workspace.repo', () => ({
+  WorkspaceRepo: class WorkspaceRepo {},
+}));
+jest.mock('@docmost/db/repos/user/user.repo', () => ({
+  UserRepo: class UserRepo {},
+}));
+jest.mock('@docmost/db/repos/session/user-session.repo', () => ({
+  UserSessionRepo: class UserSessionRepo {},
+}));
+// mcp-auth.helpers exports both runtime values (FailedLoginLimiter is used in
+// the constructor) and types. Provide a minimal FailedLoginLimiter so the
+// constructor runs; everything else the gate path doesn't need.
+jest.mock('./mcp-auth.helpers', () => ({
+  FailedLoginLimiter: class FailedLoginLimiter {
+    sweep() {}
+  },
+}));
+
+// Import AFTER the mocks are registered.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+import { McpService } from './mcp.service';
+
+type GateCreds = { email: string; password: string };
+
+// Build an McpService instance with stubbed constructor deps. We never call the
+// auth/db collaborators from the gate, so undefined stand-ins are fine for all
+// but moduleRef, which the MFA branch reads.
+function makeService(opts: {
+  checkMfaRequirements?: jest.Mock;
+}): { service: McpService; gate: (ws: unknown, creds: GateCreds) => Promise<void> } {
+  // Stub moduleRef.get -> returns an object whose checkMfaRequirements is the
+  // provided mock. The gate calls moduleRef.get(MfaModule.MfaService).
+  const moduleRef = {
+    get: jest.fn().mockReturnValue({
+      checkMfaRequirements:
+        opts.checkMfaRequirements ?? jest.fn().mockResolvedValue(undefined),
+    }),
+  };
+
+  const service = new McpService(
+    undefined as never, // environmentService
+    undefined as never, // workspaceRepo
+    undefined as never, // authService
+    undefined as never, // tokenService
+    undefined as never, // userRepo
+    undefined as never, // userSessionRepo
+    moduleRef as never, // moduleRef (read by the MFA branch)
+  );
+  // Stop the constructor's unref'd sweep timer leaking across tests.
+  service.onModuleDestroy();
+
+  // enforceBasicLoginGate is private; reach it through the instance. Calling the
+  // REAL method (not a stub) is the whole point of this suite.
+  const gate = (
+    service as unknown as {
+      enforceBasicLoginGate: (ws: unknown, creds: GateCreds) => Promise<void>;
+    }
+  ).enforceBasicLoginGate.bind(service);
+
+  return { service, gate };
+}
+
+const CREDS: GateCreds = { email: 'user@example.com', password: 'pw' };
+
+describe('McpService.enforceBasicLoginGate (REAL gate, leaf deps mocked)', () => {
+  beforeEach(() => {
+    // Reset to the community-build default (no EE module) before each test.
+    mfaModuleState = { bundled: false };
+    jest.clearAllMocks();
+  });
+
+  describe('SSO enforcement (validateSsoEnforcement)', () => {
+    it('rejects with Unauthorized when the workspace enforces SSO, before any MFA/login', async () => {
+      const { gate } = makeService({});
+      const workspace = { id: 'ws-1', enforceSso: true };
+
+      await expect(gate(workspace, CREDS)).rejects.toBeInstanceOf(
+        UnauthorizedException,
+      );
+      // The /mcp 401 surfaces an SSO-specific message (not a generic MCP error).
+      await expect(gate(workspace, CREDS)).rejects.toThrow(/enforced SSO/i);
+    });
+
+    it('does NOT consult the MFA module when SSO is enforced (gate short-circuits)', async () => {
+      // Even if the EE module WERE bundled, the SSO branch throws first, so the
+      // moduleRef MFA lookup must never run.
+      mfaModuleState = {
+        bundled: true,
+        checkMfaRequirements: jest.fn(),
+      };
+      const { service, gate } = makeService({
+        checkMfaRequirements: mfaModuleState.checkMfaRequirements,
+      });
+      const moduleRefGet = (
+        service as unknown as { moduleRef: { get: jest.Mock } }
+      ).moduleRef.get;
+
+      await expect(
+        gate({ id: 'ws-1', enforceSso: true }, CREDS),
+      ).rejects.toThrow(/enforced SSO/i);
+      // The SSO branch fired before the MFA require/lookup.
+      expect(moduleRefGet).not.toHaveBeenCalled();
+      expect(mfaModuleState.checkMfaRequirements).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('community build: EE MFA module NOT bundled', () => {
+    it('passes (no throw) when SSO is not enforced and the lazy require fails (no MFA gate)', async () => {
+      // mfaModuleState.bundled === false -> the virtual mock factory throws,
+      // exactly like require() of a missing EE module on a community build.
+      const { service, gate } = makeService({});
+      const moduleRefGet = (
+        service as unknown as { moduleRef: { get: jest.Mock } }
+      ).moduleRef.get;
+
+      await expect(
+        gate({ id: 'ws-1', enforceSso: false }, CREDS),
+      ).resolves.toBeUndefined();
+      // The require() failed, so the gate returned before touching moduleRef.
+      expect(moduleRefGet).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('EE MFA module bundled', () => {
+    it('rejects with a "use a Bearer token" signal when the user has MFA enabled', async () => {
+      const check = jest.fn().mockResolvedValue({
+        userHasMfa: true,
+        requiresMfaSetup: false,
+      });
+      mfaModuleState = { bundled: true, checkMfaRequirements: check };
+      const { gate } = makeService({ checkMfaRequirements: check });
+
+      const promise = gate({ id: 'ws-1', enforceSso: false }, CREDS);
+      await expect(promise).rejects.toBeInstanceOf(UnauthorizedException);
+      await expect(
+        gate({ id: 'ws-1', enforceSso: false }, CREDS),
+      ).rejects.toThrow(/Bearer access token/i);
+      // The real requirement check was consulted with the creds + workspace.
+      expect(check).toHaveBeenCalledWith(
+        CREDS,
+        { id: 'ws-1', enforceSso: false },
+        undefined,
+      );
+    });
+
+    it('rejects when the workspace enforces MFA (requiresMfaSetup)', async () => {
+      // requiresMfaSetup === true models a workspace that enforces MFA for a
+      // user who has not set it up yet; the Basic path cannot complete it.
+      const check = jest.fn().mockResolvedValue({
+        userHasMfa: false,
+        requiresMfaSetup: true,
+      });
+      mfaModuleState = { bundled: true, checkMfaRequirements: check };
+      const { gate } = makeService({ checkMfaRequirements: check });
+
+      await expect(
+        gate({ id: 'ws-1', enforceSso: false }, CREDS),
+      ).rejects.toThrow(/Bearer access token/i);
+    });
+
+    it('passes when the user has no MFA and the workspace does not enforce it', async () => {
+      const check = jest.fn().mockResolvedValue({
+        userHasMfa: false,
+        requiresMfaSetup: false,
+      });
+      mfaModuleState = { bundled: true, checkMfaRequirements: check };
+      const { gate } = makeService({ checkMfaRequirements: check });
+
+      await expect(
+        gate({ id: 'ws-1', enforceSso: false }, CREDS),
+      ).resolves.toBeUndefined();
+      // The bundled module's requirement check WAS consulted (proving we took
+      // the bundled branch, not the community no-op branch).
+      expect(check).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes when checkMfaRequirements returns a falsy result (no requirement flags)', async () => {
+      // Defensive: a bundled module that returns undefined must not reject.
+      const check = jest.fn().mockResolvedValue(undefined);
+      mfaModuleState = { bundled: true, checkMfaRequirements: check };
+      const { gate } = makeService({ checkMfaRequirements: check });
+
+      await expect(
+        gate({ id: 'ws-1', enforceSso: false }, CREDS),
+      ).resolves.toBeUndefined();
+    });
+  });
+});
diff --git a/apps/server/src/integrations/mcp/mcp.service.spec.ts b/apps/server/src/integrations/mcp/mcp.service.spec.ts
index bf4c8a24..467f4413 100644
--- a/apps/server/src/integrations/mcp/mcp.service.spec.ts
+++ b/apps/server/src/integrations/mcp/mcp.service.spec.ts
@@ -264,6 +264,31 @@ describe('verifyBearerAccess (Bearer revocation/disabled checks)', () => {
       ),
     ).rejects.toThrow('jwt expired');
   });
+
+  // Item 3: bind the Bearer token to THIS instance's workspace (mirrors
+  // JwtStrategy). A token whose workspaceId claim differs from the instance
+  // workspace must be rejected; matching/absent expectedWorkspaceId is allowed.
+  it('rejects a token from a DIFFERENT workspace when expectedWorkspaceId is set', async () => {
+    await expect(
+      verifyBearerAccess('t', {
+        ...bearerDeps(),
+        expectedWorkspaceId: 'ws-OTHER',
+      }),
+    ).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('accepts a token whose workspace matches expectedWorkspaceId', async () => {
+    const res = await verifyBearerAccess('t', {
+      ...bearerDeps(),
+      expectedWorkspaceId: 'ws-1',
+    });
+    expect(res).toEqual({ sub: 'user-1', email: 'u@e.com' });
+  });
+
+  it('does NOT enforce a workspace when expectedWorkspaceId is undefined (single-workspace no-op)', async () => {
+    const res = await verifyBearerAccess('t', bearerDeps());
+    expect(res).toEqual({ sub: 'user-1', email: 'u@e.com' });
+  });
 });
 
 describe('resolveMcpSessionConfig', () => {
@@ -587,23 +612,48 @@ describe('resolveMcpSessionConfig', () => {
   });
 });
 
-describe('isInitializeRequestBody (session-INIT detection)', () => {
-  it('true only for a single JSON-RPC object with method === "initialize"', () => {
-    expect(isInitializeRequestBody({ jsonrpc: '2.0', method: 'initialize' })).toBe(
-      true,
-    );
+// A full, valid JSON-RPC InitializeRequest as the @modelcontextprotocol/sdk
+// `isInitializeRequest` predicate (which isInitializeRequestBody now delegates
+// to) requires: jsonrpc + id + method === 'initialize' + params.protocolVersion.
+const fullInitializeRequest = {
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'test-client', version: '1.0.0' },
+  },
+};
+
+describe('isInitializeRequestBody (session-INIT detection, matches SDK predicate)', () => {
+  it('true for a FULL valid InitializeRequest (the SDK predicate signal)', () => {
+    expect(isInitializeRequestBody(fullInitializeRequest)).toBe(true);
+  });
+
+  it('false for a bare { method: "initialize" } with no id/params (item 1)', () => {
+    // Item 1: this previously returned true (method-only check) and let an
+    // authenticated client POST a params-less body with no mcp-session-id, which
+    // ran the side-effecting login() before http.ts 400'd it. The SDK predicate
+    // rejects it (no id, no params.protocolVersion), so it no longer mints a
+    // session / audit row.
+    expect(isInitializeRequestBody({ method: 'initialize' })).toBe(false);
+    expect(
+      isInitializeRequestBody({ jsonrpc: '2.0', method: 'initialize' }),
+    ).toBe(false);
+    expect(
+      isInitializeRequestBody({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }),
+    ).toBe(false);
   });
 
   it('false for a non-initialize method (e.g. tools/call)', () => {
     expect(
-      isInitializeRequestBody({ jsonrpc: '2.0', method: 'tools/call' }),
+      isInitializeRequestBody({ ...fullInitializeRequest, method: 'tools/call' }),
     ).toBe(false);
   });
 
   it('false for a batch (array) body, null/undefined, or a non-object', () => {
-    expect(
-      isInitializeRequestBody([{ jsonrpc: '2.0', method: 'initialize' }]),
-    ).toBe(false);
+    expect(isInitializeRequestBody([fullInitializeRequest])).toBe(false);
     expect(isInitializeRequestBody(undefined)).toBe(false);
     expect(isInitializeRequestBody(null)).toBe(false);
     expect(isInitializeRequestBody('initialize')).toBe(false);
@@ -618,8 +668,14 @@ describe('isSessionInit decision (no mcp-session-id AND initialize body)', () =>
   const decide = (sessionId: string | undefined, body: unknown): boolean =>
     !sessionId && isInitializeRequestBody(body);
 
-  it('no header + initialize body -> init', () => {
-    expect(decide(undefined, { method: 'initialize' })).toBe(true);
+  it('no header + full initialize body -> init', () => {
+    expect(decide(undefined, fullInitializeRequest)).toBe(true);
+  });
+
+  it('no header + bare params-less initialize body -> NOT init (item 1)', () => {
+    // A header-less { method: 'initialize' } with no params is no longer treated
+    // as an init by the SDK predicate, so it does not mint a session via login().
+    expect(decide(undefined, { method: 'initialize' })).toBe(false);
   });
 
   it('no header + non-initialize body -> NOT init (verifyCredentials path)', () => {
@@ -627,7 +683,7 @@ describe('isSessionInit decision (no mcp-session-id AND initialize body)', () =>
   });
 
   it('has session-id -> never init regardless of body', () => {
-    expect(decide('sess-1', { method: 'initialize' })).toBe(false);
+    expect(decide('sess-1', fullInitializeRequest)).toBe(false);
   });
 });
 
diff --git a/apps/server/src/integrations/mcp/mcp.service.ts b/apps/server/src/integrations/mcp/mcp.service.ts
index 7ac16fb6..9f71272d 100644
--- a/apps/server/src/integrations/mcp/mcp.service.ts
+++ b/apps/server/src/integrations/mcp/mcp.service.ts
@@ -154,6 +154,15 @@ export class McpService implements OnModuleDestroy {
   private async verifyMcpBearer(
     token: string,
   ): Promise<{ sub?: string; email?: string }> {
+    // Resolve THIS instance's workspace so verifyBearerAccess can bind the
+    // token's `workspaceId` claim to it (mirrors JwtStrategy). The community
+    // build is single-workspace (findFirst), so this is the default workspace
+    // and the check is a no-op here; it only rejects a foreign-workspace token
+    // in a multi-workspace deployment. Undefined (no workspace configured) means
+    // no check — the credentials path would already have failed with no
+    // workspace, and an undefined here keeps the helper a no-op rather than
+    // rejecting every token.
+    const instanceWorkspace = await this.workspaceRepo.findFirst();
     // The revocation/disabled decision logic lives in the framework-free
     // verifyBearerAccess helper (unit-testable without the heavy auth graph);
     // this method only wires in the concrete TokenService + repos.
@@ -163,6 +172,7 @@ export class McpService implements OnModuleDestroy {
       verifyJwt: bindAccessJwtVerifier(this.tokenService) as (
         t: string,
       ) => Promise<JwtPayload>,
+      expectedWorkspaceId: instanceWorkspace?.id,
       findUser: (sub, workspaceId) =>
         this.userRepo.findById(sub, workspaceId),
       findActiveSession: (sessionId) =>

From 90d3fab4835b4ddf8dd6e2fa05d6b4928d11fae7 Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 23:40:40 +0300
Subject: [PATCH 20/28] test: cover features since 053a9c0d + repair test
 tooling

Add ~330 tests across server (Jest), client (Vitest), editor-ext (Vitest)
and packages/mcp (node:test) for the gitmost features added since
053a9c0d: AI chat, AI agent roles, public-share assistant, MCP per-user
auth, HTML embed, page templates/embed, realtime tree, tree
expand/collapse, and the AI-settings UI.

Test-tooling fixes (prerequisite, were silently hiding coverage):
- Repair 3 page-template specs broken by the 11-arg TransclusionService
  constructor; they never compiled, so template access-control / content
  -leak / unsync-strip coverage was fictitious.
- Build @docmost/editor-ext before server tests via a `pretest` hook;
  the stale dist omitted the new HtmlEmbed/PageEmbed exports (TS2305).
- Let jest resolve the .tsx email templates: add `tsx` to
  moduleFileExtensions and widen the ts-jest transform to (t|j)sx?.

Behaviour-preserving "extract pure core" refactors that the tests drive:
- server: resolveShareAssistantRequest + uiMessageTextLength
  (public-share controller), decideBasicGate + mapAuthResultToResponse
  (mcp), buildErrorAssistantRecord (ai-chat), jsonbObject export (roles).
- client: render-raw-html + shouldExecute/canEdit, decide-embed-state,
  page-embed picker utils, tree-socket reducers, open/close branch maps,
  isEndpointConfigured/resolveKeyField; buildTreeWithChildren now treats
  a permission-trimmed orphan as a root instead of crashing.

Deferred (need a test DB or HTTP harness, documented in the specs):
repo-level Postgres integration tests and the public-share XFF E2E.
Pre-existing DI/lib0-ESM suite failures are untouched and out of scope.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../ai-chat/utils/error-message.test.ts       |  53 +++
 .../ai-chat/utils/tool-parts.test.tsx         | 100 ++++++
 .../components/html-embed/html-embed-view.tsx |  45 +--
 .../html-embed/render-raw-html.test.ts        | 112 ++++++
 .../components/html-embed/render-raw-html.ts  |  73 ++++
 .../page-embed/decide-embed-state.test.ts     | 141 ++++++++
 .../page-embed/decide-embed-state.ts          |  58 ++++
 .../page-embed-ancestry-context.test.tsx      |  71 ++++
 .../page-embed-lookup-context.test.tsx        | 162 +++++++++
 .../page-embed/page-embed-picker.tsx          |  13 +-
 .../page-embed-picker.utils.test.ts           |  43 +++
 .../page-embed/page-embed-picker.utils.ts     |  27 ++
 .../components/page-embed/page-embed-view.tsx |  32 +-
 .../components/space-tree.expand-all.test.tsx | 228 ++++++++++++
 .../page/tree/components/space-tree.tsx       |  14 +-
 .../page/tree/model/tree-model.test.ts        |  52 +++
 .../features/page/tree/utils/utils.test.ts    | 237 ++++++++++++-
 .../src/features/page/tree/utils/utils.ts     |  37 +-
 .../websocket/tree-socket-reducers.test.ts    | 264 ++++++++++++++
 .../websocket/tree-socket-reducers.ts         | 164 +++++++++
 .../src/features/websocket/use-tree-socket.ts | 140 +-------
 .../components/ai-provider-settings.spec.tsx  |  55 ++-
 .../components/ai-provider-settings.tsx       |  65 ++--
 apps/server/package.json                      |   6 +-
 .../html-embed-import-detect.spec.ts          |  70 ++++
 .../helpers/prosemirror/html-embed.spec.ts    |  96 +++++
 .../src/core/ai-chat/ai-chat.service.spec.ts  |  30 ++
 .../src/core/ai-chat/ai-chat.service.ts       |  26 +-
 .../public-share-chat.controller.spec.ts      | 256 ++++++++++++++
 .../ai-chat/public-share-chat.controller.ts   | 327 ++++++++++--------
 .../core/ai-chat/public-share-chat.spec.ts    | 109 +++++-
 .../roles/ai-agent-roles.service.spec.ts      | 117 +++++++
 .../core/ai-chat/roles/jsonb-object.spec.ts   |  30 ++
 .../roles/role-override-contract.spec.ts      | 135 ++++++++
 .../public-share-chat-tools.service.spec.ts   | 132 +++++++
 .../verify-user-credentials.live.spec.ts      | 233 +++++++++++++
 .../transclusion/spec/page-embed.util.spec.ts |  61 ++++
 .../spec/page-template-access.spec.ts         | 278 ++++++++++++++-
 .../spec/page-template-lookup.spec.ts         |  59 ++++
 .../spec/page-template.controller.spec.ts     |  51 +++
 .../transclusion-unsync-html-embed.spec.ts    |   1 +
 .../src/core/share/share-html-embed.spec.ts   | 128 +++++++
 .../services/workspace-html-embed.spec.ts     | 111 ++++++
 .../ai-agent-roles/ai-agent-roles.repo.ts     |   2 +-
 .../src/integrations/ai/ai-error.util.spec.ts |  22 ++
 .../src/integrations/ai/ai.service.spec.ts    | 113 ++++++
 .../src/integrations/mcp/mcp-auth.helpers.ts  | 105 ++++++
 .../src/integrations/mcp/mcp.service.spec.ts  | 195 +++++++++++
 .../src/integrations/mcp/mcp.service.ts       | 152 ++++----
 .../src/ws/listeners/page-ws.listener.spec.ts | 137 ++++++++
 apps/server/src/ws/ws-service.spec.ts         | 259 ++++++++++++++
 apps/server/src/ws/ws-tree.service.spec.ts    | 106 ++++++
 .../lib/html-embed/html-embed-codec.spec.ts   | 116 +++++++
 .../lib/markdown/html-embed-marked.spec.ts    | 105 ++++++
 .../src/lib/page-embed/page-embed.spec.ts     |  88 +++++
 .../mcp/test/unit/http-idle-eviction.test.mjs | 273 +++++++++++++++
 56 files changed, 5668 insertions(+), 447 deletions(-)
 create mode 100644 apps/client/src/features/ai-chat/utils/error-message.test.ts
 create mode 100644 apps/client/src/features/ai-chat/utils/tool-parts.test.tsx
 create mode 100644 apps/client/src/features/editor/components/html-embed/render-raw-html.test.ts
 create mode 100644 apps/client/src/features/editor/components/html-embed/render-raw-html.ts
 create mode 100644 apps/client/src/features/editor/components/page-embed/decide-embed-state.test.ts
 create mode 100644 apps/client/src/features/editor/components/page-embed/decide-embed-state.ts
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.test.tsx
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.test.ts
 create mode 100644 apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.ts
 create mode 100644 apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx
 create mode 100644 apps/client/src/features/websocket/tree-socket-reducers.test.ts
 create mode 100644 apps/client/src/features/websocket/tree-socket-reducers.ts
 create mode 100644 apps/server/src/common/helpers/prosemirror/html-embed-import-detect.spec.ts
 create mode 100644 apps/server/src/core/ai-chat/public-share-chat.controller.spec.ts
 create mode 100644 apps/server/src/core/ai-chat/roles/jsonb-object.spec.ts
 create mode 100644 apps/server/src/core/ai-chat/roles/role-override-contract.spec.ts
 create mode 100644 apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.spec.ts
 create mode 100644 apps/server/src/core/auth/services/verify-user-credentials.live.spec.ts
 create mode 100644 apps/server/src/core/workspace/services/workspace-html-embed.spec.ts
 create mode 100644 apps/server/src/ws/ws-service.spec.ts
 create mode 100644 packages/editor-ext/src/lib/html-embed/html-embed-codec.spec.ts
 create mode 100644 packages/editor-ext/src/lib/markdown/html-embed-marked.spec.ts
 create mode 100644 packages/editor-ext/src/lib/page-embed/page-embed.spec.ts
 create mode 100644 packages/mcp/test/unit/http-idle-eviction.test.mjs

diff --git a/apps/client/src/features/ai-chat/utils/error-message.test.ts b/apps/client/src/features/ai-chat/utils/error-message.test.ts
new file mode 100644
index 00000000..83d52b3c
--- /dev/null
+++ b/apps/client/src/features/ai-chat/utils/error-message.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { describeChatError } from "./error-message";
+
+// Identity translator: assert on the raw English key so the tests do not depend
+// on the i18n catalog.
+const t = (key: string) => key;
+
+describe("describeChatError", () => {
+  it('surfaces a provider "402: ..." stream error verbatim', () => {
+    expect(describeChatError("402: Insufficient credits", t)).toBe(
+      "402: Insufficient credits",
+    );
+  });
+
+  it('does NOT misclassify a body that merely contains "403" (no "statusCode":403)', () => {
+    // A provider message mentioning the number 403 must be surfaced verbatim,
+    // never folded into the "AI chat is disabled" gating message.
+    const msg = "429: rate limited after 403 attempts";
+    expect(describeChatError(msg, t)).toBe(msg);
+  });
+
+  it('maps a {"statusCode":403} body to the disabled message', () => {
+    const body = '{"statusCode":403,"message":"Forbidden"}';
+    expect(describeChatError(body, t)).toBe(
+      "AI chat is disabled for this workspace.",
+    );
+  });
+
+  it('maps a {"statusCode":503} body to the not-configured message', () => {
+    const body = '{"statusCode":503,"message":"Service Unavailable"}';
+    expect(describeChatError(body, t)).toBe(
+      "The AI provider is not configured. Ask an administrator to set it up.",
+    );
+  });
+
+  it('falls back to the generic message for "An error occurred."', () => {
+    expect(describeChatError("An error occurred.", t)).toBe(
+      "The AI agent could not respond. Please try again.",
+    );
+  });
+
+  it('falls back to the generic message for "Internal server error"', () => {
+    expect(describeChatError("Internal server error", t)).toBe(
+      "The AI agent could not respond. Please try again.",
+    );
+  });
+
+  it("falls back to the generic message for empty input", () => {
+    expect(describeChatError("", t)).toBe(
+      "The AI agent could not respond. Please try again.",
+    );
+  });
+});
diff --git a/apps/client/src/features/ai-chat/utils/tool-parts.test.tsx b/apps/client/src/features/ai-chat/utils/tool-parts.test.tsx
new file mode 100644
index 00000000..f3c3bd4c
--- /dev/null
+++ b/apps/client/src/features/ai-chat/utils/tool-parts.test.tsx
@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import {
+  toolCitations,
+  toolRunState,
+  type ToolUiPart,
+} from "./tool-parts";
+
+describe("toolCitations", () => {
+  it("emits one citation per searchPages item with a /p/{id} href", () => {
+    const part: ToolUiPart = {
+      type: "tool-searchPages",
+      state: "output-available",
+      output: [
+        { id: "p1", title: "First" },
+        { id: "p2", title: "Second" },
+      ],
+    };
+    expect(toolCitations(part)).toEqual([
+      { pageId: "p1", title: "First", href: "/p/p1" },
+      { pageId: "p2", title: "Second", href: "/p/p2" },
+    ]);
+  });
+
+  it("drops searchPages items missing an id", () => {
+    const part: ToolUiPart = {
+      type: "tool-searchPages",
+      state: "output-available",
+      output: [{ title: "No id here" }, { id: "p2", title: "Kept" }],
+    };
+    expect(toolCitations(part)).toEqual([
+      { pageId: "p2", title: "Kept", href: "/p/p2" },
+    ]);
+  });
+
+  it("falls back to input.pageId / input.title for a page-op with only pageId", () => {
+    // The mutating tools echo `pageId` (no `id`); title is taken from the input.
+    const part: ToolUiPart = {
+      type: "tool-updatePageContent",
+      state: "output-available",
+      input: { pageId: "host-1", title: "From input" },
+      output: { pageId: "host-1" },
+    };
+    expect(toolCitations(part)).toEqual([
+      { pageId: "host-1", title: "From input", href: "/p/host-1" },
+    ]);
+  });
+
+  it("prefers output.id over input.pageId when both exist", () => {
+    const part: ToolUiPart = {
+      type: "tool-getPage",
+      state: "output-available",
+      input: { pageId: "input-id", title: "Input title" },
+      output: { id: "output-id", title: "Output title" },
+    };
+    expect(toolCitations(part)).toEqual([
+      { pageId: "output-id", title: "Output title", href: "/p/output-id" },
+    ]);
+  });
+
+  it("returns [] when the state is not output-available", () => {
+    const part: ToolUiPart = {
+      type: "tool-getPage",
+      state: "input-available",
+      output: { id: "p1", title: "Pending" },
+    };
+    expect(toolCitations(part)).toEqual([]);
+  });
+
+  it("returns [] for a page-op output with no resolvable id", () => {
+    const part: ToolUiPart = {
+      type: "tool-getPage",
+      state: "output-available",
+      input: {},
+      output: { title: "Only a title" },
+    };
+    expect(toolCitations(part)).toEqual([]);
+  });
+});
+
+describe("toolRunState", () => {
+  it('maps "output-error" to error', () => {
+    expect(toolRunState("output-error")).toBe("error");
+  });
+
+  it('maps "output-denied" to error', () => {
+    expect(toolRunState("output-denied")).toBe("error");
+  });
+
+  it('maps "output-available" to done', () => {
+    expect(toolRunState("output-available")).toBe("done");
+  });
+
+  it('maps "input-available" to running', () => {
+    expect(toolRunState("input-available")).toBe("running");
+  });
+
+  it("maps undefined to running", () => {
+    expect(toolRunState(undefined)).toBe("running");
+  });
+});
diff --git a/apps/client/src/features/editor/components/html-embed/html-embed-view.tsx b/apps/client/src/features/editor/components/html-embed/html-embed-view.tsx
index a46b383a..273fbaff 100644
--- a/apps/client/src/features/editor/components/html-embed/html-embed-view.tsx
+++ b/apps/client/src/features/editor/components/html-embed/html-embed-view.tsx
@@ -15,39 +15,11 @@ import { useAtomValue } from "jotai";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import classes from "./html-embed-view.module.css";
-
-/**
- * Inject raw HTML (including <script> tags) into `container`, executing any
- * scripts.
- *
- * Setting `innerHTML` does NOT run inline or external <script> tags the browser
- * parses that way: the HTML spec marks scripts inserted via innerHTML as
- * "already started" so they never execute. To get the tracker/analytics
- * use-case working we walk the freshly-parsed scripts and replace each with a
- * brand-new <script> element copying its attributes and inline code. A
- * programmatically created+inserted <script> DOES execute, so this restores
- * normal script behaviour in the wiki origin (Variant C).
- */
-function renderRawHtml(container: HTMLElement, source: string) {
-  // Clear any previous render (re-render on source change).
-  container.innerHTML = "";
-  if (!source) return;
-
-  container.innerHTML = source;
-
-  const scripts = Array.from(container.querySelectorAll("script"));
-  for (const oldScript of scripts) {
-    const newScript = document.createElement("script");
-    // Copy every attribute (src, type, async, defer, data-*, etc.).
-    for (const attr of Array.from(oldScript.attributes)) {
-      newScript.setAttribute(attr.name, attr.value);
-    }
-    // Copy inline code.
-    newScript.text = oldScript.textContent ?? "";
-    // Replacing the node in place triggers execution.
-    oldScript.parentNode?.replaceChild(newScript, oldScript);
-  }
-}
+import {
+  canEdit as computeCanEdit,
+  renderRawHtml,
+  shouldExecute as computeShouldExecute,
+} from "./render-raw-html.ts";
 
 export default function HtmlEmbedView(props: NodeViewProps) {
   const { t } = useTranslation();
@@ -70,7 +42,10 @@ export default function HtmlEmbedView(props: NodeViewProps) {
   //    here — we execute exactly the `source` the server chose to serve.
   //  - EDITABLE editor (admin authoring): keep gating on the per-workspace
   //    toggle so an admin sees the inert placeholder when the feature is OFF.
-  const shouldExecute = !editor.isEditable || htmlEmbedEnabled;
+  const shouldExecute = computeShouldExecute(
+    editor.isEditable,
+    htmlEmbedEnabled,
+  );
 
   const contentRef = useRef<HTMLDivElement | null>(null);
   const [modalOpen, setModalOpen] = useState(false);
@@ -104,7 +79,7 @@ export default function HtmlEmbedView(props: NodeViewProps) {
   // The edit affordance is only meaningful in edit mode, is restricted to admins
   // (the server strips the node for non-admins anyway), and is offered only when
   // the workspace feature toggle is ON.
-  const canEdit = editor.isEditable && isAdmin && htmlEmbedEnabled;
+  const canEdit = computeCanEdit(editor.isEditable, isAdmin, htmlEmbedEnabled);
 
   return (
     <NodeViewWrapper
diff --git a/apps/client/src/features/editor/components/html-embed/render-raw-html.test.ts b/apps/client/src/features/editor/components/html-embed/render-raw-html.test.ts
new file mode 100644
index 00000000..324d6bb9
--- /dev/null
+++ b/apps/client/src/features/editor/components/html-embed/render-raw-html.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { JSDOM } from "jsdom";
+import { renderRawHtml, shouldExecute, canEdit } from "./render-raw-html";
+
+// jsdom does NOT execute <script> nodes unless its instance was created with
+// `runScripts: "dangerously"`. The whole point of renderRawHtml is to make
+// re-created scripts run, so the execution tests drive a dedicated script-
+// running JSDOM and pass it a container from THAT document (renderRawHtml uses
+// `container.ownerDocument`, so it creates the fresh scripts in the running
+// instance). The default vitest jsdom (no runScripts) is used for the
+// structural and policy assertions.
+describe("renderRawHtml (script execution against a runScripts jsdom)", () => {
+  let dom: JSDOM;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    dom = new JSDOM("<!doctype html><html><body></body></html>", {
+      runScripts: "dangerously",
+    });
+    container = dom.window.document.createElement("div");
+    dom.window.document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    dom.window.close();
+  });
+
+  it("re-creates and executes an inline <script> (observable side effect)", () => {
+    renderRawHtml(
+      container,
+      "<div>hello</div><script>window.__htmlEmbedFlag = true;</script>",
+    );
+    // The re-created inline script ran inside the jsdom window.
+    expect((dom.window as unknown as Record<string, unknown>).__htmlEmbedFlag).toBe(
+      true,
+    );
+    // The non-script markup is preserved.
+    expect(container.querySelector("div")?.textContent).toBe("hello");
+  });
+
+  it("copies src/async/defer onto a re-created external <script src>", () => {
+    renderRawHtml(
+      container,
+      '<script src="https://example.com/t.js" async defer></script>',
+    );
+    const script = container.querySelector("script");
+    expect(script).not.toBeNull();
+    expect(script?.getAttribute("src")).toBe("https://example.com/t.js");
+    expect(script?.hasAttribute("async")).toBe(true);
+    expect(script?.hasAttribute("defer")).toBe(true);
+  });
+
+  it("clears the container when the source is empty", () => {
+    container.innerHTML = "<p>stale</p>";
+    renderRawHtml(container, "");
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("clears prior content first on a re-render with new source", () => {
+    const win = dom.window as unknown as Record<string, unknown>;
+    renderRawHtml(
+      container,
+      "<span id='first'>one</span><script>window.__htmlEmbedCount = 1;</script>",
+    );
+    expect(win.__htmlEmbedCount).toBe(1);
+    expect(container.querySelector("#first")).not.toBeNull();
+
+    renderRawHtml(
+      container,
+      "<span id='second'>two</span><script>window.__htmlEmbedCount = 2;</script>",
+    );
+    // Prior content is gone; only the new render remains.
+    expect(container.querySelector("#first")).toBeNull();
+    expect(container.querySelector("#second")).not.toBeNull();
+    expect(win.__htmlEmbedCount).toBe(2);
+  });
+});
+
+describe("shouldExecute (execution policy)", () => {
+  it("read-only executes regardless of the workspace toggle", () => {
+    // isEditable=false → the server already gated the content.
+    expect(shouldExecute(false, false)).toBe(true);
+    expect(shouldExecute(false, true)).toBe(true);
+  });
+
+  it("editable + toggle OFF does NOT execute", () => {
+    expect(shouldExecute(true, false)).toBe(false);
+  });
+
+  it("editable + toggle ON executes", () => {
+    expect(shouldExecute(true, true)).toBe(true);
+  });
+});
+
+describe("canEdit (edit policy)", () => {
+  it("a member (non-admin) can never edit", () => {
+    expect(canEdit(true, false, true)).toBe(false);
+    expect(canEdit(false, false, true)).toBe(false);
+  });
+
+  it("an admin with the toggle OFF cannot edit", () => {
+    expect(canEdit(true, true, false)).toBe(false);
+  });
+
+  it("an admin with the toggle ON in editable mode can edit", () => {
+    expect(canEdit(true, true, true)).toBe(true);
+  });
+
+  it("an admin in read-only mode cannot edit (no edit affordance)", () => {
+    expect(canEdit(false, true, true)).toBe(false);
+  });
+});
diff --git a/apps/client/src/features/editor/components/html-embed/render-raw-html.ts b/apps/client/src/features/editor/components/html-embed/render-raw-html.ts
new file mode 100644
index 00000000..1b035aa6
--- /dev/null
+++ b/apps/client/src/features/editor/components/html-embed/render-raw-html.ts
@@ -0,0 +1,73 @@
+/**
+ * Pure DOM helpers for the HTML embed node view. Kept out of the React
+ * component so the script re-creation/execution mechanism and the execution/
+ * edit policy can be unit-tested against a bare jsdom container with no
+ * Tiptap/Mantine providers.
+ */
+
+/**
+ * Inject raw HTML (including <script> tags) into `container`, executing any
+ * scripts.
+ *
+ * Setting `innerHTML` does NOT run inline or external <script> tags the browser
+ * parses that way: the HTML spec marks scripts inserted via innerHTML as
+ * "already started" so they never execute. To get the tracker/analytics
+ * use-case working we walk the freshly-parsed scripts and replace each with a
+ * brand-new <script> element copying its attributes and inline code. A
+ * programmatically created+inserted <script> DOES execute, so this restores
+ * normal script behaviour in the wiki origin (Variant C).
+ */
+export function renderRawHtml(container: HTMLElement, source: string): void {
+  // Clear any previous render (re-render on source change).
+  container.innerHTML = "";
+  if (!source) return;
+
+  container.innerHTML = source;
+
+  // Use the container's own document so the helper works against any document
+  // (the live page or a standalone jsdom instance in tests), not just the
+  // ambient global `document`.
+  const doc = container.ownerDocument;
+  const scripts = Array.from(container.querySelectorAll("script"));
+  for (const oldScript of scripts) {
+    const newScript = doc.createElement("script");
+    // Copy every attribute (src, type, async, defer, data-*, etc.).
+    for (const attr of Array.from(oldScript.attributes)) {
+      newScript.setAttribute(attr.name, attr.value);
+    }
+    // Copy inline code.
+    newScript.text = oldScript.textContent ?? "";
+    // Replacing the node in place triggers execution.
+    oldScript.parentNode?.replaceChild(newScript, oldScript);
+  }
+}
+
+/**
+ * Execution policy split by editor mode:
+ *  - READ-ONLY / public-share view: the SERVER already decided whether to
+ *    include the embed (it strips htmlEmbed from shared content when the
+ *    workspace toggle is OFF). An anonymous viewer has no workspace and thus
+ *    reads `featureEnabled` as false, so we must NOT gate execution on it here
+ *    — we execute exactly the `source` the server chose to serve.
+ *  - EDITABLE editor (admin authoring): keep gating on the per-workspace toggle
+ *    so an admin sees the inert placeholder when the feature is OFF.
+ */
+export function shouldExecute(
+  isEditable: boolean,
+  featureEnabled: boolean,
+): boolean {
+  return !isEditable || featureEnabled;
+}
+
+/**
+ * The edit affordance is only meaningful in edit mode, is restricted to admins
+ * (the server strips the node for non-admins anyway), and is offered only when
+ * the workspace feature toggle is ON.
+ */
+export function canEdit(
+  isEditable: boolean,
+  isAdmin: boolean,
+  featureEnabled: boolean,
+): boolean {
+  return isEditable && isAdmin && featureEnabled;
+}
diff --git a/apps/client/src/features/editor/components/page-embed/decide-embed-state.test.ts b/apps/client/src/features/editor/components/page-embed/decide-embed-state.test.ts
new file mode 100644
index 00000000..b4129132
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/decide-embed-state.test.ts
@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { decideEmbedState } from "./decide-embed-state";
+import { PAGE_EMBED_MAX_DEPTH } from "./page-embed-ancestry-context";
+import type { PageTemplateLookup } from "@/features/page-embed/types/page-embed.types";
+
+const okResult: PageTemplateLookup = {
+  sourcePageId: "p1",
+  slugId: "slug-p1",
+  title: "Template",
+  icon: null,
+  content: { type: "doc" },
+  sourceUpdatedAt: "2026-01-01T00:00:00.000Z",
+};
+
+describe("decideEmbedState", () => {
+  it("returns no_source when sourcePageId is null", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: null,
+        chain: [],
+        hostPageId: null,
+        available: true,
+        result: null,
+      }),
+    ).toBe("no_source");
+  });
+
+  it("returns cycle when sourcePageId is already in the ancestor chain", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: ["root", "p1"],
+        hostPageId: "host",
+        available: true,
+        result: okResult,
+      }),
+    ).toBe("cycle");
+  });
+
+  it("returns cycle when sourcePageId equals the host page id (top-level self-embed)", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "host",
+        chain: [],
+        hostPageId: "host",
+        available: true,
+        result: okResult,
+      }),
+    ).toBe("cycle");
+  });
+
+  it("returns too_deep when chain length reaches PAGE_EMBED_MAX_DEPTH", () => {
+    const chain = Array.from({ length: PAGE_EMBED_MAX_DEPTH }, (_, i) => `a${i}`);
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain,
+        hostPageId: "host",
+        available: true,
+        result: okResult,
+      }),
+    ).toBe("too_deep");
+  });
+
+  it("cycle wins over too_deep when both apply (cycle checked first)", () => {
+    const chain = Array.from(
+      { length: PAGE_EMBED_MAX_DEPTH },
+      (_, i) => `a${i}`,
+    );
+    chain[0] = "p1"; // also a cycle
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain,
+        hostPageId: "host",
+        available: true,
+        result: okResult,
+      }),
+    ).toBe("cycle");
+  });
+
+  it("returns unavailable when no lookup context is mounted", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: [],
+        hostPageId: "host",
+        available: false,
+        result: null,
+      }),
+    ).toBe("unavailable");
+  });
+
+  it("returns loading when available but the result is not back yet", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: [],
+        hostPageId: "host",
+        available: true,
+        result: null,
+      }),
+    ).toBe("loading");
+  });
+
+  it("returns no_access when the result status is no_access", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: [],
+        hostPageId: "host",
+        available: true,
+        result: { sourcePageId: "p1", status: "no_access" },
+      }),
+    ).toBe("no_access");
+  });
+
+  it("returns not_found when the result status is not_found", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: [],
+        hostPageId: "host",
+        available: true,
+        result: { sourcePageId: "p1", status: "not_found" },
+      }),
+    ).toBe("not_found");
+  });
+
+  it("returns ok for a resolved template (happy path)", () => {
+    expect(
+      decideEmbedState({
+        sourcePageId: "p1",
+        chain: [],
+        hostPageId: "host",
+        available: true,
+        result: okResult,
+      }),
+    ).toBe("ok");
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/decide-embed-state.ts b/apps/client/src/features/editor/components/page-embed/decide-embed-state.ts
new file mode 100644
index 00000000..fc72f46e
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/decide-embed-state.ts
@@ -0,0 +1,58 @@
+import { PAGE_EMBED_MAX_DEPTH } from "./page-embed-ancestry-context";
+import type { PageTemplateLookup } from "@/features/page-embed/types/page-embed.types";
+
+/**
+ * The render outcome of a single pageEmbed node, decided BEFORE rendering a
+ * nested editor. Kept pure (no React) so the cycle / depth / access / not-found
+ * branch logic is unit-testable in isolation; the node view maps each outcome
+ * to a placeholder or the embedded content.
+ */
+export type EmbedState =
+  | "no_source" // no sourcePageId picked yet
+  | "cycle" // self-embed or an ancestor already shows this page
+  | "too_deep" // nesting depth limit reached
+  | "unavailable" // no lookup context (e.g. public share)
+  | "loading" // context present, result not back yet
+  | "ok" // resolved template content to render
+  | "no_access" // server says the viewer can't see the page
+  | "not_found"; // server says the page no longer exists
+
+export interface DecideEmbedStateInput {
+  sourcePageId: string | null;
+  /** sourcePageIds of every ancestor pageEmbed up the render tree. */
+  chain: string[];
+  /** Host page id; a top-level self-embed must be caught against it. */
+  hostPageId: string | null;
+  /** Whether a lookup context is mounted (false on public shares in MVP). */
+  available: boolean;
+  /** The lookup result, or null while still loading. */
+  result: PageTemplateLookup | null;
+}
+
+/**
+ * Decide what a pageEmbed should render. The order matters: cycle and depth
+ * guards run first (before any lookup is even consulted), then availability,
+ * then the resolved result. Mirrors the branch ladder in PageEmbedBody.
+ */
+export function decideEmbedState({
+  sourcePageId,
+  chain,
+  hostPageId,
+  available,
+  result,
+}: DecideEmbedStateInput): EmbedState {
+  if (!sourcePageId) return "no_source";
+
+  // Self-embed or a source already present in the ancestor chain → cycle.
+  const isCycle = chain.includes(sourcePageId) || hostPageId === sourcePageId;
+  if (isCycle) return "cycle";
+
+  if (chain.length >= PAGE_EMBED_MAX_DEPTH) return "too_deep";
+
+  if (!available) return "unavailable";
+  if (!result) return "loading";
+
+  if (!("status" in result)) return "ok";
+  if (result.status === "no_access") return "no_access";
+  return "not_found";
+}
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
new file mode 100644
index 00000000..6b9f3e27
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-ancestry-context.test.tsx
@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import {
+  PageEmbedAncestryProvider,
+  usePageEmbedAncestry,
+} from "./page-embed-ancestry-context";
+
+// Probe child: renders the current ancestry context value as JSON so the test
+// can assert on the accumulated chain and host without any Tiptap editor.
+function Probe({ testId }: { testId: string }) {
+  const ancestry = usePageEmbedAncestry();
+  return <div data-testid={testId}>{JSON.stringify(ancestry)}</div>;
+}
+
+function read(el: HTMLElement) {
+  return JSON.parse(el.textContent || "{}") as {
+    chain: string[];
+    hostPageId: string | null;
+  };
+}
+
+describe("PageEmbedAncestryProvider", () => {
+  it("accumulates the chain in order across nested providers", () => {
+    const { getByTestId } = render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="host">
+        <PageEmbedAncestryProvider sourcePageId="b">
+          <PageEmbedAncestryProvider sourcePageId="c">
+            <Probe testId="leaf" />
+          </PageEmbedAncestryProvider>
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const value = read(getByTestId("leaf"));
+    expect(value.chain).toEqual(["a", "b", "c"]);
+    expect(value.hostPageId).toBe("host");
+  });
+
+  it("leaves the chain unchanged when sourcePageId is absent, still propagating the host", () => {
+    const { getByTestId } = render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="host">
+        <PageEmbedAncestryProvider>
+          <Probe testId="leaf" />
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const value = read(getByTestId("leaf"));
+    expect(value.chain).toEqual(["a"]);
+    expect(value.hostPageId).toBe("host");
+  });
+
+  it("keeps the first (top-level) host even if an inner provider passes a different one", () => {
+    const { getByTestId } = render(
+      <PageEmbedAncestryProvider sourcePageId="a" hostPageId="top-host">
+        <PageEmbedAncestryProvider sourcePageId="b" hostPageId="inner-host">
+          <Probe testId="leaf" />
+        </PageEmbedAncestryProvider>
+      </PageEmbedAncestryProvider>,
+    );
+    const value = read(getByTestId("leaf"));
+    expect(value.chain).toEqual(["a", "b"]);
+    // Inner host is ignored: the top-level host is set once and propagated.
+    expect(value.hostPageId).toBe("top-host");
+  });
+
+  it("defaults to an empty chain and null host with no provider", () => {
+    const { getByTestId } = render(<Probe testId="leaf" />);
+    const value = read(getByTestId("leaf"));
+    expect(value.chain).toEqual([]);
+    expect(value.hostPageId).toBeNull();
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.test.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.test.tsx
new file mode 100644
index 00000000..44a5a413
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-lookup-context.test.tsx
@@ -0,0 +1,162 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+} from "vitest";
+import { act, render } from "@testing-library/react";
+import type { PageTemplateLookup } from "@/features/page-embed/types/page-embed.types";
+
+// Mock the API module the provider calls. Hoisted by vitest before the import.
+const lookupTemplate = vi.fn();
+vi.mock("@/features/page-embed/services/page-embed-api", () => ({
+  lookupTemplate: (...args: unknown[]) => lookupTemplate(...args),
+}));
+
+// Imported AFTER the mock is declared so the provider picks up the mock.
+import {
+  PageEmbedLookupProvider,
+  usePageEmbedLookup,
+} from "./page-embed-lookup-context";
+
+function ok(id: string): PageTemplateLookup {
+  return {
+    sourcePageId: id,
+    slugId: `slug-${id}`,
+    title: `T-${id}`,
+    icon: null,
+    content: { type: "doc" },
+    sourceUpdatedAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+// Probe that subscribes to a sourceId and exposes its latest result + refresh.
+function Probe({
+  id,
+  sink,
+}: {
+  id: string;
+  sink: (api: ReturnType<typeof usePageEmbedLookup>) => void;
+}) {
+  const api = usePageEmbedLookup(id);
+  sink(api);
+  return <div>{api.result ? "loaded" : "pending"}</div>;
+}
+
+describe("PageEmbedLookupProvider (batching / dedup / refresh)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    lookupTemplate.mockReset();
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+  });
+
+  it("dedups two subscribers for the same id into a single lookup call; both get the result", async () => {
+    let a: ReturnType<typeof usePageEmbedLookup> | null = null;
+    let b: ReturnType<typeof usePageEmbedLookup> | null = null;
+    lookupTemplate.mockResolvedValue({ items: [ok("p1")] });
+
+    render(
+      <PageEmbedLookupProvider>
+        <Probe id="p1" sink={(x) => (a = x)} />
+        <Probe id="p1" sink={(x) => (b = x)} />
+      </PageEmbedLookupProvider>,
+    );
+
+    // Subscriptions run in effects + the 10ms debounce batches them together.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(20);
+    });
+
+    expect(lookupTemplate).toHaveBeenCalledTimes(1);
+    expect(lookupTemplate).toHaveBeenCalledWith({ sourcePageIds: ["p1"] });
+    expect(a!.result).toEqual(ok("p1"));
+    expect(b!.result).toEqual(ok("p1"));
+  });
+
+  it("batches two distinct ids subscribed within the window into one call", async () => {
+    lookupTemplate.mockResolvedValue({ items: [ok("p1"), ok("p2")] });
+
+    render(
+      <PageEmbedLookupProvider>
+        <Probe id="p1" sink={() => {}} />
+        <Probe id="p2" sink={() => {}} />
+      </PageEmbedLookupProvider>,
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(20);
+    });
+
+    expect(lookupTemplate).toHaveBeenCalledTimes(1);
+    expect(lookupTemplate.mock.calls[0][0]).toEqual({
+      sourcePageIds: ["p1", "p2"],
+    });
+  });
+
+  it("refresh() clears the cache and re-fetches", async () => {
+    let a: ReturnType<typeof usePageEmbedLookup> | null = null;
+    lookupTemplate.mockResolvedValue({ items: [ok("p1")] });
+
+    render(
+      <PageEmbedLookupProvider>
+        <Probe id="p1" sink={(x) => (a = x)} />
+      </PageEmbedLookupProvider>,
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(20);
+    });
+    expect(lookupTemplate).toHaveBeenCalledTimes(1);
+
+    // refresh resolves once the next batch flush completes.
+    await act(async () => {
+      const p = a!.refresh();
+      await vi.advanceTimersByTimeAsync(20);
+      await p;
+    });
+
+    expect(lookupTemplate).toHaveBeenCalledTimes(2);
+  });
+
+  it("a rejected lookup resolves refresh() waiters, clears inFlight, and logs the error (not swallowed)", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    let a: ReturnType<typeof usePageEmbedLookup> | null = null;
+    lookupTemplate.mockRejectedValueOnce(new Error("boom"));
+
+    render(
+      <PageEmbedLookupProvider>
+        <Probe id="p1" sink={(x) => (a = x)} />
+      </PageEmbedLookupProvider>,
+    );
+
+    // Initial subscription enqueues a lookup that rejects.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(20);
+    });
+
+    expect(errSpy).toHaveBeenCalled();
+    // The error message is surfaced, not swallowed.
+    expect(errSpy.mock.calls[0][0]).toContain("[pageEmbed] template lookup failed");
+
+    // inFlight was cleared on failure, so a refresh re-enqueues and resolves.
+    lookupTemplate.mockResolvedValueOnce({ items: [ok("p1")] });
+    let resolved = false;
+    await act(async () => {
+      const p = a!.refresh().then(() => {
+        resolved = true;
+      });
+      await vi.advanceTimersByTimeAsync(20);
+      await p;
+    });
+    expect(resolved).toBe(true);
+    expect(a!.result).toEqual(ok("p1"));
+
+    errSpy.mockRestore();
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
index 7648b05e..05be42b1 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-picker.tsx
@@ -6,6 +6,7 @@ import { IconFileText, IconSearch } from "@tabler/icons-react";
 import type { Editor, Range } from "@tiptap/core";
 import { searchSuggestions } from "@/features/search/services/search-service";
 import type { IPage } from "@/features/page/types/page.types";
+import { buildPickerQuery, excludeHost } from "./page-embed-picker.utils";
 
 export const PAGE_EMBED_PICKER_EVENT = "open-page-embed-picker";
 
@@ -43,21 +44,13 @@ export default function PageEmbedPicker() {
 
   const { data, isFetching } = useQuery({
     queryKey: ["page-embed-template-picker", query],
-    queryFn: () =>
-      searchSuggestions({
-        query,
-        includePages: true,
-        onlyTemplates: true,
-        limit: 20,
-      }),
+    queryFn: () => searchSuggestions(buildPickerQuery(query)),
     enabled: opened,
     staleTime: 30 * 1000,
   });
 
   const hostPageId = detailRef.current?.hostPageId;
-  const pages = ((data?.pages ?? []) as IPage[]).filter(
-    (p) => p && p.id !== hostPageId,
-  );
+  const pages = excludeHost((data?.pages ?? []) as IPage[], hostPageId);
 
   const handleSelect = (page: IPage) => {
     const detail = detailRef.current;
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.test.ts b/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.test.ts
new file mode 100644
index 00000000..18a2b06c
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { excludeHost, buildPickerQuery } from "./page-embed-picker.utils";
+import type { IPage } from "@/features/page/types/page.types";
+
+function page(id: string): IPage {
+  return { id, title: id, slugId: `slug-${id}` } as IPage;
+}
+
+describe("excludeHost", () => {
+  it("drops the host page from the results (self-embed guard)", () => {
+    const result = excludeHost([page("a"), page("host"), page("b")], "host");
+    expect(result.map((p) => p.id)).toEqual(["a", "b"]);
+  });
+
+  it("returns all pages when hostPageId is undefined", () => {
+    const result = excludeHost([page("a"), page("b")], undefined);
+    expect(result.map((p) => p.id)).toEqual(["a", "b"]);
+  });
+
+  it("drops null/blank entries", () => {
+    const result = excludeHost(
+      [page("a"), null as unknown as IPage, page("b")],
+      "host",
+    );
+    expect(result.map((p) => p.id)).toEqual(["a", "b"]);
+  });
+});
+
+describe("buildPickerQuery", () => {
+  it("passes onlyTemplates:true with the query and page inclusion", () => {
+    expect(buildPickerQuery("foo")).toEqual({
+      query: "foo",
+      includePages: true,
+      onlyTemplates: true,
+      limit: 20,
+    });
+  });
+
+  it("preserves an empty query", () => {
+    expect(buildPickerQuery("").query).toBe("");
+    expect(buildPickerQuery("").onlyTemplates).toBe(true);
+  });
+});
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.ts b/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.ts
new file mode 100644
index 00000000..a5c48706
--- /dev/null
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-picker.utils.ts
@@ -0,0 +1,27 @@
+import type { IPage } from "@/features/page/types/page.types";
+import type { SearchSuggestionParams } from "@/features/search/types/search.types";
+
+/**
+ * Self-embed guard at insertion time: drop the host page (and any null/blank
+ * entries) from the picker results so the current page can't embed itself.
+ */
+export function excludeHost(
+  pages: IPage[],
+  hostPageId: string | undefined,
+): IPage[] {
+  return pages.filter((p) => p && p.id !== hostPageId);
+}
+
+/**
+ * Build the search-suggestions query for the template picker. Always restricts
+ * to template-flagged pages (`onlyTemplates`) and includes pages, mirroring the
+ * inline query args in PageEmbedPicker.
+ */
+export function buildPickerQuery(query: string): SearchSuggestionParams {
+  return {
+    query,
+    includePages: true,
+    onlyTemplates: true,
+    limit: 20,
+  };
+}
diff --git a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
index 63890eec..9a308bf6 100644
--- a/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
+++ b/apps/client/src/features/editor/components/page-embed/page-embed-view.tsx
@@ -21,8 +21,8 @@ import { usePageEmbedLookup } from "./page-embed-lookup-context";
 import {
   PageEmbedAncestryProvider,
   usePageEmbedAncestry,
-  PAGE_EMBED_MAX_DEPTH,
 } from "./page-embed-ancestry-context";
+import { decideEmbedState } from "./decide-embed-state";
 import PageEmbedContent from "./page-embed-content";
 
 function Placeholder({
@@ -99,13 +99,15 @@ function PageEmbedBody({
     }
   };
 
-  // --- Cycle / depth guard (evaluated before any lookup is rendered) ---------
-  // Self-embed or a source already present in the ancestor chain → cycle.
-  const isCycle =
-    !!sourcePageId &&
-    (ancestry.chain.includes(sourcePageId) ||
-      ancestry.hostPageId === sourcePageId);
-  const isTooDeep = ancestry.chain.length >= PAGE_EMBED_MAX_DEPTH;
+  // --- Cycle / depth / availability decision (pure, unit-tested) ------------
+  // Evaluated before any nested editor is rendered.
+  const embedState = decideEmbedState({
+    sourcePageId,
+    chain: ancestry.chain,
+    hostPageId: ancestry.hostPageId,
+    available,
+    result,
+  });
 
   const sourceTitle =
     result && !("status" in result) ? result.title : null;
@@ -187,28 +189,28 @@ function PageEmbedBody({
     ) : null;
 
   let body: React.ReactNode;
-  if (!sourcePageId) {
+  if (embedState === "no_source") {
     body = (
       <Placeholder
         icon={<IconInfoCircle size={18} stroke={1.6} />}
         label={t("No page selected")}
       />
     );
-  } else if (isCycle) {
+  } else if (embedState === "cycle") {
     body = (
       <Placeholder
         icon={<IconRepeat size={18} stroke={1.6} />}
         label={t("Circular embed: this page is already shown above")}
       />
     );
-  } else if (isTooDeep) {
+  } else if (embedState === "too_deep") {
     body = (
       <Placeholder
         icon={<IconRepeat size={18} stroke={1.6} />}
         label={t("Embed nesting limit reached")}
       />
     );
-  } else if (!available) {
+  } else if (embedState === "unavailable") {
     // No lookup context (e.g. public share) → placeholder, no fetch in MVP.
     body = (
       <Placeholder
@@ -216,9 +218,9 @@ function PageEmbedBody({
         label={t("Embedded page is not available here")}
       />
     );
-  } else if (!result) {
+  } else if (embedState === "loading") {
     body = <div style={{ minHeight: 24 }} />;
-  } else if (!("status" in result)) {
+  } else if (embedState === "ok" && result && !("status" in result)) {
     body = (
       <PageEmbedAncestryProvider
         sourcePageId={sourcePageId}
@@ -227,7 +229,7 @@ function PageEmbedBody({
         <PageEmbedContent content={result.content} />
       </PageEmbedAncestryProvider>
     );
-  } else if (result.status === "no_access") {
+  } else if (embedState === "no_access") {
     body = (
       <Placeholder
         icon={<IconEyeOff size={18} stroke={1.6} />}
diff --git a/apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx b/apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx
new file mode 100644
index 00000000..7f0e4313
--- /dev/null
+++ b/apps/client/src/features/page/tree/components/space-tree.expand-all.test.tsx
@@ -0,0 +1,228 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createRef } from "react";
+import { render, waitFor, cleanup } from "@testing-library/react";
+
+// --- Mocks for the heavy / networked module graph ---------------------------
+// SpaceTree pulls in query hooks, page services, i18n, notifications and two
+// child render components. The expandAll contract is exercised purely through
+// the imperative ref, so we mock everything that would otherwise need a real
+// server / router and stub the visual children to empty renders.
+
+const getSpaceTreeMock = vi.fn();
+const notificationsShowMock = vi.fn();
+
+vi.mock("@/features/page/services/page-service.ts", () => ({
+  getSpaceTree: (...args: unknown[]) => getSpaceTreeMock(...args),
+  getPageBreadcrumbs: vi.fn(),
+}));
+
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  // No root pages and no further pages — the data-load effect is inert so the
+  // test fully controls the tree through expandAll.
+  useGetRootSidebarPagesQuery: () => ({
+    data: undefined,
+    hasNextPage: false,
+    fetchNextPage: vi.fn(),
+    isFetching: false,
+  }),
+  usePageQuery: () => ({ data: undefined }),
+  fetchAllAncestorChildren: vi.fn(),
+}));
+
+vi.mock("@/features/page/tree/hooks/use-tree-mutation.ts", () => ({
+  useTreeMutation: () => ({ handleMove: vi.fn() }),
+}));
+
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: (...args: unknown[]) => notificationsShowMock(...args) },
+}));
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("react-router-dom", () => ({
+  useParams: () => ({ pageSlug: undefined }),
+}));
+
+vi.mock("@/lib", () => ({
+  extractPageSlugId: () => undefined,
+}));
+
+vi.mock("@/lib/config.ts", () => ({
+  isCompactPageTreeEnabled: () => false,
+}));
+
+// Stub the visual children so we don't drag in the full DnD / Mantine stack.
+vi.mock("./doc-tree", () => ({
+  DocTree: () => null,
+  ROW_HEIGHT_COMPACT: 28,
+  ROW_HEIGHT_STANDARD: 32,
+}));
+vi.mock("./space-tree-row", () => ({
+  SpaceTreeRow: () => null,
+}));
+
+vi.mock("@mantine/core", () => ({
+  Text: ({ children }: { children?: unknown }) => children ?? null,
+}));
+
+// The real openTreeNodesAtom is localStorage-backed (atomWithStorage +
+// getOnInit), which crashes under jsdom's localStorage shim here. Swap in a
+// plain in-memory atom with the same read value (OpenMap) and the same setter
+// shape (value OR functional updater) so the component's open-state logic runs
+// unchanged while staying inside the test store.
+vi.mock("@/features/page/tree/atoms/open-tree-nodes-atom.ts", async () => {
+  const { atom } = await import("jotai");
+  type OpenMap = Record<string, boolean>;
+  const base = atom<OpenMap>({});
+  const openTreeNodesAtom = atom(
+    (get) => get(base),
+    (get, set, update: OpenMap | ((prev: OpenMap) => OpenMap)) => {
+      const next =
+        typeof update === "function"
+          ? (update as (prev: OpenMap) => OpenMap)(get(base))
+          : update;
+      set(base, next);
+    },
+  );
+  return { openTreeNodesAtom };
+});
+
+import SpaceTree, { SpaceTreeApi } from "./space-tree";
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { openTreeNodesAtom } from "@/features/page/tree/atoms/open-tree-nodes-atom.ts";
+import { createStore, Provider } from "jotai";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+// A flat space-tree response (parentPageId pointers) that buildTree +
+// buildTreeWithChildren nest into a multi-level tree. Depth > 1 lets us assert
+// expandAll never fans out into per-branch fetches (no N+1).
+function spaceTreeItems(): SpaceTreeNode[] {
+  const n = (
+    id: string,
+    parentPageId: string | null,
+    position: string,
+  ): SpaceTreeNode => ({
+    id,
+    slugId: `slug-${id}`,
+    name: id,
+    icon: undefined,
+    position,
+    spaceId: "space-1",
+    parentPageId: parentPageId as unknown as string,
+    hasChildren: false,
+    children: [],
+  });
+  return [
+    n("root", null, "a0"),
+    n("branch", "root", "a1"),
+    n("leaf", "branch", "a1"),
+  ];
+}
+
+function renderTree(store: ReturnType<typeof createStore>) {
+  const ref = createRef<SpaceTreeApi>();
+  render(
+    <Provider store={store}>
+      <SpaceTree ref={ref} spaceId="space-1" readOnly={false} />
+    </Provider>,
+  );
+  return ref;
+}
+
+beforeEach(() => {
+  getSpaceTreeMock.mockReset();
+  notificationsShowMock.mockReset();
+  // jsdom's localStorage shim here lacks `clear`; guard it. Each test uses a
+  // fresh jotai store anyway, so cross-test open-state never leaks.
+  try {
+    localStorage.clear?.();
+  } catch {
+    /* ignore — fresh store per test isolates state */
+  }
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("SpaceTree.expandAll (integration via ref)", () => {
+  it("makes exactly ONE getSpaceTree call regardless of depth (no N+1)", async () => {
+    getSpaceTreeMock.mockResolvedValue(spaceTreeItems());
+    const store = createStore();
+    const ref = renderTree(store);
+
+    await ref.current!.expandAll();
+
+    expect(getSpaceTreeMock).toHaveBeenCalledTimes(1);
+    expect(getSpaceTreeMock).toHaveBeenCalledWith({ spaceId: "space-1" });
+
+    // Every branch node (root, branch) is opened; the leaf needs no entry.
+    const openMap = store.get(openTreeNodesAtom);
+    expect(openMap["root"]).toBe(true);
+    expect(openMap["branch"]).toBe(true);
+    expect(openMap["leaf"]).toBeUndefined();
+
+    // The full tree replaced the current-space nodes.
+    const data = store.get(treeDataAtom);
+    expect(data.map((d) => d.id)).toEqual(["root"]);
+  });
+
+  it("shows a notification and still resets isExpanding when getSpaceTree rejects", async () => {
+    getSpaceTreeMock.mockRejectedValue(new Error("boom"));
+    const store = createStore();
+    const ref = renderTree(store);
+
+    await ref.current!.expandAll();
+
+    expect(notificationsShowMock).toHaveBeenCalledTimes(1);
+    expect(notificationsShowMock).toHaveBeenCalledWith(
+      expect.objectContaining({ color: "red" }),
+    );
+
+    // isExpanding must be reset in the finally block even on failure.
+    await waitFor(() => {
+      expect(ref.current!.isExpanding).toBe(false);
+    });
+  });
+
+  it("aborts the merge when the space switches mid-flight", async () => {
+    // getSpaceTree resolves only after we flip the tree to a different space,
+    // simulating the user navigating away while the request is in flight.
+    let resolveTree: (v: SpaceTreeNode[]) => void = () => {};
+    getSpaceTreeMock.mockImplementation(
+      () =>
+        new Promise<SpaceTreeNode[]>((resolve) => {
+          resolveTree = resolve;
+        }),
+    );
+
+    const store = createStore();
+    const ref = createRef<SpaceTreeApi>();
+    const { rerender } = render(
+      <Provider store={store}>
+        <SpaceTree ref={ref} spaceId="space-1" readOnly={false} />
+      </Provider>,
+    );
+
+    const promise = ref.current!.expandAll();
+
+    // Switch the space mid-flight: spaceIdRef.current becomes "space-2".
+    rerender(
+      <Provider store={store}>
+        <SpaceTree ref={ref} spaceId="space-2" readOnly={false} />
+      </Provider>,
+    );
+
+    // Now resolve the in-flight request for the OLD space.
+    resolveTree(spaceTreeItems());
+    await promise;
+
+    // The merge must have been aborted: no tree data written, no branches opened.
+    expect(store.get(treeDataAtom)).toEqual([]);
+    const openMap = store.get(openTreeNodesAtom);
+    expect(openMap["root"]).toBeUndefined();
+    expect(openMap["branch"]).toBeUndefined();
+  });
+});
diff --git a/apps/client/src/features/page/tree/components/space-tree.tsx b/apps/client/src/features/page/tree/components/space-tree.tsx
index 7a8e0535..9a22f280 100644
--- a/apps/client/src/features/page/tree/components/space-tree.tsx
+++ b/apps/client/src/features/page/tree/components/space-tree.tsx
@@ -27,6 +27,8 @@ import {
   mergeRootTrees,
   collectAllIds,
   collectBranchIds,
+  openBranches,
+  closeIds,
 } from "@/features/page/tree/utils/utils.ts";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { treeModel } from "@/features/page/tree/model/tree-model";
@@ -236,11 +238,7 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
       // Open every branch node (node with children) of the current space only.
       const branchIds = collectBranchIds(fullTree);
 
-      setOpenTreeNodes((prev) => {
-        const next = { ...prev };
-        for (const id of branchIds) next[id] = true;
-        return next;
-      });
+      setOpenTreeNodes((prev) => openBranches(prev, branchIds));
     } catch (err: any) {
       // Never swallow: log full error + surface the real reason.
       console.error("[tree] expandAll failed", err);
@@ -261,11 +259,7 @@ const SpaceTree = forwardRef<SpaceTreeApi, SpaceTreeProps>(function SpaceTree(
     // other spaces' expanded state is left intact.
     const ids = collectAllIds(filteredData);
 
-    setOpenTreeNodes((prev) => {
-      const next = { ...prev };
-      for (const id of ids) next[id] = false;
-      return next;
-    });
+    setOpenTreeNodes((prev) => closeIds(prev, ids));
   }, [filteredData, setOpenTreeNodes]);
 
   useImperativeHandle(
diff --git a/apps/client/src/features/page/tree/model/tree-model.test.ts b/apps/client/src/features/page/tree/model/tree-model.test.ts
index 8f16c075..25c0bd1e 100644
--- a/apps/client/src/features/page/tree/model/tree-model.test.ts
+++ b/apps/client/src/features/page/tree/model/tree-model.test.ts
@@ -196,6 +196,17 @@ describe('treeModel.insertByPosition', () => {
     const t = treeModel.insertByPosition(roots, null, node);
     expect(t.map((n) => n.id)).toEqual(['a', 'b', 'c', 'x']);
   });
+
+  it('tie-break: a node whose position EQUALS a sibling lands deterministically (strict >)', () => {
+    // The insertion index is the first sibling whose position sorts STRICTLY
+    // after the new node's. An equal sibling is not strictly after, so it is
+    // skipped — the new node lands immediately AFTER every equal-position
+    // sibling and before the first strictly-greater one. This is deterministic:
+    // a tie always resolves the same way on every client.
+    const node: P = { id: 'x', name: 'X', position: 'a2' }; // equals b's position
+    const t = treeModel.insertByPosition(roots, null, node);
+    expect(t.map((n) => n.id)).toEqual(['a', 'b', 'x', 'c']);
+  });
 });
 
 // addTreeNode idempotency: the receiver early-returns when the node id already
@@ -692,4 +703,45 @@ describe('treeModel.move', () => {
     });
     expect(out.tree).toBe(fixture);
   });
+
+  it('cross-parent move does NOT apply the same-parent adjust (no off-by-one)', () => {
+    // Source `x3` sits at index 2 in parent `x`; target `y1` sits at index 0 in
+    // parent `y`. sourceInfo.index (2) > info.index (0) AND the parents differ,
+    // so the `sameParent && source.index < info.index` adjust must be 0 — the
+    // node must land at index 0 in `y`, not at index -1 (which would silently
+    // drop it at a wrong slot / off-by-one).
+    const crossFixture: N[] = [
+      {
+        id: 'x',
+        name: 'X',
+        children: [
+          { id: 'x1', name: 'X1' },
+          { id: 'x2', name: 'X2' },
+          { id: 'x3', name: 'X3' },
+        ],
+      },
+      {
+        id: 'y',
+        name: 'Y',
+        children: [
+          { id: 'y1', name: 'Y1' },
+          { id: 'y2', name: 'Y2' },
+        ],
+      },
+    ];
+    const { tree: t, result } = treeModel.move(crossFixture, 'x3', {
+      kind: 'reorder-before',
+      targetId: 'y1',
+    });
+    expect(result).toEqual({ parentId: 'y', index: 0 });
+    expect(treeModel.find(t, 'y')?.children?.map((n) => n.id)).toEqual([
+      'x3',
+      'y1',
+      'y2',
+    ]);
+    expect(treeModel.find(t, 'x')?.children?.map((n) => n.id)).toEqual([
+      'x1',
+      'x2',
+    ]);
+  });
 });
diff --git a/apps/client/src/features/page/tree/utils/utils.test.ts b/apps/client/src/features/page/tree/utils/utils.test.ts
index 7de43da1..14366b73 100644
--- a/apps/client/src/features/page/tree/utils/utils.test.ts
+++ b/apps/client/src/features/page/tree/utils/utils.test.ts
@@ -1,6 +1,14 @@
 import { describe, it, expect } from "vitest";
-import { buildTree } from "./utils";
+import {
+  buildTree,
+  buildTreeWithChildren,
+  collectAllIds,
+  collectBranchIds,
+  openBranches,
+  closeIds,
+} from "./utils";
 import type { IPage } from "@/features/page/types/page.types.ts";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
 
 function page(id: string, position: string): IPage {
   return {
@@ -15,6 +23,44 @@ function page(id: string, position: string): IPage {
   } as IPage;
 }
 
+// Flat SpaceTreeNode factory for buildTreeWithChildren (it consumes a flat list
+// with parentPageId pointers and nests them).
+function flatNode(
+  id: string,
+  parentPageId: string | null,
+  position: string,
+): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id.toUpperCase(),
+    icon: undefined,
+    position,
+    spaceId: "space-1",
+    parentPageId: parentPageId as unknown as string,
+    hasChildren: false,
+    children: [],
+  };
+}
+
+// Nested SpaceTreeNode factory for collectAllIds / collectBranchIds.
+function treeNode(
+  id: string,
+  children: SpaceTreeNode[] = [],
+): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id.toUpperCase(),
+    icon: undefined,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: children.length > 0,
+    children,
+  };
+}
+
 describe("buildTree", () => {
   it("builds one node per unique page", () => {
     const tree = buildTree([page("a", "a1"), page("b", "a2")]);
@@ -38,3 +84,192 @@ describe("buildTree", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 });
+
+describe("collectBranchIds", () => {
+  it("returns every node-with-children id in a multi-level tree", () => {
+    const tree = [
+      treeNode("root", [
+        treeNode("branch1", [treeNode("leaf1")]),
+        treeNode("leaf2"),
+      ]),
+      treeNode("root2", [treeNode("leaf3")]),
+    ];
+    expect(collectBranchIds(tree).sort()).toEqual([
+      "branch1",
+      "root",
+      "root2",
+    ]);
+  });
+
+  it("returns [] for a leaf-only tree", () => {
+    const tree = [treeNode("a"), treeNode("b"), treeNode("c")];
+    expect(collectBranchIds(tree)).toEqual([]);
+  });
+
+  it("does NOT include a node whose children is an empty array", () => {
+    // hasChildren-less / empty-children nodes are leaves for expansion purposes.
+    const tree = [treeNode("a", [])];
+    expect(collectBranchIds(tree)).toEqual([]);
+  });
+
+  it("returns every ancestor id in a deep single chain", () => {
+    const chain = treeNode("a", [
+      treeNode("b", [treeNode("c", [treeNode("d")])]),
+    ]);
+    // a, b, c are branches; d is the leaf.
+    expect(collectBranchIds([chain])).toEqual(["a", "b", "c"]);
+  });
+
+  it("returns [] for an empty tree", () => {
+    expect(collectBranchIds([])).toEqual([]);
+  });
+});
+
+describe("collectAllIds", () => {
+  it("returns every id (roots, branches, leaves)", () => {
+    const tree = [
+      treeNode("root", [
+        treeNode("branch1", [treeNode("leaf1")]),
+        treeNode("leaf2"),
+      ]),
+      treeNode("root2"),
+    ];
+    expect(collectAllIds(tree).sort()).toEqual([
+      "branch1",
+      "leaf1",
+      "leaf2",
+      "root",
+      "root2",
+    ]);
+  });
+
+  it("returns every id in a deep chain", () => {
+    const chain = treeNode("a", [
+      treeNode("b", [treeNode("c", [treeNode("d")])]),
+    ]);
+    expect(collectAllIds([chain])).toEqual(["a", "b", "c", "d"]);
+  });
+
+  it("returns [] for an empty tree", () => {
+    expect(collectAllIds([])).toEqual([]);
+  });
+
+  it("is a superset of collectBranchIds for the same tree (property)", () => {
+    const tree = [
+      treeNode("root", [
+        treeNode("branch1", [treeNode("leaf1"), treeNode("leaf2")]),
+        treeNode("branch2", [treeNode("leaf3")]),
+        treeNode("leaf4"),
+      ]),
+      treeNode("root2", [treeNode("leaf5")]),
+    ];
+    const all = new Set(collectAllIds(tree));
+    const branches = collectBranchIds(tree);
+    for (const id of branches) {
+      expect(all.has(id)).toBe(true);
+    }
+    // And the superset is strictly larger (it also has the leaves).
+    expect(all.size).toBeGreaterThan(branches.length);
+  });
+});
+
+describe("buildTreeWithChildren", () => {
+  it("nests a flat list and sorts siblings by position", () => {
+    // Provided out of position order to prove the sort.
+    const flat = [
+      flatNode("root", null, "a0"),
+      flatNode("c2", "root", "a4"),
+      flatNode("c1", "root", "a1"),
+    ];
+    const tree = buildTreeWithChildren(flat);
+    expect(tree.map((n) => n.id)).toEqual(["root"]);
+    expect(tree[0].children.map((n) => n.id)).toEqual(["c1", "c2"]);
+  });
+
+  it("recomputes hasChildren to true for nodes that gain children", () => {
+    // Parent ships with hasChildren=false; building must flip it true.
+    const flat = [
+      flatNode("root", null, "a0"),
+      flatNode("child", "root", "a1"),
+    ];
+    expect(flat[0].hasChildren).toBe(false);
+    const tree = buildTreeWithChildren(flat);
+    expect(tree[0].hasChildren).toBe(true);
+  });
+
+  it("treats a node whose parentPageId is ABSENT from the list as a root (no crash)", () => {
+    // Permission-trimmed response: `orphan`'s parent `missing` was filtered out
+    // server-side. The function must not throw and must surface the orphan as a
+    // root rather than dropping or crashing on it.
+    const flat = [
+      flatNode("root", null, "a0"),
+      flatNode("orphan", "missing", "a2"),
+    ];
+    let tree: SpaceTreeNode[] = [];
+    expect(() => {
+      tree = buildTreeWithChildren(flat);
+    }).not.toThrow();
+    expect(tree.map((n) => n.id).sort()).toEqual(["orphan", "root"]);
+  });
+});
+
+describe("openBranches", () => {
+  it("sets all given ids to true", () => {
+    const next = openBranches({}, ["a", "b", "c"]);
+    expect(next).toEqual({ a: true, b: true, c: true });
+  });
+
+  it("preserves pre-existing open ids and other-space ids", () => {
+    const prev = { existing: true, "other-space": true, closed: false };
+    const next = openBranches(prev, ["a"]);
+    expect(next).toEqual({
+      existing: true,
+      "other-space": true,
+      closed: false,
+      a: true,
+    });
+  });
+
+  it("does not mutate the input map", () => {
+    const prev = { a: false };
+    const next = openBranches(prev, ["a"]);
+    expect(prev).toEqual({ a: false });
+    expect(next).not.toBe(prev);
+  });
+
+  it("is idempotent", () => {
+    const once = openBranches({ z: true }, ["a", "b"]);
+    const twice = openBranches(once, ["a", "b"]);
+    expect(twice).toEqual(once);
+  });
+});
+
+describe("closeIds", () => {
+  it("flips current-space ids to false while leaving OTHER-space ids untouched", () => {
+    const prev = {
+      "current-1": true,
+      "current-2": true,
+      "other-space": true,
+    };
+    const next = closeIds(prev, ["current-1", "current-2"]);
+    expect(next).toEqual({
+      "current-1": false,
+      "current-2": false,
+      "other-space": true, // untouched
+    });
+  });
+
+  it("does not mutate the input map", () => {
+    const prev = { a: true };
+    const next = closeIds(prev, ["a"]);
+    expect(prev).toEqual({ a: true });
+    expect(next).not.toBe(prev);
+  });
+
+  it("is idempotent", () => {
+    const once = closeIds({ keep: true }, ["a", "b"]);
+    const twice = closeIds(once, ["a", "b"]);
+    expect(twice).toEqual(once);
+    expect(twice).toEqual({ keep: true, a: false, b: false });
+  });
+});
diff --git a/apps/client/src/features/page/tree/utils/utils.ts b/apps/client/src/features/page/tree/utils/utils.ts
index e91729fa..3ace0650 100644
--- a/apps/client/src/features/page/tree/utils/utils.ts
+++ b/apps/client/src/features/page/tree/utils/utils.ts
@@ -142,11 +142,17 @@ export function buildTreeWithChildren(items: SpaceTreeNode[]): SpaceTreeNode[] {
   // Build the tree array
   items.forEach((item) => {
     const node = nodeMap[item.id];
-    if (item.parentPageId !== null) {
+    // A permission-trimmed response can include a node whose `parentPageId` is
+    // not in the list (the parent was filtered out server-side). Treat such an
+    // orphan as a root instead of dereferencing an absent parent and throwing
+    // "Cannot read properties of undefined". Happy-path behaviour is unchanged:
+    // a node whose parent IS present still nests under it.
+    if (item.parentPageId !== null && nodeMap[item.parentPageId]) {
       // Find the parent node and add the current node to its children
       nodeMap[item.parentPageId].children.push(node);
     } else {
-      // If the item has no parent, it's a root node, so add it to the result array
+      // If the item has no parent (or its parent isn't loaded), it's a root
+      // node, so add it to the result array.
       result.push(node);
     }
   });
@@ -254,3 +260,30 @@ export function collectBranchIds(nodes: SpaceTreeNode[]): string[] {
   walk(nodes);
   return ids;
 }
+
+// The open-state map (`openTreeNodesAtom`) is shared across spaces. Pure
+// next-map helpers for expand/collapse so the merge logic can be unit-tested
+// without rendering SpaceTree. Both return a fresh map and never mutate the
+// input — ids not in `ids` (e.g. other spaces) are carried over untouched.
+
+// Set each id in `ids` to true (open). Pre-existing entries (including other
+// spaces' open state) are preserved.
+export function openBranches(
+  prevMap: Record<string, boolean>,
+  ids: string[],
+): Record<string, boolean> {
+  const next = { ...prevMap };
+  for (const id of ids) next[id] = true;
+  return next;
+}
+
+// Set each id in `ids` to false (closed). Entries not listed (e.g. other
+// spaces' ids) are left exactly as they were.
+export function closeIds(
+  prevMap: Record<string, boolean>,
+  ids: string[],
+): Record<string, boolean> {
+  const next = { ...prevMap };
+  for (const id of ids) next[id] = false;
+  return next;
+}
diff --git a/apps/client/src/features/websocket/tree-socket-reducers.test.ts b/apps/client/src/features/websocket/tree-socket-reducers.test.ts
new file mode 100644
index 00000000..52228949
--- /dev/null
+++ b/apps/client/src/features/websocket/tree-socket-reducers.test.ts
@@ -0,0 +1,264 @@
+import { describe, it, expect } from "vitest";
+import {
+  applyAddTreeNode,
+  applyMoveTreeNode,
+  applyDeleteTreeNode,
+} from "./tree-socket-reducers";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+// Minimal node factory — fills the SpaceTreeNode shape required fields while
+// letting tests override the bits that matter (position, parentPageId, etc).
+function node(
+  id: string,
+  overrides: Partial<SpaceTreeNode> = {},
+): SpaceTreeNode {
+  return {
+    id,
+    slugId: `slug-${id}`,
+    name: id.toUpperCase(),
+    icon: undefined,
+    position: "a0",
+    spaceId: "space-1",
+    parentPageId: null as unknown as string,
+    hasChildren: false,
+    children: [],
+    ...overrides,
+  };
+}
+
+describe("applyMoveTreeNode", () => {
+  // Destination parent `dst` is loaded with three positioned children; the moved
+  // node `src` is a sibling at root with a later position.
+  const buildTree = (): SpaceTreeNode[] => [
+    node("dst", {
+      position: "a0",
+      hasChildren: true,
+      children: [
+        node("c1", { position: "a1", parentPageId: "dst" }),
+        node("c2", { position: "a3", parentPageId: "dst" }),
+        node("c3", { position: "a5", parentPageId: "dst" }),
+      ],
+    }),
+    node("src", { position: "a9" }),
+  ];
+
+  it("places the node by position in the MIDDLE slot of the destination", () => {
+    const tree = buildTree();
+    const next = applyMoveTreeNode(tree, {
+      id: "src",
+      parentId: "dst",
+      oldParentId: null,
+      index: 0,
+      position: "a4",
+      pageData: {},
+    });
+    expect(treeModel.find(next, "dst")?.children?.map((n) => n.id)).toEqual([
+      "c1",
+      "c2",
+      "src",
+      "c3",
+    ]);
+  });
+
+  it("falls back to REMOVING the node when destination parent is not loaded (no leak)", () => {
+    const tree = buildTree();
+    const next = applyMoveTreeNode(tree, {
+      id: "src",
+      parentId: "not-loaded",
+      oldParentId: null,
+      index: 0,
+      position: "a4",
+      pageData: {},
+    });
+    // The source must not linger at its old place — it is removed entirely.
+    expect(treeModel.find(next, "src")).toBeNull();
+    // Destination children are untouched.
+    expect(treeModel.find(next, "dst")?.children?.map((n) => n.id)).toEqual([
+      "c1",
+      "c2",
+      "c3",
+    ]);
+  });
+
+  it("flips the OLD parent's hasChildren to false when it is left childless", () => {
+    // src is the only child of `old`; moving it to `dst` empties `old`.
+    const tree: SpaceTreeNode[] = [
+      node("old", {
+        position: "a0",
+        hasChildren: true,
+        children: [node("src", { position: "a1", parentPageId: "old" })],
+      }),
+      node("dst", { position: "a2", hasChildren: false }),
+    ];
+    const next = applyMoveTreeNode(tree, {
+      id: "src",
+      parentId: "dst",
+      oldParentId: "old",
+      index: 0,
+      position: "a1",
+      pageData: {},
+    });
+    expect(treeModel.find(next, "old")?.hasChildren).toBe(false);
+  });
+
+  it("flips the NEW parent's hasChildren to true", () => {
+    // dst starts as a childless leaf; moving src into it must flip the chevron.
+    const tree: SpaceTreeNode[] = [
+      node("dst", { position: "a0", hasChildren: false }),
+      node("src", { position: "a9" }),
+    ];
+    const next = applyMoveTreeNode(tree, {
+      id: "src",
+      parentId: "dst",
+      oldParentId: null,
+      index: 0,
+      position: "a1",
+      pageData: {},
+    });
+    expect(treeModel.find(next, "dst")?.hasChildren).toBe(true);
+    expect(treeModel.find(next, "dst")?.children?.map((n) => n.id)).toEqual([
+      "src",
+    ]);
+  });
+
+  it("returns prev unchanged when the source node is not found", () => {
+    const tree = buildTree();
+    const next = applyMoveTreeNode(tree, {
+      id: "ghost",
+      parentId: "dst",
+      oldParentId: null,
+      index: 0,
+      position: "a4",
+      pageData: {},
+    });
+    expect(next).toBe(tree);
+  });
+
+  it("applies authoritative pageData (title/icon/hasChildren) to the moved node", () => {
+    const tree = buildTree();
+    const next = applyMoveTreeNode(tree, {
+      id: "src",
+      parentId: "dst",
+      oldParentId: null,
+      index: 0,
+      position: "a4",
+      pageData: { title: "Renamed", icon: "fire", hasChildren: true },
+    });
+    const moved = treeModel.find(next, "src");
+    expect(moved?.name).toBe("Renamed");
+    expect(moved?.icon).toBe("fire");
+    expect(moved?.hasChildren).toBe(true);
+    expect(moved?.position).toBe("a4");
+  });
+});
+
+describe("applyDeleteTreeNode", () => {
+  it("removes the node together with its descendants", () => {
+    const tree: SpaceTreeNode[] = [
+      node("p", {
+        position: "a0",
+        hasChildren: true,
+        children: [
+          node("child", {
+            position: "a1",
+            parentPageId: "p",
+            hasChildren: true,
+            children: [node("grandchild", { position: "a1", parentPageId: "child" })],
+          }),
+        ],
+      }),
+    ];
+    const next = applyDeleteTreeNode(tree, {
+      node: node("child", { parentPageId: "p" }),
+    });
+    expect(treeModel.find(next, "child")).toBeNull();
+    expect(treeModel.find(next, "grandchild")).toBeNull();
+    expect(treeModel.find(next, "p")).not.toBeNull();
+  });
+
+  it("returns prev unchanged when the node is already gone (idempotent)", () => {
+    const tree: SpaceTreeNode[] = [node("a", { position: "a0" })];
+    const next = applyDeleteTreeNode(tree, {
+      node: node("ghost"),
+    });
+    expect(next).toBe(tree);
+  });
+
+  it("flips the parent's hasChildren to false when it is left childless", () => {
+    const tree: SpaceTreeNode[] = [
+      node("p", {
+        position: "a0",
+        hasChildren: true,
+        children: [node("only", { position: "a1", parentPageId: "p" })],
+      }),
+    ];
+    const next = applyDeleteTreeNode(tree, {
+      node: node("only", { parentPageId: "p" }),
+    });
+    expect(treeModel.find(next, "p")?.hasChildren).toBe(false);
+    expect(treeModel.find(next, "p")?.children).toEqual([]);
+  });
+
+  it("leaves the parent's hasChildren true when other children remain", () => {
+    const tree: SpaceTreeNode[] = [
+      node("p", {
+        position: "a0",
+        hasChildren: true,
+        children: [
+          node("c1", { position: "a1", parentPageId: "p" }),
+          node("c2", { position: "a2", parentPageId: "p" }),
+        ],
+      }),
+    ];
+    const next = applyDeleteTreeNode(tree, {
+      node: node("c1", { parentPageId: "p" }),
+    });
+    expect(treeModel.find(next, "p")?.hasChildren).toBe(true);
+  });
+});
+
+describe("applyAddTreeNode", () => {
+  const roots = (): SpaceTreeNode[] => [
+    node("a", { position: "a0" }),
+    node("b", { position: "a2" }),
+    node("c", { position: "a4" }),
+  ];
+
+  it("inserts the new node by position among siblings", () => {
+    const tree = roots();
+    const next = applyAddTreeNode(tree, {
+      parentId: null as unknown as string,
+      index: 0,
+      data: node("x", { position: "a3" }),
+    });
+    expect(next.map((n) => n.id)).toEqual(["a", "b", "x", "c"]);
+  });
+
+  it("returns prev unchanged when the id is already present (idempotent)", () => {
+    const tree = roots();
+    const next = applyAddTreeNode(tree, {
+      parentId: null as unknown as string,
+      index: 0,
+      data: node("b", { position: "a9" }),
+    });
+    expect(next).toBe(tree);
+    expect(next.map((n) => n.id)).toEqual(["a", "b", "c"]);
+  });
+
+  it("flips the new parent's hasChildren to true", () => {
+    // Parent `p` is a childless leaf; adding a child must flip its chevron.
+    const tree: SpaceTreeNode[] = [
+      node("p", { position: "a0", hasChildren: false }),
+    ];
+    const next = applyAddTreeNode(tree, {
+      parentId: "p",
+      index: 0,
+      data: node("child", { position: "a1", parentPageId: "p" }),
+    });
+    expect(treeModel.find(next, "p")?.hasChildren).toBe(true);
+    expect(treeModel.find(next, "p")?.children?.map((n) => n.id)).toEqual([
+      "child",
+    ]);
+  });
+});
diff --git a/apps/client/src/features/websocket/tree-socket-reducers.ts b/apps/client/src/features/websocket/tree-socket-reducers.ts
new file mode 100644
index 00000000..3f6226d9
--- /dev/null
+++ b/apps/client/src/features/websocket/tree-socket-reducers.ts
@@ -0,0 +1,164 @@
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import type {
+  AddTreeNodeEvent,
+  MoveTreeNodeEvent,
+  DeleteTreeNodeEvent,
+  UpdateEvent,
+} from "@/features/websocket/types";
+
+// Pure tree transforms for the `useTreeSocket` reducer arms. Extracted from the
+// hook so the realtime tree behaviour can be unit-tested without rendering the
+// hook, the socket, or jotai. The hook calls these inside its `setData`.
+//
+// IMPORTANT: these are PURE — no `queryClient`, no notifications, no atoms. The
+// delete arm's `queryClient.invalidateQueries` side effect stays in the hook;
+// `applyDeleteTreeNode` is a pure tree transform only.
+
+// `updateOne` for a page: patch the in-tree node's name/icon from the payload.
+// No-op (returns the same reference) when the node isn't loaded on this client.
+export function applyUpdateOne(
+  prev: SpaceTreeNode[],
+  event: UpdateEvent,
+): SpaceTreeNode[] {
+  if (!treeModel.find(prev, event.id)) return prev;
+  let next = prev;
+  if (event.payload?.title !== undefined) {
+    next = treeModel.update(next, event.id, {
+      name: event.payload.title,
+    } as Partial<SpaceTreeNode>);
+  }
+  if (event.payload?.icon !== undefined) {
+    next = treeModel.update(next, event.id, {
+      icon: event.payload.icon,
+    } as Partial<SpaceTreeNode>);
+  }
+  return next;
+}
+
+// `addTreeNode`: insert the new node by its fractional `position` among the
+// already-loaded siblings (not the sender's absolute index). Idempotent — if the
+// id already exists (optimistic author insert or re-delivery) returns prev
+// unchanged. Flips the new parent's `hasChildren` to true so the chevron renders.
+export function applyAddTreeNode(
+  prev: SpaceTreeNode[],
+  payload: AddTreeNodeEvent["payload"],
+): SpaceTreeNode[] {
+  // Idempotent: the author already inserted the node optimistically, and a node
+  // may be re-delivered — never insert a duplicate id.
+  if (treeModel.find(prev, payload.data.id)) return prev;
+  const newParentId = payload.parentId as string | null;
+  // Insert by `position` among already-loaded siblings (not the sender's
+  // absolute index) so order is consistent across clients with different loaded
+  // sets.
+  let next = treeModel.insertByPosition(prev, newParentId, payload.data);
+  // Mirror the emitter: flip new parent's hasChildren to true so the chevron
+  // renders on the receiver.
+  if (newParentId) {
+    next = treeModel.update(next, newParentId, {
+      hasChildren: true,
+    } as Partial<SpaceTreeNode>);
+  }
+  return next;
+}
+
+// `moveTreeNode`: place the moved node by its fractional `position` among the new
+// siblings (NOT the sender's absolute index). If the destination parent isn't
+// loaded on this client, fall back to removing the source so the UI stays
+// consistent. Applies authoritative `pageData` fields and mirrors the
+// `hasChildren` bookkeeping for both the old and the new parent.
+export function applyMoveTreeNode(
+  prev: SpaceTreeNode[],
+  payload: MoveTreeNodeEvent["payload"],
+): SpaceTreeNode[] {
+  const sourceBefore = treeModel.find(prev, payload.id);
+  if (!sourceBefore) return prev;
+  const oldParentId = (sourceBefore as SpaceTreeNode).parentPageId ?? null;
+  const newParentId = payload.parentId as string | null;
+
+  // Place the node by its fractional `position` among the new siblings — NOT by
+  // the sender's absolute `index` (the sender computed that against its own
+  // loaded set, which differs from this receiver's). Using the position keeps
+  // the visible order correct on every client; placing at `index: 0` would
+  // wrongly drop reordered/moved nodes at the top of their new sibling list.
+  const placed = treeModel.placeByPosition(prev, payload.id, {
+    parentId: newParentId,
+    position: payload.position,
+  });
+  // `placeByPosition` silently returns the same reference if the destination
+  // parent isn't loaded on this client. Falling back to removing the source
+  // keeps the UI consistent (the source reappears when the user expands the new
+  // parent and lazy-load fetches it).
+  if (placed === prev) {
+    return treeModel.remove(prev, payload.id);
+  }
+
+  // Apply the authoritative node fields the move payload carries (`pageData`) so
+  // receivers don't keep a stale title/icon/chevron on the moved node.
+  // `placeByPosition` already set `position`.
+  const pageData = payload.pageData as
+    | {
+        title?: string | null;
+        icon?: string | null;
+        hasChildren?: boolean;
+      }
+    | undefined;
+  const patch: Partial<SpaceTreeNode> = {
+    position: payload.position,
+    // Honest type: a root move has a null parent, so this is `string | null`,
+    // not always `string`.
+    parentPageId: newParentId as string | null,
+  };
+  if (pageData) {
+    // The tree node stores the title as `name`.
+    if (pageData.title !== undefined) patch.name = pageData.title ?? "";
+    if (pageData.icon !== undefined) patch.icon = pageData.icon ?? undefined;
+    if (pageData.hasChildren !== undefined)
+      patch.hasChildren = pageData.hasChildren;
+  }
+  let next = treeModel.update(placed, payload.id, patch);
+
+  // Mirror the emitter's hasChildren bookkeeping so both clients converge to the
+  // same chevron state.
+  if (oldParentId) {
+    const oldParent = treeModel.find(next, oldParentId);
+    if (!oldParent?.children?.length) {
+      next = treeModel.update(next, oldParentId, {
+        hasChildren: false,
+      } as Partial<SpaceTreeNode>);
+    }
+  }
+  if (newParentId) {
+    next = treeModel.update(next, newParentId, {
+      hasChildren: true,
+    } as Partial<SpaceTreeNode>);
+  }
+
+  return next;
+}
+
+// `deleteTreeNode`: remove the node (and its descendants) from the tree.
+// Idempotent — if the node is already gone returns prev unchanged. Mirrors the
+// `hasChildren` bookkeeping: a parent left childless flips `hasChildren` false.
+//
+// PURE: the `queryClient.invalidateQueries` side effect lives in the hook, not
+// here.
+export function applyDeleteTreeNode(
+  prev: SpaceTreeNode[],
+  payload: DeleteTreeNodeEvent["payload"],
+): SpaceTreeNode[] {
+  if (!treeModel.find(prev, payload.node.id)) return prev;
+  let next = treeModel.remove(prev, payload.node.id);
+  // Mirror the emitter's hasChildren bookkeeping so both clients converge to the
+  // same chevron state when the last child is deleted.
+  const parentPageId = payload.node.parentPageId;
+  if (parentPageId) {
+    const parent = treeModel.find(next, parentPageId);
+    if (!parent?.children?.length) {
+      next = treeModel.update(next, parentPageId, {
+        hasChildren: false,
+      } as Partial<SpaceTreeNode>);
+    }
+  }
+  return next;
+}
diff --git a/apps/client/src/features/websocket/use-tree-socket.ts b/apps/client/src/features/websocket/use-tree-socket.ts
index 317392e7..29b02ce7 100644
--- a/apps/client/src/features/websocket/use-tree-socket.ts
+++ b/apps/client/src/features/websocket/use-tree-socket.ts
@@ -6,6 +6,12 @@ import { WebSocketEvent } from "@/features/websocket/types";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { useQueryClient } from "@tanstack/react-query";
 import { treeModel } from "@/features/page/tree/model/tree-model";
+import {
+  applyUpdateOne,
+  applyAddTreeNode,
+  applyMoveTreeNode,
+  applyDeleteTreeNode,
+} from "@/features/websocket/tree-socket-reducers.ts";
 import localEmitter from "@/lib/local-emitter.ts";
 
 export const useTreeSocket = () => {
@@ -35,138 +41,26 @@ export const useTreeSocket = () => {
       switch (event.operation) {
         case "updateOne":
           if (event.entity[0] === "pages") {
-            setTreeData((prev) => {
-              if (!treeModel.find(prev, event.id)) return prev;
-              let next = prev;
-              if (event.payload?.title !== undefined) {
-                next = treeModel.update(next, event.id, {
-                  name: event.payload.title,
-                } as Partial<SpaceTreeNode>);
-              }
-              if (event.payload?.icon !== undefined) {
-                next = treeModel.update(next, event.id, {
-                  icon: event.payload.icon,
-                } as Partial<SpaceTreeNode>);
-              }
-              return next;
-            });
+            setTreeData((prev) => applyUpdateOne(prev, event));
           }
           break;
         case "addTreeNode":
-          setTreeData((prev) => {
-            // Idempotent: the author already inserted the node optimistically,
-            // and a node may be re-delivered — never insert a duplicate id.
-            if (treeModel.find(prev, event.payload.data.id)) return prev;
-            const newParentId = event.payload.parentId as string | null;
-            // Insert by `position` among already-loaded siblings (not the
-            // sender's absolute index) so order is consistent across clients
-            // with different loaded sets.
-            let next = treeModel.insertByPosition(
-              prev,
-              newParentId,
-              event.payload.data,
-            );
-            // Mirror the emitter: flip new parent's hasChildren to true so
-            // the chevron renders on the receiver.
-            if (newParentId) {
-              next = treeModel.update(next, newParentId, {
-                hasChildren: true,
-              } as Partial<SpaceTreeNode>);
-            }
-            return next;
-          });
+          setTreeData((prev) => applyAddTreeNode(prev, event.payload));
           break;
         case "moveTreeNode":
-          setTreeData((prev) => {
-            const sourceBefore = treeModel.find(prev, event.payload.id);
-            if (!sourceBefore) return prev;
-            const oldParentId =
-              (sourceBefore as SpaceTreeNode).parentPageId ?? null;
-            const newParentId = event.payload.parentId as string | null;
-
-            // Place the node by its fractional `position` among the new
-            // siblings — NOT by the sender's absolute `index` (the sender
-            // computed that against its own loaded set, which differs from
-            // this receiver's). Using the position keeps the visible order
-            // correct on every client; placing at `index: 0` would wrongly
-            // drop reordered/moved nodes at the top of their new sibling list.
-            const placed = treeModel.placeByPosition(prev, event.payload.id, {
-              parentId: newParentId,
-              position: event.payload.position,
-            });
-            // `placeByPosition` silently returns the same reference if the
-            // destination parent isn't loaded on this client. Falling back to
-            // removing the source keeps the UI consistent (the source will
-            // reappear when the user expands the new parent and lazy-load
-            // fetches it).
-            if (placed === prev) {
-              return treeModel.remove(prev, event.payload.id);
-            }
-
-            // Apply the authoritative node fields the move payload carries
-            // (`pageData`) so receivers don't keep a stale title/icon/chevron
-            // on the moved node. `placeByPosition` already set `position`.
-            const pageData = event.payload.pageData as
-              | {
-                  title?: string | null;
-                  icon?: string | null;
-                  hasChildren?: boolean;
-                }
-              | undefined;
-            const patch: Partial<SpaceTreeNode> = {
-              position: event.payload.position,
-              // Honest type: a root move has a null parent, so this is
-              // `string | null`, not always `string`.
-              parentPageId: newParentId as string | null,
-            };
-            if (pageData) {
-              // The tree node stores the title as `name`.
-              if (pageData.title !== undefined) patch.name = pageData.title ?? "";
-              if (pageData.icon !== undefined)
-                patch.icon = pageData.icon ?? undefined;
-              if (pageData.hasChildren !== undefined)
-                patch.hasChildren = pageData.hasChildren;
-            }
-            let next = treeModel.update(placed, event.payload.id, patch);
-
-            // Mirror the emitter's hasChildren bookkeeping so both clients
-            // converge to the same chevron state.
-            if (oldParentId) {
-              const oldParent = treeModel.find(next, oldParentId);
-              if (!oldParent?.children?.length) {
-                next = treeModel.update(next, oldParentId, {
-                  hasChildren: false,
-                } as Partial<SpaceTreeNode>);
-              }
-            }
-            if (newParentId) {
-              next = treeModel.update(next, newParentId, {
-                hasChildren: true,
-              } as Partial<SpaceTreeNode>);
-            }
-
-            return next;
-          });
+          setTreeData((prev) => applyMoveTreeNode(prev, event.payload));
           break;
         case "deleteTreeNode":
+          // The `invalidateQueries` side effect stays in the hook; the tree
+          // transform (`applyDeleteTreeNode`) is pure. Only invalidate when the
+          // node is actually in the tree (mirrors the pure reducer's early-out).
           setTreeData((prev) => {
-            if (!treeModel.find(prev, event.payload.node.id)) return prev;
-            queryClient.invalidateQueries({
-              queryKey: ["pages", event.payload.node.slugId].filter(Boolean),
-            });
-            let next = treeModel.remove(prev, event.payload.node.id);
-            // Mirror the emitter's hasChildren bookkeeping so both clients
-            // converge to the same chevron state when the last child is deleted.
-            const parentPageId = event.payload.node.parentPageId;
-            if (parentPageId) {
-              const parent = treeModel.find(next, parentPageId);
-              if (!parent?.children?.length) {
-                next = treeModel.update(next, parentPageId, {
-                  hasChildren: false,
-                } as Partial<SpaceTreeNode>);
-              }
+            if (treeModel.find(prev, event.payload.node.id)) {
+              queryClient.invalidateQueries({
+                queryKey: ["pages", event.payload.node.slugId].filter(Boolean),
+              });
             }
-            return next;
+            return applyDeleteTreeNode(prev, event.payload);
           });
           break;
       }
diff --git a/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx b/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx
index 4bc479bc..3b7c9335 100644
--- a/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx
+++ b/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.spec.tsx
@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest';
-import { resolveCardStatus } from './ai-provider-settings';
+import {
+  resolveCardStatus,
+  isEndpointConfigured,
+  resolveKeyField,
+} from './ai-provider-settings';
 
 describe('resolveCardStatus', () => {
   it('returns "off" when not configured and not enabled', () => {
@@ -18,3 +22,52 @@ describe('resolveCardStatus', () => {
     expect(resolveCardStatus(true, true)).toBe('ready');
   });
 });
+
+describe('isEndpointConfigured', () => {
+  it('configured when model and the endpoint own base URL are set', () => {
+    expect(isEndpointConfigured('m', 'https://own', '')).toBe(true);
+  });
+
+  it('configured by inheriting the chat base URL when own base is empty', () => {
+    expect(isEndpointConfigured('m', '', 'https://chat')).toBe(true);
+  });
+
+  it('not configured when model is set but both base URLs are empty', () => {
+    expect(isEndpointConfigured('m', '', '')).toBe(false);
+  });
+
+  it('not configured when both base URLs are whitespace-only', () => {
+    expect(isEndpointConfigured('m', '   ', '\t')).toBe(false);
+  });
+
+  it('not configured when the model is whitespace-only', () => {
+    expect(isEndpointConfigured('   ', 'https://own', 'https://chat')).toBe(
+      false,
+    );
+  });
+});
+
+describe('resolveKeyField (write-only key payload)', () => {
+  // The same logic backs all three keys (chat / embedding / stt) in buildPayload.
+  it('typed a value -> set the new key', () => {
+    expect(resolveKeyField('sk-new', false)).toEqual({
+      set: true,
+      value: 'sk-new',
+    });
+  });
+
+  it('typed a value wins even if cleared was also flagged', () => {
+    expect(resolveKeyField('sk-new', true)).toEqual({
+      set: true,
+      value: 'sk-new',
+    });
+  });
+
+  it('cleared (empty buffer) -> set the key to empty string', () => {
+    expect(resolveKeyField('', true)).toEqual({ set: true, value: '' });
+  });
+
+  it('untouched (empty buffer, not cleared) -> omit the key', () => {
+    expect(resolveKeyField('', false)).toEqual({ set: false });
+  });
+});
diff --git a/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx b/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx
index e4ff8724..4726a0ef 100644
--- a/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx
+++ b/apps/client/src/features/workspace/components/settings/components/ai-provider-settings.tsx
@@ -98,6 +98,33 @@ export function resolveCardStatus(
   return enabled ? "warning" : "off";
 }
 
+// Pure + unit-testable. A non-chat endpoint (embeddings / voice) is "configured"
+// when its model is set AND it has a usable base URL: either its own base URL is
+// non-empty, or the chat base URL is non-empty (inherited when own is empty).
+// All inputs are trimmed so whitespace-only values do not count as filled.
+export function isEndpointConfigured(
+  model: string,
+  ownBase: string,
+  chatBase: string,
+): boolean {
+  return (
+    model.trim() !== "" && (ownBase.trim() !== "" || chatBase.trim() !== "")
+  );
+}
+
+// Pure + unit-testable. Write-only API-key payload semantics:
+//   - typed a value (buffer non-empty) -> set it
+//   - explicitly cleared -> send '' to clear the stored key
+//   - untouched (empty buffer, not cleared) -> omit the key entirely
+export function resolveKeyField(
+  buffer: string,
+  cleared: boolean,
+): { set: true; value: string } | { set: false } {
+  if (buffer.length > 0) return { set: true, value: buffer };
+  if (cleared) return { set: true, value: "" };
+  return { set: false };
+}
+
 // Translate the dot's tooltip label. Kept in one place so all three endpoint
 // cards share identical wording.
 function cardStatusLabel(status: CardStatus, t: (k: string) => string): string {
@@ -263,29 +290,23 @@ export default function AiProviderSettings() {
       sttApiStyle: values.sttApiStyle,
     };
 
-    // Key semantics (never send the stored key back):
+    // Key semantics (never send the stored key back) — see resolveKeyField:
     //   - typed a value -> set it
     //   - explicitly cleared -> send '' to clear
     //   - untouched -> omit the key entirely (leave unchanged)
-    if (values.apiKey.length > 0) {
-      payload.apiKey = values.apiKey;
-    } else if (keyCleared) {
-      payload.apiKey = "";
-    }
+    const apiKeyField = resolveKeyField(values.apiKey, keyCleared);
+    if (apiKeyField.set) payload.apiKey = apiKeyField.value;
 
     // Same write-only semantics for the embedding-specific key.
-    if (values.embeddingApiKey.length > 0) {
-      payload.embeddingApiKey = values.embeddingApiKey;
-    } else if (embeddingKeyCleared) {
-      payload.embeddingApiKey = "";
-    }
+    const embeddingKeyField = resolveKeyField(
+      values.embeddingApiKey,
+      embeddingKeyCleared,
+    );
+    if (embeddingKeyField.set) payload.embeddingApiKey = embeddingKeyField.value;
 
     // Same write-only semantics for the STT-specific key.
-    if (values.sttApiKey.length > 0) {
-      payload.sttApiKey = values.sttApiKey;
-    } else if (sttKeyCleared) {
-      payload.sttApiKey = "";
-    }
+    const sttKeyField = resolveKeyField(values.sttApiKey, sttKeyCleared);
+    if (sttKeyField.set) payload.sttApiKey = sttKeyField.value;
 
     return payload;
   }
@@ -460,12 +481,12 @@ export default function AiProviderSettings() {
   const v = form.values;
   const chatBase = v.baseUrl.trim();
   const chatConfigured = v.chatModel.trim() !== "" && chatBase !== "";
-  const embedConfigured =
-    v.embeddingModel.trim() !== "" &&
-    (v.embeddingBaseUrl.trim() !== "" || chatBase !== "");
-  const sttConfigured =
-    v.sttModel.trim() !== "" &&
-    (v.sttBaseUrl.trim() !== "" || chatBase !== "");
+  const embedConfigured = isEndpointConfigured(
+    v.embeddingModel,
+    v.embeddingBaseUrl,
+    v.baseUrl,
+  );
+  const sttConfigured = isEndpointConfigured(v.sttModel, v.sttBaseUrl, v.baseUrl);
 
   const chatStatus = resolveCardStatus(chatConfigured, chatEnabled);
   const embedStatus = resolveCardStatus(embedConfigured, searchEnabled);
diff --git a/apps/server/package.json b/apps/server/package.json
index 7726fcc0..41f4ad31 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -23,6 +23,7 @@
     "migration:reset": "tsx src/database/migrate.ts down-to NO_MIGRATIONS",
     "migration:codegen": "kysely-codegen --dialect=postgres --camel-case --env-file=../../.env --out-file=./src/database/types/db.d.ts",
     "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "pretest": "pnpm --filter @docmost/editor-ext build",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:cov": "jest --coverage",
@@ -162,7 +163,8 @@
     "moduleFileExtensions": [
       "js",
       "json",
-      "ts"
+      "ts",
+      "tsx"
     ],
     "rootDir": "src",
     "testRegex": ".*\\.spec\\.ts$",
@@ -182,7 +184,7 @@
           ]
         }
       ],
-      "^.+\\.(t|j)s$": "ts-jest"
+      "^.+\\.(t|j)sx?$": "ts-jest"
     },
     "transformIgnorePatterns": [
       "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom)(@|/))"
diff --git a/apps/server/src/common/helpers/prosemirror/html-embed-import-detect.spec.ts b/apps/server/src/common/helpers/prosemirror/html-embed-import-detect.spec.ts
new file mode 100644
index 00000000..20affe2f
--- /dev/null
+++ b/apps/server/src/common/helpers/prosemirror/html-embed-import-detect.spec.ts
@@ -0,0 +1,70 @@
+import { markdownToHtml, encodeHtmlEmbedSource } from '@docmost/editor-ext';
+import { htmlToJson } from '../../../collaboration/collaboration.util';
+import { hasHtmlEmbedNode, stripHtmlEmbedNodes } from './html-embed.util';
+
+/**
+ * CONTRACT (security): an attacker who controls imported markdown/HTML could try
+ * to smuggle an htmlEmbed in the *serialized* DOM form —
+ *   <div data-type="htmlEmbed" data-source="...">
+ * — directly, bypassing the editor's `<!--html-embed:-->` comment marker.
+ *
+ * This exercises the REAL server import conversion path that ImportService uses
+ * (`markdownToHtml` then `htmlToJson`; `processHTML` adds only a cheerio
+ * link/iframe normalize pass which does not touch htmlEmbed divs) and asserts
+ * the ACTUAL behaviour so we know whether the strip gate can be bypassed.
+ *
+ * FINDING (documented): the raw embed div DOES round-trip through marked +
+ * htmlToJson into a real `htmlEmbed` node, so `hasHtmlEmbedNode` returns true and
+ * `stripHtmlEmbedNodes` removes it. The serialized-form bypass is therefore
+ * detectable and STRIPPABLE — the write-path gate covers it.
+ */
+describe('htmlEmbed smuggled via the raw serialized div in imported markdown/HTML', () => {
+  it('round-trips through markdownToHtml -> htmlToJson and is DETECTED (base64 data-source)', async () => {
+    const source = '<script>steal()</script>';
+    const encoded = encodeHtmlEmbedSource(source);
+    const md = [
+      'Hello',
+      '',
+      `<div data-type="htmlEmbed" data-source="${encoded}"></div>`,
+      '',
+      'World',
+    ].join('\n');
+
+    const html = await markdownToHtml(md);
+    // marked preserves the raw block-level div verbatim.
+    expect(html).toContain('data-type="htmlEmbed"');
+
+    const json = htmlToJson(html);
+    // The div parses into a real htmlEmbed node carrying the decoded source.
+    expect(hasHtmlEmbedNode(json)).toBe(true);
+
+    // Because it is detected, the write-path gate can strip it for non-admins.
+    const stripped = stripHtmlEmbedNodes(json);
+    expect(hasHtmlEmbedNode(stripped)).toBe(false);
+    // Surrounding non-embed content is retained.
+    expect(JSON.stringify(stripped)).toContain('Hello');
+    expect(JSON.stringify(stripped)).toContain('World');
+  });
+
+  it('round-trips through direct HTML conversion (htmlToJson) and is DETECTED', () => {
+    const source = '<script>steal()</script>';
+    const encoded = encodeHtmlEmbedSource(source);
+    const html = `<p>Hello</p><div data-type="htmlEmbed" data-source="${encoded}"></div><p>World</p>`;
+
+    const json = htmlToJson(html);
+    expect(hasHtmlEmbedNode(json)).toBe(true);
+    expect(hasHtmlEmbedNode(stripHtmlEmbedNodes(json))).toBe(false);
+  });
+
+  it('is still DETECTED even when the data-source is NOT valid base64', async () => {
+    // A naive raw inline source (HTML-escaped, not base64) still parses as an
+    // htmlEmbed NODE — the decoder just yields an empty source. Detection (and
+    // therefore stripping) does not depend on the source being well-formed, so
+    // the bypass cannot be hidden by sending a malformed data-source.
+    const md = `<div data-type="htmlEmbed" data-source="&lt;script&gt;x&lt;/script&gt;"></div>`;
+    const html = await markdownToHtml(md);
+    const json = htmlToJson(html);
+    expect(hasHtmlEmbedNode(json)).toBe(true);
+    expect(hasHtmlEmbedNode(stripHtmlEmbedNodes(json))).toBe(false);
+  });
+});
diff --git a/apps/server/src/common/helpers/prosemirror/html-embed.spec.ts b/apps/server/src/common/helpers/prosemirror/html-embed.spec.ts
index 6b07ec0b..28a59ea3 100644
--- a/apps/server/src/common/helpers/prosemirror/html-embed.spec.ts
+++ b/apps/server/src/common/helpers/prosemirror/html-embed.spec.ts
@@ -92,6 +92,102 @@ describe('stripHtmlEmbedNodes', () => {
     const result = stripHtmlEmbedNodes(doc);
     expect(result).toEqual(doc);
   });
+
+  it('strips a deeply nested htmlEmbed (3+ levels: callout > column > paragraph-sibling)', () => {
+    // htmlEmbed sits as a sibling of a paragraph, nested four containers deep.
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'columns',
+              content: [
+                {
+                  type: 'column',
+                  content: [
+                    {
+                      type: 'paragraph',
+                      content: [{ type: 'text', text: 'deep keep' }],
+                    },
+                    { type: 'htmlEmbed', attrs: { source: '<script>x</script>' } },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = stripHtmlEmbedNodes(doc);
+    expect(hasHtmlEmbedNode(result)).toBe(false);
+    const col = findFirstChild(result, 'column');
+    // Sibling paragraph survives; only the embed is removed.
+    expect(col.content).toHaveLength(1);
+    expect(col.content[0].type).toBe('paragraph');
+    expect(col.content[0].content[0].text).toBe('deep keep');
+  });
+
+  it('returns non-object / null / array-without-content nodes unchanged', () => {
+    // Non-object inputs are returned as-is (callers persist what they got).
+    expect(stripHtmlEmbedNodes(null as any)).toBeNull();
+    expect(stripHtmlEmbedNodes(undefined as any)).toBeUndefined();
+    expect(stripHtmlEmbedNodes('not-a-node' as any)).toBe('not-a-node');
+    expect(stripHtmlEmbedNodes(42 as any)).toBe(42);
+
+    // An object node with no `content` array is returned shallow-cloned, equal.
+    const leaf = { type: 'paragraph', attrs: { id: 'x' } };
+    const out = stripHtmlEmbedNodes(leaf);
+    expect(out).toEqual(leaf);
+    expect(out).not.toBe(leaf); // new object, input not mutated
+  });
+
+  it('yields empty content (not null/undefined) for a doc whose only child is an htmlEmbed', () => {
+    const doc = {
+      type: 'doc',
+      content: [{ type: 'htmlEmbed', attrs: { source: '<b>only</b>' } }],
+    };
+    const result = stripHtmlEmbedNodes(doc) as any;
+    expect(Array.isArray(result.content)).toBe(true);
+    expect(result.content).toHaveLength(0);
+    expect(result.content).not.toBeNull();
+    expect(result.content).not.toBeUndefined();
+    expect(hasHtmlEmbedNode(result)).toBe(false);
+  });
+});
+
+describe('hasHtmlEmbedNode (root/odd-shape detection)', () => {
+  it('returns true when the ROOT node itself is an htmlEmbed (not only a child)', () => {
+    const rootEmbed = { type: 'htmlEmbed', attrs: { source: '<script>r</script>' } };
+    expect(hasHtmlEmbedNode(rootEmbed)).toBe(true);
+  });
+
+  it('returns false for a doc with embed-like TEXT but no htmlEmbed node', () => {
+    // The literal string "htmlEmbed" appears only as text content, not as a
+    // node type, so it must NOT be detected.
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            { type: 'text', text: 'type: htmlEmbed <div data-type="htmlEmbed">' },
+          ],
+        },
+      ],
+    };
+    expect(hasHtmlEmbedNode(doc)).toBe(false);
+  });
+
+  it('returns false for non-object / null / array inputs', () => {
+    expect(hasHtmlEmbedNode(null)).toBe(false);
+    expect(hasHtmlEmbedNode(undefined)).toBe(false);
+    expect(hasHtmlEmbedNode('htmlEmbed')).toBe(false);
+    // A bare array (no `content` wrapper) has no node `type`, so it's false.
+    expect(hasHtmlEmbedNode([{ type: 'htmlEmbed' }] as any)).toBe(false);
+  });
 });
 
 describe('canAuthorHtmlEmbed', () => {
diff --git a/apps/server/src/core/ai-chat/ai-chat.service.spec.ts b/apps/server/src/core/ai-chat/ai-chat.service.spec.ts
index 2756df77..b788646e 100644
--- a/apps/server/src/core/ai-chat/ai-chat.service.spec.ts
+++ b/apps/server/src/core/ai-chat/ai-chat.service.spec.ts
@@ -4,6 +4,7 @@ import {
   serializeSteps,
   rowToUiMessage,
   prepareAgentStep,
+  buildErrorAssistantRecord,
   MAX_AGENT_STEPS,
   FINAL_STEP_INSTRUCTION,
 } from './ai-chat.service';
@@ -229,3 +230,32 @@ describe('prepareAgentStep', () => {
     expect(atBoundary?.toolChoice).toBe('none');
   });
 });
+
+/**
+ * Unit test for buildErrorAssistantRecord: the pure helper that shapes the
+ * assistant-message record persisted on a first-turn (or any) stream failure.
+ * The streamText onError callback builds the formatted error text via
+ * describeProviderError (tested separately) and hands it to this helper; pinning
+ * the record shape here covers the persist-assistant-on-error logic without
+ * having to seam streamText itself.
+ */
+describe('buildErrorAssistantRecord', () => {
+  it('records an empty turn with the error text in metadata (finishReason=error)', () => {
+    const rec = buildErrorAssistantRecord('401: Unauthorized');
+    expect(rec).toEqual({
+      text: '',
+      toolCalls: null,
+      metadata: { finishReason: 'error', parts: [], error: '401: Unauthorized' },
+    });
+  });
+
+  it('always produces empty text + empty parts so a failed turn is still recorded', () => {
+    const rec = buildErrorAssistantRecord('boom');
+    // No partial text and no UI parts: the turn exists in history but renders as
+    // an error, with the cause preserved in metadata.error.
+    expect(rec.text).toBe('');
+    expect(rec.metadata.parts).toEqual([]);
+    expect(rec.toolCalls).toBeNull();
+    expect(rec.metadata.error).toBe('boom');
+  });
+});
diff --git a/apps/server/src/core/ai-chat/ai-chat.service.ts b/apps/server/src/core/ai-chat/ai-chat.service.ts
index 4c4bc6f4..f492ca03 100644
--- a/apps/server/src/core/ai-chat/ai-chat.service.ts
+++ b/apps/server/src/core/ai-chat/ai-chat.service.ts
@@ -384,11 +384,7 @@ export class AiChatService {
         this.logger.error(`AI chat stream error: ${errorText}`, e?.stack);
         // Persist whatever text we have (likely empty) so the turn is recorded,
         // and record the error text in metadata so it is visible in history.
-        await persistAssistant({
-          text: '',
-          toolCalls: null,
-          metadata: { finishReason: 'error', parts: [], error: errorText },
-        });
+        await persistAssistant(buildErrorAssistantRecord(errorText));
         await closeExternalClients();
       },
       onAbort: async ({ steps }) => {
@@ -710,6 +706,26 @@ export function rowToUiMessage(row: AiChatMessage): Omit<UIMessage, 'id'> & {
   return { id: row.id, role, parts: parts as UIMessage['parts'] };
 }
 
+/**
+ * Build the assistant-message record persisted when a turn fails before any text
+ * is produced (the streamText onError path). Pure: it takes the formatted error
+ * text and returns the exact `{ text, toolCalls, metadata }` payload handed to
+ * persistAssistant, so the first-turn-failure recording shape is unit-testable
+ * without seaming streamText. The empty text + empty parts mean the failed turn
+ * is still recorded in history, with the provider cause visible in metadata.
+ */
+export function buildErrorAssistantRecord(errorText: string): {
+  text: string;
+  toolCalls: null;
+  metadata: { finishReason: 'error'; parts: []; error: string };
+} {
+  return {
+    text: '',
+    toolCalls: null,
+    metadata: { finishReason: 'error', parts: [], error: errorText },
+  };
+}
+
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
  * `tool_calls` column. Stores only what the UI action-log and history need —
diff --git a/apps/server/src/core/ai-chat/public-share-chat.controller.spec.ts b/apps/server/src/core/ai-chat/public-share-chat.controller.spec.ts
new file mode 100644
index 00000000..83f6252e
--- /dev/null
+++ b/apps/server/src/core/ai-chat/public-share-chat.controller.spec.ts
@@ -0,0 +1,256 @@
+import { HttpException } from '@nestjs/common';
+import {
+  resolveShareAssistantRequest,
+  uiMessageTextLength,
+  type ShareAssistantDeps,
+} from './public-share-chat.controller';
+import { AiNotConfiguredException } from '../../integrations/ai/ai-not-configured.exception';
+import {
+  MAX_SHARE_MESSAGES,
+  MAX_SHARE_MESSAGE_CHARS,
+} from './public-share-chat.service';
+import type { UIMessage } from 'ai';
+
+/**
+ * Unit tests for the extracted pre-hijack funnel (resolveShareAssistantRequest)
+ * and the exported size helper (uiMessageTextLength). The funnel order is
+ * security-relevant: the first failing gate must win, every failure must throw
+ * BEFORE any stream/hijack, and the access-shaped failures must all 404 (no
+ * existence leak). These exercise each branch with hand-rolled mocks — no Nest
+ * module graph, no DB.
+ */
+describe('resolveShareAssistantRequest (extracted controller funnel)', () => {
+  /** A fully-passing dep set; individual tests override single collaborators. */
+  function makeDeps(over: {
+    assistantEnabled?: boolean;
+    getShareForPage?: jest.Mock;
+    isSharingAllowed?: jest.Mock;
+    findById?: jest.Mock;
+    hasRestrictedAncestor?: jest.Mock;
+    resolveShareRole?: jest.Mock;
+    getShareChatModel?: jest.Mock;
+    tryConsumeWorkspaceQuota?: jest.Mock;
+  } = {}) {
+    const aiSettings = {
+      isPublicShareAssistantEnabled: jest
+        .fn()
+        .mockResolvedValue(over.assistantEnabled ?? true),
+    };
+    const shareService = {
+      getShareForPage:
+        over.getShareForPage ??
+        jest.fn().mockResolvedValue({
+          id: 'SHARE-A',
+          pageId: 'root-page',
+          spaceId: 'space-1',
+          sharedPage: { id: 'root-page', title: 'Root' },
+        }),
+      isSharingAllowed:
+        over.isSharingAllowed ?? jest.fn().mockResolvedValue(true),
+    };
+    const pageRepo = {
+      findById:
+        over.findById ?? jest.fn().mockResolvedValue({ id: 'opened-uuid' }),
+    };
+    const pagePermissionRepo = {
+      hasRestrictedAncestor:
+        over.hasRestrictedAncestor ?? jest.fn().mockResolvedValue(false),
+    };
+    const publicShareChat = {
+      resolveShareRole:
+        over.resolveShareRole ?? jest.fn().mockResolvedValue(null),
+      getShareChatModel:
+        over.getShareChatModel ?? jest.fn().mockResolvedValue('MODEL'),
+      tryConsumeWorkspaceQuota:
+        over.tryConsumeWorkspaceQuota ?? jest.fn().mockResolvedValue(true),
+    };
+    const deps: ShareAssistantDeps = {
+      aiSettings: aiSettings as never,
+      shareService: shareService as never,
+      pageRepo: pageRepo as never,
+      pagePermissionRepo: pagePermissionRepo as never,
+      publicShareChat: publicShareChat as never,
+    };
+    return {
+      deps,
+      aiSettings,
+      shareService,
+      pageRepo,
+      pagePermissionRepo,
+      publicShareChat,
+    };
+  }
+
+  const body = (over: Record<string, unknown> = {}) => ({
+    shareId: 'SHARE-A',
+    pageId: 'opened-page',
+    messages: [],
+    ...over,
+  });
+
+  /** Run the funnel and capture the thrown HttpException status (or null). */
+  async function statusOf(
+    deps: ShareAssistantDeps,
+    b: Record<string, unknown>,
+  ): Promise<number | null> {
+    try {
+      await resolveShareAssistantRequest(deps, {
+        workspaceId: 'ws-1',
+        body: b as never,
+      });
+      return null;
+    } catch (err) {
+      if (err instanceof HttpException) return err.getStatus();
+      throw err;
+    }
+  }
+
+  it('happy path: returns the resolved, non-null request', async () => {
+    const { deps } = makeDeps();
+    const out = await resolveShareAssistantRequest(deps, {
+      workspaceId: 'ws-1',
+      body: body() as never,
+    });
+    expect(out.shareId).toBe('SHARE-A');
+    expect(out.share.id).toBe('SHARE-A');
+    expect(out.model).toBe('MODEL');
+    expect(out.role).toBeNull();
+    expect(out.openedPage).toEqual({ id: 'opened-page', title: 'Root' });
+  });
+
+  it('assistant disabled => 404 and NO share/page/model lookups', async () => {
+    const { deps, shareService, pageRepo, publicShareChat } = makeDeps({
+      assistantEnabled: false,
+    });
+    expect(await statusOf(deps, body())).toBe(404);
+    expect(shareService.getShareForPage).not.toHaveBeenCalled();
+    expect(pageRepo.findById).not.toHaveBeenCalled();
+    expect(publicShareChat.getShareChatModel).not.toHaveBeenCalled();
+  });
+
+  it('share.id !== body.shareId => 404 (cross-share id swap rejected)', async () => {
+    const { deps, publicShareChat } = makeDeps({
+      getShareForPage: jest.fn().mockResolvedValue({
+        id: 'OTHER-SHARE',
+        pageId: 'root',
+        spaceId: 'space-1',
+        sharedPage: null,
+      }),
+    });
+    expect(await statusOf(deps, body({ shareId: 'SHARE-A' }))).toBe(404);
+    // Never reached the model resolution for an unusable share.
+    expect(publicShareChat.getShareChatModel).not.toHaveBeenCalled();
+  });
+
+  it('opened page unresolvable (pageRepo.findById -> null) => fail-closed 404', async () => {
+    const { deps } = makeDeps({
+      findById: jest.fn().mockResolvedValue(null),
+    });
+    expect(await statusOf(deps, body())).toBe(404);
+  });
+
+  it('restricted descendant => 404 (same as out-of-tree, no existence leak)', async () => {
+    const { deps, pagePermissionRepo } = makeDeps({
+      hasRestrictedAncestor: jest.fn().mockResolvedValue(true),
+    });
+    expect(await statusOf(deps, body())).toBe(404);
+    expect(pagePermissionRepo.hasRestrictedAncestor).toHaveBeenCalled();
+  });
+
+  it('getShareChatModel throws AiNotConfiguredException => 503', async () => {
+    const { deps } = makeDeps({
+      getShareChatModel: jest
+        .fn()
+        .mockRejectedValue(new AiNotConfiguredException()),
+    });
+    expect(await statusOf(deps, body())).toBe(503);
+  });
+
+  it('getShareChatModel throws a non-AiNotConfigured error => re-thrown (not a 503/404)', async () => {
+    const boom = new Error('boom');
+    const { deps } = makeDeps({
+      getShareChatModel: jest.fn().mockRejectedValue(boom),
+    });
+    await expect(
+      resolveShareAssistantRequest(deps, {
+        workspaceId: 'ws-1',
+        body: body() as never,
+      }),
+    ).rejects.toBe(boom);
+  });
+
+  it('tryConsumeWorkspaceQuota false => 429 thrown BEFORE any stream', async () => {
+    const { deps, publicShareChat } = makeDeps({
+      tryConsumeWorkspaceQuota: jest.fn().mockResolvedValue(false),
+    });
+    expect(await statusOf(deps, body())).toBe(429);
+    // The quota gate ran AFTER the model resolved (provider configured) but the
+    // function returns/throws before producing a streamable request.
+    expect(publicShareChat.tryConsumeWorkspaceQuota).toHaveBeenCalledWith('ws-1');
+  });
+
+  it('messages over MAX_SHARE_MESSAGES => 413', async () => {
+    const { deps } = makeDeps();
+    const tooMany = Array.from({ length: MAX_SHARE_MESSAGES + 1 }, () => ({
+      role: 'user',
+      parts: [{ type: 'text', text: 'hi' }],
+    }));
+    expect(await statusOf(deps, body({ messages: tooMany }))).toBe(413);
+  });
+
+  it('a single message over MAX_SHARE_MESSAGE_CHARS => 413 (uiMessageTextLength)', async () => {
+    const { deps } = makeDeps();
+    const huge = {
+      role: 'user',
+      parts: [{ type: 'text', text: 'x'.repeat(MAX_SHARE_MESSAGE_CHARS + 1) }],
+    };
+    expect(await statusOf(deps, body({ messages: [huge] }))).toBe(413);
+  });
+
+  it('the quota gate is checked BEFORE the payload caps (429 wins over 413)', async () => {
+    // Over-cap workspace AND an over-long message: the 429 must surface first, so
+    // an over-cap caller is rejected without even paying the payload-cap scan.
+    const { deps } = makeDeps({
+      tryConsumeWorkspaceQuota: jest.fn().mockResolvedValue(false),
+    });
+    const huge = {
+      role: 'user',
+      parts: [{ type: 'text', text: 'x'.repeat(MAX_SHARE_MESSAGE_CHARS + 1) }],
+    };
+    expect(await statusOf(deps, body({ messages: [huge] }))).toBe(429);
+  });
+});
+
+describe('uiMessageTextLength', () => {
+  it('returns 0 for an undefined / parts-less / non-array message', () => {
+    expect(uiMessageTextLength(undefined)).toBe(0);
+    expect(uiMessageTextLength({} as UIMessage)).toBe(0);
+    expect(uiMessageTextLength({ parts: 'nope' } as never)).toBe(0);
+  });
+
+  it('sums the lengths of ONLY the text parts', () => {
+    const msg = {
+      role: 'user',
+      parts: [
+        { type: 'text', text: 'hello' }, // 5
+        { type: 'tool-call', text: 'IGNORED' }, // non-text: ignored
+        { type: 'text', text: 'world!' }, // 6
+        { type: 'text' }, // no text field: ignored
+      ],
+    } as unknown as UIMessage;
+    expect(uiMessageTextLength(msg)).toBe(11);
+  });
+
+  it('matches the 413 boundary used by the funnel', () => {
+    const atCap = {
+      role: 'user',
+      parts: [{ type: 'text', text: 'x'.repeat(MAX_SHARE_MESSAGE_CHARS) }],
+    } as unknown as UIMessage;
+    const overCap = {
+      role: 'user',
+      parts: [{ type: 'text', text: 'x'.repeat(MAX_SHARE_MESSAGE_CHARS + 1) }],
+    } as unknown as UIMessage;
+    expect(uiMessageTextLength(atCap)).toBe(MAX_SHARE_MESSAGE_CHARS);
+    expect(uiMessageTextLength(overCap)).toBeGreaterThan(MAX_SHARE_MESSAGE_CHARS);
+  });
+});
diff --git a/apps/server/src/core/ai-chat/public-share-chat.controller.ts b/apps/server/src/core/ai-chat/public-share-chat.controller.ts
index fa5a0a5f..4c8d0a39 100644
--- a/apps/server/src/core/ai-chat/public-share-chat.controller.ts
+++ b/apps/server/src/core/ai-chat/public-share-chat.controller.ts
@@ -77,142 +77,25 @@ export class PublicShareChatController {
     @AuthWorkspace() workspace: Workspace,
   ): Promise<void> {
     const body = (req.body ?? {}) as PublicShareChatStreamBody;
-    const shareId = typeof body.shareId === 'string' ? body.shareId.trim() : '';
-    const pageId = typeof body.pageId === 'string' ? body.pageId.trim() : '';
 
     // ---- Guardrail funnel (order matters; each failure exits before stream) ----
-
-    // 1. Workspace master toggle. 404 (do not reveal the feature exists).
-    const assistantEnabled = await this.aiSettings.isPublicShareAssistantEnabled(
-      workspace.id,
+    // The whole pre-hijack fact-resolution + cap-ordering block is a pure-ish
+    // helper (collaborators passed in) so every funnel branch — 404 disabled /
+    // share-mismatch / page-unresolvable / restricted, 503 unconfigured, 429
+    // over-cap, 413 too many/too long — is unit-testable against the red-team
+    // boundaries without the full Nest/DB graph. It throws the SAME HttpException
+    // the controller would, and never starts streaming.
+    const resolved = await resolveShareAssistantRequest(
+      {
+        aiSettings: this.aiSettings,
+        shareService: this.shareService,
+        pageRepo: this.pageRepo,
+        pagePermissionRepo: this.pagePermissionRepo,
+        publicShareChat: this.publicShareChat,
+      },
+      { workspaceId: workspace.id, body },
     );
-
-    // 2. Share usable? Resolved via the page's share membership, since the page
-    //    resolution (getShareForPage) ALSO yields the share + workspace. We
-    //    still need basic input to attempt it.
-    // 3. Page in share? The same getShareForPage lookup confirms the opened page
-    //    resolves to THIS share tree, PLUS an explicit restricted-ancestor gate
-    //    (getShareForPage itself does NOT exclude restricted descendants) so a
-    //    restricted page hidden from the public view is graded not-in-share.
-    //    (shareUsable + pageInShare are set together below; the funnel grades
-    //    them as distinct ordered steps.)
-    let share: Awaited<ReturnType<ShareService['getShareForPage']>> | undefined;
-    let shareUsable = false;
-    let pageInShare = false;
-    if (assistantEnabled && shareId && pageId) {
-      // getShareForPage walks up the tree to the nearest ancestor share,
-      // enforces share.workspaceId === workspaceId and includeSubPages, and
-      // returns undefined when the page is not publicly reachable. NOTE: it
-      // joins only the `shares` table — it does NOT exclude restricted
-      // descendants — so a restricted page inside an includeSubPages share
-      // still resolves here. We add an explicit restricted-ancestor gate below
-      // (same as the public view) so the opened page's title never leaks into
-      // the system prompt for a page the public view 404s.
-      share = await this.shareService.getShareForPage(pageId, workspace.id);
-      if (share && share.id === shareId) {
-        // Confirm sharing is still allowed for the share's space (and not
-        // disabled at workspace/space level) — same gate the public views use.
-        const sharingAllowed = await this.shareService.isSharingAllowed(
-          workspace.id,
-          share.spaceId,
-        );
-        // A restricted descendant is hidden from the public share view; treat
-        // the opened page as not-in-share so the funnel returns the SAME 404 it
-        // returns for an out-of-tree page (uniform, no existence leak).
-        // hasRestrictedAncestor matches on the page UUID only, while the
-        // opened pageId may be a slugId, so resolve to the UUID first (cheap
-        // base-fields lookup, mirroring how getSharedPage resolves the page
-        // before its restricted check).
-        const openedPageRow = await this.pageRepo.findById(pageId);
-        const restricted = openedPageRow
-          ? await this.pagePermissionRepo.hasRestrictedAncestor(
-              openedPageRow.id,
-            )
-          : true; // unresolvable opened page => fail closed (treat as not-in-share)
-        // The security-relevant combination (server-resolved share id ===
-        // requested shareId, + sharingAllowed, + the restricted gate) is a pure,
-        // unit-tested helper so the access join point can be exercised against
-        // the red-team boundaries without the full Nest/DB graph.
-        ({ shareUsable, pageInShare } = deriveShareAccess({
-          resolvedShareId: share.id,
-          requestedShareId: shareId,
-          sharingAllowed,
-          restricted,
-        }));
-      }
-    }
-
-    // 4. Provider configured? Resolve the model now so an unconfigured provider
-    //    yields a clean 503 (AiNotConfiguredException) BEFORE hijack. Only
-    //    attempt this once the earlier gates passed, to avoid leaking timing.
-    let model: Awaited<ReturnType<PublicShareChatService['getShareChatModel']>> | undefined;
-    // Admin-selected identity (agent role) for the anonymous assistant, resolved
-    // server-authoritatively. null = built-in locked persona.
-    let role: AiAgentRole | null = null;
-    let providerConfigured = false;
-    if (assistantEnabled && shareUsable && pageInShare) {
-      try {
-        role = await this.publicShareChat.resolveShareRole(workspace.id);
-        model = await this.publicShareChat.getShareChatModel(workspace.id, role);
-        providerConfigured = true;
-      } catch (err) {
-        if (err instanceof AiNotConfiguredException) {
-          providerConfigured = false;
-        } else {
-          throw err;
-        }
-      }
-    }
-
-    const outcome = evaluateShareAssistantFunnel({
-      assistantEnabled,
-      shareUsable,
-      pageInShare,
-      providerConfigured,
-    });
-    if (outcome.ok === false) {
-      // 404 for everything access-shaped (feature/share/page); 503 for config.
-      if (outcome.status === 503) {
-        throw new ServiceUnavailableException('AI is not configured');
-      }
-      throw new NotFoundException('Not found');
-    }
-
-    // 5. Per-WORKSPACE anti-abuse cap (IP-independent; defense in depth). The
-    //    per-IP @Throttle above can be evaded by an attacker rotating
-    //    `X-Forwarded-For` (the app runs with trustProxy), and each evaded call
-    //    spends REAL tokens on the workspace owner's paid AI provider. This cap
-    //    is keyed by the server-resolved workspace id (never attacker-
-    //    controllable), so it bounds the owner's bill even when the per-IP limit
-    //    is fully defeated via XFF spoofing. Checked here, BEFORE res.hijack(),
-    //    so an over-cap workspace gets a clean 429 and spends nothing. NOTE:
-    //    production should ALSO front this endpoint with a trusted proxy that
-    //    REWRITES (not appends) XFF so the per-IP throttle stays meaningful.
-    if (!(await this.publicShareChat.tryConsumeWorkspaceQuota(workspace.id))) {
-      throw new HttpException(
-        'This documentation assistant is temporarily busy. Please try again later.',
-        HttpStatus.TOO_MANY_REQUESTS,
-      );
-    }
-
-    // ---- Validate / bound the payload (cheap caps; ephemeral, never stored) ----
-    const messages = Array.isArray(body.messages)
-      ? (body.messages as UIMessage[])
-      : [];
-    if (messages.length > MAX_SHARE_MESSAGES) {
-      throw new HttpException('Too many messages', 413);
-    }
-    for (const m of messages) {
-      const text = uiMessageTextLength(m);
-      if (text > MAX_SHARE_MESSAGE_CHARS) {
-        throw new HttpException('Message too long', 413);
-      }
-    }
-
-    const openedPage = {
-      id: pageId,
-      title: share?.sharedPage?.title ?? undefined,
-    };
+    const { shareId, share, model, role, messages, openedPage } = resolved;
 
     // Abort the agent loop when the client disconnects (mirrors ai-chat).
     const controller = new AbortController();
@@ -230,15 +113,15 @@ export class PublicShareChatController {
         workspaceId: workspace.id,
         shareId,
         share: {
-          id: share!.id,
-          pageId: share!.pageId,
-          sharedPage: share!.sharedPage,
+          id: share.id,
+          pageId: share.pageId,
+          sharedPage: share.sharedPage,
         },
         openedPage,
         messages,
         res,
         signal: controller.signal,
-        model: model!,
+        model,
         role,
       });
     } catch (err) {
@@ -255,8 +138,174 @@ export class PublicShareChatController {
   }
 }
 
-/** Sum of the text-part lengths of a UIMessage (cheap, for the size cap). */
-function uiMessageTextLength(message: UIMessage | undefined): number {
+/**
+ * The collaborators the pre-hijack funnel needs. Declared as the minimal slice
+ * of each injected service it actually calls, so the resolver can be unit-tested
+ * with hand-rolled mocks (no Nest module graph, no DB).
+ */
+export interface ShareAssistantDeps {
+  aiSettings: Pick<AiSettingsService, 'isPublicShareAssistantEnabled'>;
+  shareService: Pick<
+    ShareService,
+    'getShareForPage' | 'isSharingAllowed'
+  >;
+  pageRepo: Pick<PageRepo, 'findById'>;
+  pagePermissionRepo: Pick<PagePermissionRepo, 'hasRestrictedAncestor'>;
+  publicShareChat: Pick<
+    PublicShareChatService,
+    | 'resolveShareRole'
+    | 'getShareChatModel'
+    | 'tryConsumeWorkspaceQuota'
+  >;
+}
+
+/** The resolved, validated request ready to stream (everything is non-null). */
+export interface ResolvedShareAssistantRequest {
+  shareId: string;
+  share: NonNullable<Awaited<ReturnType<ShareService['getShareForPage']>>>;
+  model: Awaited<ReturnType<PublicShareChatService['getShareChatModel']>>;
+  role: AiAgentRole | null;
+  messages: UIMessage[];
+  openedPage: { id: string; title?: string };
+}
+
+/**
+ * Pre-hijack fact-resolution + cap-ordering for the anonymous public-share
+ * assistant, extracted from the controller so every funnel branch is unit-
+ * testable without the Nest/DB graph. Order is security-relevant and each
+ * failure exits BEFORE any stream/hijack:
+ *  1. assistant toggle off => 404 (no share/page/model lookups);
+ *  2. share/page access (deriveShareAccess + evaluateShareAssistantFunnel) =>
+ *     404 (uniform; restricted descendant and out-of-tree look identical);
+ *  3. provider unconfigured => 503 (AiNotConfiguredException), other errors
+ *     re-thrown;
+ *  4. per-workspace quota exhausted => 429 (BEFORE any stream/hijack);
+ *  5. payload caps => 413 (too many messages / a single message too long).
+ * Throws the SAME HttpException the controller would; returns the resolved,
+ * non-null request otherwise.
+ */
+export async function resolveShareAssistantRequest(
+  deps: ShareAssistantDeps,
+  input: { workspaceId: string; body: PublicShareChatStreamBody },
+): Promise<ResolvedShareAssistantRequest> {
+  const { workspaceId, body } = input;
+  const shareId = typeof body.shareId === 'string' ? body.shareId.trim() : '';
+  const pageId = typeof body.pageId === 'string' ? body.pageId.trim() : '';
+
+  // 1. Workspace master toggle. 404 (do not reveal the feature exists).
+  const assistantEnabled =
+    await deps.aiSettings.isPublicShareAssistantEnabled(workspaceId);
+
+  // 2/3. Share usable? Page in share? Resolved via the page's share membership,
+  //      since getShareForPage ALSO yields the share + workspace. The opened
+  //      page is then gated by an explicit restricted-ancestor check (which
+  //      getShareForPage does NOT do) so a restricted page hidden from the
+  //      public view is graded not-in-share.
+  let share: Awaited<ReturnType<ShareService['getShareForPage']>> | undefined;
+  let shareUsable = false;
+  let pageInShare = false;
+  if (assistantEnabled && shareId && pageId) {
+    share = await deps.shareService.getShareForPage(pageId, workspaceId);
+    if (share && share.id === shareId) {
+      const sharingAllowed = await deps.shareService.isSharingAllowed(
+        workspaceId,
+        share.spaceId,
+      );
+      // hasRestrictedAncestor matches on the page UUID only, while the opened
+      // pageId may be a slugId, so resolve to the UUID first (cheap base-fields
+      // lookup). An unresolvable opened page fails closed (not-in-share).
+      const openedPageRow = await deps.pageRepo.findById(pageId);
+      const restricted = openedPageRow
+        ? await deps.pagePermissionRepo.hasRestrictedAncestor(openedPageRow.id)
+        : true;
+      ({ shareUsable, pageInShare } = deriveShareAccess({
+        resolvedShareId: share.id,
+        requestedShareId: shareId,
+        sharingAllowed,
+        restricted,
+      }));
+    }
+  }
+
+  // 4. Provider configured? Resolve the model now so an unconfigured provider
+  //    yields a clean 503 BEFORE hijack. Only after the access gates pass, to
+  //    avoid leaking timing.
+  let model:
+    | Awaited<ReturnType<PublicShareChatService['getShareChatModel']>>
+    | undefined;
+  let role: AiAgentRole | null = null;
+  let providerConfigured = false;
+  if (assistantEnabled && shareUsable && pageInShare) {
+    try {
+      role = await deps.publicShareChat.resolveShareRole(workspaceId);
+      model = await deps.publicShareChat.getShareChatModel(workspaceId, role);
+      providerConfigured = true;
+    } catch (err) {
+      if (err instanceof AiNotConfiguredException) {
+        providerConfigured = false;
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  const outcome = evaluateShareAssistantFunnel({
+    assistantEnabled,
+    shareUsable,
+    pageInShare,
+    providerConfigured,
+  });
+  if (outcome.ok === false) {
+    // 404 for everything access-shaped (feature/share/page); 503 for config.
+    if (outcome.status === 503) {
+      throw new ServiceUnavailableException('AI is not configured');
+    }
+    throw new NotFoundException('Not found');
+  }
+
+  // 5. Per-WORKSPACE anti-abuse cap (IP-independent; defense in depth). Checked
+  //    BEFORE res.hijack(), so an over-cap workspace gets a clean 429 and spends
+  //    nothing.
+  if (!(await deps.publicShareChat.tryConsumeWorkspaceQuota(workspaceId))) {
+    throw new HttpException(
+      'This documentation assistant is temporarily busy. Please try again later.',
+      HttpStatus.TOO_MANY_REQUESTS,
+    );
+  }
+
+  // ---- Validate / bound the payload (cheap caps; ephemeral, never stored) ----
+  const messages = Array.isArray(body.messages)
+    ? (body.messages as UIMessage[])
+    : [];
+  if (messages.length > MAX_SHARE_MESSAGES) {
+    throw new HttpException('Too many messages', 413);
+  }
+  for (const m of messages) {
+    if (uiMessageTextLength(m) > MAX_SHARE_MESSAGE_CHARS) {
+      throw new HttpException('Message too long', 413);
+    }
+  }
+
+  const openedPage = {
+    id: pageId,
+    title: share?.sharedPage?.title ?? undefined,
+  };
+
+  // The funnel passed, so share/model are guaranteed present.
+  return {
+    shareId,
+    share: share!,
+    model: model!,
+    role,
+    messages,
+    openedPage,
+  };
+}
+
+/** Sum of the text-part lengths of a UIMessage (cheap, for the size cap).
+ * Exported so the 413 size-cap logic is unit-testable without the Nest/DB graph.
+ */
+export function uiMessageTextLength(message: UIMessage | undefined): number {
   if (!message?.parts || !Array.isArray(message.parts)) return 0;
   let total = 0;
   for (const p of message.parts) {
diff --git a/apps/server/src/core/ai-chat/public-share-chat.spec.ts b/apps/server/src/core/ai-chat/public-share-chat.spec.ts
index 623852fb..2be6a5f4 100644
--- a/apps/server/src/core/ai-chat/public-share-chat.spec.ts
+++ b/apps/server/src/core/ai-chat/public-share-chat.spec.ts
@@ -7,7 +7,11 @@ import {
   filterShareTranscript,
 } from './public-share-chat.service';
 import { PublicShareChatToolsService } from './tools/public-share-chat-tools.service';
-import { PublicShareWorkspaceLimiter } from './public-share-workspace-limiter';
+import {
+  PublicShareWorkspaceLimiter,
+  resolveShareAiWorkspaceMax,
+  SHARE_AI_WORKSPACE_MAX_PER_WINDOW,
+} from './public-share-workspace-limiter';
 
 /**
  * Minimal in-memory fake of the slice of ioredis the sliding-window limiter
@@ -195,6 +199,54 @@ describe('buildShareSystemPrompt locking', () => {
     expect(prompt).toContain('read-only assistant');
     expect(prompt).toContain('anti prompt-injection');
   });
+
+  it('an opened page with a title injects both the pageId and the title', () => {
+    const prompt = buildShareSystemPrompt({
+      share: null,
+      openedPage: { id: 'page-123', title: 'Getting Started' },
+    });
+    expect(prompt).toContain('(pageId: page-123)');
+    expect(prompt).toContain('"Getting Started"');
+    expect(prompt).toContain('the current page');
+  });
+
+  it('an opened page with a blank/whitespace title falls back to "Untitled"', () => {
+    const prompt = buildShareSystemPrompt({
+      share: null,
+      openedPage: { id: 'page-123', title: '   ' },
+    });
+    expect(prompt).toContain('(pageId: page-123)');
+    expect(prompt).toContain('"Untitled"');
+  });
+
+  it('an empty / blank pageId omits the opened-page context line entirely', () => {
+    const emptyId = buildShareSystemPrompt({
+      share: null,
+      openedPage: { id: '', title: 'Ignored' },
+    });
+    expect(emptyId).not.toContain('pageId:');
+    expect(emptyId).not.toContain('the current page');
+
+    const blankId = buildShareSystemPrompt({
+      share: null,
+      openedPage: { id: '   ', title: 'Ignored' },
+    });
+    expect(blankId).not.toContain('pageId:');
+  });
+
+  it('a present share title is injected; a blank share title is omitted', () => {
+    const withTitle = buildShareSystemPrompt({
+      share: { sharedPageTitle: 'Product Docs' },
+      openedPage: null,
+    });
+    expect(withTitle).toContain('titled "Product Docs"');
+
+    const blankTitle = buildShareSystemPrompt({
+      share: { sharedPageTitle: '   ' },
+      openedPage: null,
+    });
+    expect(blankTitle).not.toContain('This published documentation is titled');
+  });
 });
 
 describe('PublicShareChatService model fallback', () => {
@@ -306,6 +358,44 @@ describe('PublicShareChatService model fallback', () => {
   });
 });
 
+describe('resolveShareAiWorkspaceMax (env-overridable per-workspace cap)', () => {
+  const ENV = 'SHARE_AI_WORKSPACE_MAX_PER_HOUR';
+  const original = process.env[ENV];
+
+  afterEach(() => {
+    if (original === undefined) delete process.env[ENV];
+    else process.env[ENV] = original;
+  });
+
+  it('uses a valid positive integer from the env', () => {
+    process.env[ENV] = '42';
+    expect(resolveShareAiWorkspaceMax()).toBe(42);
+  });
+
+  it('floors a float value', () => {
+    process.env[ENV] = '99.9';
+    expect(resolveShareAiWorkspaceMax()).toBe(99);
+  });
+
+  it('falls back to the default for an unparseable / NaN value', () => {
+    process.env[ENV] = 'not-a-number';
+    expect(resolveShareAiWorkspaceMax()).toBe(SHARE_AI_WORKSPACE_MAX_PER_WINDOW);
+    expect(SHARE_AI_WORKSPACE_MAX_PER_WINDOW).toBe(300);
+  });
+
+  it('falls back to the default when unset', () => {
+    delete process.env[ENV];
+    expect(resolveShareAiWorkspaceMax()).toBe(SHARE_AI_WORKSPACE_MAX_PER_WINDOW);
+  });
+
+  it('falls back to the default for zero or a negative value (no unlimited / negative cap)', () => {
+    process.env[ENV] = '0';
+    expect(resolveShareAiWorkspaceMax()).toBe(SHARE_AI_WORKSPACE_MAX_PER_WINDOW);
+    process.env[ENV] = '-5';
+    expect(resolveShareAiWorkspaceMax()).toBe(SHARE_AI_WORKSPACE_MAX_PER_WINDOW);
+  });
+});
+
 describe('PublicShareWorkspaceLimiter (cluster-wide sliding-window per-workspace cap)', () => {
   it('allows up to the cap within a window, then 429s (returns false)', async () => {
     const limiter = makeLimiter(3, 60_000, () => 1_000);
@@ -353,6 +443,23 @@ describe('PublicShareWorkspaceLimiter (cluster-wide sliding-window per-workspace
     expect(await limiter.tryConsume('ws-1')).toBe(true);
   });
 
+  it('consumes a distinct member slot per call at one FIXED clock value (no same-ms score-collision under-count)', async () => {
+    // All calls happen at the SAME millisecond. The limiter mints a unique member
+    // id per attempt, so distinct calls in the same ms must NOT collide on the
+    // sorted-set score and under-count: exactly `cap` calls are admitted, the
+    // rest rejected — even though every score is identical.
+    const cap = 5;
+    const limiter = makeLimiter(cap, 60_000, () => 7_000); // clock never advances
+    const results: boolean[] = [];
+    for (let i = 0; i < cap + 3; i++) {
+      results.push(await limiter.tryConsume('ws-1'));
+    }
+    // First `cap` admitted, the remaining 3 rejected.
+    expect(results.slice(0, cap)).toEqual(Array(cap).fill(true));
+    expect(results.slice(cap)).toEqual([false, false, false]);
+    expect(results.filter(Boolean)).toHaveLength(cap);
+  });
+
   it('keeps separate budgets per workspace (one over-cap ws cannot starve another)', async () => {
     const limiter = makeLimiter(1, 60_000, () => 1_000);
     expect(await limiter.tryConsume('ws-a')).toBe(true);
diff --git a/apps/server/src/core/ai-chat/roles/ai-agent-roles.service.spec.ts b/apps/server/src/core/ai-chat/roles/ai-agent-roles.service.spec.ts
index d2cf6004..e86cbbf5 100644
--- a/apps/server/src/core/ai-chat/roles/ai-agent-roles.service.spec.ts
+++ b/apps/server/src/core/ai-chat/roles/ai-agent-roles.service.spec.ts
@@ -93,6 +93,56 @@ describe('AiAgentRolesService guards', () => {
       ).rejects.toBeInstanceOf(BadRequestException);
       expect(repo.update).not.toHaveBeenCalled();
     });
+
+    it('instructions cleared to whitespace => BadRequest, repo.update NOT called', async () => {
+      const { service, repo } = makeService({ existing: makeRow() });
+      await expect(
+        service.update('ws-1', 'r1', {
+          instructions: '   ',
+        } as UpdateAgentRoleDto),
+      ).rejects.toBeInstanceOf(BadRequestException);
+      expect(repo.update).not.toHaveBeenCalled();
+    });
+
+    it('concurrent soft-delete: row exists on the pre-update lookup but the re-fetch is undefined => BadRequest (not a TypeError)', async () => {
+      // findById returns the live row FIRST (pre-update guard passes), then the
+      // role is soft-deleted concurrently, so the POST-update re-fetch returns
+      // undefined. The service must surface a clean 400, never dereference
+      // undefined (which would throw a TypeError in toView).
+      const { service, repo } = makeService();
+      repo.findById
+        .mockResolvedValueOnce(makeRow())
+        .mockResolvedValueOnce(undefined);
+      await expect(
+        service.update('ws-1', 'r1', { name: 'X' } as UpdateAgentRoleDto),
+      ).rejects.toBeInstanceOf(BadRequestException);
+      // The UPDATE ran (the row existed pre-update), but the re-fetch failed.
+      expect(repo.update).toHaveBeenCalled();
+      expect(repo.findById).toHaveBeenCalledTimes(2);
+    });
+
+    it('emoji/description tri-state: emoji:"" => null (clear), emoji omitted => undefined (unchanged), description:"  " => null', async () => {
+      const { service, repo } = makeService({ existing: makeRow() });
+
+      // emoji explicitly emptied => clear to null; description whitespace => null.
+      await service.update('ws-1', 'r1', {
+        emoji: '',
+        description: '  ',
+      } as UpdateAgentRoleDto);
+      const patch1 = repo.update.mock.calls[0][2];
+      expect(patch1.emoji).toBeNull();
+      expect(patch1.description).toBeNull();
+
+      repo.update.mockClear();
+
+      // emoji omitted => unchanged (undefined passed through to the repo patch).
+      await service.update('ws-1', 'r1', {
+        name: 'Renamed',
+      } as UpdateAgentRoleDto);
+      const patch2 = repo.update.mock.calls[0][2];
+      expect(patch2.emoji).toBeUndefined();
+      expect(patch2.description).toBeUndefined();
+    });
   });
 
   describe('remove', () => {
@@ -136,6 +186,51 @@ describe('AiAgentRolesService guards', () => {
       expect(repo.insert).not.toHaveBeenCalled();
     });
 
+    it('modelConfig:{chatModel} only persists {chatModel} (no driver key)', async () => {
+      const { service, repo } = makeService();
+      await service.create('ws-1', 'u1', {
+        name: 'R',
+        instructions: 'do',
+        modelConfig: { chatModel: 'gpt-4o' },
+      } as CreateAgentRoleDto);
+      const values = repo.insert.mock.calls[0][0];
+      expect(values.modelConfig).toEqual({ chatModel: 'gpt-4o' });
+      expect('driver' in values.modelConfig).toBe(false);
+    });
+
+    it('modelConfig:{} (empty) normalizes to null', async () => {
+      const { service, repo } = makeService();
+      await service.create('ws-1', 'u1', {
+        name: 'R',
+        instructions: 'do',
+        modelConfig: {},
+      } as CreateAgentRoleDto);
+      expect(repo.insert.mock.calls[0][0].modelConfig).toBeNull();
+    });
+
+    it('modelConfig:{chatModel:"   "} (whitespace-only) normalizes to null', async () => {
+      const { service, repo } = makeService();
+      await service.create('ws-1', 'u1', {
+        name: 'R',
+        instructions: 'do',
+        modelConfig: { chatModel: '   ' },
+      } as CreateAgentRoleDto);
+      expect(repo.insert.mock.calls[0][0].modelConfig).toBeNull();
+    });
+
+    it('modelConfig:{driver,chatModel} round-trips both fields (trimmed)', async () => {
+      const { service, repo } = makeService();
+      await service.create('ws-1', 'u1', {
+        name: 'R',
+        instructions: 'do',
+        modelConfig: { driver: 'gemini', chatModel: '  gemini-2.0-flash  ' },
+      } as CreateAgentRoleDto);
+      expect(repo.insert.mock.calls[0][0].modelConfig).toEqual({
+        driver: 'gemini',
+        chatModel: 'gemini-2.0-flash',
+      });
+    });
+
     it('duplicate name (Postgres 23505) => ConflictException (409), not 500', async () => {
       const { service, repo } = makeService();
       // The partial unique (workspace_id, name) index rejects the insert.
@@ -148,6 +243,28 @@ describe('AiAgentRolesService guards', () => {
       ).rejects.toBeInstanceOf(ConflictException);
     });
 
+    it('duplicate name 409 message contains the TRIMMED submitted name', async () => {
+      const { service, repo } = makeService();
+      repo.insert.mockRejectedValueOnce({ code: '23505' });
+      await service
+        .create('ws-1', 'u1', {
+          name: '  Researcher  ',
+          instructions: 'do',
+        } as CreateAgentRoleDto)
+        .then(
+          () => {
+            throw new Error('expected create to throw');
+          },
+          (err: unknown) => {
+            expect(err).toBeInstanceOf(ConflictException);
+            const message = (err as ConflictException).message;
+            // The trimmed name appears verbatim; the untrimmed padding does not.
+            expect(message).toContain('"Researcher"');
+            expect(message).not.toContain('  Researcher  ');
+          },
+        );
+    });
+
     it('non-unique-violation error is NOT swallowed (re-thrown as-is)', async () => {
       const { service, repo } = makeService();
       const other = Object.assign(new Error('boom'), { code: '23502' });
diff --git a/apps/server/src/core/ai-chat/roles/jsonb-object.spec.ts b/apps/server/src/core/ai-chat/roles/jsonb-object.spec.ts
new file mode 100644
index 00000000..96875748
--- /dev/null
+++ b/apps/server/src/core/ai-chat/roles/jsonb-object.spec.ts
@@ -0,0 +1,30 @@
+import { jsonbObject } from '@docmost/db/repos/ai-agent-roles/ai-agent-roles.repo';
+
+/**
+ * Unit tests for jsonbObject: the repo helper that encodes a model_config object
+ * as a jsonb bind (or null when there is nothing to persist). It is the last
+ * line of defence before the column write, so the null-vs-bind decision is what
+ * matters here. We assert only null vs non-null because the non-null value is a
+ * kysely `sql` template fragment whose internal shape is an implementation
+ * detail of the SQL tag.
+ */
+describe('jsonbObject', () => {
+  it('returns null for null', () => {
+    expect(jsonbObject(null)).toBeNull();
+  });
+
+  it('returns null for undefined', () => {
+    expect(jsonbObject(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty object (nothing to persist)', () => {
+    expect(jsonbObject({})).toBeNull();
+  });
+
+  it('returns a (non-null) jsonb bind for a non-empty object', () => {
+    const out = jsonbObject({ driver: 'gemini', chatModel: 'gemini-2.0-flash' });
+    // A real sql fragment is produced, never null/undefined.
+    expect(out).not.toBeNull();
+    expect(out).toBeDefined();
+  });
+});
diff --git a/apps/server/src/core/ai-chat/roles/role-override-contract.spec.ts b/apps/server/src/core/ai-chat/roles/role-override-contract.spec.ts
new file mode 100644
index 00000000..c5165b26
--- /dev/null
+++ b/apps/server/src/core/ai-chat/roles/role-override-contract.spec.ts
@@ -0,0 +1,135 @@
+import { AiService } from '../../../integrations/ai/ai.service';
+import { AiNotConfiguredException } from '../../../integrations/ai/ai-not-configured.exception';
+import { roleModelOverride } from './role-model-config';
+import type { AiAgentRole } from '@docmost/db/types/entity.types';
+
+/**
+ * Contract test for the override SHAPE that travels from a role's persisted
+ * `model_config` (via roleModelOverride) into AiService.getChatModel.
+ *
+ * This is the seam between the two halves of the role-model feature:
+ *  - roleModelOverride (pure) turns model_config into a ChatModelOverride;
+ *  - getChatModel consumes that override to build the model (or to 503).
+ * Wiring the REAL roleModelOverride output into a unit-constructed AiService
+ * (with stubbed deps, no DB) pins that the two agree on the override contract:
+ *  - a cross-driver override whose creds are absent => AiNotConfiguredException
+ *    naming the role + driver;
+ *  - a chatModel-only override keeps the workspace driver/creds (no creds
+ *    lookup, no decrypt);
+ *  - an ollama cross-driver override => 503 (no silent baseUrl reuse).
+ */
+describe('role override -> AiService.getChatModel contract', () => {
+  function role(modelConfig: unknown, name = 'Researcher'): AiAgentRole {
+    return { id: 'r1', name, modelConfig } as unknown as AiAgentRole;
+  }
+
+  function makeService(opts: {
+    workspaceDriver: string;
+    baseUrl?: string;
+    credsApiKeyEnc?: string;
+  }) {
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: opts.workspaceDriver,
+        chatModel: 'gpt-4o-mini',
+        apiKey: 'workspace-key',
+        baseUrl: opts.baseUrl,
+      }),
+    };
+    const aiProviderCredentialsRepo = {
+      find: jest
+        .fn()
+        .mockResolvedValue(
+          opts.credsApiKeyEnc ? { apiKeyEnc: opts.credsApiKeyEnc } : undefined,
+        ),
+    };
+    const secretBox = { decryptSecret: jest.fn().mockReturnValue('decrypted') };
+    const service = new AiService(
+      aiSettings as never,
+      aiProviderCredentialsRepo as never,
+      secretBox as never,
+    );
+    return { service, aiSettings, aiProviderCredentialsRepo, secretBox };
+  }
+
+  it('cross-driver override with NO creds => 503 naming the role and the override driver', async () => {
+    const override = roleModelOverride(
+      role({ driver: 'gemini', chatModel: 'gemini-2.0-flash' }),
+    );
+    expect(override).toEqual({
+      driver: 'gemini',
+      chatModel: 'gemini-2.0-flash',
+      roleName: 'Researcher',
+    });
+
+    // Workspace is openai; the gemini override has no configured creds.
+    const { service, aiProviderCredentialsRepo } = makeService({
+      workspaceDriver: 'openai',
+    });
+
+    await service.getChatModel('ws-1', override).then(
+      () => {
+        throw new Error('expected getChatModel to throw');
+      },
+      (err: unknown) => {
+        expect(err).toBeInstanceOf(AiNotConfiguredException);
+        const message = (err as AiNotConfiguredException).message;
+        expect(message).toContain('gemini');
+        expect(message).toContain('Researcher');
+      },
+    );
+    expect(aiProviderCredentialsRepo.find).toHaveBeenCalledWith('ws-1', 'gemini');
+  });
+
+  it('chatModel-only override keeps the workspace driver/creds (no creds lookup, no decrypt)', async () => {
+    const override = roleModelOverride(role({ chatModel: 'gpt-4o' }));
+    // No driver in the override => the workspace driver/creds are reused.
+    expect(override).toEqual({
+      driver: undefined,
+      chatModel: 'gpt-4o',
+      roleName: 'Researcher',
+    });
+
+    const { service, aiProviderCredentialsRepo, secretBox } = makeService({
+      workspaceDriver: 'openai',
+    });
+
+    const model = await service.getChatModel('ws-1', override);
+    expect(model).toBeDefined();
+    expect(aiProviderCredentialsRepo.find).not.toHaveBeenCalled();
+    expect(secretBox.decryptSecret).not.toHaveBeenCalled();
+  });
+
+  it('ollama cross-driver override (workspace driver != ollama) => 503, no baseUrl reuse', async () => {
+    const override = roleModelOverride(
+      role({ driver: 'ollama', chatModel: 'llama3' }, 'Local'),
+    );
+    expect(override).toEqual({
+      driver: 'ollama',
+      chatModel: 'llama3',
+      roleName: 'Local',
+    });
+
+    const { service, aiProviderCredentialsRepo } = makeService({
+      workspaceDriver: 'openai',
+      baseUrl: 'https://openrouter.example/v1',
+    });
+
+    await service.getChatModel('ws-1', override).then(
+      () => {
+        throw new Error('expected getChatModel to throw');
+      },
+      (err: unknown) => {
+        expect(err).toBeInstanceOf(AiNotConfiguredException);
+        const message = (err as AiNotConfiguredException).message;
+        expect(message).toContain('ollama');
+        expect(message).toContain('openai');
+        expect(message).toContain('Local');
+        // The workspace gateway baseUrl must never be reused for ollama.
+        expect(message).not.toContain('openrouter.example');
+      },
+    );
+    // No creds lookup for ollama: we fail before reaching the creds branch.
+    expect(aiProviderCredentialsRepo.find).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.spec.ts b/apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.spec.ts
new file mode 100644
index 00000000..dd46b527
--- /dev/null
+++ b/apps/server/src/core/ai-chat/tools/public-share-chat-tools.service.spec.ts
@@ -0,0 +1,132 @@
+import { PublicShareChatToolsService } from './public-share-chat-tools.service';
+
+/**
+ * Mock-based integration tests for the anonymous public-share toolset built by
+ * forShare(). Constructed directly with hand-rolled collaborators (no Nest/DB):
+ *  - listSharePages tree assembly (dedupe, single-page root fallback, fail-soft);
+ *  - the blank-input guards on search / read.
+ */
+describe('PublicShareChatToolsService.forShare', () => {
+  type ToolExec = { execute: (args: unknown) => Promise<unknown> };
+
+  function makeService(over: {
+    getShareTree?: jest.Mock;
+    findById?: jest.Mock;
+    searchPage?: jest.Mock;
+    getShareForPage?: jest.Mock;
+  } = {}) {
+    const shareService = {
+      getShareTree: over.getShareTree ?? jest.fn(),
+      getShareForPage: over.getShareForPage ?? jest.fn(),
+      updatePublicAttachments: jest.fn(),
+    };
+    const searchService = { searchPage: over.searchPage ?? jest.fn() };
+    const pageRepo = { findById: over.findById ?? jest.fn() };
+    const pagePermissionRepo = { hasRestrictedAncestor: jest.fn() };
+    const svc = new PublicShareChatToolsService(
+      shareService as never,
+      searchService as never,
+      pageRepo as never,
+      pagePermissionRepo as never,
+    );
+    return { svc, shareService, searchService, pageRepo, pagePermissionRepo };
+  }
+
+  describe('listSharePages', () => {
+    it('includeSubPages tree: returns deduped, titled pages (root already in tree)', async () => {
+      // getShareTree returns the share root + descendants; the root IS in the
+      // tree, so no extra title lookup is needed and the tree is listed as-is.
+      const { svc, pageRepo } = makeService({
+        getShareTree: jest.fn().mockResolvedValue({
+          share: { pageId: 'root' },
+          pageTree: [
+            { id: 'root', title: 'Home' },
+            { id: 'child-1', title: 'Child One' },
+            { id: 'child-2', title: 'Child Two' },
+          ],
+        }),
+      });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      const out = (await (tools.listSharePages as unknown as ToolExec).execute(
+        {},
+      )) as Array<{ id: string; title: string }>;
+      expect(out).toEqual([
+        { id: 'root', title: 'Home' },
+        { id: 'child-1', title: 'Child One' },
+        { id: 'child-2', title: 'Child Two' },
+      ]);
+      // The root was already in the tree => no fallback title lookup.
+      expect(pageRepo.findById).not.toHaveBeenCalled();
+    });
+
+    it('single-page share (empty tree): falls back to the root title and PREPENDS it', async () => {
+      const { svc, pageRepo } = makeService({
+        getShareTree: jest.fn().mockResolvedValue({
+          share: { pageId: 'root' },
+          pageTree: [], // includeSubPages=false => empty tree
+        }),
+        findById: jest.fn().mockResolvedValue({ id: 'root', title: 'Solo Page' }),
+      });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      const out = (await (tools.listSharePages as unknown as ToolExec).execute(
+        {},
+      )) as Array<{ id: string; title: string }>;
+      expect(out).toEqual([{ id: 'root', title: 'Solo Page' }]);
+      expect(pageRepo.findById).toHaveBeenCalledWith('root');
+    });
+
+    it('de-duplicates pages by id, keeping the first (titled) occurrence', async () => {
+      const { svc } = makeService({
+        getShareTree: jest.fn().mockResolvedValue({
+          share: { pageId: 'root' },
+          pageTree: [
+            { id: 'root', title: 'Home' },
+            { id: 'dup', title: 'First' },
+            { id: 'dup', title: 'Second (dropped)' },
+            { id: 'root', title: 'Home again (dropped)' },
+          ],
+        }),
+      });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      const out = (await (tools.listSharePages as unknown as ToolExec).execute(
+        {},
+      )) as Array<{ id: string; title: string }>;
+      expect(out).toEqual([
+        { id: 'root', title: 'Home' },
+        { id: 'dup', title: 'First' },
+      ]);
+    });
+
+    it('getShareTree throws => returns [] (fail-soft, never throws to the model)', async () => {
+      const { svc } = makeService({
+        getShareTree: jest.fn().mockRejectedValue(new Error('db down')),
+      });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      await expect(
+        (tools.listSharePages as unknown as ToolExec).execute({}),
+      ).resolves.toEqual([]);
+    });
+  });
+
+  describe('searchSharePages blank guard', () => {
+    it('blank query => [] WITHOUT calling searchService', async () => {
+      const { svc, searchService } = makeService({ searchPage: jest.fn() });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      await expect(
+        (tools.searchSharePages as unknown as ToolExec).execute({ query: '   ' }),
+      ).resolves.toEqual([]);
+      expect(searchService.searchPage).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('getSharePage blank guard', () => {
+    it('blank pageId => throws "A pageId is required." WITHOUT calling getShareForPage', async () => {
+      const { svc, shareService } = makeService({ getShareForPage: jest.fn() });
+      const tools = svc.forShare('SHARE-A', 'ws-1');
+      await expect(
+        (tools.getSharePage as unknown as ToolExec).execute({ pageId: '   ' }),
+      ).rejects.toThrow('A pageId is required.');
+      expect(shareService.getShareForPage).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/apps/server/src/core/auth/services/verify-user-credentials.live.spec.ts b/apps/server/src/core/auth/services/verify-user-credentials.live.spec.ts
new file mode 100644
index 00000000..5504b3bd
--- /dev/null
+++ b/apps/server/src/core/auth/services/verify-user-credentials.live.spec.ts
@@ -0,0 +1,233 @@
+import { UnauthorizedException } from '@nestjs/common';
+import { AuthService } from './auth.service';
+import { CREDENTIALS_MISMATCH_MESSAGE } from '../auth.constants';
+import { hashPassword } from '../../../common/helpers';
+
+/**
+ * LIVE security contract for AuthService.verifyUserCredentials / login (M4
+ * item 5).
+ *
+ * The (now-fixed) jest config CAN import AuthService at the module level (the
+ * `^src/(.*)$` moduleNameMapper resolves the transitive `src/...` imports and the
+ * ts-jest transform loads the graph). AuthService cannot be `.compile()`-d via
+ * the Nest TestingModule (its full provider graph is not wired here), but it can
+ * be constructed directly with mocked collaborators — which is exactly what we
+ * need to exercise the credential-check decision live.
+ *
+ * The load-bearing property: verifyUserCredentials (and login(), which reuses it)
+ * throws EXACTLY the shared CREDENTIALS_MISMATCH_MESSAGE for all three
+ * credentials-failure cases — unknown email, disabled user, wrong password. The
+ * /mcp Basic brute-force limiter only counts a failure when it recognises THIS
+ * exact message (isCredentialsFailure in mcp-auth.helpers matches the same shared
+ * constant); a reword that diverged here would silently turn /mcp Basic into an
+ * unthrottled password-guessing oracle.
+ */
+
+const WORKSPACE_ID = 'ws-1';
+
+// Build an AuthService with the dependencies verifyUserCredentials/login touch
+// stubbed, and a userRepo whose findByEmail is overridable per test. Only the
+// collaborators actually reached on these paths need real behaviour; the rest
+// are inert mocks (constructor wiring only).
+function makeAuthService(over: {
+  findByEmail?: jest.Mock;
+} = {}): {
+  service: AuthService;
+  userRepo: { findByEmail: jest.Mock; updateLastLogin: jest.Mock };
+  sessionService: { createSessionAndToken: jest.Mock };
+  auditService: { log: jest.Mock };
+} {
+  const userRepo = {
+    findByEmail: over.findByEmail ?? jest.fn(),
+    updateLastLogin: jest.fn().mockResolvedValue(undefined),
+  };
+  const sessionService = {
+    createSessionAndToken: jest.fn().mockResolvedValue('issued-token'),
+  };
+  const auditService = { log: jest.fn() };
+  // environmentService: isCloud() false (so throwIfEmailNotVerified does not
+  // require verification) + a stable app secret.
+  const environmentService = {
+    isCloud: jest.fn().mockReturnValue(false),
+    getAppSecret: jest.fn().mockReturnValue('test-secret'),
+  };
+
+  // Constructor signature (auth.service.ts): signupService, tokenService,
+  // sessionService, userSessionRepo, userRepo, userTokenRepo, mailService,
+  // domainService, environmentService, db, auditService.
+  const service = new (AuthService as unknown as new (...args: unknown[]) => AuthService)(
+    {}, // signupService
+    {}, // tokenService
+    sessionService, // sessionService
+    {}, // userSessionRepo
+    userRepo, // userRepo
+    {}, // userTokenRepo
+    {}, // mailService
+    {}, // domainService
+    environmentService, // environmentService
+    {}, // db
+    auditService, // auditService
+  );
+
+  return { service, userRepo, sessionService, auditService };
+}
+
+describe('AuthService.verifyUserCredentials (live credentials-mismatch contract)', () => {
+  it('UNKNOWN email -> throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
+    const { service } = makeAuthService({
+      findByEmail: jest.fn().mockResolvedValue(undefined),
+    });
+
+    await expect(
+      service.verifyUserCredentials(
+        { email: 'nobody@example.com', password: 'whatever' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toMatchObject({ message: CREDENTIALS_MISMATCH_MESSAGE });
+    await expect(
+      service.verifyUserCredentials(
+        { email: 'nobody@example.com', password: 'whatever' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toBeInstanceOf(UnauthorizedException);
+  });
+
+  it('DISABLED user -> throws exactly CREDENTIALS_MISMATCH_MESSAGE (no password oracle)', async () => {
+    // A deactivated user must be indistinguishable from a wrong password: same
+    // message, before any password comparison.
+    const passwordHash = await hashPassword('correct-horse');
+    const disabledUser = {
+      id: 'u-1',
+      email: 'disabled@example.com',
+      password: passwordHash,
+      deactivatedAt: new Date(),
+      deletedAt: null,
+      emailVerifiedAt: new Date(),
+    };
+    const { service } = makeAuthService({
+      findByEmail: jest.fn().mockResolvedValue(disabledUser),
+    });
+
+    await expect(
+      service.verifyUserCredentials(
+        { email: 'disabled@example.com', password: 'correct-horse' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toMatchObject({ message: CREDENTIALS_MISMATCH_MESSAGE });
+  });
+
+  it('WRONG password -> throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
+    const passwordHash = await hashPassword('correct-horse');
+    const user = {
+      id: 'u-1',
+      email: 'user@example.com',
+      password: passwordHash,
+      deactivatedAt: null,
+      deletedAt: null,
+      emailVerifiedAt: new Date(),
+    };
+    const { service } = makeAuthService({
+      findByEmail: jest.fn().mockResolvedValue(user),
+    });
+
+    await expect(
+      service.verifyUserCredentials(
+        { email: 'user@example.com', password: 'wrong-password' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toMatchObject({ message: CREDENTIALS_MISMATCH_MESSAGE });
+  });
+
+  it('CORRECT credentials -> resolves the matched user (no side effects here)', async () => {
+    const passwordHash = await hashPassword('correct-horse');
+    const user = {
+      id: 'u-1',
+      email: 'user@example.com',
+      password: passwordHash,
+      deactivatedAt: null,
+      deletedAt: null,
+      emailVerifiedAt: new Date(),
+    };
+    const { service, sessionService, auditService, userRepo } =
+      makeAuthService({ findByEmail: jest.fn().mockResolvedValue(user) });
+
+    const result = await service.verifyUserCredentials(
+      { email: 'user@example.com', password: 'correct-horse' },
+      WORKSPACE_ID,
+    );
+    expect(result).toBe(user);
+    // verifyUserCredentials is non-side-effecting: no session/audit/lastLogin.
+    expect(sessionService.createSessionAndToken).not.toHaveBeenCalled();
+    expect(auditService.log).not.toHaveBeenCalled();
+    expect(userRepo.updateLastLogin).not.toHaveBeenCalled();
+  });
+});
+
+describe('AuthService.login (live credentials-mismatch contract via verifyUserCredentials)', () => {
+  it('UNKNOWN email -> login throws exactly CREDENTIALS_MISMATCH_MESSAGE, mints NO session', async () => {
+    const { service, sessionService } = makeAuthService({
+      findByEmail: jest.fn().mockResolvedValue(undefined),
+    });
+
+    await expect(
+      service.login(
+        { email: 'nobody@example.com', password: 'whatever' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toMatchObject({ message: CREDENTIALS_MISMATCH_MESSAGE });
+    expect(sessionService.createSessionAndToken).not.toHaveBeenCalled();
+  });
+
+  it('WRONG password -> login throws exactly CREDENTIALS_MISMATCH_MESSAGE', async () => {
+    const passwordHash = await hashPassword('correct-horse');
+    const user = {
+      id: 'u-1',
+      email: 'user@example.com',
+      password: passwordHash,
+      deactivatedAt: null,
+      deletedAt: null,
+      emailVerifiedAt: new Date(),
+    };
+    const { service } = makeAuthService({
+      findByEmail: jest.fn().mockResolvedValue(user),
+    });
+
+    await expect(
+      service.login(
+        { email: 'user@example.com', password: 'wrong-password' },
+        WORKSPACE_ID,
+      ),
+    ).rejects.toMatchObject({ message: CREDENTIALS_MISMATCH_MESSAGE });
+  });
+
+  it('CORRECT credentials -> login mints the session (the side-effecting path)', async () => {
+    const passwordHash = await hashPassword('correct-horse');
+    const user = {
+      id: 'u-1',
+      email: 'user@example.com',
+      password: passwordHash,
+      deactivatedAt: null,
+      deletedAt: null,
+      emailVerifiedAt: new Date(),
+    };
+    const { service, sessionService, auditService, userRepo } =
+      makeAuthService({ findByEmail: jest.fn().mockResolvedValue(user) });
+
+    await expect(
+      service.login(
+        { email: 'user@example.com', password: 'correct-horse' },
+        WORKSPACE_ID,
+      ),
+    ).resolves.toBe('issued-token');
+    // login() reuses verifyUserCredentials but DOES run the three side effects.
+    expect(userRepo.updateLastLogin).toHaveBeenCalledWith('u-1', WORKSPACE_ID);
+    expect(auditService.log).toHaveBeenCalled();
+    expect(sessionService.createSessionAndToken).toHaveBeenCalledWith(user);
+  });
+
+  it('the message login throws is the SAME shared constant the /mcp limiter matches', () => {
+    // Cross-file coupling lock: the constant is the single source of truth shared
+    // by AuthService and mcp-auth.helpers.isCredentialsFailure.
+    expect(CREDENTIALS_MISMATCH_MESSAGE).toBe('Email or password does not match');
+  });
+});
diff --git a/apps/server/src/core/page/transclusion/spec/page-embed.util.spec.ts b/apps/server/src/core/page/transclusion/spec/page-embed.util.spec.ts
index 2bdca7b7..9219154c 100644
--- a/apps/server/src/core/page/transclusion/spec/page-embed.util.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-embed.util.spec.ts
@@ -80,6 +80,67 @@ describe('collectPageEmbedsFromPmJson', () => {
     };
     expect(collectPageEmbedsFromPmJson(doc)).toEqual([]);
   });
+
+  it('ignores a pageEmbed whose sourcePageId is not a string', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'pageEmbed', attrs: { sourcePageId: 123 as any } },
+        { type: 'pageEmbed', attrs: { sourcePageId: null as any } },
+        { type: 'pageEmbed', attrs: { sourcePageId: { nested: true } as any } },
+        { type: 'pageEmbed', attrs: { sourcePageId: ['arr'] as any } },
+        // a valid one mixed in proves only the bad ones are dropped
+        { type: 'pageEmbed', attrs: { sourcePageId: 'good' } },
+      ],
+    };
+    expect(collectPageEmbedsFromPmJson(doc)).toEqual([
+      { sourcePageId: 'good' },
+    ]);
+  });
+
+  it('collects a pageEmbed nested under multiple block containers', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'columns',
+              content: [
+                {
+                  type: 'column',
+                  content: [
+                    {
+                      type: 'details',
+                      content: [
+                        {
+                          type: 'pageEmbed',
+                          attrs: { sourcePageId: 'deep' },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectPageEmbedsFromPmJson(doc)).toEqual([{ sourcePageId: 'deep' }]);
+  });
+
+  it('terminates (does not silently hang) on a self-referencing/cyclic object', () => {
+    // FINDING: there is NO explicit cycle guard. A hand-built cyclic JS object
+    // (which cannot arise from JSON parsing — the real input path) makes the
+    // recursive walk overflow the stack and throw a RangeError. It TERMINATES
+    // with a controlled error rather than recursing unboundedly forever, and a
+    // non-cyclic (JSON-shaped) document is never affected.
+    const node: any = { type: 'doc', content: [] };
+    node.content.push(node); // content array references its own parent node
+    expect(() => collectPageEmbedsFromPmJson(node)).toThrow(RangeError);
+  });
 });
 
 describe('pageEmbed HTML <-> JSON round-trip (server schema)', () => {
diff --git a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
index 3c497d80..2f37eb97 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template-access.spec.ts
@@ -68,6 +68,7 @@ describe('TransclusionService — template access core (real filter)', () => {
       {} as any, // attachmentRepo
       {} as any, // storageService
       {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
     return { service, db, pageRepo, spaceMemberRepo, pagePermissionRepo };
@@ -187,8 +188,103 @@ describe('TransclusionService — template access core (real filter)', () => {
   });
 });
 
+describe('TransclusionService.filterViewerAccessiblePageIds — AND ordering (content-leak control)', () => {
+  function makeDb(executeRows: Array<{ id: string }>) {
+    const builder: any = {};
+    builder.selectFrom = jest.fn(() => builder);
+    builder.select = jest.fn(() => builder);
+    builder.where = jest.fn(() => builder);
+    builder.execute = jest.fn(async () => executeRows);
+    return builder;
+  }
+
+  function makeService(opts: {
+    spaceVisibleRows: Array<{ id: string }>;
+    permissionAccessibleIds: string[];
+  }) {
+    const db = makeDb(opts.spaceVisibleRows);
+    const spaceMemberRepo = {
+      getUserSpaceIdsQuery: jest.fn(() => ({ __subquery: true })),
+    };
+    const filterAccessiblePageIds = jest
+      .fn()
+      .mockResolvedValue(opts.permissionAccessibleIds);
+    const pagePermissionRepo = { filterAccessiblePageIds };
+
+    const service = new TransclusionService(
+      db as any, // db
+      {} as any, // pageTransclusionsRepo
+      {} as any, // pageTransclusionReferencesRepo
+      {} as any, // pageTemplateReferencesRepo
+      {} as any, // pageRepo
+      pagePermissionRepo as any,
+      spaceMemberRepo as any,
+      {} as any, // attachmentRepo
+      {} as any, // storageService
+      {} as any, // pageAccessService
+      {} as any, // workspaceRepo
+    );
+
+    return { service, filterAccessiblePageIds };
+  }
+
+  it('space-visible AND permission-accessible → returned', async () => {
+    const { service } = makeService({
+      spaceVisibleRows: [{ id: 'p1' }],
+      permissionAccessibleIds: ['p1'],
+    });
+    const out = await service.filterViewerAccessiblePageIds(
+      ['p1'],
+      'u1',
+      'w1',
+    );
+    expect(out).toEqual(['p1']);
+  });
+
+  it('space-visible but permission-rejected → dropped', async () => {
+    const { service, filterAccessiblePageIds } = makeService({
+      spaceVisibleRows: [{ id: 'p1' }],
+      permissionAccessibleIds: [],
+    });
+    const out = await service.filterViewerAccessiblePageIds(
+      ['p1'],
+      'u1',
+      'w1',
+    );
+    expect(out).toEqual([]);
+    // The permission filter only ever sees the space-visible candidate.
+    expect(filterAccessiblePageIds).toHaveBeenCalledWith({
+      pageIds: ['p1'],
+      userId: 'u1',
+    });
+  });
+
+  it('NOT space-visible but permission-accessible → STILL dropped (AND-ordering enforced)', async () => {
+    // The page would pass page-level permission filtering, but it is not visible
+    // at the space level (e.g. a private space the viewer is not a member of).
+    // The space-visibility gate runs FIRST and short-circuits, so the page-level
+    // permission filter is never even consulted — preventing a private-space
+    // content leak via an unrestricted source page.
+    const { service, filterAccessiblePageIds } = makeService({
+      spaceVisibleRows: [],
+      permissionAccessibleIds: ['private-but-permitted'],
+    });
+    const out = await service.filterViewerAccessiblePageIds(
+      ['private-but-permitted'],
+      'u1',
+      'w1',
+    );
+    expect(out).toEqual([]);
+    expect(filterAccessiblePageIds).not.toHaveBeenCalled();
+  });
+});
+
 describe('TransclusionService.syncPageTemplateReferences — workspace scoping', () => {
-  function makeService(opts: { inWorkspaceIds: string[] }) {
+  function makeService(opts: {
+    inWorkspaceIds: string[];
+    /** existing rows already persisted for the reference page */
+    existingSourceIds?: string[];
+  }) {
     // db stub: the in-workspace existence query returns only allowed ids.
     const builder: any = {};
     builder.selectFrom = jest.fn(() => builder);
@@ -201,25 +297,37 @@ describe('TransclusionService.syncPageTemplateReferences — workspace scoping',
     const insertMany = jest.fn().mockResolvedValue(undefined);
     const deleteByReferenceAndSources = jest.fn().mockResolvedValue(undefined);
     const pageTemplateReferencesRepo = {
-      findByReferencePageId: jest.fn().mockResolvedValue([]),
+      findByReferencePageId: jest
+        .fn()
+        .mockResolvedValue(
+          (opts.existingSourceIds ?? []).map((sourcePageId) => ({
+            sourcePageId,
+          })),
+        ),
       insertMany,
       deleteByReferenceAndSources,
     };
 
     const service = new TransclusionService(
-      builder as any,
-      {} as any,
-      {} as any,
+      builder as any, // db
+      {} as any, // pageTransclusionsRepo
+      {} as any, // pageTransclusionReferencesRepo
       pageTemplateReferencesRepo as any,
-      {} as any,
-      {} as any,
-      {} as any,
-      {} as any,
-      {} as any,
-      {} as any,
+      {} as any, // pageRepo
+      {} as any, // pagePermissionRepo
+      {} as any, // spaceMemberRepo
+      {} as any, // attachmentRepo
+      {} as any, // storageService
+      {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
-    return { service, insertMany, pageTemplateReferencesRepo };
+    return {
+      service,
+      insertMany,
+      deleteByReferenceAndSources,
+      pageTemplateReferencesRepo,
+    };
   }
 
   function docWithEmbeds(sourceIds: string[]) {
@@ -264,4 +372,150 @@ describe('TransclusionService.syncPageTemplateReferences — workspace scoping',
     expect(result.inserted).toBe(0);
     expect(insertMany).not.toHaveBeenCalled();
   });
+
+  it('DELETE branch: an existing in-workspace ref removed from the doc is deleted', async () => {
+    // 'gone' was referenced before but is no longer in the doc; 'stay' remains.
+    const { service, insertMany, deleteByReferenceAndSources } = makeService({
+      inWorkspaceIds: ['stay'],
+      existingSourceIds: ['stay', 'gone'],
+    });
+
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      docWithEmbeds(['stay']),
+    );
+
+    expect(result.deleted).toBe(1);
+    expect(result.inserted).toBe(0); // 'stay' already existed
+    expect(insertMany).not.toHaveBeenCalled();
+    expect(deleteByReferenceAndSources).toHaveBeenCalledTimes(1);
+    expect(deleteByReferenceAndSources).toHaveBeenCalledWith(
+      'host',
+      ['gone'],
+      undefined, // no trx supplied
+    );
+  });
+
+  it('does NOT delete a stale ref whose source is now cross-workspace if it is also still embedded', async () => {
+    // Edge: 'x' is still embedded in the doc but no longer in-workspace. It is
+    // not in desiredIds (filtered out) AND it exists → it should be deleted, not
+    // kept, because the reference graph must drop the cross-workspace edge.
+    const { service, deleteByReferenceAndSources } = makeService({
+      inWorkspaceIds: [], // 'x' no longer in-workspace
+      existingSourceIds: ['x'],
+    });
+
+    const result = await service.syncPageTemplateReferences(
+      'host',
+      'w1',
+      docWithEmbeds(['x']),
+    );
+
+    expect(result.deleted).toBe(1);
+    expect(deleteByReferenceAndSources).toHaveBeenCalledWith(
+      'host',
+      ['x'],
+      undefined,
+    );
+  });
+});
+
+describe('TransclusionService.insertTemplateReferencesForPages — per-workspace existence validation', () => {
+  /**
+   * Smart db stub: each existence query is `.where('id','in', ids)` +
+   * `.where('workspaceId','=', wsId)`; `.execute()` returns only the ids that
+   * `validByWorkspace[wsId]` declares in-workspace. The builder snapshots the
+   * last `id`-in list and `workspaceId` value per chain (selectFrom resets).
+   */
+  function makeDb(validByWorkspace: Record<string, string[]>) {
+    const builder: any = {};
+    let curIds: string[] = [];
+    let curWs: string | undefined;
+    builder.selectFrom = jest.fn(() => {
+      curIds = [];
+      curWs = undefined;
+      return builder;
+    });
+    builder.select = jest.fn(() => builder);
+    builder.where = jest.fn((col: string, op: string, val: any) => {
+      if (col === 'id' && op === 'in') curIds = val;
+      if (col === 'workspaceId' && op === '=') curWs = val;
+      return builder;
+    });
+    builder.execute = jest.fn(async () => {
+      const valid = new Set(validByWorkspace[curWs ?? ''] ?? []);
+      return curIds.filter((id) => valid.has(id)).map((id) => ({ id }));
+    });
+    return builder;
+  }
+
+  function makeService(validByWorkspace: Record<string, string[]>) {
+    const insertMany = jest.fn().mockResolvedValue(undefined);
+    const pageTemplateReferencesRepo = { insertMany };
+    const service = new TransclusionService(
+      makeDb(validByWorkspace) as any, // db
+      {} as any, // pageTransclusionsRepo
+      {} as any, // pageTransclusionReferencesRepo
+      pageTemplateReferencesRepo as any,
+      {} as any, // pageRepo
+      {} as any, // pagePermissionRepo
+      {} as any, // spaceMemberRepo
+      {} as any, // attachmentRepo
+      {} as any, // storageService
+      {} as any, // pageAccessService
+      {} as any, // workspaceRepo
+    );
+    return { service, insertMany };
+  }
+
+  const embedDoc = (ids: string[]) => ({
+    type: 'doc',
+    content: ids.map((id) => ({
+      type: 'pageEmbed',
+      attrs: { sourcePageId: id },
+    })),
+  });
+
+  it('validates each workspace separately: a source in-ws for A but cross-ws for B inserts only the valid delta', async () => {
+    // 'shared' is in-workspace for wA but NOT for wB. Page A embeds 'shared'
+    // (valid → inserted). Page B embeds 'shared' (cross-ws for wB → dropped).
+    const { service, insertMany } = makeService({
+      wA: ['shared'],
+      wB: [], // 'shared' is not a page in wB
+    });
+
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'pageA', workspaceId: 'wA', content: embedDoc(['shared']) },
+      { id: 'pageB', workspaceId: 'wB', content: embedDoc(['shared']) },
+    ]);
+
+    expect(result.inserted).toBe(1);
+    expect(insertMany).toHaveBeenCalledTimes(1);
+    expect(insertMany.mock.calls[0][0]).toEqual([
+      { workspaceId: 'wA', referencePageId: 'pageA', sourcePageId: 'shared' },
+    ]);
+  });
+
+  it('inserts the in-workspace deltas for both pages when each is valid in its own workspace', async () => {
+    const { service, insertMany } = makeService({
+      wA: ['a-src'],
+      wB: ['b-src'],
+    });
+
+    const result = await service.insertTemplateReferencesForPages([
+      { id: 'pageA', workspaceId: 'wA', content: embedDoc(['a-src']) },
+      { id: 'pageB', workspaceId: 'wB', content: embedDoc(['b-src']) },
+    ]);
+
+    expect(result.inserted).toBe(2);
+    const rows = insertMany.mock.calls[0][0];
+    expect(rows).toEqual(
+      expect.arrayContaining([
+        { workspaceId: 'wA', referencePageId: 'pageA', sourcePageId: 'a-src' },
+        { workspaceId: 'wB', referencePageId: 'pageB', sourcePageId: 'b-src' },
+      ]),
+    );
+    expect(rows).toHaveLength(2);
+  });
 });
diff --git a/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
index f62a047c..fbcd9486 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template-lookup.spec.ts
@@ -1,4 +1,5 @@
 import { TransclusionService } from '../transclusion.service';
+import * as collabUtil from '../../../../collaboration/collaboration.util';
 
 /**
  * Exercises the pure access/mapping logic of `lookupTemplate`:
@@ -34,6 +35,7 @@ describe('TransclusionService.lookupTemplate (access mapping)', () => {
       {} as any, // attachmentRepo
       {} as any, // storageService
       {} as any, // pageAccessService
+      {} as any, // workspaceRepo
     );
 
     jest
@@ -110,4 +112,61 @@ describe('TransclusionService.lookupTemplate (access mapping)', () => {
     expect((items[1] as any).status).toBeUndefined();
     expect((items[2] as any).status).toBe('no_access');
   });
+
+  // Content-prep failure path: if jsonToNode throws for an accessible page, the
+  // item must degrade to not_found and NEVER return content (which would
+  // otherwise carry the source's un-stripped comment marks).
+  describe('content-prep failure → not_found', () => {
+    let jsonToNodeSpy: jest.SpyInstance;
+
+    afterEach(() => {
+      jsonToNodeSpy?.mockRestore();
+    });
+
+    it('maps to not_found and returns no content when jsonToNode throws', async () => {
+      // The page is accessible and present, but content preparation blows up.
+      jsonToNodeSpy = jest
+        .spyOn(collabUtil, 'jsonToNode')
+        .mockImplementation(() => {
+          throw new Error('boom');
+        });
+
+      const contentWithComment = {
+        type: 'doc',
+        content: [
+          {
+            type: 'paragraph',
+            content: [
+              {
+                type: 'text',
+                text: 'secret',
+                marks: [{ type: 'comment', attrs: { commentId: 'leak' } }],
+              },
+            ],
+          },
+        ],
+      };
+
+      const { service } = makeService({
+        accessibleIds: ['p1'],
+        pages: [
+          {
+            id: 'p1',
+            title: 'T',
+            icon: null,
+            content: contentWithComment,
+            updatedAt: now,
+          },
+        ],
+      });
+
+      // Silence the service's error logger for the expected throw.
+      jest.spyOn((service as any).logger, 'error').mockImplementation(() => {});
+
+      const { items } = await service.lookupTemplate(['p1'], 'u1', 'w1');
+      expect(items).toEqual([{ sourcePageId: 'p1', status: 'not_found' }]);
+      // Crucially: no content field, so no comment mark can leak.
+      expect((items[0] as any).content).toBeUndefined();
+    });
+  });
 });
diff --git a/apps/server/src/core/page/transclusion/spec/page-template.controller.spec.ts b/apps/server/src/core/page/transclusion/spec/page-template.controller.spec.ts
index 2de644e0..df340b13 100644
--- a/apps/server/src/core/page/transclusion/spec/page-template.controller.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/page-template.controller.spec.ts
@@ -1,7 +1,10 @@
 import { Test } from '@nestjs/testing';
 import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
 import { PageTemplateController } from '../page-template.controller';
 import { TransclusionService } from '../transclusion.service';
+import { TemplateLookupDto } from '../dto/template-lookup.dto';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { PageAccessService } from '../../page-access/page-access.service';
 import { JwtAuthGuard } from '../../../../common/guards/jwt-auth.guard';
@@ -90,4 +93,52 @@ describe('PageTemplateController.toggleTemplate', () => {
     );
     expect(out).toEqual({ pageId: 'p1', isTemplate: false });
   });
+
+  it('lookup forwards dto.sourcePageIds + user.id + user.workspaceId to the service', async () => {
+    const expected = { items: [] };
+    (transclusionService.lookupTemplate as jest.Mock).mockResolvedValue(
+      expected,
+    );
+
+    const dto = { sourcePageIds: ['s1', 's2'] } as any;
+    const out = await controller.lookup(dto, user);
+
+    expect(transclusionService.lookupTemplate).toHaveBeenCalledWith(
+      ['s1', 's2'],
+      'u1', // user.id
+      'w1', // user.workspaceId
+    );
+    expect(out).toBe(expected);
+  });
+});
+
+describe('TemplateLookupDto validation (class-validator)', () => {
+  const uuid = (n: number) =>
+    `00000000-0000-4000-8000-${String(n).padStart(12, '0')}`;
+
+  it('accepts an array of <=50 valid UUIDs', async () => {
+    const dto = plainToInstance(TemplateLookupDto, {
+      sourcePageIds: [uuid(1), uuid(2)],
+    });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('rejects an over-cap array (ArrayMaxSize 50)', async () => {
+    const dto = plainToInstance(TemplateLookupDto, {
+      sourcePageIds: Array.from({ length: 51 }, (_, i) => uuid(i)),
+    });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].constraints).toHaveProperty('arrayMaxSize');
+  });
+
+  it('rejects a non-UUID member (IsUUID each)', async () => {
+    const dto = plainToInstance(TemplateLookupDto, {
+      sourcePageIds: [uuid(1), 'not-a-uuid'],
+    });
+    const errors = await validate(dto);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].constraints).toHaveProperty('isUuid');
+  });
 });
diff --git a/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts b/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
index 8ad13121..4d149369 100644
--- a/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
+++ b/apps/server/src/core/page/transclusion/spec/transclusion-unsync-html-embed.spec.ts
@@ -56,6 +56,7 @@ function buildService(featureEnabled = true) {
     {} as any, // db (unused on this path)
     pageTransclusionsRepo as any,
     pageTransclusionReferencesRepo as any,
+    {} as any, // pageTemplateReferencesRepo (unused on this path)
     pageRepo as any,
     {} as any, // pagePermissionRepo (unused)
     {} as any, // spaceMemberRepo (unused)
diff --git a/apps/server/src/core/share/share-html-embed.spec.ts b/apps/server/src/core/share/share-html-embed.spec.ts
index 1bfeff1c..162ba4ae 100644
--- a/apps/server/src/core/share/share-html-embed.spec.ts
+++ b/apps/server/src/core/share/share-html-embed.spec.ts
@@ -131,3 +131,131 @@ describe('ShareService htmlEmbed server-authoritative kill-switch (real code)',
     expect(hasHtmlEmbedNode(out)).toBe(true);
   });
 });
+
+// Exercises the REAL ShareService.lookupTransclusionForShare post-processing for
+// the share-served transclusion path: the same server-authoritative htmlEmbed
+// kill-switch must apply to each transcluded item's content, and a not_found
+// item must never be run through prepareContentForShare (so its absent content
+// can't be serialized/leaked). The access graph (shareRepo / isSharingAllowed /
+// getShareForPage / restricted-ancestor) is stubbed so the strip/serve mapping
+// runs deterministically; lookupWithAccessSet is mocked to control the items.
+describe('ShareService.lookupTransclusionForShare htmlEmbed kill-switch (real code)', () => {
+  const SHARE = 'share-1';
+  const SPACE = 'space-1';
+  const SRC = 'src-page';
+
+  function buildTransclusionService(opts: {
+    htmlEmbed?: boolean | undefined;
+    items: any[];
+  }) {
+    const shareRepo = {
+      findById: jest.fn(async () => ({
+        id: SHARE,
+        workspaceId: WS,
+        spaceId: SPACE,
+      })),
+    };
+    const pageRepo = { findById: jest.fn() };
+    const pagePermissionRepo = {
+      hasRestrictedAncestor: jest.fn(async () => false),
+    };
+    const tokenService = {
+      generateAttachmentToken: jest.fn(async () => 'tok'),
+    };
+    const lookupWithAccessSet = jest.fn(async () => ({ items: opts.items }));
+    const transclusionService = { lookupWithAccessSet };
+    const workspaceRepo = {
+      findById: jest.fn(async () => ({
+        id: WS,
+        settings: { htmlEmbed: opts.htmlEmbed },
+      })),
+    };
+
+    const service = new ShareService(
+      shareRepo as any,
+      pageRepo as any,
+      pagePermissionRepo as any,
+      {} as any, // db (unused — isSharingAllowed stubbed below)
+      tokenService as any,
+      transclusionService as any,
+      workspaceRepo as any,
+    );
+
+    // isSharingAllowed and getShareForPage hit the raw db; stub them so the
+    // access chain resolves SRC as reachable and prepareContentForShare runs.
+    jest.spyOn(service, 'isSharingAllowed').mockResolvedValue(true);
+    jest
+      .spyOn(service, 'getShareForPage')
+      .mockResolvedValue({ pageId: SRC, spaceId: SPACE, id: 's2' } as any);
+
+    return { service, transclusionService, lookupWithAccessSet };
+  }
+
+  const transcludedItemWithEmbed = () => ({
+    sourcePageId: SRC,
+    transclusionId: 't1',
+    content: {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'block body' }] },
+        { type: 'htmlEmbed', attrs: { source: '<script>t()</script>' } },
+      ],
+    },
+    sourceUpdatedAt: new Date('2026-06-20T00:00:00.000Z'),
+  });
+
+  const refs = [{ sourcePageId: SRC, transclusionId: 't1' }];
+
+  it('toggle OFF: strips htmlEmbed from each transcluded item content', async () => {
+    const { service } = buildTransclusionService({
+      htmlEmbed: false,
+      items: [transcludedItemWithEmbed()],
+    });
+
+    const { items } = await service.lookupTransclusionForShare(SHARE, refs, WS);
+    expect(items).toHaveLength(1);
+    const item = items[0] as any;
+    expect(item.status).toBeUndefined();
+    expect(hasHtmlEmbedNode(item.content)).toBe(false);
+    // Non-embed body of the transcluded block is preserved.
+    expect(JSON.stringify(item.content)).toContain('block body');
+  });
+
+  it('toggle ON: serves htmlEmbed in the transcluded item content', async () => {
+    const { service } = buildTransclusionService({
+      htmlEmbed: true,
+      items: [transcludedItemWithEmbed()],
+    });
+
+    const { items } = await service.lookupTransclusionForShare(SHARE, refs, WS);
+    const item = items[0] as any;
+    expect(item.status).toBeUndefined();
+    expect(hasHtmlEmbedNode(item.content)).toBe(true);
+    expect(JSON.stringify(item.content)).toContain('block body');
+  });
+
+  it('a not_found item is NOT run through prepareContentForShare (no token minting)', async () => {
+    const notFoundItem = {
+      sourcePageId: SRC,
+      transclusionId: 't1',
+      status: 'not_found' as const,
+    };
+    const { service } = buildTransclusionService({
+      htmlEmbed: true,
+      items: [notFoundItem],
+    });
+    // tokenService is reachable via the service; spy on it to assert it is never
+    // touched for a status item (prepareContentForShare mints tokens).
+    const tokenSpy = jest.spyOn(
+      (service as any).tokenService,
+      'generateAttachmentToken',
+    );
+
+    const { items } = await service.lookupTransclusionForShare(SHARE, refs, WS);
+    // not_found is collapsed to no_access for share viewers and carries NO content.
+    const item = items[0] as any;
+    expect(item.status).toBe('no_access');
+    expect(item.content).toBeUndefined();
+    expect(tokenSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/server/src/core/workspace/services/workspace-html-embed.spec.ts b/apps/server/src/core/workspace/services/workspace-html-embed.spec.ts
new file mode 100644
index 00000000..fda0f5fa
--- /dev/null
+++ b/apps/server/src/core/workspace/services/workspace-html-embed.spec.ts
@@ -0,0 +1,111 @@
+import { WorkspaceService } from './workspace.service';
+
+/**
+ * Exercises the REAL WorkspaceService.update htmlEmbed-toggle persistence at the
+ * service seam: an update carrying `htmlEmbed` must call
+ * `workspaceRepo.updateSetting(workspaceId, 'htmlEmbed', value, trx)`, and an
+ * update WITHOUT it must not touch that setting. The repo, db transaction, and
+ * audit service are mocked; `executeTx` runs the callback against a fake trx.
+ *
+ * DEFERRED (DB-only): the "does not clobber sibling settings" guarantee is a
+ * jsonb merge property of `updateSetting`'s SQL and needs a real Postgres to
+ * assert. This spec only asserts the service-level CALL SHAPE.
+ */
+describe('WorkspaceService.update — htmlEmbed toggle persistence (real code)', () => {
+  function buildService(opts: { settingsBefore?: Record<string, any> }) {
+    const updateSetting = jest.fn().mockResolvedValue(undefined);
+    const updateWorkspace = jest.fn().mockResolvedValue(undefined);
+    const workspaceRepo = {
+      // First call: read settingsBefore. Second call: return the updated
+      // workspace (must include a licenseKey because update() destructures it).
+      findById: jest
+        .fn()
+        .mockResolvedValueOnce({ id: 'w1', settings: opts.settingsBefore ?? {} })
+        .mockResolvedValueOnce({ id: 'w1', name: 'WS', licenseKey: null }),
+      updateSetting,
+      updateWorkspace,
+    };
+
+    // Fake kysely db: only .transaction().execute(cb) is used on this path.
+    const db = {
+      transaction: jest.fn(() => ({
+        execute: jest.fn(async (cb: any) => cb({ __trx: true })),
+      })),
+    };
+
+    const auditService = { log: jest.fn() };
+
+    const service = new WorkspaceService(
+      workspaceRepo as any, // workspaceRepo
+      {} as any, // spaceService
+      {} as any, // spaceMemberService
+      {} as any, // groupRepo
+      {} as any, // groupUserRepo
+      {} as any, // userRepo
+      {} as any, // environmentService
+      {} as any, // domainService
+      {} as any, // licenseCheckService
+      {} as any, // shareRepo
+      {} as any, // watcherRepo
+      {} as any, // favoriteRepo
+      db as any, // db (InjectKysely)
+      {} as any, // attachmentQueue
+      {} as any, // billingQueue
+      {} as any, // aiQueue
+      auditService as any, // auditService
+      {} as any, // userSessionRepo
+    );
+
+    return { service, workspaceRepo, updateSetting, auditService };
+  }
+
+  it('persists htmlEmbed:true via updateSetting with the htmlEmbed key', async () => {
+    const { service, updateSetting } = buildService({});
+
+    await service.update('w1', { htmlEmbed: true } as any);
+
+    expect(updateSetting).toHaveBeenCalledTimes(1);
+    expect(updateSetting).toHaveBeenCalledWith(
+      'w1',
+      'htmlEmbed',
+      true,
+      expect.anything(), // the transaction handle
+    );
+  });
+
+  it('persists htmlEmbed:false (explicit disable is not dropped)', async () => {
+    const { service, updateSetting } = buildService({
+      settingsBefore: { htmlEmbed: true },
+    });
+
+    await service.update('w1', { htmlEmbed: false } as any);
+
+    expect(updateSetting).toHaveBeenCalledWith(
+      'w1',
+      'htmlEmbed',
+      false,
+      expect.anything(),
+    );
+  });
+
+  it('does NOT call updateSetting when htmlEmbed is undefined in the dto', async () => {
+    const { service, updateSetting } = buildService({});
+
+    await service.update('w1', { name: 'New name' } as any);
+
+    expect(updateSetting).not.toHaveBeenCalled();
+  });
+
+  it('audits the htmlEmbed change (before/after) when the value actually changes', async () => {
+    const { service, auditService } = buildService({
+      settingsBefore: { htmlEmbed: false },
+    });
+
+    await service.update('w1', { htmlEmbed: true } as any);
+
+    expect(auditService.log).toHaveBeenCalledTimes(1);
+    const logged = auditService.log.mock.calls[0][0];
+    expect(logged.changes.before.htmlEmbed).toBe(false);
+    expect(logged.changes.after.htmlEmbed).toBe(true);
+  });
+});
diff --git a/apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts b/apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts
index b5e4ed98..4adfa677 100644
--- a/apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts
+++ b/apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts
@@ -132,7 +132,7 @@ export class AiAgentRoleRepo {
  * generated column type is the broad `JsonValue` union, which a concrete object
  * type is not structurally assignable to.
  */
-function jsonbObject(value: ModelConfigValue | undefined) {
+export function jsonbObject(value: ModelConfigValue | undefined) {
   if (value === null || value === undefined || Object.keys(value).length === 0) {
     return null;
   }
diff --git a/apps/server/src/integrations/ai/ai-error.util.spec.ts b/apps/server/src/integrations/ai/ai-error.util.spec.ts
index c9b7fb3e..414701d4 100644
--- a/apps/server/src/integrations/ai/ai-error.util.spec.ts
+++ b/apps/server/src/integrations/ai/ai-error.util.spec.ts
@@ -58,4 +58,26 @@ describe('describeProviderError', () => {
     // 'e | response body: ' + 300 chars + '…'
     expect(out.length).toBeLessThan('e | response body: '.length + 305);
   });
+
+  it('uses the fallback for a numeric or boolean (non-object, non-string) error', () => {
+    // typeof number / boolean is neither 'object' nor a non-empty 'string', so
+    // the early branch returns the fallback verbatim.
+    expect(describeProviderError(500, 'AI stream error')).toBe('AI stream error');
+    expect(describeProviderError(0, 'AI stream error')).toBe('AI stream error');
+    expect(describeProviderError(true)).toBe('Unknown error');
+    expect(describeProviderError(false, 'fb')).toBe('fb');
+  });
+
+  it('statusCode present but message undefined => "<code>:" with no trailing space', () => {
+    // `${code}: ${undefined ?? ''}`.trim() collapses to just "<code>:".
+    expect(describeProviderError({ statusCode: 503 })).toBe('503:');
+    // The trailing space after the colon is trimmed away.
+    expect(describeProviderError({ statusCode: 503 }).endsWith(': ')).toBe(false);
+  });
+
+  it('object with neither message nor statusCode nor body => fallback', () => {
+    expect(describeProviderError({}, 'AI stream error')).toBe('AI stream error');
+    // An object carrying only unrelated keys is still treated as message-less.
+    expect(describeProviderError({ foo: 'bar' } as never)).toBe('Unknown error');
+  });
 });
diff --git a/apps/server/src/integrations/ai/ai.service.spec.ts b/apps/server/src/integrations/ai/ai.service.spec.ts
index 7bedc23a..ef44a59d 100644
--- a/apps/server/src/integrations/ai/ai.service.spec.ts
+++ b/apps/server/src/integrations/ai/ai.service.spec.ts
@@ -171,4 +171,117 @@ describe('AiService.getChatModel role model override', () => {
     expect(aiProviderCredentialsRepo.find).not.toHaveBeenCalled();
     expect(secretBox.decryptSecret).not.toHaveBeenCalled();
   });
+
+  /**
+   * Build a service whose workspace driver is ollama (no apiKey, with a baseUrl).
+   * Complements makeService (which configures openai) for the same-driver and
+   * not-configured ollama cases.
+   */
+  function makeOllamaService(over: { baseUrl?: string } = {}) {
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: 'ollama',
+        chatModel: 'llama3',
+        apiKey: undefined,
+        baseUrl: over.baseUrl ?? 'http://localhost:11434/v1',
+      }),
+    };
+    const aiProviderCredentialsRepo = { find: jest.fn() };
+    const secretBox = { decryptSecret: jest.fn() };
+    const service = new AiService(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiSettings as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiProviderCredentialsRepo as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      secretBox as any,
+    );
+    return { service, aiSettings, aiProviderCredentialsRepo, secretBox };
+  }
+
+  it('same-driver ollama override (workspace driver=ollama): reuses the workspace ollama baseUrl, no creds lookup/decrypt', async () => {
+    // Workspace driver IS ollama. A role that overrides to ollama (same driver)
+    // legitimately reuses the workspace's configured ollama endpoint — it must
+    // NOT hit the cross-driver 503 path, NOT query ai_provider_credentials, and
+    // NOT decrypt anything (ollama needs no key).
+    const { service, aiProviderCredentialsRepo, secretBox } = makeOllamaService();
+
+    const model = await service.getChatModel('ws-1', {
+      driver: 'ollama',
+      chatModel: 'llama3.1',
+      roleName: 'Local',
+    });
+
+    expect(model).toBeDefined();
+    expect(aiProviderCredentialsRepo.find).not.toHaveBeenCalled();
+    expect(secretBox.decryptSecret).not.toHaveBeenCalled();
+  });
+
+  it('chatModel-only override on an ollama workspace: reuses the workspace ollama baseUrl, no creds lookup', async () => {
+    // No override.driver on an ollama workspace => the workspace ollama driver +
+    // baseUrl are reused; no creds lookup, no decrypt (the cheap public-share
+    // model-only override path against an ollama workspace).
+    const { service, aiProviderCredentialsRepo, secretBox } = makeOllamaService();
+
+    const model = await service.getChatModel('ws-1', { chatModel: 'mistral' });
+
+    expect(model).toBeDefined();
+    expect(aiProviderCredentialsRepo.find).not.toHaveBeenCalled();
+    expect(secretBox.decryptSecret).not.toHaveBeenCalled();
+  });
+
+  it('blank chatModel guard: workspace has a driver but a blank chatModel and no override chatModel => AiNotConfiguredException', async () => {
+    // cfg.driver passes the first guard, but cfg.chatModel is blank and the
+    // override carries no chatModel, so the effective chatModel is empty.
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: 'openai',
+        chatModel: '',
+        apiKey: 'workspace-key',
+        baseUrl: undefined,
+      }),
+    };
+    const aiProviderCredentialsRepo = { find: jest.fn() };
+    const secretBox = { decryptSecret: jest.fn() };
+    const service = new AiService(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiSettings as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiProviderCredentialsRepo as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      secretBox as any,
+    );
+
+    await expect(
+      // Override has only a roleName, no chatModel to fill the blank.
+      service.getChatModel('ws-1', { roleName: 'Writer' }),
+    ).rejects.toBeInstanceOf(AiNotConfiguredException);
+  });
+
+  it('non-ollama driver with a missing apiKey => AiNotConfiguredException', async () => {
+    // Workspace is openai (non-ollama) with a model but NO apiKey: the combined
+    // `driver !== ollama && !apiKey` guard must 503.
+    const aiSettings = {
+      resolve: jest.fn().mockResolvedValue({
+        driver: 'openai',
+        chatModel: 'gpt-4o-mini',
+        apiKey: undefined,
+        baseUrl: undefined,
+      }),
+    };
+    const aiProviderCredentialsRepo = { find: jest.fn() };
+    const secretBox = { decryptSecret: jest.fn() };
+    const service = new AiService(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiSettings as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      aiProviderCredentialsRepo as any,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      secretBox as any,
+    );
+
+    await expect(service.getChatModel('ws-1')).rejects.toBeInstanceOf(
+      AiNotConfiguredException,
+    );
+  });
 });
diff --git a/apps/server/src/integrations/mcp/mcp-auth.helpers.ts b/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
index 4a0b5be1..0d1237e7 100644
--- a/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
+++ b/apps/server/src/integrations/mcp/mcp-auth.helpers.ts
@@ -359,6 +359,111 @@ export function isInitializeRequestBody(body: unknown): boolean {
   return (body as { method?: unknown }).method === 'initialize';
 }
 
+/**
+ * The outcome of McpService.handle's pre-hijack gauntlet, as a pure value the
+ * caller acts on. Either send a JSON error with a fixed status (`respond`), or
+ * proceed to hijack the response and delegate to the MCP transport (`hijack`).
+ * Keeping this a pure decision (no FastifyReply, no res.hijack) makes the
+ * status/body mapping unit-testable, and guarantees no error path can leak the
+ * password or Authorization header — the body is only ever a fixed string or the
+ * UnauthorizedException's own message.
+ */
+export type McpHandleDecision =
+  | { kind: 'respond'; status: number; body: { error: string } }
+  | { kind: 'hijack' };
+
+/**
+ * Pure mapping of McpService.handle's auth/enablement gauntlet to a response
+ * decision. Precedence mirrors handle():
+ *   1. shared X-MCP-Token mismatch -> 401 {error:'Unauthorized'} (no hijack).
+ *   2. workspace MCP disabled      -> 403 {error:'MCP is disabled ...'}.
+ *   3. resolveSessionConfig threw:
+ *        - an UnauthorizedException -> 401 with err.message (a SPECIFIC reason;
+ *          never the password/header — the message is the only thing surfaced).
+ *        - any other error          -> 500 generic 'Internal server error'.
+ *   4. otherwise (auth resolved)   -> hijack and delegate to the transport.
+ */
+export function mapAuthResultToResponse(input: {
+  sharedTokenOk: boolean;
+  enabled: boolean;
+  error?: unknown;
+}): McpHandleDecision {
+  if (!input.sharedTokenOk) {
+    return { kind: 'respond', status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  if (!input.enabled) {
+    return {
+      kind: 'respond',
+      status: 403,
+      body: { error: 'MCP is disabled for this workspace' },
+    };
+  }
+
+  if (input.error !== undefined) {
+    if (input.error instanceof UnauthorizedException) {
+      return {
+        kind: 'respond',
+        status: 401,
+        body: { error: input.error.message },
+      };
+    }
+    return {
+      kind: 'respond',
+      status: 500,
+      body: { error: 'Internal server error' },
+    };
+  }
+
+  return { kind: 'hijack' };
+}
+
+// Result of the EE MFA module's requirement check for the Basic gate. Both
+// flags absent/false means MFA does not block the password login.
+export interface BasicGateMfaResult {
+  userHasMfa?: boolean;
+  requiresMfaSetup?: boolean;
+}
+
+/**
+ * Pure decision logic for the /mcp HTTP-Basic pre-token gate, replicating EXACTLY
+ * what AuthController.login enforces before issuing a token, so the Basic path is
+ * not an SSO/MFA bypass. Framework-free (no ModuleRef, no on-disk EE MFA module)
+ * so the SSO/MFA decision is unit-testable in isolation:
+ *
+ *   - `ssoEnforced` true  -> throw Unauthorized ("enforced SSO"); a password
+ *      login is not allowed on an SSO-enforced workspace.
+ *   - otherwise, `mfa` is the EE MFA module's requirement result (or undefined
+ *      when no EE MFA module is bundled — a community/fork build). If MFA is
+ *      present and the user has MFA enabled OR needs MFA setup, throw Unauthorized
+ *      telling the caller to use a Bearer access token (Basic cannot complete MFA).
+ *   - no SSO + no MFA gate -> resolve (the Basic login is allowed to proceed).
+ *
+ * McpService.enforceBasicLoginGate wires the concrete `validateSsoEnforcement`
+ * result and the lazily-loaded MFA module result into this, so the gate decision
+ * itself carries no framework dependencies. Throws UnauthorizedException on
+ * rejection (surfaced as a clean 401); never logs the password.
+ */
+export function decideBasicGate(input: {
+  ssoEnforced: boolean;
+  mfa?: BasicGateMfaResult;
+}): void {
+  if (input.ssoEnforced) {
+    throw new UnauthorizedException(
+      'This workspace has enforced SSO login. Use SSO; MCP HTTP Basic is not allowed.',
+    );
+  }
+
+  const mfa = input.mfa;
+  if (mfa && (mfa.userHasMfa || mfa.requiresMfaSetup)) {
+    throw new UnauthorizedException(
+      'This account requires multi-factor authentication. MCP HTTP Basic ' +
+        'cannot complete MFA — log in normally and use a Bearer access token ' +
+        'instead.',
+    );
+  }
+}
+
 /** Extract a Bearer token from an Authorization header (case-insensitive). */
 export function extractBearer(
   authHeader: string | undefined,
diff --git a/apps/server/src/integrations/mcp/mcp.service.spec.ts b/apps/server/src/integrations/mcp/mcp.service.spec.ts
index bf4c8a24..e8a57748 100644
--- a/apps/server/src/integrations/mcp/mcp.service.spec.ts
+++ b/apps/server/src/integrations/mcp/mcp.service.spec.ts
@@ -9,6 +9,9 @@ import {
   sharedTokenMatches,
   clientIp,
   bindAccessJwtVerifier,
+  extractBearer,
+  decideBasicGate,
+  mapAuthResultToResponse,
   McpAuthDeps,
 } from './mcp-auth.helpers';
 import { JwtType } from '../../core/auth/dto/jwt-payload';
@@ -79,6 +82,26 @@ describe('parseBasicAuth', () => {
   });
 });
 
+describe('extractBearer', () => {
+  it('extracts the token from a "Bearer <token>" header', () => {
+    expect(extractBearer('Bearer abc.def.ghi')).toBe('abc.def.ghi');
+  });
+
+  it('is case-insensitive on the scheme (lowercase + uppercase)', () => {
+    // The split keeps the token as-is; only the scheme is compared lowercased.
+    expect(extractBearer('bearer abc')).toBe('abc');
+    expect(extractBearer('BEARER abc')).toBe('abc');
+  });
+
+  it('returns undefined for a non-Bearer scheme (e.g. Basic)', () => {
+    expect(extractBearer('Basic abc')).toBeUndefined();
+  });
+
+  it('returns undefined for an undefined header', () => {
+    expect(extractBearer(undefined)).toBeUndefined();
+  });
+});
+
 describe('isCredentialsFailure', () => {
   it('is true for the credentials-mismatch UnauthorizedException', () => {
     expect(
@@ -185,6 +208,43 @@ describe('FailedLoginLimiter', () => {
     expect(lim.isBlocked(k, 0)).toBe(true);
     expect(lim.isBlocked(k, 1000)).toBe(false);
   });
+
+  describe('sweep (expired-bucket eviction, injectable clock)', () => {
+    // sweep() drops buckets whose windowStart is older than windowMs so
+    // never-revisited keys cannot accumulate forever. It takes an injectable
+    // `now` so the behaviour is deterministic without faking timers.
+    it('drops a bucket strictly older than windowMs', () => {
+      const lim = new FailedLoginLimiter(5, 1000);
+      // Seed a bucket at t=0 (windowStart=0).
+      lim.recordFailure('stale', 0);
+      // Sweep well past the window: now - windowStart = 5000 >= 1000 -> dropped.
+      lim.sweep(5000);
+      // A dropped bucket means a brand-new bucket is created on next touch, so
+      // the prior failure count is gone (a single fresh failure is far from 5).
+      lim.recordFailure('stale', 5001);
+      expect(lim.isBlocked('stale', 5001)).toBe(false);
+    });
+
+    it('drops a bucket exactly at the windowMs boundary (>= is inclusive)', () => {
+      const lim = new FailedLoginLimiter(1, 1000);
+      lim.recordFailure('boundary', 0); // windowStart=0, blocked at threshold 1
+      expect(lim.isBlocked('boundary', 0)).toBe(true);
+      // now - windowStart = 1000 == windowMs -> the >= check evicts it.
+      lim.sweep(1000);
+      // Re-touch at the same instant: a fresh bucket (count 0) is created, so the
+      // key is no longer blocked, proving the boundary bucket was swept.
+      expect(lim.isBlocked('boundary', 1000)).toBe(false);
+    });
+
+    it('retains a fresh bucket still within the window', () => {
+      const lim = new FailedLoginLimiter(1, 1000);
+      lim.recordFailure('fresh', 0); // windowStart=0
+      // now - windowStart = 999 < 1000 -> the bucket survives the sweep.
+      lim.sweep(999);
+      // Still blocked because the bucket (and its count) was retained.
+      expect(lim.isBlocked('fresh', 999)).toBe(true);
+    });
+  });
 });
 
 describe('verifyBearerAccess (Bearer revocation/disabled checks)', () => {
@@ -769,3 +829,138 @@ describe('bindAccessJwtVerifier enforces JwtType.ACCESS (item 3)', () => {
     expect(res).toEqual({ sub: 'user-1', email: undefined });
   });
 });
+
+describe('decideBasicGate (pure SSO/MFA pre-token gate, refactor R1)', () => {
+  // The pure decision extracted out of McpService.enforceBasicLoginGate. It is
+  // tested WITHOUT ModuleRef and WITHOUT an on-disk EE MFA module: the SSO verdict
+  // and the MFA requirement result are passed in as plain values.
+
+  it('SSO enforced -> throws Unauthorized ("enforced SSO")', () => {
+    expect(() => decideBasicGate({ ssoEnforced: true })).toThrow(
+      UnauthorizedException,
+    );
+    expect(() => decideBasicGate({ ssoEnforced: true })).toThrow(/enforced SSO/);
+    // SSO takes precedence even if MFA flags are also set.
+    expect(() =>
+      decideBasicGate({ ssoEnforced: true, mfa: { userHasMfa: true } }),
+    ).toThrow(/enforced SSO/);
+  });
+
+  it('no SSO + no MFA module (mfa undefined) -> resolves (Basic allowed)', () => {
+    // A community/fork build with no EE MFA module passes mfa: undefined and the
+    // gate must allow the password login (same as the controller with no MFA).
+    expect(() => decideBasicGate({ ssoEnforced: false })).not.toThrow();
+    expect(() =>
+      decideBasicGate({ ssoEnforced: false, mfa: undefined }),
+    ).not.toThrow();
+  });
+
+  it('MFA present + userHasMfa -> rejects ("use a Bearer access token")', () => {
+    expect(() =>
+      decideBasicGate({ ssoEnforced: false, mfa: { userHasMfa: true } }),
+    ).toThrow(/use a Bearer access token/);
+    expect(() =>
+      decideBasicGate({ ssoEnforced: false, mfa: { userHasMfa: true } }),
+    ).toThrow(UnauthorizedException);
+  });
+
+  it('MFA present + requiresMfaSetup -> rejects', () => {
+    expect(() =>
+      decideBasicGate({ ssoEnforced: false, mfa: { requiresMfaSetup: true } }),
+    ).toThrow(/use a Bearer access token/);
+  });
+
+  it('MFA present but none required (both flags false) -> resolves', () => {
+    expect(() =>
+      decideBasicGate({
+        ssoEnforced: false,
+        mfa: { userHasMfa: false, requiresMfaSetup: false },
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe('mapAuthResultToResponse (handle status/body mapping, refactor R2)', () => {
+  // The pure response decision extracted out of McpService.handle. It maps the
+  // pre-hijack gauntlet (shared token, enablement, auth error) to either a fixed
+  // JSON error response or the hijack path — never leaking the password/header.
+
+  it('wrong X-MCP-Token -> 401 {error:"Unauthorized"} and NOT the hijack path', () => {
+    const d = mapAuthResultToResponse({ sharedTokenOk: false, enabled: true });
+    expect(d).toEqual({
+      kind: 'respond',
+      status: 401,
+      body: { error: 'Unauthorized' },
+    });
+  });
+
+  it('workspace MCP disabled -> 403', () => {
+    const d = mapAuthResultToResponse({ sharedTokenOk: true, enabled: false });
+    expect(d.kind).toBe('respond');
+    if (d.kind === 'respond') {
+      expect(d.status).toBe(403);
+      expect(d.body).toEqual({ error: 'MCP is disabled for this workspace' });
+    }
+  });
+
+  it('an UnauthorizedException -> 401 with err.message; no password/header leaked', () => {
+    // Construct an UnauthorizedException whose message is the SPECIFIC auth reason.
+    const err = new UnauthorizedException('Email or password does not match');
+    const d = mapAuthResultToResponse({
+      sharedTokenOk: true,
+      enabled: true,
+      error: err,
+    });
+    expect(d).toEqual({
+      kind: 'respond',
+      status: 401,
+      body: { error: 'Email or password does not match' },
+    });
+    // The surfaced body is ONLY the exception message — never the raw secret.
+    if (d.kind === 'respond') {
+      const serialized = JSON.stringify(d.body);
+      expect(serialized).not.toContain('password=');
+      expect(serialized).not.toContain('Authorization');
+      expect(serialized).not.toContain('Basic ');
+      expect(serialized).not.toContain('Bearer ');
+    }
+  });
+
+  it('a non-Unauthorized error -> 500 generic (no error detail surfaced)', () => {
+    const err = new Error('db blew up: connection string secret');
+    const d = mapAuthResultToResponse({
+      sharedTokenOk: true,
+      enabled: true,
+      error: err,
+    });
+    expect(d).toEqual({
+      kind: 'respond',
+      status: 500,
+      body: { error: 'Internal server error' },
+    });
+    // The generic body must NOT echo the underlying error message.
+    if (d.kind === 'respond') {
+      expect(d.body.error).not.toContain('secret');
+    }
+  });
+
+  it('happy path (auth resolved, no error) -> hijack', () => {
+    const d = mapAuthResultToResponse({ sharedTokenOk: true, enabled: true });
+    expect(d).toEqual({ kind: 'hijack' });
+  });
+
+  it('shared-token failure takes precedence over disabled/error', () => {
+    // Even with a disabled workspace and an error, a bad shared token is the
+    // first gate, so the response is the uniform 401 Unauthorized.
+    const d = mapAuthResultToResponse({
+      sharedTokenOk: false,
+      enabled: false,
+      error: new UnauthorizedException('should not surface'),
+    });
+    expect(d).toEqual({
+      kind: 'respond',
+      status: 401,
+      body: { error: 'Unauthorized' },
+    });
+  });
+});
diff --git a/apps/server/src/integrations/mcp/mcp.service.ts b/apps/server/src/integrations/mcp/mcp.service.ts
index 7ac16fb6..0af88c65 100644
--- a/apps/server/src/integrations/mcp/mcp.service.ts
+++ b/apps/server/src/integrations/mcp/mcp.service.ts
@@ -25,6 +25,8 @@ import {
   sharedTokenMatches,
   clientIp,
   bindAccessJwtVerifier,
+  decideBasicGate,
+  mapAuthResultToResponse,
   DocmostMcpConfig,
   ResolvedMcpAuth,
 } from './mcp-auth.helpers';
@@ -231,49 +233,54 @@ export class McpService implements OnModuleDestroy {
     workspace: Workspace,
     creds: { email: string; password: string },
   ): Promise<void> {
-    // 1) SSO enforcement. validateSsoEnforcement throws BadRequestException; we
-    // re-surface it as Unauthorized so the /mcp 401 path is consistent and a
-    // token is never issued.
+    // 1) SSO enforcement. validateSsoEnforcement throws when the workspace
+    // enforces SSO; we only need the boolean verdict for the pure decision.
+    let ssoEnforced = false;
     try {
       validateSsoEnforcement(workspace);
     } catch {
-      throw new UnauthorizedException(
-        'This workspace has enforced SSO login. Use SSO; MCP HTTP Basic is not allowed.',
-      );
+      ssoEnforced = true;
     }
 
     // 2) MFA gate — lazy-require the EE module exactly like AuthController.login.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let MfaModule: any;
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      MfaModule = require('./../../ee/mfa/services/mfa.service');
-    } catch {
-      // No EE MFA module bundled in this build: same as the controller -> no
-      // MFA gate. (A community/fork build has no MFA, so Basic is allowed.)
-      return;
+    // On a fork WITHOUT the EE module bundled, mfaResult stays undefined and the
+    // pure gate behaves exactly like the controller (no MFA module -> no MFA
+    // gate). We only LOAD the module + read the requirement flags here; the
+    // accept/reject decision lives in the framework-free decideBasicGate so the
+    // SSO/MFA logic is unit-testable without ModuleRef or the on-disk EE module.
+    let mfaResult: { userHasMfa?: boolean; requiresMfaSetup?: boolean } | undefined;
+    // Only consult the MFA module when SSO has not already disqualified the
+    // request (SSO short-circuits, and skipping the load avoids a needless
+    // require on the SSO-reject path).
+    if (!ssoEnforced) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let MfaModule: any;
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        MfaModule = require('./../../ee/mfa/services/mfa.service');
+      } catch {
+        // No EE MFA module bundled in this build: same as the controller -> no
+        // MFA gate. (A community/fork build has no MFA, so Basic is allowed.)
+        MfaModule = undefined;
+      }
+
+      if (MfaModule) {
+        const mfaService = this.moduleRef.get(MfaModule.MfaService, {
+          strict: false,
+        });
+        // Same requirement check the controller uses. We pass NO FastifyReply
+        // (the controller passes `res` only to set a cookie on the no-MFA happy
+        // path, which we never take here): we only read the requirement flags.
+        mfaResult = await mfaService.checkMfaRequirements(
+          creds,
+          workspace,
+          undefined,
+        );
+      }
     }
 
-    const mfaService = this.moduleRef.get(MfaModule.MfaService, {
-      strict: false,
-    });
-    // Use the same requirement check the controller uses. We pass NO FastifyReply
-    // (the controller passes `res` only to set a cookie on the no-MFA happy path,
-    // which we never take here): we only read the requirement flags. Be tolerant
-    // of either a (loginInput, workspace) or (loginInput, workspace, res) shape.
-    const mfaResult = await mfaService.checkMfaRequirements(
-      creds,
-      workspace,
-      undefined,
-    );
-
-    if (mfaResult && (mfaResult.userHasMfa || mfaResult.requiresMfaSetup)) {
-      throw new UnauthorizedException(
-        'This account requires multi-factor authentication. MCP HTTP Basic ' +
-          'cannot complete MFA — log in normally and use a Bearer access token ' +
-          'instead.',
-      );
-    }
+    // Pure accept/reject decision (throws UnauthorizedException on rejection).
+    decideBasicGate({ ssoEnforced, mfa: mfaResult });
   }
 
   // Lazily create the HTTP handler exactly once. The import is indirected so
@@ -333,52 +340,61 @@ export class McpService implements OnModuleDestroy {
     // matching `X-MCP-Token` header. It now lives in its OWN header so it never
     // collides with `Authorization`, which carries the per-user credentials.
     const sharedToken = process.env.MCP_TOKEN;
-    if (sharedToken) {
-      const provided = req.headers['x-mcp-token'];
-      if (!sharedTokenMatches(sharedToken, provided)) {
-        res.status(401).send({ error: 'Unauthorized' });
-        return;
-      }
-    }
+    const sharedTokenOk = sharedToken
+      ? sharedTokenMatches(sharedToken, req.headers['x-mcp-token'])
+      : true;
 
-    if (!(await this.isEnabled())) {
-      res.status(403).send({ error: 'MCP is disabled for this workspace' });
-      return;
-    }
+    // Short-circuit checks (shared token, enablement) that do not need the auth
+    // resolution. Compute them up front so the response mapping is a single pure
+    // decision (mapAuthResultToResponse) that cannot leak the password/header.
+    const enabled = sharedTokenOk ? await this.isEnabled() : false;
 
     // Resolve + validate the per-session identity BEFORE hijacking the response
     // so bad credentials surface as a clean 401 JSON (never a torn response and
     // never a generic "MCP error"). The resolved config/identity is stashed on
     // the raw request for the package's resolver + identify hook to read back.
-    let resolved: ResolvedMcpAuth;
-    try {
-      resolved = await this.resolveSessionConfig(req);
-    } catch (err) {
-      if (err instanceof UnauthorizedException) {
-        // Warn once if the only thing missing is the service account, to keep
-        // the original operator hint.
-        if (
-          !this.credsConfigured() &&
-          !req.headers['authorization'] &&
-          !this.warnedMissingCreds
-        ) {
-          this.warnedMissingCreds = true;
-          this.logger.warn(
-            'MCP is enabled but received a request with no credentials and no ' +
-              'MCP_DOCMOST_EMAIL/MCP_DOCMOST_PASSWORD service account configured.',
-          );
+    let resolved: ResolvedMcpAuth | undefined;
+    let authError: unknown;
+    if (sharedTokenOk && enabled) {
+      try {
+        resolved = await this.resolveSessionConfig(req);
+      } catch (err) {
+        authError = err;
+        if (err instanceof UnauthorizedException) {
+          // Warn once if the only thing missing is the service account, to keep
+          // the original operator hint.
+          if (
+            !this.credsConfigured() &&
+            !req.headers['authorization'] &&
+            !this.warnedMissingCreds
+          ) {
+            this.warnedMissingCreds = true;
+            this.logger.warn(
+              'MCP is enabled but received a request with no credentials and no ' +
+                'MCP_DOCMOST_EMAIL/MCP_DOCMOST_PASSWORD service account configured.',
+            );
+          }
+        } else {
+          this.logger.error('MCP auth resolution failed', err as Error);
         }
-        res.status(401).send({ error: err.message });
-        return;
       }
-      this.logger.error('MCP auth resolution failed', err as Error);
-      res.status(500).send({ error: 'Internal server error' });
+    }
+
+    // Pure status/body mapping for the whole pre-hijack gauntlet.
+    const decision = mapAuthResultToResponse({
+      sharedTokenOk,
+      enabled,
+      error: authError,
+    });
+    if (decision.kind === 'respond') {
+      res.status(decision.status).send(decision.body);
       return;
     }
 
     // Stash the resolved auth on the raw request so the package's resolver +
     // identify hook (wired in getHandler) read it back instead of re-parsing.
-    (req.raw as unknown as Record<symbol, unknown>)[MCP_RESOLVED] = resolved;
+    (req.raw as unknown as Record<symbol, unknown>)[MCP_RESOLVED] =
+      resolved as ResolvedMcpAuth;
 
     // Hand the raw Node req/res to the MCP transport. hijack() tells Fastify
     // to stop managing this response so the transport can write to it directly.
diff --git a/apps/server/src/ws/listeners/page-ws.listener.spec.ts b/apps/server/src/ws/listeners/page-ws.listener.spec.ts
index 734e8228..3282d318 100644
--- a/apps/server/src/ws/listeners/page-ws.listener.spec.ts
+++ b/apps/server/src/ws/listeners/page-ws.listener.spec.ts
@@ -3,6 +3,7 @@ import { PageWsListener } from './page-ws.listener';
 import { WsTreeService } from '../ws-tree.service';
 import {
   PageEvent,
+  PageMovedEvent,
   TreeNodeSnapshot,
 } from '../../database/listeners/page.listener';
 
@@ -93,3 +94,139 @@ describe('PageWsListener.onPageCreated', () => {
     expect(wsTree.broadcastRefetchRoot).not.toHaveBeenCalled();
   });
 });
+
+describe('PageWsListener delete/move/restore handlers', () => {
+  let listener: PageWsListener;
+  let wsTree: {
+    broadcastPageCreated: jest.Mock;
+    broadcastPageDeleted: jest.Mock;
+    broadcastPageMoved: jest.Mock;
+    broadcastRefetchRoot: jest.Mock;
+  };
+  let warnSpy: jest.SpyInstance;
+
+  const secondSnapshot: TreeNodeSnapshot = {
+    id: 'page-2',
+    slugId: 'slug-2',
+    title: 'World',
+    icon: '📁',
+    position: 'a2',
+    spaceId: 'space-1',
+    parentPageId: null,
+  };
+
+  beforeEach(async () => {
+    wsTree = {
+      broadcastPageCreated: jest.fn().mockResolvedValue(undefined),
+      broadcastPageDeleted: jest.fn().mockResolvedValue(undefined),
+      broadcastPageMoved: jest.fn().mockResolvedValue(undefined),
+      broadcastRefetchRoot: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        PageWsListener,
+        { provide: WsTreeService, useValue: wsTree },
+      ],
+    }).compile();
+
+    listener = module.get<PageWsListener>(PageWsListener);
+    // The PAGE_RESTORED-without-spaceId branch logs a warning; silence + assert.
+    warnSpy = jest
+      .spyOn(listener['logger'], 'warn')
+      .mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  // --- onPageDeleted (PAGE_SOFT_DELETED / PAGE_DELETED) ---
+
+  it('onPageDeleted with N `pages`: one broadcastPageDeleted per page', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1', 'page-2'],
+      workspaceId: 'ws-1',
+      pages: [snapshot, secondSnapshot],
+    };
+
+    await listener.onPageDeleted(event);
+
+    expect(wsTree.broadcastPageDeleted).toHaveBeenCalledTimes(2);
+    expect(wsTree.broadcastPageDeleted).toHaveBeenNthCalledWith(1, snapshot);
+    expect(wsTree.broadcastPageDeleted).toHaveBeenNthCalledWith(
+      2,
+      secondSnapshot,
+    );
+  });
+
+  it('onPageDeleted with an EMPTY `pages` array: no broadcast', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      pages: [],
+    };
+
+    await listener.onPageDeleted(event);
+
+    expect(wsTree.broadcastPageDeleted).not.toHaveBeenCalled();
+  });
+
+  it('onPageDeleted with UNDEFINED `pages`: no broadcast (no crash)', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+    };
+
+    await listener.onPageDeleted(event);
+
+    expect(wsTree.broadcastPageDeleted).not.toHaveBeenCalled();
+  });
+
+  // --- onPageMoved (PAGE_MOVED) ---
+
+  it('onPageMoved: forwards the whole event to a single broadcastPageMoved', async () => {
+    const event: PageMovedEvent = {
+      workspaceId: 'ws-1',
+      oldParentId: 'old-parent',
+      hasChildren: false,
+      node: { ...snapshot, parentPageId: 'new-parent', position: 'a5' },
+    };
+
+    await listener.onPageMoved(event);
+
+    expect(wsTree.broadcastPageMoved).toHaveBeenCalledTimes(1);
+    expect(wsTree.broadcastPageMoved).toHaveBeenCalledWith(event);
+  });
+
+  // --- onPageRestored (PAGE_RESTORED) ---
+
+  it('onPageRestored WITHOUT spaceId: warns and does NOT refetch', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+    };
+
+    await listener.onPageRestored(event);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('PAGE_RESTORED'),
+    );
+    expect(wsTree.broadcastRefetchRoot).not.toHaveBeenCalled();
+  });
+
+  it('onPageRestored WITH spaceId: one broadcastRefetchRoot scoped to the space', async () => {
+    const event: PageEvent = {
+      pageIds: ['page-1'],
+      workspaceId: 'ws-1',
+      spaceId: 'space-9',
+    };
+
+    await listener.onPageRestored(event);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    expect(wsTree.broadcastRefetchRoot).toHaveBeenCalledTimes(1);
+    expect(wsTree.broadcastRefetchRoot).toHaveBeenCalledWith('space-9');
+  });
+});
diff --git a/apps/server/src/ws/ws-service.spec.ts b/apps/server/src/ws/ws-service.spec.ts
new file mode 100644
index 00000000..c87d1493
--- /dev/null
+++ b/apps/server/src/ws/ws-service.spec.ts
@@ -0,0 +1,259 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { WsService } from './ws.service';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import {
+  getSpaceRoomName,
+  WS_SPACE_RESTRICTION_CACHE_PREFIX,
+  WS_CACHE_TTL_MS,
+} from './ws.utils';
+
+/**
+ * WsService server-side unit tests (M7 item 2):
+ *  - spaceHasRestrictions cache lifecycle (miss -> read+set with TTL; hit ->
+ *    no re-read; documents the stale-false window).
+ *  - broadcastToAuthorizedUsers fan-out (authorized-only delivery, multi-socket
+ *    fan-out per user, sockets with no userId skipped).
+ *
+ * Both private methods are exercised through their public entry points:
+ * spaceHasRestrictions via emitTreeEvent, broadcastToAuthorizedUsers via
+ * emitToAuthorizedUsers. WsService is constructed with mocked cache + repo and a
+ * mocked socket.io server, so no live infra is needed.
+ */
+
+describe('WsService.spaceHasRestrictions (cache lifecycle, via emitTreeEvent)', () => {
+  let service: WsService;
+  let pagePermissionRepo: {
+    hasRestrictedPagesInSpace: jest.Mock;
+    hasRestrictedAncestor: jest.Mock;
+    getUserIdsWithPageAccess: jest.Mock;
+  };
+  let cache: { get: jest.Mock; set: jest.Mock; del: jest.Mock };
+  let roomEmit: jest.Mock;
+
+  beforeEach(async () => {
+    pagePermissionRepo = {
+      hasRestrictedPagesInSpace: jest.fn(),
+      hasRestrictedAncestor: jest.fn(),
+      getUserIdsWithPageAccess: jest.fn(),
+    };
+    cache = {
+      get: jest.fn().mockResolvedValue(null),
+      set: jest.fn().mockResolvedValue(undefined),
+      del: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        WsService,
+        { provide: PagePermissionRepo, useValue: pagePermissionRepo },
+        { provide: CACHE_MANAGER, useValue: cache },
+      ],
+    }).compile();
+
+    service = module.get<WsService>(WsService);
+
+    roomEmit = jest.fn();
+    const server = {
+      to: jest.fn().mockReturnValue({ emit: roomEmit }),
+      in: jest.fn().mockReturnValue({ fetchSockets: jest.fn() }),
+    };
+    service.setServer(server as never);
+  });
+
+  const cacheKey = (spaceId: string): string =>
+    `${WS_SPACE_RESTRICTION_CACHE_PREFIX}${spaceId}`;
+
+  it('first call MISSES the cache -> reads the repo and sets it with WS_CACHE_TTL_MS', async () => {
+    cache.get.mockResolvedValue(null); // miss
+    pagePermissionRepo.hasRestrictedPagesInSpace.mockResolvedValue(true);
+    pagePermissionRepo.hasRestrictedAncestor.mockResolvedValue(false);
+
+    await service.emitTreeEvent('space-1', 'page-1', { op: 'x' });
+
+    expect(cache.get).toHaveBeenCalledWith(cacheKey('space-1'));
+    expect(pagePermissionRepo.hasRestrictedPagesInSpace).toHaveBeenCalledTimes(1);
+    expect(pagePermissionRepo.hasRestrictedPagesInSpace).toHaveBeenCalledWith(
+      'space-1',
+    );
+    // The freshly-read verdict is cached with the 30s TTL.
+    expect(cache.set).toHaveBeenCalledWith(
+      cacheKey('space-1'),
+      true,
+      WS_CACHE_TTL_MS,
+    );
+  });
+
+  it('second call HITS the cache -> the repo is NOT re-read', async () => {
+    // Cache hit returns false (no restrictions) -> open-space fast path.
+    cache.get.mockResolvedValue(false);
+
+    await service.emitTreeEvent('space-1', 'page-1', { op: 'x' });
+
+    expect(cache.get).toHaveBeenCalledWith(cacheKey('space-1'));
+    // The whole point of the cache: no repo read on a hit.
+    expect(pagePermissionRepo.hasRestrictedPagesInSpace).not.toHaveBeenCalled();
+    expect(cache.set).not.toHaveBeenCalled();
+    // false verdict -> broadcast to the whole room (open-space fast path).
+    expect(roomEmit).toHaveBeenCalledWith('message', { op: 'x' });
+  });
+
+  it('a cached `false` is returned even when restrictions now exist (the stale window)', async () => {
+    // The cache says "no restrictions" (false) but the repo, if asked, would now
+    // say true. spaceHasRestrictions trusts the cached false and never re-reads —
+    // this documents the up-to-TTL stale window the production comment warns about
+    // (a payload can fan out room-wide until the cache is invalidated/expires).
+    cache.get.mockResolvedValue(false);
+    pagePermissionRepo.hasRestrictedPagesInSpace.mockResolvedValue(true);
+
+    await service.emitTreeEvent('space-1', 'page-1', { op: 'stale' });
+
+    expect(pagePermissionRepo.hasRestrictedPagesInSpace).not.toHaveBeenCalled();
+    // Treated as open -> the event is broadcast to the WHOLE room.
+    expect(roomEmit).toHaveBeenCalledWith('message', { op: 'stale' });
+  });
+
+  it('caches a `false` verdict too (so the next emit hits, not re-reads)', async () => {
+    cache.get.mockResolvedValueOnce(null); // first call: miss
+    pagePermissionRepo.hasRestrictedPagesInSpace.mockResolvedValue(false);
+
+    await service.emitTreeEvent('space-2', 'page-9', { op: 'y' });
+
+    expect(cache.set).toHaveBeenCalledWith(
+      cacheKey('space-2'),
+      false,
+      WS_CACHE_TTL_MS,
+    );
+  });
+});
+
+describe('WsService.broadcastToAuthorizedUsers fan-out (via emitToAuthorizedUsers)', () => {
+  let service: WsService;
+  let pagePermissionRepo: {
+    hasRestrictedPagesInSpace: jest.Mock;
+    hasRestrictedAncestor: jest.Mock;
+    getUserIdsWithPageAccess: jest.Mock;
+  };
+  let cache: { get: jest.Mock; set: jest.Mock; del: jest.Mock };
+  let fetchSockets: jest.Mock;
+  let serverIn: jest.Mock;
+
+  beforeEach(async () => {
+    pagePermissionRepo = {
+      hasRestrictedPagesInSpace: jest.fn(),
+      hasRestrictedAncestor: jest.fn(),
+      getUserIdsWithPageAccess: jest.fn(),
+    };
+    cache = {
+      get: jest.fn().mockResolvedValue(null),
+      set: jest.fn().mockResolvedValue(undefined),
+      del: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        WsService,
+        { provide: PagePermissionRepo, useValue: pagePermissionRepo },
+        { provide: CACHE_MANAGER, useValue: cache },
+      ],
+    }).compile();
+
+    service = module.get<WsService>(WsService);
+
+    fetchSockets = jest.fn();
+    serverIn = jest.fn().mockReturnValue({ fetchSockets });
+    const server = {
+      to: jest.fn().mockReturnValue({ emit: jest.fn() }),
+      in: serverIn,
+    };
+    service.setServer(server as never);
+  });
+
+  it('only sockets whose userId is in getUserIdsWithPageAccess receive the event', async () => {
+    pagePermissionRepo.getUserIdsWithPageAccess.mockResolvedValue(['user-ok']);
+
+    const okEmit = jest.fn();
+    const noEmit = jest.fn();
+    fetchSockets.mockResolvedValue([
+      { id: 's1', data: { userId: 'user-ok' }, emit: okEmit },
+      { id: 's2', data: { userId: 'user-no' }, emit: noEmit },
+    ]);
+
+    const data = { operation: 'moveTreeNode' };
+    await service.emitToAuthorizedUsers('space-1', 'page-1', data);
+
+    // The authorized set is resolved from the candidate userIds present on the
+    // sockets (deduped), then only those users' sockets get the event.
+    expect(pagePermissionRepo.getUserIdsWithPageAccess).toHaveBeenCalledWith(
+      'page-1',
+      expect.arrayContaining(['user-ok', 'user-no']),
+    );
+    expect(okEmit).toHaveBeenCalledWith('message', data);
+    expect(noEmit).not.toHaveBeenCalled();
+  });
+
+  it('a user with TWO sockets receives the event on BOTH (userSocketMap fan-out)', async () => {
+    pagePermissionRepo.getUserIdsWithPageAccess.mockResolvedValue(['user-ok']);
+
+    const tab1 = jest.fn();
+    const tab2 = jest.fn();
+    fetchSockets.mockResolvedValue([
+      { id: 's1', data: { userId: 'user-ok' }, emit: tab1 },
+      { id: 's2', data: { userId: 'user-ok' }, emit: tab2 },
+    ]);
+
+    const data = { operation: 'moveTreeNode' };
+    await service.emitToAuthorizedUsers('space-1', 'page-1', data);
+
+    // Both of the authorized user's sockets (e.g. two browser tabs) receive it.
+    expect(tab1).toHaveBeenCalledWith('message', data);
+    expect(tab2).toHaveBeenCalledWith('message', data);
+    // The candidate set is deduped to a single userId even with two sockets.
+    expect(pagePermissionRepo.getUserIdsWithPageAccess).toHaveBeenCalledWith(
+      'page-1',
+      ['user-ok'],
+    );
+  });
+
+  it('a socket with NO userId is skipped (not a candidate, never emitted to)', async () => {
+    pagePermissionRepo.getUserIdsWithPageAccess.mockResolvedValue(['user-ok']);
+
+    const okEmit = jest.fn();
+    const anonEmit = jest.fn();
+    fetchSockets.mockResolvedValue([
+      { id: 's1', data: { userId: 'user-ok' }, emit: okEmit },
+      // Unauthenticated socket: no userId -> excluded from the candidate map.
+      { id: 's2', data: {}, emit: anonEmit },
+    ]);
+
+    const data = { operation: 'moveTreeNode' };
+    await service.emitToAuthorizedUsers('space-1', 'page-1', data);
+
+    expect(okEmit).toHaveBeenCalledWith('message', data);
+    expect(anonEmit).not.toHaveBeenCalled();
+    // The no-userId socket is not even offered as a candidate to the repo.
+    expect(pagePermissionRepo.getUserIdsWithPageAccess).toHaveBeenCalledWith(
+      'page-1',
+      ['user-ok'],
+    );
+  });
+
+  it('no sockets in the room -> no repo lookup, no emit', async () => {
+    fetchSockets.mockResolvedValue([]);
+
+    await service.emitToAuthorizedUsers('space-1', 'page-1', { op: 'x' });
+
+    expect(pagePermissionRepo.getUserIdsWithPageAccess).not.toHaveBeenCalled();
+  });
+
+  it('routes through the space room name', async () => {
+    pagePermissionRepo.getUserIdsWithPageAccess.mockResolvedValue([]);
+    fetchSockets.mockResolvedValue([
+      { id: 's1', data: { userId: 'u' }, emit: jest.fn() },
+    ]);
+
+    await service.emitToAuthorizedUsers('space-7', 'page-1', { op: 'x' });
+
+    expect(serverIn).toHaveBeenCalledWith(getSpaceRoomName('space-7'));
+  });
+});
diff --git a/apps/server/src/ws/ws-tree.service.spec.ts b/apps/server/src/ws/ws-tree.service.spec.ts
index 0c511223..973e6b00 100644
--- a/apps/server/src/ws/ws-tree.service.spec.ts
+++ b/apps/server/src/ws/ws-tree.service.spec.ts
@@ -329,3 +329,109 @@ describe('WsService.emitTreeEvent', () => {
     expect(anonEmit).toHaveBeenCalledWith('message', data);
   });
 });
+
+describe('move-into-restricted disjointness contract (WsTreeService + real WsService)', () => {
+  // CONTRACT: a move under a restricted ancestor PARTITIONS the room. The
+  // authorized set (gets the moveTreeNode via emitToAuthorizedUsers) and its
+  // complement (gets the deleteTreeNode via emitDeleteToUnauthorized) are
+  // disjoint and together cover every socket — and an anonymous (no-userId)
+  // socket lands in the delete set. We wire a REAL WsService (only its repo,
+  // cache and socket server mocked) so both broadcasts run against the SAME fixed
+  // socket set, the way they do in production.
+  let treeService: WsTreeService;
+  let pagePermissionRepo: {
+    hasRestrictedPagesInSpace: jest.Mock;
+    hasRestrictedAncestor: jest.Mock;
+    getUserIdsWithPageAccess: jest.Mock;
+  };
+
+  // Fixed room: two authorized users (one with two sockets), one unauthorized
+  // user, one anonymous socket.
+  const moveSeen: string[] = [];
+  const deleteSeen: string[] = [];
+
+  const mkSocket = (id: string, userId: string | undefined) => ({
+    id,
+    data: userId ? { userId } : {},
+    emit: jest.fn((_event: string, payload: { operation: string }) => {
+      if (payload.operation === 'moveTreeNode') moveSeen.push(id);
+      if (payload.operation === 'deleteTreeNode') deleteSeen.push(id);
+    }),
+  });
+
+  const sockets = [
+    mkSocket('s-ok-1', 'user-ok'), // authorized, tab 1
+    mkSocket('s-ok-2', 'user-ok'), // authorized, tab 2 (fan-out)
+    mkSocket('s-no', 'user-no'), // unauthorized
+    mkSocket('s-anon', undefined), // anonymous (no userId)
+  ];
+
+  beforeEach(async () => {
+    moveSeen.length = 0;
+    deleteSeen.length = 0;
+
+    pagePermissionRepo = {
+      hasRestrictedPagesInSpace: jest.fn().mockResolvedValue(true),
+      // The move destination IS under a restricted ancestor.
+      hasRestrictedAncestor: jest.fn().mockResolvedValue(true),
+      // Only user-ok is authorized to see the page.
+      getUserIdsWithPageAccess: jest.fn().mockResolvedValue(['user-ok']),
+    };
+    const cache = {
+      get: jest.fn().mockResolvedValue(null),
+      set: jest.fn().mockResolvedValue(undefined),
+      del: jest.fn().mockResolvedValue(undefined),
+    };
+
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        WsTreeService,
+        WsService,
+        { provide: PagePermissionRepo, useValue: pagePermissionRepo },
+        { provide: CACHE_MANAGER, useValue: cache },
+      ],
+    }).compile();
+
+    const wsService = module.get<WsService>(WsService);
+    const server = {
+      to: jest.fn().mockReturnValue({ emit: jest.fn() }),
+      in: jest.fn().mockReturnValue({
+        fetchSockets: jest.fn().mockResolvedValue(sockets),
+      }),
+    };
+    wsService.setServer(server as never);
+
+    treeService = module.get<WsTreeService>(WsTreeService);
+  });
+
+  it('authorized set (move) and complement (delete) partition the room; anon is in delete', async () => {
+    const event: PageMovedEvent = {
+      workspaceId: 'ws-1',
+      oldParentId: 'old-parent',
+      hasChildren: false,
+      node: { ...snapshot, parentPageId: 'restricted-parent', position: 'a5' },
+    };
+
+    await treeService.broadcastPageMoved(event);
+
+    const moveSet = new Set(moveSeen);
+    const deleteSet = new Set(deleteSeen);
+
+    // Authorized user's BOTH sockets got the move; nobody else did.
+    expect(moveSet).toEqual(new Set(['s-ok-1', 's-ok-2']));
+    // Everyone else (unauthorized + anonymous) got the delete.
+    expect(deleteSet).toEqual(new Set(['s-no', 's-anon']));
+
+    // DISJOINT: no socket received both a move and a delete.
+    const intersection = [...moveSet].filter((id) => deleteSet.has(id));
+    expect(intersection).toEqual([]);
+
+    // PARTITION: the two sets together cover every socket in the room exactly.
+    const union = new Set([...moveSet, ...deleteSet]);
+    expect(union).toEqual(new Set(sockets.map((s) => s.id)));
+
+    // The anonymous socket specifically lands in the DELETE set, never the move.
+    expect(deleteSet.has('s-anon')).toBe(true);
+    expect(moveSet.has('s-anon')).toBe(false);
+  });
+});
diff --git a/packages/editor-ext/src/lib/html-embed/html-embed-codec.spec.ts b/packages/editor-ext/src/lib/html-embed/html-embed-codec.spec.ts
new file mode 100644
index 00000000..fbee45d2
--- /dev/null
+++ b/packages/editor-ext/src/lib/html-embed/html-embed-codec.spec.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  encodeHtmlEmbedSource,
+  decodeHtmlEmbedSource,
+} from "./html-embed";
+
+// Unit coverage for the base64 codec used by the htmlEmbed node's
+// data-source attribute (html-embed.ts). The codec has two branches:
+//   - the BROWSER branch: btoa(encodeURIComponent(s)) / decodeURIComponent(atob(s));
+//   - the NODE fallback: Buffer.from(..).toString("base64") / Buffer.from(s,"base64").
+// Server-side schema parsing (htmlToJson with no global btoa/atob) hits the
+// fallback, so both branches must round-trip identically; otherwise an embed
+// encoded in the browser would decode wrong on the server (or vice versa).
+//
+// We force the fallback by temporarily DELETING globalThis.btoa/atob (jsdom
+// provides them in this env), restoring them after each test so the suite stays
+// hermetic.
+
+const realBtoa = globalThis.btoa;
+const realAtob = globalThis.atob;
+
+function deleteBase64Globals(): void {
+  // @ts-expect-error — intentionally removing the globals to exercise the
+  // `typeof btoa !== "function"` Node fallback branch in the codec.
+  delete globalThis.btoa;
+  // @ts-expect-error — see above.
+  delete globalThis.atob;
+}
+
+afterEach(() => {
+  // Always restore so one test's stubbing never leaks into another.
+  globalThis.btoa = realBtoa;
+  globalThis.atob = realAtob;
+});
+
+describe("html-embed codec — browser btoa/atob branch", () => {
+  it("round-trips ASCII source", () => {
+    const src = "<script>alert(1)</script>";
+    const enc = encodeHtmlEmbedSource(src);
+    expect(enc).not.toBe("");
+    // base64 of the encodeURIComponent form never contains a raw '<'.
+    expect(enc).not.toContain("<");
+    expect(decodeHtmlEmbedSource(enc)).toBe(src);
+  });
+
+  it("round-trips UTF-8 / non-Latin1 source (the reason for encodeURIComponent)", () => {
+    const src = '<p>héllo → 世界 𝕏</p>';
+    const enc = encodeHtmlEmbedSource(src);
+    expect(decodeHtmlEmbedSource(enc)).toBe(src);
+  });
+});
+
+describe("html-embed codec — Node Buffer fallback branch", () => {
+  it("encode uses the Buffer fallback when btoa is unavailable and still round-trips (UTF-8)", () => {
+    const src = '<div>héllo → 世界 𝕏</div>';
+
+    deleteBase64Globals();
+    // With the globals gone, encode must take the Buffer path...
+    const encFallback = encodeHtmlEmbedSource(src);
+    expect(encFallback).not.toBe("");
+    // ...and decode (also via Buffer) must recover the exact source.
+    expect(decodeHtmlEmbedSource(encFallback)).toBe(src);
+  });
+
+  it("the Buffer fallback produces the SAME bytes the browser branch does (cross-env parity)", () => {
+    const src = '<span>café — 日本語</span>';
+
+    // Browser branch (globals intact).
+    const encBrowser = encodeHtmlEmbedSource(src);
+
+    // Fallback branch.
+    deleteBase64Globals();
+    const encFallback = encodeHtmlEmbedSource(src);
+
+    // Identical base64 => an embed encoded in either environment decodes
+    // identically in the other (server <-> client losslessness).
+    expect(encFallback).toBe(encBrowser);
+
+    // And the fallback can decode what the browser produced.
+    expect(decodeHtmlEmbedSource(encBrowser)).toBe(src);
+  });
+
+  it("empty string -> '' on both encode and decode in the fallback (early return, branch never reached)", () => {
+    deleteBase64Globals();
+    expect(encodeHtmlEmbedSource("")).toBe("");
+    expect(decodeHtmlEmbedSource("")).toBe("");
+  });
+
+  it("decode of malformed base64 -> '' via the catch branch (fallback)", () => {
+    // In the Buffer fallback, Buffer.from(..,'base64') is lenient and never
+    // throws, so to hit the catch we need a payload whose DECODED bytes are an
+    // invalid percent-escape, which makes decodeURIComponent throw. base64 of a
+    // lone '%' decodes back to '%', and decodeURIComponent('%') is a URIError.
+    const badBase64 = Buffer.from("%", "utf-8").toString("base64"); // "JQ=="
+
+    deleteBase64Globals();
+    // Sanity: the raw decode really does throw, so we're exercising the catch.
+    expect(() =>
+      decodeURIComponent(Buffer.from(badBase64, "base64").toString("utf-8")),
+    ).toThrow();
+    // The codec swallows it and returns "" rather than propagating.
+    expect(decodeHtmlEmbedSource(badBase64)).toBe("");
+  });
+});
+
+describe("html-embed codec — decode of malformed input (browser branch)", () => {
+  it("returns '' for input atob rejects (catch branch)", () => {
+    // atob throws on characters outside the base64 alphabet; the codec catches
+    // it and returns "" instead of throwing.
+    expect(decodeHtmlEmbedSource("@@not-base64@@")).toBe("");
+  });
+
+  it("empty string short-circuits to '' (never calls atob)", () => {
+    expect(decodeHtmlEmbedSource("")).toBe("");
+  });
+});
diff --git a/packages/editor-ext/src/lib/markdown/html-embed-marked.spec.ts b/packages/editor-ext/src/lib/markdown/html-embed-marked.spec.ts
new file mode 100644
index 00000000..7904f063
--- /dev/null
+++ b/packages/editor-ext/src/lib/markdown/html-embed-marked.spec.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { htmlEmbedExtension } from "./utils/html-embed.marked";
+import { markdownToHtml } from "./index";
+import { encodeHtmlEmbedSource } from "../html-embed/html-embed";
+
+// CONTRACT tests for the marked block tokenizer that rebuilds an htmlEmbed node
+// from the `<!--html-embed:BASE64-->` marker (html-embed.marked.ts), plus the
+// observable round-trip through markdownToHtml.
+//
+// These pin the REAL tokenizer behaviour the import path depends on:
+//   - the tokenizer rule is anchored (^) and only accepts the base64 alphabet
+//     [A-Za-z0-9+/=], so a marker with non-base64 chars is NOT tokenized and
+//     survives as a literal HTML comment (not silently turned into something the
+//     server's strip no longer recognizes);
+//   - start() reports the correct index of the next marker so marked invokes the
+//     tokenizer at the right offset when a marker sits mid-document / after text;
+//   - a marker with surrounding text on the SAME line is split out into its own
+//     embed div while the surrounding text becomes ordinary paragraphs.
+//
+// The contract is asserted against the actual exported extension and pipeline —
+// no behaviour is invented; the expectations were read off the real tokenizer.
+
+const SAMPLE = "<b>x</b>";
+const ENC = encodeHtmlEmbedSource(SAMPLE);
+
+describe("htmlEmbed marked tokenizer — start()", () => {
+  it("returns the index of a marker that sits mid-document", () => {
+    const src = `hello world <!--html-embed:${ENC}-->`;
+    expect(htmlEmbedExtension.start(src)).toBe(src.indexOf("<!--html-embed:"));
+  });
+
+  it("returns 0 when the marker is at the very start", () => {
+    expect(htmlEmbedExtension.start(`<!--html-embed:${ENC}-->`)).toBe(0);
+  });
+
+  it("returns -1 when there is no marker", () => {
+    expect(htmlEmbedExtension.start("no marker here")).toBe(-1);
+  });
+});
+
+describe("htmlEmbed marked tokenizer — tokenizer()", () => {
+  it("tokenizes a marker at the start of the input, capturing the base64 payload", () => {
+    const token = htmlEmbedExtension.tokenizer(`<!--html-embed:${ENC}-->`);
+    expect(token).toBeTruthy();
+    expect(token!.type).toBe("htmlEmbed");
+    expect(token!.raw).toBe(`<!--html-embed:${ENC}-->`);
+    expect(token!.encoded).toBe(ENC);
+  });
+
+  it("tokenizes an EMPTY marker (the [A-Za-z0-9+/=]* class allows zero chars)", () => {
+    const token = htmlEmbedExtension.tokenizer("<!--html-embed:-->");
+    expect(token).toBeTruthy();
+    expect(token!.encoded).toBe("");
+    expect(token!.raw).toBe("<!--html-embed:-->");
+  });
+
+  it("does NOT tokenize when text precedes the marker (rule is anchored ^)", () => {
+    // marked relies on start() to advance to the marker; the tokenizer itself
+    // only matches at offset 0, so a non-anchored call returns undefined.
+    expect(
+      htmlEmbedExtension.tokenizer(`hello <!--html-embed:${ENC}-->`),
+    ).toBeUndefined();
+  });
+
+  it("does NOT tokenize a marker containing a non-base64 char ('$')", () => {
+    expect(
+      htmlEmbedExtension.tokenizer("<!--html-embed:ab$cd-->"),
+    ).toBeUndefined();
+  });
+
+  it("does NOT tokenize a marker containing a space", () => {
+    expect(
+      htmlEmbedExtension.tokenizer("<!--html-embed:ab cd-->"),
+    ).toBeUndefined();
+  });
+
+  it("renderer emits the embed div the node's parseHTML recognizes", () => {
+    const token = htmlEmbedExtension.tokenizer(`<!--html-embed:${ENC}-->`)!;
+    const html = htmlEmbedExtension.renderer(token as any);
+    expect(html).toBe(
+      `<div data-type="htmlEmbed" data-source="${ENC}"></div>`,
+    );
+  });
+});
+
+describe("htmlEmbed marked tokenizer — markdownToHtml round-trip", () => {
+  it("splits a marker out of surrounding same-line text into its own embed div", async () => {
+    const html = await markdownToHtml(`before <!--html-embed:${ENC}--> after`);
+    // The marker became the embed div...
+    expect(html).toContain(
+      `<div data-type="htmlEmbed" data-source="${ENC}"></div>`,
+    );
+    // ...and the surrounding text survived as ordinary paragraph content.
+    expect(html).toContain("before");
+    expect(html).toContain("after");
+  });
+
+  it("leaves a marker with non-base64 chars as a literal comment (NOT an embed div)", async () => {
+    const html = await markdownToHtml("<!--html-embed:ab$cd-->");
+    // It is NOT tokenized into an embed div the server would strip...
+    expect(html).not.toContain('data-type="htmlEmbed"');
+    // ...it passes through unchanged as a literal HTML comment.
+    expect(html).toContain("<!--html-embed:ab$cd-->");
+  });
+});
diff --git a/packages/editor-ext/src/lib/page-embed/page-embed.spec.ts b/packages/editor-ext/src/lib/page-embed/page-embed.spec.ts
new file mode 100644
index 00000000..95638090
--- /dev/null
+++ b/packages/editor-ext/src/lib/page-embed/page-embed.spec.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import { getSchema } from "@tiptap/core";
+import { generateHTML, generateJSON } from "@tiptap/html";
+import { Document } from "@tiptap/extension-document";
+import { Paragraph } from "@tiptap/extension-paragraph";
+import { Text } from "@tiptap/extension-text";
+import { PageEmbed } from "./page-embed";
+
+// CONTRACT tests for the PageEmbed node's parse/render round-trip
+// (page-embed.ts). The whole-page live embed stores ONLY a `sourcePageId`
+// reference; renderHTML must serialize it as `data-source-page-id` and parseHTML
+// must recover it. If this attribute mapping drifts, an embed saved to HTML loses
+// its target page on reload (the node view would have nothing to fetch).
+//
+// We assert at the editor-ext schema level using the same Tiptap utilities the
+// other editor-ext tests use (getSchema + @tiptap/html generateHTML/generateJSON
+// over a jsdom DOM), driving a real HTML -> node JSON -> HTML round-trip through
+// the node's actual addAttributes()/parseHTML()/renderHTML().
+
+// Minimal schema: a doc of blocks, plus the PageEmbed block node under test.
+const extensions = [Document, Paragraph, Text, PageEmbed];
+
+describe("PageEmbed schema", () => {
+  it("registers the pageEmbed node in the schema", () => {
+    const schema = getSchema(extensions);
+    expect(schema.nodes.pageEmbed).toBeTruthy();
+  });
+});
+
+describe("PageEmbed parse/render round-trip", () => {
+  it("recovers sourcePageId from data-source-page-id on parse (HTML -> JSON)", () => {
+    const html = `<div data-type="pageEmbed" data-source-page-id="pg-123"></div>`;
+    const json = generateJSON(html, extensions);
+
+    const node = json.content?.[0];
+    expect(node?.type).toBe("pageEmbed");
+    expect(node?.attrs?.sourcePageId).toBe("pg-123");
+  });
+
+  it("emits data-source-page-id on render (JSON -> HTML)", () => {
+    const json = {
+      type: "doc",
+      content: [{ type: "pageEmbed", attrs: { sourcePageId: "pg-456" } }],
+    };
+    const html = generateHTML(json, extensions);
+
+    expect(html).toContain('data-type="pageEmbed"');
+    expect(html).toContain('data-source-page-id="pg-456"');
+  });
+
+  it("survives a full HTML -> node -> HTML round-trip (attribute preserved)", () => {
+    const start = `<div data-type="pageEmbed" data-source-page-id="pg-789"></div>`;
+
+    // HTML -> node JSON -> HTML.
+    const json = generateJSON(start, extensions);
+    const html = generateHTML(json, extensions);
+
+    // The id survived the round-trip in the serialized HTML...
+    expect(html).toContain('data-source-page-id="pg-789"');
+
+    // ...and re-parsing the round-tripped HTML yields the same id (stable across
+    // an extra pass — no loss, no duplication).
+    const json2 = generateJSON(html, extensions);
+    expect(json2.content?.[0]?.attrs?.sourcePageId).toBe("pg-789");
+  });
+
+  it("omits data-source-page-id entirely when sourcePageId is null (renderHTML guard)", () => {
+    // The renderHTML maps a null/empty id to {} (no attribute), so an embed
+    // without a target page does not emit a stray empty attribute.
+    const json = {
+      type: "doc",
+      content: [{ type: "pageEmbed", attrs: { sourcePageId: null } }],
+    };
+    const html = generateHTML(json, extensions);
+
+    expect(html).toContain('data-type="pageEmbed"');
+    expect(html).not.toContain("data-source-page-id");
+  });
+
+  it("parses a div without the attribute to a null sourcePageId (default)", () => {
+    const html = `<div data-type="pageEmbed"></div>`;
+    const json = generateJSON(html, extensions);
+
+    expect(json.content?.[0]?.type).toBe("pageEmbed");
+    // getAttribute returns null when absent; parseHTML returns it verbatim.
+    expect(json.content?.[0]?.attrs?.sourcePageId).toBeNull();
+  });
+});
diff --git a/packages/mcp/test/unit/http-idle-eviction.test.mjs b/packages/mcp/test/unit/http-idle-eviction.test.mjs
new file mode 100644
index 00000000..6521f268
--- /dev/null
+++ b/packages/mcp/test/unit/http-idle-eviction.test.mjs
@@ -0,0 +1,273 @@
+// Unit tests for createMcpHttpHandler's idle-session eviction (http.ts).
+//
+// http.ts keeps one transport per MCP session alive between requests, keyed by
+// the mcp-session-id header, and runs a periodic sweep (setInterval, every 5
+// min) that closes any transport idle longer than the idle TTL
+// (MCP_SESSION_IDLE_MS, default 30 min) and drops its lastSeen + sessionIdentity
+// bookkeeping. Routing a request to an existing transport refreshes its
+// lastSeen.
+//
+// We drive this DETERMINISTICALLY rather than waiting wall-clock: the env knob
+// MCP_SESSION_IDLE_MS is read ONCE when the handler is created, so we set it
+// small; and node:test's mock.timers lets us mock both `setInterval` (the sweep)
+// and `Date` (the lastSeen comparison clock) so ticking advances the clock and
+// fires the sweep on demand.
+//
+// IMPORTANT mock.timers semantics: when a tick spans MULTIPLE timer fires (or
+// overshoots a fire), the callbacks all observe Date.now() == the FINAL ticked
+// time, not their individual scheduled times. So to make the sweep's
+// `now - lastSeen` comparison meaningful we tick EXACTLY to a sweep boundary
+// (a multiple of the sweep interval): then Date.now() inside the sweep equals
+// that boundary. The mocked clock starts at 0, so sweeps fire at SWEEP, 2*SWEEP,
+// ... We pin each session's lastSeen by establishing/touching it at a known
+// pre-boundary clock, then tick the remaining delta to land exactly on the
+// boundary.
+//
+// Sessions are established over a real loopback http server (so the SDK's
+// StreamableHTTPServerTransport gets genuine Node req/res and a real
+// mcp-session-id), exactly like http-resolver.test.mjs, and the server is closed
+// in a finally.
+//
+// Eviction is asserted via its OBSERVABLE effect: once a session is evicted its
+// transport is gone from the handler's internal map, so a subsequent non-init
+// request replaying that session id is treated as unknown (400 "no valid
+// session ID") — the same response an id that was never established would get.
+// An active (recently-seen) session is retained and its subsequent request is
+// NOT a 400.
+import { test, mock } from "node:test";
+import assert from "node:assert/strict";
+
+const INIT_BODY = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "initialize",
+  params: {
+    protocolVersion: "2025-03-26",
+    capabilities: {},
+    clientInfo: { name: "test", version: "0.0.0" },
+  },
+};
+
+const SWEEP_MS = 5 * 60 * 1000; // setInterval cadence in http.ts.
+
+// Spin a loopback http server bridging every request into the MCP handler with
+// its JSON body parsed, mirroring the embedding host. Returns { call, close }.
+async function startLoopback(handler) {
+  const http = await import("node:http");
+  const server = http.createServer((req, res) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => {
+      const body = raw ? JSON.parse(raw) : undefined;
+      handler.handleRequest(req, res, body).catch(() => {
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.end();
+        }
+      });
+    });
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  const { port } = server.address();
+
+  const call = (headers, body) =>
+    new Promise((resolve) => {
+      const r = http.request(
+        {
+          host: "127.0.0.1",
+          port,
+          method: "POST",
+          path: "/mcp",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            ...headers,
+          },
+        },
+        (resp) => {
+          let data = "";
+          resp.on("data", (c) => (data += c));
+          resp.on("end", () =>
+            resolve({
+              statusCode: resp.statusCode,
+              sessionId: resp.headers["mcp-session-id"],
+              body: data,
+            }),
+          );
+        },
+      );
+      r.end(JSON.stringify(body));
+    });
+
+  return { call, close: () => new Promise((r) => server.close(r)) };
+}
+
+// The sweep closes transports asynchronously (void transport.close()), whose
+// onclose then removes the entry from the internal map. Yield to the event loop
+// so those microtasks settle before we assert the observable effect.
+const settle = () => new Promise((r) => setImmediate(r));
+
+// Set the idle TTL env knob (read once at handler creation) and enable mocked
+// setInterval + Date BEFORE creating the handler, so the sweep interval and
+// every Date.now() (lastSeen at init, lastSeen on routing, and the sweep's
+// comparison) all run on the same mocked clock. Returns restore() to undo it.
+function withMockedTimers(idleMs) {
+  const prevIdle = process.env.MCP_SESSION_IDLE_MS;
+  process.env.MCP_SESSION_IDLE_MS = String(idleMs);
+  mock.timers.enable({ apis: ["setInterval", "Date"] });
+  return () => {
+    mock.timers.reset();
+    if (prevIdle === undefined) delete process.env.MCP_SESSION_IDLE_MS;
+    else process.env.MCP_SESSION_IDLE_MS = prevIdle;
+  };
+}
+
+test("idle session is evicted by the sweep; an active session is retained", async () => {
+  // A small TTL: idle longer than 1s triggers eviction. Both sessions start at
+  // clock 0; we keep one fresh (touch it just before the sweep) and leave the
+  // other idle, then fire ONE sweep exactly on its boundary.
+  const idleMs = 1000;
+  const restore = withMockedTimers(idleMs);
+
+  const { createMcpHttpHandler } = await import("../../build/http.js");
+  const handler = createMcpHttpHandler(() => ({
+    apiUrl: "http://127.0.0.1:3000/api",
+    getToken: async () => "t",
+  }));
+
+  const lb = await startLoopback(handler);
+  try {
+    // T0 (clock 0): establish both sessions; lastSeen(A) = lastSeen(B) = 0.
+    const a = await lb.call({}, INIT_BODY);
+    const b = await lb.call({}, INIT_BODY);
+    assert.ok(a.sessionId, "session A must get an mcp-session-id");
+    assert.ok(b.sessionId, "session B must get an mcp-session-id");
+    assert.notEqual(a.sessionId, b.sessionId, "distinct sessions");
+
+    // Advance to just before the first sweep boundary (SWEEP - 1ms): no sweep
+    // fires yet (boundary not reached). lastSeen(A) stays 0.
+    mock.timers.tick(SWEEP_MS - 1);
+    // Touch ONLY B here, refreshing lastSeen(B) to SWEEP-1 (active); A is left
+    // idle since clock 0.
+    const touchB = await lb.call(
+      { "mcp-session-id": b.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 5 },
+    );
+    assert.notEqual(touchB.statusCode, 400, "B alive right before the sweep");
+
+    // Land EXACTLY on the sweep boundary (clock = SWEEP). Inside the sweep
+    // Date.now() == SWEEP, so:
+    //   idle(A) = SWEEP - 0       = SWEEP   > TTL(1s)  -> A EVICTED
+    //   idle(B) = SWEEP - (SWEEP-1) = 1ms   < TTL(1s)  -> B RETAINED
+    mock.timers.tick(1);
+    await settle();
+
+    // OBSERVABLE EFFECT 1 — A evicted: replaying its session id on a non-init
+    // request is now treated as unknown (400, no valid session).
+    const aAfter = await lb.call(
+      { "mcp-session-id": a.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 10 },
+    );
+    assert.equal(aAfter.statusCode, 400, "evicted session id is unknown -> 400");
+    assert.match(aAfter.body, /no valid session ID/);
+
+    // OBSERVABLE EFFECT 2 — B retained: a subsequent request on its session id
+    // is routed to the live transport, NOT rejected as an unknown session.
+    const bAfter = await lb.call(
+      { "mcp-session-id": b.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 11 },
+    );
+    assert.notEqual(
+      bAfter.statusCode,
+      400,
+      "active session must survive the sweep (not 400)",
+    );
+  } finally {
+    await lb.close();
+    restore();
+  }
+});
+
+test("a session left idle past the TTL is dropped so its id becomes unknown", async () => {
+  // Simplest single-session eviction: establish a session, let it go idle past
+  // the TTL, fire the sweep on its boundary, and confirm its id is now unknown
+  // (400). Pins the core "lastSeen older than TTL -> closed and dropped" path.
+  const idleMs = 1000;
+  const restore = withMockedTimers(idleMs);
+
+  const { createMcpHttpHandler } = await import("../../build/http.js");
+  const handler = createMcpHttpHandler(() => ({
+    apiUrl: "http://127.0.0.1:3000/api",
+    getToken: async () => "t",
+  }));
+
+  const lb = await startLoopback(handler);
+  try {
+    const s = await lb.call({}, INIT_BODY);
+    assert.ok(s.sessionId, "session must get an mcp-session-id");
+
+    // Fire the first sweep exactly on its boundary: Date.now() == SWEEP, idle =
+    // SWEEP - 0 = SWEEP > TTL, so the untouched session is evicted.
+    mock.timers.tick(SWEEP_MS);
+    await settle();
+
+    const after = await lb.call(
+      { "mcp-session-id": s.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 30 },
+    );
+    assert.equal(after.statusCode, 400, "idle session id is unknown -> 400");
+    assert.match(after.body, /no valid session ID/);
+  } finally {
+    await lb.close();
+    restore();
+  }
+});
+
+test("activity refreshes lastSeen so a busy session is never evicted", async () => {
+  // A session kept busy (a request just before the sweep) refreshes its
+  // lastSeen, so even though it was created long ago the sweep must not evict
+  // it. Pins the "routing to an existing transport refreshes its idle
+  // timestamp" branch of http.ts.
+  const idleMs = 1000;
+  const restore = withMockedTimers(idleMs);
+
+  const { createMcpHttpHandler } = await import("../../build/http.js");
+  const handler = createMcpHttpHandler(() => ({
+    apiUrl: "http://127.0.0.1:3000/api",
+    getToken: async () => "t",
+  }));
+
+  const lb = await startLoopback(handler);
+  try {
+    const s = await lb.call({}, INIT_BODY);
+    assert.ok(s.sessionId, "session must get an mcp-session-id");
+
+    // Age to just before the sweep boundary, then touch the session so its
+    // lastSeen is refreshed to SWEEP-1 (well within the TTL of the imminent
+    // sweep).
+    mock.timers.tick(SWEEP_MS - 1);
+    const touch = await lb.call(
+      { "mcp-session-id": s.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 40 },
+    );
+    assert.notEqual(touch.statusCode, 400, "session still alive before sweep");
+
+    // Land exactly on the sweep boundary: idle = SWEEP - (SWEEP-1) = 1ms < TTL,
+    // so the busy session is retained.
+    mock.timers.tick(1);
+    await settle();
+
+    const after = await lb.call(
+      { "mcp-session-id": s.sessionId },
+      { jsonrpc: "2.0", method: "ping", id: 41 },
+    );
+    assert.notEqual(
+      after.statusCode,
+      400,
+      "a session touched just before the sweep must not be evicted",
+    );
+  } finally {
+    await lb.close();
+    restore();
+  }
+});

From f6e216cb87aa15fe88c1f735b0e70d50d71ce849 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 20 Jun 2026 23:45:43 +0300
Subject: [PATCH 21/28] feat(ai-chat): auto-collapse the chat window on page
 focus, expand on header (#42)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The floating chat window covered page content; you could only collapse it
manually. Now it auto-collapses to its header (visual collapse only — ChatThread
stays mounted so an in-flight stream isn't interrupted) when you interact with
the page, and expands again from the header.

- document mousedown listener in the CAPTURE phase, armed only when
  windowOpen && !minimized; collapses on a pointer-down outside the window.
  Guards: ignore clicks inside the window and inside any Mantine [data-portal]
  (the chat-list kebab menu + delete-confirm modal render in portals).
- Header click expands: startDrag distinguishes click vs drag by a 4px
  threshold (minimizedRef avoids a stale closure); an expand-click doesn't
  persist geometry.
- Reset minimized=false when the window opens (no sticky collapsed state).
- a11y: when minimized, the title is the keyboard expand affordance
  (role=button, tabIndex, aria-label Expand, Enter/Space) — kept off the
  dragBar container so no role=button wraps the Minimize/Close buttons.
- Pure helpers shouldCollapseOnOutsidePointer + isHeaderClick with vitest tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../components/ai-chat-window.module.css      |  6 ++
 .../ai-chat/components/ai-chat-window.tsx     | 74 ++++++++++++++++-
 .../ai-chat/utils/collapse-helpers.test.ts    | 79 +++++++++++++++++++
 .../ai-chat/utils/collapse-helpers.ts         | 41 ++++++++++
 4 files changed, 197 insertions(+), 3 deletions(-)
 create mode 100644 apps/client/src/features/ai-chat/utils/collapse-helpers.test.ts
 create mode 100644 apps/client/src/features/ai-chat/utils/collapse-helpers.ts

diff --git a/apps/client/src/features/ai-chat/components/ai-chat-window.module.css b/apps/client/src/features/ai-chat/components/ai-chat-window.module.css
index 71de2066..5758a018 100644
--- a/apps/client/src/features/ai-chat/components/ai-chat-window.module.css
+++ b/apps/client/src/features/ai-chat/components/ai-chat-window.module.css
@@ -57,6 +57,12 @@
     display: none;
 }
 
+/* In the collapsed state the header expands the window on click, so hint that
+   it is clickable (override the drag `grab` cursor). */
+.minimized .dragBar {
+    cursor: pointer;
+}
+
 .dragBar {
     display: flex;
     align-items: center;
diff --git a/apps/client/src/features/ai-chat/components/ai-chat-window.tsx b/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
index 1b9012c5..2384f788 100644
--- a/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
+++ b/apps/client/src/features/ai-chat/components/ai-chat-window.tsx
@@ -38,6 +38,10 @@ import {
 import ConversationList from "@/features/ai-chat/components/conversation-list.tsx";
 import ChatThread from "@/features/ai-chat/components/chat-thread.tsx";
 import { buildChatMarkdown } from "@/features/ai-chat/utils/chat-markdown.ts";
+import {
+  shouldCollapseOnOutsidePointer,
+  isHeaderClick,
+} from "@/features/ai-chat/utils/collapse-helpers.ts";
 import { useClipboard } from "@/hooks/use-clipboard";
 import { notifications } from "@mantine/notifications";
 import classes from "@/features/ai-chat/components/ai-chat-window.module.css";
@@ -110,6 +114,10 @@ export default function AiChatWindow() {
   // History section starts collapsed (matches the former panel's behavior).
   const [historyOpen, setHistoryOpen] = useState(false);
   const [minimized, setMinimized] = useState(false);
+  // Mirror of `minimized` for handlers wrapped in useCallback([]) (startDrag),
+  // which would otherwise close over a stale value. Kept in sync below.
+  const minimizedRef = useRef(minimized);
+  minimizedRef.current = minimized;
 
   const winRef = useRef<HTMLDivElement>(null);
   // Live window geometry (position + size); initialized lazily on first open so
@@ -254,8 +262,31 @@ export default function AiChatWindow() {
   useLayoutEffect(() => {
     if (!windowOpen) return;
     setGeom((prev) => (prev ? clampGeom(prev) : computeInitialGeom()));
+    // Always show the window expanded on (re)open: a collapsed state from a
+    // previous open session must not stick. Runs before paint so the first
+    // frame is already expanded. The composer's autofocus is a focus INSIDE the
+    // window (not an outside mousedown), so it cannot self-collapse the window.
+    setMinimized(false);
   }, [windowOpen]);
 
+  // Auto-collapse the window into its header as soon as the user interacts with
+  // anything outside it (clicks the page/editor). Armed ONLY while the window is
+  // open and expanded, so it never fires repeatedly and never collapses on the
+  // open→reset transition. Capture phase so a page handler's stopPropagation in
+  // the bubble phase can't hide the event from us; the in-window/portal guards
+  // (shouldCollapseOnOutsidePointer) prevent false collapses from clicks inside
+  // the window or inside Mantine portals (kebab menu, delete-confirm modal).
+  useEffect(() => {
+    if (!windowOpen || minimized) return;
+    const onPointerDown = (e: MouseEvent): void => {
+      if (shouldCollapseOnOutsidePointer(e.target, winRef.current)) {
+        setMinimized(true);
+      }
+    };
+    document.addEventListener("mousedown", onPointerDown, true);
+    return () => document.removeEventListener("mousedown", onPointerDown, true);
+  }, [windowOpen, minimized]);
+
   // Persist the user's resize into state so it survives close/reopen. Skipped
   // while minimized so the collapsed (auto) height is never captured. The
   // equality guard avoids an update loop.
@@ -303,10 +334,21 @@ export default function AiChatWindow() {
       el.style.top = `${nt}px`;
     };
 
-    const up = (): void => {
+    const up = (ev: MouseEvent): void => {
       document.removeEventListener("mousemove", move);
       document.removeEventListener("mouseup", up);
       document.body.style.userSelect = "";
+      // Treat a near-zero-movement press as a click (not a drag). When the
+      // window is minimized, a header click expands it; nothing to persist
+      // because the position did not change. minimizedRef avoids the stale
+      // `minimized` captured by useCallback([]).
+      if (
+        minimizedRef.current &&
+        isHeaderClick(sx, sy, ev.clientX, ev.clientY)
+      ) {
+        setMinimized(false);
+        return;
+      }
       const el2 = winRef.current;
       // Persist the final position back into state (preserving the size) so
       // re-renders keep it.
@@ -350,14 +392,40 @@ export default function AiChatWindow() {
         height: minimized ? undefined : geom.height,
       }}
     >
-      {/* drag bar / header */}
+      {/* drag bar / header. Mouse users expand a minimized window by clicking
+          anywhere on the bar (the click-vs-drag logic in startDrag, which
+          excludes the buttons). The keyboard/screen-reader Expand affordance
+          lives on the title element below — NOT on this container — so we never
+          nest the Minimize/Close <button>s inside an element with
+          role="button" (invalid ARIA: nested interactive controls). */}
       <div className={classes.dragBar} onMouseDown={startDrag}>
         <IconGripVertical
           size={14}
           color="var(--mantine-color-gray-4)"
           style={{ flex: "none" }}
         />
-        <span className={classes.title}>{t("AI chat")}</span>
+        {/* When minimized, the title doubles as the keyboard Expand button:
+            it carries role/tabIndex/aria-label and an Enter/Space handler, and
+            unlike the dragBar it contains no nested <button>s. When expanded it
+            is a plain, non-focusable label. */}
+        <span
+          className={classes.title}
+          role={minimized ? "button" : undefined}
+          tabIndex={minimized ? 0 : undefined}
+          aria-label={minimized ? t("Expand") : undefined}
+          onKeyDown={
+            minimized
+              ? (event) => {
+                  if (event.key === "Enter" || event.key === " ") {
+                    event.preventDefault();
+                    setMinimized(false);
+                  }
+                }
+              : undefined
+          }
+        >
+          {t("AI chat")}
+        </span>
 
         {/* Role badge for the active chat (emoji + name). Shown only when the
             chat is bound to a role that still exists. */}
diff --git a/apps/client/src/features/ai-chat/utils/collapse-helpers.test.ts b/apps/client/src/features/ai-chat/utils/collapse-helpers.test.ts
new file mode 100644
index 00000000..d9fed247
--- /dev/null
+++ b/apps/client/src/features/ai-chat/utils/collapse-helpers.test.ts
@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  shouldCollapseOnOutsidePointer,
+  isHeaderClick,
+} from "./collapse-helpers";
+
+describe("shouldCollapseOnOutsidePointer", () => {
+  let windowEl: HTMLDivElement;
+  let inside: HTMLSpanElement;
+  let portal: HTMLDivElement;
+  let portalChild: HTMLButtonElement;
+  let page: HTMLDivElement;
+
+  beforeEach(() => {
+    // The floating window with a child node.
+    windowEl = document.createElement("div");
+    inside = document.createElement("span");
+    windowEl.appendChild(inside);
+
+    // A Mantine-style portal (data-portal="true") with a child (e.g. a menu item).
+    portal = document.createElement("div");
+    portal.setAttribute("data-portal", "true");
+    portalChild = document.createElement("button");
+    portal.appendChild(portalChild);
+
+    // An unrelated page element.
+    page = document.createElement("div");
+
+    document.body.append(windowEl, portal, page);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("returns false for a target inside the window", () => {
+    expect(shouldCollapseOnOutsidePointer(inside, windowEl)).toBe(false);
+    expect(shouldCollapseOnOutsidePointer(windowEl, windowEl)).toBe(false);
+  });
+
+  it("returns false for a target inside a Mantine portal", () => {
+    expect(shouldCollapseOnOutsidePointer(portal, windowEl)).toBe(false);
+    expect(shouldCollapseOnOutsidePointer(portalChild, windowEl)).toBe(false);
+  });
+
+  it("returns true for a target on the page (outside window and portals)", () => {
+    expect(shouldCollapseOnOutsidePointer(page, windowEl)).toBe(true);
+  });
+
+  it("returns false when there is no window element", () => {
+    expect(shouldCollapseOnOutsidePointer(page, null)).toBe(false);
+  });
+
+  it("returns false for a non-Element target", () => {
+    expect(shouldCollapseOnOutsidePointer(null, windowEl)).toBe(false);
+    expect(shouldCollapseOnOutsidePointer(document, windowEl)).toBe(false);
+  });
+});
+
+describe("isHeaderClick", () => {
+  it("treats a zero-movement press as a click", () => {
+    expect(isHeaderClick(100, 100, 100, 100)).toBe(true);
+  });
+
+  it("treats movement within the threshold as a click", () => {
+    expect(isHeaderClick(100, 100, 103, 97)).toBe(true);
+    expect(isHeaderClick(100, 100, 104, 104)).toBe(true);
+  });
+
+  it("treats movement beyond the threshold (either axis) as a drag", () => {
+    expect(isHeaderClick(100, 100, 105, 100)).toBe(false);
+    expect(isHeaderClick(100, 100, 100, 105)).toBe(false);
+  });
+
+  it("honors a custom threshold", () => {
+    expect(isHeaderClick(0, 0, 8, 0, 10)).toBe(true);
+    expect(isHeaderClick(0, 0, 11, 0, 10)).toBe(false);
+  });
+});
diff --git a/apps/client/src/features/ai-chat/utils/collapse-helpers.ts b/apps/client/src/features/ai-chat/utils/collapse-helpers.ts
new file mode 100644
index 00000000..c0a61779
--- /dev/null
+++ b/apps/client/src/features/ai-chat/utils/collapse-helpers.ts
@@ -0,0 +1,41 @@
+// Pure helpers for the AI chat window auto-collapse behavior. Kept free of React
+// so they can be unit-tested in isolation (see collapse-helpers.test.ts).
+
+/**
+ * Decide whether an outside pointer (mousedown) should collapse the chat window.
+ *
+ * Returns true only when the pointer target is genuinely "on the page": NOT
+ * inside the window element AND NOT inside a Mantine portal. Mantine renders
+ * dropdown menus (chat-list kebab), modals (delete-confirm), tooltips and
+ * notifications into portals tagged with `data-portal="true"`; clicks on those
+ * are part of operating the chat, so they must not collapse it.
+ */
+export function shouldCollapseOnOutsidePointer(
+  target: EventTarget | null,
+  windowEl: HTMLElement | null,
+): boolean {
+  if (!windowEl) return false;
+  if (!(target instanceof Element)) return false;
+  // Inside the window itself -> not an "away" interaction (drag, resize, typing).
+  if (windowEl.contains(target)) return false;
+  // Inside a Mantine portal the chat owns (kebab menu, confirm modal, tooltip,
+  // notifications). data-portal="true" reliably excludes all of them.
+  if (target.closest("[data-portal]")) return false;
+  return true;
+}
+
+/**
+ * Click-vs-drag discrimination for the window header: a press whose pointer
+ * moved less than `threshold` px on both axes between mousedown and mouseup is
+ * treated as a click (which expands a collapsed window), not a drag (which
+ * repositions it).
+ */
+export function isHeaderClick(
+  downX: number,
+  downY: number,
+  upX: number,
+  upY: number,
+  threshold = 4,
+): boolean {
+  return Math.abs(upX - downX) <= threshold && Math.abs(upY - downY) <= threshold;
+}

From e0aac5aa04f8130f7bfff0762b889468da647d67 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 00:04:18 +0300
Subject: [PATCH 22/28] feat(share): public-share AI chat reuses the internal
 chat's presentation (#41)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The public-share widget was a separate minimal impl: plain-text answer, static
'Thinking…', no markdown, no tool-cards. Now it renders through the internal
chat's debugged presentational layer (MessageList/MessageItem/TypingIndicator/
ToolCallCard), so a share gets the same incremental streaming, animated typing
indicator, markdown, and tool-call cards. The share keeps its anonymous
transport (useChat + DefaultChatTransport '/api/shares/ai/stream',
credentials:'omit').

The shared components were already prop-driven (UIMessage[] + isStreaming) with
no transport/auth coupling; made the new props additive optionals (emptyState,
showCitations, neutralizeInternalLinks) all defaulting to current behavior, so
the internal chat is unchanged.

Security (review-caught): rendering assistant markdown on the ANONYMOUS share
made internal links (/p/{id}, /settings/...) clickable, which the old plain-text
render didn't. renderChatMarkdown gains neutralizeInternalLinks (true only on
the share): a one-shot DOMPurify afterSanitizeAttributes hook (added/removed by
reference around a single sanitize) strips href from internal/relative/non-http(s)
links (rendered inert) and keeps external http(s) links with
rel=noopener noreferrer nofollow target=_blank. Tests cover both the link
neutralization and the absence of any global-hook leak into internal renders.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../ai-chat/components/message-item.tsx       |  30 +++++-
 .../ai-chat/components/message-list.tsx       |  47 ++++++--
 .../components/show-typing-indicator.test.ts  |  55 ++++++++++
 .../ai-chat/components/tool-call-card.tsx     |  15 ++-
 .../features/ai-chat/utils/markdown.test.ts   |  69 ++++++++++++
 .../src/features/ai-chat/utils/markdown.ts    |  71 +++++++++++-
 .../share/components/share-ai-widget.tsx      | 101 ++++++++----------
 7 files changed, 315 insertions(+), 73 deletions(-)
 create mode 100644 apps/client/src/features/ai-chat/components/show-typing-indicator.test.ts
 create mode 100644 apps/client/src/features/ai-chat/utils/markdown.test.ts

diff --git a/apps/client/src/features/ai-chat/components/message-item.tsx b/apps/client/src/features/ai-chat/components/message-item.tsx
index 4ba1d934..e8709d5c 100644
--- a/apps/client/src/features/ai-chat/components/message-item.tsx
+++ b/apps/client/src/features/ai-chat/components/message-item.tsx
@@ -10,6 +10,18 @@ import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
 interface MessageItemProps {
   message: UIMessage;
+  /**
+   * Forwarded to ToolCallCard: whether tool cards render page citation links.
+   * Defaults to true (internal chat). The public share passes false.
+   */
+  showCitations?: boolean;
+  /**
+   * Neutralize internal/relative markdown links in the rendered answer (drop
+   * their href so they become inert text). Defaults to false (internal chat,
+   * links stay clickable). The anonymous public share passes true so internal
+   * UUIDs/routes in the assistant's markdown don't leak as clickable links.
+   */
+  neutralizeInternalLinks?: boolean;
 }
 
 /**
@@ -24,7 +36,11 @@ interface MessageItemProps {
  * `message` prop identity (and its `parts`) changes each tick. Re-rendering the
  * text parts on each delta is what makes the answer stream in progressively.
  */
-export default function MessageItem({ message }: MessageItemProps) {
+export default function MessageItem({
+  message,
+  showCitations = true,
+  neutralizeInternalLinks = false,
+}: MessageItemProps) {
   const { t } = useTranslation();
   const isUser = message.role === "user";
 
@@ -53,7 +69,9 @@ export default function MessageItem({ message }: MessageItemProps) {
           // starts with an empty text part before the first token arrives); the
           // typing indicator covers that gap until real content streams in.
           if (!part.text.trim()) return null;
-          const html = renderChatMarkdown(part.text);
+          const html = renderChatMarkdown(part.text, {
+            neutralizeInternalLinks,
+          });
           if (html) {
             return (
               <div
@@ -73,7 +91,13 @@ export default function MessageItem({ message }: MessageItemProps) {
         }
 
         if (isToolPart(part.type)) {
-          return <ToolCallCard key={index} part={part as unknown as ToolUiPart} />;
+          return (
+            <ToolCallCard
+              key={index}
+              part={part as unknown as ToolUiPart}
+              showCitations={showCitations}
+            />
+          );
         }
 
         return null;
diff --git a/apps/client/src/features/ai-chat/components/message-list.tsx b/apps/client/src/features/ai-chat/components/message-list.tsx
index ed0fb73d..3d9c5024 100644
--- a/apps/client/src/features/ai-chat/components/message-list.tsx
+++ b/apps/client/src/features/ai-chat/components/message-list.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef } from "react";
+import { ReactNode, useEffect, useRef } from "react";
 import { Center, ScrollArea, Stack, Text } from "@mantine/core";
 import { useTranslation } from "react-i18next";
 import type { UIMessage } from "@ai-sdk/react";
@@ -10,6 +10,26 @@ import classes from "@/features/ai-chat/components/ai-chat.module.css";
 interface MessageListProps {
   messages: UIMessage[];
   isStreaming: boolean;
+  /**
+   * Content shown when the transcript is empty and no turn is in flight.
+   * Defaults to the internal chat's prompt. The public share passes its own
+   * documentation-focused copy. This is purely the empty-state text; the
+   * streaming/typing/markdown/tool-card paths below are shared verbatim.
+   */
+  emptyState?: ReactNode;
+  /**
+   * Forwarded to MessageItem -> ToolCallCard: whether tool cards render page
+   * citation links. Defaults to true (internal chat). The public share passes
+   * false because an anonymous reader cannot open the linked internal pages.
+   */
+  showCitations?: boolean;
+  /**
+   * Forwarded to MessageItem: neutralize internal/relative markdown links in
+   * the rendered answers (drop their href so they render as inert text).
+   * Defaults to false (internal chat). The public share passes true so internal
+   * UUIDs/routes don't leak as clickable links to anonymous readers.
+   */
+  neutralizeInternalLinks?: boolean;
 }
 
 // Distance (px) from the bottom within which the viewport still counts as
@@ -24,7 +44,7 @@ const BOTTOM_THRESHOLD = 40;
  *  - the last (assistant) message has no non-empty text and no tool part.
  * Once any text/tool part arrives, MessageItem renders it and this hides.
  */
-function showTypingIndicator(messages: UIMessage[], isStreaming: boolean): boolean {
+export function showTypingIndicator(messages: UIMessage[], isStreaming: boolean): boolean {
   if (!isStreaming) return false;
   const last = messages[messages.length - 1];
   if (!last) return true; // submitted with nothing rendered yet.
@@ -41,7 +61,13 @@ function showTypingIndicator(messages: UIMessage[], isStreaming: boolean): boole
  * but only while the user is pinned to the bottom — if they scrolled up to read
  * earlier messages, streamed deltas no longer yank them back down.
  */
-export default function MessageList({ messages, isStreaming }: MessageListProps) {
+export default function MessageList({
+  messages,
+  isStreaming,
+  emptyState,
+  showCitations = true,
+  neutralizeInternalLinks = false,
+}: MessageListProps) {
   const { t } = useTranslation();
   const viewportRef = useRef<HTMLDivElement>(null);
   // Whether the viewport is currently pinned to the bottom. Starts true so the
@@ -104,9 +130,11 @@ export default function MessageList({ messages, isStreaming }: MessageListProps)
   if (messages.length === 0 && !typing) {
     return (
       <Center className={classes.messages}>
-        <Text size="sm" c="dimmed" ta="center">
-          {t("Ask the AI agent anything about your workspace.")}
-        </Text>
+        {emptyState ?? (
+          <Text size="sm" c="dimmed" ta="center">
+            {t("Ask the AI agent anything about your workspace.")}
+          </Text>
+        )}
       </Center>
     );
   }
@@ -115,7 +143,12 @@ export default function MessageList({ messages, isStreaming }: MessageListProps)
     <ScrollArea className={classes.messages} viewportRef={viewportRef} scrollbarSize={6} type="scroll">
       <Stack gap={0} pr="xs">
         {messages.map((message) => (
-          <MessageItem key={message.id} message={message} />
+          <MessageItem
+            key={message.id}
+            message={message}
+            showCitations={showCitations}
+            neutralizeInternalLinks={neutralizeInternalLinks}
+          />
         ))}
         {typing && <TypingIndicator />}
       </Stack>
diff --git a/apps/client/src/features/ai-chat/components/show-typing-indicator.test.ts b/apps/client/src/features/ai-chat/components/show-typing-indicator.test.ts
new file mode 100644
index 00000000..5cc023d9
--- /dev/null
+++ b/apps/client/src/features/ai-chat/components/show-typing-indicator.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import type { UIMessage } from "@ai-sdk/react";
+import { showTypingIndicator } from "@/features/ai-chat/components/message-list.tsx";
+
+/**
+ * Pure-helper tests for the typing-indicator bridging logic that the internal
+ * chat and the public share widget now share. This is the behavior that decides
+ * whether the animated "AI agent is typing…" placeholder shows in the gap
+ * between sending and the first streamed token.
+ */
+const msg = (
+  role: "user" | "assistant",
+  parts: UIMessage["parts"],
+): UIMessage => ({ id: Math.random().toString(), role, parts }) as UIMessage;
+
+describe("showTypingIndicator", () => {
+  it("is hidden when not streaming", () => {
+    expect(showTypingIndicator([], false)).toBe(false);
+    expect(
+      showTypingIndicator([msg("assistant", [{ type: "text", text: "hi" }])], false),
+    ).toBe(false);
+  });
+
+  it("shows while streaming with no messages yet (just submitted)", () => {
+    expect(showTypingIndicator([], true)).toBe(true);
+  });
+
+  it("shows while streaming when the last message is still the user's", () => {
+    expect(
+      showTypingIndicator([msg("user", [{ type: "text", text: "q" }])], true),
+    ).toBe(true);
+  });
+
+  it("shows while streaming when the assistant row has no visible content", () => {
+    expect(
+      showTypingIndicator([msg("assistant", [{ type: "text", text: "" }])], true),
+    ).toBe(true);
+    expect(
+      showTypingIndicator([msg("assistant", [{ type: "text", text: "   " }])], true),
+    ).toBe(true);
+  });
+
+  it("hides once the assistant streams non-empty text", () => {
+    expect(
+      showTypingIndicator([msg("assistant", [{ type: "text", text: "answer" }])], true),
+    ).toBe(false);
+  });
+
+  it("hides once a tool part appears (even before any text)", () => {
+    const toolPart = { type: "tool-searchPages" } as unknown as UIMessage["parts"][number];
+    expect(
+      showTypingIndicator([msg("assistant", [toolPart])], true),
+    ).toBe(false);
+  });
+});
diff --git a/apps/client/src/features/ai-chat/components/tool-call-card.tsx b/apps/client/src/features/ai-chat/components/tool-call-card.tsx
index 921be2fb..d337bd1f 100644
--- a/apps/client/src/features/ai-chat/components/tool-call-card.tsx
+++ b/apps/client/src/features/ai-chat/components/tool-call-card.tsx
@@ -13,6 +13,14 @@ import classes from "@/features/ai-chat/components/ai-chat.module.css";
 
 interface ToolCallCardProps {
   part: ToolUiPart;
+  /**
+   * Whether to render page citation links. Defaults to true (the internal chat,
+   * where the reader is authenticated and the `/p/{id}` links resolve). The
+   * public share passes false: an anonymous reader cannot open internal pages,
+   * so the links would 404/redirect to login. Suppressing them keeps the card
+   * (the action log itself) while dropping the unusable links.
+   */
+  showCitations?: boolean;
 }
 
 /**
@@ -20,12 +28,15 @@ interface ToolCallCardProps {
  * agent DID (the agent writes without confirmation — D2), its run state
  * (running / done / error), and citation link(s) to any referenced page(s).
  */
-export default function ToolCallCard({ part }: ToolCallCardProps) {
+export default function ToolCallCard({
+  part,
+  showCitations = true,
+}: ToolCallCardProps) {
   const { t } = useTranslation();
   const toolName = getToolName(part);
   const state = toolRunState(part.state);
   const { key, values } = toolLabelKey(toolName);
-  const citations = toolCitations(part);
+  const citations = showCitations ? toolCitations(part) : [];
 
   return (
     <div className={classes.toolCard}>
diff --git a/apps/client/src/features/ai-chat/utils/markdown.test.ts b/apps/client/src/features/ai-chat/utils/markdown.test.ts
new file mode 100644
index 00000000..993dcf4d
--- /dev/null
+++ b/apps/client/src/features/ai-chat/utils/markdown.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
+
+/**
+ * Tests for the internal-link neutralization used by the anonymous public
+ * share. Now that the share renders the assistant's MARKDOWN (not plain text),
+ * internal app links (e.g. `[page](/p/{uuid})`) would otherwise become clickable
+ * `<a href="/p/...">`, leaking internal UUIDs/structure and linking to auth-gated
+ * routes. With the flag ON those links are made inert (href removed) while the
+ * visible text and the rest of the markdown formatting are preserved; genuinely
+ * EXTERNAL http(s) links are kept with a safe rel/target. With the flag OFF
+ * (internal default) links keep their href so the authenticated chat is unchanged.
+ */
+
+/** Parse the rendered HTML and return the first <a> element (or null). */
+function firstAnchor(html: string): HTMLAnchorElement | null {
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  return doc.querySelector("a");
+}
+
+describe("renderChatMarkdown — internal link neutralization", () => {
+  it("makes an internal link inert when the flag is ON (no href, text kept)", () => {
+    const html = renderChatMarkdown("[x](/p/abc)", {
+      neutralizeInternalLinks: true,
+    });
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.hasAttribute("href")).toBe(false);
+    expect(a!.hasAttribute("target")).toBe(false);
+    // Visible link text is preserved.
+    expect(a!.textContent).toBe("x");
+  });
+
+  it("neutralizes bare-fragment links when the flag is ON", () => {
+    const html = renderChatMarkdown("[here](#section)", {
+      neutralizeInternalLinks: true,
+    });
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.hasAttribute("href")).toBe(false);
+  });
+
+  it("keeps an external http(s) link with a safe rel/target when the flag is ON", () => {
+    const html = renderChatMarkdown("[y](https://example.com)", {
+      neutralizeInternalLinks: true,
+    });
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.getAttribute("href")).toBe("https://example.com");
+    expect(a!.getAttribute("rel")).toBe("noopener noreferrer nofollow");
+    expect(a!.getAttribute("target")).toBe("_blank");
+  });
+
+  it("keeps internal links clickable when the flag is OFF (internal default)", () => {
+    const html = renderChatMarkdown("[x](/p/abc)");
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.getAttribute("href")).toBe("/p/abc");
+  });
+
+  it("does not leave a global DOMPurify hook that affects a later internal render", () => {
+    // A neutralizing render first, then an internal render: the internal link
+    // must survive (the hook is removed after the share render).
+    renderChatMarkdown("[x](/p/abc)", { neutralizeInternalLinks: true });
+    const html = renderChatMarkdown("[x](/p/abc)");
+    const a = firstAnchor(html);
+    expect(a!.getAttribute("href")).toBe("/p/abc");
+  });
+});
diff --git a/apps/client/src/features/ai-chat/utils/markdown.ts b/apps/client/src/features/ai-chat/utils/markdown.ts
index 529b3140..d7ba4e74 100644
--- a/apps/client/src/features/ai-chat/utils/markdown.ts
+++ b/apps/client/src/features/ai-chat/utils/markdown.ts
@@ -1,6 +1,51 @@
 import { markdownToHtml } from "@docmost/editor-ext";
 import DOMPurify from "dompurify";
 
+export interface RenderChatMarkdownOptions {
+  /**
+   * Neutralize INTERNAL links so they render as inert text (no `href`/`target`).
+   * Used by the anonymous public share: the assistant's answer can contain
+   * relative app links (e.g. `[page](/p/{uuid})`, `[settings](/settings/members)`)
+   * that would otherwise become clickable `<a href="/p/...">`, leaking internal
+   * UUIDs/structure and pointing at auth-gated routes. An anonymous reader can
+   * still follow genuinely EXTERNAL `http(s)` links, so those are kept (with a
+   * safe `rel`/`target`). Defaults to false — the internal chat keeps internal
+   * links clickable for authenticated users.
+   */
+  neutralizeInternalLinks?: boolean;
+}
+
+/**
+ * Whether `href` points at an EXTERNAL absolute URL we are happy for an
+ * anonymous reader to follow. Only absolute `http(s)://` URLs qualify;
+ * everything else (relative `/...`, bare fragments `#...`, protocol-relative
+ * `//...`, other schemes) is treated as internal/unsafe and neutralized.
+ */
+function isExternalHttpUrl(href: string): boolean {
+  return /^https?:\/\//i.test(href.trim());
+}
+
+/**
+ * DOMPurify `afterSanitizeAttributes` hook that neutralizes internal links.
+ * Hooks are GLOBAL on the DOMPurify instance, so this is only ever registered
+ * for the duration of a single sanitize call (added then removed in
+ * `renderChatMarkdown`) — it must never leak into the internal chat's renders.
+ */
+function neutralizeInternalLinksHook(node: Element): void {
+  if (node.nodeName !== "A") return;
+  const href = node.getAttribute("href");
+  if (href !== null && isExternalHttpUrl(href)) {
+    // Genuinely external link: keep it, but force a safe rel/target.
+    node.setAttribute("rel", "noopener noreferrer nofollow");
+    node.setAttribute("target", "_blank");
+    return;
+  }
+  // Internal/relative/fragment link (or no href): make it inert text. Drop the
+  // href and any target so it is no longer clickable; the visible text stays.
+  node.removeAttribute("href");
+  node.removeAttribute("target");
+}
+
 /**
  * Render AI markdown to sanitized HTML for read-only display. We reuse the
  * app's `markdownToHtml` (the same `marked` pipeline used for paste/import) so
@@ -12,9 +57,31 @@ import DOMPurify from "dompurify";
  * synchronously, but we guard the Promise case by returning a safe empty string
  * for that branch (the caller renders the raw text fallback instead).
  */
-export function renderChatMarkdown(markdown: string): string {
+export function renderChatMarkdown(
+  markdown: string,
+  options: RenderChatMarkdownOptions = {},
+): string {
   if (!markdown) return "";
   const html = markdownToHtml(markdown);
   if (typeof html !== "string") return "";
-  return DOMPurify.sanitize(html);
+
+  if (!options.neutralizeInternalLinks) {
+    // Internal chat: unchanged behavior, no hook registered.
+    return DOMPurify.sanitize(html);
+  }
+
+  // Public share: register the neutralization hook only for THIS sanitize call,
+  // then remove it immediately so it can never affect the internal chat (hooks
+  // are global on the shared DOMPurify instance).
+  DOMPurify.addHook("afterSanitizeAttributes", neutralizeInternalLinksHook);
+  try {
+    return DOMPurify.sanitize(html);
+  } finally {
+    // Remove by reference (not a bare pop) so we only ever remove OUR hook,
+    // robust to any other afterSanitizeAttributes hook registered in future.
+    DOMPurify.removeHook(
+      "afterSanitizeAttributes",
+      neutralizeInternalLinksHook,
+    );
+  }
 }
diff --git a/apps/client/src/features/share/components/share-ai-widget.tsx b/apps/client/src/features/share/components/share-ai-widget.tsx
index 90d0b9af..5212e2c4 100644
--- a/apps/client/src/features/share/components/share-ai-widget.tsx
+++ b/apps/client/src/features/share/components/share-ai-widget.tsx
@@ -7,8 +7,6 @@ import {
   Box,
   Group,
   Paper,
-  ScrollArea,
-  Stack,
   Text,
   Textarea,
   Tooltip,
@@ -22,6 +20,7 @@ import {
 import { useTranslation } from "react-i18next";
 import { useChat, type UIMessage } from "@ai-sdk/react";
 import { DefaultChatTransport } from "ai";
+import MessageList from "@/features/ai-chat/components/message-list.tsx";
 
 interface ShareAiWidgetProps {
   /** The share id (or key) the assistant is scoped to. */
@@ -30,17 +29,6 @@ interface ShareAiWidgetProps {
   pageId: string;
 }
 
-/** Concatenate the visible text parts of a UIMessage. */
-function messageText(message: UIMessage): string {
-  return (message.parts ?? [])
-    .filter(
-      (p): p is { type: "text"; text: string } =>
-        p?.type === "text" && typeof (p as { text?: string }).text === "string",
-    )
-    .map((p) => p.text)
-    .join("");
-}
-
 /**
  * Lightweight, EPHEMERAL "Ask AI" widget for a public shared page.
  *
@@ -49,6 +37,15 @@ function messageText(message: UIMessage): string {
  * memory (this component's `useChat` store) and is sent with `credentials:
  * "omit"` to the anonymous `/api/shares/ai/stream` endpoint. The server stores
  * nothing.
+ *
+ * Presentation is now shared with the internal chat: the same `MessageList`
+ * renders the streamed transcript, so the public share gets the SAME
+ * incremental markdown render, animated typing indicator, and tool-call cards
+ * as the internal chat. Only the anonymous specifics differ — no auth, no
+ * history, `credentials: "omit"`, suppressed page citations (an anonymous
+ * reader cannot open the linked internal pages), neutralized internal markdown
+ * links (so internal UUIDs/auth-gated routes in the answer don't leak as
+ * clickable links), and a documentation-focused empty state.
  */
 export default function ShareAiWidget({ shareId, pageId }: ShareAiWidgetProps) {
   const { t } = useTranslation();
@@ -147,53 +144,39 @@ export default function ShareAiWidget({ shareId, pageId }: ShareAiWidgetProps) {
           </ActionIcon>
         </Group>
 
-        <ScrollArea style={{ flex: 1 }} p="sm" scrollbarSize={6} type="scroll">
-          {messages.length === 0 ? (
-            <Text size="sm" c="dimmed" ta="center" mt="lg">
-              {t("Ask a question about this documentation.")}
-            </Text>
-          ) : (
-            <Stack gap="sm">
-              {messages.map((message) => (
-                <Box
-                  key={message.id}
-                  style={{
-                    alignSelf:
-                      message.role === "user" ? "flex-end" : "flex-start",
-                    maxWidth: "85%",
-                  }}
-                >
-                  <Paper
-                    p="xs"
-                    radius="md"
-                    bg={
-                      message.role === "user"
-                        ? "var(--mantine-color-blue-light)"
-                        : "var(--mantine-color-default-hover)"
-                    }
-                  >
-                    <Text size="sm" style={{ whiteSpace: "pre-wrap" }}>
-                      {messageText(message) ||
-                        (isStreaming ? t("Thinking…") : "")}
-                    </Text>
-                  </Paper>
-                </Box>
-              ))}
-            </Stack>
-          )}
+        {/* Shared transcript: same incremental streaming render, animated typing
+            indicator, markdown, and tool-call cards as the internal chat. The
+            share is anonymous, so page citation links are suppressed (an
+            anonymous reader cannot open the linked internal pages). */}
+        <Box style={{ flex: 1, minHeight: 0, display: "flex", padding: "var(--mantine-spacing-sm)" }}>
+          <MessageList
+            messages={messages}
+            isStreaming={isStreaming}
+            showCitations={false}
+            // Anonymous reader: neutralize internal/relative links in the
+            // assistant's markdown so internal UUIDs/auth-gated routes don't
+            // leak as clickable links (external http(s) links are kept).
+            neutralizeInternalLinks={true}
+            emptyState={
+              <Text size="sm" c="dimmed" ta="center">
+                {t("Ask a question about this documentation.")}
+              </Text>
+            }
+          />
+        </Box>
 
-          {error && (
-            <Alert
-              variant="light"
-              color="red"
-              icon={<IconAlertTriangle size={16} />}
-              mt="sm"
-              title={t("Something went wrong")}
-            >
-              {t("The assistant is unavailable right now. Please try again.")}
-            </Alert>
-          )}
-        </ScrollArea>
+        {error && (
+          <Alert
+            variant="light"
+            color="red"
+            icon={<IconAlertTriangle size={16} />}
+            mx="sm"
+            mb="xs"
+            title={t("Something went wrong")}
+          >
+            {t("The assistant is unavailable right now. Please try again.")}
+          </Alert>
+        )}
 
         <Group
           gap="xs"

From bd377ca4a8c99526e2246812bbace776c48ccf9b Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 00:19:39 +0300
Subject: [PATCH 23/28] docs(backlog): record deferred tests + non-test gaps
 from the coverage PR

Captures what PR #49 intentionally left out: DB-integration tests (need a
test Postgres), the public-share XFF e2e + real-Redis Lua check (need an
HTTP/Redis harness), the full AiChatService.stream integration (R1-stream
seam), and the related non-test findings (no server-side model allow-list,
unreferenced restriction-cache invalidation, client-only embed recursion
cap, missing cycle guard, and the pre-existing jest DI/lib0-ESM debt).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../backlog/feature-test-coverage-deferred.md | 125 ++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 docs/backlog/feature-test-coverage-deferred.md

diff --git a/docs/backlog/feature-test-coverage-deferred.md b/docs/backlog/feature-test-coverage-deferred.md
new file mode 100644
index 00000000..05483b81
--- /dev/null
+++ b/docs/backlog/feature-test-coverage-deferred.md
@@ -0,0 +1,125 @@
+# Отложенные тесты по фичам с коммита 053a9c0d (хвост от PR #49)
+
+## Контекст
+
+PR #49 («test: cover features since 053a9c0d + repair test tooling») закрыл
+основную массу покрытия новых фич gitmost (+~330 тестов: server/Jest,
+client/Vitest, editor-ext/Vitest, packages/mcp/node:test) и починил
+тест-инструментарий (FIX-0 сломанные спеки transclusion, BUILD-0 сборка
+editor-ext перед серверными тестами, INFRA-0 резолв `.tsx` email-шаблонов).
+
+Часть тестов из принятого тест-плана **намеренно отложена** — им нужен
+тестовый Postgres, реальный Redis или HTTP/e2e-харнес, которых в проекте
+сейчас нет, либо инвазивный рефактор продакшн-кода. Ниже — что осталось и
+почему, чтобы не потерять.
+
+---
+
+## 1. Интеграционные тесты против БД (нужен тестовый Postgres)
+
+Сейчас все repo-зависимые проверки делаются на моках; SQL-уровень не
+исполняется. Чтобы покрыть это честно, нужен поднимаемый в CI Postgres
+(testcontainers или сервис в pipeline) + хелпер миграций.
+
+- **`AiAgentRoleRepo` — изоляция и индексы.**
+  `apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts`.
+  Проверить против реальной БД: `findById`/`listByWorkspace` исключают
+  soft-deleted строки; `findById` для roleId из ЧУЖОГО workspace → undefined
+  (tenant-изоляция); дубль имени в одном workspace → 23505; то же имя
+  переиспользуемо после softDelete (partial unique index
+  `WHERE deleted_at IS NULL`, миграция `20260620T120000-ai-agent-roles.ts`);
+  одинаковое имя в разных workspace разрешено. Это «хребет» безопасности —
+  сейчас только предполагается unit-моками.
+
+- **`AiChatRepo.findByCreator` — join role-badge.**
+  `apps/server/src/database/repos/ai-chat/ai-chat.repo.ts` (~:27-70).
+  Чат с enabled-ролью → roleName/roleEmoji заполнены; с soft-deleted ролью →
+  бейдж NULL; с DISABLED ролью → бейдж NULL (должно совпадать с
+  `resolveRoleForRequest`); ORDER BY квалифицирован `aiChats.*` (нет
+  ambiguous column после join). Не проверяемо чистым unit-ом.
+
+- **`WorkspaceService.update` / `WorkspaceRepo.updateSetting` — jsonb-merge.**
+  `apps/server/src/core/workspace/services/workspace.service.ts` (~:514),
+  `apps/server/src/database/repos/workspace/workspace.repo.ts` (~:275).
+  Сейчас покрыта только форма вызова сервиса
+  (`workspace-html-embed.spec.ts`). Не покрыто (нужна БД): `htmlEmbed:true`
+  персистится через jsonb-merge **не затирая** соседние настройки (ai,
+  sharing). Это и есть «kill-switch пишется» — критично, что write-половина
+  тоггла не ломает остальной settings-namespace.
+
+- **FK `page_template_references` onDelete('cascade').**
+  Миграция `20260620T131000-page-template-references.ts`. Проверить, что
+  удаление source/reference-страницы каскадит строки ссылок.
+
+## 2. HTTP / e2e-харнес (его нет в apps/server)
+
+- **Public-share ассистент: обход per-IP throttle ротацией XFF, но
+  per-workspace cap держит.**
+  Контроллер использует стоковый `@UseGuards(ThrottlerGuard)`
+  (`apps/server/src/core/ai-chat/public-share-chat.controller.ts`), IP берётся
+  из Fastify `trustProxy` → `X-Forwarded-For`. Единственный оправданный e2e
+  (named journey «аноним спамит ассистента»): ротация XFF обходит per-IP
+  лимит 5/min, но per-workspace cost-cap всё равно отдаёт 429. Требует
+  поднятого HTTP-слоя Nest + trusted-proxy конфигурации.
+
+- **Достоверность Lua-окна cost-cap против реального Redis.**
+  `apps/server/src/core/ai-chat/public-share-workspace-limiter.ts`
+  (`SLIDING_WINDOW_LUA`). Сейчас cap тестируется против TS-реализации
+  `FakeRedis` в `public-share-chat.spec.ts` — баг в самой Lua-строке
+  (`>=` vs `>`, неверный PEXPIRE) не поймается. Нужен интеграционный тест
+  против реального/testcontainers Redis.
+
+## 3. Полная интеграция `AiChatService.stream` (рефактор R1-stream)
+
+`apps/server/src/core/ai-chat/ai-chat.service.ts`. В PR #49 извлечён и
+покрыт только чистый `buildErrorAssistantRecord`. Полные интеграционные
+сценарии — **запись чата, упавшего на первом ходу** (onError), жизненный
+цикл external-MCP клиентов (закрытие при throw/onFinish), и
+**история восстанавливается из БД, а не из `body.messages`** (анти-tamper) —
+требуют сидирования SDK `streamText` (инъекция/seam колбэков `onError`/
+`onFinish`/`onAbort` + `res.hijack`). Отложено, чтобы не дестабилизировать
+287-строчный `stream()`; делать вместе с выносом testable turn-pipeline.
+
+---
+
+## Сопутствующие НЕ-тестовые находки (отдельные задачи)
+
+Всплыли во время написания тестов; чинить отдельными PR, не в тест-ветке.
+
+- **Нет серверной валидации «допустимого набора моделей» для роли.**
+  `chatModel` — свободная строка `MaxLength(200)`
+  (`apps/server/src/core/ai-chat/roles/dto/agent-role.dto.ts`); невалидная
+  модель принимается и падает только в рантайме как provider-ошибка/503.
+  Плюс клиентский enum драйверов
+  (`ai-agent-role-form.tsx`) захардкожен и может разойтись с серверным
+  `AI_DRIVERS` (`apps/server/src/integrations/ai/ai.types.ts`) — кандидат на
+  shared-константу или contract-тест.
+
+- **`WsService.invalidateSpaceRestrictionCache` не имеет вызывающих.**
+  `apps/server/src/ws/ws.service.ts` (~:44-48). Кэш `spaceHasRestrictions`
+  (TTL 30с) ничем не инвалидируется при изменении ограничений → реальное
+  30-секундное окно устаревания (риск утечки заголовков/метаданных дерева).
+  Привязать инвалидацию к ручкам restrict/grant/revoke.
+
+- **Серверный guard рекурсии page-embed.**
+  Cap глубины/циклов `PAGE_EMBED_MAX_DEPTH=5` — только клиентский
+  (`page-embed-view.tsx`). Серверный `/pages/template/lookup` ограничен лишь
+  throttle 30/60с + `ArrayMaxSize(50)`. Оценить, нужен ли серверный guard
+  раскрытия.
+
+- **`collectPageEmbedsFromPmJson` без cycle-guard.**
+  `apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts`
+  (~:108-139). На циклическом объекте — `RangeError` (stack overflow). Через
+  JSON-парсинг недостижимо (реальный вход), поэтому низкий приоритет; тест
+  закрепляет текущее поведение.
+
+- **Предсуществующий долг jest-инфраструктуры (блокирует часть интеграций).**
+  16 серверных сьютов падают: (а) NestJS DI — стоковые `should be defined`
+  через `Test.createTestingModule(...).compile()` без провайдеров (auth,
+  page, comment, group, space, search, user, workspace, token, storage,
+  environment); (б) lib0 ESM — `Cannot use import statement outside a module`
+  из `lib0/decoding.js` по цепочке `@hocuspocus/server` (comment.service,
+  page.service, page.controller). `lib0` не входит в jest
+  `transformIgnorePatterns`. Пока это так, полноценные интеграционные тесты
+  сервисов/контроллеров через полный DI-граф невозможны (в PR #49 такие
+  тесты сделаны прямым конструированием с моками).

From 41efacbe3df17e60d41fc6bd50bec3e92809cb52 Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 00:25:05 +0300
Subject: [PATCH 24/28] docs(backlog): move non-test findings out to issues
 #52-#56

Keep the backlog focused on deferred TESTS; the related non-test gaps
(model-allow-list, restriction-cache invalidation, server embed-recursion
guard, collectPageEmbeds cycle guard, jest DI/lib0-ESM debt) are now
tracked as issues #52-#56 and only linked from the backlog.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../backlog/feature-test-coverage-deferred.md | 46 +++----------------
 1 file changed, 7 insertions(+), 39 deletions(-)

diff --git a/docs/backlog/feature-test-coverage-deferred.md b/docs/backlog/feature-test-coverage-deferred.md
index 05483b81..410357a4 100644
--- a/docs/backlog/feature-test-coverage-deferred.md
+++ b/docs/backlog/feature-test-coverage-deferred.md
@@ -82,44 +82,12 @@ editor-ext перед серверными тестами, INFRA-0 резолв
 
 ---
 
-## Сопутствующие НЕ-тестовые находки (отдельные задачи)
+## Сопутствующие НЕ-тестовые находки
 
-Всплыли во время написания тестов; чинить отдельными PR, не в тест-ветке.
+Вынесены в отдельные issues (всплыли во время написания тестов):
 
-- **Нет серверной валидации «допустимого набора моделей» для роли.**
-  `chatModel` — свободная строка `MaxLength(200)`
-  (`apps/server/src/core/ai-chat/roles/dto/agent-role.dto.ts`); невалидная
-  модель принимается и падает только в рантайме как provider-ошибка/503.
-  Плюс клиентский enum драйверов
-  (`ai-agent-role-form.tsx`) захардкожен и может разойтись с серверным
-  `AI_DRIVERS` (`apps/server/src/integrations/ai/ai.types.ts`) — кандидат на
-  shared-константу или contract-тест.
-
-- **`WsService.invalidateSpaceRestrictionCache` не имеет вызывающих.**
-  `apps/server/src/ws/ws.service.ts` (~:44-48). Кэш `spaceHasRestrictions`
-  (TTL 30с) ничем не инвалидируется при изменении ограничений → реальное
-  30-секундное окно устаревания (риск утечки заголовков/метаданных дерева).
-  Привязать инвалидацию к ручкам restrict/grant/revoke.
-
-- **Серверный guard рекурсии page-embed.**
-  Cap глубины/циклов `PAGE_EMBED_MAX_DEPTH=5` — только клиентский
-  (`page-embed-view.tsx`). Серверный `/pages/template/lookup` ограничен лишь
-  throttle 30/60с + `ArrayMaxSize(50)`. Оценить, нужен ли серверный guard
-  раскрытия.
-
-- **`collectPageEmbedsFromPmJson` без cycle-guard.**
-  `apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts`
-  (~:108-139). На циклическом объекте — `RangeError` (stack overflow). Через
-  JSON-парсинг недостижимо (реальный вход), поэтому низкий приоритет; тест
-  закрепляет текущее поведение.
-
-- **Предсуществующий долг jest-инфраструктуры (блокирует часть интеграций).**
-  16 серверных сьютов падают: (а) NestJS DI — стоковые `should be defined`
-  через `Test.createTestingModule(...).compile()` без провайдеров (auth,
-  page, comment, group, space, search, user, workspace, token, storage,
-  environment); (б) lib0 ESM — `Cannot use import statement outside a module`
-  из `lib0/decoding.js` по цепочке `@hocuspocus/server` (comment.service,
-  page.service, page.controller). `lib0` не входит в jest
-  `transformIgnorePatterns`. Пока это так, полноценные интеграционные тесты
-  сервисов/контроллеров через полный DI-граф невозможны (в PR #49 такие
-  тесты сделаны прямым конструированием с моками).
+- #52 — ai-roles: нет серверной валидации модели роли + дрейф enum драйверов.
+- #53 — ws: `invalidateSpaceRestrictionCache` без вызывающих (30с stale-окно).
+- #54 — page-embed: серверный guard глубины/циклов раскрытия.
+- #55 — transclusion: cycle-guard в `collectPageEmbedsFromPmJson`.
+- #56 — test-infra: jest DI + lib0 ESM (16 падающих сьютов).

From d96f94a80aa66de1070974c9c881f077d39d101f Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 00:44:21 +0300
Subject: [PATCH 25/28] ci: run the test suites on push/PR + quarantine broken
 stock scaffolds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add .github/workflows/test.yml (pnpm + Node 22): on pull_request and push
to develop it installs, builds @docmost/editor-ext and runs `pnpm -r test`
across all packages (server Jest, client Vitest, editor-ext Vitest,
packages/mcp node:test). So tests now run automatically in CI, not just
on demand.

To make the run green, quarantine the 16 pre-existing stock NestJS
`should be defined` scaffold specs via jest `testPathIgnorePatterns` —
they never compiled (missing DI providers / lib0 ESM) and assert nothing
useful. Tracked for a proper fix/removal in issue #56. Verified each
pattern drops only its scaffold (46 of 62 suites still collected) and the
full `pnpm -r test` is green: server 587, client 185, editor-ext 56,
mcp 247.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/test.yml | 42 ++++++++++++++++++++++++++++++++++++++
 apps/server/package.json   | 19 +++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 .github/workflows/test.yml

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 00000000..54a82264
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,42 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches:
+      - develop
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Required for the client suite, which resolves @docmost/editor-ext via its
+      # dist build (the server suite also rebuilds it through its own pretest).
+      - name: Build editor-ext
+        run: pnpm --filter @docmost/editor-ext build
+
+      - name: Run tests
+        run: pnpm -r test
diff --git a/apps/server/package.json b/apps/server/package.json
index 41f4ad31..cabff6df 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -168,6 +168,25 @@
     ],
     "rootDir": "src",
     "testRegex": ".*\\.spec\\.ts$",
+    "testPathIgnorePatterns": [
+      "/node_modules/",
+      "<rootDir>/core/auth/auth.controller.spec.ts",
+      "<rootDir>/core/auth/services/auth.service.spec.ts",
+      "<rootDir>/core/auth/services/token.service.spec.ts",
+      "<rootDir>/core/comment/comment.service.spec.ts",
+      "<rootDir>/core/group/group.controller.spec.ts",
+      "<rootDir>/core/group/services/group.service.spec.ts",
+      "<rootDir>/core/page/page.controller.spec.ts",
+      "<rootDir>/core/page/services/page.service.spec.ts",
+      "<rootDir>/core/search/search.controller.spec.ts",
+      "<rootDir>/core/search/search.service.spec.ts",
+      "<rootDir>/core/space/services/space.service.spec.ts",
+      "<rootDir>/core/space/space.controller.spec.ts",
+      "<rootDir>/core/user/user.controller.spec.ts",
+      "<rootDir>/core/workspace/services/workspace.service.spec.ts",
+      "<rootDir>/integrations/environment/environment.service.spec.ts",
+      "<rootDir>/integrations/storage/storage.service.spec.ts"
+    ],
     "transform": {
       "happy-dom.+\\.js$": [
         "babel-jest",

From 0caceb614bf8178b32e4693895254de489387136 Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 01:17:27 +0300
Subject: [PATCH 26/28] ci: gate develop & release image builds on the test
 suite

The Docker-image builds ran independently of the Test workflow, so a
failing test would not block publishing the :develop image (or a
release). GitHub Actions `needs:` only works within one workflow, so the
two separate workflows didn't depend on each other.

Make test.yml a reusable workflow (workflow_call) and call it from
develop.yml and release.yml as a `test` job that `build` depends on
(`needs: test`); release's `release` job already needs `build`, so it
waits transitively. test.yml keeps its pull_request trigger for PR
gating; its redundant push:develop trigger is dropped (develop.yml now
calls it on push).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/develop.yml | 5 +++++
 .github/workflows/release.yml | 5 +++++
 .github/workflows/test.yml    | 4 +---
 3 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/develop.yml b/.github/workflows/develop.yml
index 5959983e..2d81467c 100644
--- a/.github/workflows/develop.yml
+++ b/.github/workflows/develop.yml
@@ -18,7 +18,12 @@ env:
   IMAGE: ghcr.io/vvzvlad/gitmost
 
 jobs:
+  # Run the reusable test suite first so a failing test blocks the image build.
+  test:
+    uses: ./.github/workflows/test.yml
+
   build:
+    needs: test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7137d953..694df01b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -19,7 +19,12 @@ env:
   IMAGE: ghcr.io/vvzvlad/gitmost
 
 jobs:
+  # Run the reusable test suite first so a failing test blocks the image build.
+  test:
+    uses: ./.github/workflows/test.yml
+
   build:
+    needs: test
     strategy:
       matrix:
         include:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 54a82264..955b0ac2 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -2,9 +2,7 @@ name: Test
 
 on:
   pull_request:
-  push:
-    branches:
-      - develop
+  workflow_call:
   workflow_dispatch:
 
 concurrency:

From f63719a21ce73deccf3e5a3c12b8fb5f9a87b0e3 Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 01:20:11 +0300
Subject: [PATCH 27/28] fix(share): neutralize own-origin absolute links in
 public-share AI chat

isExternalHttpUrl treated any http(s):// URL as external, so an absolute link
back to the app's own host (e.g. https://self/p/{uuid}, /settings/members)
emitted by the assistant stayed clickable on the anonymous share, leaking
internal UUIDs/structure and pointing at auth-gated routes. Classify a link as
external only when its host differs from window.location.host; unparseable URLs
are treated as internal (fail-closed). Tests cover own-origin absolute (flag
on -> inert), external host (kept with safe rel/target), dangerous schemes, and
no behavior change for the internal chat (flag off).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../features/ai-chat/utils/markdown.test.ts   | 56 +++++++++++++++++--
 .../src/features/ai-chat/utils/markdown.ts    | 29 +++++++---
 2 files changed, 74 insertions(+), 11 deletions(-)

diff --git a/apps/client/src/features/ai-chat/utils/markdown.test.ts b/apps/client/src/features/ai-chat/utils/markdown.test.ts
index 993dcf4d..ae993bff 100644
--- a/apps/client/src/features/ai-chat/utils/markdown.test.ts
+++ b/apps/client/src/features/ai-chat/utils/markdown.test.ts
@@ -8,8 +8,10 @@ import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
  * `<a href="/p/...">`, leaking internal UUIDs/structure and linking to auth-gated
  * routes. With the flag ON those links are made inert (href removed) while the
  * visible text and the rest of the markdown formatting are preserved; genuinely
- * EXTERNAL http(s) links are kept with a safe rel/target. With the flag OFF
- * (internal default) links keep their href so the authenticated chat is unchanged.
+ * EXTERNAL http(s) links (a DIFFERENT host than the app's own origin) are kept
+ * with a safe rel/target, while absolute links back to our OWN origin are
+ * neutralized too. With the flag OFF (internal default) links keep their href so
+ * the authenticated chat is unchanged.
  */
 
 /** Parse the rendered HTML and return the first <a> element (or null). */
@@ -41,16 +43,54 @@ describe("renderChatMarkdown — internal link neutralization", () => {
   });
 
   it("keeps an external http(s) link with a safe rel/target when the flag is ON", () => {
-    const html = renderChatMarkdown("[y](https://example.com)", {
+    const html = renderChatMarkdown("[y](https://example.com/x)", {
       neutralizeInternalLinks: true,
     });
     const a = firstAnchor(html);
     expect(a).not.toBeNull();
-    expect(a!.getAttribute("href")).toBe("https://example.com");
+    expect(a!.getAttribute("href")).toBe("https://example.com/x");
     expect(a!.getAttribute("rel")).toBe("noopener noreferrer nofollow");
     expect(a!.getAttribute("target")).toBe("_blank");
   });
 
+  it("neutralizes an absolute link to our OWN origin when the flag is ON", () => {
+    // An LLM can emit an absolute URL back at our own host (e.g.
+    // `http://self/p/{uuid}`); it is internal and must be made inert just like a
+    // relative `/p/...` link, not kept clickable as if it were external.
+    const ownOrigin = `${window.location.origin}/p/abc`;
+    const html = renderChatMarkdown(`[x](${ownOrigin})`, {
+      neutralizeInternalLinks: true,
+    });
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.hasAttribute("href")).toBe(false);
+    expect(a!.hasAttribute("target")).toBe(false);
+    expect(a!.textContent).toBe("x");
+  });
+
+  it("neutralizes dangerous/unsafe schemes when the flag is ON", () => {
+    // javascript:, data:, and protocol-relative `//...` must never stay
+    // clickable on the anonymous share — they are not genuinely external
+    // http(s) links to a different host, so the href is dropped (or sanitized
+    // away entirely by DOMPurify).
+    for (const markdown of [
+      "[a](javascript:alert(1))",
+      "[b](data:text/html,<script>alert(1)</script>)",
+      "[c](//evil.com/x)",
+    ]) {
+      const html = renderChatMarkdown(markdown, {
+        neutralizeInternalLinks: true,
+      });
+      const a = firstAnchor(html);
+      // Either the anchor was stripped of its href, or DOMPurify removed the
+      // unsafe href outright; in both cases nothing dangerous remains.
+      if (a !== null) {
+        expect(a.hasAttribute("href")).toBe(false);
+        expect(a.hasAttribute("target")).toBe(false);
+      }
+    }
+  });
+
   it("keeps internal links clickable when the flag is OFF (internal default)", () => {
     const html = renderChatMarkdown("[x](/p/abc)");
     const a = firstAnchor(html);
@@ -58,6 +98,14 @@ describe("renderChatMarkdown — internal link neutralization", () => {
     expect(a!.getAttribute("href")).toBe("/p/abc");
   });
 
+  it("keeps an absolute own-origin link clickable when the flag is OFF (internal default)", () => {
+    const ownOrigin = `${window.location.origin}/p/abc`;
+    const html = renderChatMarkdown(`[x](${ownOrigin})`);
+    const a = firstAnchor(html);
+    expect(a).not.toBeNull();
+    expect(a!.getAttribute("href")).toBe(ownOrigin);
+  });
+
   it("does not leave a global DOMPurify hook that affects a later internal render", () => {
     // A neutralizing render first, then an internal render: the internal link
     // must survive (the hook is removed after the share render).
diff --git a/apps/client/src/features/ai-chat/utils/markdown.ts b/apps/client/src/features/ai-chat/utils/markdown.ts
index d7ba4e74..c48e5002 100644
--- a/apps/client/src/features/ai-chat/utils/markdown.ts
+++ b/apps/client/src/features/ai-chat/utils/markdown.ts
@@ -8,21 +8,36 @@ export interface RenderChatMarkdownOptions {
    * relative app links (e.g. `[page](/p/{uuid})`, `[settings](/settings/members)`)
    * that would otherwise become clickable `<a href="/p/...">`, leaking internal
    * UUIDs/structure and pointing at auth-gated routes. An anonymous reader can
-   * still follow genuinely EXTERNAL `http(s)` links, so those are kept (with a
-   * safe `rel`/`target`). Defaults to false — the internal chat keeps internal
-   * links clickable for authenticated users.
+   * still follow genuinely EXTERNAL `http(s)` links (a DIFFERENT host than the
+   * app's own origin), so those are kept (with a safe `rel`/`target`); absolute
+   * links back to our OWN origin (e.g. `https://self/p/{uuid}`) are internal and
+   * neutralized too. Defaults to false — the internal chat keeps internal links
+   * clickable for authenticated users.
    */
   neutralizeInternalLinks?: boolean;
 }
 
 /**
  * Whether `href` points at an EXTERNAL absolute URL we are happy for an
- * anonymous reader to follow. Only absolute `http(s)://` URLs qualify;
- * everything else (relative `/...`, bare fragments `#...`, protocol-relative
- * `//...`, other schemes) is treated as internal/unsafe and neutralized.
+ * anonymous reader to follow. A link qualifies only if it is absolute
+ * `http(s)://` AND its host differs from the app's own origin
+ * (`window.location.host`): absolute links back to our OWN host (e.g.
+ * `https://self/p/{uuid}`) are internal and must be neutralized, exactly like
+ * relative `/p/...` links. Everything else (relative `/...`, bare fragments
+ * `#...`, protocol-relative `//...`, other schemes, or anything that does not
+ * parse) is treated as internal/unsafe and neutralized — fail closed.
  */
 function isExternalHttpUrl(href: string): boolean {
-  return /^https?:\/\//i.test(href.trim());
+  const value = href.trim();
+  if (!/^https?:\/\//i.test(value)) return false;
+  try {
+    // External only if it points at a DIFFERENT host than the app's own origin.
+    // Absolute links back to our own host (e.g. https://self/p/{uuid}) are
+    // internal and must be neutralized, same as relative `/p/...` links.
+    return new URL(value).host !== window.location.host;
+  } catch {
+    return false; // unparseable -> treat as internal/unsafe, neutralize
+  }
 }
 
 /**

From 730486ad1276a51fe53a1e03b832c9f4e9446230 Mon Sep 17 00:00:00 2001
From: claude_code <claude_code@vvzvlad.xyz>
Date: Sun, 21 Jun 2026 01:25:36 +0300
Subject: [PATCH 28/28] test(mcp): keep real mcp-auth.helpers in gate spec mock
 (forward-compat with #49)

After develop merged, mcp.service.ts calls decideBasicGate from mcp-auth.helpers.
The gate spec mocked the whole module returning only FailedLoginLimiter, so the
merged code crashed with 'decideBasicGate is not a function' (7/7 failing).
Spread jest.requireActual('./mcp-auth.helpers') so the real helpers are kept and
the gate exercises real logic; keep only FailedLoginLimiter stubbed so its
constructor runs without a real sweep timer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../mcp/mcp-basic-login-gate.spec.ts          | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts b/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts
index b9eb7a0c..351b467b 100644
--- a/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts
+++ b/apps/server/src/integrations/mcp/mcp-basic-login-gate.spec.ts
@@ -72,14 +72,20 @@ jest.mock('@docmost/db/repos/user/user.repo', () => ({
 jest.mock('@docmost/db/repos/session/user-session.repo', () => ({
   UserSessionRepo: class UserSessionRepo {},
 }));
-// mcp-auth.helpers exports both runtime values (FailedLoginLimiter is used in
-// the constructor) and types. Provide a minimal FailedLoginLimiter so the
-// constructor runs; everything else the gate path doesn't need.
-jest.mock('./mcp-auth.helpers', () => ({
-  FailedLoginLimiter: class FailedLoginLimiter {
-    sweep() {}
-  },
-}));
+// mcp-auth.helpers exports runtime values the gate relies on (decideBasicGate,
+// mapAuthResultToResponse, etc.). Keep the REAL helpers so the gate exercises
+// real logic; only stub FailedLoginLimiter so its constructor runs without a
+// real sweep timer. The module is framework-free and loads cleanly under jest
+// (mcp.service.spec.ts already imports it directly), so requireActual is safe.
+jest.mock('./mcp-auth.helpers', () => {
+  const actual = jest.requireActual('./mcp-auth.helpers');
+  return {
+    ...actual,
+    FailedLoginLimiter: class FailedLoginLimiter {
+      sweep() {}
+    },
+  };
+});
 
 // Import AFTER the mocks are registered.
 // eslint-disable-next-line @typescript-eslint/no-require-imports