From d6d7dd82f6458df2c0c647f9e378d98601cc93c3 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 07:10:04 +0300
Subject: [PATCH 01/17] feat(prosemirror-markdown): new headless converter
 package seeded from git-sync (#293 stage 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create @docmost/prosemirror-markdown — the single framework-free ProseMirror<->
Markdown converter + schema mirror that git-sync and mcp will both consume,
ending the three-hand-synced-copies drift (#293). This step only CREATES the
package (no consumer yet; git-sync untouched); the switch of git-sync and mcp
onto it, plus the canonical format decisions, come in later commits of this PR.

- packages/prosemirror-markdown/src/lib/: the 8 converter-core files copied
  VERBATIM from packages/git-sync/src/lib (docmost-schema, markdown-converter,
  markdown-to-prosemirror, canonicalize, markdown-document, node-ops, page-file,
  index). Confirmed byte-identical — no behavioral drift introduced.
- src/index.ts barrel; package.json (@tiptap/* + jsdom/marked/zod, editor-ext
  workspace devDep for the contract test); tsconfig/vitest configs.
- 24 converter-core test files + fixtures copied (engine-coupled layout/
  redteam-layout-title tests correctly excluded — they import ../src/engine).
- pnpm-lock importer added; build/ gitignored (CI-built).

Verified (clean checkout, no network): pnpm --frozen-lockfile EXIT 0; tsc EXIT 0;
vitest 23 files, 443 passed | 1 expected-fail (the same image-diagrams
known-limitation carried from git-sync) — faithful extraction. git-sync untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |    4 +
 packages/prosemirror-markdown/package.json    |   45 +
 packages/prosemirror-markdown/src/index.ts    |    9 +
 .../src/lib/canonicalize.ts                   |  247 +++
 .../src/lib/docmost-schema.ts                 | 1544 +++++++++++++++++
 .../prosemirror-markdown/src/lib/index.ts     |   26 +
 .../src/lib/markdown-converter.ts             | 1130 ++++++++++++
 .../src/lib/markdown-document.ts              |  154 ++
 .../src/lib/markdown-to-prosemirror.ts        |  365 ++++
 .../prosemirror-markdown/src/lib/node-ops.ts  |  897 ++++++++++
 .../prosemirror-markdown/src/lib/page-file.ts |   81 +
 .../test/canonicalize-extra.test.ts           |  205 +++
 .../test/canonicalize.test.ts                 |  302 ++++
 .../test/diagram-roundtrip.test.ts            |  109 ++
 .../test/docmost-schema-attrs.test.ts         |  124 ++
 .../corpus/01-headings-paragraphs.json        |   36 +
 .../test/fixtures/corpus/02-inline-marks.json |   62 +
 .../test/fixtures/corpus/03-lists.json        |  113 ++
 .../test/fixtures/corpus/04-blocks.json       |   38 +
 .../test/fixtures/corpus/05-table.json        |   85 +
 .../test/fixtures/corpus/06-diagrams.json     |   17 +
 .../fixtures/corpus/07-textstyle-mention.json |   35 +
 .../test/fixtures/corpus/08-details.json      |   15 +
 .../test/fixtures/corpus/09-columns.json      |   17 +
 .../corpus/10-mention-in-heading.json         |   13 +
 .../known-limitations/image-diagrams.json     |   21 +
 .../test/fixtures/sample-doc.json             |  151 ++
 .../test/markdown-converter-gaps.test.ts      |  845 +++++++++
 .../test/markdown-converter-golden.test.ts    |  402 +++++
 .../markdown-converter-html-marks.test.ts     |  223 +++
 .../test/markdown-converter.test.ts           |  645 +++++++
 .../test/markdown-document-envelope.test.ts   |  218 +++
 .../test/markdown-document.test.ts            |   66 +
 ...markdown-roundtrip-spoiler-caption.test.ts |  129 ++
 .../test/markdown-roundtrip.property.test.ts  |  698 ++++++++
 .../test/markdown-to-prosemirror-gaps.test.ts |  535 ++++++
 .../test/media-roundtrip.test.ts              |  275 +++
 .../test/node-ops-extra.test.ts               |  268 +++
 .../test/node-ops.test.ts                     |  908 ++++++++++
 .../test/page-file.test.ts                    |   33 +
 .../test/redteam-converter.test.ts            |   89 +
 .../test/roundtrip-all-nodes.test.ts          |  297 ++++
 .../test/roundtrip-corpus.test.ts             |  104 ++
 .../test/roundtrip-helpers.ts                 |   75 +
 .../test/roundtrip.test.ts                    |  168 ++
 .../test/schema-editor-ext-contract.test.ts   |   87 +
 .../test/schema-surface-snapshot.test.ts      |  125 ++
 packages/prosemirror-markdown/tsconfig.json   |   15 +
 .../prosemirror-markdown/tsconfig.vitest.json |   15 +
 .../prosemirror-markdown/vitest.config.ts     |   40 +
 pnpm-lock.yaml                                |   61 +
 51 files changed, 12166 insertions(+)
 create mode 100644 packages/prosemirror-markdown/package.json
 create mode 100644 packages/prosemirror-markdown/src/index.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/canonicalize.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/docmost-schema.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/index.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/markdown-converter.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/markdown-document.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/node-ops.ts
 create mode 100644 packages/prosemirror-markdown/src/lib/page-file.ts
 create mode 100644 packages/prosemirror-markdown/test/canonicalize-extra.test.ts
 create mode 100644 packages/prosemirror-markdown/test/canonicalize.test.ts
 create mode 100644 packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
 create mode 100644 packages/prosemirror-markdown/test/docmost-schema-attrs.test.ts
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/01-headings-paragraphs.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/02-inline-marks.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/03-lists.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/04-blocks.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/05-table.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/06-diagrams.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/07-textstyle-mention.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/08-details.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/09-columns.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/corpus/10-mention-in-heading.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json
 create mode 100644 packages/prosemirror-markdown/test/fixtures/sample-doc.json
 create mode 100644 packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-converter-html-marks.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-converter.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-document-envelope.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-document.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-roundtrip.property.test.ts
 create mode 100644 packages/prosemirror-markdown/test/markdown-to-prosemirror-gaps.test.ts
 create mode 100644 packages/prosemirror-markdown/test/media-roundtrip.test.ts
 create mode 100644 packages/prosemirror-markdown/test/node-ops-extra.test.ts
 create mode 100644 packages/prosemirror-markdown/test/node-ops.test.ts
 create mode 100644 packages/prosemirror-markdown/test/page-file.test.ts
 create mode 100644 packages/prosemirror-markdown/test/redteam-converter.test.ts
 create mode 100644 packages/prosemirror-markdown/test/roundtrip-all-nodes.test.ts
 create mode 100644 packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
 create mode 100644 packages/prosemirror-markdown/test/roundtrip-helpers.ts
 create mode 100644 packages/prosemirror-markdown/test/roundtrip.test.ts
 create mode 100644 packages/prosemirror-markdown/test/schema-editor-ext-contract.test.ts
 create mode 100644 packages/prosemirror-markdown/test/schema-surface-snapshot.test.ts
 create mode 100644 packages/prosemirror-markdown/tsconfig.json
 create mode 100644 packages/prosemirror-markdown/tsconfig.vitest.json
 create mode 100644 packages/prosemirror-markdown/vitest.config.ts

diff --git a/.gitignore b/.gitignore
index bbc6abc1..2619e48e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,10 @@ node_modules/
 # so src/ and prod can never silently diverge).
 packages/git-sync/build/
 
+# prosemirror-markdown compiled output (built in CI/Docker via `pnpm build`,
+# never committed, so src/ and prod can never silently diverge).
+packages/prosemirror-markdown/build/
+
 # Logs
 logs
 *.log
diff --git a/packages/prosemirror-markdown/package.json b/packages/prosemirror-markdown/package.json
new file mode 100644
index 00000000..9f0bd2e3
--- /dev/null
+++ b/packages/prosemirror-markdown/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@docmost/prosemirror-markdown",
+  "version": "0.1.0",
+  "description": "Pure ProseMirror <-> Markdown converter + schema mirror (headless, framework-free).",
+  "private": true,
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@tiptap/core": "3.20.4",
+    "@tiptap/extension-highlight": "3.20.4",
+    "@tiptap/extension-image": "3.20.4",
+    "@tiptap/extension-subscript": "3.20.4",
+    "@tiptap/extension-superscript": "3.20.4",
+    "@tiptap/extension-task-item": "3.20.4",
+    "@tiptap/extension-task-list": "3.20.4",
+    "@tiptap/html": "3.20.4",
+    "@tiptap/pm": "3.20.4",
+    "@tiptap/starter-kit": "3.20.4",
+    "jsdom": "25.0.0",
+    "marked": "17.0.5",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@docmost/editor-ext": "workspace:*",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^20.0.0",
+    "fast-check": "^4.8.0",
+    "typescript": "^5.0.0",
+    "vitest": "4.1.6"
+  }
+}
diff --git a/packages/prosemirror-markdown/src/index.ts b/packages/prosemirror-markdown/src/index.ts
new file mode 100644
index 00000000..fe94a762
--- /dev/null
+++ b/packages/prosemirror-markdown/src/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Public surface of `@docmost/prosemirror-markdown`.
+ *
+ * A headless, framework-free ProseMirror <-> Markdown converter plus the
+ * Docmost schema mirror. Everything lives under `lib/` (the converter core);
+ * this top-level barrel simply re-exports that surface so the package entry is
+ * the converter surface.
+ */
+export * from "./lib/index.js";
diff --git a/packages/prosemirror-markdown/src/lib/canonicalize.ts b/packages/prosemirror-markdown/src/lib/canonicalize.ts
new file mode 100644
index 00000000..99ff5bc6
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/canonicalize.ts
@@ -0,0 +1,247 @@
+/**
+ * Semantic canonicalization of ProseMirror/TipTap documents for the round-trip
+ * idempotency check (SPEC §11, "Task #0", option (b): compare a CANONICALIZED
+ * form rather than raw bytes).
+ *
+ * `markdownToProseMirror` reconstructs schema DEFAULT attributes (e.g.
+ * `indent: null` where the source omitted it) and regenerates per-block ids on
+ * every import. A raw deep-equal of the source doc against the re-imported doc
+ * therefore diverges even when the two are semantically identical. This module
+ * normalizes a document so that two semantically-equal docs compare deep-equal
+ * regardless of block ids and absent-vs-explicit-default-null attributes.
+ *
+ * It is a self-contained module with no external dependencies.
+ */
+
+/**
+ * Known NON-NULL schema defaults that `markdownToProseMirror` materializes on
+ * import, keyed by node/mark type → { attr: defaultValue }.
+ *
+ * Why this exists: `canonicalizeAttrs` already treats an absent attr as
+ * equivalent to an explicit `null`/`undefined`. But several Docmost schema
+ * attributes default to a NON-null value, so import fills them in even when the
+ * source omitted them — making "attr absent" diverge from "attr at its default
+ * value" under a raw deep-equal. To keep "absent ≡ explicit-default", we ALSO
+ * drop any attr whose value equals its known schema default. A non-default
+ * value (e.g. `orderedList.start: 5`) is NOT a default, so it is KEPT.
+ *
+ * Every entry below was read from `packages/docmost-client/src/lib/
+ * docmost-schema.ts` (the line refs are the exact `default:` declarations) and
+ * confirmed to be materialized by an export→import→export round-trip:
+ *   - mark `link`    target / rel  — DocmostAttributes + StarterKit link.
+ *       StarterKit's link extension defaults `target: "_blank"` and
+ *       `rel: "noopener noreferrer nofollow"`; both materialize on import
+ *       (empirically confirmed) even when the source had only `href`.
+ *   - mark `comment` resolved      — docmost-schema.ts L213-214 (`default: false`).
+ *   - node `orderedList` start     — provided by StarterKit's orderedList
+ *       (`default: 1`); materializes on import (empirically confirmed).
+ *   - node `drawio`/`excalidraw`/`video`/`youtube`/`embed` align — the diagram
+ *       attribute set and the media nodes declare `align: { default: "center" }`
+ *       (docmost-schema.ts L745-750 diagramAttributes; L564 video; L626 youtube;
+ *       L667 embed). The diagram `align` is the one the round-trip materializes
+ *       (docmost-schema.ts L745); the media/embed entries normalize the SAME
+ *       `align` default for consistency. Note: this only normalizes `align` —
+ *       full canonical stability of `embed` is separately limited by the
+ *       converter coercing numeric `width`/`height` to strings, which is outside
+ *       canonicalize's scope.
+ *
+ * NOTE: `image` has NO non-null align default — its `align` defaults to `null`
+ * (docmost-schema.ts L174), so it is already handled by the null-drop rule and
+ * is intentionally NOT listed here.
+ */
+const KNOWN_DEFAULTS: Record<string, Record<string, unknown>> = {
+  // mark types
+  link: {
+    target: "_blank",
+    rel: "noopener noreferrer nofollow",
+  },
+  comment: {
+    resolved: false,
+  },
+  // node types
+  orderedList: {
+    start: 1,
+  },
+  drawio: {
+    align: "center",
+  },
+  excalidraw: {
+    align: "center",
+  },
+  video: {
+    align: "center",
+  },
+  youtube: {
+    align: "center",
+  },
+  embed: {
+    align: "center",
+  },
+};
+
+/**
+ * Prune an `attrs` object in place on a fresh copy: drop keys whose value is
+ * `null` or `undefined` (an absent attribute and an explicit default of `null`
+ * are semantically equivalent here). Optionally also drop a node-level `id`
+ * (block ids are regenerated on import, SPEC §11). ALSO drop any attr whose
+ * value equals the node/mark `type`'s known NON-null schema default
+ * (`KNOWN_DEFAULTS`), so "attr absent" ≡ "attr at its default value" — without
+ * this, the import-materialized `link.target`/`comment.resolved`/
+ * `orderedList.start`/diagram `align` defaults would be a phantom diff. Every
+ * non-default attribute value is KEPT (level, language, src, href, commentId,
+ * width, a non-default `start`/`align`, ...).
+ *
+ * Returns the pruned attrs object, or `undefined` if nothing meaningful is
+ * left (so the caller can drop the `attrs` key entirely: `{attrs:{}}` ≡ no
+ * attrs).
+ */
+function canonicalizeAttrs(
+  attrs: Record<string, unknown>,
+  dropId: boolean,
+  type: string | undefined,
+): Record<string, unknown> | undefined {
+  const defaults = type ? KNOWN_DEFAULTS[type] : undefined;
+  const out: Record<string, unknown> = {};
+  // Stable key order so a JSON.stringify of the canonical form is comparable
+  // regardless of the input's key order.
+  for (const key of Object.keys(attrs).sort()) {
+    // Block ids are regenerated on import; drop them on NODE attrs only.
+    if (dropId && key === "id") continue;
+    const value = attrs[key];
+    // Absent ≡ explicit-default-null/undefined.
+    if (value === null || value === undefined) continue;
+    // Absent ≡ explicit known non-null default (e.g. link.target="_blank").
+    // A non-default value (e.g. orderedList.start=5) does NOT match, so it is
+    // kept. The `comment` mark's `commentId` is never a default, so it always
+    // survives (SPEC §3); only its `resolved: false` default is normalized away.
+    if (defaults && key in defaults && value === defaults[key]) continue;
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Return a DEEP COPY of a ProseMirror node tree, canonicalized so that two
+ * semantically-equal documents compare deep-equal. Rules (applied recursively
+ * to the node, its `content`, and its `marks`):
+ *
+ *  1. Remove node-level `attrs.id` (regenerated on import). Mark attrs are NOT
+ *     touched for `id` (marks carry no block id; only their meaningful attrs).
+ *  2. In any `attrs` object (node OR mark) drop keys whose value is `null`/
+ *     `undefined` (absent ≡ explicit default null) OR equals that node/mark
+ *     type's known non-null schema default (absent ≡ explicit default).
+ *     Keep every non-default value. The type is passed into the attrs
+ *     normalizer so it can look up `KNOWN_DEFAULTS`.
+ *  3. If an `attrs` object becomes empty after pruning, drop the `attrs` key.
+ *  4. Preserve `marks` (including the `comment` mark and its `commentId` — a
+ *     meaningful anchor per SPEC §3; never strip it).
+ *  5. Preserve `text`, `type`, and `content` order exactly.
+ *  6. Never mutate the input.
+ */
+export function canonicalizeContent(node: any): any {
+  if (Array.isArray(node)) {
+    return node.map((child) => canonicalizeContent(child));
+  }
+  if (node === null || typeof node !== "object") {
+    // Primitive leaf (string/number/boolean/null): returned as-is.
+    return node;
+  }
+
+  // A node is a mark when it has a `type` but never carries block `content`
+  // and lives inside a `marks` array. We cannot tell from the node alone, so
+  // we distinguish at the recursion site: node `attrs` drop `id`, mark `attrs`
+  // do not. This is handled by passing a `dropId` flag down for the `attrs`
+  // key specifically (nodes) vs the `marks[].attrs` path (marks).
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(node)) {
+    if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
+      // Node-level attrs: drop the block id, null/undefined attrs, and any
+      // attr at this node type's known non-null schema default.
+      const canon = canonicalizeAttrs(
+        node.attrs as Record<string, unknown>,
+        true,
+        typeof node.type === "string" ? node.type : undefined,
+      );
+      if (canon !== undefined) out.attrs = canon;
+      // else: drop the `attrs` key entirely (rule 3).
+    } else if (key === "marks" && Array.isArray(node.marks)) {
+      // Marks: keep them all (incl. comment); canonicalize their attrs but do
+      // NOT drop `id` (a mark's `id` would be a meaningful attr, not a block
+      // id). An empty marks array is dropped so `marks:[]` ≡ no marks.
+      const marks = (node.marks as any[]).map((mark) => canonicalizeMark(mark));
+      if (marks.length > 0) out.marks = marks;
+    } else {
+      out[key] = canonicalizeContent(node[key]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Canonicalize a single mark: keep `type`, prune its `attrs` (null/undefined
+ * AND known non-null defaults dropped, empty attrs removed) but NEVER drop a
+ * mark's attribute as a "block id" — marks have no block id, only meaningful
+ * attrs (href, commentId, color, level, ...). Meaningful NON-default attrs
+ * survive (the `comment` mark's `commentId` is never a default, so it always
+ * survives — SPEC §3); only known defaults like `link.target="_blank"`,
+ * `link.rel="noopener…"` and `comment.resolved=false` are normalized away.
+ */
+function canonicalizeMark(mark: any): any {
+  if (mark === null || typeof mark !== "object") return mark;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(mark)) {
+    if (key === "attrs" && mark.attrs && typeof mark.attrs === "object") {
+      const canon = canonicalizeAttrs(
+        mark.attrs as Record<string, unknown>,
+        false,
+        typeof mark.type === "string" ? mark.type : undefined,
+      );
+      if (canon !== undefined) out.attrs = canon;
+    } else {
+      out[key] = canonicalizeContent(mark[key]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Deep structural equality of two values that is key-order-insensitive.
+ * Used to compare canonical forms. (`canonicalizeContent` already emits
+ * `attrs` in a stable key order, but the top-level node keys preserve input
+ * order, so we compare structurally rather than by string.)
+ */
+function deepEqual(a: any, b: any): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== "object") return false;
+
+  const aIsArr = Array.isArray(a);
+  const bIsArr = Array.isArray(b);
+  if (aIsArr !== bIsArr) return false;
+
+  if (aIsArr) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const k of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!deepEqual(a[k], b[k])) return false;
+  }
+  return true;
+}
+
+/**
+ * True when two ProseMirror documents are semantically equal: equal after
+ * canonicalization (block ids stripped, absent-vs-default-null normalized).
+ */
+export function docsCanonicallyEqual(a: any, b: any): boolean {
+  return deepEqual(canonicalizeContent(a), canonicalizeContent(b));
+}
diff --git a/packages/prosemirror-markdown/src/lib/docmost-schema.ts b/packages/prosemirror-markdown/src/lib/docmost-schema.ts
new file mode 100644
index 00000000..276efe90
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/docmost-schema.ts
@@ -0,0 +1,1544 @@
+/**
+ * Full TipTap extension set matching the real Docmost document schema.
+ *
+ * The default StarterKit-only schema silently destroys Docmost-specific
+ * nodes (callout, table) and drops attributes it does not know about
+ * (node ids, image sizing, link targets). Every code path that converts
+ * to or from ProseMirror JSON must use THIS set, otherwise a round-trip
+ * loses content.
+ *
+ * PROVENANCE / KEEP IN SYNC: this file is a VENDORED MIRROR of the canonical
+ * Docmost document schema in `@docmost/editor-ext`. The node/mark/attribute
+ * surface MUST be kept in sync with editor-ext — anything present there but
+ * missing here is silently dropped on a round-trip (data loss). The exported
+ * `docmostExtensions` surface is guarded by `test/schema-surface-snapshot.test.ts`,
+ * which fails loudly on any drift; when it does, re-verify parity against
+ * `@docmost/editor-ext` before updating the snapshot.
+ */
+import StarterKit from "@tiptap/starter-kit";
+import Image from "@tiptap/extension-image";
+import TaskList from "@tiptap/extension-task-list";
+import TaskItem from "@tiptap/extension-task-item";
+import Highlight from "@tiptap/extension-highlight";
+import Subscript from "@tiptap/extension-subscript";
+import Superscript from "@tiptap/extension-superscript";
+import { Node, Extension, Mark } from "@tiptap/core";
+
+// Inlined from @tiptap/core's getStyleProperty (added after 3.20.x) so this
+// package can stay on the same @tiptap/core version as the editor and avoid a
+// duplicate-tiptap version split in the monorepo. Reads a single declaration
+// from an element's inline `style` attribute, last-wins, case-insensitive.
+function getStyleProperty(element: HTMLElement, propertyName: string): string | null {
+  const styleAttr = element.getAttribute("style");
+  if (!styleAttr) {
+    return null;
+  }
+  const decls = styleAttr.split(";").map((decl) => decl.trim()).filter(Boolean);
+  const target = propertyName.toLowerCase();
+  for (let i = decls.length - 1; i >= 0; i -= 1) {
+    const decl = decls[i];
+    const colonIndex = decl.indexOf(":");
+    if (colonIndex === -1) {
+      continue;
+    }
+    const prop = decl.slice(0, colonIndex).trim().toLowerCase();
+    if (prop === target) {
+      return decl.slice(colonIndex + 1).trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Allowed Docmost callout types; anything else falls back to "info".
+ *
+ * This MUST stay in lockstep with the editor's canonical set
+ * (`getValidCalloutType` in `@docmost/editor-ext` callout/utils.ts:
+ * default | info | note | success | warning | danger). A type missing here is
+ * silently flattened to "info" on the markdown -> ProseMirror round-trip, so a
+ * `[!note]` / `[!default]` callout authored in the editor would come back as
+ * `[!info]` after a git sync (the QA "callout type -> [!info]" fidelity loss).
+ * `note` and `default` were previously absent and so were being flattened.
+ *
+ * The editor SCHEMA genuinely only supports these six banner types — there is no
+ * `tip`/`caution`/`important`/`question` callout node. So those are NOT first-
+ * class types we can round-trip literally; they are INPUT ALIASES (GitHub/Obsidian
+ * alert syntax). The editor's own paste/import path maps them onto the supported
+ * set (see `GITHUB_ALERT_TYPE_MAP` in
+ * `@docmost/editor-ext` markdown/utils/github-callout.marked.ts:
+ * tip -> success, caution -> danger, important -> info). We mirror that aliasing
+ * here so an ingested `> [!tip]` / `> [!caution]` lands on the closest real banner
+ * (success / danger) instead of flatly collapsing to `info` — matching exactly how
+ * the editor itself would interpret the same alias. A schema type always maps to
+ * itself first (idempotent round-trip); the alias map only rewrites NON-schema
+ * names; anything still unknown falls back to `info`.
+ */
+const CALLOUT_TYPES = ["default", "info", "note", "success", "warning", "danger"];
+/**
+ * NON-schema callout aliases -> their closest supported banner. Mirrors the
+ * editor's `GITHUB_ALERT_TYPE_MAP` for the names that are NOT already schema
+ * types (a schema type is preserved as-is and never consulted here). Keeping
+ * these in lockstep means git-sync ingest and an editor paste interpret the same
+ * `> [!alias]` identically.
+ */
+const CALLOUT_TYPE_ALIASES: Record<string, string> = {
+  tip: "success",
+  caution: "danger",
+  important: "info",
+};
+export const clampCalloutType = (value: string | null | undefined): string => {
+  if (!value) return "info";
+  const lower = value.toLowerCase();
+  // A real schema type round-trips to itself (idempotent).
+  if (CALLOUT_TYPES.includes(lower)) return lower;
+  // A known GitHub/Obsidian alias maps to the editor's closest banner.
+  if (CALLOUT_TYPE_ALIASES[lower]) return CALLOUT_TYPE_ALIASES[lower];
+  // Anything else is collapsed to the safe default (matches the editor).
+  return "info";
+};
+
+/**
+ * Allowlist guard for CSS color values imported from HTML.
+ *
+ * Docmost interpolates stored mark colors straight into an inline style
+ * attribute (e.g. style="background-color: ${color}" / "color: ${color}").
+ * An unsanitized value such as `red; --x: url(...)` or `red"><script>` would
+ * let a crafted document break out of the style attribute. We therefore only
+ * accept a narrow, well-formed subset of CSS <color> syntax and reject (-> null)
+ * anything else.
+ *
+ * Accepted forms:
+ *   - named colors:           letters only, e.g. "red", "rebeccapurple"
+ *   - hex:                    #rgb, #rgba, #rrggbb, #rrggbbaa
+ *   - functional notation:    rgb()/rgba()/hsl()/hsla() containing only
+ *                             digits, %, ., commas, spaces and slashes
+ */
+const SAFE_COLOR_RE =
+  /^(?:[a-zA-Z]+|#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgb|rgba|hsl|hsla)\([0-9.,%/\s]+\))$/;
+export const sanitizeCssColor = (
+  value: string | null | undefined,
+): string | null => {
+  if (typeof value !== "string") return null;
+  const color = value.trim();
+  return color && SAFE_COLOR_RE.test(color) ? color : null;
+};
+
+/** Docmost callout (info/warning/danger/success banner). */
+const Callout = Node.create({
+  name: "callout",
+  group: "block",
+  content: "block+",
+  defining: true,
+  addAttributes() {
+    return {
+      // Read the type from data-callout-type so generateJSON(html) preserves
+      // it; without an explicit parseHTML every imported callout became "info".
+      type: {
+        default: "info",
+        parseHTML: (el: HTMLElement) =>
+          clampCalloutType(el.getAttribute("data-callout-type")),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-callout-type": clampCalloutType(attrs.type),
+        }),
+      },
+      icon: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-icon"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.icon ? { "data-icon": attrs.icon } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="callout"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "callout", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Minimal table family: enough for schema round-trips and HTML parsing. */
+const Table = Node.create({
+  name: "table",
+  group: "block",
+  content: "tableRow+",
+  isolating: true,
+  parseHTML() {
+    return [{ tag: "table" }];
+  },
+  renderHTML() {
+    return ["table", ["tbody", 0]];
+  },
+});
+
+const TableRow = Node.create({
+  name: "tableRow",
+  content: "(tableCell | tableHeader)*",
+  parseHTML() {
+    return [{ tag: "tr" }];
+  },
+  renderHTML() {
+    return ["tr", 0];
+  },
+});
+
+const cellAttributes = () => ({
+  colspan: { default: 1 },
+  rowspan: { default: 1 },
+  colwidth: { default: null },
+  backgroundColor: { default: null },
+  backgroundColorName: { default: null },
+  // Column alignment so GFM aligned tables (|:--|:-:|--:|) round-trip.
+  align: {
+    default: null,
+    parseHTML: (el: HTMLElement) =>
+      el.getAttribute("align") || el.style.textAlign || null,
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.align ? { align: attrs.align } : {},
+  },
+});
+
+const TableCell = Node.create({
+  name: "tableCell",
+  content: "block+",
+  isolating: true,
+  addAttributes: cellAttributes,
+  parseHTML() {
+    return [{ tag: "td" }];
+  },
+  renderHTML() {
+    return ["td", 0];
+  },
+});
+
+const TableHeader = Node.create({
+  name: "tableHeader",
+  content: "block+",
+  isolating: true,
+  addAttributes: cellAttributes,
+  parseHTML() {
+    return [{ tag: "th" }];
+  },
+  renderHTML() {
+    return ["th", 0];
+  },
+});
+
+/**
+ * Attributes Docmost stores on standard nodes that the stock extensions
+ * do not declare. Without these, Node.fromJSON silently drops them —
+ * including the block ids that heading anchors rely on.
+ */
+const DocmostAttributes = Extension.create({
+  name: "docmostAttributes",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["heading", "paragraph"],
+        attributes: {
+          id: { default: null },
+          indent: { default: null },
+          // textAlign must round-trip the exported `<p style="text-align:…">`
+          // (and the legacy `<... align="…">`) form (review #10). Without an
+          // explicit parseHTML the default reads a bare `textAlign` attribute
+          // (never present), so alignment was silently dropped on every import.
+          textAlign: {
+            default: null,
+            parseHTML: (el: HTMLElement) =>
+              el.style?.textAlign || el.getAttribute("align") || null,
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.textAlign
+                ? { style: `text-align: ${attrs.textAlign}` }
+                : {},
+          },
+        },
+      },
+      {
+        types: ["image"],
+        attributes: {
+          align: { default: null },
+          // imageToHtml emits these Docmost-specific image attrs as data-*; map
+          // them back explicitly so a top-level image (or one inside a column)
+          // round-trips them. Without a parseHTML the default reads the bare
+          // attribute name (e.g. getAttribute("attachmentId") -> null) and the
+          // value — including the attachmentId that links the image to its
+          // stored file — is silently dropped on every round-trip (data loss).
+          attachmentId: {
+            default: null,
+            parseHTML: (el: HTMLElement) =>
+              el.getAttribute("data-attachment-id"),
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.attachmentId
+                ? { "data-attachment-id": attrs.attachmentId }
+                : {},
+          },
+          aspectRatio: {
+            default: null,
+            parseHTML: (el: HTMLElement) =>
+              el.getAttribute("data-aspect-ratio"),
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.aspectRatio != null
+                ? { "data-aspect-ratio": attrs.aspectRatio }
+                : {},
+          },
+          // Plain-text image caption (issue #221). editor-ext's image node
+          // serializes it as `data-caption` on the <img>; mirror that mapping so
+          // a captioned image survives the markdown <-> ProseMirror round-trip.
+          // Emit data-caption only when set, so caption-less images stay clean.
+          caption: {
+            default: null,
+            parseHTML: (el: HTMLElement) =>
+              el.getAttribute("data-caption") || null,
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.caption ? { "data-caption": attrs.caption } : {},
+          },
+          height: { default: null },
+          placeholder: { default: null },
+          size: {
+            default: null,
+            parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.size != null ? { "data-size": attrs.size } : {},
+          },
+          width: { default: null },
+        },
+      },
+      {
+        types: ["orderedList"],
+        attributes: { type: { default: null } },
+      },
+      {
+        types: ["link"],
+        attributes: { internal: { default: null }, title: { default: null } },
+      },
+    ];
+  },
+});
+
+/**
+ * Docmost inline comment mark. Anchors a comment thread to a text range via
+ * `commentId`. Without it, any document containing comment highlights fails to
+ * round-trip through the schema ("There is no mark type comment in this schema"),
+ * which breaks update_page_json and edit_page_text on every commented page.
+ * Mirrors Docmost's @docmost/editor-ext comment mark (commentId / resolved).
+ */
+const Comment = Mark.create({
+  name: "comment",
+  exitable: true,
+  inclusive: false,
+  addAttributes() {
+    return {
+      commentId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-comment-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.commentId ? { "data-comment-id": attrs.commentId } : {},
+      },
+      resolved: {
+        default: false,
+        parseHTML: (el: HTMLElement) =>
+          el.getAttribute("data-resolved") === "true",
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.resolved ? { "data-resolved": "true" } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "span[data-comment-id]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { class: "comment-mark", ...HTMLAttributes }, 0];
+  },
+});
+
+/**
+ * Inline spoiler mark (issue #259). Mirrors the @docmost/editor-ext `spoiler`
+ * mark so a document carrying a spoiler survives the git-sync round-trip.
+ * Markdown has no native spoiler syntax, so the markdown-converter emits it as
+ * raw inline HTML (`<span data-spoiler="true">…</span>`); without this mark the
+ * span re-parses as plain text and the spoiler is silently dropped on import.
+ * It parses span[data-spoiler] and re-renders the same span[data-spoiler][class].
+ */
+const Spoiler = Mark.create({
+  name: "spoiler",
+  inclusive: false,
+  parseHTML() {
+    return [{ tag: "span[data-spoiler]" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-spoiler": "true", class: "spoiler", ...HTMLAttributes }, 0];
+  },
+});
+
+/**
+ * Text color mark. The markdown-converter emits colored text as
+ * <span style="color: ...">, but with no mark parsing it back the color was
+ * silently dropped on import. This mirrors TipTap's @tiptap/extension-text-style
+ * `textStyle` mark (the name Docmost expects) and carries a single `color`
+ * attribute. The parsed color is passed through the allowlist guard so a crafted
+ * style cannot break out of the attribute when Docmost re-renders it.
+ */
+const TextStyle = Mark.create({
+  name: "textStyle",
+  addAttributes() {
+    return {
+      color: {
+        default: null,
+        parseHTML: (el: HTMLElement) =>
+          sanitizeCssColor(
+            el.style.color || el.getAttribute("data-color"),
+          ),
+        renderHTML: (attrs: Record<string, any>) => {
+          const color = sanitizeCssColor(attrs.color);
+          return color ? { style: `color: ${color}` } : {};
+        },
+      },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "span",
+        // Only claim a plain colored span. Do NOT match spans that are already a
+        // comment mark (data-comment-id) or a mention node (data-type=mention),
+        // otherwise importing such HTML would silently drop the comment/mention.
+        getAttrs: (el: HTMLElement) =>
+          el.style.color &&
+          !el.getAttribute("data-comment-id") &&
+          el.getAttribute("data-type") !== "mention"
+            ? {}
+            : false,
+      },
+    ];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", HTMLAttributes, 0];
+  },
+});
+
+/**
+ * Passthrough definitions for the remaining Docmost-specific nodes.
+ *
+ * TiptapTransformer.toYdoc (the write path every mutation uses) throws
+ * "Unknown node type: X" for any node not registered here, so editing ANY
+ * page that contains one of these nodes used to fail outright. The read path
+ * (fromYdoc) accepts them, which is why they appear in real documents.
+ *
+ * Each node below mirrors the real @docmost/editor-ext definition's name,
+ * group, content, inline/atom flags and attribute keys (with the same data-*
+ * HTML mapping) so that a fromYdoc -> transform -> toYdoc round-trip both
+ * validates and preserves attributes faithfully. Interactive concerns
+ * (node views, commands, keyboard shortcuts, input rules, suggestion plugins)
+ * are intentionally omitted: the MCP server never renders these nodes, it only
+ * needs the schema to accept and carry them. The Callout node above is the
+ * pattern these follow.
+ */
+
+/** Docmost @mention (user/page reference). Inline atom. */
+const Mention = Node.create({
+  name: "mention",
+  group: "inline",
+  inline: true,
+  selectable: true,
+  atom: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.id ? { "data-id": attrs.id } : {},
+      },
+      label: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-label"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.label ? { "data-label": attrs.label } : {},
+      },
+      entityType: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-type"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.entityType ? { "data-entity-type": attrs.entityType } : {},
+      },
+      entityId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.entityId ? { "data-entity-id": attrs.entityId } : {},
+      },
+      slugId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-slug-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.slugId ? { "data-slug-id": attrs.slugId } : {},
+      },
+      creatorId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-creator-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.creatorId ? { "data-creator-id": attrs.creatorId } : {},
+      },
+      anchorId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-anchor-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.anchorId ? { "data-anchor-id": attrs.anchorId } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-type="mention"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["span", { "data-type": "mention", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Inline KaTeX expression. Carries the LaTeX source in `text`. */
+const MathInline = Node.create({
+  name: "mathInline",
+  group: "inline",
+  inline: true,
+  atom: true,
+  addAttributes() {
+    return {
+      text: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-type="mathInline"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "span",
+      { "data-type": "mathInline", "data-katex": "true" },
+      `${HTMLAttributes.text ?? ""}`,
+    ];
+  },
+});
+
+/** Block KaTeX expression. Carries the LaTeX source in `text`. */
+const MathBlock = Node.create({
+  name: "mathBlock",
+  group: "block",
+  atom: true,
+  isolating: true,
+  addAttributes() {
+    return {
+      text: { default: "" },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="mathBlock"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      { "data-type": "mathBlock", "data-katex": "true" },
+      `${HTMLAttributes.text ?? ""}`,
+    ];
+  },
+});
+
+/** Collapsible <details> wrapper: summary + content children. */
+const Details = Node.create({
+  name: "details",
+  group: "block",
+  content: "detailsSummary detailsContent",
+  defining: true,
+  isolating: true,
+  addAttributes() {
+    return {
+      open: {
+        default: false,
+        parseHTML: (el: HTMLElement) => el.hasAttribute("open"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.open ? { open: "" } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "details" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["details", { ...HTMLAttributes }, 0];
+  },
+});
+
+/** Clickable summary line of a <details> block. */
+const DetailsSummary = Node.create({
+  name: "detailsSummary",
+  group: "block",
+  content: "inline*",
+  defining: true,
+  isolating: true,
+  selectable: false,
+  parseHTML() {
+    return [{ tag: "summary" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["summary", { "data-type": "detailsSummary", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Body of a <details> block. Permissive content so fromYdoc output validates. */
+const DetailsContent = Node.create({
+  name: "detailsContent",
+  group: "block",
+  // Docmost declares block* (an empty details body is valid); block+ would
+  // reject a collapsed/empty details on round-trip.
+  content: "block*",
+  defining: true,
+  selectable: false,
+  parseHTML() {
+    return [{ tag: 'div[data-type="detailsContent"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "detailsContent", ...HTMLAttributes }, 0];
+  },
+});
+
+/** File attachment card (non-image upload). Block atom. */
+const Attachment = Node.create({
+  name: "attachment",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      url: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-url"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-attachment-url": attrs.url ?? "",
+        }),
+      },
+      name: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-name"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.name ? { "data-attachment-name": attrs.name } : {},
+      },
+      mime: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-mime"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.mime ? { "data-attachment-mime": attrs.mime } : {},
+      },
+      size: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-size"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.size != null ? { "data-attachment-size": attrs.size } : {},
+      },
+      attachmentId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.attachmentId
+            ? { "data-attachment-id": attrs.attachmentId }
+            : {},
+      },
+      // Docmost declares `placeholder` (a transient upload key, not rendered
+      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
+      placeholder: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="attachment"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "attachment", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Uploaded <video> player. Block atom. */
+const Video = Node.create({
+  name: "video",
+  group: "block",
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      src: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
+        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
+      },
+      alt: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("aria-label"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.alt ? { "aria-label": attrs.alt } : {},
+      },
+      attachmentId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.attachmentId
+            ? { "data-attachment-id": attrs.attachmentId }
+            : {},
+      },
+      width: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.width != null ? { width: attrs.width } : {},
+      },
+      height: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.height != null ? { height: attrs.height } : {},
+      },
+      size: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.size != null ? { "data-size": attrs.size } : {},
+      },
+      align: {
+        default: "center",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.align ? { "data-align": attrs.align } : {},
+      },
+      aspectRatio: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.aspectRatio != null
+            ? { "data-aspect-ratio": attrs.aspectRatio }
+            : {},
+      },
+      // Docmost declares `placeholder` (a transient upload key, not rendered
+      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
+      placeholder: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "video" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["video", { controls: "true", ...HTMLAttributes }];
+  },
+});
+
+/**
+ * Defensive passthrough for a `youtube` node. Docmost itself has no dedicated
+ * youtube node (YouTube is handled via `embed`), but the converter read path
+ * references this type, so accept it as a generic block atom that preserves
+ * its src so legacy/external documents survive a round-trip.
+ */
+const Youtube = Node.create({
+  name: "youtube",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      src: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-src": attrs.src ?? "",
+        }),
+      },
+      width: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.width != null ? { "data-width": attrs.width } : {},
+      },
+      height: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.height != null ? { "data-height": attrs.height } : {},
+      },
+      align: {
+        default: "center",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.align ? { "data-align": attrs.align } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="youtube"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "youtube", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Generic embed (provider iframe). Block atom. */
+const Embed = Node.create({
+  name: "embed",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      src: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-src": attrs.src ?? "",
+        }),
+      },
+      provider: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-provider"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-provider": attrs.provider ?? "",
+        }),
+      },
+      align: {
+        default: "center",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-align": attrs.align ?? "center",
+        }),
+      },
+      width: {
+        default: 800,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-width": attrs.width,
+        }),
+      },
+      height: {
+        default: 600,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-height": attrs.height,
+        }),
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="embed"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "embed", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Shared attribute set for drawio/excalidraw diagram nodes. */
+const diagramAttributes = () => ({
+  src: {
+    default: "",
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
+    renderHTML: (attrs: Record<string, any>) => ({
+      "data-src": attrs.src ?? "",
+    }),
+  },
+  title: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-title"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.title ? { "data-title": attrs.title } : {},
+  },
+  alt: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-alt"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.alt ? { "data-alt": attrs.alt } : {},
+  },
+  width: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.width != null ? { "data-width": attrs.width } : {},
+  },
+  height: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.height != null ? { "data-height": attrs.height } : {},
+  },
+  size: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.size != null ? { "data-size": attrs.size } : {},
+  },
+  aspectRatio: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.aspectRatio != null
+        ? { "data-aspect-ratio": attrs.aspectRatio }
+        : {},
+  },
+  align: {
+    default: "center",
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.align ? { "data-align": attrs.align } : {},
+  },
+  attachmentId: {
+    default: null,
+    parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
+    renderHTML: (attrs: Record<string, any>) =>
+      attrs.attachmentId ? { "data-attachment-id": attrs.attachmentId } : {},
+  },
+});
+
+/** draw.io diagram. Block atom (image-backed). */
+const Drawio = Node.create({
+  name: "drawio",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes: diagramAttributes,
+  parseHTML() {
+    return [{ tag: 'div[data-type="drawio"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "drawio", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Excalidraw diagram. Block atom (image-backed). */
+const Excalidraw = Node.create({
+  name: "excalidraw",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes: diagramAttributes,
+  parseHTML() {
+    return [{ tag: 'div[data-type="excalidraw"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "excalidraw", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Multi-column layout container holding one or more `column` children. */
+const Columns = Node.create({
+  name: "columns",
+  group: "block",
+  content: "column+",
+  defining: true,
+  isolating: true,
+  addAttributes() {
+    return {
+      layout: {
+        default: "two_equal",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-layout"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.layout ? { "data-layout": attrs.layout } : {},
+      },
+      widthMode: {
+        default: "normal",
+        parseHTML: (el: HTMLElement) =>
+          el.getAttribute("data-width-mode") || "normal",
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.widthMode && attrs.widthMode !== "normal"
+            ? { "data-width-mode": attrs.widthMode }
+            : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="columns"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "columns", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Single column within a `columns` layout. */
+const Column = Node.create({
+  name: "column",
+  group: "block",
+  content: "block+",
+  defining: true,
+  isolating: true,
+  selectable: false,
+  addAttributes() {
+    return {
+      width: {
+        default: null,
+        parseHTML: (el: HTMLElement) => {
+          const value = el.getAttribute("data-width");
+          return value ? parseFloat(value) : null;
+        },
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.width ? { "data-width": attrs.width } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="column"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "column", ...HTMLAttributes }, 0];
+  },
+});
+
+/**
+ * Subpages listing block (auto-generated index of child pages). Docmost
+ * declares no attributes; the markdown-converter has a `case "subpages"`, so
+ * the read path can emit it and toYdoc must accept it. Block atom.
+ */
+const Subpages = Node.create({
+  name: "subpages",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      recursive: {
+        default: false,
+        parseHTML: (el: HTMLElement) =>
+          el.getAttribute("data-recursive") === "true",
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.recursive ? { "data-recursive": "true" } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="subpages"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "subpages", ...HTMLAttributes }];
+  },
+});
+
+/** Uploaded <audio> player. Block atom. Mirrors Docmost audio attrs. */
+const Audio = Node.create({
+  name: "audio",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      src: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
+        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
+      },
+      attachmentId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.attachmentId
+            ? { "data-attachment-id": attrs.attachmentId }
+            : {},
+      },
+      size: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.size != null ? { "data-size": attrs.size } : {},
+      },
+      // Transient upload key Docmost declares with rendered:false; carried so
+      // a round-trip never hits "Unsupported attribute".
+      placeholder: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: "audio" }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["audio", { controls: "true", ...HTMLAttributes }];
+  },
+});
+
+/** Embedded PDF viewer. Block atom. Mirrors Docmost pdf attrs. */
+const Pdf = Node.create({
+  name: "pdf",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      src: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
+        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
+      },
+      name: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-name"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.name ? { "data-name": attrs.name } : {},
+      },
+      attachmentId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.attachmentId
+            ? { "data-attachment-id": attrs.attachmentId }
+            : {},
+      },
+      size: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.size != null ? { "data-size": attrs.size } : {},
+      },
+      width: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.width != null ? { width: attrs.width } : {},
+      },
+      height: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.height != null ? { height: attrs.height } : {},
+      },
+      // Transient upload key Docmost declares with rendered:false; carried so
+      // a round-trip never hits "Unsupported attribute".
+      placeholder: { default: null },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="pdf"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "pdf", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Page break (print/export divider). Block atom; Docmost declares no attrs. */
+const PageBreak = Node.create({
+  name: "pageBreak",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  parseHTML() {
+    return [{ tag: 'div[data-type="pageBreak"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "pageBreak", ...HTMLAttributes }];
+  },
+});
+
+/**
+ * Footnote feature (mirror of @docmost/editor-ext footnote, matching the MCP
+ * schema mirror). 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. The
+ * <sup> parse rule uses priority 100 so it beats the Superscript mark's <sup>
+ * rule (otherwise an empty reference parses as an empty superscript and drops).
+ */
+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];
+  },
+});
+
+/**
+ * Encode/decode the htmlEmbed `source` (arbitrary HTML/CSS/JS) to/from base64
+ * for the `data-source` attribute. Ported from @docmost/editor-ext so the
+ * markdown-converter HTML path (generateJSON via parseHTML) round-trips the
+ * raw source losslessly and keeps it inert while it sits in the attribute.
+ * `encodeURIComponent`/`decodeURIComponent` wrap btoa/atob so UTF-8 survives.
+ */
+export function encodeHtmlEmbedSource(source: string): string {
+  if (!source) return "";
+  try {
+    if (typeof btoa === "function") {
+      return btoa(encodeURIComponent(source));
+    }
+    return Buffer.from(encodeURIComponent(source), "utf-8").toString("base64");
+  } catch {
+    return "";
+  }
+}
+
+export function decodeHtmlEmbedSource(encoded: string): string {
+  if (!encoded) return "";
+  try {
+    if (typeof atob === "function") {
+      return decodeURIComponent(atob(encoded));
+    }
+    return decodeURIComponent(Buffer.from(encoded, "base64").toString("utf-8"));
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Docmost raw HTML embed. Block atom; the client renders `source` inside a
+ * sandboxed iframe. Mirrors the @docmost/editor-ext node — `source` rides the
+ * `data-source` attribute base64-encoded (this is an HTML/generateJSON path, so
+ * it MUST use base64 to avoid double-encoding / injection).
+ */
+const HtmlEmbed = Node.create({
+  name: "htmlEmbed",
+  group: "block",
+  inline: false,
+  isolating: true,
+  atom: true,
+  defining: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      source: {
+        default: "",
+        parseHTML: (el: HTMLElement) =>
+          decodeHtmlEmbedSource(el.getAttribute("data-source") || ""),
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-source": encodeHtmlEmbedSource(attrs.source || ""),
+        }),
+      },
+      height: {
+        default: null,
+        parseHTML: (el: HTMLElement) => {
+          const v = el.getAttribute("data-height");
+          if (!v) return null;
+          const n = parseInt(v, 10);
+          return Number.isFinite(n) ? n : null;
+        },
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.height != null ? { "data-height": String(attrs.height) } : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="htmlEmbed"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "htmlEmbed", ...HTMLAttributes }];
+  },
+});
+
+/**
+ * Inline status pill. Mirrors @docmost/editor-ext status: the label rides in
+ * the element's TEXT content (not an attribute) and the color in data-color.
+ */
+const Status = Node.create({
+  name: "status",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      text: {
+        default: "",
+        parseHTML: (el: HTMLElement) => el.textContent || "",
+      },
+      color: {
+        default: "gray",
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-color") || "gray",
+        renderHTML: (attrs: Record<string, any>) => ({
+          "data-color": attrs.color ?? "gray",
+        }),
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'span[data-type="status"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "span",
+      { "data-type": "status", "data-color": HTMLAttributes["data-color"] },
+      `${HTMLAttributes.text ?? ""}`,
+    ];
+  },
+});
+
+/**
+ * Whole-page live embed. Holds only a `sourcePageId` reference. Mirrors
+ * @docmost/editor-ext pageEmbed. Block atom.
+ */
+const PageEmbed = Node.create({
+  name: "pageEmbed",
+  group: "block",
+  atom: true,
+  isolating: true,
+  selectable: true,
+  draggable: true,
+  addAttributes() {
+    return {
+      sourcePageId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-source-page-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.sourcePageId
+            ? { "data-source-page-id": attrs.sourcePageId }
+            : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="pageEmbed"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "pageEmbed", ...HTMLAttributes }];
+  },
+});
+
+/**
+ * Block node types allowed inside a `transclusionSource` (mirrors
+ * @docmost/editor-ext transclusion constants). Excludes transclusion nodes
+ * (no nesting) and child-only nodes.
+ */
+const TRANSCLUSION_SOURCE_CONTENT_EXPRESSION =
+  "(paragraph | heading | blockquote | codeBlock | horizontalRule | bulletList" +
+  " | orderedList | taskList | image | video | audio | attachment | callout" +
+  " | details | embed | mathBlock | table | drawio | excalidraw | pdf" +
+  " | subpages | columns | youtube)+";
+
+/** Sync-source block: editable content shared into transclusion references. */
+const TransclusionSource = Node.create({
+  name: "transclusionSource",
+  group: "block",
+  content: TRANSCLUSION_SOURCE_CONTENT_EXPRESSION,
+  defining: true,
+  isolating: true,
+  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-type="transclusionSource"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ["div", { "data-type": "transclusionSource", ...HTMLAttributes }, 0];
+  },
+});
+
+/** Live reference to a transcluded block/page. Block atom. */
+const TransclusionReference = Node.create({
+  name: "transclusionReference",
+  group: "block",
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      sourcePageId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-source-page-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.sourcePageId
+            ? { "data-source-page-id": attrs.sourcePageId }
+            : {},
+      },
+      transclusionId: {
+        default: null,
+        parseHTML: (el: HTMLElement) => el.getAttribute("data-transclusion-id"),
+        renderHTML: (attrs: Record<string, any>) =>
+          attrs.transclusionId
+            ? { "data-transclusion-id": attrs.transclusionId }
+            : {},
+      },
+    };
+  },
+  parseHTML() {
+    return [{ tag: 'div[data-type="transclusionReference"]' }];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      { "data-type": "transclusionReference", ...HTMLAttributes },
+    ];
+  },
+});
+
+/**
+ * Full extension list. Image is block-level (matches Docmost); the
+ * ProseMirror DOM parser hoists <img> found inside <p> automatically.
+ * StarterKit v3 already bundles the link extension, configured here.
+ */
+export const docmostExtensions = [
+  StarterKit.configure({
+    codeBlock: {},
+    heading: {},
+    link: { openOnClick: false },
+  }),
+  // Preserve image width/height as the AUTHORED string. Without an explicit
+  // parseHTML the stock Image node attribute falls back to tiptap core's
+  // `fromString`, which coerces a numeric width like "320" into the number 320
+  // — changing the stored type on every markdown round-trip (Docmost stores
+  // these as strings, e.g. "320" or "50%", matching how video/audio/pdf are
+  // handled in this mirror). The node attribute is applied AFTER the global
+  // DocmostAttributes one, so the fix must live on the Image node itself.
+  Image.extend({
+    addAttributes() {
+      const parent = (this.parent?.() ?? {}) as Record<string, any>;
+      return {
+        ...parent,
+        width: {
+          ...parent.width,
+          parseHTML: (el: HTMLElement) => el.getAttribute("width"),
+        },
+        height: {
+          ...parent.height,
+          parseHTML: (el: HTMLElement) => el.getAttribute("height"),
+        },
+      };
+    },
+  }).configure({ inline: false }),
+  TaskList,
+  TaskItem.configure({ nested: true }),
+  // Highlight stores its color unescaped and Docmost interpolates it into
+  // style="background-color: ${color}". Wrap the color attribute's parseHTML
+  // with the same allowlist guard used by textStyle so a crafted import color
+  // cannot break out of the style attribute. Multicolor behavior is preserved.
+  Highlight.extend({
+    addAttributes() {
+      const parent = this.parent?.() ?? {};
+      return {
+        ...parent,
+        color: {
+          ...(parent as Record<string, any>).color,
+          parseHTML: (el: HTMLElement) =>
+            sanitizeCssColor(
+              el.getAttribute("data-color") ||
+                getStyleProperty(el, "background-color") ||
+                el.style.backgroundColor,
+            ),
+        },
+      };
+    },
+  }).configure({ multicolor: true }),
+  Subscript,
+  Superscript,
+  // StarterKit does not provide a textStyle mark, so register ours; without it
+  // generateJSON drops <span style="color: ...">, defeating the color import.
+  TextStyle,
+  Comment,
+  Spoiler,
+  Callout,
+  Table,
+  TableRow,
+  TableCell,
+  TableHeader,
+  Mention,
+  MathInline,
+  MathBlock,
+  Details,
+  DetailsSummary,
+  DetailsContent,
+  Attachment,
+  Video,
+  Youtube,
+  Embed,
+  Drawio,
+  Excalidraw,
+  Columns,
+  Column,
+  Subpages,
+  Audio,
+  Pdf,
+  PageBreak,
+  FootnoteReference,
+  FootnotesList,
+  FootnoteDefinition,
+  HtmlEmbed,
+  Status,
+  PageEmbed,
+  TransclusionSource,
+  TransclusionReference,
+  DocmostAttributes,
+];
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
new file mode 100644
index 00000000..9e797a26
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -0,0 +1,26 @@
+/**
+ * Public surface of the pure converter (`lib/`). This barrel re-exports the
+ * PURE, IO-free pieces the sync engine needs: the self-contained markdown
+ * (de)serializers, the lossless ProseMirror <-> Markdown converter, the
+ * markdown -> ProseMirror import path, and semantic canonicalization for the
+ * round-trip idempotency check (SPEC §11).
+ *
+ * There is no REST client, websocket/collab write-path, auth-utils or page-lock
+ * here — the gitmost server writes natively.
+ */
+export {
+  serializeDocmostMarkdown,
+  parseDocmostMarkdown,
+  serializeDocmostMarkdownBody,
+} from "./markdown-document.js";
+export type { DocmostMdMeta } from "./markdown-document.js";
+
+export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
+
+export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
+
+export {
+  canonicalizeContent,
+  docsCanonicallyEqual,
+} from "./canonicalize.js";
+export { parsePageFile, serializePageFile } from "./page-file.js";
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
new file mode 100644
index 00000000..013a54f3
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -0,0 +1,1130 @@
+import { encodeHtmlEmbedSource } from "./docmost-schema.js";
+
+/**
+ * Hard cap on processNode recursion depth (see the depth guard below).
+ *
+ * Chosen well above any realistic document (the deepest legitimate nesting the
+ * editor can produce is far shallower) yet far below the point where the
+ * converter's own call stack overflows. The heaviest shape (deeply nested
+ * lists) costs ~5 JS frames per level and the runtime stack holds ~10k frames,
+ * so the measured overflow is around level ~650 (deeply nested lists); 400
+ * leaves a comfortable margin while still rendering pathological-but-bounded
+ * docs in full (the 200-level stress fixture reaches depth ~204).
+ */
+const MAX_NODE_DEPTH = 400;
+
+/**
+ * Convert ProseMirror/TipTap JSON content to Markdown
+ * Supports all Docmost-specific node types and extensions
+ */
+export function convertProseMirrorToMarkdown(content: any): string {
+  if (!content || !content.content) return "";
+
+  // Escape a value interpolated into an HTML double-quoted attribute value
+  // (textAlign, colors, image src, math `text`, all data-* attrs, etc.). In the
+  // ATTRIBUTE context only the quote that delimits the value and the ampersand
+  // that starts an entity are special, so we escape ONLY & " (and ' for safety
+  // when single-quoted delimiters are used). We deliberately do NOT escape < or
+  // >: the HTML re-parser (parse5/jsdom via @tiptap/html) does NOT decode
+  // &lt;/&gt; back inside attribute values, so escaping them would corrupt the
+  // stored data (e.g. a math node's LaTeX `a < b`) and ACCUMULATE escapes on
+  // every round-trip (`a < b` -> `a &lt; b` -> `a &amp;lt; b`). Escaping & "
+  // keeps the value inert against attribute-injection while staying idempotent.
+  // NOTE: escape ONLY & and " here. The value is always wrapped in double
+  // quotes, so " is the only delimiter; ' is NOT special in a double-quoted
+  // value, and parse5 does not decode &#39; back inside attribute values, so
+  // escaping ' would (like < >) corrupt the value and accumulate &amp; on every
+  // round-trip. Escaping & and " is idempotent (parse5 decodes them back).
+  const escapeAttr = (value: unknown): string =>
+    String(value)
+      .replace(/&/g, "&amp;")
+      .replace(/"/g, "&quot;");
+
+  // Escape a value placed as HTML element TEXT content (between tags), where
+  // <, >, and & are all significant. Used for text rendered inside raw-HTML
+  // blocks (table cells / columns) so stored characters cannot inject markup.
+  const escapeHtmlText = (value: unknown): string =>
+    String(value)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
+
+  // Percent-encode characters that would break out of a markdown URL target
+  // (...) — whitespace/newlines and parentheses — so a stored src stays a
+  // single inert token (used for image/video/youtube srcs).
+  const encodeMdUrl = (value: unknown): string =>
+    String(value || "")
+      .replace(/\s/g, (c: string) => (c === " " ? "%20" : encodeURIComponent(c)))
+      .replace(/\(/g, "%28")
+      .replace(/\)/g, "%29");
+
+  // Recursion depth guard. processNode is mutually recursive (directly and via
+  // processListItem/processTaskItem/blockToHtml), and a pathologically nested
+  // document (e.g. tens of thousands of nested blockquotes) would otherwise
+  // overflow the call stack and throw a RangeError, which would abort the sync
+  // and prevent the page from ever being written. We track the live nesting
+  // depth in a closure counter (the wrapper below) so we NEVER throw: past the
+  // limit we stop recursing and emit the node's own text (or nothing) instead.
+  // Normal documents never approach MAX_NODE_DEPTH, so their output is byte-
+  // identical. NOTE: the wrapper signature is (node) only — several callers use
+  // `.map(processNode)`, which would otherwise pass the array index as a second
+  // argument; the wrapper ignores extra arguments so that is harmless.
+  let nodeDepth = 0;
+
+  // A table cell whose content is NOT a single plain paragraph — a list, code
+  // block, blockquote, multiple paragraphs, etc. A GFM pipe cell can only hold
+  // inline content on one line, so such a cell must force the HTML <table> form
+  // or its structure is flattened/lost on round trip (review #8).
+  const cellIsMultiBlock = (cell: any): boolean => {
+    const blocks = cell.content || [];
+    if (blocks.length > 1) return true;
+    const only = blocks[0];
+    return only != null && only.type !== "paragraph";
+  };
+
+  // Render a whole table as raw HTML `<table>` (round-trips via the schema's
+  // table-family parseHTML). Used when a GFM pipe table would be wrong: merged
+  // cells (colspan/rowspan), multi-block cells (#8), OR the table sits inside a
+  // raw-HTML container like a column (marked does not parse markdown inside raw
+  // HTML, so a GFM pipe table there becomes literal "| a | b |" text — #7).
+  // `blockToHtml` is referenced lazily (defined below; only called at runtime).
+  const tableToHtml = (tableRows: any[]): string => {
+    const renderHtmlCell = (cell: any): string => {
+      const tag = cell.type === "tableHeader" ? "th" : "td";
+      const a = cell.attrs || {};
+      const cellParts: string[] = [];
+      if ((a.colspan ?? 1) > 1)
+        cellParts.push(`colspan="${escapeAttr(a.colspan)}"`);
+      if ((a.rowspan ?? 1) > 1)
+        cellParts.push(`rowspan="${escapeAttr(a.rowspan)}"`);
+      if (a.align) cellParts.push(`align="${escapeAttr(a.align)}"`);
+      const open = cellParts.length
+        ? `<${tag} ${cellParts.join(" ")}>`
+        : `<${tag}>`;
+      const inner = (cell.content || [])
+        .map((block: any) => blockToHtml(block))
+        .join("");
+      return `${open}${inner}</${tag}>`;
+    };
+    const htmlRows = tableRows
+      .map(
+        (row: any) =>
+          `<tr>${(row.content || []).map(renderHtmlCell).join("")}</tr>`,
+      )
+      .join("");
+    return `<table><tbody>${htmlRows}</tbody></table>`;
+  };
+
+  const processNode = (node: any): string => {
+    if (nodeDepth >= MAX_NODE_DEPTH) {
+      // Bail out of deeper recursion without throwing. A text node still has
+      // its own content worth keeping; a container at the limit collapses to
+      // "" (its already-too-deep subtree is dropped) rather than overflowing.
+      return typeof node?.text === "string" ? node.text : "";
+    }
+    nodeDepth++;
+    try {
+      return processNodeInner(node);
+    } finally {
+      nodeDepth--;
+    }
+  };
+
+  const processNodeInner = (node: any): string => {
+    const type = node.type;
+    const nodeContent = node.content || [];
+
+    switch (type) {
+      case "doc":
+        return nodeContent.map(processNode).join("\n\n");
+
+      case "paragraph":
+        const text = nodeContent.map(processNode).join("");
+        const align = node.attrs?.textAlign;
+        if (align && align !== "left") {
+          // Emit alignment as a styled `<p>` (review #10). The old
+          // `<div align="…">` had NO matching import parse rule — the div was
+          // unwrapped and alignment lost on every round trip. A styled `<p>`
+          // round-trips: the paragraph parse rule (tag:"p") matches and the
+          // textAlign global-attribute parseHTML (docmost-schema) reads the style.
+          return `<p style="text-align:${escapeAttr(align)}">${text}</p>`;
+        }
+        return text || "";
+
+      case "heading":
+        const level = node.attrs?.level || 1;
+        const headingText = nodeContent.map(processNode).join("");
+        const headingAlign = node.attrs?.textAlign;
+        if (headingAlign && headingAlign !== "left") {
+          // Emit alignment as a styled `<hN>` so it round-trips losslessly,
+          // symmetric to the paragraph case above (review F5/A1). The bare
+          // `## text` markdown form carries NO alignment, so an aligned heading
+          // would silently drop textAlign on export. A styled `<hN>` re-parses:
+          // the heading parse rule (tag:"h1".."h6") matches and the textAlign
+          // global-attribute parseHTML (docmost-schema) reads the style back,
+          // preserving BOTH level and textAlign. escapeAttr keeps the align
+          // value injection-safe, exactly like the paragraph arm.
+          return `<h${level} style="text-align:${escapeAttr(headingAlign)}">${headingText}</h${level}>`;
+        }
+        // No alignment (or the default "left"): keep the plain `## text`
+        // markdown form — HTML-ifying an unaligned heading would be needless
+        // churn, exactly as the paragraph case keeps plain text when unaligned.
+        return "#".repeat(level) + " " + headingText;
+
+      case "text":
+        let textContent = node.text || "";
+        // Apply marks (bold, italic, code, etc.)
+        if (node.marks) {
+          // The schema's `code` mark declares `excludes: "_"` — it excludes every
+          // other inline mark — so the editor can NEVER produce a text run that
+          // carries `code` together with another mark, and on import any
+          // co-occurring mark is always dropped (the run comes back as code-only).
+          // The lossless, byte-stable behavior is therefore: when a run has the
+          // `code` mark, emit ONLY the backtick code span and ignore every other
+          // mark, so md1 is already code-only and md2 === md1. Runs WITHOUT a code
+          // mark are rendered exactly as before.
+          const markTypes = node.marks.map((m: any) => m.type);
+          const hasCode = markTypes.includes("code");
+          if (hasCode) {
+            textContent = `\`${textContent}\``;
+            return textContent;
+          }
+          const codeCombined = false;
+          for (const mark of node.marks) {
+            switch (mark.type) {
+              case "bold":
+                textContent = codeCombined
+                  ? `<strong>${textContent}</strong>`
+                  : `**${textContent}**`;
+                break;
+              case "italic":
+                textContent = codeCombined
+                  ? `<em>${textContent}</em>`
+                  : `*${textContent}*`;
+                break;
+              case "code":
+                // When combined with another mark, wrap as <code> so the
+                // surrounding HTML marks can nest around it; otherwise use the
+                // plain backtick span.
+                textContent = codeCombined
+                  ? `<code>${textContent}</code>`
+                  : `\`${textContent}\``;
+                break;
+              case "link": {
+                const href = mark.attrs?.href || "";
+                const title = mark.attrs?.title;
+                if (codeCombined) {
+                  // Emit an HTML anchor so it can wrap the nested <code>.
+                  const safeHref = escapeAttr(href);
+                  if (title) {
+                    textContent = `<a href="${safeHref}" title="${escapeAttr(String(title))}">${textContent}</a>`;
+                  } else {
+                    textContent = `<a href="${safeHref}">${textContent}</a>`;
+                  }
+                } else if (title) {
+                  // Emit the optional markdown link title; escape an embedded
+                  // double-quote so it cannot terminate the title string early.
+                  const safeTitle = String(title).replace(/"/g, '\\"');
+                  textContent = `[${textContent}](${href} "${safeTitle}")`;
+                } else {
+                  textContent = `[${textContent}](${href})`;
+                }
+                break;
+              }
+              case "strike":
+                textContent = codeCombined
+                  ? `<s>${textContent}</s>`
+                  : `~~${textContent}~~`;
+                break;
+              case "underline":
+                textContent = `<u>${textContent}</u>`;
+                break;
+              case "subscript":
+                textContent = `<sub>${textContent}</sub>`;
+                break;
+              case "superscript":
+                textContent = `<sup>${textContent}</sup>`;
+                break;
+              case "highlight": {
+                // Preserve a null/empty color as a plain highlight (a bare
+                // <mark> with no background-color); only emit the style when a
+                // color is actually set, so a plain highlight is not forced to
+                // yellow on export.
+                const color = mark.attrs?.color;
+                textContent = color
+                  ? `<mark style="background-color: ${escapeAttr(color)}">${textContent}</mark>`
+                  : `<mark>${textContent}</mark>`;
+                break;
+              }
+              case "textStyle":
+                if (mark.attrs?.color) {
+                  textContent = `<span style="color: ${escapeAttr(mark.attrs.color)}">${textContent}</span>`;
+                }
+                break;
+              case "spoiler":
+                // Markdown has no native spoiler syntax, so emit the same raw
+                // inline HTML the editor-ext/MCP stack uses. The schema's Spoiler
+                // mark parses span[data-spoiler] back on import, so the mark
+                // survives the PM -> MD -> PM round-trip.
+                textContent = `<span data-spoiler="true">${textContent}</span>`;
+                break;
+              case "comment": {
+                // Emit the inline comment anchor so highlights round-trip. The
+                // schema's Comment mark parses span[data-comment-id] (attrs
+                // commentId/resolved).
+                const cid = mark.attrs?.commentId;
+                if (cid) {
+                  const resolvedAttr = mark.attrs?.resolved
+                    ? ` data-resolved="true"`
+                    : "";
+                  textContent = `<span data-comment-id="${escapeAttr(cid)}"${resolvedAttr}>${textContent}</span>`;
+                }
+                break;
+              }
+            }
+          }
+        }
+        return textContent;
+
+      case "codeBlock":
+        const language = node.attrs?.language || "";
+        // Strip ALL trailing newlines so the export is idempotent: marked
+        // re-adds exactly one trailing "\n" on import, so trimming only one
+        // here would let the text grow by "\n" on each round-trip. Removing
+        // every trailing newline makes repeated cycles stable.
+        const code = nodeContent
+          .map(processNode)
+          .join("")
+          .replace(/\n+$/, "");
+        // CommonMark: an inner ``` run inside the code would prematurely close
+        // a 3-backtick fence (corrupting the block on re-import). Use an outer
+        // fence one backtick longer than the longest backtick run in the code
+        // (minimum 3) so the inner fence is always content.
+        const longestBacktickRun = (code.match(/`+/g) || []).reduce(
+          (max: number, run: string) => Math.max(max, run.length),
+          0,
+        );
+        const fence = "`".repeat(Math.max(3, longestBacktickRun + 1));
+        return fence + language + "\n" + code + "\n" + fence;
+
+      case "bulletList":
+        return nodeContent
+          .map((item: any) => processListItem(item, "-"))
+          .join("\n");
+
+      case "orderedList":
+        return nodeContent
+          .map((item: any, index: number) =>
+            processListItem(item, `${index + 1}.`),
+          )
+          .join("\n");
+
+      case "taskList":
+        return nodeContent.map((item: any) => processTaskItem(item)).join("\n");
+
+      case "taskItem":
+        // Delegate to the same helper used by taskList so multi-block and
+        // nested task items render and indent consistently.
+        return processTaskItem(node);
+
+      case "listItem":
+        return nodeContent.map(processNode).join("\n");
+
+      case "blockquote":
+        // Prefix EVERY line of EVERY child with "> " and separate block-level
+        // children with a blank ">" line so code blocks / multi-paragraph
+        // quotes round-trip correctly.
+        return nodeContent
+          .map((n: any) =>
+            processNode(n)
+              .split("\n")
+              .map((line: string) => (line.length ? `> ${line}` : ">"))
+              .join("\n"),
+          )
+          .join("\n>\n");
+
+      case "horizontalRule":
+        return "---";
+
+      case "hardBreak":
+        // Two trailing spaces before the newline encode a markdown hard break;
+        // a bare "\n" would be reimported as a soft break and lost.
+        return "  \n";
+
+      case "image": {
+        const imgAttrs = node.attrs || {};
+        // A top-level image with layout/identity attrs beyond src/alt cannot be
+        // expressed by markdown `![](src)` — width/height/align/size/
+        // attachmentId/aspectRatio would be silently dropped on export and lost
+        // on re-import. Emit the SAME schema-matching <img> used inside columns
+        // (imageToHtml) so those attrs survive the round-trip. A bare image
+        // (only src/alt, optionally a title — which has no schema attr) keeps
+        // the lighter markdown form so existing image round-trip tests hold.
+        const hasLayoutAttrs =
+          imgAttrs.width != null ||
+          imgAttrs.height != null ||
+          imgAttrs.align ||
+          imgAttrs.size != null ||
+          imgAttrs.attachmentId ||
+          imgAttrs.aspectRatio != null ||
+          // A caption (issue #221) cannot be expressed by markdown `![](src)`,
+          // so route a captioned image through imageToHtml's raw <img> form
+          // (data-caption) — the same lossless form used for the other
+          // Docmost-specific image attrs.
+          imgAttrs.caption;
+        if (hasLayoutAttrs) {
+          return imageToHtml(node);
+        }
+        const imgAlt = imgAttrs.alt || "";
+        // Neutralize characters that could break out of the markdown image
+        // URL: spaces/newlines and parentheses would terminate the (...) target
+        // and let a stored src inject following markdown/HTML. Percent-encode
+        // them so the URL stays a single inert token.
+        const imgSrc = encodeMdUrl(imgAttrs.src);
+        // A bare image (only src/alt, optionally a title) has no caption, so the
+        // lighter markdown form is lossless here; captioned images took the
+        // imageToHtml branch above.
+        return `![${imgAlt}](${imgSrc})`;
+      }
+
+      case "video": {
+        // Emit the schema-matching <video> element so generateJSON rebuilds the
+        // node with its attrs intact. The schema's parseHTML reads src/aria-label
+        // from the standard attributes and the remaining attrs from data-*.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
+        if (attrs.alt) parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
+        if (attrs.attachmentId)
+          parts.push(
+            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
+          );
+        if (attrs.width != null)
+          parts.push(`width="${escapeAttr(attrs.width)}"`);
+        if (attrs.height != null)
+          parts.push(`height="${escapeAttr(attrs.height)}"`);
+        if (attrs.size != null)
+          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+        if (attrs.align)
+          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+        if (attrs.aspectRatio != null)
+          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
+        // Wrap in a block <div> so marked treats it as a block (a bare <video>
+        // is inline-level HTML and marked wraps it in <p>, leaving a spurious
+        // empty paragraph beside the hoisted block atom). The wrapper has no
+        // data-type, so the schema parser ignores it and just hoists the video.
+        return `<div><video ${parts.join(" ")}></video></div>`;
+      }
+
+      case "youtube": {
+        // Emit the schema-matching div[data-type="youtube"]; the schema reads
+        // src from data-src and width/height/align from data-* attributes.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="youtube"`,
+          `data-src="${escapeAttr(attrs.src ?? "")}"`,
+        ];
+        if (attrs.width != null)
+          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+        if (attrs.height != null)
+          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+        if (attrs.align)
+          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "table": {
+        // A GFM pipe table cannot represent merged cells. If ANY cell carries
+        // colspan>1 or rowspan>1, a pipe table would corrupt the grid on
+        // re-import, so emit the WHOLE table as raw HTML <table> instead: the
+        // schema's table family parseHTML (tag table/tr/td/th, with colspan/
+        // rowspan read from the same-named HTML attrs and align via parseHTML)
+        // round-trips it faithfully. Otherwise keep the lighter GFM pipe table.
+        const tableRows: any[] = nodeContent;
+        if (tableRows.length === 0) return "";
+        const hasSpan = tableRows.some((row: any) =>
+          (row.content || []).some(
+            (cell: any) =>
+              (cell.attrs?.colspan ?? 1) > 1 || (cell.attrs?.rowspan ?? 1) > 1,
+          ),
+        );
+        // A GFM pipe table also cannot hold a cell with block content (a list,
+        // code block, paragraphs) — it would be flattened to one line and lost
+        // (review #8). Force the HTML form for those too.
+        const hasMultiBlockCell = tableRows.some((row: any) =>
+          (row.content || []).some((cell: any) => cellIsMultiBlock(cell)),
+        );
+
+        if (hasSpan || hasMultiBlockCell) {
+          return tableToHtml(tableRows);
+        }
+
+        // No merged cells: emit a GFM table (header row + separator) so the
+        // markdown can be parsed back into a table on re-import.
+        const rows = tableRows.map(processNode);
+        const headerCells = tableRows[0]?.content || [];
+        const columns = headerCells.length || 1;
+        // Derive alignment markers (:--, :-:, --:) from each header cell.
+        const markers = Array.from({ length: columns }, (_, i) => {
+          const align = headerCells[i]?.attrs?.align;
+          switch (align) {
+            case "left":
+              return ":--";
+            case "center":
+              return ":-:";
+            case "right":
+              return "--:";
+            default:
+              return "---";
+          }
+        });
+        const separator = "| " + markers.join(" | ") + " |";
+        return [rows[0], separator, ...rows.slice(1)].join("\n");
+      }
+
+      case "tableRow":
+        return "| " + nodeContent.map(processNode).join(" | ") + " |";
+
+      case "tableCell":
+      case "tableHeader": {
+        // Join multiple block children with a space (not "") so adjacent blocks
+        // like a paragraph followed by a list don't collide into "line1- a".
+        // Then collapse newlines and escape pipes so a cell containing "|" or a
+        // line break cannot corrupt the surrounding GFM row.
+        return nodeContent
+          .map(processNode)
+          .join(" ")
+          .replace(/\r?\n/g, " ")
+          .replace(/\|/g, "\\|");
+      }
+
+      case "callout": {
+        // Obsidian-native callout: `> [!type]` opener + a blockquote (`>`-prefixed)
+        // body, so it renders as a callout in Obsidian. The importer parses both
+        // this and the legacy `:::type` fence (existing vaults). Each body line is
+        // blockquote-prefixed; a blank line becomes a bare `>` so the callout is
+        // not split.
+        const calloutType = (node.attrs?.type || "info").toLowerCase();
+        const calloutBody = nodeContent
+          .map(processNode)
+          .join("\n")
+          .split("\n")
+          .map((l: string) => (l.length ? `> ${l}` : ">"))
+          .join("\n");
+        return `> [!${calloutType}]\n${calloutBody}`;
+      }
+
+      case "details": {
+        // The `open` (collapsed/expanded) state lives on the details node, NOT on
+        // the summary, so emit the <details> wrapper HERE carrying it — otherwise
+        // the open state is dropped on a round trip. The schema's details node
+        // parses `open` back from the attribute.
+        const open = node.attrs?.open ? " open" : "";
+        return `<details${open}>\n${nodeContent.map(processNode).join("")}</details>`;
+      }
+
+      case "detailsSummary":
+        return `<summary>${nodeContent.map(processNode).join("")}</summary>\n\n`;
+
+      case "detailsContent":
+        return `${nodeContent.map(processNode).join("\n")}\n`;
+
+      case "mathInline": {
+        // The schema's `text` attribute has no parseHTML, so TipTap's default
+        // parser reads it from the `text` HTML attribute (NOT the element's text
+        // content). Emit span[data-type="mathInline"] carrying the LaTeX in a
+        // `text="..."` attribute so it round-trips. marked cannot parse $...$
+        // back, so the previous form was lossy.
+        const inlineMath = node.attrs?.text || "";
+        return `<span data-type="mathInline" data-katex="true" text="${escapeAttr(inlineMath)}"></span>`;
+      }
+
+      case "mathBlock": {
+        // Same as mathInline: the LaTeX must ride in the `text` HTML attribute
+        // for the schema's default parser to recover it.
+        const blockMath = node.attrs?.text || "";
+        return `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(blockMath)}"></div>`;
+      }
+
+      case "mention": {
+        // Emit span[data-type="mention"] with the schema's data-* attributes so
+        // generateJSON rebuilds the mention node instead of leaving "@label"
+        // plain text that cannot re-parse.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`data-type="mention"`];
+        if (attrs.id) parts.push(`data-id="${escapeAttr(attrs.id)}"`);
+        if (attrs.label)
+          parts.push(`data-label="${escapeAttr(attrs.label)}"`);
+        if (attrs.entityType)
+          parts.push(`data-entity-type="${escapeAttr(attrs.entityType)}"`);
+        if (attrs.entityId)
+          parts.push(`data-entity-id="${escapeAttr(attrs.entityId)}"`);
+        if (attrs.slugId)
+          parts.push(`data-slug-id="${escapeAttr(attrs.slugId)}"`);
+        if (attrs.creatorId)
+          parts.push(`data-creator-id="${escapeAttr(attrs.creatorId)}"`);
+        if (attrs.anchorId)
+          parts.push(`data-anchor-id="${escapeAttr(attrs.anchorId)}"`);
+        // Keep the label as visible text content too; the schema reads attrs
+        // from data-*, so the inner text is purely cosmetic and harmless.
+        const mentionLabel = attrs.label || attrs.id || "";
+        // The label is visible element TEXT content here (the data-* attrs above
+        // carry the real values), so escape it for the text context, not attrs.
+        return `<span ${parts.join(" ")}>@${escapeHtmlText(mentionLabel)}</span>`;
+      }
+
+      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
+        // schema-matching div[data-type="attachment"] with data-attachment-*
+        // attrs so the node round-trips instead of degrading to a markdown link.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="attachment"`,
+          `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
+        ];
+        if (attrs.name)
+          parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
+        if (attrs.mime)
+          parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
+        if (attrs.size != null)
+          parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
+        if (attrs.attachmentId)
+          parts.push(
+            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
+          );
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "drawio":
+      case "excalidraw": {
+        // Emit the schema-matching div[data-type=...] carrying the diagram's
+        // attrs as data-* (the schema's diagramAttributes reads src/title/alt/
+        // width/height/size/aspectRatio/align/attachmentId from data-*), so the
+        // diagram round-trips instead of degrading to a lossy placeholder.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="${type}"`,
+          `data-src="${escapeAttr(attrs.src ?? "")}"`,
+        ];
+        if (attrs.title != null)
+          parts.push(`data-title="${escapeAttr(attrs.title)}"`);
+        if (attrs.alt != null) parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
+        if (attrs.width != null)
+          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+        if (attrs.height != null)
+          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+        if (attrs.size != null)
+          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+        if (attrs.aspectRatio != null)
+          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
+        if (attrs.align)
+          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+        if (attrs.attachmentId)
+          parts.push(
+            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
+          );
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "embed": {
+        // Emit the schema-matching div[data-type="embed"]; the schema reads
+        // src/provider/align/width/height from data-* attributes so the node
+        // (and its provider iframe info) survives the round-trip.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="embed"`,
+          `data-src="${escapeAttr(attrs.src ?? "")}"`,
+          `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
+        ];
+        if (attrs.align)
+          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+        if (attrs.width != null)
+          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+        if (attrs.height != null)
+          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "audio": {
+        // Emit the schema-matching <audio> element (was emitting nothing). The
+        // schema reads src from src and attachmentId/size from data-*.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
+        if (attrs.attachmentId)
+          parts.push(
+            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
+          );
+        if (attrs.size != null)
+          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+        // Wrap in a block <div> for the same reason as video: a bare <audio> is
+        // inline-level HTML that marked would wrap in <p>.
+        return `<div><audio ${parts.join(" ")}></audio></div>`;
+      }
+
+      case "pdf": {
+        // Emit the schema-matching div[data-type="pdf"] (was emitting nothing).
+        // The schema reads src/width/height from standard attrs and name/
+        // attachmentId/size from data-*.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="pdf"`,
+          `src="${escapeAttr(attrs.src ?? "")}"`,
+        ];
+        if (attrs.name) parts.push(`data-name="${escapeAttr(attrs.name)}"`);
+        if (attrs.attachmentId)
+          parts.push(
+            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
+          );
+        if (attrs.size != null)
+          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+        if (attrs.width != null)
+          parts.push(`width="${escapeAttr(attrs.width)}"`);
+        if (attrs.height != null)
+          parts.push(`height="${escapeAttr(attrs.height)}"`);
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "columns": {
+        // Emit the schema-matching div[data-type="columns"] wrapper so the
+        // multi-column layout survives. Without a case the children were
+        // concatenated with no separator and the text merged. The schema reads
+        // layout from data-layout and widthMode from data-width-mode. The whole
+        // block is raw HTML, so render children via blockToHtml (NOT markdown,
+        // which marked would not re-parse inside a raw HTML block).
+        const attrs = node.attrs || {};
+        const parts: string[] = [`data-type="columns"`];
+        if (attrs.layout)
+          parts.push(`data-layout="${escapeAttr(attrs.layout)}"`);
+        if (attrs.widthMode && attrs.widthMode !== "normal")
+          parts.push(`data-width-mode="${escapeAttr(attrs.widthMode)}"`);
+        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
+        return `<div ${parts.join(" ")}>${inner}</div>`;
+      }
+
+      case "column": {
+        // Emit the schema-matching div[data-type="column"]; the schema reads the
+        // column width from data-width. Children are rendered as HTML so their
+        // formatting survives inside this raw HTML block.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`data-type="column"`];
+        if (attrs.width)
+          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
+        return `<div ${parts.join(" ")}>${inner}</div>`;
+      }
+
+      case "pageBreak":
+        // Emit the schema-matching div[data-type="pageBreak"] so marked passes
+        // it through as a block and generateJSON rebuilds the pageBreak atom.
+        // Without this case the node fell through to `default` and rendered ""
+        // (the divider silently disappeared and could not round-trip).
+        return `<div data-type="pageBreak"></div>`;
+
+      case "subpages": {
+        // Emit the schema-matching div[data-type="subpages"] so marked passes it
+        // through as a block and generateJSON rebuilds the subpages atom. The old
+        // `{{SUBPAGES}}` literal had no parseHTML inverse, so on import it stayed
+        // as plain text — the embed rendered as the literal "{{SUBPAGES}}" on the
+        // page after a round-trip (red-team: subpages round-trip data loss).
+        // `data-recursive` carries the recursive toggle so it round-trips too.
+        const recursive = node.attrs?.recursive ? ` data-recursive="true"` : "";
+        return `<div data-type="subpages"${recursive}></div>`;
+      }
+
+      case "status": {
+        // Inline status pill. The schema reads the label from the element's
+        // TEXT content and the color from data-color, so emit both; without a
+        // case this inline atom fell through to `default` and collapsed to "".
+        const attrs = node.attrs || {};
+        const statusColor = attrs.color || "gray";
+        return `<span data-type="status" data-color="${escapeAttr(statusColor)}">${escapeHtmlText(attrs.text ?? "")}</span>`;
+      }
+
+      case "htmlEmbed": {
+        // Block atom; the schema reads the raw source from a base64-encoded
+        // data-source attribute (and an optional fixed height from data-height).
+        // Encode with the shared helper so it decodes symmetrically on import.
+        const attrs = node.attrs || {};
+        const parts: string[] = [
+          `data-type="htmlEmbed"`,
+          `data-source="${escapeAttr(encodeHtmlEmbedSource(attrs.source ?? ""))}"`,
+        ];
+        if (attrs.height != null)
+          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "footnoteReference": {
+        // Inline atom marker. The schema reads its id from data-id on a
+        // sup[data-footnote-ref]; the visible number is derived, not stored.
+        const attrs = node.attrs || {};
+        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
+        return `<sup data-footnote-ref${idAttr}></sup>`;
+      }
+
+      case "footnotesList": {
+        // Bottom container of footnote definitions (section[data-footnotes]).
+        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
+        return `<section data-footnotes>${inner}</section>`;
+      }
+
+      case "footnoteDefinition": {
+        // One footnote note keyed by id (div[data-footnote-def]).
+        const attrs = node.attrs || {};
+        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
+        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
+        return `<div data-footnote-def${idAttr}>${inner}</div>`;
+      }
+
+      case "pageEmbed": {
+        // Whole-page live embed; the schema reads data-source-page-id.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`data-type="pageEmbed"`];
+        if (attrs.sourcePageId)
+          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "transclusionReference": {
+        // Live reference to a transcluded block/page. Block atom; the schema
+        // reads data-source-page-id and data-transclusion-id.
+        const attrs = node.attrs || {};
+        const parts: string[] = [`data-type="transclusionReference"`];
+        if (attrs.sourcePageId)
+          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
+        if (attrs.transclusionId)
+          parts.push(
+            `data-transclusion-id="${escapeAttr(attrs.transclusionId)}"`,
+          );
+        return `<div ${parts.join(" ")}></div>`;
+      }
+
+      case "transclusionSource": {
+        // Sync-source container; the schema reads data-id and re-parses its
+        // block children, so render them as schema-matching HTML.
+        const attrs = node.attrs || {};
+        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
+        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
+        return `<div data-type="transclusionSource"${idAttr}>${inner}</div>`;
+      }
+
+      default:
+        // Fallback: process children
+        return nodeContent.map(processNode).join("");
+    }
+  };
+
+  // Render inline content (text runs + their marks) to HTML. Used by the raw
+  // HTML fallbacks (spanned tables, columns) where marked will NOT re-parse
+  // markdown, so backtick/asterisk/bracket syntax would otherwise leak as
+  // literal characters. Each mark is mirrored to the HTML the schema's parseHTML
+  // accepts so it re-imports as the matching ProseMirror mark.
+  const inlineToHtml = (inlineNodes: any[]): string =>
+    (inlineNodes || [])
+      .map((n: any) => {
+        if (n.type === "hardBreak") return "<br>";
+        if (n.type !== "text") {
+          // Inline atoms (mention, mathInline) already emit schema HTML.
+          return processNode(n);
+        }
+        let t = escapeHtmlText(n.text || "");
+        for (const mark of n.marks || []) {
+          switch (mark.type) {
+            case "bold":
+              t = `<strong>${t}</strong>`;
+              break;
+            case "italic":
+              t = `<em>${t}</em>`;
+              break;
+            case "code":
+              t = `<code>${t}</code>`;
+              break;
+            case "strike":
+              t = `<s>${t}</s>`;
+              break;
+            case "underline":
+              t = `<u>${t}</u>`;
+              break;
+            case "subscript":
+              t = `<sub>${t}</sub>`;
+              break;
+            case "superscript":
+              t = `<sup>${t}</sup>`;
+              break;
+            case "link":
+              t = `<a href="${escapeAttr(mark.attrs?.href || "")}">${t}</a>`;
+              break;
+            case "highlight":
+              t = mark.attrs?.color
+                ? `<mark style="background-color: ${escapeAttr(mark.attrs.color)}">${t}</mark>`
+                : `<mark>${t}</mark>`;
+              break;
+            case "textStyle":
+              if (mark.attrs?.color)
+                t = `<span style="color: ${escapeAttr(mark.attrs.color)}">${t}</span>`;
+              break;
+            case "comment":
+              // Inline comment anchor inside a raw-HTML container (columns /
+              // spanned table cells), so commented text there also round-trips.
+              if (mark.attrs?.commentId) {
+                const r = mark.attrs?.resolved ? ` data-resolved="true"` : "";
+                t = `<span data-comment-id="${escapeAttr(mark.attrs.commentId)}"${r}>${t}</span>`;
+              }
+              break;
+          }
+        }
+        return t;
+      })
+      .join("");
+
+  // Emit the schema-matching <img> for an image node. Shared so the image is
+  // emitted as real HTML wherever a raw-HTML container needs it (inside a column
+  // or a spanned table cell), where markdown `![](...)` would NOT be re-parsed
+  // and would survive as literal text. The Image extension reads src/alt from
+  // the standard attributes; the Docmost extra attrs (width/height/align/size/
+  // attachmentId/aspectRatio) are global attributes read from same-named DOM
+  // attributes, so emit them by name.
+  const imageToHtml = (node: any): string => {
+    const attrs = node.attrs || {};
+    const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
+    if (attrs.alt) parts.push(`alt="${escapeAttr(attrs.alt)}"`);
+    if (attrs.title) parts.push(`title="${escapeAttr(attrs.title)}"`);
+    if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
+    if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
+    if (attrs.align) parts.push(`align="${escapeAttr(attrs.align)}"`);
+    if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+    if (attrs.attachmentId)
+      parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+    if (attrs.aspectRatio != null)
+      parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
+    // Plain-text caption (issue #221). Markdown `![](src)` cannot carry it, so
+    // emit it as data-caption; the schema's image `caption` attr parses it back.
+    if (attrs.caption) parts.push(`data-caption="${escapeAttr(attrs.caption)}"`);
+    return `<img ${parts.join(" ")}>`;
+  };
+
+  // Emit the schema-matching div[data-type="callout"] for a callout node. The
+  // schema reads the banner type from data-callout-type. Children are rendered
+  // as HTML so they survive inside a raw-HTML container.
+  const calloutToHtml = (node: any): string => {
+    const type = (node.attrs?.type || "info").toLowerCase();
+    const inner = (node.content || []).map(blockToHtml).join("");
+    return `<div data-type="callout" data-callout-type="${escapeAttr(type)}">${inner}</div>`;
+  };
+
+  // Emit a schema-matching <details> tree. The schema parses <details>,
+  // summary[data-type="detailsSummary"], and div[data-type="detailsContent"].
+  // The `open` (collapsed/expanded) state lives on the details node and the
+  // schema parses it back from the attribute, so emit it here too — mirroring
+  // the top-level `details` case — or a NESTED details (inside columns/cells)
+  // would silently drop `open:true` every round trip.
+  const detailsToHtml = (node: any): string => {
+    const open = node.attrs?.open ? " open" : "";
+    const inner = (node.content || []).map(blockToHtml).join("");
+    return `<details${open}>${inner}</details>`;
+  };
+  const detailsSummaryToHtml = (node: any): string =>
+    `<summary data-type="detailsSummary">${inlineToHtml(node.content || [])}</summary>`;
+  const detailsContentToHtml = (node: any): string => {
+    const inner = (node.content || []).map(blockToHtml).join("");
+    return `<div data-type="detailsContent">${inner}</div>`;
+  };
+
+  // Emit the schema-matching taskList/taskItem HTML. bridgeTaskLists (in
+  // collaboration.ts) recognizes ul[data-type="taskList"] with
+  // li[data-type="taskItem"][data-checked]; emitting that directly here keeps
+  // task lists inside columns/cells from degrading to literal "- [ ]" text.
+  const taskListToHtml = (node: any): string => {
+    const items = (node.content || [])
+      .map((it: any) => {
+        const checked = it.attrs?.checked ? "true" : "false";
+        return `<li data-type="taskItem" data-checked="${checked}">${blockChildrenToHtml(it)}</li>`;
+      })
+      .join("");
+    return `<ul data-type="taskList">${items}</ul>`;
+  };
+
+  // Render a block node to HTML for the raw-HTML containers (spanned tables,
+  // columns). marked does NOT re-parse markdown inside a raw-HTML block, so
+  // EVERY block type that can appear inside a column or a spanned cell must be
+  // emitted as schema-matching HTML here — never as markdown, or it would land
+  // as literal text on re-import. Nodes whose processNode case already produces
+  // schema-matching HTML (math/media/embed/attachment/nested columns/spanned
+  // table) are delegated to processNode; the markdown-emitting cases
+  // (image/blockquote/callout/details/hr/taskList) get explicit HTML here.
+  const blockToHtml = (block: any): string => {
+    const children = block.content || [];
+    switch (block.type) {
+      case "paragraph": {
+        // Carry textAlign here too (symmetric with the processNode paragraph
+        // case): a paragraph nested inside an HTML container (column/table/
+        // callout) would otherwise drop its alignment on the round trip.
+        const pAlign = block.attrs?.textAlign;
+        const pStyle =
+          pAlign && pAlign !== "left"
+            ? ` style="text-align:${escapeAttr(pAlign)}"`
+            : "";
+        return `<p${pStyle}>${inlineToHtml(children)}</p>`;
+      }
+      case "heading": {
+        // Same for a heading nested in an HTML container: emit the alignment as
+        // an inline style (symmetric with the processNode heading case) so it is
+        // not silently dropped. Clamp the level to a valid HTML heading tag.
+        const level = Math.min(6, Math.max(1, block.attrs?.level || 1));
+        const hAlign = block.attrs?.textAlign;
+        const hStyle =
+          hAlign && hAlign !== "left"
+            ? ` style="text-align:${escapeAttr(hAlign)}"`
+            : "";
+        return `<h${level}${hStyle}>${inlineToHtml(children)}</h${level}>`;
+      }
+      case "bulletList":
+        return `<ul>${children
+          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
+          .join("")}</ul>`;
+      case "orderedList":
+        return `<ol>${children
+          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
+          .join("")}</ol>`;
+      case "codeBlock": {
+        const lang = block.attrs?.language || "";
+        // The code itself is element TEXT content (between <code> tags), so it
+        // must escape < > & — NOT the attribute escaper. The language rides in
+        // a class ATTRIBUTE, so it uses escapeAttr.
+        const code = escapeHtmlText(
+          children
+            .map(processNode)
+            .join("")
+            .replace(/\n+$/, ""),
+        );
+        const cls = lang ? ` class="language-${escapeAttr(lang)}"` : "";
+        return `<pre><code${cls}>${code}</code></pre>`;
+      }
+      case "image":
+        return imageToHtml(block);
+      case "blockquote":
+        return `<blockquote>${children.map(blockToHtml).join("")}</blockquote>`;
+      case "horizontalRule":
+        return "<hr>";
+      case "callout":
+        return calloutToHtml(block);
+      case "details":
+        return detailsToHtml(block);
+      case "detailsSummary":
+        return detailsSummaryToHtml(block);
+      case "detailsContent":
+        return detailsContentToHtml(block);
+      case "taskList":
+        return taskListToHtml(block);
+      case "taskItem":
+        // A bare taskItem (outside a taskList) still needs a wrapping list so
+        // the schema parses it; wrap it in a single-item taskList.
+        return taskListToHtml({ content: [block] });
+      // A table nested in a raw-HTML block (e.g. inside a column) MUST be the
+      // HTML <table> form — a GFM pipe table here would not be re-parsed by
+      // marked and would round-trip as literal "| a | b |" text (review #7).
+      case "table":
+        return tableToHtml(block.content || []);
+      // columns/column, math, media, embed, attachment, mention, etc. already
+      // emit schema-matching HTML from processNode.
+      case "columns":
+      case "column":
+      case "mathBlock":
+      case "video":
+      case "audio":
+      case "pdf":
+      case "youtube":
+      case "embed":
+      case "attachment":
+      case "drawio":
+      case "excalidraw":
+      case "htmlEmbed":
+      case "footnotesList":
+      case "footnoteDefinition":
+      case "pageEmbed":
+      case "transclusionSource":
+      case "transclusionReference":
+        return processNode(block);
+      default:
+        // Any still-unhandled block type: NEVER fall back to markdown inside a
+        // raw-HTML block (it would become literal text). Wrap its rendered
+        // children in a <div> so their content is preserved; if it has no block
+        // children, render its inline content instead.
+        if (children.length && children.some((c: any) => c.type !== "text")) {
+          return `<div>${children.map(blockToHtml).join("")}</div>`;
+        }
+        return `<div>${inlineToHtml(children)}</div>`;
+    }
+  };
+
+  // Render the block children of a list item to HTML (a listItem holds block+
+  // content). Mirrors processListItem but for the HTML fallback path.
+  const blockChildrenToHtml = (item: any): string =>
+    (item.content || []).map((b: any) => blockToHtml(b)).join("");
+
+  // Indent the rendered children of a list item under a marker prefix.
+  // Each child block is a (possibly multi-line) string. The very first physical
+  // line of the first child carries the marker (e.g. "- " or "1. "); EVERY
+  // other line — the remaining lines of the first child AND all lines of every
+  // subsequent child (nested lists, code blocks, extra paragraphs) — is indented
+  // to align under the marker. Without indenting these continuation lines, the
+  // 2nd/3rd line of a nested child collapses to column 0 and escapes the list.
+  //
+  // The continuation indent MUST equal the LIST marker width, which is not the
+  // same as the visible prefix width:
+  //   - bullet "- "          -> 2 columns
+  //   - task   "- [ ] "      -> marker is still "- " (the "[ ] " is content), 2
+  //   - ordered "1. "/"10. " -> 3/4 columns, scaling with the number's digits
+  // CommonMark anchors nested content to the marker column, so an ordered item
+  // indented to only 2 columns would be re-parsed as a sibling/loose content on
+  // re-import. Callers therefore pass the exact indent width to use.
+  const indentItemChildren = (
+    childStrings: string[],
+    prefix: string,
+    indentWidth: number,
+  ): string => {
+    const indent = " ".repeat(indentWidth);
+    const lines: string[] = [];
+    childStrings.forEach((child, childIndex) => {
+      child.split("\n").forEach((line, lineIndex) => {
+        if (childIndex === 0 && lineIndex === 0) {
+          // First physical line of the first block gets the marker.
+          lines.push(`${prefix} ${line}`);
+        } else {
+          // Indent every continuation line by the marker width; keep blank
+          // lines blank rather than emitting trailing whitespace.
+          lines.push(line.length ? `${indent}${line}` : "");
+        }
+      });
+    });
+    return lines.join("\n");
+  };
+
+  const processListItem = (item: any, prefix: string): string => {
+    const itemContent = item.content || [];
+    const childStrings = itemContent.map(processNode);
+    if (childStrings.length === 0) return prefix;
+    // The rendered marker is `${prefix} ` (prefix + one space), so its width —
+    // and thus the continuation indent — is prefix.length + 1. This is correct
+    // for both bullet ("-" -> 2) and ordered ("1." -> 3, "10." -> 4) markers,
+    // since for those the visible prefix IS the list marker.
+    return indentItemChildren(childStrings, prefix, prefix.length + 1);
+  };
+
+  const processTaskItem = (item: any): string => {
+    const checked = item.attrs?.checked || false;
+    const checkbox = checked ? "[x]" : "[ ]";
+    const prefix = `- ${checkbox}`;
+    const itemContent = item.content || [];
+    const childStrings = itemContent.map(processNode);
+    // An empty task item still needs its checkbox marker; without this guard
+    // the indent below produces "" and the "- [ ]"/"- [x]" row disappears.
+    if (childStrings.length === 0) return prefix;
+    // The list marker for a task item is just "- " (2 columns); the "[ ] "/"[x] "
+    // checkbox is item content, NOT part of the marker. So the continuation
+    // indent is a fixed 2 — do NOT derive it from the wider prefix.length.
+    return indentItemChildren(childStrings, prefix, 2);
+  };
+
+  return processNode(content).trim();
+}
diff --git a/packages/prosemirror-markdown/src/lib/markdown-document.ts b/packages/prosemirror-markdown/src/lib/markdown-document.ts
new file mode 100644
index 00000000..8f4953ea
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/markdown-document.ts
@@ -0,0 +1,154 @@
+/**
+ * Self-contained Docmost-flavoured Markdown document (custom extensions).
+ *
+ * A single `.md` file that packages everything needed to losslessly round-trip
+ * a page through "download -> edit body -> re-upload":
+ *   - a leading `docmost:meta` block: a one-line JSON object with page identity;
+ *   - the Markdown body (carrying inline comment anchors and diagrams as HTML);
+ *   - a trailing `docmost:comments` block: a one-line JSON array of comment
+ *     threads.
+ *
+ * Both metadata blocks are HTML comments on purpose: `marked`/`generateJSON`
+ * drop HTML comments, so even if the WHOLE file were ever fed straight to the
+ * importer without first stripping the blocks, the metadata cannot leak into the
+ * document. (A fenced ```docmost-comments``` block would WRONGLY become a
+ * codeBlock node, so a fenced block is deliberately NOT used.)
+ *
+ * The delimiter literals may legitimately appear in the BODY too (e.g. a user
+ * re-pastes an exported `.md` into a page, or a page documents this very
+ * format). To stay robust, parsing treats only the FINAL, document-ending
+ * `docmost:comments` block as metadata: it is the last `<!-- docmost:comments`
+ * opener whose closing `-->` sits at the very end of the file. Any earlier
+ * literal occurrence is left in the body untouched.
+ *
+ * NOTE on comments: in this version the comment THREAD records are preserved in
+ * the file but are NOT pushed back to the server on import — only the inline
+ * comment marks (anchors) embedded in the body are restored. Managing comment
+ * records stays with the comment tools/UI.
+ */
+
+export interface DocmostMdMeta {
+  version: number;
+  pageId?: string;
+  slugId?: string;
+  title?: string;
+  spaceId?: string;
+  parentPageId?: string | null;
+}
+
+// Match the leading meta block (allow leading whitespace). Capture group 1 is
+// the JSON text between the markers.
+const META_RE = /^\s*<!--\s*docmost:meta\s*\n([\s\S]*?)\n-->/;
+// Match a `docmost:comments` opener. Used globally to scan for the LAST opener
+// rather than end-anchoring a single regex (which would mis-capture across a
+// literal opener that appears earlier in the body).
+const COMMENTS_OPEN_RE = /<!--[ \t]*docmost:comments[ \t]*\r?\n/g;
+
+/**
+ * Assemble the full self-contained markdown file: meta block, body, and the
+ * comments block. The meta block is always emitted; the comments block is always
+ * emitted too (with `[]` when there are no comments) so the format stays uniform
+ * and parsing stays simple.
+ */
+export function serializeDocmostMarkdown(
+  meta: DocmostMdMeta,
+  body: string,
+  comments: any[],
+): string {
+  const metaJson = JSON.stringify(meta);
+  const commentsJson = JSON.stringify(Array.isArray(comments) ? comments : []);
+  const trimmedBody = (body ?? "").trim();
+  return (
+    `<!-- docmost:meta\n${metaJson}\n-->\n\n` +
+    `${trimmedBody}\n\n` +
+    `<!-- docmost:comments\n${commentsJson}\n-->\n`
+  );
+}
+
+/**
+ * Split a self-contained file back into its parts. Tolerant: if the meta or
+ * comments block is missing (e.g. a hand-written plain-markdown file), the
+ * corresponding value is returned as `null` and the whole input is treated as
+ * the body. This never throws on a MISSING block; only a `JSON.parse` failure
+ * inside a block that IS present is surfaced as a thrown Error with a clear
+ * message. Robust to `\r\n` line endings.
+ */
+export function parseDocmostMarkdown(full: string): {
+  meta: DocmostMdMeta | null;
+  body: string;
+  comments: any[] | null;
+} {
+  // Normalize line endings so the anchored regexes work regardless of CRLF.
+  const normalized = (full ?? "").replace(/\r\n/g, "\n");
+
+  // Extract the leading meta block (start-anchored — already unambiguous).
+  let meta: DocmostMdMeta | null = null;
+  let metaEnd = 0;
+  const metaMatch = normalized.match(META_RE);
+  if (metaMatch) {
+    try {
+      meta = JSON.parse(metaMatch[1]);
+    } catch (e) {
+      throw new Error(
+        `Invalid docmost:meta JSON block: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+      );
+    }
+    // Body starts right after the matched meta block.
+    metaEnd = (metaMatch.index ?? 0) + metaMatch[0].length;
+  }
+
+  // Find the LAST `<!-- docmost:comments` opener; the real file-level block is
+  // the final one whose closing `-->` ends the document. Any earlier literal
+  // occurrence inside the body (e.g. a re-pasted export) is left in the body.
+  let lastOpenStart = -1;
+  let lastOpenEnd = -1;
+  let m: RegExpExecArray | null;
+  COMMENTS_OPEN_RE.lastIndex = 0;
+  while ((m = COMMENTS_OPEN_RE.exec(normalized)) !== null) {
+    lastOpenStart = m.index;
+    lastOpenEnd = m.index + m[0].length;
+  }
+
+  let comments: any[] | null = null;
+  let bodyEnd = normalized.length;
+  if (lastOpenStart !== -1) {
+    const rest = normalized.slice(lastOpenEnd);
+    const close = rest.match(/\r?\n-->[ \t]*\r?\n?\s*$/); // closer must end the doc
+    if (close) {
+      const jsonText = rest.slice(0, close.index);
+      try {
+        comments = JSON.parse(jsonText);
+      } catch (e) {
+        throw new Error(
+          `Invalid docmost:comments JSON block: ${
+            e instanceof Error ? e.message : String(e)
+          }`,
+        );
+      }
+      bodyEnd = lastOpenStart; // strip from the opener to end of document
+    }
+  }
+
+  const body = normalized.slice(metaEnd, bodyEnd).trim();
+  return { meta, body, comments };
+}
+
+/**
+ * Serialize a self-contained markdown file with the meta block + body ONLY —
+ * NO trailing `docmost:comments` block. The sync engine never touches
+ * `/comments` (SPEC §3): the synced file carries just page identity (meta) and
+ * the body, where comment threads survive only as inline `<span
+ * data-comment-id>` anchor marks inside the body.
+ *
+ * `parseDocmostMarkdown` already tolerates a missing comments block (it returns
+ * `comments: null` and treats the rest as body), so a file produced here
+ * round-trips cleanly through the parser.
+ */
+export function serializeDocmostMarkdownBody(
+  meta: DocmostMdMeta,
+  body: string,
+): string {
+  return `<!-- docmost:meta\n${JSON.stringify(meta)}\n-->\n\n${(body ?? "").trim()}\n`;
+}
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
new file mode 100644
index 00000000..4466edf4
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -0,0 +1,365 @@
+/**
+ * Pure markdown -> ProseMirror conversion.
+ *
+ * The converter path is `markdownToProseMirror` (marked -> HTML ->
+ * generateJSON) plus the two pre/post processors it needs (`preprocessCallouts`,
+ * `bridgeTaskLists`). The gitmost server writes the resulting page bodies
+ * natively through the collab gateway, so no websocket/Yjs write-path lives
+ * here.
+ */
+import { generateJSON } from "@tiptap/html";
+import { JSDOM } from "jsdom";
+import { marked } from "marked";
+import { docmostExtensions } from "./docmost-schema.js";
+
+// Setup DOM environment for Tiptap HTML parsing in Node.js
+const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
+global.window = dom.window as any;
+global.document = dom.window.document;
+// @ts-ignore
+global.Element = dom.window.Element;
+
+/**
+ * Hard ceiling above which we skip callout preprocessing entirely. The linear
+ * scanner below has no quadratic blow-up, but we still cap input defensively so
+ * a pathological multi-megabyte payload cannot tie up the event loop; in that
+ * case the markdown is passed through verbatim (callouts are simply not
+ * detected) rather than risking a slow scan.
+ */
+const MAX_CALLOUT_PREPROCESS_BYTES = 4 * 1024 * 1024; // 4 MB
+
+/** Matches an opening callout fence: `:::type` (type captured, lower-cased). */
+const CALLOUT_OPEN_RE = /^:::\s*(\w+)\s*$/;
+/** Matches a bare closing callout fence: `:::`. */
+const CALLOUT_CLOSE_RE = /^:::\s*$/;
+/**
+ * Matches an Obsidian-native callout opener: `> [!type]` (type captured). An
+ * optional title after the type is allowed but ignored (the Docmost callout
+ * schema has no title). The body is the following contiguous blockquote lines.
+ */
+const CALLOUT_BQ_OPEN_RE = /^>\s*\[!(\w+)\]/;
+/** Matches any blockquote continuation line (`>` … ). */
+const BLOCKQUOTE_LINE_RE = /^>/;
+/** Matches the start/end of a code fence (``` or ~~~), capturing the marker. */
+const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
+
+/**
+ * Pre-process Docmost-flavoured markdown: convert `:::type ... :::`
+ * callout blocks (the syntax our markdown export produces) into HTML
+ * divs that the callout extension parses. The inner content is rendered
+ * through marked as regular markdown.
+ *
+ * Implemented as a single linear pass over the lines (no quadratic regex
+ * rescan). It:
+ *   - tracks fenced code regions (```...``` and ~~~...~~~) and never treats a
+ *     `:::` line that lives inside a code fence as a callout delimiter, so a
+ *     callout body that itself contains a fenced code block with a `:::` line is
+ *     no longer corrupted;
+ *   - matches an opening `:::type` line with the next CLOSING `:::` at the SAME
+ *     nesting level, supporting NESTED callouts via a depth counter (an inner
+ *     `:::type` opens a deeper level and consumes a matching `:::`);
+ *   - emits the same `<div data-type="callout" data-callout-type="TYPE">` output
+ *     (inner rendered through marked) as the previous regex implementation.
+ */
+async function preprocessCallouts(markdown: string): Promise<string> {
+  // Defensive cap: skip preprocessing for pathologically large inputs.
+  if (markdown.length > MAX_CALLOUT_PREPROCESS_BYTES) {
+    return markdown;
+  }
+
+  // Recursively transform a slice of lines, converting top-level callouts in
+  // that slice into <div> blocks and rendering their inner content (which may
+  // itself contain nested callouts) through this same function.
+  const transform = async (lines: string[]): Promise<string> => {
+    const out: string[] = [];
+    let inCodeFence = false;
+    let codeFenceMarker = ""; // the exact run of backticks/tildes that opened it
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+
+      // Inside a code fence, only its matching closing fence is significant;
+      // everything else (including `:::` lines) is copied through verbatim.
+      if (inCodeFence) {
+        out.push(line);
+        const fence = line.match(CODE_FENCE_RE);
+        if (fence && fence[2].startsWith(codeFenceMarker[0]) &&
+            fence[2].length >= codeFenceMarker.length) {
+          inCodeFence = false;
+          codeFenceMarker = "";
+        }
+        i++;
+        continue;
+      }
+
+      // A code fence opening outside any callout body: enter code-fence mode.
+      const fenceOpen = line.match(CODE_FENCE_RE);
+      if (fenceOpen) {
+        inCodeFence = true;
+        codeFenceMarker = fenceOpen[2];
+        out.push(line);
+        i++;
+        continue;
+      }
+
+      // An opening callout fence: scan forward (with code-fence and nested
+      // callout awareness) for its matching closing `:::` at the same level.
+      const open = line.match(CALLOUT_OPEN_RE);
+      if (open) {
+        const type = open[1].toLowerCase();
+        const bodyLines: string[] = [];
+        let depth = 1;
+        let innerInCodeFence = false;
+        let innerCodeFenceMarker = "";
+        let j = i + 1;
+        for (; j < lines.length; j++) {
+          const bl = lines[j];
+          if (innerInCodeFence) {
+            const f = bl.match(CODE_FENCE_RE);
+            if (f && f[2].startsWith(innerCodeFenceMarker[0]) &&
+                f[2].length >= innerCodeFenceMarker.length) {
+              innerInCodeFence = false;
+              innerCodeFenceMarker = "";
+            }
+            bodyLines.push(bl);
+            continue;
+          }
+          const innerFence = bl.match(CODE_FENCE_RE);
+          if (innerFence) {
+            innerInCodeFence = true;
+            innerCodeFenceMarker = innerFence[2];
+            bodyLines.push(bl);
+            continue;
+          }
+          if (CALLOUT_OPEN_RE.test(bl)) {
+            depth++;
+            bodyLines.push(bl);
+            continue;
+          }
+          if (CALLOUT_CLOSE_RE.test(bl)) {
+            depth--;
+            if (depth === 0) break; // matching close for THIS callout
+            bodyLines.push(bl);
+            continue;
+          }
+          bodyLines.push(bl);
+        }
+
+        if (j < lines.length) {
+          // Found the matching closing fence: render the body (recursively, so
+          // nested callouts are handled) and emit the callout div.
+          const inner = await transform(bodyLines);
+          const renderedInner = await marked.parse(inner);
+          out.push(
+            `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
+          );
+          i = j + 1; // skip past the closing `:::`
+          continue;
+        }
+        // No matching close (unterminated callout): treat the opener as a
+        // literal line and continue, preserving the original text.
+        out.push(line);
+        i++;
+        continue;
+      }
+
+      // An Obsidian-native callout: `> [!type]` opener; the body is the following
+      // CONTIGUOUS blockquote (`>`-prefixed) lines. Strip ONE blockquote level and
+      // recurse so nested callouts (`> > [!type]`) are handled, then emit the same
+      // callout div the `:::` path produces. A normal blockquote (no `[!type]` on
+      // its first line) does not match and stays a blockquote.
+      const bqOpen = line.match(CALLOUT_BQ_OPEN_RE);
+      if (bqOpen) {
+        const type = bqOpen[1].toLowerCase();
+        const bodyLines: string[] = [];
+        let j = i + 1;
+        for (; j < lines.length; j++) {
+          if (!BLOCKQUOTE_LINE_RE.test(lines[j])) break;
+          bodyLines.push(lines[j].replace(/^>\s?/, ""));
+        }
+        const inner = await transform(bodyLines);
+        const renderedInner = await marked.parse(inner);
+        out.push(
+          `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
+        );
+        i = j;
+        continue;
+      }
+
+      out.push(line);
+      i++;
+    }
+
+    return out.join("\n");
+  };
+
+  return transform(markdown.split("\n"));
+}
+
+/**
+ * Bridge marked's checkbox lists to TipTap task lists.
+ *
+ * marked renders GitHub task list items (`- [x] done`) as a plain
+ * `<ul><li><p><input type="checkbox" checked> text</p></li></ul>` WITHOUT the
+ * markup TipTap's TaskList/TaskItem extensions parse. This rewrites such lists
+ * into the shape those extensions expect:
+ *   TaskList parseHTML matches `ul[data-type="taskList"]`,
+ *   TaskItem matches `li[data-type="taskItem"]`,
+ *   the checked state is read from `data-checked === "true"`.
+ *
+ * A list is only converted when it has at least one `<li>` and EVERY direct
+ * `<li>` contains a checkbox input. Both `<ul>` and `<ol>` are considered: a
+ * numbered checklist (`1. [x] a`, which marked renders as an `<ol>` of checkbox
+ * `<li>`s) would otherwise lose its task state. TipTap task lists are unordered,
+ * so a matching `<ol>` is emitted as `data-type="taskList"` exactly like a
+ * `<ul>`. Mixed or ordinary lists (including ordinary `<ol>` lists) are left
+ * untouched so they keep rendering as bullet/numbered lists. The marked `<p>`
+ * wrapper is kept inside the `<li>` because TaskItem content allows paragraphs.
+ */
+function bridgeTaskLists(html: string): string {
+  // Cheap early-out: if the markup contains no checkbox input at all there is
+  // nothing to bridge, so skip the expensive JSDOM parse entirely. This is the
+  // common case (most pages have no task lists).
+  if (!/type=["']?checkbox/i.test(html)) {
+    return html;
+  }
+  // Defensive cap (consistent with preprocessCallouts): skip the bridge for
+  // pathologically large inputs rather than running a second expensive JSDOM
+  // parse on a multi-megabyte payload. The markup is passed through verbatim.
+  if (html.length > MAX_CALLOUT_PREPROCESS_BYTES) {
+    return html;
+  }
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  // Collect the checkbox(es) that belong to THIS <li> directly: either direct
+  // child <input type="checkbox"> elements or ones inside the <li>'s direct <p>
+  // child (the shape marked emits: `<li><p><input type="checkbox"> text</p></li>`).
+  // Checkboxes nested deeper (e.g. inside a child <ul>/<ol>) are excluded so a
+  // bullet <li> that merely contains a nested task sublist is not misdetected.
+  // Raw inline HTML can put more than one checkbox in a single <li>; we gather
+  // ALL of them so none survive into the converted item.
+  const directCheckboxes = (li: Element): Element[] => {
+    const found: Element[] = [];
+    for (const child of Array.from(li.children)) {
+      if (
+        child.tagName === "INPUT" &&
+        child.getAttribute("type") === "checkbox"
+      ) {
+        found.push(child);
+        continue;
+      }
+      if (child.tagName === "P") {
+        for (const inp of Array.from(
+          child.querySelectorAll(":scope > input[type='checkbox']"),
+        )) {
+          found.push(inp);
+        }
+      }
+    }
+    return found;
+  };
+  // Both <ul> and <ol> are candidates: an <ol> whose every direct <li> carries
+  // its own checkbox is a numbered checklist that must also become a taskList.
+  const lists = Array.from(document.querySelectorAll("ul, ol"));
+  for (const list of lists) {
+    // Only consider DIRECT child <li> elements; nested lists are handled by
+    // their own iteration of the outer loop.
+    const items = Array.from(list.children).filter(
+      (child) => child.tagName === "LI",
+    );
+    if (items.length === 0) continue;
+    const itemCheckboxes = items.map((li) => directCheckboxes(li));
+    // Convert only when every direct <li> carries at least one OWN checkbox.
+    if (!itemCheckboxes.every((boxes) => boxes.length > 0)) continue;
+
+    // A numbered checklist arrives as an <ol>. We must NOT leave the tag as
+    // <ol> while tagging it data-type="taskList": generateJSON would then match
+    // BOTH the orderedList rule (tag ol) and the taskList rule (data-type),
+    // emitting a phantom empty orderedList beside the real taskList. So rename a
+    // qualifying <ol> to a <ul> — move its <li> children over and replace it —
+    // leaving only the taskList rule to match. Already-<ul> lists are unchanged.
+    let target: Element = list;
+    if (list.tagName === "OL") {
+      const ul = document.createElement("ul");
+      // Carry over existing attributes (e.g. class) so nothing is silently lost.
+      for (const attr of Array.from(list.attributes)) {
+        ul.setAttribute(attr.name, attr.value);
+      }
+      // Move every child node (including the <li>s we collected) into the <ul>.
+      while (list.firstChild) {
+        ul.appendChild(list.firstChild);
+      }
+      list.replaceWith(ul);
+      target = ul;
+    }
+
+    target.setAttribute("data-type", "taskList");
+    items.forEach((li, index) => {
+      const boxes = itemCheckboxes[index];
+      // The first checkbox determines the checked state (matches the previous
+      // single-checkbox behaviour); any extras only need removing.
+      const input = boxes[0] ?? null;
+      li.setAttribute("data-type", "taskItem");
+      const checked =
+        input != null &&
+        (input.hasAttribute("checked") || (input as any).checked);
+      li.setAttribute("data-checked", checked ? "true" : "false");
+      // Remove ALL direct checkbox inputs so none survive into the content
+      // (a raw-inline-HTML <li> may carry more than one).
+      for (const box of boxes) {
+        box.remove();
+      }
+    });
+  }
+  return document.body.innerHTML;
+}
+
+/**
+ * Recursively strip content-less paragraph nodes from a generated doc.
+ *
+ * A block-level atom whose markdown form is INLINE (e.g. the block `image`'s
+ * `![](url)`, or a bare media element) is wrapped by marked in a <p>; the schema
+ * then HOISTS the block atom out of that paragraph, leaving an EMPTY paragraph
+ * sibling. On the next export that empty `<p>` renders to "" and the doc "\n\n"
+ * join injects a phantom blank gap, so the markdown is not byte-stable.
+ *
+ * Markdown blank lines are separators, never content, so generateJSON only ever
+ * produces an empty paragraph as such a hoist artifact — removing them is safe
+ * and general (it also subsumes the <div>-wrapper workaround the `video` case
+ * uses). We remove ONLY `type === 'paragraph'` nodes whose `content` is absent
+ * or an empty array; every other node (including atoms without `content`) is
+ * preserved, and we recurse into the content of any node that has children.
+ */
+function stripEmptyParagraphs(node: any): any {
+  if (!node || !Array.isArray(node.content)) {
+    // Atom / leaf node (no children to recurse into): keep as-is.
+    return node;
+  }
+  const mapped = node.content.map((child: any) => stripEmptyParagraphs(child));
+  const isEmptyParagraph = (child: any): boolean =>
+    !!child &&
+    child.type === "paragraph" &&
+    (!Array.isArray(child.content) || child.content.length === 0);
+  const filtered = mapped.filter((child: any) => !isEmptyParagraph(child));
+  // Schema-validity guard: several nodes require NON-empty block content
+  // (`content: "block+"` — tableCell, tableHeader, blockquote, column, callout,
+  // and the doc root). For an empty one of those, generateJSON materializes a
+  // single empty paragraph as its OBLIGATORY content — that is not a hoist
+  // artifact. If stripping would empty the container, keep ONE empty paragraph
+  // so the result stays schema-valid (an empty cell/quote must not become `[]`).
+  const cleaned =
+    filtered.length === 0 && mapped.length > 0 ? [mapped[0]] : filtered;
+  return { ...node, content: cleaned };
+}
+
+/** 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 bridged = bridgeTaskLists(html);
+  const doc = generateJSON(bridged, docmostExtensions);
+  return stripEmptyParagraphs(doc);
+}
diff --git a/packages/prosemirror-markdown/src/lib/node-ops.ts b/packages/prosemirror-markdown/src/lib/node-ops.ts
new file mode 100644
index 00000000..4934b216
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/node-ops.ts
@@ -0,0 +1,897 @@
+/**
+ * Pure, network-free helpers for manipulating a ProseMirror/TipTap document
+ * tree by node id.
+ *
+ * A ProseMirror node here is a plain JSON object of the shape produced by
+ * Docmost: `{ type, attrs?, content?, text?, marks? }`. Children live in the
+ * `content` array; a node carries a stable id in `attrs.id`. Callouts and
+ * table cells hold their children in `content` just like any other block, so a
+ * single recursive walk reaches them all.
+ *
+ * Every exported function operates on a DEEP CLONE of the input document and
+ * returns the new document. The input doc and any `newNode`/`node` argument are
+ * never mutated. All functions are defensively null-safe: missing/!Array
+ * `content`, non-object nodes, and absent `attrs` are tolerated.
+ */
+
+/** Deep-clone a JSON-serializable value without mutating the original. */
+function clone<T>(value: T): T {
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  // Fallback for environments without structuredClone.
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/** True if `value` is a non-null object (and not an array). */
+function isObject(value: any): value is Record<string, any> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True if `node` carries the given id in `node.attrs.id`. */
+function matchesId(node: any, nodeId: string): boolean {
+  return isObject(node) && isObject(node.attrs) && node.attrs.id === nodeId;
+}
+
+/**
+ * Recursively concatenate all text contained in a node.
+ *
+ * Text nodes contribute their `text` string; container nodes contribute the
+ * joined `blockPlainText` of their `content` children. Returns "" for nullish
+ * or non-object inputs.
+ */
+export function blockPlainText(node: any): string {
+  if (!isObject(node)) return "";
+  let out = "";
+  if (typeof node.text === "string") {
+    out += node.text;
+  }
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      out += blockPlainText(child);
+    }
+  }
+  return out;
+}
+
+/** Truncate `text` to at most `n` chars, appending an ellipsis when cut. */
+function truncate(text: string, n: number): string {
+  return text.length > n ? text.slice(0, n) + "…" : text;
+}
+
+/** One compact outline entry for a single top-level block. */
+export interface OutlineEntry {
+  index: number;
+  type: string | undefined;
+  id: string | null;
+  firstText: string;
+  /** Present for headings only. */
+  level?: number | null;
+  /** Present for tables only. */
+  rows?: number;
+  cols?: number;
+  header?: string[];
+  /** Present for list blocks only (bulletList/orderedList/taskList). */
+  items?: number;
+}
+
+/**
+ * Build a COMPACT outline of the TOP-LEVEL blocks of `doc` (the entries in
+ * `doc.content`). Deliberately does NOT recurse into paragraphs, list items, or
+ * table cells — compactness is the point; use `getNodeByRef` to drill into a
+ * specific block.
+ *
+ * Each entry carries `{ index, type, id, firstText }`, plus type-specific
+ * extras: headings add `level`; tables add `rows`/`cols` and the first row's
+ * cell texts as `header`; list blocks (types ending in "List") add `items`.
+ * `firstText` is the block's plain text truncated to 100 chars. Null-safe:
+ * a missing or non-object doc/content yields `[]`.
+ */
+export function buildOutline(doc: any): OutlineEntry[] {
+  if (!isObject(doc) || !Array.isArray(doc.content)) return [];
+
+  const out: OutlineEntry[] = [];
+  for (let i = 0; i < doc.content.length; i++) {
+    const block = doc.content[i];
+    const type = isObject(block) ? block.type : undefined;
+    const entry: OutlineEntry = {
+      index: i,
+      type,
+      id: isObject(block) && isObject(block.attrs) ? block.attrs.id ?? null : null,
+      firstText: truncate(blockPlainText(block), 100),
+    };
+
+    if (type === "heading") {
+      entry.level = isObject(block.attrs) ? block.attrs.level ?? null : null;
+    } else if (type === "table") {
+      const headerRow = block.content?.[0]?.content ?? [];
+      entry.rows = block.content?.length ?? 0;
+      entry.cols = block.content?.[0]?.content?.length ?? 0;
+      entry.header = headerRow.map((cell: any) =>
+        truncate(blockPlainText(cell), 40),
+      );
+    } else if (typeof type === "string" && type.endsWith("List")) {
+      entry.items = block.content?.length ?? 0;
+    }
+
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Resolve a single node by reference and return `{ node, path, type }`, or
+ * `null` when nothing matches.
+ *
+ * - `ref` of the form `#<n>` (e.g. `#2`) selects the TOP-LEVEL block at index
+ *   `n` in `doc.content`. This is the only way to address table/tableRow/
+ *   tableCell nodes, which carry no `attrs.id`.
+ * - Otherwise `ref` is treated as a block id: the FIRST node anywhere in the
+ *   tree with `attrs.id === ref` is returned.
+ *
+ * `path` is the array of child indices from the doc root down to the node
+ * (so a top-level block is `[index]`). The returned `node` is a DEEP CLONE,
+ * so callers can mutate it without touching the input doc. Null-safe.
+ */
+export function getNodeByRef(
+  doc: any,
+  ref: string,
+): { node: any; path: number[]; type: string | undefined } | null {
+  if (!isObject(doc)) return null;
+
+  // "#<n>": index into the top-level content array.
+  const indexMatch = typeof ref === "string" ? ref.match(/^#(\d+)$/) : null;
+  if (indexMatch) {
+    const index = Number(indexMatch[1]);
+    const block = Array.isArray(doc.content) ? doc.content[index] : undefined;
+    if (!isObject(block)) return null;
+    return { node: clone(block), path: [index], type: block.type };
+  }
+
+  // Otherwise: depth-first search for the first node with attrs.id === ref.
+  const search = (
+    node: any,
+    trail: number[],
+  ): { node: any; path: number[]; type: string } | null => {
+    if (!isObject(node)) return null;
+    if (Array.isArray(node.content)) {
+      for (let i = 0; i < node.content.length; i++) {
+        const child = node.content[i];
+        const path = [...trail, i];
+        if (matchesId(child, ref)) {
+          return { node: clone(child), path, type: child.type };
+        }
+        const hit = search(child, path);
+        if (hit != null) return hit;
+      }
+    }
+    return null;
+  };
+
+  return search(doc, []);
+}
+
+/**
+ * Replace EVERY node whose `attrs.id === nodeId` with a deep clone of
+ * `newNode`, anywhere in the tree (including inside callouts and table cells).
+ *
+ * Operates on a clone of `doc`; returns `{ doc, replaced }` where `replaced`
+ * is the number of nodes substituted. A fresh clone of `newNode` is used for
+ * each match so they do not share references.
+ */
+export function replaceNodeById(
+  doc: any,
+  nodeId: string,
+  newNode: any,
+): { doc: any; replaced: number } {
+  const out = clone(doc);
+  let replaced = 0;
+
+  // Walk a content array, replacing direct matches and recursing into the
+  // (possibly new) children of non-matching nodes.
+  const walkContent = (content: any[]): void => {
+    for (let i = 0; i < content.length; i++) {
+      const child = content[i];
+      if (matchesId(child, nodeId)) {
+        content[i] = clone(newNode);
+        replaced++;
+        // Do not recurse into a freshly substituted node.
+        continue;
+      }
+      if (isObject(child) && Array.isArray(child.content)) {
+        walkContent(child.content);
+      }
+    }
+  };
+
+  if (isObject(out) && Array.isArray(out.content)) {
+    walkContent(out.content);
+  }
+  return { doc: out, replaced };
+}
+
+/**
+ * Remove EVERY node whose `attrs.id === nodeId` from its parent `content`
+ * array, anywhere in the tree (recursive, including callouts and tables).
+ *
+ * Operates on a clone of `doc`; returns `{ doc, deleted }` where `deleted` is
+ * the number of nodes removed.
+ */
+export function deleteNodeById(
+  doc: any,
+  nodeId: string,
+): { doc: any; deleted: number } {
+  const out = clone(doc);
+  let deleted = 0;
+
+  // Filter a content array in place, dropping matches and recursing into the
+  // surviving children.
+  const walkContent = (content: any[]): any[] => {
+    const kept: any[] = [];
+    for (const child of content) {
+      if (matchesId(child, nodeId)) {
+        deleted++;
+        continue;
+      }
+      if (isObject(child) && Array.isArray(child.content)) {
+        child.content = walkContent(child.content);
+      }
+      kept.push(child);
+    }
+    return kept;
+  };
+
+  if (isObject(out) && Array.isArray(out.content)) {
+    out.content = walkContent(out.content);
+  }
+  return { doc: out, deleted };
+}
+
+/**
+ * Deep-clone `doc` and strip every node/mark attribute whose value is strictly
+ * `undefined`, so the result is safe to hand to Yjs (which throws an opaque
+ * "Unexpected content type" when asked to store an `undefined` attribute value).
+ *
+ * Only `undefined` keys are removed; `null`, `false`, `0`, and `""` are all
+ * legitimate JSON-storable values and are preserved. Operates on a clone and
+ * returns it; the input is never mutated. Defensively null-safe like the rest
+ * of the file.
+ */
+export function sanitizeForYjs(doc: any): any {
+  const out = clone(doc);
+
+  // Drop every key whose value is strictly `undefined` from an attrs object.
+  const stripUndefined = (attrs: any): void => {
+    if (!isObject(attrs)) return;
+    for (const key of Object.keys(attrs)) {
+      if (attrs[key] === undefined) {
+        delete attrs[key];
+      }
+    }
+  };
+
+  const walk = (node: any): void => {
+    if (!isObject(node)) return;
+    stripUndefined(node.attrs);
+    if (Array.isArray(node.marks)) {
+      for (const mark of node.marks) {
+        if (isObject(mark)) stripUndefined(mark.attrs);
+      }
+    }
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) {
+        walk(child);
+      }
+    }
+  };
+
+  walk(out);
+  return out;
+}
+
+/**
+ * Diagnostics helper: walk the tree and return a human-readable path string for
+ * the FIRST attribute value (in any `node.attrs` or `mark.attrs`) that Yjs
+ * cannot store — i.e. `undefined`, a `function`, a `symbol`, or a `bigint`
+ * (e.g. `content[3].content[0].attrs.indent (undefined)`). Returns `null` when
+ * every attribute is storable. Null-safe.
+ */
+export function findUnstorableAttr(doc: any): string | null {
+  const isUnstorable = (value: any): string | null => {
+    if (value === undefined) return "undefined";
+    const t = typeof value;
+    if (t === "function") return "function";
+    if (t === "symbol") return "symbol";
+    if (t === "bigint") return "bigint";
+    return null;
+  };
+
+  // Check an attrs object; return the offending sub-path or null.
+  const checkAttrs = (attrs: any, basePath: string): string | null => {
+    if (!isObject(attrs)) return null;
+    for (const key of Object.keys(attrs)) {
+      const kind = isUnstorable(attrs[key]);
+      if (kind != null) return `${basePath}.${key} (${kind})`;
+    }
+    return null;
+  };
+
+  const walk = (node: any, path: string): string | null => {
+    if (!isObject(node)) return null;
+    const attrHit = checkAttrs(node.attrs, `${path}.attrs`);
+    if (attrHit != null) return attrHit;
+    if (Array.isArray(node.marks)) {
+      for (let i = 0; i < node.marks.length; i++) {
+        const markHit = checkAttrs(
+          node.marks[i]?.attrs,
+          `${path}.marks[${i}].attrs`,
+        );
+        if (markHit != null) return markHit;
+      }
+    }
+    if (Array.isArray(node.content)) {
+      for (let i = 0; i < node.content.length; i++) {
+        const childHit = walk(node.content[i], `${path}.content[${i}]`);
+        if (childHit != null) return childHit;
+      }
+    }
+    return null;
+  };
+
+  // The root doc node carries no useful index, so start the path at "doc".
+  if (!isObject(doc)) return null;
+  const attrHit = checkAttrs(doc.attrs, "attrs");
+  if (attrHit != null) return attrHit;
+  if (Array.isArray(doc.content)) {
+    for (let i = 0; i < doc.content.length; i++) {
+      const childHit = walk(doc.content[i], `content[${i}]`);
+      if (childHit != null) return childHit;
+    }
+  }
+  return null;
+}
+
+/**
+ * Table structural node types and the container each must live directly inside.
+ * Used by `insertNodeRelative` to splice rows/cells into the correct ancestor
+ * rather than blindly into the anchor's direct parent (which would corrupt the
+ * table's nesting).
+ */
+const STRUCTURAL_TYPES = new Set(["tableRow", "tableCell", "tableHeader"]);
+const REQUIRED_CONTAINER: Record<string, string> = {
+  tableRow: "table",
+  tableCell: "tableRow",
+  tableHeader: "tableRow",
+};
+
+/**
+ * Locate an anchor and return its ancestor chain (from `doc` down to and
+ * including the matched node). Each chain entry is `{ node, index }` where
+ * `index` is the node's position inside its parent's `content` array (the root
+ * doc has index -1). Returns `null` when the anchor cannot be resolved.
+ */
+function findAnchorChain(
+  doc: any,
+  opts: InsertOptions,
+): { node: any; index: number }[] | null {
+  if (!isObject(doc)) return null;
+
+  // DFS by id anywhere in the tree, accumulating the path.
+  if (opts.anchorNodeId != null) {
+    const targetId = opts.anchorNodeId;
+    const search = (
+      node: any,
+      index: number,
+      trail: { node: any; index: number }[],
+    ): { node: any; index: number }[] | null => {
+      if (!isObject(node)) return null;
+      const here = [...trail, { node, index }];
+      if (matchesId(node, targetId)) return here;
+      if (Array.isArray(node.content)) {
+        for (let i = 0; i < node.content.length; i++) {
+          const hit = search(node.content[i], i, here);
+          if (hit != null) return hit;
+        }
+      }
+      return null;
+    };
+    return search(doc, -1, []);
+  }
+
+  // By text: only top-level blocks are scanned (same rule as the JSON path).
+  if (opts.anchorText != null && Array.isArray(doc.content)) {
+    for (let i = 0; i < doc.content.length; i++) {
+      if (blockPlainText(doc.content[i]).includes(opts.anchorText)) {
+        return [
+          { node: doc, index: -1 },
+          { node: doc.content[i], index: i },
+        ];
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Options controlling where `insertNodeRelative` places the new node. */
+export interface InsertOptions {
+  position: "before" | "after" | "append";
+  /** Resolve the anchor by node id anywhere in the tree (preferred). */
+  anchorNodeId?: string;
+  /** Fallback: first TOP-LEVEL block whose plain text includes this string. */
+  anchorText?: string;
+}
+
+/**
+ * Insert a deep clone of `node` relative to an anchor.
+ *
+ * - position "append": push the node onto the top-level `doc.content`.
+ * - position "before"/"after": locate the anchor and splice the node into the
+ *   anchor's parent `content` array immediately before / after it.
+ *
+ * Anchor resolution for before/after:
+ *   - if `anchorNodeId` is given, find the node with `attrs.id === anchorNodeId`
+ *     anywhere in the tree (recursive);
+ *   - otherwise, if `anchorText` is given, scan only TOP-LEVEL `doc.content`
+ *     blocks and pick the first whose `blockPlainText` includes `anchorText`.
+ *
+ * Operates on a clone of `doc`; returns `{ doc, inserted }`. `inserted` is
+ * false when the anchor could not be resolved (the doc is returned unchanged
+ * apart from being cloned).
+ */
+export function insertNodeRelative(
+  doc: any,
+  node: any,
+  opts: InsertOptions,
+): { doc: any; inserted: boolean } {
+  const out = clone(doc);
+  const fresh = clone(node);
+
+  // Defensive: stay null-safe like the other exports — a missing opts means
+  // there is nothing actionable to do.
+  if (!isObject(opts)) return { doc: out, inserted: false };
+
+  const isStructural = isObject(node) && STRUCTURAL_TYPES.has(node.type);
+
+  // "append": top-level push.
+  if (opts.position === "append") {
+    // Structural table nodes (tableRow/tableCell/tableHeader) cannot live at the
+    // top level — appending one would produce invalid nesting.
+    if (isStructural) {
+      throw new Error(
+        `insert_node: cannot append a ${node.type} at the top level; use ` +
+          `position before/after with an anchor inside the target table`,
+      );
+    }
+    if (isObject(out)) {
+      if (!Array.isArray(out.content)) out.content = [];
+      out.content.push(fresh);
+      return { doc: out, inserted: true };
+    }
+    return { doc: out, inserted: false };
+  }
+
+  const offset = opts.position === "after" ? 1 : 0;
+
+  // Structural insert (before/after a tableRow/tableCell/tableHeader): splice
+  // into the nearest enclosing table/tableRow rather than the anchor's direct
+  // parent, so the row/cell lands at the correct level of the table.
+  if (isStructural) {
+    const containerType = REQUIRED_CONTAINER[node.type];
+    const chain = findAnchorChain(out, opts);
+    // Anchor not resolved at all — keep the existing "anchor not found" path.
+    if (chain == null) return { doc: out, inserted: false };
+
+    // Find the DEEPEST ancestor (including the anchor itself) of the required
+    // container type.
+    let containerIdx = -1;
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (isObject(chain[i].node) && chain[i].node.type === containerType) {
+        containerIdx = i;
+        break;
+      }
+    }
+
+    if (containerIdx === -1) {
+      throw new Error(
+        `insert_node: cannot insert a ${node.type} here — the anchor is not ` +
+          `inside a ${containerType}. Anchor on a cell's text or a block id ` +
+          `that lives inside the target table.`,
+      );
+    }
+
+    const container = chain[containerIdx].node;
+    if (!Array.isArray(container.content)) container.content = [];
+
+    if (containerIdx === chain.length - 1) {
+      // The matched container IS the anchor node itself (e.g. anchorText
+      // resolved to the table block): append/prepend within it.
+      const at = opts.position === "after" ? container.content.length : 0;
+      container.content.splice(at, 0, fresh);
+    } else {
+      // The immediate child on the path leading to the anchor is the row/cell
+      // to splice next to.
+      const enclosingChildIndex = chain[containerIdx + 1].index;
+      container.content.splice(enclosingChildIndex + offset, 0, fresh);
+    }
+    return { doc: out, inserted: true };
+  }
+
+  // Resolve by id anywhere in the tree: splice into the parent content array.
+  if (opts.anchorNodeId != null) {
+    let inserted = false;
+    const walkContent = (content: any[]): void => {
+      for (let i = 0; i < content.length; i++) {
+        const child = content[i];
+        if (matchesId(child, opts.anchorNodeId as string)) {
+          content.splice(i + offset, 0, fresh);
+          inserted = true;
+          return;
+        }
+        if (isObject(child) && Array.isArray(child.content)) {
+          walkContent(child.content);
+          if (inserted) return;
+        }
+      }
+    };
+    if (isObject(out) && Array.isArray(out.content)) {
+      walkContent(out.content);
+    }
+    return { doc: out, inserted };
+  }
+
+  // Resolve by text: only top-level doc.content blocks are scanned.
+  if (opts.anchorText != null && isObject(out) && Array.isArray(out.content)) {
+    for (let i = 0; i < out.content.length; i++) {
+      if (blockPlainText(out.content[i]).includes(opts.anchorText)) {
+        out.content.splice(i + offset, 0, fresh);
+        return { doc: out, inserted: true };
+      }
+    }
+  }
+
+  return { doc: out, inserted: false };
+}
+
+// ===========================================================================
+// Table editing helpers
+//
+// A Docmost table is a ProseMirror subtree with NO ids on the structural nodes:
+//   table   -> { type:"table",     content:[tableRow...] }
+//   row     -> { type:"tableRow",  content:[tableCell|tableHeader...] }
+//   cell    -> { type:"tableCell"|"tableHeader", attrs:{colspan,rowspan,colwidth},
+//                content:[paragraph...] }
+//   para    -> { type:"paragraph", attrs:{id,indent}, content:[textNode...] }
+// Only paragraphs/headings carry an `attrs.id`, so a cell is addressed via the
+// id of the paragraph inside it. The helpers below all operate on a DEEP CLONE
+// of the input doc (via `clone`) and never mutate their inputs.
+// ===========================================================================
+
+/**
+ * Collect EVERY `attrs.id` present anywhere in `node` into `used`. Used to seed
+ * `makeFreshId` so generated paragraph ids never collide with existing ones.
+ */
+function collectIds(node: any, used: Set<string>): void {
+  if (!isObject(node)) return;
+  if (isObject(node.attrs) && typeof node.attrs.id === "string") {
+    used.add(node.attrs.id);
+  }
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) collectIds(child, used);
+  }
+}
+
+/**
+ * Fresh-id generator: returns a random Docmost-style id (12 chars from
+ * lowercase `a-z0-9`) that is not already in `used`, and records it. On the
+ * rare collision the id is regenerated. Callers rely on uniqueness, not on the
+ * exact string, so randomness is fine — and unlike a module-local counter it
+ * needs no reset and cannot become predictable across calls.
+ */
+function makeFreshId(used: Set<string>): string {
+  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let id: string;
+  do {
+    id = "";
+    for (let i = 0; i < 12; i++) {
+      id += alphabet[Math.floor(Math.random() * alphabet.length)];
+    }
+  } while (used.has(id) || id === "");
+  used.add(id);
+  return id;
+}
+
+/**
+ * Resolve a table reference against an ALREADY-CLONED doc and return the LIVE
+ * table node (a reference inside `rootClone`, so the caller may mutate it) plus
+ * its index path. Returns null when no table matches.
+ *
+ * - `#<n>`: the top-level block at index `n`, only if its `type === "table"`.
+ * - otherwise: DFS for the node with `attrs.id === tableRef`, then walk UP its
+ *   ancestor chain to the nearest `type === "table"` ancestor.
+ */
+function locateTable(
+  rootClone: any,
+  tableRef: string,
+): { table: any; path: number[] } | null {
+  if (!isObject(rootClone)) return null;
+
+  // "#<n>": index into the top-level content array; must be a table.
+  const indexMatch = typeof tableRef === "string" ? tableRef.match(/^#(\d+)$/) : null;
+  if (indexMatch) {
+    const index = Number(indexMatch[1]);
+    const block = Array.isArray(rootClone.content)
+      ? rootClone.content[index]
+      : undefined;
+    if (isObject(block) && block.type === "table") {
+      return { table: block, path: [index] };
+    }
+    return null;
+  }
+
+  // Otherwise: DFS for attrs.id === tableRef, tracking the ancestor chain, then
+  // climb to the nearest enclosing table.
+  const search = (
+    node: any,
+    trail: { node: any; index: number }[],
+  ): { table: any; path: number[] } | null => {
+    if (!isObject(node)) return null;
+    if (Array.isArray(node.content)) {
+      for (let i = 0; i < node.content.length; i++) {
+        const child = node.content[i];
+        const here = [...trail, { node: child, index: i }];
+        if (matchesId(child, tableRef)) {
+          // Walk UP to the nearest table ancestor (including the match itself).
+          for (let j = here.length - 1; j >= 0; j--) {
+            if (isObject(here[j].node) && here[j].node.type === "table") {
+              return {
+                table: here[j].node,
+                path: here.slice(0, j + 1).map((e) => e.index),
+              };
+            }
+          }
+          return null; // id found but no enclosing table
+        }
+        const hit = search(child, here);
+        if (hit != null) return hit;
+      }
+    }
+    return null;
+  };
+
+  return search(rootClone, []);
+}
+
+/** Build the plain-text → single-paragraph cell content used by all writers. */
+function makeCellParagraph(id: string, text: string): any {
+  return {
+    type: "paragraph",
+    attrs: { id, indent: 0 },
+    // Empty string → a paragraph with an empty content array.
+    content: text ? [{ type: "text", text }] : [],
+  };
+}
+
+/**
+ * Read a table as a matrix. Returns null when `tableRef` resolves to no table.
+ *
+ * - `rows`/`cols`: the table's row count and the column count of its FIRST row.
+ *   Tables may be ragged (rows of differing length), so `cols` reflects only
+ *   row 0; use the per-row length of `cells`/`cellIds` for each row's actual
+ *   width.
+ * - `cells`: `string[][]` of each cell's `blockPlainText`.
+ * - `cellIds`: `(string|null)[][]` of each cell's FIRST paragraph id (or null),
+ *   so callers can `patch_node` a cell for rich-formatted edits.
+ * - `path`: index path of the table within the doc.
+ */
+export function readTable(
+  doc: any,
+  tableRef: string,
+): {
+  rows: number;
+  cols: number;
+  cells: string[][];
+  cellIds: (string | null)[][];
+  path: number[];
+} | null {
+  const root = clone(doc);
+  const located = locateTable(root, tableRef);
+  if (located == null) return null;
+  const { table, path } = located;
+
+  const rowNodes = Array.isArray(table.content) ? table.content : [];
+  const rows = rowNodes.length;
+  const cols = rowNodes[0]?.content?.length ?? 0;
+
+  const cells: string[][] = [];
+  const cellIds: (string | null)[][] = [];
+  for (const rowNode of rowNodes) {
+    const cellNodes = Array.isArray(rowNode?.content) ? rowNode.content : [];
+    const rowText: string[] = [];
+    const rowIds: (string | null)[] = [];
+    for (const cellNode of cellNodes) {
+      rowText.push(blockPlainText(cellNode));
+      // The cell's first paragraph carries the id used for patch_node.
+      const firstPara = Array.isArray(cellNode?.content)
+        ? cellNode.content[0]
+        : undefined;
+      const id =
+        isObject(firstPara) && isObject(firstPara.attrs)
+          ? firstPara.attrs.id ?? null
+          : null;
+      rowIds.push(id);
+    }
+    cells.push(rowText);
+    cellIds.push(rowIds);
+  }
+
+  return { rows, cols, cells, cellIds, path };
+}
+
+/**
+ * Insert a row of plain-text cells into a table. Returns `{ doc, inserted }`.
+ *
+ * The row is padded to the table's column count (`cells[i] ?? ""`); supplying
+ * MORE cells than columns throws. Each new cell copies `colwidth` for its
+ * column from the header row when present, gets a fresh-id paragraph, and a
+ * `colspan:1, rowspan:1` attrs. `index` (when an integer in `[0, rows]`) splices
+ * the row there; otherwise the row is appended at the end.
+ */
+export function insertTableRow(
+  doc: any,
+  tableRef: string,
+  cells: string[],
+  index?: number,
+): { doc: any; inserted: boolean } {
+  const out = clone(doc);
+  const located = locateTable(out, tableRef);
+  if (located == null) return { doc: out, inserted: false };
+  const { table } = located;
+
+  if (!Array.isArray(table.content)) table.content = [];
+  const rows = table.content.length;
+  const headerRow = table.content[0];
+  const headerCells = Array.isArray(headerRow?.content) ? headerRow.content : [];
+
+  // Column count is the WIDEST existing row, so the guard below stays
+  // meaningful for ragged tables and the new row matches the table's width.
+  // Fall back to the supplied cell count only when the table has no rows.
+  let colCount = 0;
+  for (const r of table.content) {
+    if (isObject(r) && Array.isArray(r.content)) colCount = Math.max(colCount, r.content.length);
+  }
+  if (colCount === 0) colCount = Array.isArray(cells) ? cells.length : 0;
+
+  if (Array.isArray(cells) && cells.length > colCount) {
+    throw new Error(
+      `table_insert_row: got ${cells.length} cell(s) but the table has ${colCount} column(s)`,
+    );
+  }
+
+  // Resolve the landing index up front so the cell-type decision and the splice
+  // below agree: a valid integer in [0, rows] splices there, else we append.
+  const landingIndex =
+    typeof index === "number" && Number.isInteger(index) && index >= 0 && index <= rows
+      ? index
+      : rows;
+
+  // Seed the id generator with every id already in the doc so the new cell
+  // paragraph ids are unique within the whole document.
+  const used = new Set<string>();
+  collectIds(out, used);
+
+  const newCells: any[] = [];
+  for (let i = 0; i < colCount; i++) {
+    const text = (Array.isArray(cells) ? cells[i] : undefined) ?? "";
+    const attrs: Record<string, any> = { colspan: 1, rowspan: 1 };
+    // Copy this column's colwidth from the header row's cell when present.
+    const colwidth = headerCells[i]?.attrs?.colwidth;
+    if (colwidth !== undefined) attrs.colwidth = colwidth;
+    // A row landing at index 0 becomes the new header row, so inherit the
+    // current header cell's type per column (Docmost uses "tableHeader" there);
+    // every other position is a plain data cell.
+    const cellType = landingIndex === 0 ? headerCells[i]?.type ?? "tableCell" : "tableCell";
+    newCells.push({
+      type: cellType,
+      attrs,
+      content: [makeCellParagraph(makeFreshId(used), text)],
+    });
+  }
+
+  const newRow = { type: "tableRow", content: newCells };
+
+  // Splice at the resolved landing index (append when index was omitted/invalid).
+  table.content.splice(landingIndex, 0, newRow);
+
+  return { doc: out, inserted: true };
+}
+
+/**
+ * Delete the row at 0-based `index` from a table. Returns `{ doc, deleted }`.
+ * `deleted` is false only when the table cannot be located. Throws on an
+ * out-of-range index, and refuses to delete the table's only row.
+ */
+export function deleteTableRow(
+  doc: any,
+  tableRef: string,
+  index: number,
+): { doc: any; deleted: boolean } {
+  const out = clone(doc);
+  const located = locateTable(out, tableRef);
+  if (located == null) return { doc: out, deleted: false };
+  const { table } = located;
+
+  if (!Array.isArray(table.content)) table.content = [];
+  const rows = table.content.length;
+
+  if (!Number.isInteger(index) || index < 0 || index >= rows) {
+    throw new Error(
+      `table_delete_row: row index ${index} out of range (table has ${rows} row(s))`,
+    );
+  }
+  if (rows <= 1) {
+    throw new Error(
+      "table_delete_row: refusing to delete the only row of the table",
+    );
+  }
+
+  table.content.splice(index, 1);
+  return { doc: out, deleted: true };
+}
+
+/**
+ * Set the plain-text content of cell `[row, col]` (0-based) to `text`. Returns
+ * `{ doc, updated }`; `updated` is false only when the table cannot be located.
+ * Throws when `row`/`col` is out of range. The cell's own attrs (colspan/
+ * rowspan/colwidth) are preserved; its content becomes a single text paragraph
+ * that reuses the cell's existing first-paragraph id when present, else a fresh
+ * one.
+ */
+export function updateTableCell(
+  doc: any,
+  tableRef: string,
+  row: number,
+  col: number,
+  text: string,
+): { doc: any; updated: boolean } {
+  const out = clone(doc);
+  const located = locateTable(out, tableRef);
+  if (located == null) return { doc: out, updated: false };
+  const { table } = located;
+
+  const rowNodes = Array.isArray(table.content) ? table.content : [];
+  const rows = rowNodes.length;
+  const rowNode = rowNodes[row];
+  const cols = isObject(rowNode) && Array.isArray(rowNode.content)
+    ? rowNode.content.length
+    : 0;
+
+  if (
+    !Number.isInteger(row) ||
+    row < 0 ||
+    row >= rows ||
+    !Number.isInteger(col) ||
+    col < 0 ||
+    col >= cols
+  ) {
+    throw new Error(`table_update_cell: cell [${row},${col}] out of range`);
+  }
+
+  const cellNode = rowNode.content[col];
+  // Reuse the cell's existing first-paragraph id, or mint a fresh unique one.
+  const existingPara = Array.isArray(cellNode?.content)
+    ? cellNode.content[0]
+    : undefined;
+  let id =
+    isObject(existingPara) && isObject(existingPara.attrs)
+      ? existingPara.attrs.id
+      : undefined;
+  if (typeof id !== "string" || id.length === 0) {
+    const used = new Set<string>();
+    collectIds(out, used);
+    id = makeFreshId(used);
+  }
+
+  cellNode.content = [makeCellParagraph(id, text)];
+  return { doc: out, updated: true };
+}
diff --git a/packages/prosemirror-markdown/src/lib/page-file.ts b/packages/prosemirror-markdown/src/lib/page-file.ts
new file mode 100644
index 00000000..26e43776
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/page-file.ts
@@ -0,0 +1,81 @@
+/**
+ * The native-Obsidian page-file format (design: docs/backlog/git-sync-thin-meta.md).
+ * A page file is CLEAN markdown with a minimal YAML frontmatter carrying ONLY the
+ * page's durable identity:
+ *
+ *   ---
+ *   gitmost_id: 019ef6fc-2638-7ce1-9ce3-2756ce038480
+ *   ---
+ *   <clean markdown body>
+ *
+ * Everything else is derived (title = filename, parentPageId = enclosing folder,
+ * spaceId = the vault, updatedAt = git). `gitmost_id` (a Docmost pageId) is the
+ * only non-derivable bit and travels WITH the file so identity survives any move,
+ * even one git's rename detection misses. Third-party editors (Obsidian, …) see
+ * clean markdown; the frontmatter is hidden in their preview.
+ *
+ * No backward-compat with the old `docmost:meta` format: vaults are a cache, wiped
+ * and rebuilt native. A file WITHOUT a `gitmost_id` frontmatter is an un-tracked
+ * (e.g. hand-written) file -> the caller ADOPTS it (creates a page, writes the id).
+ */
+
+/**
+ * The frontmatter key carrying the Docmost pageId. NAMESPACED (not a bare `id`)
+ * so it never collides with a user's own frontmatter fields.
+ */
+export const ID_KEY = "gitmost_id";
+
+/** Leading YAML frontmatter block: `---\n…\n---` at the very start of the file. */
+const FRONTMATTER_RE = /^?---\n([\s\S]*?)\n---\n?/;
+
+/** The top-level `<ID_KEY>: <value>` line inside the frontmatter (quotes optional). */
+function readIdFromYaml(yaml: string): string | null {
+  const re = new RegExp(`^${ID_KEY}:\\s*(.+?)\\s*$`);
+  for (const line of yaml.split("\n")) {
+    const m = line.match(re);
+    if (m) {
+      const v = m[1].trim().replace(/^["']|["']$/g, "");
+      return v === "" ? null : v;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse a page file into its identity (`id`) and clean markdown `body`. Tolerant:
+ * a file with no frontmatter (a hand-written third-party file) returns `id: null`
+ * and the whole text as the body — the caller then ADOPTS it (creates a page,
+ * writes the id back).
+ *
+ * KNOWN LIMITATION (phase 4 — adoption, see docs/backlog/git-sync-thin-meta.md):
+ * a leading frontmatter block is stripped from `body` even when it carries NO
+ * `gitmost_id` but DOES carry the user's own Obsidian properties (`tags:` etc.).
+ * On adoption those fields are not yet round-tripped — `serializePageFile`
+ * write-back persists only `gitmost_id`. Preserving arbitrary user frontmatter
+ * across the Docmost round-trip (BOTH adoption write-back AND the next pull's
+ * re-serialize) is deferred to the adoption phase; until then, do NOT roll the
+ * native format onto a real Obsidian vault whose notes carry properties.
+ */
+export function parsePageFile(full: string): {
+  id: string | null;
+  body: string;
+} {
+  const text = (full ?? "").replace(/\r\n/g, "\n");
+
+  // Native format: a `gitmost_id` YAML frontmatter. Anything else (no frontmatter,
+  // or frontmatter without the key) is an un-tracked file -> adopt.
+  const fm = text.match(FRONTMATTER_RE);
+  if (fm) {
+    return { id: readIdFromYaml(fm[1]), body: text.slice(fm[0].length).trim() };
+  }
+  return { id: null, body: text.trim() };
+}
+
+/**
+ * Serialize a page into the thin format: `id` frontmatter + a blank line + the
+ * clean body + a trailing newline. Deterministic so an unchanged page re-syncs to
+ * byte-identical output (no churn — the loop-guard relies on it).
+ */
+export function serializePageFile(id: string, body: string): string {
+  return `---\n${ID_KEY}: ${id}\n---\n\n${body.trim()}\n`;
+}
diff --git a/packages/prosemirror-markdown/test/canonicalize-extra.test.ts b/packages/prosemirror-markdown/test/canonicalize-extra.test.ts
new file mode 100644
index 00000000..e2103f80
--- /dev/null
+++ b/packages/prosemirror-markdown/test/canonicalize-extra.test.ts
@@ -0,0 +1,205 @@
+import { describe, expect, it } from 'vitest';
+import fc from 'fast-check';
+// Barrel import (R-Infra alias resolves this to packages/docmost-client/src so
+// coverage measures the real source, not stale dist).
+import { canonicalizeContent, docsCanonicallyEqual } from 'docmost-client';
+
+// ---------------------------------------------------------------------------
+// Gaps NOT covered by canonicalize.test.ts (test-strategy report §2 diff):
+//   - the *.align family (drawio/excalidraw/video/youtube/embed): a "center"
+//     default is dropped, a non-default value is kept;
+//   - comment.resolved: TRUE is PRESERVED (only resolved:false is normalized);
+//   - link.target / link.rel NON-default values are kept;
+//   - property: canonicalizeContent is a fixpoint, docsCanonicallyEqual is
+//     reflexive and symmetric.
+// The base file already covers id-stripping, null-drop, link/comment/orderedList
+// default-drop, key-order insensitivity, and a real-diff negative — not re-added.
+// ---------------------------------------------------------------------------
+
+describe('canonicalizeContent — *.align default family', () => {
+  // Every diagram/media node whose schema `align` defaults to "center".
+  const alignTypes = ['drawio', 'excalidraw', 'video', 'youtube', 'embed'];
+
+  for (const type of alignTypes) {
+    it(`${type}: align "center" (the schema default) is dropped`, () => {
+      const out = canonicalizeContent({
+        type,
+        attrs: { id: 'n-1', src: '/x', align: 'center' },
+      });
+      // align==default removed; the meaningful src survives.
+      expect(out.attrs).toEqual({ src: '/x' });
+    });
+
+    it(`${type}: a NON-default align (e.g. "right") is kept`, () => {
+      const out = canonicalizeContent({
+        type,
+        attrs: { id: 'n-1', src: '/x', align: 'right' },
+      });
+      expect(out.attrs).toEqual({ src: '/x', align: 'right' });
+    });
+  }
+
+  it('image align is NOT in KNOWN_DEFAULTS: a non-null align survives, null is dropped', () => {
+    // image.align defaults to null, so it is handled by the null-drop rule and
+    // a real value ("left") must be kept (no spurious default match).
+    const kept = canonicalizeContent({
+      type: 'image',
+      attrs: { id: 'i-1', src: '/a.png', align: 'left' },
+    });
+    expect(kept.attrs).toEqual({ src: '/a.png', align: 'left' });
+    // An image with align:"center" must KEEP it (center is NOT a default for
+    // image, only for the diagram/media family) — guards against over-matching.
+    const center = canonicalizeContent({
+      type: 'image',
+      attrs: { id: 'i-2', src: '/b.png', align: 'center' },
+    });
+    expect(center.attrs).toEqual({ src: '/b.png', align: 'center' });
+  });
+});
+
+describe('canonicalizeContent — comment.resolved:true preserved (SPEC §11 L66)', () => {
+  it('keeps resolved:true (a legitimate change, not a default to normalize away)', () => {
+    const out = canonicalizeContent({
+      type: 'text',
+      text: 'anchored',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1', resolved: true } }],
+    });
+    // resolved:true is NON-default; it must survive alongside the commentId so a
+    // resolve-vs-unresolved divergence is not falsely reported as equal.
+    expect(out.marks).toEqual([
+      { type: 'comment', attrs: { commentId: 'cmt-1', resolved: true } },
+    ]);
+  });
+
+  it('a resolved:true comment is NOT canonically equal to an unresolved one', () => {
+    const resolved = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'c', resolved: true } }],
+    };
+    const open = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'c' } }],
+    };
+    expect(docsCanonicallyEqual(resolved, open)).toBe(false);
+  });
+});
+
+describe('canonicalizeContent — link non-default target/rel kept', () => {
+  it('keeps a NON-default link.target (e.g. "_self")', () => {
+    const out = canonicalizeContent({
+      type: 'text',
+      text: 'l',
+      marks: [{ type: 'link', attrs: { href: 'https://e.com', target: '_self' } }],
+    });
+    // _self != the "_blank" default, so target must survive.
+    expect(out.marks).toEqual([
+      { type: 'link', attrs: { href: 'https://e.com', target: '_self' } },
+    ]);
+  });
+
+  it('keeps a NON-default link.rel', () => {
+    const out = canonicalizeContent({
+      type: 'text',
+      text: 'l',
+      marks: [{ type: 'link', attrs: { href: 'https://e.com', rel: 'nofollow' } }],
+    });
+    expect(out.marks).toEqual([
+      { type: 'link', attrs: { href: 'https://e.com', rel: 'nofollow' } },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Property-based oracle checks (SPEC §11). The generated trees mix node/mark
+// types, ids, null attrs, known-default attrs and meaningful attrs, so the
+// invariants are exercised across the whole canonicalization surface.
+// ---------------------------------------------------------------------------
+
+// An attribute value: a meaningful value, a null/undefined, a block id, or a
+// known schema default — so pruning, id-drop, null-drop and default-drop all
+// fire during shrinking.
+const attrValueArb = fc.oneof(
+  fc.string({ minLength: 1, maxLength: 6 }),
+  fc.integer({ min: 0, max: 9 }),
+  fc.boolean(),
+  fc.constant(null),
+);
+
+// A recursive ProseMirror-ish node arbitrary (bounded depth) with type, attrs
+// (incl. an id and possibly a known default), optional marks and content.
+const nodeArb: fc.Arbitrary<any> = fc.letrec((tie) => ({
+  node: fc.record(
+    {
+      type: fc.constantFrom(
+        'paragraph',
+        'heading',
+        'orderedList',
+        'drawio',
+        'video',
+        'text',
+      ),
+      text: fc.option(fc.string({ minLength: 0, maxLength: 5 }), { nil: undefined }),
+      attrs: fc.option(
+        fc.dictionary(
+          fc.constantFrom('id', 'level', 'start', 'align', 'src', 'indent', 'keep'),
+          attrValueArb,
+          { maxKeys: 4 },
+        ),
+        { nil: undefined },
+      ),
+      marks: fc.option(
+        fc.array(
+          fc.record({
+            type: fc.constantFrom('bold', 'link', 'comment'),
+            attrs: fc.option(
+              fc.dictionary(
+                fc.constantFrom('href', 'target', 'rel', 'commentId', 'resolved'),
+                fc.oneof(attrValueArb, fc.constant('_blank')),
+                { maxKeys: 3 },
+              ),
+              { nil: undefined },
+            ),
+          }),
+          { maxLength: 2 },
+        ),
+        { nil: undefined },
+      ),
+      content: fc.option(fc.array(tie('node'), { maxLength: 2 }), { nil: undefined }),
+    },
+    { requiredKeys: ['type'] },
+  ),
+})).node;
+
+describe('canonicalizeContent — property invariants (SPEC §11 oracle)', () => {
+  it('is a fixpoint: f(f(x)) === f(x)', () => {
+    fc.assert(
+      fc.property(nodeArb, (node) => {
+        const once = canonicalizeContent(node);
+        const twice = canonicalizeContent(once);
+        // The canonical form must already be stable under a second pass.
+        expect(twice).toEqual(once);
+      }),
+      { numRuns: 300 },
+    );
+  });
+
+  it('docsCanonicallyEqual is reflexive: equal(x, x) is always true', () => {
+    fc.assert(
+      fc.property(nodeArb, (node) => {
+        expect(docsCanonicallyEqual(node, node)).toBe(true);
+      }),
+      { numRuns: 300 },
+    );
+  });
+
+  it('docsCanonicallyEqual is symmetric: equal(a, b) === equal(b, a)', () => {
+    fc.assert(
+      fc.property(nodeArb, nodeArb, (a, b) => {
+        expect(docsCanonicallyEqual(a, b)).toBe(docsCanonicallyEqual(b, a));
+      }),
+      { numRuns: 300 },
+    );
+  });
+});
diff --git a/packages/prosemirror-markdown/test/canonicalize.test.ts b/packages/prosemirror-markdown/test/canonicalize.test.ts
new file mode 100644
index 00000000..cec5da49
--- /dev/null
+++ b/packages/prosemirror-markdown/test/canonicalize.test.ts
@@ -0,0 +1,302 @@
+import { describe, expect, it } from 'vitest';
+// Import via the package barrel to also assert the symbols are re-exported.
+import { canonicalizeContent, docsCanonicallyEqual } from 'docmost-client';
+
+describe('canonicalizeContent', () => {
+  it('strips node-level attrs.id, recursively', () => {
+    const input = {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { id: 'h-1', level: 2 },
+          content: [{ type: 'text', text: 'Title' }],
+        },
+      ],
+    };
+    const out = canonicalizeContent(input);
+    expect(out.content[0].attrs).toEqual({ level: 2 });
+    // No `id` survives anywhere in the canonical tree.
+    expect(JSON.stringify(out)).not.toContain('"id"');
+  });
+
+  it('drops null/undefined attrs but keeps every non-null attr', () => {
+    const out = canonicalizeContent({
+      type: 'paragraph',
+      attrs: {
+        id: 'p-1',
+        indent: null,
+        textAlign: undefined,
+        level: 0,
+        keep: 'yes',
+      },
+      content: [],
+    });
+    // null/undefined gone; non-null values (incl. 0 and false) kept.
+    expect(out.attrs).toEqual({ keep: 'yes', level: 0 });
+  });
+
+  it('removes an attrs object that becomes empty after pruning', () => {
+    const out = canonicalizeContent({
+      type: 'paragraph',
+      attrs: { id: 'p-1', indent: null, textAlign: null },
+      content: [{ type: 'text', text: 'x' }],
+    });
+    // attrs had only an id + null defaults -> the whole attrs key is dropped.
+    expect('attrs' in out).toBe(false);
+    expect(out).toEqual({
+      type: 'paragraph',
+      content: [{ type: 'text', text: 'x' }],
+    });
+  });
+
+  it('treats {attrs:{}} as equivalent to no attrs', () => {
+    const withEmpty = canonicalizeContent({ type: 'paragraph', attrs: {} });
+    const without = canonicalizeContent({ type: 'paragraph' });
+    expect(withEmpty).toEqual(without);
+  });
+
+  it('keeps comment marks + commentId but normalizes resolved:false default (SPEC §3 anchor)', () => {
+    const out = canonicalizeContent({
+      type: 'text',
+      text: 'anchored',
+      marks: [
+        { type: 'comment', attrs: { commentId: 'cmt-1', resolved: false } },
+      ],
+    });
+    // The comment mark is preserved; commentId (a meaningful anchor) survives,
+    // but the `resolved: false` schema default is normalized away.
+    expect(out.marks).toEqual([
+      { type: 'comment', attrs: { commentId: 'cmt-1' } },
+    ]);
+  });
+
+  it('drops known non-null schema defaults (link target/rel, comment resolved)', () => {
+    const out = canonicalizeContent({
+      type: 'text',
+      text: 'a link',
+      marks: [
+        {
+          type: 'link',
+          attrs: {
+            href: 'https://example.com/page',
+            target: '_blank',
+            rel: 'noopener noreferrer nofollow',
+          },
+        },
+      ],
+    });
+    // href (non-default) kept; target/rel (schema defaults) dropped.
+    expect(out.marks).toEqual([
+      { type: 'link', attrs: { href: 'https://example.com/page' } },
+    ]);
+  });
+
+  it('keeps a NON-default value that happens to share an attr name (orderedList start:5)', () => {
+    const out = canonicalizeContent({
+      type: 'orderedList',
+      attrs: { id: 'ol-1', start: 5 },
+      content: [],
+    });
+    // start:5 is NOT the default (1), so it must survive.
+    expect(out.attrs).toEqual({ start: 5 });
+  });
+
+  it('keeps meaningful node/mark attrs (level, language, href, src, width)', () => {
+    const out = canonicalizeContent({
+      type: 'doc',
+      content: [
+        {
+          type: 'codeBlock',
+          attrs: { id: 'c-1', language: 'js' },
+          content: [{ type: 'text', text: 'x' }],
+        },
+        {
+          type: 'image',
+          attrs: { id: 'i-1', src: '/a.png', width: 100, height: null },
+        },
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'link',
+              marks: [{ type: 'link', attrs: { href: 'https://e.com' } }],
+            },
+          ],
+        },
+      ],
+    });
+    expect(out.content[0].attrs).toEqual({ language: 'js' });
+    expect(out.content[1].attrs).toEqual({ src: '/a.png', width: 100 });
+    expect(out.content[2].content[0].marks[0].attrs).toEqual({
+      href: 'https://e.com',
+    });
+  });
+
+  it('preserves text, type and content order exactly', () => {
+    const input = {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'one' },
+        { type: 'text', text: 'two', marks: [{ type: 'bold' }] },
+        { type: 'text', text: 'three' },
+      ],
+    };
+    const out = canonicalizeContent(input);
+    expect(out.content.map((n: any) => n.text)).toEqual([
+      'one',
+      'two',
+      'three',
+    ]);
+    expect(out.content[1].marks).toEqual([{ type: 'bold' }]);
+  });
+
+  it('drops an empty marks array (marks:[] === no marks)', () => {
+    const out = canonicalizeContent({ type: 'text', text: 'x', marks: [] });
+    expect('marks' in out).toBe(false);
+  });
+
+  it('does not mutate its input (frozen tree passes through unchanged)', () => {
+    const input = Object.freeze({
+      type: 'doc',
+      content: Object.freeze([
+        Object.freeze({
+          type: 'paragraph',
+          attrs: Object.freeze({ id: 'p-1', indent: null }),
+          content: Object.freeze([Object.freeze({ type: 'text', text: 'x' })]),
+        }),
+      ]),
+    });
+    const before = JSON.stringify(input);
+    const out = canonicalizeContent(input);
+    // Input is structurally identical after the call.
+    expect(JSON.stringify(input)).toBe(before);
+    // A fresh tree is returned.
+    expect(out).not.toBe(input);
+    expect('attrs' in out.content[0]).toBe(false);
+  });
+});
+
+describe('docsCanonicallyEqual', () => {
+  it('is true when docs differ only by block ids', () => {
+    const a = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { id: 'h-1', level: 1 }, content: [] },
+      ],
+    };
+    const b = {
+      type: 'doc',
+      content: [
+        { type: 'heading', attrs: { id: 'h-DIFFERENT', level: 1 }, content: [] },
+      ],
+    };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is true when one side omits an attr the other sets to default null', () => {
+    const a = {
+      type: 'paragraph',
+      attrs: { id: 'p-1' },
+      content: [{ type: 'text', text: 'x' }],
+    };
+    const b = {
+      type: 'paragraph',
+      attrs: { id: 'p-2', indent: null, textAlign: null },
+      content: [{ type: 'text', text: 'x' }],
+    };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is key-order-insensitive for attrs', () => {
+    const a = { type: 'image', attrs: { src: '/a.png', width: 10 } };
+    const b = { type: 'image', attrs: { width: 10, src: '/a.png' } };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is false for a real text difference', () => {
+    const a = { type: 'text', text: 'hello' };
+    const b = { type: 'text', text: 'world' };
+    expect(docsCanonicallyEqual(a, b)).toBe(false);
+  });
+
+  it('is false for a real attr difference (different level)', () => {
+    const a = { type: 'heading', attrs: { id: 'x', level: 1 } };
+    const b = { type: 'heading', attrs: { id: 'y', level: 2 } };
+    expect(docsCanonicallyEqual(a, b)).toBe(false);
+  });
+
+  it('is false when a meaningful mark attr differs (commentId)', () => {
+    const a = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
+    };
+    const b = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-2' } }],
+    };
+    expect(docsCanonicallyEqual(a, b)).toBe(false);
+  });
+
+  it('is true when a link has only href vs one with the schema-default target/rel', () => {
+    const a = {
+      type: 'text',
+      text: 'link',
+      marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
+    };
+    const b = {
+      type: 'text',
+      text: 'link',
+      marks: [
+        {
+          type: 'link',
+          attrs: {
+            href: 'https://example.com',
+            target: '_blank',
+            rel: 'noopener noreferrer nofollow',
+          },
+        },
+      ],
+    };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is true when an orderedList omits start vs one with the default start:1', () => {
+    const a = { type: 'orderedList', content: [] };
+    const b = { type: 'orderedList', attrs: { start: 1 }, content: [] };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is false when an orderedList has a non-default start (5 vs absent)', () => {
+    const a = { type: 'orderedList', content: [] };
+    const b = { type: 'orderedList', attrs: { start: 5 }, content: [] };
+    expect(docsCanonicallyEqual(a, b)).toBe(false);
+  });
+
+  it('is true when a comment mark omits resolved vs one with the default false', () => {
+    const a = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
+    };
+    const b = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1', resolved: false } }],
+    };
+    expect(docsCanonicallyEqual(a, b)).toBe(true);
+  });
+
+  it('is false when a comment mark is dropped entirely', () => {
+    const a = {
+      type: 'text',
+      text: 'x',
+      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
+    };
+    const b = { type: 'text', text: 'x' };
+    expect(docsCanonicallyEqual(a, b)).toBe(false);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts b/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
new file mode 100644
index 00000000..d8ffc5fe
--- /dev/null
+++ b/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+  docsCanonicallyEqual,
+} from 'docmost-client';
+
+// Helper mirroring the convention in markdown-converter.test.ts: wrap atoms in
+// a top-level doc node so convertProseMirrorToMarkdown (which requires
+// content.content) walks them.
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+
+describe('diagram round-trip (docmost-schema diagramAttributes)', () => {
+  // SPEC case 1: drawio carrying the full numeric-attr surface
+  // (data-width/data-height/data-size/data-aspect-ratio) that it shares with
+  // audio/video/pdf but which no fixture exercises on a diagram node.
+  it('drawio round-trips numeric attrs, coercing number -> string via getAttribute', async () => {
+    const input = doc({
+      type: 'drawio',
+      attrs: {
+        src: '/d.drawio',
+        attachmentId: 'att-1',
+        width: 640,
+        height: 480,
+        size: 1234,
+        aspectRatio: 1.777,
+        align: 'center',
+      },
+    });
+
+    const md1 = convertProseMirrorToMarkdown(input);
+    const doc2 = await markdownToProseMirror(md1);
+    const md2 = convertProseMirrorToMarkdown(doc2);
+
+    // Exact serialized form: numbers render as bare data-* values; attribute
+    // order follows the converter's emit order (src, then width/height/size/
+    // aspect-ratio/align, then attachment-id).
+    expect(md1).toBe(
+      '<div data-type="drawio" data-src="/d.drawio" data-width="640" data-height="480" data-size="1234" data-aspect-ratio="1.777" data-align="center" data-attachment-id="att-1"></div>',
+    );
+
+    // A second export reproduces the first byte-for-byte (drawio align default
+    // is already "center", so nothing new materializes on import).
+    expect(md2).toBe(md1);
+
+    // Re-import coerces every numeric attr to a STRING because parseHTML reads
+    // them via getAttribute(). This is the gap the reviewer flagged: the
+    // number -> string coercion on a diagram node is otherwise untested.
+    const attrs2 = doc2.content[0].attrs;
+    expect(attrs2.width).toBe('640');
+    expect(attrs2.height).toBe('480');
+    expect(attrs2.size).toBe('1234');
+    expect(attrs2.aspectRatio).toBe('1.777');
+    expect(typeof attrs2.width).toBe('string');
+    expect(typeof attrs2.aspectRatio).toBe('string');
+    // String attrs pass through unchanged.
+    expect(attrs2.align).toBe('center');
+    expect(attrs2.attachmentId).toBe('att-1');
+
+    // Canonically NOT equal: the numeric -> string coercion survives
+    // canonicalization (only align='center' is normalized away via
+    // KNOWN_DEFAULTS.drawio), so 640 !== '640' makes the docs differ.
+    expect(docsCanonicallyEqual(input, doc2)).toBe(false);
+  });
+
+  // SPEC case 2: minimal excalidraw atom with ONLY string attrs (no align, no
+  // numeric attrs). Locks the one-time export divergence (align='center'
+  // default materializes only on import) plus escapeAttr of title/alt through
+  // the data-title/data-alt path.
+  it('excalidraw materializes align default only on import and escapes title/alt', async () => {
+    const input = doc({
+      type: 'excalidraw',
+      attrs: {
+        src: '/e.excalidraw',
+        title: 'My "Diagram"',
+        alt: 'a&b',
+      },
+    });
+
+    const md1 = convertProseMirrorToMarkdown(input);
+    const doc2 = await markdownToProseMirror(md1);
+    const md2 = convertProseMirrorToMarkdown(doc2);
+
+    // First export: no align emitted (the input doc carries no align), and the
+    // " in title becomes &quot;, the & in alt becomes &amp; via escapeAttr.
+    expect(md1).toBe(
+      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b"></div>',
+    );
+
+    // Second export: align='center' has now materialized (the schema's
+    // diagramAttributes default), so md2 gains a data-align="center" suffix and
+    // is NOT byte-equal to md1. This one-time divergence is the diagram quirk.
+    expect(md2).toBe(
+      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b" data-align="center"></div>',
+    );
+    expect(md2).not.toBe(md1);
+
+    // Re-import decodes the escaped entities back to the original characters.
+    const attrs2 = doc2.content[0].attrs;
+    expect(attrs2.title).toBe('My "Diagram"');
+    expect(attrs2.alt).toBe('a&b');
+    expect(attrs2.align).toBe('center');
+
+    // Canonically EQUAL: align='center' is normalized away via
+    // KNOWN_DEFAULTS.excalidraw, and title/alt are non-default strings that
+    // survive on both sides, so the docs are semantically equal.
+    expect(docsCanonicallyEqual(input, doc2)).toBe(true);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/docmost-schema-attrs.test.ts b/packages/prosemirror-markdown/test/docmost-schema-attrs.test.ts
new file mode 100644
index 00000000..fb7a3591
--- /dev/null
+++ b/packages/prosemirror-markdown/test/docmost-schema-attrs.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import {
+  sanitizeCssColor,
+  clampCalloutType,
+  encodeHtmlEmbedSource,
+  decodeHtmlEmbedSource,
+} from '../src/lib/docmost-schema.js';
+
+// These tests pin the two security/normalization helpers that Docmost
+// interpolates into inline style and the callout banner type on re-render.
+// They are the allowlist guard (XSS/style-breakout boundary) and the
+// case-insensitive callout normalizer, both otherwise only exercised
+// indirectly through parseHTML/renderHTML.
+
+describe('sanitizeCssColor', () => {
+  it('accepts a plain named color unchanged', () => {
+    expect(sanitizeCssColor('red')).toBe('red');
+  });
+
+  it('accepts 3-digit and 6-digit hex colors unchanged', () => {
+    expect(sanitizeCssColor('#abc')).toBe('#abc');
+    expect(sanitizeCssColor('#aabbcc')).toBe('#aabbcc');
+  });
+
+  it('accepts well-formed functional notation unchanged', () => {
+    expect(sanitizeCssColor('rgb(1,2,3)')).toBe('rgb(1,2,3)');
+    expect(sanitizeCssColor('rgba(0,0,0,0.5)')).toBe('rgba(0,0,0,0.5)');
+    expect(sanitizeCssColor('hsl(120,50%,50%)')).toBe('hsl(120,50%,50%)');
+  });
+
+  it('trims surrounding whitespace before matching', () => {
+    // '  blue  ' trims to 'blue', which is a valid named color.
+    expect(sanitizeCssColor('  blue  ')).toBe('blue');
+  });
+
+  it('rejects a style-injection payload (returns null)', () => {
+    expect(sanitizeCssColor('red; --x: url(x)')).toBeNull();
+  });
+
+  it('rejects an attribute-breakout payload (returns null)', () => {
+    expect(sanitizeCssColor('red"><script>')).toBeNull();
+  });
+
+  it('rejects the empty string (returns null)', () => {
+    expect(sanitizeCssColor('')).toBeNull();
+  });
+
+  it('rejects non-string input via the typeof guard (returns null)', () => {
+    // @ts-expect-error deliberately passing a non-string to exercise the guard
+    expect(sanitizeCssColor(123)).toBeNull();
+  });
+});
+
+describe('clampCalloutType', () => {
+  it('lowercases an uppercase valid type', () => {
+    expect(clampCalloutType('INFO')).toBe('info');
+  });
+
+  it('lowercases a mixed-case valid type', () => {
+    expect(clampCalloutType('Warning')).toBe('warning');
+  });
+
+  it('passes through already-lowercase valid types', () => {
+    expect(clampCalloutType('danger')).toBe('danger');
+    expect(clampCalloutType('success')).toBe('success');
+  });
+
+  it('PRESERVES every editor-canonical type (note/default no longer flattened)', () => {
+    // Regression for the QA "callout type -> [!info]" fidelity loss: `note` and
+    // `default` are valid editor callout types and must survive the git
+    // round-trip, not collapse to `info`.
+    expect(clampCalloutType('note')).toBe('note');
+    expect(clampCalloutType('default')).toBe('default');
+    expect(clampCalloutType('info')).toBe('info');
+    expect(clampCalloutType('warning')).toBe('warning');
+    expect(clampCalloutType('danger')).toBe('danger');
+    expect(clampCalloutType('success')).toBe('success');
+  });
+
+  it('maps GitHub/Obsidian alert ALIASES to the editor banner (not flatly info)', () => {
+    // The editor schema has no tip/caution/important callout node — they are input
+    // aliases the editor's own paste path maps onto the supported set
+    // (GITHUB_ALERT_TYPE_MAP in editor-ext). git-sync mirrors that aliasing so an
+    // ingested `> [!tip]` / `> [!caution]` lands on the closest real banner instead
+    // of collapsing everything to `info`.
+    expect(clampCalloutType('tip')).toBe('success');
+    expect(clampCalloutType('TIP')).toBe('success');
+    expect(clampCalloutType('caution')).toBe('danger');
+    expect(clampCalloutType('important')).toBe('info');
+  });
+
+  it('falls back to "info" for genuinely unknown types', () => {
+    expect(clampCalloutType('question')).toBe('info');
+    expect(clampCalloutType('banana')).toBe('info');
+  });
+
+  it('falls back to "info" for empty string and null', () => {
+    expect(clampCalloutType('')).toBe('info');
+    expect(clampCalloutType(null)).toBe('info');
+  });
+});
+
+// The htmlEmbed `source` rides the data-source attribute base64-encoded so the
+// raw HTML/CSS/JS stays inert and double-encoding-free across a round trip.
+// Encode/decode MUST be exact inverses (incl. UTF-8) or the embed body corrupts.
+describe('encode/decodeHtmlEmbedSource', () => {
+  it('round-trips ASCII HTML losslessly', () => {
+    const src = '<b>hi</b>';
+    expect(decodeHtmlEmbedSource(encodeHtmlEmbedSource(src))).toBe(src);
+  });
+
+  it('round-trips multi-byte UTF-8 (Cyrillic + emoji) losslessly', () => {
+    const src = '<p>Привет, мир 🌍 — café</p>';
+    const encoded = encodeHtmlEmbedSource(src);
+    // It is actually encoded (not passed through verbatim).
+    expect(encoded).not.toBe(src);
+    expect(decodeHtmlEmbedSource(encoded)).toBe(src);
+  });
+
+  it('maps empty string to empty string both ways', () => {
+    expect(encodeHtmlEmbedSource('')).toBe('');
+    expect(decodeHtmlEmbedSource('')).toBe('');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/01-headings-paragraphs.json b/packages/prosemirror-markdown/test/fixtures/corpus/01-headings-paragraphs.json
new file mode 100644
index 00000000..ebacda0e
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/01-headings-paragraphs.json
@@ -0,0 +1,36 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 1 },
+      "content": [{ "type": "text", "text": "Level one heading" }]
+    },
+    {
+      "type": "paragraph",
+      "content": [{ "type": "text", "text": "A plain paragraph of text." }]
+    },
+    {
+      "type": "heading",
+      "attrs": { "level": 2 },
+      "content": [{ "type": "text", "text": "Level two heading" }]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "First line of a paragraph" },
+        { "type": "hardBreak" },
+        { "type": "text", "text": "second line after a hard break." }
+      ]
+    },
+    {
+      "type": "heading",
+      "attrs": { "level": 3 },
+      "content": [{ "type": "text", "text": "Level three heading" }]
+    },
+    {
+      "type": "paragraph",
+      "content": [{ "type": "text", "text": "Closing paragraph." }]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/02-inline-marks.json b/packages/prosemirror-markdown/test/fixtures/corpus/02-inline-marks.json
new file mode 100644
index 00000000..41a9e618
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/02-inline-marks.json
@@ -0,0 +1,62 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "marks": [{ "type": "bold" }], "text": "bold" },
+        { "type": "text", "text": " " },
+        { "type": "text", "marks": [{ "type": "italic" }], "text": "italic" },
+        { "type": "text", "text": " " },
+        { "type": "text", "marks": [{ "type": "code" }], "text": "code" },
+        { "type": "text", "text": " " },
+        { "type": "text", "marks": [{ "type": "strike" }], "text": "strike" }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        {
+          "type": "text",
+          "marks": [
+            {
+              "type": "link",
+              "attrs": {
+                "href": "https://example.com/page"
+              }
+            }
+          ],
+          "text": "a link"
+        },
+        { "type": "text", "text": ", " },
+        {
+          "type": "text",
+          "marks": [{ "type": "highlight" }],
+          "text": "highlighted"
+        },
+        { "type": "text", "text": ", base" },
+        { "type": "text", "marks": [{ "type": "subscript" }], "text": "sub" },
+        { "type": "text", "text": " and base" },
+        { "type": "text", "marks": [{ "type": "superscript" }], "text": "sup" },
+        { "type": "text", "text": "." }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Here is a " },
+        {
+          "type": "text",
+          "marks": [
+            {
+              "type": "comment",
+              "attrs": { "commentId": "cmt-xyz789" }
+            }
+          ],
+          "text": "commented anchor span"
+        },
+        { "type": "text", "text": " that must survive (SPEC §3)." }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/03-lists.json b/packages/prosemirror-markdown/test/fixtures/corpus/03-lists.json
new file mode 100644
index 00000000..2b7209b5
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/03-lists.json
@@ -0,0 +1,113 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "bulletList",
+      "content": [
+        {
+          "type": "listItem",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "First bullet" }]
+            }
+          ]
+        },
+        {
+          "type": "listItem",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "Second bullet with a nested list" }]
+            },
+            {
+              "type": "bulletList",
+              "content": [
+                {
+                  "type": "listItem",
+                  "content": [
+                    {
+                      "type": "paragraph",
+                      "content": [{ "type": "text", "text": "Nested bullet A" }]
+                    }
+                  ]
+                },
+                {
+                  "type": "listItem",
+                  "content": [
+                    {
+                      "type": "paragraph",
+                      "content": [{ "type": "text", "text": "Nested bullet B" }]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "orderedList",
+      "content": [
+        {
+          "type": "listItem",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "First ordered item" }]
+            }
+          ]
+        },
+        {
+          "type": "listItem",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "Second ordered item" }]
+            },
+            {
+              "type": "orderedList",
+              "content": [
+                {
+                  "type": "listItem",
+                  "content": [
+                    {
+                      "type": "paragraph",
+                      "content": [{ "type": "text", "text": "Nested ordered one" }]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "taskList",
+      "content": [
+        {
+          "type": "taskItem",
+          "attrs": { "checked": true },
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "Done task" }]
+            }
+          ]
+        },
+        {
+          "type": "taskItem",
+          "attrs": { "checked": false },
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [{ "type": "text", "text": "Pending task" }]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/04-blocks.json b/packages/prosemirror-markdown/test/fixtures/corpus/04-blocks.json
new file mode 100644
index 00000000..4eb8a7e6
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/04-blocks.json
@@ -0,0 +1,38 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "blockquote",
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [{ "type": "text", "text": "A quoted line." }]
+        },
+        {
+          "type": "paragraph",
+          "content": [{ "type": "text", "text": "A second quoted paragraph." }]
+        }
+      ]
+    },
+    {
+      "type": "horizontalRule"
+    },
+    {
+      "type": "codeBlock",
+      "attrs": { "language": "js" },
+      "content": [
+        { "type": "text", "text": "const a = 1;\nconsole.log(a);\n" }
+      ]
+    },
+    {
+      "type": "callout",
+      "attrs": { "type": "warning" },
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [{ "type": "text", "text": "This is a warning callout." }]
+        }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/05-table.json b/packages/prosemirror-markdown/test/fixtures/corpus/05-table.json
new file mode 100644
index 00000000..3a062e7b
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/05-table.json
@@ -0,0 +1,85 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "table",
+      "content": [
+        {
+          "type": "tableRow",
+          "content": [
+            {
+              "type": "tableHeader",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "Name" }]
+                }
+              ]
+            },
+            {
+              "type": "tableHeader",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "Value" }]
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "tableRow",
+          "content": [
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "alpha" }]
+                }
+              ]
+            },
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "1" }]
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "tableRow",
+          "content": [
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "beta" }]
+                }
+              ]
+            },
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "2" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/06-diagrams.json b/packages/prosemirror-markdown/test/fixtures/corpus/06-diagrams.json
new file mode 100644
index 00000000..ea069091
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/06-diagrams.json
@@ -0,0 +1,17 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [{ "type": "text", "text": "A drawio and an excalidraw diagram follow." }]
+    },
+    {
+      "type": "drawio",
+      "attrs": { "src": "/api/files/def/flow.drawio", "align": "center", "attachmentId": "att-1" }
+    },
+    {
+      "type": "excalidraw",
+      "attrs": { "src": "/api/files/ghi/sketch.excalidraw", "align": "center", "attachmentId": "att-2" }
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/07-textstyle-mention.json b/packages/prosemirror-markdown/test/fixtures/corpus/07-textstyle-mention.json
new file mode 100644
index 00000000..9cfbcc8d
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/07-textstyle-mention.json
@@ -0,0 +1,35 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Some " },
+        {
+          "type": "text",
+          "marks": [{ "type": "textStyle", "attrs": { "color": "#ff0000" } }],
+          "text": "red colored"
+        },
+        { "type": "text", "text": " text." }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Ping " },
+        {
+          "type": "mention",
+          "attrs": {
+            "id": "m-1",
+            "label": "Alice",
+            "entityType": "user",
+            "entityId": "u-1",
+            "slugId": "s-1",
+            "creatorId": "c-1"
+          }
+        },
+        { "type": "text", "text": " please." }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/08-details.json b/packages/prosemirror-markdown/test/fixtures/corpus/08-details.json
new file mode 100644
index 00000000..74c26682
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/08-details.json
@@ -0,0 +1,15 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "details",
+      "attrs": { "open": false },
+      "content": [
+        { "type": "detailsSummary", "content": [{ "type": "text", "text": "Click to expand" }] },
+        { "type": "detailsContent", "content": [
+          { "type": "paragraph", "content": [{ "type": "text", "text": "Hidden body paragraph." }] }
+        ]}
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/09-columns.json b/packages/prosemirror-markdown/test/fixtures/corpus/09-columns.json
new file mode 100644
index 00000000..49c0abe6
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/09-columns.json
@@ -0,0 +1,17 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "columns",
+      "attrs": { "layout": "two", "widthMode": "normal" },
+      "content": [
+        { "type": "column", "attrs": { "width": 50 }, "content": [
+          { "type": "paragraph", "content": [{ "type": "text", "text": "Left column." }] }
+        ]},
+        { "type": "column", "attrs": { "width": 50 }, "content": [
+          { "type": "paragraph", "content": [{ "type": "text", "text": "Right column." }] }
+        ]}
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/corpus/10-mention-in-heading.json b/packages/prosemirror-markdown/test/fixtures/corpus/10-mention-in-heading.json
new file mode 100644
index 00000000..18fb0600
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/corpus/10-mention-in-heading.json
@@ -0,0 +1,13 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 2 },
+      "content": [
+        { "type": "text", "text": "Notes for " },
+        { "type": "mention", "attrs": { "id": "m-2", "label": "Bob", "entityType": "user", "entityId": "u-2", "slugId": "s-2", "creatorId": "c-2" } }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json b/packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json
new file mode 100644
index 00000000..2d8e12b7
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json
@@ -0,0 +1,21 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [{ "type": "text", "text": "An image followed by two diagrams." }]
+    },
+    {
+      "type": "image",
+      "attrs": { "src": "/api/files/abc/diagram.png", "alt": "A picture" }
+    },
+    {
+      "type": "drawio",
+      "attrs": { "src": "/api/files/def/flow.drawio", "attachmentId": "att-1" }
+    },
+    {
+      "type": "excalidraw",
+      "attrs": { "src": "/api/files/ghi/sketch.excalidraw", "attachmentId": "att-2" }
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/fixtures/sample-doc.json b/packages/prosemirror-markdown/test/fixtures/sample-doc.json
new file mode 100644
index 00000000..137a6bd0
--- /dev/null
+++ b/packages/prosemirror-markdown/test/fixtures/sample-doc.json
@@ -0,0 +1,151 @@
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 1, "id": "h-1" },
+      "content": [{ "type": "text", "text": "Round-trip sample" }]
+    },
+    {
+      "type": "paragraph",
+      "attrs": { "id": "p-1" },
+      "content": [
+        { "type": "text", "text": "This paragraph has " },
+        { "type": "text", "marks": [{ "type": "bold" }], "text": "bold" },
+        { "type": "text", "text": ", " },
+        { "type": "text", "marks": [{ "type": "italic" }], "text": "italic" },
+        { "type": "text", "text": " and a " },
+        {
+          "type": "text",
+          "marks": [
+            {
+              "type": "link",
+              "attrs": {
+                "href": "https://example.com"
+              }
+            }
+          ],
+          "text": "link"
+        },
+        { "type": "text", "text": "." }
+      ]
+    },
+    {
+      "type": "paragraph",
+      "attrs": { "id": "p-2" },
+      "content": [
+        { "type": "text", "text": "Here is a " },
+        {
+          "type": "text",
+          "marks": [
+            { "type": "comment", "attrs": { "commentId": "cmt-abc123", "resolved": false } }
+          ],
+          "text": "commented span"
+        },
+        { "type": "text", "text": " that must survive the round-trip." }
+      ]
+    },
+    {
+      "type": "bulletList",
+      "attrs": { "id": "ul-1" },
+      "content": [
+        {
+          "type": "listItem",
+          "attrs": { "id": "li-1" },
+          "content": [
+            {
+              "type": "paragraph",
+              "attrs": { "id": "p-3" },
+              "content": [{ "type": "text", "text": "First bullet" }]
+            }
+          ]
+        },
+        {
+          "type": "listItem",
+          "attrs": { "id": "li-2" },
+          "content": [
+            {
+              "type": "paragraph",
+              "attrs": { "id": "p-4" },
+              "content": [{ "type": "text", "text": "Second bullet" }]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "table",
+      "attrs": { "id": "tbl-1" },
+      "content": [
+        {
+          "type": "tableRow",
+          "content": [
+            {
+              "type": "tableHeader",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "Name" }]
+                }
+              ]
+            },
+            {
+              "type": "tableHeader",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "Value" }]
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "tableRow",
+          "content": [
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "alpha" }]
+                }
+              ]
+            },
+            {
+              "type": "tableCell",
+              "attrs": { "colspan": 1, "rowspan": 1 },
+              "content": [
+                {
+                  "type": "paragraph",
+                  "content": [{ "type": "text", "text": "1" }]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "type": "callout",
+      "attrs": { "type": "info", "id": "callout-1" },
+      "content": [
+        {
+          "type": "paragraph",
+          "attrs": { "id": "p-5" },
+          "content": [{ "type": "text", "text": "This is an info callout." }]
+        }
+      ]
+    },
+    {
+      "type": "codeBlock",
+      "attrs": { "language": "js", "id": "code-1" },
+      "content": [
+        { "type": "text", "text": "const a = 1;\nconsole.log(a);\n" }
+      ]
+    }
+  ]
+}
diff --git a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
new file mode 100644
index 00000000..47ab05bc
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
@@ -0,0 +1,845 @@
+import { describe, expect, it } from 'vitest';
+// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
+// pulls in collaboration.ts and mutates the global DOM at import time), matching
+// the other converter unit tests. markdownToProseMirror is imported for the
+// round-trip cases; loading it mutates the global DOM via jsdom (required for
+// @tiptap/html's generateJSON under Node) — this is expected.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+// Wrap one or more nodes in a minimal ProseMirror doc. The top-level converter
+// joins doc children with "\n\n" then .trim()s, so a single-node doc yields
+// exactly that node's rendered (trimmed) string.
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string) => ({ type: 'text', text: t });
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// Run a full export -> import -> export cycle and return both markdown strings
+// plus the intermediate ProseMirror doc (mirrors the property test's helper).
+async function roundTrip(node: any): Promise<{ md1: string; doc2: any; md2: string }> {
+  const md1 = convertProseMirrorToMarkdown(doc(node));
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, doc2, md2 };
+}
+
+// ---------------------------------------------------------------------------
+// 1. pageBreak DATA LOSS (markdown-converter.ts has NO `case "pageBreak"`).
+//
+// The schema declares a `pageBreak` block atom (docmost-schema.ts ~L1009), so a
+// real document CAN legally contain one. The converter's switch has no branch
+// for it, so it falls through to `default`, which renders only the node's
+// children — and a pageBreak atom has NONE. It therefore exports to "" and the
+// node silently disappears: an exported markdown file can never carry a page
+// break, and a round-trip cannot reconstruct it. We pin this as a known
+// divergence with an `it.fails` round-trip repro (mirroring the package's two
+// existing documented `it.fails` bugs in markdown-roundtrip.property.test.ts).
+// ---------------------------------------------------------------------------
+describe('pageBreak data loss (no converter case — SPEC §11 divergence)', () => {
+  it('exports a pageBreak node to the schema-matching block div', () => {
+    // FIXED: a standalone pageBreak now emits the block-level HTML div so the
+    // node survives instead of being erased to "".
+    expect(convertProseMirrorToMarkdown(doc({ type: 'pageBreak' }))).toBe(
+      '<div data-type="pageBreak"></div>',
+    );
+  });
+
+  it('keeps a pageBreak sitting BETWEEN two paragraphs on export', () => {
+    // FIXED: with surrounding content the divider is emitted as its own block
+    // between the two paragraphs (joined by the doc "\n\n"), no longer dropped.
+    const out = convertProseMirrorToMarkdown(
+      doc(para(text('before')), { type: 'pageBreak' }, para(text('after'))),
+    );
+    expect(out).toBe(
+      'before\n\n<div data-type="pageBreak"></div>\n\nafter',
+    );
+    expect(out).toContain('pageBreak');
+  });
+
+  // FIXED: a pageBreak node now survives an export -> import -> export cycle
+  // because the FIRST export emits the schema-matching block div, which marked
+  // passes through and generateJSON rebuilds into a pageBreak node again.
+  it('a pageBreak node round-trips (export -> import yields a pageBreak)', async () => {
+    const { md1, doc2 } = await roundTrip({ type: 'pageBreak' });
+    expect(md1).not.toBe('');
+    const types = (doc2.content || []).map((n: any) => n.type);
+    expect(types).toContain('pageBreak');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. subpages round-trip (`case "subpages"` emits the schema-matching div).
+//
+// It used to emit the literal `{{SUBPAGES}}`, which has no markdown/HTML meaning,
+// so on re-import the subpages BLOCK came back as a plain PARAGRAPH carrying the
+// literal string (the embed rendered as visible "{{SUBPAGES}}" text on the page
+// after a sync — data loss). It now emits `<div data-type="subpages">` like the
+// other embed nodes, so the schema's parseHTML rebuilds the subpages node.
+// ---------------------------------------------------------------------------
+describe('subpages round-trip (schema-matching div)', () => {
+  it('emits the subpages div and re-imports as a subpages node (no literal leak)', async () => {
+    const { md1, doc2 } = await roundTrip({ type: 'subpages' });
+    expect(md1).toBe('<div data-type="subpages"></div>');
+
+    const collect = (n: any): string[] => [
+      n.type,
+      ...((n.content || []) as any[]).flatMap(collect),
+    ];
+    const allTypes = (doc2.content || []).flatMap(collect);
+    // The subpages node survives, and no literal {{SUBPAGES}} text leaked back.
+    expect(allTypes).toContain('subpages');
+    expect(JSON.stringify(doc2)).not.toContain('{{SUBPAGES}}');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. column.width number<->string drift (`case "column"` + width parseHTML).
+//
+// The converter emits the width verbatim into `data-width="..."` (a STRING in
+// the HTML, as all HTML attributes are). On import the schema's `column.width`
+// parseHTML does `parseFloat(value)`, so the attribute always comes back as a
+// NUMBER. A document authored/stored with a STRING fractional width therefore
+// DRIFTS to a number across a round-trip at the ProseMirror-doc level — even
+// though the emitted MARKDOWN stays byte-stable (the number prints the same).
+// Pinned here as a documented attribute-type divergence (SPEC §11).
+// ---------------------------------------------------------------------------
+describe('column.width number<->string drift (schema parseFloat — SPEC §11)', () => {
+  const columnsWith = (width: any) => ({
+    type: 'columns',
+    attrs: { layout: 'two' },
+    content: [
+      { type: 'column', attrs: { width }, content: [para(text('L'))] },
+      { type: 'column', content: [para(text('R'))] },
+    ],
+  });
+
+  it('a STRING fractional width drifts to a NUMBER across the round-trip', async () => {
+    const { md1, doc2, md2 } = await roundTrip(columnsWith('33.3'));
+
+    // The emitted markdown carries the value as an HTML attribute string and is
+    // byte-stable across the cycle (the divergence is at the doc level only).
+    expect(md1).toContain('data-width="33.3"');
+    expect(md2).toBe(md1);
+
+    // But the doc attribute type changed: authored as string "33.3", it comes
+    // back as the number 33.3 (schema's parseFloat). This is the drift.
+    const rtWidth = doc2.content?.[0]?.content?.[0]?.attrs?.width;
+    expect(typeof rtWidth).toBe('number');
+    expect(rtWidth).toBe(33.3);
+  });
+
+  it('a NUMBER fractional width keeps its value (no precision loss) and is byte-stable', async () => {
+    const { md1, doc2, md2 } = await roundTrip(columnsWith(33.333333));
+    expect(md1).toContain('data-width="33.333333"');
+    expect(md2).toBe(md1);
+    const rtWidth = doc2.content?.[0]?.content?.[0]?.attrs?.width;
+    expect(typeof rtWidth).toBe('number');
+    expect(rtWidth).toBe(33.333333);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5b. EMPTY detailsContent (`case "details"` with an empty body).
+//
+// detailsContent's schema content is `block*` (docmost-schema.ts ~L474), so an
+// empty details body is legal. The converter must handle a `detailsContent`
+// with no children without crashing and without emitting invalid output that
+// breaks the round-trip. This pins that an empty details body exports cleanly
+// and re-imports as a valid `details` whose body is an empty `detailsContent`.
+// ---------------------------------------------------------------------------
+describe('empty detailsContent (schema allows block*)', () => {
+  const emptyDetails = doc({
+    type: 'details',
+    content: [
+      { type: 'detailsSummary', content: [text('Summary')] },
+      { type: 'detailsContent', content: [] },
+    ],
+  });
+
+  it('exports an empty details body without crashing or producing junk', () => {
+    const md = convertProseMirrorToMarkdown(emptyDetails);
+    // The summary survives and the <details> wrapper closes; the empty body adds
+    // no content of its own.
+    expect(md).toContain('<summary>Summary</summary>');
+    expect(md).toContain('</details>');
+    expect(md).not.toContain('undefined');
+    expect(md).not.toContain('null');
+  });
+
+  it('round-trips to a valid details with an empty detailsContent body', async () => {
+    const md1 = convertProseMirrorToMarkdown(emptyDetails);
+    const doc2 = await markdownToProseMirror(md1);
+    const md2 = convertProseMirrorToMarkdown(doc2);
+    // Export is byte-stable (no growth / no junk on the second pass).
+    expect(md2).toBe(md1);
+
+    // The re-imported tree is a details with summary + an empty content body.
+    const details = doc2.content?.[0];
+    expect(details?.type).toBe('details');
+    const childTypes = (details?.content || []).map((c: any) => c.type);
+    expect(childTypes).toEqual(['detailsSummary', 'detailsContent']);
+    const detailsContent = details.content.find(
+      (c: any) => c.type === 'detailsContent',
+    );
+    // block* — an empty body has no (or empty) content, which is valid.
+    expect(detailsContent.content == null || detailsContent.content.length === 0).toBe(
+      true,
+    );
+  });
+});
+
+// ===========================================================================
+// CONVERTER GAP COVERAGE (specs 1–29)
+//
+// These describe the converter's exact emission for under-tested branches and,
+// for the round-trip cases, pin export byte-stability and/or documented data
+// loss. docsCanonicallyEqual is imported here (not at the top) to keep the
+// existing block's imports untouched. heading/col are local helpers; doc/text/
+// para are reused from the top of the file.
+// ===========================================================================
+import { docsCanonicallyEqual } from '../src/lib/canonicalize.js';
+
+const heading = (level: number, ...inline: any[]) => ({
+  type: 'heading',
+  attrs: { level },
+  content: inline,
+});
+// A two-layout columns block carrying a single column with exactly one child —
+// the shared shape for the raw-HTML-container round-trip specs (15, 17–29).
+const oneColumn = (child: any) => ({
+  type: 'columns',
+  attrs: { layout: 'two' },
+  content: [{ type: 'column', content: [child] }],
+});
+// Extract the single column's single child node from a round-tripped doc.
+const colChildOf = (doc2: any) =>
+  doc2?.content?.[0]?.content?.[0]?.content?.[0];
+
+describe('converter gap coverage — emission branches (specs 1–11)', () => {
+  // 1. orderedList renders index+1 and DROPS the start attribute.
+  it('orderedList start:5 restarts numbering at 1 (start attr ignored)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'orderedList',
+        attrs: { start: 5 },
+        content: [
+          { type: 'listItem', content: [para(text('a'))] },
+          { type: 'listItem', content: [para(text('b'))] },
+        ],
+      }),
+    );
+    expect(out).toBe('1. a\n2. b');
+  });
+
+  // 2. An empty paragraph contributes an empty segment between two "\n\n" joins.
+  it('an empty paragraph between two paragraphs yields doubled blank lines', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(para(text('a')), { type: 'paragraph' }, para(text('b'))),
+    );
+    expect(out).toBe('a\n\n\n\nb');
+  });
+
+  // 3. A code block inside a blockquote: every physical line gets "> ".
+  it('a codeBlock inside a blockquote prefixes every fence/code line with "> "', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'blockquote',
+        content: [
+          {
+            type: 'codeBlock',
+            attrs: { language: 'js' },
+            content: [text('a\nb')],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe('> ```js\n> a\n> b\n> ```');
+  });
+
+  // 4. A body cell with TWO block children (paragraph + bulletList) cannot be a
+  //    GFM pipe row (inline-only). #8 emits the WHOLE table as HTML <table> so
+  //    the paragraph and the list each survive as their own block instead of
+  //    being lossily flattened into one "p1 - a" pipe cell.
+  it('a table cell with paragraph+list emits an HTML <table> (blocks preserved)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [{ type: 'tableHeader', content: [para(text('h'))] }],
+          },
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                content: [
+                  para(text('p1')),
+                  {
+                    type: 'bulletList',
+                    content: [{ type: 'listItem', content: [para(text('a'))] }],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe(
+      '<table><tbody><tr><th><p>h</p></th></tr><tr><td><p>p1</p><ul><li><p>a</p></li></ul></td></tr></tbody></table>',
+    );
+  });
+
+  // 5. code + link co-occur: the schema's `code` mark excludes all other marks
+  //    (including link), so the link cannot survive import. The lossless,
+  //    byte-stable behavior is to emit ONLY the backtick code span (code wins).
+  it('a code+link run emits the backtick code form (code wins, link dropped)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(
+        para({
+          type: 'text',
+          text: 'x',
+          marks: [
+            { type: 'code' },
+            { type: 'link', attrs: { href: 'http://a?b&c"d' } },
+          ],
+        }),
+      ),
+    );
+    expect(out).toBe('`x`');
+  });
+
+  // 6. hardBreak inside a heading: prefix applied once, "  \n" between a and b.
+  it('a hardBreak inside an h2 heading produces "## a  \\nb"', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(heading(2, text('a'), { type: 'hardBreak' }, text('b'))),
+    );
+    expect(out).toBe('## a  \nb');
+  });
+
+  // 7. encodeMdUrl's non-space whitespace sub-path: a newline -> %0A.
+  it('an image src containing a newline percent-encodes it to %0A', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({ type: 'image', attrs: { alt: 'cap', src: '/a\nb.png' } }),
+    );
+    expect(out).toBe('![cap](/a%0Ab.png)');
+  });
+
+  // 8. spanned-table HTML fallback: rowspan>1 AND align cell-attr branches, <td>.
+  it('a spanned cell with rowspan+align emits <td rowspan align> in that order', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                attrs: { rowspan: 2, align: 'center' },
+                content: [para(text('m'))],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe(
+      '<table><tbody><tr><td rowspan="2" align="center"><p>m</p></td></tr></tbody></table>',
+    );
+  });
+
+  // 9. taskItem fixed indent width of 2 (NOT prefix.length+1) for a nested sublist.
+  it('a task item with a nested bullet sublist indents the sublist by 2 columns', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'taskList',
+        content: [
+          {
+            type: 'taskItem',
+            attrs: { checked: false },
+            content: [
+              para(text('top')),
+              {
+                type: 'bulletList',
+                content: [
+                  { type: 'listItem', content: [para(text('child'))] },
+                ],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe('- [ ] top\n  - child');
+  });
+
+  // 10. A bulletList inside a blockquote: each list line independently prefixed.
+  it('a bulletList inside a blockquote prefixes every list line with "> "', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'blockquote',
+        content: [
+          {
+            type: 'bulletList',
+            content: [
+              { type: 'listItem', content: [para(text('x'))] },
+              { type: 'listItem', content: [para(text('y'))] },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe('> - x\n> - y');
+  });
+
+  // 11. A non-spanned cell with TWO block paragraphs: #8 emits the whole table
+  //     as HTML <table>, so each paragraph stays its own <p> and the literal
+  //     pipe needs no escaping inside HTML text (the old GFM path space-joined
+  //     the blocks into one line and escaped the pipe to \|).
+  it('a table cell with two paragraphs emits an HTML <table> (blocks kept, no pipe-escape)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [{ type: 'tableHeader', content: [para(text('h'))] }],
+          },
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                content: [para(text('a|b')), para(text('c'))],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe(
+      '<table><tbody><tr><th><p>h</p></th></tr><tr><td><p>a|b</p><p>c</p></td></tr></tbody></table>',
+    );
+  });
+});
+
+describe('converter gap coverage — documented round-trip data loss (specs 12–14)', () => {
+  // 12. A 3-backtick fence inside a codeBlock body is now lengthened: the outer
+  //     fence widens to (longest inner run + 1) backticks per CommonMark, so the
+  //     inner ``` is treated as content and the block survives as ONE node.
+  it('a triple-backtick fence inside a codeBlock body round-trips via a widened fence', async () => {
+    const d = doc({
+      type: 'codeBlock',
+      attrs: { language: 'js' },
+      content: [{ type: 'text', text: '```\ninner\n```' }],
+    });
+    const md1 = convertProseMirrorToMarkdown(d);
+    // Outer fence widened to 4 backticks; the inner 3-backtick fence is content.
+    expect(md1).toBe('````js\n```\ninner\n```\n````');
+
+    const doc2 = await markdownToProseMirror(md1);
+    // The block survives as a SINGLE code block (no premature split).
+    const top = doc2.content || [];
+    expect(top).toHaveLength(1);
+    expect(top[0].type).toBe('codeBlock');
+    expect(top[0].attrs?.language).toBe('js');
+    expect(top[0].content?.[0]?.text).toContain('```\ninner\n```');
+
+    const md2 = convertProseMirrorToMarkdown(doc2);
+    expect(md2).toBe(md1); // byte-stable
+    // Canonically the re-imported code text gains a single trailing newline
+    // (marked re-adds it; the exporter strips it back, hence byte stability).
+    // The fence is no longer lossy: the inner fence and content fully survive.
+    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
+  });
+
+  // 13. A leading ordered-list marker in paragraph text is NOT escaped, so a
+  //     plain paragraph silently becomes an orderedList on re-import.
+  it('a paragraph starting with "1. " is promoted to an orderedList on re-import', async () => {
+    const d = doc({
+      type: 'paragraph',
+      content: [{ type: 'text', text: '1. not a list' }],
+    });
+    const md1 = convertProseMirrorToMarkdown(d);
+    expect(md1).toBe('1. not a list'); // no backslash escape
+
+    const doc2 = await markdownToProseMirror(md1);
+    expect(doc2.content?.[0]?.type).toBe('orderedList');
+    const li = doc2.content[0].content?.[0];
+    expect(li?.type).toBe('listItem');
+    expect(li.content?.[0]?.content?.[0]).toMatchObject({
+      type: 'text',
+      text: 'not a list', // the "1. " was consumed as a list marker
+    });
+    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
+  });
+
+  // 14. The image emitter drops the title attribute (silently lost on round-trip).
+  it('an image title attribute is dropped on export and lost on re-import', async () => {
+    const d = doc({
+      type: 'image',
+      attrs: { src: '/i.png', alt: 'a', title: 't"q' },
+    });
+    const md1 = convertProseMirrorToMarkdown(d);
+    expect(md1).toBe('![a](/i.png)'); // no title, no quotes
+
+    const doc2 = await markdownToProseMirror(md1);
+    const img = (doc2.content || []).find((n: any) => n.type === 'image');
+    expect(img).toBeTruthy();
+    expect(img.attrs?.title).toBeNull(); // the original 't"q' was dropped
+    expect(img.attrs?.src).toBe('/i.png');
+    expect(img.attrs?.alt).toBe('a');
+    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
+  });
+});
+
+describe('converter gap coverage — raw-HTML container round-trips (specs 15–29)', () => {
+  // 15. image inside a column: imageToHtml width+align arms; byte-stable; no
+  //     literal-markdown text node leaks.
+  it('an image in a column emits <img> (width/align arms) and round-trips byte-stable', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({
+        type: 'image',
+        attrs: { src: '/i.png', alt: 'cap', width: 320, align: 'center' },
+      }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><img src="/i.png" alt="cap" width="320" align="center"></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('image');
+  });
+
+  // 16. image inside a SPANNED table cell (the other raw-HTML container).
+  it('an image in a spanned table cell emits <img> (width arm) and round-trips byte-stable', async () => {
+    const { md1, md2 } = await roundTrip({
+      type: 'table',
+      content: [
+        {
+          type: 'tableRow',
+          content: [
+            {
+              type: 'tableCell',
+              attrs: { colspan: 2 },
+              content: [
+                {
+                  type: 'image',
+                  attrs: { src: '/i.png', alt: 'x', width: 100 },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    expect(md1).toBe(
+      '<table><tbody><tr><td colspan="2"><img src="/i.png" alt="x" width="100"></td></tr></tbody></table>',
+    );
+    expect(md2).toBe(md1);
+  });
+
+  // 17. callout inside a column: calloutToHtml lower-cases the type; byte-stable.
+  it('a callout in a column emits the HTML div (type lower-cased) and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({
+        type: 'callout',
+        attrs: { type: 'WARNING' },
+        content: [para(text('a'))],
+      }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><div data-type="callout" data-callout-type="warning"><p>a</p></div></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('callout');
+  });
+
+  // 18. details tree inside a column: summary via inlineToHtml, content via blockToHtml.
+  it('a details tree in a column emits <details>/<summary>/<div detailsContent> and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({
+        type: 'details',
+        content: [
+          { type: 'detailsSummary', content: [text('S')] },
+          { type: 'detailsContent', content: [para(text('body'))] },
+        ],
+      }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><details><summary data-type="detailsSummary">S</summary><div data-type="detailsContent"><p>body</p></div></details></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('details');
+  });
+
+  // 19. taskList inside a column: BOTH checked:true and checked:false arms.
+  it('a taskList in a column emits both data-checked arms and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({
+        type: 'taskList',
+        content: [
+          {
+            type: 'taskItem',
+            attrs: { checked: true },
+            content: [para(text('done'))],
+          },
+          {
+            type: 'taskItem',
+            attrs: { checked: false },
+            content: [para(text('todo'))],
+          },
+        ],
+      }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><ul data-type="taskList"><li data-type="taskItem" data-checked="true"><p>done</p></li><li data-type="taskItem" data-checked="false"><p>todo</p></li></ul></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('taskList');
+  });
+
+  // 20. bare taskItem (no wrapping taskList) inside a column self-wraps.
+  it('a bare taskItem in a column self-wraps in a single-item taskList and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({
+        type: 'taskItem',
+        attrs: { checked: false },
+        content: [para(text('lone'))],
+      }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><ul data-type="taskList"><li data-type="taskItem" data-checked="false"><p>lone</p></li></ul></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('taskList');
+  });
+
+  // 21. blockquote inside a column: real <blockquote>, not markdown "> q".
+  it('a blockquote in a column emits <blockquote> and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({ type: 'blockquote', content: [para(text('q'))] }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><blockquote><p>q</p></blockquote></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('blockquote');
+  });
+
+  // 22. horizontalRule inside a column: literal <hr>, not markdown "---".
+  it('a horizontalRule in a column emits <hr> and round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({ type: 'horizontalRule' }),
+    );
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><hr></div></div>',
+    );
+    expect(md2).toBe(md1);
+    expect(colChildOf(doc2)?.type).toBe('horizontalRule');
+  });
+
+  // 23. Unknown block type with NON-text block children -> <div>-wrap of children.
+  it('an unknown block with block children wraps them in <div> (no markdown leak)', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn({
+          type: 'someFutureBlock',
+          content: [para(text('a')), para(text('b'))],
+        }),
+      ),
+    );
+    expect(md1).toContain('<div><p>a</p><p>b</p></div>');
+    // No markdown paragraph separator survives inside the raw-HTML column.
+    expect(md1).toBe(
+      '<div data-type="columns" data-layout="two"><div data-type="column"><div><p>a</p><p>b</p></div></div></div>',
+    );
+  });
+
+  // 24. Unknown block with ONLY inline/text children -> <div>inlineToHtml</div>.
+  it('an unknown block with only inline children renders inline as HTML (marks not markdown)', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn({
+          type: 'someInlineOnlyBlock',
+          content: [text('hi'), { type: 'text', text: '!', marks: [{ type: 'bold' }] }],
+        }),
+      ),
+    );
+    expect(md1).toContain('<div>hi<strong>!</strong></div>');
+  });
+
+  // 25. mathBlock inside a column delegates through processNode (NOT $$ fence).
+  it('a mathBlock in a column delegates to processNode (HTML div, no $$ fence)', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(oneColumn({ type: 'mathBlock', attrs: { text: 'a^2+b^2' } })),
+    );
+    expect(md1).toContain(
+      '<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>',
+    );
+    expect(md1).not.toContain('$$');
+  });
+
+  // 26. SPANNED table inside a column delegates to processNode -> raw <table>.
+  it('a spanned table in a column delegates to raw <table> HTML (no GFM pipes)', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn({
+          type: 'table',
+          content: [
+            {
+              type: 'tableRow',
+              content: [
+                {
+                  type: 'tableCell',
+                  attrs: { colspan: 2 },
+                  content: [para(text('x'))],
+                },
+              ],
+            },
+          ],
+        }),
+      ),
+    );
+    expect(md1).toContain('<table');
+    expect(md1).toContain('colspan="2"');
+    // No GFM pipe-table separator leaked into the raw-HTML column.
+    expect(md1).not.toContain('| --- |');
+  });
+
+  // 27. list item with TWO block children (paragraph + codeBlock) -> blockChildrenToHtml.
+  it('a list item with paragraph+codeBlock in a column emits both blocks as HTML', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn({
+          type: 'bulletList',
+          content: [
+            {
+              type: 'listItem',
+              content: [
+                para(text('p')),
+                {
+                  type: 'codeBlock',
+                  attrs: { language: 'js' },
+                  content: [text('a\nb')],
+                },
+              ],
+            },
+          ],
+        }),
+      ),
+    );
+    expect(md1).toContain('<p>p</p>');
+    expect(md1).toContain('<pre><code class="language-js">a\nb</code></pre>');
+    // The two blocks appear sequentially inside the same <li>.
+    expect(md1).toContain(
+      '<li><p>p</p><pre><code class="language-js">a\nb</code></pre></li>',
+    );
+  });
+
+  // 28. ordered list item whose 2nd block child is a NESTED bulletList.
+  it('an ordered list item with a nested bulletList in a column emits nested <ul> HTML', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn({
+          type: 'orderedList',
+          content: [
+            {
+              type: 'listItem',
+              content: [
+                para(text('p1')),
+                {
+                  type: 'bulletList',
+                  content: [
+                    { type: 'listItem', content: [para(text('nested'))] },
+                  ],
+                },
+              ],
+            },
+          ],
+        }),
+      ),
+    );
+    // NOTE(review): the spec's expected literal said '<ul><li>nested</li></ul>',
+    // but blockChildrenToHtml renders the nested listItem's paragraph child as a
+    // real <p>, so the actual (correct) emission is '<ul><li><p>nested</p></li></ul>'.
+    expect(md1).toContain(
+      '<ol><li><p>p1</p><ul><li><p>nested</p></li></ul></li></ol>',
+    );
+    // No markdown list markers leaked into the raw-HTML column.
+    expect(md1).not.toContain('1. ');
+    expect(md1).not.toContain('- nested');
+  });
+
+  // 29. mathInline atom inside a column paragraph -> inlineToHtml delegates via processNode.
+  it('a mathInline atom in a column paragraph emits schema HTML (no $...$ fence)', () => {
+    const md1 = convertProseMirrorToMarkdown(
+      doc(oneColumn(para(text('eq: '), { type: 'mathInline', attrs: { text: 'x_i' } }))),
+    );
+    expect(md1).toContain(
+      '<p>eq: <span data-type="mathInline" data-katex="true" text="x_i"></span></p>',
+    );
+    expect(md1).not.toContain('$x_i$');
+  });
+});
+
+// ===========================================================================
+// 30. heading.textAlign round-trip (A1). The paragraph case already exports a
+// non-default alignment as a styled `<p style="text-align:…">` that re-parses
+// losslessly; headings used to emit only the bare `## text` form, silently
+// DROPPING textAlign on export. The heading case is now symmetric: an aligned
+// heading exports as `<hN style="text-align:…">` and re-parses back to a heading
+// carrying BOTH the level and the textAlign, so the round-trip is lossless; an
+// UNaligned heading still emits the bare `## text` markdown form (no churn).
+// ===========================================================================
+const alignedHeading = (level: number, align: string, ...inline: any[]) => ({
+  type: 'heading',
+  attrs: { level, textAlign: align },
+  content: inline,
+});
+
+describe('heading.textAlign round-trip (A1)', () => {
+  it('an aligned heading exports as <hN style="text-align:…"> (not bare ##)', () => {
+    expect(convertProseMirrorToMarkdown(doc(alignedHeading(2, 'center', text('Title'))))).toBe(
+      '<h2 style="text-align:center">Title</h2>',
+    );
+  });
+
+  it('survives export -> import -> export losslessly (level AND textAlign preserved)', async () => {
+    const input = alignedHeading(2, 'center', text('Title'));
+    const { md1, doc2, md2 } = await roundTrip(input);
+    // Export direction: a styled <hN>, injection-safe via escapeAttr.
+    expect(md1).toBe('<h2 style="text-align:center">Title</h2>');
+    // Import direction: re-parses to a heading node with the level AND textAlign
+    // (the raw <hN style> HTML block flows through marked -> generateJSON, where
+    // the heading parse rule matches and the textAlign global attr reads the
+    // style back). Byte-stable second export closes the loop.
+    const h = doc2.content[0];
+    expect(h.type).toBe('heading');
+    expect(h.attrs.level).toBe(2);
+    expect(h.attrs.textAlign).toBe('center');
+    expect(md2).toBe(md1);
+    // Canonical equality of the re-parsed doc against the original input doc.
+    expect(docsCanonicallyEqual(doc2, doc(input))).toBe(true);
+  });
+
+  it('a right-aligned h3 round-trips its level and alignment', async () => {
+    const { doc2 } = await roundTrip(alignedHeading(3, 'right', text('Head')));
+    const h = doc2.content[0];
+    expect(h.type).toBe('heading');
+    expect(h.attrs.level).toBe(3);
+    expect(h.attrs.textAlign).toBe('right');
+  });
+
+  it('an UNaligned heading still emits the bare "## text" form (no HTML churn)', () => {
+    const bare = convertProseMirrorToMarkdown(doc(heading(2, text('Plain'))));
+    expect(bare).toBe('## Plain');
+    expect(bare).not.toContain('<h2');
+    // The default "left" alignment is likewise NOT wrapped.
+    expect(
+      convertProseMirrorToMarkdown(doc(alignedHeading(2, 'left', text('Plain')))),
+    ).toBe('## Plain');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
new file mode 100644
index 00000000..f8ba6b76
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -0,0 +1,402 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates global DOM at import time).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+
+// markdown-converter.ts is the weakest pure module (report §2). These golden
+// tests close the gaps the base markdown-converter.test.ts leaves open:
+// columns/column wrapper, embed/audio/pdf (used to emit nothing), drawio/
+// excalidraw data-align presence rule, the remaining inline-mark matrix,
+// paragraph.textAlign, subpages + unknown-in-container fallback, escaping
+// idempotence, table-cell pipe/newline sanitization, and empty/single-column
+// tables. Cases already asserted in the base file are NOT repeated.
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const c = (node: any) => convertProseMirrorToMarkdown(doc(node));
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+describe('columns / column (raw-HTML layout wrapper)', () => {
+  it('wraps a multi-column layout as nested data-type divs with the children inside (regression: children unwrapped)', () => {
+    const out = c({
+      type: 'columns',
+      attrs: { layout: 'two' },
+      content: [
+        { type: 'column', attrs: { width: 50 }, content: [para(text('L'))] },
+        { type: 'column', content: [para(text('R'))] },
+      ],
+    });
+    expect(out).toBe(
+      '<div data-type="columns" data-layout="two">' +
+        '<div data-type="column" data-width="50"><p>L</p></div>' +
+        '<div data-type="column"><p>R</p></div>' +
+        '</div>',
+    );
+  });
+
+  it('omits the default widthMode "normal" but emits a non-default one', () => {
+    const normal = c({
+      type: 'columns',
+      attrs: { layout: 'two', widthMode: 'normal' },
+      content: [{ type: 'column', content: [para(text('x'))] }],
+    });
+    expect(normal).not.toContain('data-width-mode');
+    const wide = c({
+      type: 'columns',
+      attrs: { layout: 'two', widthMode: 'full' },
+      content: [{ type: 'column', content: [para(text('x'))] }],
+    });
+    expect(wide).toContain('data-width-mode="full"');
+  });
+});
+
+describe('embed / audio / pdf (previously emitted nothing — invisible regression)', () => {
+  it('embed emits div[data-type="embed"] with src/provider', () => {
+    expect(c({ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } })).toBe(
+      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
+    );
+  });
+
+  it('audio emits a div-wrapped <audio> with src', () => {
+    expect(c({ type: 'audio', attrs: { src: '/a.mp3' } })).toBe(
+      '<div><audio src="/a.mp3"></audio></div>',
+    );
+  });
+
+  it('pdf emits div[data-type="pdf"] with src and name', () => {
+    expect(c({ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf' } })).toBe(
+      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf"></div>',
+    );
+  });
+});
+
+describe('drawio / excalidraw data-align asymmetry (SPEC §11)', () => {
+  it('drawio: data-align is ABSENT when align is unset', () => {
+    const out = c({ type: 'drawio', attrs: { src: '/d.drawio' } });
+    expect(out).toBe('<div data-type="drawio" data-src="/d.drawio"></div>');
+    expect(out).not.toContain('data-align');
+  });
+
+  it('drawio: data-align is PRESENT for a non-default align', () => {
+    expect(c({ type: 'drawio', attrs: { src: '/d.drawio', align: 'right' } })).toBe(
+      '<div data-type="drawio" data-src="/d.drawio" data-align="right"></div>',
+    );
+  });
+
+  it('excalidraw: data-align is ABSENT when align is unset', () => {
+    const out = c({ type: 'excalidraw', attrs: { src: '/e.excalidraw' } });
+    expect(out).toBe('<div data-type="excalidraw" data-src="/e.excalidraw"></div>');
+    expect(out).not.toContain('data-align');
+  });
+});
+
+describe('inline-mark matrix (underline/sub/sup/highlight±color/textStyle/comment)', () => {
+  it('emits the schema HTML for each remaining inline mark in one matrix', () => {
+    const cases: [any[], string][] = [
+      [[{ type: 'underline' }], '<u>m</u>'],
+      [[{ type: 'subscript' }], '<sub>m</sub>'],
+      [[{ type: 'superscript' }], '<sup>m</sup>'],
+      [[{ type: 'highlight' }], '<mark>m</mark>'],
+      [
+        [{ type: 'highlight', attrs: { color: '#ff0000' } }],
+        '<mark style="background-color: #ff0000">m</mark>',
+      ],
+      [
+        [{ type: 'textStyle', attrs: { color: '#00ff00' } }],
+        '<span style="color: #00ff00">m</span>',
+      ],
+      [
+        [{ type: 'comment', attrs: { commentId: 'cid-1' } }],
+        '<span data-comment-id="cid-1">m</span>',
+      ],
+      [
+        [{ type: 'comment', attrs: { commentId: 'cid-1', resolved: true } }],
+        '<span data-comment-id="cid-1" data-resolved="true">m</span>',
+      ],
+    ];
+    for (const [marks, expected] of cases) {
+      expect(c(para(text('m', marks)))).toBe(expected);
+    }
+  });
+
+  it('a textStyle mark with no color emits nothing (plain text passes through)', () => {
+    expect(c(para(text('plain', [{ type: 'textStyle', attrs: {} }])))).toBe('plain');
+  });
+
+  it('a comment mark with no commentId emits nothing (plain text)', () => {
+    expect(c(para(text('plain', [{ type: 'comment', attrs: {} }])))).toBe('plain');
+  });
+});
+
+describe('paragraph.textAlign -> <p style="text-align:...">', () => {
+  it('non-default alignment emits an HTML <p style="text-align:...">', () => {
+    // #7 fix: a non-default paragraph alignment now round-trips. It is exported
+    // as an HTML `<p style="text-align:center">` (the schema's paragraph
+    // parseHTML reads `style="text-align"` back onto `textAlign` on import), so
+    // the alignment survives instead of collapsing to bare text. (The old
+    // `<div align="center">` form was NOT re-parsed onto the paragraph and was
+    // therefore lossy.)
+    expect(c({ type: 'paragraph', attrs: { textAlign: 'center' }, content: [text('x')] })).toBe(
+      '<p style="text-align:center">x</p>',
+    );
+  });
+
+  it('textAlign "left" (the default) is NOT wrapped', () => {
+    expect(c({ type: 'paragraph', attrs: { textAlign: 'left' }, content: [text('x')] })).toBe('x');
+  });
+});
+
+describe('subpages token + unknown-in-container fallback', () => {
+  it('subpages emits the schema-matching div (round-trips, unlike the old {{SUBPAGES}} literal)', () => {
+    expect(c({ type: 'subpages' })).toBe('<div data-type="subpages"></div>');
+  });
+
+  it('an unknown block inside a raw-HTML container is wrapped in <div> (never markdown)', () => {
+    // Inside columns the children are rendered as HTML; an unknown block type
+    // must NOT fall back to markdown (which would land as literal text on
+    // re-import). It is wrapped in a <div> so its children survive.
+    const out = c({
+      type: 'columns',
+      attrs: { layout: 'two' },
+      content: [
+        { type: 'column', content: [{ type: 'weirdBlock', content: [para(text('kept'))] }] },
+      ],
+    });
+    expect(out).toBe(
+      '<div data-type="columns" data-layout="two">' +
+        '<div data-type="column"><div><p>kept</p></div></div>' +
+        '</div>',
+    );
+  });
+
+  it('an unknown TOP-LEVEL block falls back to its children only (markdown context)', () => {
+    expect(c({ type: 'totallyUnknown', content: [text('inner')] })).toBe('inner');
+  });
+});
+
+describe('escaping idempotence (SPEC §11 phantom-diff guard)', () => {
+  it('escapeAttr escapes ONLY & and " in an attribute context, and is idempotent', () => {
+    // The mathBlock `text` attr goes through escapeAttr. & -> &amp;, " -> &quot;.
+    const once = c({ type: 'mathBlock', attrs: { text: 'a & "b"' } });
+    expect(once).toBe(
+      '<div data-type="mathBlock" data-katex="true" text="a &amp; &quot;b&quot;"></div>',
+    );
+    // < and > are deliberately NOT escaped (would accumulate on round-trips).
+    const angled = c({ type: 'mathBlock', attrs: { text: 'a < b > c' } });
+    expect(angled).toContain('text="a < b > c"');
+    expect(angled).not.toContain('&lt;');
+    expect(angled).not.toContain('&gt;');
+  });
+
+  it('encodeMdUrl turns a space into %20 in an image src (single inert URL token)', () => {
+    expect(c({ type: 'image', attrs: { alt: 'c', src: '/my pic.png' } })).toBe(
+      '![c](/my%20pic.png)',
+    );
+  });
+});
+
+describe('multi-block table cell -> HTML <table> (#8: GFM pipes cannot hold block content)', () => {
+  it('emits the whole table as HTML <table> so a multi-paragraph cell survives', () => {
+    // A cell holding TWO block paragraphs cannot be represented by a GFM pipe
+    // row (one inline line only) — the old GFM path collapsed the two blocks
+    // into one line ("a\|b c"), losing the block boundary and forcing a fragile
+    // pipe-escape. #8 emits the WHOLE table as raw HTML <table> instead: the
+    // schema's table-family parseHTML round-trips it, each paragraph stays its
+    // own <p>, and the literal pipe needs no escaping inside HTML text.
+    const out = c({
+      type: 'table',
+      content: [
+        { type: 'tableRow', content: [
+          { type: 'tableHeader', content: [para(text('H'))] },
+        ]},
+        { type: 'tableRow', content: [
+          { type: 'tableCell', content: [para(text('a|b')), para(text('c'))] },
+        ]},
+      ],
+    });
+    expect(out).toBe(
+      '<table><tbody><tr><th><p>H</p></th></tr><tr><td><p>a|b</p><p>c</p></td></tr></tbody></table>',
+    );
+  });
+});
+
+describe('empty / single-column tables', () => {
+  it('a table with no rows renders as the empty string', () => {
+    expect(c({ type: 'table', content: [] })).toBe('');
+  });
+
+  it('a single-column GFM table emits one column with a "---" separator', () => {
+    const out = c({
+      type: 'table',
+      content: [
+        { type: 'tableRow', content: [{ type: 'tableHeader', content: [para(text('Only'))] }] },
+        { type: 'tableRow', content: [{ type: 'tableCell', content: [para(text('v'))] }] },
+      ],
+    });
+    expect(out).toBe('| Only |\n| --- |\n| v |');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Media / attachment / container full-attribute coverage. The base golden file
+// only sets the minimal attrs for each media node (src, or src+name), so the
+// optional-attribute emission branches and their exact ORDERING are uncovered.
+// These cases pin the full ordered attribute string for video/youtube/embed/
+// audio/pdf/attachment plus the all-absent side of every optional guard, and
+// the distinct HTML-container (blockToHtml / inlineToHtml) paths for an
+// orderedList and a hardBreak inside a column.
+// ---------------------------------------------------------------------------
+describe('media / attachment / container full-attribute golden coverage', () => {
+  it('video: emits all optional attrs in source order (alt->aria-label, attachmentId/size/align/aspectRatio->data-*)', () => {
+    expect(
+      c({
+        type: 'video',
+        attrs: {
+          src: '/v.mp4',
+          alt: 'clip',
+          attachmentId: 'att-1',
+          width: 640,
+          height: 480,
+          size: 1234,
+          align: 'center',
+          aspectRatio: 1.777,
+        },
+      }),
+    ).toBe(
+      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
+    );
+  });
+
+  it('video: with only src, every optional guard takes its false branch (src-only <video>, no data-type on wrapper)', () => {
+    expect(c({ type: 'video', attrs: { src: '/v.mp4' } })).toBe(
+      '<div><video src="/v.mp4"></video></div>',
+    );
+  });
+
+  it('youtube + embed: each emits its full optional attr set in source order', () => {
+    // (a) youtube: width/height/align all present -> data-* in order.
+    expect(
+      c({
+        type: 'youtube',
+        attrs: { src: 'https://youtu.be/abc', width: 560, height: 315, align: 'right' },
+      }),
+    ).toBe(
+      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
+    );
+    // (b) embed: align/width/height optional branches after src+provider.
+    expect(
+      c({
+        type: 'embed',
+        attrs: { src: 'https://x.com/e', provider: 'iframe', align: 'left', width: 600, height: 400 },
+      }),
+    ).toBe(
+      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
+    );
+  });
+
+  it('audio: emits data-attachment-id then data-size after src when both are set', () => {
+    expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7', size: 9001 } })).toBe(
+      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
+    );
+  });
+
+  it('audio: with attachmentId but no size, data-size is suppressed (size != null false branch)', () => {
+    expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7' } })).toBe(
+      '<div><audio src="/a.mp3" data-attachment-id="att-7"></audio></div>',
+    );
+  });
+
+  it('pdf: emits the full optional attr set in order (data-name, data-attachment-id, data-size, width, height)', () => {
+    expect(
+      c({
+        type: 'pdf',
+        attrs: {
+          src: '/d.pdf',
+          name: 'd.pdf',
+          attachmentId: 'att-9',
+          size: 2048,
+          width: 800,
+          height: 600,
+        },
+      }),
+    ).toBe(
+      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9" data-size="2048" width="800" height="600"></div>',
+    );
+  });
+
+  it('attachment: emits data-attachment-name/mime/size/id in order after the always-present url', () => {
+    expect(
+      c({
+        type: 'attachment',
+        attrs: {
+          url: '/f.zip',
+          name: 'f.zip',
+          mime: 'application/zip',
+          size: 512,
+          attachmentId: 'att-3',
+        },
+      }),
+    ).toBe(
+      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
+    );
+  });
+
+  it('attachment: with only a url, no spurious data-attachment-name/mime/size/id appear (all guards false)', () => {
+    expect(c({ type: 'attachment', attrs: { url: '/f.zip' } })).toBe(
+      '<div data-type="attachment" data-attachment-url="/f.zip"></div>',
+    );
+  });
+
+  it('orderedList inside a column renders via blockToHtml as <ol> (start attr DROPPED) with bold->strong, code->code', () => {
+    const out = c({
+      type: 'columns',
+      attrs: { layout: 'two' },
+      content: [
+        {
+          type: 'column',
+          content: [
+            {
+              type: 'orderedList',
+              attrs: { start: 3 },
+              content: [
+                {
+                  type: 'listItem',
+                  content: [para(text('a', [{ type: 'bold' }]))],
+                },
+                {
+                  type: 'listItem',
+                  content: [para(text('b', [{ type: 'code' }]))],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    // blockToHtml orderedList path emits a plain <ol> with no start attribute,
+    // and inlineToHtml maps bold->strong, code->code.
+    expect(out).toContain(
+      '<ol><li><p><strong>a</strong></p></li><li><p><code>b</code></p></li></ol>',
+    );
+    // The start:3 attr is NOT preserved in the HTML/column container path.
+    expect(out).not.toContain('start=');
+  });
+
+  it('hardBreak inside a column renders as <br> via inlineToHtml (not the markdown two-space form)', () => {
+    const out = c({
+      type: 'columns',
+      attrs: { layout: 'two' },
+      content: [
+        {
+          type: 'column',
+          content: [para(text('a'), { type: 'hardBreak' }, text('b'))],
+        },
+      ],
+    });
+    expect(out).toContain('<p>a<br>b</p>');
+    // The processNode markdown "  \n" hard-break form must NOT appear in the
+    // raw-HTML column container path.
+    expect(out).not.toContain('  \n');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter-html-marks.test.ts b/packages/prosemirror-markdown/test/markdown-converter-html-marks.test.ts
new file mode 100644
index 00000000..8c011d9c
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-converter-html-marks.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it } from 'vitest';
+// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
+// pulls in collaboration.ts and mutates the global DOM at import time), matching
+// the other converter unit tests (see markdown-converter-gaps.test.ts).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+
+// Minimal ProseMirror builders. The top-level converter joins doc children with
+// "\n\n" then .trim()s, so a single-node doc yields exactly that node's rendered
+// (trimmed) string.
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// A columns node carrying a SINGLE column, whose content is the supplied block
+// children. columns/column are raw-HTML containers, so their children render via
+// blockToHtml -> inlineToHtml (the HTML-mirroring path under test).
+const oneColumn = (...blocks: any[]) => ({
+  type: 'columns',
+  attrs: { layout: 'two' },
+  content: [{ type: 'column', content: blocks }],
+});
+
+// Extract the inner HTML of the single column from a rendered columns string.
+// Output shape is:
+//   <div data-type="columns" data-layout="two"><div data-type="column">INNER</div></div>
+const COLUMN_PREFIX =
+  '<div data-type="columns" data-layout="two"><div data-type="column">';
+const COLUMN_SUFFIX = '</div></div>';
+const columnInner = (rendered: string): string => {
+  expect(rendered.startsWith(COLUMN_PREFIX)).toBe(true);
+  expect(rendered.endsWith(COLUMN_SUFFIX)).toBe(true);
+  return rendered.slice(COLUMN_PREFIX.length, rendered.length - COLUMN_SUFFIX.length);
+};
+
+// ---------------------------------------------------------------------------
+// 1. inlineToHtml mark-mirroring INSIDE a raw-HTML container (columns).
+//
+// At the TOP level the `text` case emits markdown markers (**, *, ``, ~~) for
+// bold/italic/code/strike. But inside columns (and spanned table cells) the
+// content is raw HTML that marked will NOT re-parse, so inlineToHtml
+// (markdown-converter.ts lines 599-619) MUST mirror each mark to HTML instead:
+// bold-><strong>, italic-><em>, code-><code>, strike-><s>, underline-><u>. This
+// is a DISTINCT branch from the top-level mark path; if it leaked markdown, the
+// literal ** / `` would survive as text on re-import.
+// ---------------------------------------------------------------------------
+describe('inlineToHtml: bold/italic/code/strike/underline -> HTML inside columns', () => {
+  it('mirrors each single-mark run to its schema HTML tag (not markdown markers)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn(
+          para(
+            text('b', [{ type: 'bold' }]),
+            text('i', [{ type: 'italic' }]),
+            text('c', [{ type: 'code' }]),
+            text('s', [{ type: 'strike' }]),
+            text('u', [{ type: 'underline' }]),
+          ),
+        ),
+      ),
+    );
+    expect(out).toBe(
+      '<div data-type="columns" data-layout="two">' +
+        '<div data-type="column">' +
+        '<p><strong>b</strong><em>i</em><code>c</code><s>s</s><u>u</u></p>' +
+        '</div></div>',
+    );
+    // Belt-and-suspenders: none of the top-level markdown markers leaked.
+    expect(out).not.toContain('**');
+    expect(out).not.toContain('~~');
+    expect(out).not.toContain('`');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. inlineToHtml: link/hardBreak/highlight/textStyle/comment inside columns.
+//
+// Exercises the remaining inlineToHtml branches that are uncovered inside a
+// raw-HTML container: link href escaping via escapeAttr (line 621; & -> &amp;,
+// " -> &quot;), hardBreak -> <br> (line 591), highlight WITH vs WITHOUT color
+// (624-626), textStyle color (628-630), and comment with data-resolved (632-638).
+// ---------------------------------------------------------------------------
+describe('inlineToHtml: link/hardBreak/highlight/textStyle/comment inside columns', () => {
+  it('escapes link hrefs, emits <br>, plain/colored <mark>, span color, and resolved comment', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn(
+          para(
+            text('lnk', [{ type: 'link', attrs: { href: 'http://a?b&c"d' } }]),
+            { type: 'hardBreak' },
+            text('hl', [{ type: 'highlight', attrs: { color: '#ff0000' } }]),
+            text('plain', [{ type: 'highlight' }]),
+            text('clr', [{ type: 'textStyle', attrs: { color: 'red' } }]),
+            text('cm', [
+              { type: 'comment', attrs: { commentId: 'c1', resolved: true } },
+            ]),
+          ),
+        ),
+      ),
+    );
+    expect(columnInner(out)).toBe(
+      '<p>' +
+        '<a href="http://a?b&amp;c&quot;d">lnk</a>' +
+        '<br>' +
+        '<mark style="background-color: #ff0000">hl</mark>' +
+        '<mark>plain</mark>' +
+        '<span style="color: red">clr</span>' +
+        '<span data-comment-id="c1" data-resolved="true">cm</span>' +
+        '</p>',
+    );
+  });
+
+  it('omits data-resolved when the comment is not resolved', () => {
+    // The resolved sub-branch (632-638) is load-bearing: an unresolved comment
+    // must emit a bare data-comment-id span with NO data-resolved attribute.
+    const out = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn(
+          para(
+            text('cm', [
+              { type: 'comment', attrs: { commentId: 'c1', resolved: false } },
+            ]),
+          ),
+        ),
+      ),
+    );
+    expect(columnInner(out)).toBe('<p><span data-comment-id="c1">cm</span></p>');
+    expect(out).not.toContain('data-resolved');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. blockToHtml non-paragraph branches inside columns: heading / codeBlock /
+//    bulletList.
+//
+// heading -> <hN> (718-721), codeBlock with-language vs no-language class fork
+// (730-742; the no-language `cls = ''` branch at 741 yields a BARE <code> with
+// no class), and bulletList -> <ul><li><p>...</p></li></ul> (722-725). Code text
+// is element TEXT content, so it is escapeHtmlText-escaped (not the attr escaper),
+// and embedded newlines are preserved verbatim.
+// ---------------------------------------------------------------------------
+describe('blockToHtml: heading / codeBlock(lang & no-lang) / bulletList inside columns', () => {
+  it('emits <hN>, language vs bare <pre><code>, and <ul><li><p>..</p></li>', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(
+        oneColumn(
+          { type: 'heading', attrs: { level: 2 }, content: [text('H')] },
+          {
+            type: 'codeBlock',
+            attrs: { language: 'js' },
+            content: [text('a\nb')],
+          },
+          { type: 'codeBlock', content: [text('plain')] },
+          {
+            type: 'bulletList',
+            content: [
+              { type: 'listItem', content: [para(text('item'))] },
+            ],
+          },
+        ),
+      ),
+    );
+    expect(columnInner(out)).toBe(
+      '<h2>H</h2>' +
+        '<pre><code class="language-js">a\nb</code></pre>' +
+        '<pre><code>plain</code></pre>' +
+        '<ul><li><p>item</p></li></ul>',
+    );
+    // The no-language codeBlock must NOT carry a class attribute (the cls=''
+    // fork at line 741): its <code> opens bare.
+    expect(out).toContain('<pre><code>plain</code></pre>');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Spanned-table renderHtmlCell + orderedList block child (HTML fallback).
+//
+// A colspan>1 cell forces the WHOLE table to the raw-<table> HTML fallback
+// (markdown-converter.ts ~287-331). renderHtmlCell emits colspan + align attrs
+// (312-316) and renders each block child via blockToHtml. An orderedList child
+// hits the blockToHtml orderedList branch (726-729), which emits
+// <ol><li><p>..</p></li>..</ol> — the schema's `start` attr is NOT emitted by
+// this HTML <ol> branch.
+// ---------------------------------------------------------------------------
+describe('spanned table: renderHtmlCell colspan/align + orderedList block child', () => {
+  it('renders the colspan/align cell with an <ol> (start attr is dropped)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc({
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                attrs: { colspan: 2, align: 'center' },
+                content: [
+                  {
+                    type: 'orderedList',
+                    attrs: { start: 3 },
+                    content: [
+                      { type: 'listItem', content: [para(text('one'))] },
+                      { type: 'listItem', content: [para(text('two'))] },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(out).toBe(
+      '<table><tbody><tr>' +
+        '<td colspan="2" align="center">' +
+        '<ol><li><p>one</p></li><li><p>two</p></li></ol>' +
+        '</td>' +
+        '</tr></tbody></table>',
+    );
+    // The HTML <ol> branch does not propagate the ProseMirror `start` attribute.
+    expect(out).not.toContain('start');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter.test.ts b/packages/prosemirror-markdown/test/markdown-converter.test.ts
new file mode 100644
index 00000000..98cb88c0
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-converter.test.ts
@@ -0,0 +1,645 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates global DOM at import time).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+
+// Wrap a single node in a minimal ProseMirror doc. The top-level converter
+// joins doc children with "\n\n" and then .trim()s the whole output, so a
+// single-node doc yields exactly that node's rendered (and trimmed) string.
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+// Convenience: a text node, optionally with marks.
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+// Convenience: a paragraph wrapping inline children.
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+describe('convertProseMirrorToMarkdown', () => {
+  // ---------------------------------------------------------------------------
+  describe('headings', () => {
+    it('emits the right number of "#" for levels 1-6', () => {
+      for (let level = 1; level <= 6; level++) {
+        const out = convertProseMirrorToMarkdown(
+          doc({ type: 'heading', attrs: { level }, content: [text('H')] }),
+        );
+        expect(out).toBe('#'.repeat(level) + ' H');
+      }
+    });
+
+    it('defaults to level 1 when level is missing', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'heading', content: [text('NoLevel')] }),
+      );
+      expect(out).toBe('# NoLevel');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('text marks', () => {
+    it('bold', () => {
+      expect(
+        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'bold' }])))),
+      ).toBe('**x**');
+    });
+
+    it('italic', () => {
+      expect(
+        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'italic' }])))),
+      ).toBe('*x*');
+    });
+
+    it('strike', () => {
+      expect(
+        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'strike' }])))),
+      ).toBe('~~x~~');
+    });
+
+    it('inline code (sole mark) uses backtick span', () => {
+      expect(
+        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'code' }])))),
+      ).toBe('`x`');
+    });
+
+    it('code + another mark emits the backtick code form (code wins)', () => {
+      // The schema's `code` mark excludes all other marks, so the editor can
+      // never produce code+bold on one run and import always drops the co-mark.
+      // The lossless, byte-stable behavior is to emit ONLY the backtick code
+      // span and ignore the co-occurring mark.
+      const out = convertProseMirrorToMarkdown(
+        doc(para(text('x', [{ type: 'bold' }, { type: 'code' }]))),
+      );
+      expect(out).toBe('`x`');
+    });
+
+    it('code + strike combo emits the backtick code form (code wins)', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(para(text('x', [{ type: 'strike' }, { type: 'code' }]))),
+      );
+      expect(out).toBe('`x`');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('links', () => {
+    it('href only', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(para(text('site', [{ type: 'link', attrs: { href: 'https://e.com' } }]))),
+      );
+      expect(out).toBe('[site](https://e.com)');
+    });
+
+    it('href + title with an embedded double quote is escaped', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(
+          para(
+            text('site', [
+              { type: 'link', attrs: { href: 'https://e.com', title: 'a "b" c' } },
+            ]),
+          ),
+        ),
+      );
+      // The markdown link-title form escapes the inner " as \".
+      expect(out).toBe('[site](https://e.com "a \\"b\\" c")');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('image', () => {
+    it('percent-encodes spaces and parentheses in src', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'image',
+          attrs: { alt: 'cap', src: '/files/my pic (1).png' },
+        }),
+      );
+      // space -> %20, ( -> %28, ) -> %29
+      expect(out).toBe('![cap](/files/my%20pic%20%281%29.png)');
+    });
+
+    it('empty alt and missing src render harmlessly', () => {
+      const out = convertProseMirrorToMarkdown(doc({ type: 'image', attrs: {} }));
+      expect(out).toBe('![]()');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('codeBlock', () => {
+    it('with language', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'codeBlock',
+          attrs: { language: 'ts' },
+          content: [text('const a = 1;')],
+        }),
+      );
+      expect(out).toBe('```ts\nconst a = 1;\n```');
+    });
+
+    it('without language emits empty info string', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'codeBlock', content: [text('plain')] }),
+      );
+      expect(out).toBe('```\nplain\n```');
+    });
+
+    it('strips ALL trailing newlines for idempotency', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'codeBlock', content: [text('a\n\n\n')] }),
+      );
+      // Every trailing "\n" is removed, then exactly one is re-added by the fence.
+      expect(out).toBe('```\na\n```');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('lists', () => {
+    it('bullet list', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'bulletList',
+          content: [
+            { type: 'listItem', content: [para(text('one'))] },
+            { type: 'listItem', content: [para(text('two'))] },
+          ],
+        }),
+      );
+      expect(out).toBe('- one\n- two');
+    });
+
+    it('ordered list numbers items sequentially', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'orderedList',
+          content: [
+            { type: 'listItem', content: [para(text('a'))] },
+            { type: 'listItem', content: [para(text('b'))] },
+            { type: 'listItem', content: [para(text('c'))] },
+          ],
+        }),
+      );
+      expect(out).toBe('1. a\n2. b\n3. c');
+    });
+
+    it('nested bullet list indents the child by the 2-col marker width', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'bulletList',
+          content: [
+            {
+              type: 'listItem',
+              content: [
+                para(text('parent')),
+                {
+                  type: 'bulletList',
+                  content: [{ type: 'listItem', content: [para(text('child'))] }],
+                },
+              ],
+            },
+          ],
+        }),
+      );
+      // First line carries the marker; the nested list is indented 2 columns.
+      expect(out).toBe('- parent\n  - child');
+    });
+
+    it('nested ordered list indents by the wider 3-col marker width', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'orderedList',
+          content: [
+            {
+              type: 'listItem',
+              content: [
+                para(text('parent')),
+                {
+                  type: 'orderedList',
+                  content: [{ type: 'listItem', content: [para(text('child'))] }],
+                },
+              ],
+            },
+          ],
+        }),
+      );
+      // "1. " is 3 columns wide, so the continuation indent is 3 spaces.
+      expect(out).toBe('1. parent\n   1. child');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('task list', () => {
+    it('unchecked and checked items', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'taskList',
+          content: [
+            { type: 'taskItem', attrs: { checked: false }, content: [para(text('todo'))] },
+            { type: 'taskItem', attrs: { checked: true }, content: [para(text('done'))] },
+          ],
+        }),
+      );
+      expect(out).toBe('- [ ] todo\n- [x] done');
+    });
+
+    it('empty task item keeps its marker', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'taskList',
+          content: [{ type: 'taskItem', attrs: { checked: false }, content: [] }],
+        }),
+      );
+      expect(out).toBe('- [ ]');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('blockquote', () => {
+    it('single paragraph quote prefixes the line', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'blockquote', content: [para(text('quoted'))] }),
+      );
+      expect(out).toBe('> quoted');
+    });
+
+    it('multi-paragraph quote separates blocks with a bare ">" line', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'blockquote',
+          content: [para(text('first')), para(text('second'))],
+        }),
+      );
+      expect(out).toBe('> first\n>\n> second');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('breaks and rules', () => {
+    it('horizontal rule', () => {
+      expect(
+        convertProseMirrorToMarkdown(doc({ type: 'horizontalRule' })),
+      ).toBe('---');
+    });
+
+    it('hard break emits two trailing spaces then newline', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(para(text('a'), { type: 'hardBreak' }, text('b'))),
+      );
+      expect(out).toBe('a  \nb');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('tables', () => {
+    it('GFM table emits alignment markers derived from header cells', () => {
+      const headerRow = {
+        type: 'tableRow',
+        content: [
+          { type: 'tableHeader', attrs: { align: 'left' }, content: [para(text('L'))] },
+          { type: 'tableHeader', attrs: { align: 'center' }, content: [para(text('C'))] },
+          { type: 'tableHeader', attrs: { align: 'right' }, content: [para(text('R'))] },
+          { type: 'tableHeader', content: [para(text('N'))] },
+        ],
+      };
+      const bodyRow = {
+        type: 'tableRow',
+        content: [
+          { type: 'tableCell', content: [para(text('1'))] },
+          { type: 'tableCell', content: [para(text('2'))] },
+          { type: 'tableCell', content: [para(text('3'))] },
+          { type: 'tableCell', content: [para(text('4'))] },
+        ],
+      };
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'table', content: [headerRow, bodyRow] }),
+      );
+      expect(out).toBe(
+        [
+          '| L | C | R | N |',
+          '| :-- | :-: | --: | --- |',
+          '| 1 | 2 | 3 | 4 |',
+        ].join('\n'),
+      );
+    });
+
+    it('spanned table (colspan/rowspan) emits raw <table> HTML', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'table',
+          content: [
+            {
+              type: 'tableRow',
+              content: [
+                {
+                  type: 'tableHeader',
+                  attrs: { colspan: 2 },
+                  content: [para(text('wide'))],
+                },
+              ],
+            },
+            {
+              type: 'tableRow',
+              content: [
+                { type: 'tableCell', content: [para(text('a'))] },
+                { type: 'tableCell', content: [para(text('b'))] },
+              ],
+            },
+          ],
+        }),
+      );
+      expect(out).toBe(
+        '<table><tbody>' +
+          '<tr><th colspan="2"><p>wide</p></th></tr>' +
+          '<tr><td><p>a</p></td><td><p>b</p></td></tr>' +
+          '</tbody></table>',
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('callout and details', () => {
+    it('callout uses lowercased type fence', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'callout',
+          attrs: { type: 'WARNING' },
+          content: [para(text('beware'))],
+        }),
+      );
+      expect(out).toBe('> [!warning]\n> beware');
+    });
+
+    it('callout defaults to info', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'callout', content: [para(text('hi'))] }),
+      );
+      expect(out).toBe('> [!info]\n> hi');
+    });
+
+    it('details emits summary + content wrapped in <details>', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'details',
+          content: [
+            { type: 'detailsSummary', content: [text('Title')] },
+            { type: 'detailsContent', content: [para(text('Body'))] },
+          ],
+        }),
+      );
+      // details joins its children with "\n"; summary opens, content closes.
+      expect(out).toBe('<details>\n<summary>Title</summary>\n\nBody\n</details>');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('math', () => {
+    it('inline math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(para({ type: 'mathInline', attrs: { text: 'a < b' } })),
+      );
+      // < and > must NOT be HTML-escaped (idempotency); only & and " would be.
+      expect(out).toBe(
+        '<span data-type="mathInline" data-katex="true" text="a < b"></span>',
+      );
+      expect(out).not.toContain('&lt;');
+    });
+
+    it('block math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'mathBlock', attrs: { text: 'x > y & z' } }),
+      );
+      // & IS escaped (entity-significant), but < and > are NOT.
+      expect(out).toBe(
+        '<div data-type="mathBlock" data-katex="true" text="x > y &amp; z"></div>',
+      );
+      expect(out).not.toContain('&lt;');
+      expect(out).not.toContain('&gt;');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('inline atoms and media', () => {
+    it('mention emits schema span with data-* attrs and visible label', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(
+          para({
+            type: 'mention',
+            attrs: { id: 'u1', label: 'Alice', entityType: 'user' },
+          }),
+        ),
+      );
+      expect(out).toBe(
+        '<span data-type="mention" data-id="u1" data-label="Alice" data-entity-type="user">@Alice</span>',
+      );
+    });
+
+    it('attachment emits div with schema data-attachment-* attrs', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'attachment',
+          attrs: { url: '/files/x.zip', name: 'x.zip', mime: 'application/zip', size: 99 },
+        }),
+      );
+      expect(out).toBe(
+        '<div data-type="attachment" data-attachment-url="/files/x.zip" ' +
+          'data-attachment-name="x.zip" data-attachment-mime="application/zip" ' +
+          'data-attachment-size="99"></div>',
+      );
+    });
+
+    it('video emits a <div>-wrapped <video> with schema attrs', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'video',
+          attrs: { src: '/v.mp4', alt: 'clip', width: 640 },
+        }),
+      );
+      expect(out).toBe(
+        '<div><video src="/v.mp4" aria-label="clip" width="640"></video></div>',
+      );
+    });
+
+    it('youtube emits a div[data-type="youtube"] with data-src', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'youtube',
+          attrs: { src: 'https://youtu.be/abc', width: 560, height: 315 },
+        }),
+      );
+      expect(out).toBe(
+        '<div data-type="youtube" data-src="https://youtu.be/abc" ' +
+          'data-width="560" data-height="315"></div>',
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('edge cases', () => {
+    it('null content returns ""', () => {
+      expect(convertProseMirrorToMarkdown(null)).toBe('');
+    });
+
+    it('empty object returns ""', () => {
+      expect(convertProseMirrorToMarkdown({})).toBe('');
+    });
+
+    it('doc with no content returns ""', () => {
+      expect(convertProseMirrorToMarkdown({ type: 'doc' })).toBe('');
+    });
+
+    it('unknown node type falls back to children-only (no throw, text preserved)', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'totallyUnknownType', content: [text('kept')] }),
+      );
+      expect(out).toBe('kept');
+    });
+
+    it('deeply nested structure does not stack-overflow', () => {
+      // Build a deeply nested bullet list (each level holds one nested list).
+      let node: any = { type: 'listItem', content: [para(text('leaf'))] };
+      for (let i = 0; i < 200; i++) {
+        node = {
+          type: 'listItem',
+          content: [para(text('lvl')), { type: 'bulletList', content: [node] }],
+        };
+      }
+      const root = doc({ type: 'bulletList', content: [node] });
+      expect(() => convertProseMirrorToMarkdown(root)).not.toThrow();
+      const out = convertProseMirrorToMarkdown(root);
+      expect(out).toContain('leaf');
+      expect(out.startsWith('- lvl')).toBe(true);
+    });
+  });
+
+  // ===========================================================================
+  // Targeted coverage for marker-width-scaled list indent, the markdown
+  // link-title escape branch, the markdown callout fence, and the blockquote
+  // per-line prefixer over a multi-line nested-block child. Grounded against
+  // the real converter output (verified empirically) — see processListItem /
+  // indentItemChildren (src 812-843), the link mark branch (src 117-121), the
+  // callout case (src 373-376), and the blockquote prefixer (src 210-221).
+  describe('marker-width / link-title / callout / blockquote-nested', () => {
+    // Spec 1 — two-digit ordered marker scales the continuation indent to 4.
+    it('indents a nested ordered sublist under item 10 by 4 spaces (marker "10. ")', () => {
+      // Items 1..10 ("a".."j"); the 10th additionally holds a nested
+      // orderedList with one paragraph "x".
+      const items: any[] = [];
+      for (let i = 0; i < 9; i++) {
+        items.push({
+          type: 'listItem',
+          content: [para(text(String.fromCharCode(97 + i)))], // 'a'..'i'
+        });
+      }
+      items.push({
+        type: 'listItem',
+        content: [
+          para(text('j')),
+          {
+            type: 'orderedList',
+            content: [{ type: 'listItem', content: [para(text('x'))] }],
+          },
+        ],
+      });
+
+      const out = convertProseMirrorToMarkdown(
+        doc({ type: 'orderedList', content: items }),
+      );
+
+      // The 10th marker is the 4-column "10. "; the nested sublist line must be
+      // indented exactly 4 spaces (prefix.length 3 + 1), NOT 3.
+      expect(out).toContain('10. j\n    1. x');
+      // Guard against the off-by-one (3-space) regression that would re-parse
+      // the sublist as loose/sibling content on import.
+      expect(out).not.toContain('10. j\n   1. x');
+      // And the single-digit items keep the narrower 3-column marker (no body
+      // continuation here, but the marker itself must stay "1. ".."9. ").
+      expect(out.startsWith('1. a\n2. b\n')).toBe(true);
+      expect(out).toContain('\n9. i\n10. j');
+    });
+
+    // Spec 2 — markdown link-title branch escapes an embedded double quote and
+    // emits the href raw.
+    it('escapes an embedded double-quote in a markdown link title and emits href raw', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc(
+          para(
+            text('lbl', [
+              {
+                type: 'link',
+                attrs: { href: 'http://a', title: 'he said "hi"' },
+              },
+            ]),
+          ),
+        ),
+      );
+      // The title's " is backslash-escaped (.replace(/"/g,'\\"')) so it cannot
+      // terminate the (url "title") syntax early; the href is RAW (not escaped).
+      expect(out).toBe('[lbl](http://a "he said \\"hi\\"")');
+    });
+
+    // Spec 3 — markdown callout fence lowercases the type and joins multiple
+    // paragraph children.
+    it('lowercases an uppercase callout type and joins its paragraphs', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'callout',
+          attrs: { type: 'WARNING' },
+          content: [para(text('line1')), para(text('line2'))],
+        }),
+      );
+      // NOTE(review): the spec predicted ':::warning\nline1\n\nline2\n:::' (a
+      // The converter joins the callout's rendered children with a single '\n'
+      // and emits an Obsidian-native callout: a `> [!type]` opener plus one
+      // `>`-prefixed body line per content line. We pin the lowercasing
+      // (WARNING -> warning) and the multi-child join.
+      expect(out).toBe('> [!warning]\n> line1\n> line2');
+      // The type is lowercased (an uppercase `[!WARNING]` would not re-import).
+      expect(out.startsWith('> [!warning]\n')).toBe(true);
+      expect(out).not.toContain('[!WARNING]');
+      // Both paragraph children are present, each blockquote-prefixed.
+      expect(out).toContain('> line1\n> line2');
+    });
+
+    // Spec 4 — blockquote per-line prefixer over a multi-line nested callout.
+    it('prefixes every line of a nested callout child with "> "', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'blockquote',
+          content: [
+            {
+              type: 'callout',
+              attrs: { type: 'INFO' },
+              content: [para(text('a')), para(text('b'))],
+            },
+          ],
+        }),
+      );
+      // NOTE(review): the spec predicted '> :::info\n> a\n>\n> b\n> :::',
+      // assuming the nested callout body contains a blank line between 'a' and
+      // The nested callout renders as an Obsidian callout '> [!info]\n> a\n> b'
+      // (single-'\n' join, no blank line). The outer blockquote prefixer then
+      // prefixes each of those lines with '> ' again, yielding a doubly-nested
+      // blockquote — the realistic per-line-prefix loop over a multi-line child.
+      expect(out).toBe('> > [!info]\n> > a\n> > b');
+      // Every produced line carries the '> ' prefix (no line escapes to col 0).
+      for (const line of out.split('\n')) {
+        expect(line.startsWith('>')).toBe(true);
+      }
+    });
+
+    // The empty-line '>' branch from Spec 4's intent IS reachable — just not via
+    // the nested callout (whose body has no blank line). A two-paragraph
+    // blockquote DOES separate its block children with a bare '>' line, which is
+    // the branch the spec wanted to protect. Pin it directly so the
+    // (line.length ? '> ' : '>') empty-line path stays covered.
+    it('maps an internal blank line to a bare ">" (not "> ") in a multi-block quote', () => {
+      const out = convertProseMirrorToMarkdown(
+        doc({
+          type: 'blockquote',
+          content: [para(text('p1')), para(text('p2'))],
+        }),
+      );
+      expect(out).toBe('> p1\n>\n> p2');
+      // The separator line is exactly '>' with NO trailing space.
+      expect(out.split('\n')).toContain('>');
+      expect(out).not.toContain('> \n');
+    });
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-document-envelope.test.ts b/packages/prosemirror-markdown/test/markdown-document-envelope.test.ts
new file mode 100644
index 00000000..05698a08
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-document-envelope.test.ts
@@ -0,0 +1,218 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates global DOM at import time).
+import {
+  serializeDocmostMarkdown,
+  parseDocmostMarkdown,
+  serializeDocmostMarkdownBody,
+  type DocmostMdMeta,
+} from '../src/lib/markdown-document.js';
+
+const meta: DocmostMdMeta = {
+  version: 1,
+  pageId: 'p1',
+  slugId: 's1',
+  title: 'Hello',
+  spaceId: 'sp1',
+  parentPageId: null,
+};
+
+describe('serializeDocmostMarkdown / parseDocmostMarkdown', () => {
+  // ---------------------------------------------------------------------------
+  describe('round-trip', () => {
+    it('round-trips meta, body, and comments', () => {
+      const body = '# Title\n\nSome **body** text.';
+      const comments = [{ id: 'c1', text: 'a note' }];
+      const full = serializeDocmostMarkdown(meta, body, comments);
+      const parsed = parseDocmostMarkdown(full);
+      expect(parsed.meta).toEqual(meta);
+      expect(parsed.body).toBe(body);
+      expect(parsed.comments).toEqual(comments);
+    });
+
+    it('emits a comments block with [] even when there are no comments', () => {
+      const full = serializeDocmostMarkdown(meta, 'body', []);
+      expect(full).toContain('<!-- docmost:comments\n[]\n-->');
+      const parsed = parseDocmostMarkdown(full);
+      expect(parsed.comments).toEqual([]);
+      expect(parsed.body).toBe('body');
+    });
+
+    it('non-array comments arg is normalized to [] in the serialized output', () => {
+      const full = serializeDocmostMarkdown(meta, 'body', null as any);
+      expect(full).toContain('<!-- docmost:comments\n[]\n-->');
+    });
+
+    it('trims surrounding whitespace from the body on serialize', () => {
+      const full = serializeDocmostMarkdown(meta, '\n\n  body  \n\n', []);
+      const parsed = parseDocmostMarkdown(full);
+      expect(parsed.body).toBe('body');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('missing blocks (tolerant parsing)', () => {
+    it('missing meta block yields meta:null', () => {
+      const input = 'Just a body.\n\n<!-- docmost:comments\n[]\n-->\n';
+      const parsed = parseDocmostMarkdown(input);
+      expect(parsed.meta).toBeNull();
+      expect(parsed.body).toBe('Just a body.');
+      expect(parsed.comments).toEqual([]);
+    });
+
+    it('missing comments block yields comments:null and treats all as body', () => {
+      const input =
+        '<!-- docmost:meta\n' + JSON.stringify(meta) + '\n-->\n\nbody only';
+      const parsed = parseDocmostMarkdown(input);
+      expect(parsed.meta).toEqual(meta);
+      expect(parsed.comments).toBeNull();
+      expect(parsed.body).toBe('body only');
+    });
+
+    it('plain markdown with neither block: meta and comments null, whole input is body', () => {
+      const input = '# Plain\n\nNo envelope here.';
+      const parsed = parseDocmostMarkdown(input);
+      expect(parsed.meta).toBeNull();
+      expect(parsed.comments).toBeNull();
+      expect(parsed.body).toBe(input);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('CRLF normalization', () => {
+    it('parses a CRLF-encoded document the same as LF', () => {
+      const lf = serializeDocmostMarkdown(meta, 'line one\nline two', [
+        { id: 'c1' },
+      ]);
+      const crlf = lf.replace(/\n/g, '\r\n');
+      const parsed = parseDocmostMarkdown(crlf);
+      expect(parsed.meta).toEqual(meta);
+      expect(parsed.body).toBe('line one\nline two');
+      expect(parsed.comments).toEqual([{ id: 'c1' }]);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('only the final document-ending comments block is captured', () => {
+    it('an earlier literal docmost:comments opener inside the body stays in the body', () => {
+      // The body documents the format and contains a literal opener that does
+      // NOT end the document. Only the trailing block is treated as metadata.
+      const bodyWithLiteral =
+        'Here is how the format looks:\n\n<!-- docmost:comments\n[{"fake":true}]\n-->\n\nand more prose after it.';
+      const full = serializeDocmostMarkdown(meta, bodyWithLiteral, [
+        { id: 'real' },
+      ]);
+      const parsed = parseDocmostMarkdown(full);
+      // The real (final) block parses into the comments...
+      expect(parsed.comments).toEqual([{ id: 'real' }]);
+      // ...and the earlier literal opener is preserved verbatim in the body.
+      expect(parsed.body).toContain(
+        '<!-- docmost:comments\n[{"fake":true}]\n-->',
+      );
+      expect(parsed.body).toContain('and more prose after it.');
+    });
+
+    it('a literal opener whose closer does NOT end the doc is left entirely in the body', () => {
+      // No real trailing block: the opener is not document-ending, so comments
+      // stays null and nothing is stripped.
+      const input =
+        '<!-- docmost:meta\n' +
+        JSON.stringify(meta) +
+        '\n-->\n\nbody start\n\n<!-- docmost:comments\n[]\n-->\n\ntrailing text not ending the doc';
+      const parsed = parseDocmostMarkdown(input);
+      expect(parsed.comments).toBeNull();
+      expect(parsed.body).toContain('<!-- docmost:comments');
+      expect(parsed.body).toContain('trailing text not ending the doc');
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('end-anchored comments closer tolerates CRLF + trailing whitespace', () => {
+    it('captures the final comments block when its "-->" closer has CRLF and trailing spaces', () => {
+      // The closer regex is /\r?\n-->[ \t]*\r?\n?\s*$/. Build a document whose
+      // trailing comments block uses CRLF line endings AND has trailing spaces
+      // after the "-->" closer, then assert it is still recognised as the
+      // document-ending block (and the body is not polluted by it).
+      const metaLine = JSON.stringify(meta);
+      const crlfDoc =
+        `<!-- docmost:meta\r\n${metaLine}\r\n-->\r\n\r\n` +
+        `the body line\r\n\r\n` +
+        `<!-- docmost:comments\r\n[{"id":"c-crlf"}]\r\n-->  \r\n`;
+      const parsed = parseDocmostMarkdown(crlfDoc);
+      expect(parsed.meta).toEqual(meta);
+      expect(parsed.body).toBe('the body line');
+      expect(parsed.comments).toEqual([{ id: 'c-crlf' }]);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  describe('malformed JSON throws a clear error', () => {
+    it('throws on malformed meta JSON', () => {
+      const input = '<!-- docmost:meta\n{not valid json}\n-->\n\nbody';
+      expect(() => parseDocmostMarkdown(input)).toThrow(/docmost:meta JSON/);
+    });
+
+    it('throws on malformed comments JSON', () => {
+      const input = 'body\n\n<!-- docmost:comments\n[not, valid]\n-->\n';
+      expect(() => parseDocmostMarkdown(input)).toThrow(/docmost:comments JSON/);
+    });
+  });
+});
+
+describe('serializeDocmostMarkdownBody', () => {
+  it('emits NO comments block', () => {
+    const out = serializeDocmostMarkdownBody(meta, 'just the body');
+    expect(out).not.toContain('docmost:comments');
+    expect(out).toContain('<!-- docmost:meta');
+  });
+
+  it('serialize -> parse preserves meta and the trimmed body, comments null (SPEC §3)', () => {
+    const fullMeta: DocmostMdMeta = {
+      version: 1,
+      pageId: 'page-123',
+      slugId: 'slug-abc',
+      title: 'My Page',
+      spaceId: 'space-1',
+      parentPageId: 'parent-9',
+    };
+    const body = 'Hello\n\nWorld';
+    const out = serializeDocmostMarkdownBody(fullMeta, body);
+    const parsed = parseDocmostMarkdown(out);
+    expect(parsed.meta).toEqual(fullMeta);
+    expect(parsed.body).toBe(body);
+    expect(parsed.comments).toBeNull();
+  });
+
+  it('preserves a null parentPageId for a root page', () => {
+    const out = serializeDocmostMarkdownBody(meta, 'body text');
+    const parsed = parseDocmostMarkdown(out);
+    expect(parsed.meta).toEqual(meta);
+    expect(parsed.comments).toBeNull();
+  });
+
+  it('produces a parseable file for an empty or missing body', () => {
+    const minimal: DocmostMdMeta = { version: 1, pageId: 'p-empty' };
+
+    const emptyFile = serializeDocmostMarkdownBody(minimal, '');
+    const parsedEmpty = parseDocmostMarkdown(emptyFile);
+    expect(parsedEmpty.meta).toEqual(minimal);
+    expect(parsedEmpty.body).toBe('');
+    expect(parsedEmpty.comments).toBeNull();
+
+    // Missing body (undefined) — serializer coalesces to "".
+    const missingFile = serializeDocmostMarkdownBody(
+      minimal,
+      undefined as unknown as string,
+    );
+    const parsedMissing = parseDocmostMarkdown(missingFile);
+    expect(parsedMissing.meta).toEqual(minimal);
+    expect(parsedMissing.body).toBe('');
+    expect(parsedMissing.comments).toBeNull();
+  });
+
+  it('trims the body', () => {
+    const out = serializeDocmostMarkdownBody(meta, '\n\n  hi  \n');
+    const parsed = parseDocmostMarkdown(out);
+    expect(parsed.body).toBe('hi');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-document.test.ts b/packages/prosemirror-markdown/test/markdown-document.test.ts
new file mode 100644
index 00000000..c23447d9
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-document.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import {
+  serializeDocmostMarkdownBody,
+  parseDocmostMarkdown,
+  type DocmostMdMeta,
+} from 'docmost-client';
+
+describe('serializeDocmostMarkdownBody round-trip (SPEC §3)', () => {
+  it('serialize -> parse preserves meta and the trimmed body, with no comments block', () => {
+    const meta: DocmostMdMeta = {
+      version: 1,
+      pageId: 'page-123',
+      slugId: 'slug-abc',
+      title: 'My Page',
+      spaceId: 'space-1',
+      parentPageId: 'parent-9',
+    };
+    const body = 'Hello\n\nWorld';
+
+    const file = serializeDocmostMarkdownBody(meta, body);
+    const parsed = parseDocmostMarkdown(file);
+
+    expect(parsed.meta).toEqual(meta);
+    expect(parsed.body).toBe(body);
+    // No trailing docmost:comments block was emitted (SPEC §3).
+    expect(parsed.comments).toBeNull();
+  });
+
+  it('preserves a null parentPageId for a root page', () => {
+    const meta: DocmostMdMeta = {
+      version: 1,
+      pageId: 'root-1',
+      slugId: 'root-slug',
+      title: 'Root',
+      spaceId: 'space-1',
+      parentPageId: null,
+    };
+    const file = serializeDocmostMarkdownBody(meta, 'body text');
+    const parsed = parseDocmostMarkdown(file);
+    expect(parsed.meta).toEqual(meta);
+    expect(parsed.comments).toBeNull();
+  });
+
+  it('produces a parseable file for an empty/missing body', () => {
+    const meta: DocmostMdMeta = { version: 1, pageId: 'p-empty' };
+
+    // Empty string body.
+    const emptyFile = serializeDocmostMarkdownBody(meta, '');
+    expect(() => parseDocmostMarkdown(emptyFile)).not.toThrow();
+    const parsedEmpty = parseDocmostMarkdown(emptyFile);
+    expect(parsedEmpty.meta).toEqual(meta);
+    expect(parsedEmpty.body).toBe('');
+    expect(parsedEmpty.comments).toBeNull();
+
+    // Missing body (undefined) — serializer coalesces to "".
+    const missingFile = serializeDocmostMarkdownBody(
+      meta,
+      undefined as unknown as string,
+    );
+    expect(() => parseDocmostMarkdown(missingFile)).not.toThrow();
+    const parsedMissing = parseDocmostMarkdown(missingFile);
+    expect(parsedMissing.meta).toEqual(meta);
+    expect(parsedMissing.body).toBe('');
+    expect(parsedMissing.comments).toBeNull();
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts b/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
new file mode 100644
index 00000000..ea6b4c00
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+} from "docmost-client";
+
+// Round-trip coverage for the two editor features git-sync's converter
+// predated and must now preserve losslessly:
+//   - the `spoiler` inline mark (issue #259), emitted as raw inline HTML
+//     `<span data-spoiler="true">…</span>` (Markdown has no native syntax);
+//   - the image `caption` attribute (issue #221), emitted as `data-caption`
+//     on the raw <img> (Markdown `![](src)` cannot carry it).
+// We exercise the real export -> import -> export cycle: a PM doc must survive
+// PM -> MD -> PM unchanged, and the raw-HTML forms in incoming Markdown must
+// parse back to the mark/attribute.
+
+const doc = (...nodes: any[]) => ({ type: "doc", content: nodes });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: "text", text: t, marks } : { type: "text", text: t };
+const para = (...inline: any[]) => ({ type: "paragraph", content: inline });
+
+// Count text nodes carrying a `spoiler` mark anywhere in a PM JSON doc.
+function countSpoilerMarks(node: any): number {
+  let count = 0;
+  const walk = (n: any) => {
+    if (!n || typeof n !== "object") return;
+    if (Array.isArray(n.marks)) {
+      for (const mark of n.marks) if (mark?.type === "spoiler") count++;
+    }
+    if (Array.isArray(n.content)) n.content.forEach(walk);
+  };
+  walk(node);
+  return count;
+}
+
+// Find the first image node anywhere in a PM JSON doc.
+function findImage(node: any): any | null {
+  if (!node || typeof node !== "object") return null;
+  if (node.type === "image") return node;
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      const hit = findImage(child);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+describe("spoiler mark round-trip (#259)", () => {
+  it("survives export -> import -> export unchanged", async () => {
+    const source = doc(
+      para(
+        text("before "),
+        text("hidden", [{ type: "spoiler" }]),
+        text(" after"),
+      ),
+    );
+
+    const md1 = convertProseMirrorToMarkdown(source);
+    // Lossless raw inline HTML form.
+    expect(md1).toContain('<span data-spoiler="true">hidden</span>');
+
+    const doc2 = await markdownToProseMirror(md1);
+    // The spoiler mark was recovered on import.
+    expect(countSpoilerMarks(doc2)).toBe(1);
+    expect(JSON.stringify(doc2)).toContain("hidden");
+
+    // Byte-stable: a second export reproduces the first exactly.
+    const md2 = convertProseMirrorToMarkdown(doc2);
+    expect(md2).toBe(md1);
+  });
+
+  it("keeps the spoiler intact when it intersects a bold mark", async () => {
+    const source = doc(
+      para(text("secret", [{ type: "bold" }, { type: "spoiler" }])),
+    );
+
+    const md1 = convertProseMirrorToMarkdown(source);
+    expect(md1).toContain('data-spoiler="true"');
+
+    const doc2 = await markdownToProseMirror(md1);
+    expect(countSpoilerMarks(doc2)).toBe(1);
+    // Bold survives alongside the spoiler.
+    expect(JSON.stringify(doc2)).toContain('"bold"');
+  });
+
+  it("parses a raw <span data-spoiler> in incoming Markdown back to the mark", async () => {
+    const incoming = 'before <span data-spoiler="true">hidden</span> after';
+    const parsed = await markdownToProseMirror(incoming);
+    expect(countSpoilerMarks(parsed)).toBe(1);
+  });
+});
+
+describe("image caption round-trip (#221)", () => {
+  it("survives export -> import -> export with the caption preserved", async () => {
+    const source = doc({
+      type: "image",
+      attrs: { src: "/files/a.png", alt: "cat", caption: "A grey cat" },
+    });
+
+    const md1 = convertProseMirrorToMarkdown(source);
+    // A captioned image takes the raw <img> form so data-caption can ride along.
+    expect(md1).toContain('data-caption="A grey cat"');
+
+    const doc2 = await markdownToProseMirror(md1);
+    const img = findImage(doc2);
+    expect(img).toBeTruthy();
+    expect(img.attrs?.caption).toBe("A grey cat");
+
+    // Byte-stable: a second export reproduces the first exactly.
+    const md2 = convertProseMirrorToMarkdown(doc2);
+    expect(md2).toBe(md1);
+  });
+
+  it("parses a raw <img data-caption> in incoming Markdown back to the caption", async () => {
+    const incoming = '<img src="/files/a.png" alt="cat" data-caption="A grey cat">';
+    const parsed = await markdownToProseMirror(incoming);
+    const img = findImage(parsed);
+    expect(img).toBeTruthy();
+    expect(img.attrs?.caption).toBe("A grey cat");
+  });
+
+  it("leaves a caption-less image on the lighter markdown form", () => {
+    const md = convertProseMirrorToMarkdown(
+      doc({ type: "image", attrs: { src: "/files/a.png", alt: "cat" } }),
+    );
+    expect(md).toBe("![cat](/files/a.png)");
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-roundtrip.property.test.ts b/packages/prosemirror-markdown/test/markdown-roundtrip.property.test.ts
new file mode 100644
index 00000000..50f83d73
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-roundtrip.property.test.ts
@@ -0,0 +1,698 @@
+import { describe, expect, it, vi } from 'vitest';
+import fc from 'fast-check';
+
+// These property tests run real ProseMirror<->Markdown conversion × NUM_RUNS, so
+// each takes ~4–5s. Inputs are DETERMINISTIC (fixed SEED below) — the only source
+// of flakiness is wall-clock: under the full suite's parallel worker load they can
+// exceed vitest's default 5000ms per-test timeout. Give them ample headroom so CI
+// (which gates the docker build, AGENTS.md) is deterministic regardless of load.
+vi.setConfig({ testTimeout: 30000 });
+// Import the converter DIRECTLY from src (NOT the docmost-client barrel) so we
+// match the path used by the other converter unit tests.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+// markdownToProseMirror lives in collaboration.ts; importing it mutates the
+// global DOM via jsdom at module load time — this is expected and required for
+// @tiptap/html's generateJSON to run under Node.
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+import { stripBlockIds } from './roundtrip-helpers.js';
+
+// ---------------------------------------------------------------------------
+// WHY THIS TEST EXISTS (SPEC §11 / "Задача №0")
+//
+// git is the state store, and git diffs byte-for-byte. The sync daemon does
+// `export(markdown) -> import(ProseMirror) -> export(markdown)` on every pull,
+// so if the *second* export differs from the first by even one byte, every
+// pull produces a phantom diff -> endless commits/conflicts. The single
+// property git actually needs is therefore MARKDOWN BYTE-STABILITY:
+//
+//     md2 := export(import(export(doc)))   MUST equal   md1 := export(doc)
+//
+// This file fuzzes that invariant with fast-check over randomly generated,
+// representative Docmost ProseMirror documents.
+//
+// ---------------------------------------------------------------------------
+// THE "SUPPORTED SPACE" PROBLEM
+//
+// A NAIVE generator surfaces two different kinds of `md2 !== md1`:
+//
+//   (a) GENUINE converter limitations — documented below as `it.fails` repros.
+//   (b) Inputs the converter LEGITIMATELY normalizes, i.e. markdown that is
+//       ambiguous or that the schema rewrites to a canonical form. These are
+//       NOT byte-stable by construction and are NOT bugs; the fix is to keep
+//       the generator inside the byte-stable / supported space.
+//
+// The following were all empirically confirmed (by probing the live converter)
+// and are EXCLUDED from / canonicalized by the byte-stable arbitrary. Each is a
+// markdown ambiguity or a schema/ProseMirror normalization, NOT a converter bug.
+//
+//   * Text that re-triggers block/inline markdown syntax on re-parse:
+//       - a leading `>`/`*`/`-`/`#`/`1.` turns a paragraph into a blockquote/
+//         list/heading;
+//       - `a  b` (2+ spaces) collapses to `a b`;
+//       - `<b>` / `</div>` parse as real HTML tags (and run-concatenation can
+//         form `<word>` across a run boundary);
+//       - `&amp;` / `&lt;` decode back to `&` / `<`;
+//       - a lone backtick is a code-span delimiter and re-pairs globally.
+//     -> The text arbitrary emits space-joined tokens that BEGIN and END with an
+//        alphanumeric word, with any single special char confined to the middle
+//        (space-flanked). Every char the task requires (* _ [ ] ( ) | < > &, and
+//        more) is covered this way; the backtick is exercised via code spans.
+//   * A purely numeric image `alt` ("0") or link `title` ("0") is parsed back as
+//     a NUMBER and dropped by the converter's `value || ""` -> alt/title always
+//     carry at least one letter.
+//   * Callout types other than info/success/warning/danger normalize to `info`
+//     (schema only knows those four) -> generator restricts to those four.
+//   * A list item / callout / blockquote with MULTIPLE block children: the
+//     converter joins them with a single "\n", which marked re-parses as ONE
+//     merged paragraph ("- p1\n  p2" -> "- p1 p2"). -> container bodies hold a
+//     SINGLE paragraph, optionally plus ONE nested list for lists.
+//   * `orderedList.start` / `1)` markers normalize to `1.` -> not emitted.
+//   * Two sibling lists sharing a marker family (bullet/task use "-", ordered
+//     uses "1.") MERGE into one list -> no two list blocks are adjacent.
+//   * TWO consecutive hard breaks render a blank line that marked eats as a
+//     paragraph break, and a trailing hard break is trimmed -> consecutive/
+//     trailing hard breaks are collapsed/removed.
+//   * Adjacent text runs with IDENTICAL marks ("**a****b****c**" -> "**abc**").
+//     A real ProseMirror doc never stores split same-mark runs (the editor
+//     coalesces them) -> the generator merges them too (normalizeInline).
+//
+// The GENUINE, real-but-intentional non-roundtrip limitations are kept HONEST as
+// `it.fails` blocks below (so the suite stays green only because they are marked
+// expected-to-fail, never by hiding them):
+//
+//   1. The `code` mark COMBINED with any other mark. The converter emits nested
+//      HTML (`<strong><code>x</code></strong>`), but the schema's `code` mark
+//      declares `excludes: "_"`, so on import every co-occurring mark is dropped
+//      and the run comes back as `code` only -> md2 == "`x`". Acknowledged in
+//      markdown-converter.ts (the long comment above the marks switch);
+//      impossible to round-trip both while `code` excludes them.
+//   2. A BLOCK-level `image` placed BETWEEN other blocks. The Docmost image node
+//      is block-level but `![](url)` is inline; marked wraps it in a <p>, the
+//      schema hoists the <img> out and leaves an empty paragraph sibling, which
+//      injects an extra blank gap on the second export. An image IS byte-stable
+//      as the sole block (edge artifacts get trimmed) — covered by a green test.
+// ---------------------------------------------------------------------------
+
+// Run a full export -> import -> export cycle and return both markdown strings.
+async function roundTrip(doc: unknown): Promise<{ md1: string; md2: string; doc2: any }> {
+  const md1 = convertProseMirrorToMarkdown(doc);
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, md2, doc2 };
+}
+
+const SEED = 42;
+const NUM_RUNS = 100;
+
+// ---------------------------------------------------------------------------
+// Inline text arbitraries
+// ---------------------------------------------------------------------------
+
+// Alphanumeric "word" (no markdown-significant characters). Length 1..6.
+const wordArb = fc
+  .stringMatching(/^[A-Za-z0-9]{1,6}$/)
+  .filter((w) => w.length > 0);
+
+// A SINGLE markdown-significant character, emitted only as an isolated,
+// space-flanked token. Every char the task calls out plus a few more; each was
+// verified byte-stable in this position.
+//
+// NOTE: the backtick (`) is DELIBERATELY excluded from free-floating plain
+// text. A lone backtick is a markdown code-span DELIMITER, so its round-trip
+// depends on GLOBAL backtick pairing: a stray backtick in running text adjacent
+// to a real code span ("A ` " + `code`) re-pairs into a different code span and
+// loses a space — genuinely outside the byte-stable space. The backtick is
+// still fully exercised as the `code`-mark delimiter and inside code blocks.
+const specialCharArb = fc.constantFrom(
+  '*', '_', '[', ']', '(', ')', '{', '}', '|', '<', '>', '&', '#', '!', '~', '=', '+', '-',
+);
+
+// Build a "safe special" text string: a space-joined sequence of tokens that
+// always BEGINS and ENDS with an alphanumeric word, with any isolated special
+// chars confined to the MIDDLE (each space-flanked by words).
+//
+// Both boundary guarantees matter:
+//   * Leading word: the line never opens with a block/inline trigger
+//     (">", "*", "-", "#", "1." ...).
+//   * Trailing word: adjacent text runs CONCATENATE with no separator, so a run
+//     ending in a bare "<" beside a run starting with a letter would form a fake
+//     HTML tag ("...0 <" + "A >" -> "0 <A >"), which marked/jsdom strips. Ending
+//     every run with an alphanumeric word keeps every special internal and
+//     space-flanked even after concatenation.
+const safeTextArb: fc.Arbitrary<string> = fc
+  .tuple(
+    wordArb,
+    fc.array(fc.oneof(wordArb, specialCharArb), { minLength: 0, maxLength: 3 }),
+    wordArb,
+  )
+  .map(([first, middle, last]) => [first, ...middle, last].join(' '));
+
+// A plain alphanumeric phrase (1..3 words) for places where even isolated
+// specials are not wanted (e.g. code-block language, mention labels).
+const phraseArb: fc.Arbitrary<string> = fc
+  .array(wordArb, { minLength: 1, maxLength: 3 })
+  .map((ws) => ws.join(' '));
+
+// A phrase guaranteed to contain at least one letter. Used for image alt text:
+// a PURELY numeric alt (e.g. "0", "00") is parsed back by the schema as a
+// NUMBER, and the converter's `alt || ""` then treats the number 0 as falsy and
+// DROPS the alt ("![0](u)" -> "![](u)") — not byte-stable. A letter anywhere in
+// the alt keeps it a string and avoids the coercion.
+const letterPhraseArb: fc.Arbitrary<string> = fc
+  .tuple(
+    fc.stringMatching(/^[A-Za-z]{1,4}$/),
+    fc.array(wordArb, { minLength: 0, maxLength: 2 }),
+  )
+  .map(([head, rest]) => [head, ...rest].join(' '));
+
+
+// A text run with an OPTIONAL single non-code mark (bold/italic/strike), or a
+// SOLE `code` mark, or a link. `code` is never combined with another mark in
+// the byte-stable arbitrary (that combination is the known bug, exercised
+// separately in the it.fails block). Marks wrap safe text, which stays stable
+// even when it contains isolated specials.
+const markedTextRunArb: fc.Arbitrary<any> = fc.oneof(
+  // Plain text.
+  safeTextArb.map((t) => ({ type: 'text', text: t })),
+  // Single formatting mark.
+  fc
+    .tuple(safeTextArb, fc.constantFrom('bold', 'italic', 'strike'))
+    .map(([t, m]) => ({ type: 'text', text: t, marks: [{ type: m }] })),
+  // Sole code mark (backtick span). safeTextArb is already backtick-free, so the
+  // code span content cannot contain an inner backtick (which would be
+  // ambiguous to re-parse).
+  safeTextArb.map((t) => ({ type: 'text', text: t, marks: [{ type: 'code' }] })),
+  // Link with safe text and a paren/space-free href, optionally with a title.
+  // The title rides in a markdown link-title attribute; a purely numeric title
+  // is coerced to a number and dropped on re-import (same class of quirk as the
+  // image alt), so the title always carries at least one letter.
+  fc
+    .tuple(
+      phraseArb,
+      fc.webUrl().filter((u) => !/[()\s]/.test(u)),
+      fc.option(letterPhraseArb, { nil: undefined }),
+    )
+    .map(([t, href, title]) => ({
+      type: 'text',
+      text: t,
+      marks: [{ type: 'link', attrs: title ? { href, title } : { href } }],
+    })),
+  // Inline COMMENT anchor (SPEC §3): a span[data-comment-id] that must survive
+  // the round-trip byte-for-byte. The commentId is an alphanumeric token (no
+  // attribute-breaking chars), and `resolved` rides as data-resolved="true"
+  // only when true — both forms were verified byte-stable.
+  fc
+    .tuple(safeTextArb, fc.stringMatching(/^[A-Za-z0-9]{4,10}$/), fc.boolean())
+    .map(([t, commentId, resolved]) => ({
+      type: 'text',
+      text: t,
+      marks: [
+        {
+          type: 'comment',
+          attrs: resolved ? { commentId, resolved: true } : { commentId },
+        },
+      ],
+    })),
+);
+
+// Inline math node carrying LaTeX that includes the `a < b` the task asks for.
+const mathInlineArb: fc.Arbitrary<any> = fc
+  .constantFrom('a < b', 'x^2 + y^2', 'a < b < c', '\\frac{1}{2}', 'E = mc^2')
+  .map((text) => ({ type: 'mathInline', attrs: { text } }));
+
+// Mention node (schema attrs); label/id are plain phrases.
+const mentionArb: fc.Arbitrary<any> = fc
+  .tuple(phraseArb, fc.uuid(), fc.uuid())
+  .map(([label, id, entityId]) => ({
+    type: 'mention',
+    attrs: { id, label, entityType: 'user', entityId },
+  }));
+
+const hardBreakArb: fc.Arbitrary<any> = fc.constant({ type: 'hardBreak' });
+
+// Canonicalize a generated inline-content array the way ProseMirror itself
+// stores inline content, then trim the markdown-fragile edges. Applied to both
+// paragraph and heading inline content.
+//
+//   1) MERGE adjacent `text` runs that carry IDENTICAL marks. A real
+//      ProseMirror document never stores two neighbouring runs with the same
+//      mark set — the editor coalesces them into one. A naive generator that
+//      leaves them split produces UNREALISTIC docs AND breaks byte-stability:
+//      three adjacent bold runs export as "**a****b****c**", whose inner
+//      "****" boundaries are ambiguous and re-parse as a single "**abc**".
+//      Merging makes the generated doc canonical and the markdown stable.
+//   2) Collapse CONSECUTIVE hard breaks. Two in a row render as "  \n  \n",
+//      whose middle whitespace-only line marked treats as a paragraph break, so
+//      "a  \n  \nb" re-parses to "a\n\nb". A SINGLE hard break round-trips.
+//   3) Drop a TRAILING hard break: "...  \n" sits at the paragraph edge and is
+//      removed by the converter's .trim().
+const sameMarks = (a: any[] | undefined, b: any[] | undefined): boolean =>
+  JSON.stringify(a ?? []) === JSON.stringify(b ?? []);
+
+function normalizeInline(nodes: any[]): any[] {
+  const out: any[] = [];
+  for (const node of nodes) {
+    const prev = out[out.length - 1];
+    // Collapse a second consecutive hard break.
+    if (node.type === 'hardBreak' && prev && prev.type === 'hardBreak') {
+      continue;
+    }
+    // Merge an adjacent text run with the same marks.
+    if (
+      node.type === 'text' &&
+      prev &&
+      prev.type === 'text' &&
+      sameMarks(prev.marks, node.marks)
+    ) {
+      prev.text += node.text;
+      continue;
+    }
+    // Clone text nodes so the in-place merge above never mutates a shared value.
+    out.push(node.type === 'text' ? { ...node } : node);
+  }
+  while (out.length > 1 && out[out.length - 1].type === 'hardBreak') {
+    out.pop();
+  }
+  return out;
+}
+
+// Inline content for a paragraph: at least one marked text run, optionally with
+// inline atoms (math/mention) and hard breaks interspersed. Always starts with a
+// text run so the paragraph never opens with a block trigger.
+const inlineContentArb: fc.Arbitrary<any[]> = fc
+  .tuple(
+    markedTextRunArb,
+    fc.array(
+      fc.oneof(
+        { weight: 5, arbitrary: markedTextRunArb },
+        { weight: 1, arbitrary: mathInlineArb },
+        { weight: 1, arbitrary: mentionArb },
+        { weight: 1, arbitrary: hardBreakArb },
+      ),
+      { minLength: 0, maxLength: 4 },
+    ),
+  )
+  .map(([first, rest]) => normalizeInline([first, ...rest]));
+
+// Inline content for a HEADING — identical to a paragraph's, but WITHOUT hard
+// breaks. A hard break inside an ATX heading ("# a  \nb") is NOT byte-stable:
+// marked does not honour a hard break inside a heading, so it re-parses as the
+// heading "# a" plus a separate paragraph "b" (md2 = "# a\n\nb"). math/mention/
+// link inside a heading are fine (verified) and stay in the menu.
+const headingInlineContentArb: fc.Arbitrary<any[]> = fc
+  .tuple(
+    markedTextRunArb,
+    fc.array(
+      fc.oneof(
+        { weight: 5, arbitrary: markedTextRunArb },
+        { weight: 1, arbitrary: mathInlineArb },
+        { weight: 1, arbitrary: mentionArb },
+      ),
+      { minLength: 0, maxLength: 4 },
+    ),
+  )
+  .map(([first, rest]) => normalizeInline([first, ...rest]));
+
+// ---------------------------------------------------------------------------
+// Block arbitraries
+// ---------------------------------------------------------------------------
+
+const paragraphArb: fc.Arbitrary<any> = inlineContentArb.map((content) => ({
+  type: 'paragraph',
+  content,
+}));
+
+const headingArb: fc.Arbitrary<any> = fc
+  .tuple(fc.integer({ min: 1, max: 6 }), headingInlineContentArb)
+  .map(([level, content]) => ({ type: 'heading', attrs: { level }, content }));
+
+// Code block content: 1..4 lines of plain phrases (may contain specials inline,
+// which are inert inside a fenced block). Language is optional and is a single
+// lowercase token.
+const codeBlockArb: fc.Arbitrary<any> = fc
+  .tuple(
+    fc.option(fc.constantFrom('js', 'ts', 'python', 'go', 'rust', 'bash'), {
+      nil: '',
+    }),
+    fc
+      .array(safeTextArb, { minLength: 1, maxLength: 4 })
+      .map((lines) => lines.join('\n')),
+  )
+  .map(([language, code]) => ({
+    type: 'codeBlock',
+    attrs: { language },
+    content: [{ type: 'text', text: code }],
+  }));
+
+const blockquoteArb: fc.Arbitrary<any> = paragraphArb.map((p) => ({
+  type: 'blockquote',
+  content: [p],
+}));
+
+const horizontalRuleArb: fc.Arbitrary<any> = fc.constant({
+  type: 'horizontalRule',
+});
+
+// Callout: ONE paragraph child; type restricted to the four the schema knows.
+const calloutArb: fc.Arbitrary<any> = fc
+  .tuple(
+    fc.constantFrom('info', 'success', 'warning', 'danger'),
+    paragraphArb,
+  )
+  .map(([type, p]) => ({ type: 'callout', attrs: { type }, content: [p] }));
+
+const mathBlockArb: fc.Arbitrary<any> = fc
+  .constantFrom('a < b', 'a < b < c', '\\sum_{i=0}^{n} i', 'x = \\frac{-b}{2a}', '')
+  .map((text) => ({ type: 'mathBlock', attrs: { text } }));
+
+const imageArb: fc.Arbitrary<any> = fc
+  .tuple(
+    fc.webUrl(),
+    // alt is a letter-bearing phrase OR empty. Brackets/parens leak into the
+    // markdown image syntax (not byte-stable) so they are excluded, and a purely
+    // numeric alt is coerced to a number and dropped (see letterPhraseArb), so
+    // alt always carries at least one letter when non-empty.
+    fc.option(letterPhraseArb, { nil: '' }),
+  )
+  .map(([src, alt]) => ({ type: 'image', attrs: { src, alt } }));
+
+// A simple list item: ONE paragraph, optionally followed by ONE nested bullet
+// list (single level of nesting). depth controls whether nesting is allowed.
+function listItemArb(allowNest: boolean): fc.Arbitrary<any> {
+  if (!allowNest) {
+    return paragraphArb.map((p) => ({ type: 'listItem', content: [p] }));
+  }
+  return fc
+    .tuple(
+      paragraphArb,
+      fc.option(
+        fc.array(
+          paragraphArb.map((p) => ({ type: 'listItem', content: [p] })),
+          { minLength: 1, maxLength: 3 },
+        ),
+        { nil: undefined },
+      ),
+    )
+    .map(([p, nested]) => ({
+      type: 'listItem',
+      content: nested
+        ? [p, { type: 'bulletList', content: nested }]
+        : [p],
+    }));
+}
+
+const bulletListArb: fc.Arbitrary<any> = fc
+  .array(listItemArb(true), { minLength: 1, maxLength: 4 })
+  .map((items) => ({ type: 'bulletList', content: items }));
+
+const orderedListArb: fc.Arbitrary<any> = fc
+  .array(listItemArb(true), { minLength: 1, maxLength: 4 })
+  .map((items) => ({ type: 'orderedList', content: items }));
+
+// Task item: ONE paragraph, optional ONE nested bullet list.
+const taskItemArb: fc.Arbitrary<any> = fc
+  .tuple(
+    fc.boolean(),
+    paragraphArb,
+    fc.option(
+      fc.array(listItemArb(false), { minLength: 1, maxLength: 2 }),
+      { nil: undefined },
+    ),
+  )
+  .map(([checked, p, nested]) => ({
+    type: 'taskItem',
+    attrs: { checked },
+    content: nested ? [p, { type: 'bulletList', content: nested }] : [p],
+  }));
+
+const taskListArb: fc.Arbitrary<any> = fc
+  .array(taskItemArb, { minLength: 1, maxLength: 4 })
+  .map((items) => ({ type: 'taskList', content: items }));
+
+// GFM table: a header row + 1..3 body rows, with a fixed column count (1..3) and
+// per-column alignment. Cells hold a single short paragraph of safe text.
+const tableArb: fc.Arbitrary<any> = fc
+  .integer({ min: 1, max: 3 })
+  .chain((cols) => {
+    const cellArb = (header: boolean, align?: string) =>
+      phraseArb.map((t) => ({
+        type: header ? 'tableHeader' : 'tableCell',
+        attrs: align ? { align } : {},
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: t }] }],
+      }));
+    const alignsArb = fc.array(
+      fc.constantFrom(undefined, 'left', 'center', 'right'),
+      { minLength: cols, maxLength: cols },
+    );
+    return fc
+      .tuple(
+        alignsArb,
+        fc.array(
+          fc.constant(null), // body-row placeholders; cells filled below
+          { minLength: 1, maxLength: 3 },
+        ),
+      )
+      .chain(([aligns, bodyRows]) => {
+        const headerRow = fc
+          .tuple(...aligns.map((a) => cellArb(true, a)))
+          .map((cells) => ({ type: 'tableRow', content: cells }));
+        const bodyRowArbs = bodyRows.map(() =>
+          fc
+            .tuple(...aligns.map(() => cellArb(false)))
+            .map((cells) => ({ type: 'tableRow', content: cells })),
+        );
+        return fc
+          .tuple(headerRow, fc.tuple(...bodyRowArbs))
+          .map(([h, body]) => ({ type: 'table', content: [h, ...body] }));
+      });
+  });
+
+// ---------------------------------------------------------------------------
+// Top-level document arbitrary
+// ---------------------------------------------------------------------------
+
+// The full menu of block nodes that are byte-stable when SEQUENCED with other
+// blocks. NOTE: `image` is deliberately NOT in this menu — see the dedicated
+// image tests below. The Docmost `image` node is BLOCK-level, but its markdown
+// form `![](url)` is INLINE; marked wraps it in a <p>, the schema then hoists
+// the block <img> out and leaves an EMPTY paragraph beside it, so on the second
+// export the stray empty paragraph injects extra blank lines between siblings
+// ("p\n\n![](u)\n\nq" -> "p\n\n\n\n![](u)\n\nq"). An image is only byte-stable
+// when it is the SOLE block (the edge artifacts get .trim()'d away). It is
+// therefore covered by its own targeted tests, not mixed into multi-block docs.
+const blockArb: fc.Arbitrary<any> = fc.oneof(
+  { weight: 6, arbitrary: paragraphArb },
+  { weight: 3, arbitrary: headingArb },
+  { weight: 2, arbitrary: codeBlockArb },
+  { weight: 2, arbitrary: bulletListArb },
+  { weight: 2, arbitrary: orderedListArb },
+  { weight: 2, arbitrary: taskListArb },
+  { weight: 2, arbitrary: blockquoteArb },
+  { weight: 2, arbitrary: tableArb },
+  { weight: 2, arbitrary: calloutArb },
+  { weight: 1, arbitrary: horizontalRuleArb },
+  { weight: 1, arbitrary: mathBlockArb },
+);
+
+const LIST_TYPES = new Set(['bulletList', 'orderedList', 'taskList']);
+
+// A bounded document: 1..8 block nodes. Kept small so each run is cheap (each
+// run does a real marked + jsdom parse) and shrinking stays fast.
+//
+// Post-process: never let two LIST blocks sit directly adjacent. Two sibling
+// lists that share a marker family — bullet/task both use "-", ordered uses
+// "1." — are MERGED by markdown into a single list when only a blank line
+// separates them ("- a\n\n- b" -> one list -> "- a\n- b"), which is not
+// byte-stable. (A non-list block between two lists separates them fine, as does
+// a different marker family, but dropping every back-to-back list is the clean,
+// always-correct rule.) We drop a list block whenever the previously kept block
+// is also a list.
+const docArb: fc.Arbitrary<any> = fc
+  .array(blockArb, { minLength: 1, maxLength: 8 })
+  .map((content) => {
+    const out: any[] = [];
+    for (const block of content) {
+      const prev = out[out.length - 1];
+      if (
+        prev &&
+        LIST_TYPES.has(prev.type) &&
+        LIST_TYPES.has(block.type)
+      ) {
+        continue; // skip a list that would sit right after another list
+      }
+      out.push(block);
+    }
+    // Guarantee a non-empty document even if filtering removed everything but a
+    // single dropped block (cannot happen here since the first block is always
+    // kept, but keep the invariant explicit).
+    return { type: 'doc', content: out.length ? out : content.slice(0, 1) };
+  });
+
+// ---------------------------------------------------------------------------
+// The properties
+// ---------------------------------------------------------------------------
+
+describe('markdown <-> ProseMirror round-trip (property-based)', () => {
+  it('the generator covers every targeted node type at least once', () => {
+    // A sanity check that the arbitrary actually exercises the intended node
+    // variety within NUM_RUNS — not a correctness property, just coverage.
+    const seen = new Set<string>();
+    const collect = (node: any) => {
+      if (!node || typeof node !== 'object') return;
+      if (node.type) seen.add(node.type);
+      for (const m of node.marks ?? []) seen.add(`mark:${m.type}`);
+      for (const c of node.content ?? []) collect(c);
+    };
+    fc.assert(
+      fc.property(docArb, (doc) => {
+        collect(doc);
+        return true;
+      }),
+      { numRuns: NUM_RUNS, seed: SEED },
+    );
+    // Core block types and marks we expect to appear.
+    for (const t of [
+      'paragraph',
+      'heading',
+      'codeBlock',
+      'bulletList',
+      'orderedList',
+      'taskList',
+      'blockquote',
+      'table',
+      'callout',
+      'horizontalRule',
+      'mathBlock',
+      // 'image' is covered by its own dedicated tests, not docArb.
+      'mention',
+      'mathInline',
+      'hardBreak',
+      'mark:bold',
+      'mark:italic',
+      'mark:strike',
+      'mark:code',
+      'mark:link',
+      'mark:comment',
+    ]) {
+      expect(seen, `expected the generator to produce ${t}`).toContain(t);
+    }
+  });
+
+  it('markdown is byte-stable across export -> import -> export', async () => {
+    // The property git needs: a second export reproduces the first byte-for-byte.
+    await fc.assert(
+      fc.asyncProperty(docArb, async (doc) => {
+        const { md1, md2 } = await roundTrip(doc);
+        expect(md2).toBe(md1);
+      }),
+      { numRuns: NUM_RUNS, seed: SEED },
+    );
+  });
+
+  it('the document is semantically stable on a second cycle (ids stripped)', async () => {
+    // Optional, stronger-feeling property. We do NOT compare doc vs doc2: the
+    // converter reconstructs schema default attrs on the FIRST import (a known
+    // SPEC §11 divergence). But once the markdown is byte-stable, importing the
+    // SAME markdown twice must yield structurally identical docs (modulo the
+    // regenerated block ids). So we compare doc2 (import of md1) with doc3
+    // (import of md2 == md1) after stripping ids.
+    await fc.assert(
+      fc.asyncProperty(docArb, async (doc) => {
+        const md1 = convertProseMirrorToMarkdown(doc);
+        const doc2 = await markdownToProseMirror(md1);
+        const md2 = convertProseMirrorToMarkdown(doc2);
+        // Guard: this property only makes sense when md is byte-stable.
+        expect(md2).toBe(md1);
+        const doc3 = await markdownToProseMirror(md2);
+        expect(stripBlockIds(doc3)).toEqual(stripBlockIds(doc2));
+      }),
+      { numRuns: NUM_RUNS, seed: SEED },
+    );
+  });
+
+  it('a SOLE image block is byte-stable', async () => {
+    // An image is byte-stable when it is the only block in the document: the
+    // stray empty paragraph the schema leaves beside the hoisted block <img>
+    // sits at a document edge and is removed by the converter's final .trim().
+    await fc.assert(
+      fc.asyncProperty(imageArb, async (image) => {
+        const doc = { type: 'doc', content: [image] };
+        const { md1, md2 } = await roundTrip(doc);
+        expect(md2).toBe(md1);
+      }),
+      { numRuns: NUM_RUNS, seed: SEED },
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // KNOWN, DOCUMENTED non-roundtrip bug #2 (kept honest as it.fails).
+  //
+  // BUG: a block-level `image` placed BETWEEN other blocks is not byte-stable.
+  // The Docmost image node is BLOCK-level but its markdown form `![](url)` is
+  // INLINE. marked wraps the inline image in a <p>; the schema then hoists the
+  // block <img> out of that <p>, leaving an EMPTY paragraph as a sibling. On the
+  // second export that empty paragraph renders as "" and the "\n\n" doc join
+  // injects an extra blank gap:
+  //   "p\n\n![x](u)\n\nq"  ->  "p\n\n\n\n![x](u)\n\nq"   (=> md2 !== md1).
+  // Minimal repro doc:
+  //   { type:'doc', content:[
+  //       { type:'paragraph', content:[{type:'text',text:'p'}] },
+  //       { type:'image', attrs:{ src:'http://a.aa', alt:'x' } },
+  //       { type:'paragraph', content:[{type:'text',text:'q'}] } ] }
+  // Not "fixed" — the source must not change; documented and exercised here.
+  // -------------------------------------------------------------------------
+  it('a block image between other blocks is byte-stable', async () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'p' }] },
+        { type: 'image', attrs: { src: 'http://a.aa', alt: 'x' } },
+        { type: 'paragraph', content: [{ type: 'text', text: 'q' }] },
+      ],
+    };
+    const { md1, md2 } = await roundTrip(doc);
+    expect(md2).toBe(md1);
+  });
+
+  // -------------------------------------------------------------------------
+  // KNOWN, DOCUMENTED non-roundtrip bug #1 (kept honest as it.fails).
+  //
+  // BUG: the `code` mark combined with ANY other mark does NOT round-trip.
+  // The converter emits nested HTML so the output is well-formed, e.g.
+  //   marks [code, bold]  ->  md1 = "<strong><code>x</code></strong>"
+  // but the schema's `code` mark declares `excludes: "_"`, so on import the
+  // co-occurring mark is dropped and the run comes back as code-only:
+  //   md2 = "`x`"   (=> md2 !== md1).
+  // Minimal repro doc:
+  //   { type:'doc', content:[ { type:'paragraph', content:[
+  //       { type:'text', text:'x', marks:[{type:'code'},{type:'bold'}] } ] } ] }
+  // This is acknowledged in markdown-converter.ts (the long comment above the
+  // marks switch): preserving both marks is impossible while `code` excludes
+  // them. Documented here, not "fixed", because the source must not change.
+  // -------------------------------------------------------------------------
+  it(
+    'code mark combined with another mark is byte-stable',
+    async () => {
+      const codeComboArb = fc
+        .tuple(safeTextArb, fc.constantFrom('bold', 'italic', 'strike'))
+        .map(([t, other]) => ({
+          type: 'doc',
+          content: [
+            {
+              type: 'paragraph',
+              content: [
+                { type: 'text', text: t, marks: [{ type: 'code' }, { type: other }] },
+              ],
+            },
+          ],
+        }));
+      await fc.assert(
+        fc.asyncProperty(codeComboArb, async (doc) => {
+          const { md1, md2 } = await roundTrip(doc);
+          expect(md2).toBe(md1);
+        }),
+        { numRuns: 20, seed: SEED },
+      );
+    },
+  );
+});
diff --git a/packages/prosemirror-markdown/test/markdown-to-prosemirror-gaps.test.ts b/packages/prosemirror-markdown/test/markdown-to-prosemirror-gaps.test.ts
new file mode 100644
index 00000000..7fdf29e9
--- /dev/null
+++ b/packages/prosemirror-markdown/test/markdown-to-prosemirror-gaps.test.ts
@@ -0,0 +1,535 @@
+import { describe, expect, it } from 'vitest';
+// markdownToProseMirror lives next to the markdown->HTML preprocessors
+// (preprocessCallouts, bridgeTaskLists). Those helpers are NOT exported, so we
+// exercise them through the public entry point, which runs the full
+// markdown -> preprocessCallouts -> marked -> bridgeTaskLists -> generateJSON
+// pipeline. Importing this module mutates the global DOM via jsdom (required for
+// @tiptap/html under Node) — expected, same as the property test.
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+// The export side (ProseMirror -> markdown) is pulled in for the round-trip
+// specs below (underline/sub/sup marks, heading levels, link title). Imported
+// directly from src/lib (not the barrel) like the other converter unit tests.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+
+// Find every node of a given type anywhere in a ProseMirror doc tree.
+const findAll = (node: any, type: string, acc: any[] = []): any[] => {
+  if (node && node.type === type) acc.push(node);
+  for (const child of node?.content || []) findAll(child, type, acc);
+  return acc;
+};
+// Concatenate all text within a subtree (order-preserving).
+const allText = (node: any): string => {
+  if (node?.type === 'text') return node.text || '';
+  return (node?.content || []).map(allText).join('');
+};
+
+// ---------------------------------------------------------------------------
+// Obsidian-native callouts: the export emits `> [!type]` (a blockquote callout,
+// which renders as a callout in Obsidian) and the importer parses it back —
+// alongside the legacy `:::type` fence so existing vaults keep working.
+// ---------------------------------------------------------------------------
+describe('preprocessCallouts: Obsidian `> [!type]` callouts', () => {
+  it('imports `> [!type]` as a callout node (not a plain blockquote)', async () => {
+    const md = ['> [!warning]', '> be careful', '> second line'].join('\n');
+    const docNode = await markdownToProseMirror(md);
+    const callouts = findAll(docNode, 'callout');
+    expect(callouts).toHaveLength(1);
+    expect(callouts[0].attrs?.type).toBe('warning');
+    expect(findAll(docNode, 'blockquote')).toHaveLength(0);
+    expect(allText(callouts[0])).toContain('be careful');
+  });
+
+  it('imports a nested `> > [!type]` callout inside another', async () => {
+    const md = ['> [!info]', '> outer', '> > [!danger]', '> > inner'].join('\n');
+    const docNode = await markdownToProseMirror(md);
+    const outer = docNode.content?.[0];
+    expect(outer?.type).toBe('callout');
+    expect(outer?.attrs?.type).toBe('info');
+    const inner = (outer?.content || []).filter(
+      (n: any) => n.type === 'callout',
+    );
+    expect(inner).toHaveLength(1);
+    expect(inner[0].attrs?.type).toBe('danger');
+    expect(allText(inner[0])).toContain('inner');
+  });
+
+  it('round-trips a callout: export -> `> [!type]` -> import keeps type + body', async () => {
+    const original = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          attrs: { type: 'success' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'done' }] }],
+        },
+      ],
+    };
+    const md = convertProseMirrorToMarkdown(original);
+    expect(md).toBe('> [!success]\n> done');
+    const back = await markdownToProseMirror(md);
+    const callouts = findAll(back, 'callout');
+    expect(callouts).toHaveLength(1);
+    expect(callouts[0].attrs?.type).toBe('success');
+    expect(allText(callouts[0])).toContain('done');
+  });
+
+  it('a plain blockquote (no `[!type]`) stays a blockquote', async () => {
+    const back = await markdownToProseMirror('> just a quote\n> more');
+    expect(findAll(back, 'callout')).toHaveLength(0);
+    expect(findAll(back, 'blockquote')).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. preprocessCallouts — two uncovered branches.
+//
+// (a) NESTED callouts: an inner `:::type ... :::` inside an outer callout body
+//     must be matched at its own nesting level (the depth counter) and emerge as
+//     a callout NESTED inside the outer callout — not flattened or mis-closed.
+// (b) A `:::` line INSIDE a fenced code block must NOT be treated as a callout
+//     delimiter: the scanner tracks code fences and copies their lines verbatim,
+//     so the outer callout's matching `:::` is the one AFTER the fence closes.
+// ---------------------------------------------------------------------------
+describe('preprocessCallouts: nested callouts + code-fenced ":::"', () => {
+  it('(a) parses a callout nested inside another callout', async () => {
+    const md = [
+      ':::info',
+      'outer text',
+      ':::warning',
+      'inner text',
+      ':::',
+      ':::',
+    ].join('\n');
+
+    const docNode = await markdownToProseMirror(md);
+
+    // Exactly two callouts, and one is nested inside the other.
+    const callouts = findAll(docNode, 'callout');
+    expect(callouts).toHaveLength(2);
+
+    const outer = docNode.content?.[0];
+    expect(outer?.type).toBe('callout');
+    expect(outer?.attrs?.type).toBe('info');
+
+    // The inner callout is a CHILD of the outer one (not a sibling at doc level).
+    const innerCallouts = (outer?.content || []).filter(
+      (n: any) => n.type === 'callout',
+    );
+    expect(innerCallouts).toHaveLength(1);
+    expect(innerCallouts[0].attrs?.type).toBe('warning');
+
+    // Both bodies kept their text.
+    expect(allText(outer)).toContain('outer text');
+    expect(allText(innerCallouts[0])).toContain('inner text');
+  });
+
+  it('(b) a ":::" line inside a fenced code block is NOT a callout delimiter', async () => {
+    // The inner ``` ... ``` fence contains a `:::` line. If preprocessCallouts
+    // treated it as the closing fence, the callout would terminate early and the
+    // code text would leak out. The correct behavior: the fence content survives
+    // verbatim in a codeBlock, and the callout closes at the LAST ":::".
+    const md = [
+      ':::info',
+      'before code',
+      '```',
+      ':::',
+      'still inside the code fence',
+      '```',
+      'after code',
+      ':::',
+    ].join('\n');
+
+    const docNode = await markdownToProseMirror(md);
+
+    // One callout wrapping everything (it did not close early on the fenced ":::")
+    const callouts = findAll(docNode, 'callout');
+    expect(callouts).toHaveLength(1);
+    const callout = callouts[0];
+
+    // The code block is a CHILD of the callout and still contains the ":::" line.
+    const codeBlocks = findAll(callout, 'codeBlock');
+    expect(codeBlocks).toHaveLength(1);
+    expect(allText(codeBlocks[0])).toContain(':::');
+    expect(allText(codeBlocks[0])).toContain('still inside the code fence');
+
+    // The text before and after the fence is part of the callout, not a stray
+    // top-level paragraph created by an early close.
+    expect(allText(callout)).toContain('before code');
+    expect(allText(callout)).toContain('after code');
+  });
+
+  it('(c) an UNCLOSED ":::" opener is treated as a literal line, not a callout', async () => {
+    // Realistic input: a hand-edited vault file with a `:::info` opener and no
+    // matching closing `:::`. The fallback emits the opener as a LITERAL line
+    // rather than swallowing the rest of the document into a phantom callout —
+    // previously uncovered (markdown-to-prosemirror.ts).
+    const md = [':::info', 'orphan body line', 'another line'].join('\n');
+
+    const docNode = await markdownToProseMirror(md);
+
+    // No callout node was created (the opener never closed).
+    expect(findAll(docNode, 'callout')).toHaveLength(0);
+    // The opener survives as literal text and the body lines are preserved (the
+    // rest of the document was NOT eaten by an unterminated callout).
+    const text = allText(docNode);
+    expect(text).toContain(':::info');
+    expect(text).toContain('orphan body line');
+    expect(text).toContain('another line');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. bridgeTaskLists — numbered checklist + mixed-list negative.
+//
+// (a) A NUMBERED checklist (`1. [x] ...`) is rendered by marked as an <ol> of
+//     checkbox <li>s. The bridge must convert it to a taskList AND rename the
+//     <ol> to a <ul> so generateJSON does NOT also match the orderedList rule
+//     and emit a phantom empty orderedList beside the real taskList.
+// (b) NEGATIVE: a MIXED list (some items have checkboxes, some don't) must NOT
+//     be converted — it stays an ordinary bullet/numbered list.
+// ---------------------------------------------------------------------------
+describe('bridgeTaskLists: numbered checklist + mixed-list negative', () => {
+  it('(a) a numbered <ol> checklist becomes a taskList with NO phantom orderedList', async () => {
+    const md = ['1. [x] done', '2. [ ] todo'].join('\n');
+
+    const docNode = await markdownToProseMirror(md);
+
+    // It became a taskList...
+    const taskLists = findAll(docNode, 'taskList');
+    expect(taskLists).toHaveLength(1);
+
+    const items = (taskLists[0].content || []).filter(
+      (n: any) => n.type === 'taskItem',
+    );
+    expect(items).toHaveLength(2);
+    expect(items[0].attrs?.checked).toBe(true);
+    expect(items[1].attrs?.checked).toBe(false);
+    expect(allText(items[0])).toContain('done');
+    expect(allText(items[1])).toContain('todo');
+
+    // ...and NO phantom (empty) orderedList survived the <ol> -> <ul> rename.
+    const orderedLists = findAll(docNode, 'orderedList');
+    expect(orderedLists).toHaveLength(0);
+  });
+
+  it('(b) a MIXED list (some items checkboxed, some not) is NOT converted to a taskList', async () => {
+    const md = ['- [x] checked item', '- plain item'].join('\n');
+
+    const docNode = await markdownToProseMirror(md);
+
+    // The bridge requires EVERY direct <li> to carry its own checkbox; one plain
+    // item disqualifies the whole list, so it stays a bulletList.
+    expect(findAll(docNode, 'taskList')).toHaveLength(0);
+    expect(findAll(docNode, 'taskItem')).toHaveLength(0);
+
+    const bulletLists = findAll(docNode, 'bulletList');
+    expect(bulletLists).toHaveLength(1);
+    const listItems = findAll(bulletLists[0], 'listItem');
+    expect(listItems).toHaveLength(2);
+    // Both items survive as ordinary list items (text preserved).
+    expect(allText(bulletLists[0])).toContain('checked item');
+    expect(allText(bulletLists[0])).toContain('plain item');
+  });
+});
+
+// Find the first mark of a given type on a text node anywhere in the tree.
+const firstMark = (node: any, markType: string): any => {
+  if (node?.type === 'text') {
+    for (const m of node.marks || []) if (m.type === markType) return m;
+  }
+  for (const child of node?.content || []) {
+    const found = firstMark(child, markType);
+    if (found) return found;
+  }
+  return null;
+};
+
+// ---------------------------------------------------------------------------
+// Spec 1. IMPORT-side color sanitization for the highlight + textStyle marks.
+//
+// The Highlight.extend / TextStyle parseHTML run attacker-controlled colors
+// through sanitizeCssColor when generateJSON re-parses stored HTML. This is the
+// real defense that strips a crafted color on IMPORT (the export-side emission
+// is tested elsewhere; the parse path was not).
+// ---------------------------------------------------------------------------
+describe('import: highlight/textStyle color sanitization (parseHTML)', () => {
+  it('strips the unsafe "--x:1" declaration but keeps the safe "red" background-color', async () => {
+    const doc = await markdownToProseMirror(
+      '<mark style="background-color: red; --x:1">x</mark>',
+    );
+    const mark = firstMark(doc, 'highlight');
+    // The highlight mark IS present on the text run.
+    expect(mark).not.toBeNull();
+    expect(allText(doc)).toContain('x');
+    // NOTE(review): Spec 1 expected attrs.color === null for this input. The
+    // ACTUAL behavior is attrs.color === 'red': the schema's Highlight.extend
+    // reads the color via getStyleProperty(el, 'background-color'), which
+    // isolates the `background-color: red` declaration and DROPS the separate
+    // unsafe `--x:1` declaration. sanitizeCssColor('red') then accepts the bare
+    // named color. So the injection ('--x:1') is stripped (the defense holds)
+    // but the legitimate 'red' survives — color is 'red', not null. The
+    // color-dropped-to-null path is exercised by the data-color variant below,
+    // where the whole "red; --x:1" string reaches sanitizeCssColor and fails.
+    expect(mark.attrs.color).toBe('red');
+  });
+
+  it('drops a crafted color carried whole in data-color (sanitizeCssColor -> null)', async () => {
+    // Here the entire unsafe string is the candidate color (no per-declaration
+    // splitting), so sanitizeCssColor rejects it and the highlight color is null
+    // while the highlight mark itself is still applied.
+    const doc = await markdownToProseMirror(
+      '<mark data-color="red; --x:1">x</mark>',
+    );
+    const mark = firstMark(doc, 'highlight');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.color).toBeNull();
+  });
+
+  it("imports '#ff0000' as the highlight mark color verbatim", async () => {
+    const doc = await markdownToProseMirror(
+      '<mark style="background-color: #ff0000">x</mark>',
+    );
+    const mark = firstMark(doc, 'highlight');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.color).toBe('#ff0000');
+  });
+
+  it("imports a colored span as a textStyle mark with the sanitized color", async () => {
+    const doc = await markdownToProseMirror(
+      '<span style="color: rebeccapurple">y</span>',
+    );
+    const mark = firstMark(doc, 'textStyle');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.color).toBe('rebeccapurple');
+    // It is carried on a real text node containing the span's text.
+    expect(allText(doc)).toContain('y');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 2. Importing a non-schema callout fence resolves the type via the editor's
+// alias map (known GitHub/Obsidian aliases) or clamps to 'info' (unknown).
+//
+// preprocessCallouts emits div[data-type=callout][data-callout-type=<type>]; the
+// schema's Callout.type parseHTML pipes it through clampCalloutType. A known alias
+// (`tip`) maps to the editor's banner (`success`); a genuinely unknown type
+// (`banana`) clamps to the 'info' default. End-to-end import-side resolution.
+// ---------------------------------------------------------------------------
+describe('import: non-schema callout fence resolves via alias map / clamps to info', () => {
+  it("imports ':::tip' as a callout whose attrs.type === 'success' (alias)", async () => {
+    const doc = await markdownToProseMirror(':::tip\nhello\n:::');
+    const callouts = findAll(doc, 'callout');
+    expect(callouts).toHaveLength(1);
+    expect(callouts[0].attrs.type).toBe('success');
+    // The body paragraph survived inside the callout.
+    expect(allText(callouts[0])).toContain('hello');
+    const paras = findAll(callouts[0], 'paragraph');
+    expect(paras.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("imports ':::banana' (unknown) as a callout whose attrs.type === 'info'", async () => {
+    const doc = await markdownToProseMirror(':::banana\nhello\n:::');
+    const callouts = findAll(doc, 'callout');
+    expect(callouts).toHaveLength(1);
+    expect(callouts[0].attrs.type).toBe('info');
+    expect(allText(callouts[0])).toContain('hello');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 3. Importing a columns layout with a string data-width yields a numeric
+// column width, and the columns wrapper carries its default layout/widthMode.
+// ---------------------------------------------------------------------------
+describe('import: columns layout with string data-width -> numeric width', () => {
+  it('parses data-width="33.5" to the number 33.5 and populates columns defaults', async () => {
+    const doc = await markdownToProseMirror(
+      '<div data-type="columns"><div data-type="column" data-width="33.5"><p>a</p></div></div>',
+    );
+    const columns = findAll(doc, 'columns');
+    expect(columns).toHaveLength(1);
+    // Columns default attrs are populated (not undefined).
+    expect(columns[0].attrs.widthMode).toBe('normal');
+    expect(columns[0].attrs.layout).not.toBeNull();
+    expect(columns[0].attrs.layout).toBe('two_equal');
+
+    const cols = findAll(columns[0], 'column');
+    expect(cols).toHaveLength(1);
+    // parseFloat('33.5') -> 33.5 as a NUMBER, not the string '33.5'.
+    expect(cols[0].attrs.width).toBe(33.5);
+    expect(typeof cols[0].attrs.width).toBe('number');
+    expect(allText(cols[0])).toContain('a');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 4. Comment mark resolved-attribute boolean coercion on import.
+//
+// The comment mark's resolved attr parseHTML compares
+// el.getAttribute('data-resolved') === 'true', so a missing attribute yields
+// false (default) and the literal 'true' yields boolean true.
+// ---------------------------------------------------------------------------
+describe('import: comment mark commentId + resolved boolean coercion', () => {
+  it("data-resolved='true' -> resolved:true with the parsed commentId", async () => {
+    const doc = await markdownToProseMirror(
+      '<span data-comment-id="c1" data-resolved="true">x</span>',
+    );
+    const mark = firstMark(doc, 'comment');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.commentId).toBe('c1');
+    expect(mark.attrs.resolved).toBe(true);
+  });
+
+  it('a missing data-resolved -> resolved:false (default)', async () => {
+    const doc = await markdownToProseMirror(
+      '<span data-comment-id="c2">y</span>',
+    );
+    const mark = firstMark(doc, 'comment');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.commentId).toBe('c2');
+    expect(mark.attrs.resolved).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 5. A NON-numeric truthy data-width reaches parseFloat and yields NaN.
+//
+// Column.width parseHTML is `value ? parseFloat(value) : null`; 'abc' is truthy
+// so parseFloat('abc') -> NaN leaks through as the raw attribute value rather
+// than falling back to the null default. (JSON.stringify would serialize NaN to
+// null — see the assertion below — so the leak is invisible in serialized JSON.)
+// ---------------------------------------------------------------------------
+describe('import: malformed non-numeric data-width leaks NaN', () => {
+  it("data-width='abc' -> column width is NaN (typeof number), not null", async () => {
+    const doc = await markdownToProseMirror(
+      '<div data-type="columns"><div data-type="column" data-width="abc"><p>x</p></div></div>',
+    );
+    const width = doc.content[0].content[0].attrs.width;
+    expect(typeof width).toBe('number');
+    expect(Number.isNaN(width)).toBe(true);
+    // Document that the leak is masked by JSON serialization: NaN -> null.
+    expect(JSON.parse(JSON.stringify(doc)).content[0].content[0].attrs.width).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 6. A column with NO data-width attribute lands on the null default.
+//
+// The else branch of `value ? parseFloat(value) : null` (getAttribute -> null)
+// must yield exactly null (not NaN/undefined), and the columns wrapper carries
+// its layout/widthMode defaults.
+// ---------------------------------------------------------------------------
+describe('import: width-less column lands on null default', () => {
+  it('no data-width -> column width === null, columns defaults populated', async () => {
+    const doc = await markdownToProseMirror(
+      '<div data-type="columns"><div data-type="column"><p>y</p></div></div>',
+    );
+    expect(doc.content[0].content[0].attrs.width).toBe(null);
+    expect(doc.content[0].attrs.layout).toBe('two_equal');
+    expect(doc.content[0].attrs.widthMode).toBe('normal');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 7. A structural callout div with missing/empty data-callout-type clamps
+// to 'info' via clampCalloutType (the parseHTML getAttrs fallback), with no icon.
+// ---------------------------------------------------------------------------
+describe('import: callout div with missing/empty data-callout-type clamps to info', () => {
+  it('a callout div with NO data-callout-type -> type:info, icon:null', async () => {
+    const doc = await markdownToProseMirror(
+      '<div data-type="callout"><p>z</p></div>',
+    );
+    expect(doc.content[0].type).toBe('callout');
+    expect(doc.content[0].attrs.type).toBe('info');
+    expect(doc.content[0].attrs.icon).toBeNull();
+  });
+
+  it('a callout div with EMPTY data-callout-type -> type:info, icon:null', async () => {
+    const doc = await markdownToProseMirror(
+      '<div data-type="callout" data-callout-type=""><p>w</p></div>',
+    );
+    expect(doc.content[0].type).toBe('callout');
+    expect(doc.content[0].attrs.type).toBe('info');
+    expect(doc.content[0].attrs.icon).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 8. A plain <td> with no align/colspan/rowspan/colwidth lands on the
+// schema defaults (align null via the `||` fallback arm; spans default to 1).
+// ---------------------------------------------------------------------------
+describe('import: span/align-less table cell lands on defaults', () => {
+  it('a bare td -> align:null, colspan:1, rowspan:1, colwidth:null', async () => {
+    const doc = await markdownToProseMirror(
+      '<table><tbody><tr><td><p>c</p></td></tr></tbody></table>',
+    );
+    const cells = findAll(doc, 'tableCell');
+    expect(cells).toHaveLength(1);
+    const attrs = cells[0].attrs;
+    expect(attrs.align).toBeNull();
+    expect(attrs.colspan).toBe(1);
+    expect(attrs.rowspan).toBe(1);
+    expect(attrs.colwidth).toBeNull();
+    expect(allText(cells[0])).toContain('c');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 9. underline/subscript/superscript marks survive import and re-export.
+// (inlineToHtml src 611-619 renders them back to <u>/<sub>/<sup>.)
+// ---------------------------------------------------------------------------
+describe('import+export: underline/subscript/superscript marks round-trip', () => {
+  it('<u>/<sub>/<sup> import to the right marks and re-export unchanged', async () => {
+    const doc = await markdownToProseMirror('<p><u>a</u><sub>b</sub><sup>c</sup></p>');
+    const para = findAll(doc, 'paragraph')[0];
+    const texts = (para.content || []).filter((n: any) => n.type === 'text');
+    expect(texts).toHaveLength(3);
+    expect(texts[0].text).toBe('a');
+    expect((texts[0].marks || []).map((m: any) => m.type)).toEqual(['underline']);
+    expect(texts[1].text).toBe('b');
+    expect((texts[1].marks || []).map((m: any) => m.type)).toEqual(['subscript']);
+    expect(texts[2].text).toBe('c');
+    expect((texts[2].marks || []).map((m: any) => m.type)).toEqual(['superscript']);
+
+    const md = convertProseMirrorToMarkdown(doc);
+    expect(md).toContain('<u>a</u>');
+    expect(md).toContain('<sub>b</sub>');
+    expect(md).toContain('<sup>c</sup>');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 10. Heading level attribute fidelity (h1/h2/h6) on import and re-export.
+// ---------------------------------------------------------------------------
+describe('import+export: heading levels 1/2/6 round-trip', () => {
+  it('parses # / ## / ###### to level 1/2/6 and re-emits them', async () => {
+    const doc = await markdownToProseMirror('# H1\n\n## H2\n\n###### H6');
+    const headings = findAll(doc, 'heading');
+    expect(headings).toHaveLength(3);
+    expect(headings[0].attrs.level).toBe(1);
+    expect(headings[1].attrs.level).toBe(2);
+    expect(headings[2].attrs.level).toBe(6);
+
+    const md = convertProseMirrorToMarkdown(doc);
+    const blocks = md.split('\n\n');
+    expect(blocks).toContain('# H1');
+    expect(blocks).toContain('## H2');
+    expect(blocks).toContain('###### H6');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Spec 11. Link mark recovers BOTH href and title on import and round-trips.
+// ---------------------------------------------------------------------------
+describe('import+export: link mark href + title round-trip', () => {
+  it('parses [lbl](http://a "the title") with href+title and re-emits it', async () => {
+    const doc = await markdownToProseMirror('[lbl](http://a "the title")');
+    const mark = firstMark(doc, 'link');
+    expect(mark).not.toBeNull();
+    expect(mark.attrs.href).toBe('http://a');
+    expect(mark.attrs.title).toBe('the title');
+    expect(allText(doc)).toContain('lbl');
+
+    const md = convertProseMirrorToMarkdown(doc);
+    expect(md).toContain('[lbl](http://a "the title")');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/media-roundtrip.test.ts b/packages/prosemirror-markdown/test/media-roundtrip.test.ts
new file mode 100644
index 00000000..cc687704
--- /dev/null
+++ b/packages/prosemirror-markdown/test/media-roundtrip.test.ts
@@ -0,0 +1,275 @@
+import { describe, expect, it } from 'vitest';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+  docsCanonicallyEqual,
+} from 'docmost-client';
+
+// ---------------------------------------------------------------------------
+// Media / atom node round-trip coverage (audio, video, pdf, attachment, embed,
+// youtube). The existing specs (corpus + property test) exercise the EXPORT
+// direction of these nodes only; their parseHTML branches (the INVERSE parse of
+// the exported HTML) are otherwise unprotected. Each test runs the full
+// export -> import -> export pipeline and pins:
+//   - the exact md1 byte string the converter emits,
+//   - whether md2 is byte-stable (md2 === md1) or grows by a materialized
+//     schema default on the first import,
+//   - the re-parsed doc2 attrs (NOTE: parseHTML reads via getAttribute and so
+//     returns STRINGS for numeric attrs, which is what breaks naive canonical
+//     equality), and
+//   - docsCanonicallyEqual(doc, doc2) where the spec asserts a specific result.
+//
+// `convertProseMirrorToMarkdown` requires a full doc ({type:'doc', content:[]}),
+// so each spec's `doc=[...]` content array is wrapped via mkDoc().
+// ---------------------------------------------------------------------------
+
+/** Wrap a content array (as the specs express `doc`) into a real PM doc. */
+const mkDoc = (content: any[]) => ({ type: 'doc', content });
+
+/** export -> import -> export, returning both markdowns and the re-parsed doc. */
+async function roundTrip(doc: any) {
+  const md1 = convertProseMirrorToMarkdown(doc);
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, md2, doc2 };
+}
+
+/** Find the first node of a given type anywhere in a PM doc tree. */
+const findFirst = (node: any, type: string): any => {
+  if (node && node.type === type) return node;
+  for (const child of node?.content || []) {
+    const hit = findFirst(child, type);
+    if (hit) return hit;
+  }
+  return null;
+};
+
+describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', () => {
+  // 1. audio with ALL optional attrs ---------------------------------------
+  it('audio with src+attachmentId+size: byte-stable, size re-parses to the STRING "9001"', async () => {
+    const doc = mkDoc([
+      { type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7', size: 9001 } },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
+    );
+    // Byte-stable: a second export reproduces the first exactly.
+    expect(md2).toBe(md1);
+
+    const audio = findFirst(doc2, 'audio');
+    expect(audio).not.toBeNull();
+    expect(audio.type).toBe('audio');
+    expect(audio.attrs.src).toBe('/a.mp3');
+    expect(audio.attrs.attachmentId).toBe('att-7');
+    // NOTE: the schema's data-size parseHTML returns getAttribute() -> a STRING,
+    // so the number 9001 comes back as the string '9001'.
+    expect(audio.attrs.size).toBe('9001');
+  });
+
+  // 2. fully-populated video -----------------------------------------------
+  it('video with all attrs: byte-stable; numeric attrs re-parse to STRINGS; canonical equality FALSE', async () => {
+    const doc = mkDoc([
+      {
+        type: 'video',
+        attrs: {
+          src: '/v.mp4',
+          alt: 'clip',
+          attachmentId: 'att-1',
+          width: 640,
+          height: 480,
+          size: 1234,
+          align: 'center',
+          aspectRatio: 1.777,
+        },
+      },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
+    );
+    expect(md2).toBe(md1);
+
+    const video = findFirst(doc2, 'video');
+    expect(video).not.toBeNull();
+    expect(video.attrs.alt).toBe('clip');
+    // All numeric attrs come back as STRINGS via getAttribute().
+    expect(video.attrs.width).toBe('640');
+    expect(video.attrs.height).toBe('480');
+    expect(video.attrs.size).toBe('1234');
+    expect(video.attrs.aspectRatio).toBe('1.777');
+
+    // Byte-stable export but NOT canonically equal: the numeric width/height/
+    // size/aspectRatio came back as strings, so deep-equal of the canonical
+    // forms fails (align:'center' is normalized away, the numbers are not).
+    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
+  });
+
+  // 3. minimal video (only src) --------------------------------------------
+  it('minimal video (src only): NOT byte-stable (gains data-align="center") but canonically equal', async () => {
+    const doc = mkDoc([{ type: 'video', attrs: { src: '/v.mp4' } }]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe('<div><video src="/v.mp4"></video></div>');
+    // video.align has a non-null schema default 'center' that materializes on
+    // import; the converter only emits data-align when set, so export #2 grows
+    // by data-align="center" exactly once (the documented one-time asymmetry).
+    expect(md2).toBe('<div><video src="/v.mp4" data-align="center"></video></div>');
+    expect(md2).not.toBe(md1);
+
+    // align:'center' is normalized away via KNOWN_DEFAULTS.video, so despite the
+    // byte growth the documents ARE canonically equal.
+    expect(docsCanonicallyEqual(doc, doc2)).toBe(true);
+  });
+
+  // 4. pdf with no numeric attrs (positive control) -------------------------
+  it('pdf with src+name+attachmentId (no numerics): byte- AND canonically-stable', async () => {
+    const doc = mkDoc([
+      { type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf', attachmentId: 'att-9' } },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9"></div>',
+    );
+    expect(md2).toBe(md1);
+
+    const pdf = findFirst(doc2, 'pdf');
+    expect(pdf).not.toBeNull();
+    expect(pdf.attrs.src).toBe('/d.pdf');
+    expect(pdf.attrs.name).toBe('d.pdf');
+    expect(pdf.attrs.attachmentId).toBe('att-9');
+
+    // No numeric attrs to coerce to strings, so the round-trip is BOTH byte- and
+    // canonically-stable (the positive control vs. the numeric-divergence cases).
+    expect(docsCanonicallyEqual(doc, doc2)).toBe(true);
+  });
+
+  // 5. attachment with numeric size ----------------------------------------
+  it('attachment with url+name+mime+size+attachmentId: byte-stable; size STRING; canonical FALSE', async () => {
+    const doc = mkDoc([
+      {
+        type: 'attachment',
+        attrs: {
+          url: '/f.zip',
+          name: 'f.zip',
+          mime: 'application/zip',
+          size: 512,
+          attachmentId: 'att-3',
+        },
+      },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
+    );
+    expect(md2).toBe(md1);
+
+    const att = findFirst(doc2, 'attachment');
+    expect(att).not.toBeNull();
+    expect(att.attrs.url).toBe('/f.zip');
+    expect(att.attrs.name).toBe('f.zip');
+    expect(att.attrs.mime).toBe('application/zip');
+    expect(att.attrs.attachmentId).toBe('att-3');
+    // data-attachment-size parseHTML -> getAttribute() -> STRING.
+    expect(att.attrs.size).toBe('512');
+
+    // The numeric size coerced to a string breaks canonical equality.
+    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
+  });
+
+  // 6. embed WITH explicit width/height/align (byte-stable) ----------------
+  it('embed with explicit src+provider+align+width+height: byte-stable; width/height STRINGS', async () => {
+    const doc = mkDoc([
+      {
+        type: 'embed',
+        attrs: {
+          src: 'https://x.com/e',
+          provider: 'iframe',
+          align: 'left',
+          width: 600,
+          height: 400,
+        },
+      },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
+    );
+    expect(md2).toBe(md1);
+
+    const embed = findFirst(doc2, 'embed');
+    expect(embed).not.toBeNull();
+    expect(embed.attrs.src).toBe('https://x.com/e');
+    expect(embed.attrs.provider).toBe('iframe');
+    expect(embed.attrs.align).toBe('left');
+    // data-width / data-height parseHTML -> getAttribute() -> STRINGS.
+    expect(embed.attrs.width).toBe('600');
+    expect(embed.attrs.height).toBe('400');
+  });
+
+  // 7. minimal embed (only src+provider) -----------------------------------
+  it('minimal embed (src+provider): NOT byte-stable; defaults width/height materialize as NUMBERS 800/600', async () => {
+    const doc = mkDoc([
+      { type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
+    );
+    // embed has non-null schema defaults align='center', width=800, height=600
+    // that the converter never emits on export #1 but materialize on import, so
+    // export #2 grows by three data-* attrs (a one-time divergence).
+    expect(md2).toBe(
+      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="center" data-width="800" data-height="600"></div>',
+    );
+    expect(md2).not.toBe(md1);
+
+    const embed = findFirst(doc2, 'embed');
+    expect(embed).not.toBeNull();
+    expect(embed.attrs.align).toBe('center');
+    // NOTE: these come from the addAttributes default (NOT parseHTML), so on the
+    // FIRST import they are the NUMBERS 800/600, not strings — parseHTML only
+    // runs when the attribute is actually present on the imported element.
+    expect(embed.attrs.width).toBe(800);
+    expect(embed.attrs.height).toBe(600);
+  });
+
+  // 8. youtube with src+width+height+align ---------------------------------
+  it('youtube with src+width+height+align(right): byte-stable; width/height STRINGS; canonical FALSE', async () => {
+    const doc = mkDoc([
+      {
+        type: 'youtube',
+        attrs: {
+          src: 'https://youtu.be/abc',
+          width: 560,
+          height: 315,
+          align: 'right',
+        },
+      },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+
+    expect(md1).toBe(
+      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
+    );
+    expect(md2).toBe(md1);
+
+    const yt = findFirst(doc2, 'youtube');
+    expect(yt).not.toBeNull();
+    expect(yt.attrs.src).toBe('https://youtu.be/abc');
+    expect(yt.attrs.align).toBe('right');
+    // data-width / data-height parseHTML -> getAttribute() -> STRINGS.
+    expect(yt.attrs.width).toBe('560');
+    expect(yt.attrs.height).toBe('315');
+
+    // Numeric width/height coerced to strings; align='right' is non-default so
+    // it is kept (not in KNOWN_DEFAULTS.youtube's normalization). Canonical FALSE.
+    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/node-ops-extra.test.ts b/packages/prosemirror-markdown/test/node-ops-extra.test.ts
new file mode 100644
index 00000000..fbdb058a
--- /dev/null
+++ b/packages/prosemirror-markdown/test/node-ops-extra.test.ts
@@ -0,0 +1,268 @@
+import { describe, expect, it } from 'vitest';
+import fc from 'fast-check';
+import {
+  getNodeByRef,
+  replaceNodeById,
+  insertNodeRelative,
+  insertTableRow,
+  updateTableCell,
+  sanitizeForYjs,
+  findUnstorableAttr,
+  buildOutline,
+} from '../src/lib/node-ops.js';
+
+// Gaps NOT covered by node-ops.test.ts (test-strategy report §2). The base file
+// is comprehensive; these add only the missing edges: newNode-arg immutability,
+// anchor-is-container routing, malformed opts, ragged/empty/no-colwidth/non-int
+// insertTableRow, getNodeByRef non-object/#-1, updateTableCell empty-id refresh,
+// outline 100/40 boundary, malformed marks, and the makeFreshId property.
+
+const text = (value: string, marks?: any[]): any => {
+  const node: any = { type: 'text', text: value };
+  if (marks) node.marks = marks;
+  return node;
+};
+const para = (id: string, value = ''): any => ({
+  type: 'paragraph',
+  attrs: { id, indent: 0 },
+  content: value ? [text(value)] : [],
+});
+const cell = (
+  type: 'tableCell' | 'tableHeader',
+  paraId: string | null,
+  value = '',
+  extraAttrs: Record<string, any> = {},
+): any => ({
+  type,
+  attrs: { colspan: 1, rowspan: 1, ...extraAttrs },
+  content: paraId == null ? [] : [para(paraId, value)],
+});
+const row = (cells: any[]): any => ({ type: 'tableRow', content: cells });
+const doc = (...content: any[]): any => ({ type: 'doc', content });
+
+// ===========================================================================
+describe('replaceNodeById — newNode ARGUMENT immutability', () => {
+  it('does not mutate the caller-supplied newNode after replacement', () => {
+    // The doc-argument immutability is covered in the base file; this pins the
+    // OTHER input — the replacement node must be deep-cloned, so mutating the
+    // result never reaches the caller's newNode (and vice versa).
+    const d = doc(para('p0', 'old'), para('p1', 'old2'));
+    const newNode = { type: 'paragraph', attrs: { id: 'new' }, content: [text('NEW')] };
+    const snapshot = structuredClone(newNode);
+    const res = replaceNodeById(d, 'p0', newNode);
+    // Mutating the inserted copy must not touch the argument...
+    res.doc.content[0].content.push(text('mutated'));
+    expect(newNode).toEqual(snapshot);
+    // ...and mutating the argument afterwards must not touch the inserted copy.
+    newNode.content.push(text('later'));
+    expect(res.doc.content[0].content).toEqual([text('NEW'), text('mutated')]);
+  });
+});
+
+// ===========================================================================
+describe('insertNodeRelative — container routing and malformed opts', () => {
+  it('routes a structural row when anchorText resolves to the TABLE block itself', () => {
+    // anchorText only scans top-level blocks, so it resolves to the whole table;
+    // the matched container IS the anchor (containerIdx === chain.length-1), so
+    // a row "after" must be appended inside the table, not spliced beside a row.
+    const table = { type: 'table', content: [row([cell('tableCell', 'r0', 'hello cell')])] };
+    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
+    const res = insertNodeRelative(doc(table), newRow, {
+      position: 'after',
+      anchorText: 'hello cell',
+    });
+    expect(res.inserted).toBe(true);
+    const firstCellId = (r: any) => r.content[0].content[0].attrs.id;
+    expect(res.doc.content[0].content.map(firstCellId)).toEqual(['r0', 'rNew']);
+  });
+
+  it('prepends a structural row when anchorText resolves to the table and position is "before"', () => {
+    const table = { type: 'table', content: [row([cell('tableCell', 'r0', 'hello cell')])] };
+    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
+    const res = insertNodeRelative(doc(table), newRow, {
+      position: 'before',
+      anchorText: 'hello cell',
+    });
+    const firstCellId = (r: any) => r.content[0].content[0].attrs.id;
+    expect(res.doc.content[0].content.map(firstCellId)).toEqual(['rNew', 'r0']);
+  });
+
+  it('is a no-op (inserted:false) for a malformed opts object', () => {
+    const d = doc(para('p0'));
+    const res = insertNodeRelative(d, para('n'), null as any);
+    expect(res.inserted).toBe(false);
+    expect(res.doc).toEqual(d);
+  });
+});
+
+// ===========================================================================
+describe('insertTableRow — column count and index edge cases', () => {
+  const ragged = () => ({
+    type: 'table',
+    content: [
+      row([cell('tableHeader', 'h0', 'H0')]), // 1 col
+      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]), // 2 cols
+    ],
+  });
+
+  it('derives the column count from the WIDEST row (ragged table)', () => {
+    // The guard counts against the widest row (2), so 3 cells throws...
+    expect(() => insertTableRow(doc(ragged()), '#0', ['X', 'Y', 'Z'])).toThrow(
+      /got 3 cell\(s\) but the table has 2 column\(s\)/,
+    );
+    // ...and a 2-cell row is padded to the widest width (2), not the header's 1.
+    const res = insertTableRow(doc(ragged()), '#0', ['X', 'Y']);
+    expect(res.doc.content[0].content[2].content).toHaveLength(2);
+  });
+
+  it('an EMPTY table falls back to the supplied cell count', () => {
+    const res = insertTableRow(doc({ type: 'table', content: [] }), '#0', ['A', 'B']);
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content[0].content[0].content).toHaveLength(2);
+  });
+
+  it('omits colwidth entirely when the header cell has none (no undefined leak)', () => {
+    const noColwidth = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'h0', 'H')]),
+        row([cell('tableCell', 'c0', 'A')]),
+      ],
+    };
+    const res = insertTableRow(doc(noColwidth), '#0', ['X']);
+    const newCellAttrs = res.doc.content[0].content[2].content[0].attrs;
+    expect('colwidth' in newCellAttrs).toBe(false); // not colwidth:undefined
+  });
+
+  it('APPENDS for a non-integer or negative index (does not throw)', () => {
+    const t = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'h0', 'H')]),
+        row([cell('tableCell', 'c0', 'A')]),
+      ],
+    };
+    const frac = insertTableRow(doc(t), '#0', ['X'], 1.5);
+    expect(frac.inserted).toBe(true);
+    expect(frac.doc.content[0].content).toHaveLength(3); // appended at the end
+    const neg = insertTableRow(doc(t), '#0', ['X'], -1);
+    expect(neg.doc.content[0].content).toHaveLength(3);
+  });
+});
+
+// ===========================================================================
+describe('getNodeByRef — malformed refs', () => {
+  it('returns null for a non-object block at a valid #n index', () => {
+    const d = { type: 'doc', content: [null] };
+    expect(getNodeByRef(d, '#0')).toBeNull();
+  });
+
+  it('returns null for "#-1" (the index regex does not match a negative)', () => {
+    const d = doc(para('p0'));
+    // "#-1" matches neither the "#<digits>" form nor any block id -> null.
+    expect(getNodeByRef(d, '#-1')).toBeNull();
+  });
+});
+
+// ===========================================================================
+describe('updateTableCell — fresh id when the first paragraph has an empty id', () => {
+  it('mints a fresh id when the existing first paragraph id is the empty string', () => {
+    const table = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'h0', 'H')]),
+        row([
+          {
+            type: 'tableCell',
+            attrs: { colspan: 1, rowspan: 1 },
+            content: [{ type: 'paragraph', attrs: { id: '' }, content: [text('old')] }],
+          },
+        ]),
+      ],
+    };
+    const res = updateTableCell(doc(table), '#0', 1, 0, 'new');
+    const newId = res.doc.content[0].content[1].content[0].content[0].attrs.id;
+    // An empty id is treated as missing -> a fresh Docmost-style id is minted.
+    expect(newId).toMatch(/^[a-z0-9]{12}$/);
+    expect(newId).not.toBe('');
+  });
+});
+
+// ===========================================================================
+describe('buildOutline — exact 100 / 40 char truncation boundaries', () => {
+  it('does NOT truncate firstText at exactly 100 chars but DOES at 101', () => {
+    const at100 = buildOutline(doc(para('p', 'x'.repeat(100))));
+    expect(at100[0].firstText).toBe('x'.repeat(100)); // boundary: not cut
+    expect(at100[0].firstText.endsWith('…')).toBe(false);
+    const at101 = buildOutline(doc(para('p', 'x'.repeat(101))));
+    expect(at101[0].firstText).toBe('x'.repeat(100) + '…'); // first char over the cap
+  });
+
+  it('does NOT truncate a header cell at exactly 40 chars but DOES at 41', () => {
+    const tableAt40 = {
+      type: 'table',
+      content: [row([cell('tableHeader', 'h', 'y'.repeat(40))])],
+    };
+    expect(buildOutline(doc(tableAt40))[0].header).toEqual(['y'.repeat(40)]);
+    const tableAt41 = {
+      type: 'table',
+      content: [row([cell('tableHeader', 'h', 'y'.repeat(41))])],
+    };
+    expect(buildOutline(doc(tableAt41))[0].header).toEqual(['y'.repeat(40) + '…']);
+  });
+});
+
+// ===========================================================================
+describe('sanitizeForYjs / findUnstorableAttr — malformed marks array', () => {
+  const malformed = () =>
+    doc({
+      type: 'paragraph',
+      attrs: { id: 'p' },
+      content: [
+        text('x', [null, { type: 'link', attrs: { href: 'u', gone: undefined } }]),
+      ],
+    });
+
+  it('sanitizeForYjs skips a null mark and strips undefined on the real one', () => {
+    const res = sanitizeForYjs(malformed());
+    const marks = res.content[0].content[0].marks;
+    expect(marks[0]).toBeNull(); // the null mark is left untouched, not crashed on
+    expect(marks[1].attrs).toEqual({ href: 'u' }); // undefined dropped
+  });
+
+  it('findUnstorableAttr skips a null mark and reports the real undefined attr path', () => {
+    expect(findUnstorableAttr(malformed())).toBe(
+      'content[0].content[0].marks[1].attrs.gone (undefined)',
+    );
+  });
+});
+
+// ===========================================================================
+describe('makeFreshId — format and uniqueness (property, via insertTableRow)', () => {
+  it('every minted cell-paragraph id matches ^[a-z0-9]{12}$ and is globally unique', () => {
+    fc.assert(
+      fc.property(fc.integer({ min: 1, max: 5 }), (cols) => {
+        // Build an empty-id table of `cols` columns; the inserted row mints a
+        // fresh id per cell. The doc carries one pre-existing id to also assert
+        // the new ids never collide with it.
+        const headerCells = Array.from({ length: cols }, (_, i) =>
+          cell('tableHeader', `pre-${i}`, `H${i}`),
+        );
+        const d = doc({ type: 'table', content: [row(headerCells)] });
+        const res = insertTableRow(d, '#0', Array.from({ length: cols }, () => 'v'), 1);
+        const ids = res.doc.content[0].content[1].content.map(
+          (c: any) => c.content[0].attrs.id,
+        );
+        for (const id of ids) {
+          expect(id).toMatch(/^[a-z0-9]{12}$/);
+        }
+        // Unique within the new row AND distinct from the pre-existing ids.
+        expect(new Set(ids).size).toBe(ids.length);
+        for (const id of ids) {
+          expect(id.startsWith('pre-')).toBe(false);
+        }
+      }),
+      { numRuns: 100 },
+    );
+  });
+});
diff --git a/packages/prosemirror-markdown/test/node-ops.test.ts b/packages/prosemirror-markdown/test/node-ops.test.ts
new file mode 100644
index 00000000..52d302f1
--- /dev/null
+++ b/packages/prosemirror-markdown/test/node-ops.test.ts
@@ -0,0 +1,908 @@
+import { describe, expect, it } from 'vitest';
+import {
+  blockPlainText,
+  buildOutline,
+  getNodeByRef,
+  replaceNodeById,
+  deleteNodeById,
+  sanitizeForYjs,
+  findUnstorableAttr,
+  insertNodeRelative,
+  readTable,
+  insertTableRow,
+  deleteTableRow,
+  updateTableCell,
+} from '../src/lib/node-ops.js';
+
+// ---------------------------------------------------------------------------
+// Tiny ProseMirror/TipTap JSON fixture builders. These produce the exact plain
+// JSON shape Docmost uses: { type, attrs?, content?, text?, marks? }.
+// ---------------------------------------------------------------------------
+
+/** A text leaf node, optionally carrying marks. */
+function text(value: string, marks?: any[]): any {
+  const node: any = { type: 'text', text: value };
+  if (marks) node.marks = marks;
+  return node;
+}
+
+/** A paragraph block with an id and a single text child (or empty). */
+function para(id: string, value = ''): any {
+  return {
+    type: 'paragraph',
+    attrs: { id, indent: 0 },
+    content: value ? [text(value)] : [],
+  };
+}
+
+/** A heading block. */
+function heading(id: string, level: number, value: string): any {
+  return {
+    type: 'heading',
+    attrs: { id, level },
+    content: [text(value)],
+  };
+}
+
+/** A table cell (or header) wrapping a single paragraph; extra attrs merged in. */
+function cell(
+  type: 'tableCell' | 'tableHeader',
+  paraId: string | null,
+  value = '',
+  extraAttrs: Record<string, any> = {},
+): any {
+  const attrs = { colspan: 1, rowspan: 1, ...extraAttrs };
+  return {
+    type,
+    attrs,
+    content: paraId == null ? [] : [para(paraId, value)],
+  };
+}
+
+/** A table row. */
+function row(cells: any[]): any {
+  return { type: 'tableRow', content: cells };
+}
+
+/** A doc root with the given top-level blocks. */
+function doc(...content: any[]): any {
+  return { type: 'doc', content };
+}
+
+// ===========================================================================
+// blockPlainText
+// ===========================================================================
+describe('blockPlainText', () => {
+  it('returns the text of a plain text node', () => {
+    expect(blockPlainText(text('hello'))).toBe('hello');
+  });
+
+  it('concatenates text from nested containers', () => {
+    const node = {
+      type: 'paragraph',
+      content: [text('foo'), text('bar'), { type: 'span', content: [text('baz')] }],
+    };
+    expect(blockPlainText(node)).toBe('foobarbaz');
+  });
+
+  it('returns "" for nullish or non-object inputs', () => {
+    expect(blockPlainText(null)).toBe('');
+    expect(blockPlainText(undefined)).toBe('');
+    expect(blockPlainText('a string')).toBe('');
+    expect(blockPlainText(42)).toBe('');
+    expect(blockPlainText([text('x')])).toBe(''); // arrays are not objects here
+  });
+
+  it('uses BOTH text and nested content of a node, text first', () => {
+    const node = { type: 'weird', text: 'A', content: [text('B'), text('C')] };
+    expect(blockPlainText(node)).toBe('ABC');
+  });
+});
+
+// ===========================================================================
+// buildOutline
+// ===========================================================================
+describe('buildOutline', () => {
+  it('captures heading level, id and firstText', () => {
+    const outline = buildOutline(doc(heading('h1', 2, 'Title')));
+    expect(outline).toEqual([
+      { index: 0, type: 'heading', id: 'h1', firstText: 'Title', level: 2 },
+    ]);
+  });
+
+  it('reports table rows/cols and header texts (cols from row 0)', () => {
+    const table = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'a', 'H1'), cell('tableHeader', 'b', 'H2')]),
+        row([cell('tableCell', 'c', 'x'), cell('tableCell', 'd', 'y')]),
+      ],
+    };
+    const [entry] = buildOutline(doc(table));
+    expect(entry.type).toBe('table');
+    expect(entry.rows).toBe(2);
+    expect(entry.cols).toBe(2);
+    expect(entry.header).toEqual(['H1', 'H2']);
+  });
+
+  it('derives cols from row 0 for a ragged table', () => {
+    const table = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'a', 'H1')]), // row 0 has 1 col
+        row([cell('tableCell', 'b', 'x'), cell('tableCell', 'c', 'y')]), // 2 cols
+      ],
+    };
+    const [entry] = buildOutline(doc(table));
+    expect(entry.rows).toBe(2);
+    expect(entry.cols).toBe(1); // cols reflect ONLY row 0
+    expect(entry.header).toEqual(['H1']);
+  });
+
+  it('reports item count for any *List block', () => {
+    const list = {
+      type: 'bulletList',
+      attrs: { id: 'l1' },
+      content: [{ type: 'listItem' }, { type: 'listItem' }, { type: 'listItem' }],
+    };
+    const [entry] = buildOutline(doc(list));
+    expect(entry.type).toBe('bulletList');
+    expect(entry.items).toBe(3);
+  });
+
+  it('returns [] for an empty or non-object doc', () => {
+    expect(buildOutline(null)).toEqual([]);
+    expect(buildOutline({ type: 'doc' })).toEqual([]); // no content array
+    expect(buildOutline({ type: 'doc', content: [] })).toEqual([]);
+    expect(buildOutline('nope')).toEqual([]);
+  });
+
+  it('falls back to null id when a block has no attrs.id', () => {
+    const [entry] = buildOutline(doc({ type: 'paragraph', content: [text('hi')] }));
+    expect(entry.id).toBeNull();
+    expect(entry.firstText).toBe('hi');
+  });
+
+  it('truncates firstText to 100 chars with an ellipsis', () => {
+    const long = 'x'.repeat(150);
+    const [entry] = buildOutline(doc(para('p', long)));
+    expect(entry.firstText).toBe('x'.repeat(100) + '…');
+    expect(entry.firstText.length).toBe(101); // 100 chars + ellipsis
+  });
+
+  it('truncates table header cell text to 40 chars', () => {
+    const long = 'y'.repeat(60);
+    const table = {
+      type: 'table',
+      content: [row([cell('tableHeader', 'a', long)])],
+    };
+    const [entry] = buildOutline(doc(table));
+    expect(entry.header).toEqual(['y'.repeat(40) + '…']);
+  });
+});
+
+// ===========================================================================
+// getNodeByRef
+// ===========================================================================
+describe('getNodeByRef', () => {
+  it('resolves a top-level block by #n', () => {
+    const d = doc(para('p0', 'zero'), para('p1', 'one'));
+    const hit = getNodeByRef(d, '#1');
+    expect(hit).not.toBeNull();
+    expect(hit!.path).toEqual([1]);
+    expect(hit!.type).toBe('paragraph');
+    expect(hit!.node.attrs.id).toBe('p1');
+  });
+
+  it('returns null for #n out of range', () => {
+    const d = doc(para('p0'));
+    expect(getNodeByRef(d, '#5')).toBeNull();
+    expect(getNodeByRef(d, '#1')).toBeNull();
+  });
+
+  it('finds a nested node by id with the correct path', () => {
+    const table = {
+      type: 'table',
+      content: [row([cell('tableCell', 'deep', 'found me')])],
+    };
+    const d = doc(para('p0'), table);
+    const hit = getNodeByRef(d, 'deep');
+    expect(hit).not.toBeNull();
+    // doc.content[1] -> table.content[0] -> row.content[0] -> cell.content[0]
+    expect(hit!.path).toEqual([1, 0, 0, 0]);
+    expect(hit!.type).toBe('paragraph');
+  });
+
+  it('returns null when the id is not found', () => {
+    const d = doc(para('p0'));
+    expect(getNodeByRef(d, 'missing')).toBeNull();
+  });
+
+  it('returns the FIRST node for a duplicate id', () => {
+    const d = doc(para('dup', 'first'), para('dup', 'second'));
+    const hit = getNodeByRef(d, 'dup');
+    expect(hit!.path).toEqual([0]);
+    expect(blockPlainText(hit!.node)).toBe('first');
+  });
+
+  it('returns null for a non-object doc', () => {
+    expect(getNodeByRef(null, '#0')).toBeNull();
+    expect(getNodeByRef('x', 'id')).toBeNull();
+  });
+
+  it('returns a CLONE — mutating it does not touch the input doc', () => {
+    const d = doc(para('p0', 'orig'));
+    const snapshot = structuredClone(d);
+    const hit = getNodeByRef(d, 'p0');
+    hit!.node.attrs.id = 'mutated';
+    hit!.node.content.push(text('extra'));
+    expect(d).toEqual(snapshot);
+  });
+});
+
+// ===========================================================================
+// replaceNodeById
+// ===========================================================================
+describe('replaceNodeById', () => {
+  const newNode = () => ({ type: 'paragraph', attrs: { id: 'new' }, content: [text('NEW')] });
+
+  it('reports replaced:0 when nothing matches', () => {
+    const d = doc(para('p0'));
+    const res = replaceNodeById(d, 'missing', newNode());
+    expect(res.replaced).toBe(0);
+    expect(res.doc).toEqual(d);
+  });
+
+  it('replaces a single match', () => {
+    const d = doc(para('p0', 'old'), para('p1'));
+    const res = replaceNodeById(d, 'p0', newNode());
+    expect(res.replaced).toBe(1);
+    expect(res.doc.content[0]).toEqual(newNode());
+    expect(res.doc.content[1].attrs.id).toBe('p1');
+  });
+
+  it('replaces N matches', () => {
+    const d = doc(para('dup', 'a'), para('keep'), para('dup', 'b'));
+    const res = replaceNodeById(d, 'dup', newNode());
+    expect(res.replaced).toBe(2);
+    expect(res.doc.content[0]).toEqual(newNode());
+    expect(res.doc.content[1].attrs.id).toBe('keep');
+    expect(res.doc.content[2]).toEqual(newNode());
+  });
+
+  it('replaces a nested match inside a table cell', () => {
+    const table = {
+      type: 'table',
+      content: [row([cell('tableCell', 'inner', 'x')])],
+    };
+    const d = doc(table);
+    const res = replaceNodeById(d, 'inner', newNode());
+    expect(res.replaced).toBe(1);
+    expect(res.doc.content[0].content[0].content[0].content[0]).toEqual(newNode());
+  });
+
+  it('does NOT recurse into the substituted node', () => {
+    // The replacement itself carries the same id; it must not be re-replaced.
+    const d = doc(para('target'));
+    const replacement = { type: 'paragraph', attrs: { id: 'target' }, content: [text('R')] };
+    const res = replaceNodeById(d, 'target', replacement);
+    expect(res.replaced).toBe(1); // not 2 — no recursion into the new node
+  });
+
+  it('gives each match a SEPARATE clone', () => {
+    const d = doc(para('dup'), para('dup'));
+    const res = replaceNodeById(d, 'dup', newNode());
+    res.doc.content[0].content.push(text('mutated'));
+    // The second replacement must be untouched.
+    expect(res.doc.content[1]).toEqual(newNode());
+  });
+
+  it('does not mutate the input doc', () => {
+    const d = doc(para('p0', 'old'));
+    const snapshot = structuredClone(d);
+    replaceNodeById(d, 'p0', newNode());
+    expect(d).toEqual(snapshot);
+  });
+});
+
+// ===========================================================================
+// deleteNodeById
+// ===========================================================================
+describe('deleteNodeById', () => {
+  it('reports deleted:0 when nothing matches', () => {
+    const d = doc(para('p0'));
+    const res = deleteNodeById(d, 'missing');
+    expect(res.deleted).toBe(0);
+    expect(res.doc).toEqual(d);
+  });
+
+  it('deletes a single match', () => {
+    const d = doc(para('p0'), para('p1'), para('p2'));
+    const res = deleteNodeById(d, 'p1');
+    expect(res.deleted).toBe(1);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'p2']);
+  });
+
+  it('deletes N matches', () => {
+    const d = doc(para('dup'), para('keep'), para('dup'));
+    const res = deleteNodeById(d, 'dup');
+    expect(res.deleted).toBe(2);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['keep']);
+  });
+
+  it('deletes a nested node and preserves sibling order', () => {
+    // A callout-style container holding three paragraph children; deleting the
+    // middle one must leave the outer siblings in order.
+    const callout = {
+      type: 'callout',
+      attrs: { id: 'cal' },
+      content: [para('a', 'A'), para('b', 'B'), para('c', 'C')],
+    };
+    const d = doc(para('outer0'), callout, para('outer1'));
+    const res = deleteNodeById(d, 'b');
+    expect(res.deleted).toBe(1);
+    // Inner siblings keep their order.
+    const innerIds = res.doc.content[1].content.map((cl: any) => cl.attrs.id);
+    expect(innerIds).toEqual(['a', 'c']);
+    // Outer siblings are untouched and in order.
+    const outerIds = res.doc.content.map((cl: any) => cl.attrs.id);
+    expect(outerIds).toEqual(['outer0', 'cal', 'outer1']);
+  });
+
+  it('does not mutate the input doc (deep-equal before/after)', () => {
+    const d = doc(para('p0'), para('p1'));
+    const snapshot = structuredClone(d);
+    deleteNodeById(d, 'p0');
+    expect(d).toEqual(snapshot);
+  });
+});
+
+// ===========================================================================
+// sanitizeForYjs
+// ===========================================================================
+describe('sanitizeForYjs', () => {
+  it('strips undefined keys from node.attrs', () => {
+    const d = doc({ type: 'paragraph', attrs: { id: 'p', gone: undefined, kept: 1 } });
+    const res = sanitizeForYjs(d);
+    expect('gone' in res.content[0].attrs).toBe(false);
+    expect(res.content[0].attrs).toEqual({ id: 'p', kept: 1 });
+  });
+
+  it('strips undefined keys from mark.attrs', () => {
+    const d = doc({
+      type: 'paragraph',
+      attrs: { id: 'p' },
+      content: [text('hi', [{ type: 'link', attrs: { href: 'u', gone: undefined } }])],
+    });
+    const res = sanitizeForYjs(d);
+    expect('gone' in res.content[0].content[0].marks[0].attrs).toBe(false);
+    expect(res.content[0].content[0].marks[0].attrs).toEqual({ href: 'u' });
+  });
+
+  it('PRESERVES null, false, 0 and "" (only undefined is dropped)', () => {
+    const d = doc({
+      type: 'paragraph',
+      attrs: { a: null, b: false, c: 0, d: '', e: undefined },
+    });
+    const res = sanitizeForYjs(d);
+    expect(res.content[0].attrs).toEqual({ a: null, b: false, c: 0, d: '' });
+  });
+
+  it('recurses into nested content', () => {
+    const d = doc({
+      type: 'table',
+      content: [row([cell('tableCell', null, '', { gone: undefined, colwidth: null })])],
+    });
+    const res = sanitizeForYjs(d);
+    const cellAttrs = res.content[0].content[0].content[0].attrs;
+    expect('gone' in cellAttrs).toBe(false);
+    expect(cellAttrs.colwidth).toBeNull();
+  });
+
+  it('does not mutate the input doc', () => {
+    const d = doc({ type: 'paragraph', attrs: { id: 'p', gone: undefined } });
+    // structuredClone preserves an explicit `undefined` value key, so snapshot it.
+    const snapshot = structuredClone(d);
+    sanitizeForYjs(d);
+    expect(d).toEqual(snapshot);
+    expect('gone' in d.content[0].attrs).toBe(true); // still present on the input
+  });
+});
+
+// ===========================================================================
+// findUnstorableAttr
+// ===========================================================================
+describe('findUnstorableAttr', () => {
+  it('returns null for a fully storable doc', () => {
+    const d = doc(para('p0', 'clean'));
+    expect(findUnstorableAttr(d)).toBeNull();
+  });
+
+  it('detects an undefined node attr with its path and kind', () => {
+    const d = doc(para('a'), para('b'), { type: 'paragraph', attrs: { id: 'c', x: undefined } });
+    expect(findUnstorableAttr(d)).toBe('content[2].attrs.x (undefined)');
+  });
+
+  it('detects a function attr', () => {
+    const d = doc({ type: 'paragraph', attrs: { fn: () => 1 } });
+    expect(findUnstorableAttr(d)).toBe('content[0].attrs.fn (function)');
+  });
+
+  it('detects a symbol attr', () => {
+    const d = doc({ type: 'paragraph', attrs: { s: Symbol('x') } });
+    expect(findUnstorableAttr(d)).toBe('content[0].attrs.s (symbol)');
+  });
+
+  it('detects a bigint attr', () => {
+    const d = doc({ type: 'paragraph', attrs: { big: 10n } });
+    expect(findUnstorableAttr(d)).toBe('content[0].attrs.big (bigint)');
+  });
+
+  it('detects an unstorable mark attr with the marks[i] path', () => {
+    const d = doc({
+      type: 'paragraph',
+      attrs: { id: 'p' },
+      content: [text('hi'), text('yo', [{ type: 'link', attrs: { x: undefined } }])],
+    });
+    expect(findUnstorableAttr(d)).toBe('content[0].content[1].marks[0].attrs.x (undefined)');
+  });
+
+  it('returns the FIRST hit only', () => {
+    const d = doc(
+      { type: 'paragraph', attrs: { first: undefined } },
+      { type: 'paragraph', attrs: { second: undefined } },
+    );
+    expect(findUnstorableAttr(d)).toBe('content[0].attrs.first (undefined)');
+  });
+
+  it('returns null for a non-object doc', () => {
+    expect(findUnstorableAttr(null)).toBeNull();
+    expect(findUnstorableAttr('x')).toBeNull();
+  });
+});
+
+// ===========================================================================
+// insertNodeRelative
+// ===========================================================================
+describe('insertNodeRelative', () => {
+  const block = (id: string, value = '') => para(id, value);
+
+  it('appends a node to top-level content', () => {
+    const d = doc(para('p0'));
+    const res = insertNodeRelative(d, block('new', 'N'), { position: 'append' });
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new']);
+  });
+
+  it('creates a content array when appending to a doc without one', () => {
+    const res = insertNodeRelative({ type: 'doc' }, block('new'), { position: 'append' });
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['new']);
+  });
+
+  it('inserts before a node by id (top level)', () => {
+    const d = doc(para('p0'), para('p1'));
+    const res = insertNodeRelative(d, block('new'), { position: 'before', anchorNodeId: 'p1' });
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
+  });
+
+  it('inserts after a node by id (top level)', () => {
+    const d = doc(para('p0'), para('p1'));
+    const res = insertNodeRelative(d, block('new'), { position: 'after', anchorNodeId: 'p0' });
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
+  });
+
+  it('inserts before a NESTED anchor by id, into its own parent content', () => {
+    const table = {
+      type: 'table',
+      content: [row([cell('tableCell', 'inner', 'x')])],
+    };
+    const d = doc(table);
+    const res = insertNodeRelative(d, block('new'), { position: 'before', anchorNodeId: 'inner' });
+    expect(res.inserted).toBe(true);
+    // The new (non-structural) node is spliced into the cell's content before the paragraph.
+    const cellContent = res.doc.content[0].content[0].content[0].content;
+    expect(cellContent.map((c: any) => c.attrs.id)).toEqual(['new', 'inner']);
+  });
+
+  it('inserts by anchorText against top-level blocks (substring match)', () => {
+    const d = doc(para('p0', 'hello world'), para('p1', 'other'));
+    const res = insertNodeRelative(d, block('new'), { position: 'after', anchorText: 'world' });
+    expect(res.inserted).toBe(true);
+    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
+  });
+
+  it('returns inserted:false when the anchor cannot be resolved', () => {
+    const d = doc(para('p0'));
+    const byId = insertNodeRelative(d, block('new'), { position: 'after', anchorNodeId: 'nope' });
+    expect(byId.inserted).toBe(false);
+    expect(byId.doc).toEqual(d);
+
+    const byText = insertNodeRelative(d, block('new'), { position: 'before', anchorText: 'zzz' });
+    expect(byText.inserted).toBe(false);
+    expect(byText.doc).toEqual(d);
+  });
+
+  it('routes a structural tableRow to the nearest table container', () => {
+    const table = {
+      type: 'table',
+      content: [
+        row([cell('tableCell', 'r0c0', 'A')]),
+        row([cell('tableCell', 'r1c0', 'B')]),
+      ],
+    };
+    const d = doc(table);
+    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
+    // Anchor on a cell paragraph inside row 0; "after" should put the row after row 0.
+    const res = insertNodeRelative(d, newRow, { position: 'after', anchorNodeId: 'r0c0' });
+    expect(res.inserted).toBe(true);
+    const rowFirstCellId = (r: any) => r.content[0].content[0].attrs.id;
+    expect(res.doc.content[0].content.map(rowFirstCellId)).toEqual(['r0c0', 'rNew', 'r1c0']);
+  });
+
+  it('throws when appending a structural node at the top level', () => {
+    const d = doc(para('p0'));
+    const newRow = row([cell('tableCell', 'x', 'X')]);
+    expect(() => insertNodeRelative(d, newRow, { position: 'append' })).toThrow(
+      /cannot append a tableRow at the top level/,
+    );
+  });
+
+  it('throws when a structural anchor is not inside the required container', () => {
+    // Anchor resolves to a top-level paragraph that is not inside any table.
+    const d = doc(para('p0', 'loose'));
+    const newRow = row([cell('tableCell', 'x', 'X')]);
+    expect(() =>
+      insertNodeRelative(d, newRow, { position: 'after', anchorNodeId: 'p0' }),
+    ).toThrow(/the anchor is not inside a table/);
+  });
+
+  it('honours offset: before vs after place the node on the correct side', () => {
+    const d = doc(para('a'), para('b'), para('c'));
+    const before = insertNodeRelative(d, block('N'), { position: 'before', anchorNodeId: 'b' });
+    expect(before.doc.content.map((c: any) => c.attrs.id)).toEqual(['a', 'N', 'b', 'c']);
+    const after = insertNodeRelative(d, block('N'), { position: 'after', anchorNodeId: 'b' });
+    expect(after.doc.content.map((c: any) => c.attrs.id)).toEqual(['a', 'b', 'N', 'c']);
+  });
+
+  it('does not mutate the input doc or the node argument', () => {
+    const d = doc(para('p0'));
+    const dSnapshot = structuredClone(d);
+    const node = block('new', 'N');
+    const nodeSnapshot = structuredClone(node);
+    insertNodeRelative(d, node, { position: 'append' });
+    expect(d).toEqual(dSnapshot);
+    expect(node).toEqual(nodeSnapshot);
+  });
+});
+
+// ===========================================================================
+// readTable
+// ===========================================================================
+describe('readTable', () => {
+  const makeTable = () => ({
+    type: 'table',
+    content: [
+      row([cell('tableHeader', 'h0', 'H0'), cell('tableHeader', 'h1', 'H1')]),
+      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
+    ],
+  });
+
+  it('reads a table by #n', () => {
+    const d = doc(para('p0'), makeTable());
+    const res = readTable(d, '#1');
+    expect(res).not.toBeNull();
+    expect(res!.rows).toBe(2);
+    expect(res!.cols).toBe(2);
+    expect(res!.cells).toEqual([['H0', 'H1'], ['A', 'B']]);
+    expect(res!.cellIds).toEqual([['h0', 'h1'], ['c0', 'c1']]);
+    expect(res!.path).toEqual([1]);
+  });
+
+  it('climbs from an inner paragraph id up to the table', () => {
+    const d = doc(makeTable());
+    const res = readTable(d, 'c1'); // id of a paragraph inside a data cell
+    expect(res).not.toBeNull();
+    expect(res!.path).toEqual([0]);
+    expect(res!.cells).toEqual([['H0', 'H1'], ['A', 'B']]);
+  });
+
+  it('reports per-row widths via cells for a ragged table', () => {
+    const table = {
+      type: 'table',
+      content: [
+        row([cell('tableHeader', 'h0', 'H0')]),
+        row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
+      ],
+    };
+    const res = readTable(doc(table), '#0');
+    expect(res!.cols).toBe(1); // cols comes from row 0
+    expect(res!.cells).toEqual([['H0'], ['A', 'B']]); // actual per-row widths preserved
+    expect(res!.cellIds).toEqual([['h0'], ['c0', 'c1']]);
+  });
+
+  it('reports null cellId for an empty cell with no paragraph', () => {
+    const table = {
+      type: 'table',
+      content: [row([cell('tableCell', null), cell('tableCell', 'c1', 'B')])],
+    };
+    const res = readTable(doc(table), '#0');
+    expect(res!.cells).toEqual([['', 'B']]);
+    expect(res!.cellIds).toEqual([[null, 'c1']]);
+  });
+
+  it('returns null when the ref matches no table', () => {
+    const d = doc(para('p0'));
+    expect(readTable(d, '#0')).toBeNull(); // #0 is a paragraph, not a table
+    expect(readTable(d, 'missing')).toBeNull();
+    expect(readTable(d, 'p0')).toBeNull(); // id found but no enclosing table
+  });
+});
+
+// ===========================================================================
+// insertTableRow
+// ===========================================================================
+describe('insertTableRow', () => {
+  const makeTable = () => ({
+    type: 'table',
+    content: [
+      row([
+        cell('tableHeader', 'h0', 'H0', { colwidth: [120] }),
+        cell('tableHeader', 'h1', 'H1', { colwidth: [240] }),
+      ]),
+      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
+    ],
+  });
+
+  /** First-paragraph ids of every cell in a row, for ordering assertions. */
+  const rowCellParaIds = (r: any): (string | undefined)[] =>
+    r.content.map((c: any) => c.content[0]?.attrs?.id);
+  /** Cell text of a row. */
+  const rowTexts = (r: any): string[] =>
+    r.content.map((c: any) => blockPlainText(c));
+
+  it('appends a row when index is omitted', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y']);
+    expect(res.inserted).toBe(true);
+    const rows = res.doc.content[0].content;
+    expect(rows.length).toBe(3);
+    expect(rowTexts(rows[2])).toEqual(['X', 'Y']);
+  });
+
+  it('splices at a middle index', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y'], 1);
+    const rows = res.doc.content[0].content;
+    expect(rows.length).toBe(3);
+    expect(rowTexts(rows[1])).toEqual(['X', 'Y']); // new row at index 1
+    expect(rowTexts(rows[2])).toEqual(['A', 'B']); // old data row pushed down
+  });
+
+  it('splices at the end index', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y'], 2); // rows == 2, valid end index
+    const rows = res.doc.content[0].content;
+    expect(rows.length).toBe(3);
+    expect(rowTexts(rows[2])).toEqual(['X', 'Y']);
+  });
+
+  it('APPENDS (does not throw) for an out-of-range index', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y'], 99);
+    const rows = res.doc.content[0].content;
+    expect(res.inserted).toBe(true);
+    expect(rows.length).toBe(3);
+    expect(rowTexts(rows[2])).toEqual(['X', 'Y']); // appended at the end
+  });
+
+  it('throws when given more cells than columns', () => {
+    const d = doc(makeTable());
+    expect(() => insertTableRow(d, '#0', ['X', 'Y', 'Z'])).toThrow(
+      /got 3 cell\(s\) but the table has 2 column\(s\)/,
+    );
+  });
+
+  it('pads a short row to the column count', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['only']);
+    const rows = res.doc.content[0].content;
+    expect(rowTexts(rows[2])).toEqual(['only', '']); // padded with empty cell
+  });
+
+  it('copies colwidth from the header row for each column', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y']);
+    const newRow = res.doc.content[0].content[2];
+    expect(newRow.content[0].attrs.colwidth).toEqual([120]);
+    expect(newRow.content[1].attrs.colwidth).toEqual([240]);
+    expect(newRow.content[0].attrs).toMatchObject({ colspan: 1, rowspan: 1 });
+  });
+
+  it('index 0 inherits the header cell TYPE', () => {
+    const d = doc(makeTable());
+    const res = insertTableRow(d, '#0', ['X', 'Y'], 0);
+    const newRow = res.doc.content[0].content[0];
+    expect(newRow.content.every((c: any) => c.type === 'tableHeader')).toBe(true);
+    // A non-zero index produces plain data cells instead.
+    const res2 = insertTableRow(d, '#0', ['X', 'Y'], 1);
+    const dataRow = res2.doc.content[0].content[1];
+    expect(dataRow.content.every((c: any) => c.type === 'tableCell')).toBe(true);
+  });
+
+  it('mints unique, well-formed paragraph ids for new cells', () => {
+    const d = doc(makeTable());
+    const existing = new Set(['h0', 'h1', 'c0', 'c1']);
+    const res = insertTableRow(d, '#0', ['X', 'Y']);
+    const newRow = res.doc.content[0].content[2];
+    const ids = rowCellParaIds(newRow) as string[];
+    for (const id of ids) {
+      expect(typeof id).toBe('string');
+      expect(id).toMatch(/^[a-z0-9]{12}$/); // Docmost-style 12-char id
+      expect(existing.has(id)).toBe(false); // unique vs pre-existing ids
+    }
+    expect(new Set(ids).size).toBe(ids.length); // unique within the row
+  });
+
+  it('returns inserted:false when the table cannot be located', () => {
+    const d = doc(para('p0'));
+    const res = insertTableRow(d, 'missing', ['X']);
+    expect(res.inserted).toBe(false);
+    expect(res.doc).toEqual(d);
+  });
+
+  it('does not mutate the input doc', () => {
+    const d = doc(makeTable());
+    const snapshot = structuredClone(d);
+    insertTableRow(d, '#0', ['X', 'Y'], 1);
+    expect(d).toEqual(snapshot);
+  });
+});
+
+// ===========================================================================
+// deleteTableRow
+// ===========================================================================
+describe('deleteTableRow', () => {
+  const makeTable = () => ({
+    type: 'table',
+    content: [
+      row([cell('tableHeader', 'h0', 'H')]),
+      row([cell('tableCell', 'c0', 'A')]),
+      row([cell('tableCell', 'c1', 'B')]),
+    ],
+  });
+  const firstId = (r: any) => r.content[0].content[0].attrs.id;
+
+  it('deletes a middle row and preserves siblings', () => {
+    const d = doc(makeTable());
+    const res = deleteTableRow(d, '#0', 1);
+    expect(res.deleted).toBe(true);
+    expect(res.doc.content[0].content.map(firstId)).toEqual(['h0', 'c1']);
+  });
+
+  it('deletes the first row', () => {
+    const d = doc(makeTable());
+    const res = deleteTableRow(d, '#0', 0);
+    expect(res.doc.content[0].content.map(firstId)).toEqual(['c0', 'c1']);
+  });
+
+  it('deletes the last row', () => {
+    const d = doc(makeTable());
+    const res = deleteTableRow(d, '#0', 2);
+    expect(res.doc.content[0].content.map(firstId)).toEqual(['h0', 'c0']);
+  });
+
+  it('throws on an out-of-range index', () => {
+    const d = doc(makeTable());
+    expect(() => deleteTableRow(d, '#0', 99)).toThrow(/out of range/);
+    expect(() => deleteTableRow(d, '#0', -1)).toThrow(/out of range/);
+  });
+
+  it('throws when asked to delete the only row', () => {
+    const single = {
+      type: 'table',
+      content: [row([cell('tableCell', 'c0', 'A')])],
+    };
+    expect(() => deleteTableRow(doc(single), '#0', 0)).toThrow(
+      /refusing to delete the only row/,
+    );
+  });
+
+  it('returns deleted:false when the table cannot be located', () => {
+    const d = doc(para('p0'));
+    const res = deleteTableRow(d, 'missing', 0);
+    expect(res.deleted).toBe(false);
+    expect(res.doc).toEqual(d);
+  });
+
+  it('does not mutate the input doc', () => {
+    const d = doc(makeTable());
+    const snapshot = structuredClone(d);
+    deleteTableRow(d, '#0', 1);
+    expect(d).toEqual(snapshot);
+  });
+});
+
+// ===========================================================================
+// updateTableCell
+// ===========================================================================
+describe('updateTableCell', () => {
+  const makeTable = () => ({
+    type: 'table',
+    content: [
+      row([cell('tableHeader', 'h0', 'H0'), cell('tableHeader', 'h1', 'H1')]),
+      row([
+        cell('tableCell', 'c0', 'A', { colspan: 2, rowspan: 3, colwidth: [200] }),
+        cell('tableCell', 'c1', 'B'),
+      ]),
+    ],
+  });
+
+  it('sets the cell text', () => {
+    const d = doc(makeTable());
+    const res = updateTableCell(d, '#0', 1, 1, 'NEW');
+    expect(res.updated).toBe(true);
+    expect(blockPlainText(res.doc.content[0].content[1].content[1])).toBe('NEW');
+  });
+
+  it('REUSES the existing first-paragraph id', () => {
+    const d = doc(makeTable());
+    const res = updateTableCell(d, '#0', 1, 0, 'changed');
+    const para0 = res.doc.content[0].content[1].content[0].content[0];
+    expect(para0.attrs.id).toBe('c0'); // critical: id reused, not regenerated
+    expect(para0.content[0].text).toBe('changed');
+  });
+
+  it('mints a fresh id when the cell had no paragraph', () => {
+    const table = {
+      type: 'table',
+      content: [row([cell('tableCell', null), cell('tableCell', 'c1', 'B')])],
+    };
+    const d = doc(table);
+    const res = updateTableCell(d, '#0', 0, 0, 'now has text');
+    const newPara = res.doc.content[0].content[0].content[0].content[0];
+    expect(typeof newPara.attrs.id).toBe('string');
+    expect(newPara.attrs.id).toMatch(/^[a-z0-9]{12}$/);
+    expect(newPara.attrs.id).not.toBe('c1'); // unique vs existing ids
+    expect(newPara.content[0].text).toBe('now has text');
+  });
+
+  it('PRESERVES the cell colspan/rowspan/colwidth (only content replaced)', () => {
+    const d = doc(makeTable());
+    const res = updateTableCell(d, '#0', 1, 0, 'x');
+    const cellNode = res.doc.content[0].content[1].content[0];
+    expect(cellNode.attrs).toEqual({ colspan: 2, rowspan: 3, colwidth: [200] });
+  });
+
+  it('throws when row or col is out of range', () => {
+    const d = doc(makeTable());
+    expect(() => updateTableCell(d, '#0', 5, 0, 'x')).toThrow(/out of range/);
+    expect(() => updateTableCell(d, '#0', 0, 5, 'x')).toThrow(/out of range/);
+    expect(() => updateTableCell(d, '#0', -1, 0, 'x')).toThrow(/out of range/);
+  });
+
+  it('an empty string yields an empty paragraph content array', () => {
+    const d = doc(makeTable());
+    const res = updateTableCell(d, '#0', 1, 1, '');
+    const cellPara = res.doc.content[0].content[1].content[1].content[0];
+    expect(cellPara.type).toBe('paragraph');
+    expect(cellPara.content).toEqual([]); // empty string -> empty content
+    expect(cellPara.attrs.id).toBe('c1'); // id still reused
+  });
+
+  it('returns updated:false when the table cannot be located', () => {
+    const d = doc(para('p0'));
+    const res = updateTableCell(d, 'missing', 0, 0, 'x');
+    expect(res.updated).toBe(false);
+    expect(res.doc).toEqual(d);
+  });
+
+  it('does not mutate the input doc', () => {
+    const d = doc(makeTable());
+    const snapshot = structuredClone(d);
+    updateTableCell(d, '#0', 1, 1, 'NEW');
+    expect(d).toEqual(snapshot);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/page-file.test.ts b/packages/prosemirror-markdown/test/page-file.test.ts
new file mode 100644
index 00000000..9cd54efc
--- /dev/null
+++ b/packages/prosemirror-markdown/test/page-file.test.ts
@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { parsePageFile, serializePageFile } from "../src/lib/page-file";
+
+describe("page-file thin format", () => {
+  it("round-trips id frontmatter + clean body", () => {
+    const text = serializePageFile("019ef6fc-2638", "# Hello\n\nbody text");
+    expect(text.startsWith("---\ngitmost_id: 019ef6fc-2638\n---\n")).toBe(true);
+    const { id, body } = parsePageFile(text);
+    expect(id).toBe("019ef6fc-2638");
+    expect(body).toBe("# Hello\n\nbody text");
+  });
+
+  it("serialization is deterministic (byte-identical for the same input)", () => {
+    expect(serializePageFile("p", "x")).toBe(serializePageFile("p", "x"));
+  });
+
+  it("reads id from frontmatter with quotes / extra fields", () => {
+    expect(parsePageFile('---\ngitmost_id: "abc"\ntitle: ignored\n---\nbody').id).toBe("abc");
+    expect(parsePageFile("---\ngitmost_id: 'xyz'\n---\nbody").id).toBe("xyz");
+  });
+
+
+  it("ADOPT: a plain hand-written file has no id and keeps its whole body", () => {
+    const { id, body } = parsePageFile("# Just a note\n\nwritten in Obsidian");
+    expect(id).toBeNull();
+    expect(body).toBe("# Just a note\n\nwritten in Obsidian");
+  });
+
+  it("tolerates empty / whitespace input", () => {
+    expect(parsePageFile("").id).toBeNull();
+    expect(parsePageFile("   \n  ").body).toBe("");
+  });
+});
diff --git a/packages/prosemirror-markdown/test/redteam-converter.test.ts b/packages/prosemirror-markdown/test/redteam-converter.test.ts
new file mode 100644
index 00000000..a6f88f68
--- /dev/null
+++ b/packages/prosemirror-markdown/test/redteam-converter.test.ts
@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest';
+// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
+// pulls in collaboration.ts and mutates the global DOM at import time), matching
+// the other converter unit tests. markdownToProseMirror is imported for the
+// round-trip cases; loading it mutates the global DOM via jsdom (required for
+// @tiptap/html's generateJSON under Node) — this is expected.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+
+// ---------------------------------------------------------------------------
+// #1 editor-ext atoms dropped: the `default` branch (markdown-converter.ts
+// ~584-586) collapses unknown atoms to "" by mapping their (empty) children.
+// ---------------------------------------------------------------------------
+describe('#1 editor-ext atoms dropped', () => {
+  it('preserves an inline status atom text', () => {
+    const d = doc({
+      type: 'paragraph',
+      content: [{ type: 'status', attrs: { text: 'Done' } }],
+    });
+    expect(convertProseMirrorToMarkdown(d)).toContain('Done');
+  });
+
+  it('preserves a block htmlEmbed atom', () => {
+    const d = doc({ type: 'htmlEmbed', attrs: { source: '<b>hi</b>' } });
+    expect(convertProseMirrorToMarkdown(d)).not.toBe('');
+  });
+
+  it('preserves a footnoteReference atom', () => {
+    const d = doc({
+      type: 'paragraph',
+      content: [{ type: 'footnoteReference', attrs: { id: 'fn1', referenceNumber: 1 } }],
+    });
+    expect(convertProseMirrorToMarkdown(d)).not.toBe('');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// #2 top-level image attrs lost: a top-level image emits markdown ![](src),
+// which carries no width/height/align/attachmentId.
+// ---------------------------------------------------------------------------
+describe('#2 top-level image attrs lost', () => {
+  it('keeps width through export and re-import', async () => {
+    const d = doc({
+      type: 'image',
+      attrs: { src: '/files/x.png', width: '320', height: '200', align: 'right', attachmentId: 'a1' },
+    });
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toContain('320');
+    const back = await markdownToProseMirror(md);
+    expect(back.content[0].attrs.width).toBe('320');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// #3 code-fence corruption: a code block whose TEXT contains a ``` fence must
+// be emitted with a wider outer fence so the inner fence survives.
+// ---------------------------------------------------------------------------
+describe('#3 code-fence corruption', () => {
+  it('round-trips a code block containing an inner fence', async () => {
+    const code = '```js\nfoo()\n```';
+    const d = doc({
+      type: 'codeBlock',
+      attrs: { language: '' },
+      content: [{ type: 'text', text: code }],
+    });
+    const md1 = convertProseMirrorToMarkdown(d);
+    const back = await markdownToProseMirror(md1);
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// #16 depth guard: deep recursion in processNode overflows the stack (today a
+// RangeError) instead of being guarded.
+// ---------------------------------------------------------------------------
+describe('#16 depth guard', () => {
+  it('does not throw on a deeply nested blockquote doc', () => {
+    const DEPTH = 50000;
+    let node: any = { type: 'paragraph', content: [{ type: 'text', text: 'x' }] };
+    for (let i = 0; i < DEPTH; i++) {
+      node = { type: 'blockquote', content: [node] };
+    }
+    const d = doc(node);
+    expect(() => convertProseMirrorToMarkdown(d)).not.toThrow();
+  });
+});
diff --git a/packages/prosemirror-markdown/test/roundtrip-all-nodes.test.ts b/packages/prosemirror-markdown/test/roundtrip-all-nodes.test.ts
new file mode 100644
index 00000000..6bc634a9
--- /dev/null
+++ b/packages/prosemirror-markdown/test/roundtrip-all-nodes.test.ts
@@ -0,0 +1,297 @@
+import { describe, expect, it } from 'vitest';
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+/**
+ * Exhaustive serialize -> deserialize round trip for EVERY node and mark type the
+ * Docmost document schema supports. The git-sync converter exports a page body to
+ * Markdown and imports it back; any node type that has no parseHTML inverse (or is
+ * serialized to a literal that never re-parses) silently degrades to plain text on
+ * a round trip — e.g. `subpages` used to export as the literal `{{SUBPAGES}}` and
+ * came back as the visible text "{{SUBPAGES}}" instead of the embed.
+ *
+ * This guards the whole class: for one representative fixture per type, the node
+ * (or mark) MUST still be present after convert -> import, and the exported
+ * Markdown must not contain a `{{...}}` template literal (the old lossy form).
+ */
+
+const T = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const P = (...c: any[]) => ({ type: 'paragraph', content: c });
+const doc = (...c: any[]) => ({ type: 'doc', content: c });
+
+// `primary` is the node/mark type that must survive the round trip.
+const FIXTURES: Record<string, { doc: any; primary: string }> = {
+  paragraph: { doc: doc(P(T('hello'))), primary: 'paragraph' },
+  heading: { doc: doc({ type: 'heading', attrs: { level: 2 }, content: [T('H2')] }), primary: 'heading' },
+  blockquote: { doc: doc({ type: 'blockquote', content: [P(T('q'))] }), primary: 'blockquote' },
+  codeBlock: { doc: doc({ type: 'codeBlock', attrs: { language: 'js' }, content: [T('foo()')] }), primary: 'codeBlock' },
+  bulletList: { doc: doc({ type: 'bulletList', content: [{ type: 'listItem', content: [P(T('a'))] }] }), primary: 'bulletList' },
+  orderedList: { doc: doc({ type: 'orderedList', attrs: { start: 1 }, content: [{ type: 'listItem', content: [P(T('a'))] }] }), primary: 'orderedList' },
+  taskList: { doc: doc({ type: 'taskList', content: [{ type: 'taskItem', attrs: { checked: true }, content: [P(T('done'))] }] }), primary: 'taskList' },
+  horizontalRule: { doc: doc({ type: 'horizontalRule' }), primary: 'horizontalRule' },
+  image: { doc: doc({ type: 'image', attrs: { src: '/f/x.png', width: '320', align: 'center' } }), primary: 'image' },
+  hardBreak: { doc: doc(P(T('a'), { type: 'hardBreak' }, T('b'))), primary: 'hardBreak' },
+  callout: { doc: doc({ type: 'callout', attrs: { type: 'info' }, content: [P(T('note'))] }), primary: 'callout' },
+  columns: {
+    doc: doc({ type: 'columns', content: [
+      { type: 'column', attrs: { width: '50%' }, content: [P(T('L'))] },
+      { type: 'column', attrs: { width: '50%' }, content: [P(T('R'))] }] }),
+    primary: 'column',
+  },
+  details: {
+    doc: doc({ type: 'details', content: [
+      { type: 'detailsSummary', content: [T('Sum')] },
+      { type: 'detailsContent', content: [P(T('body'))] }] }),
+    primary: 'details',
+  },
+  table: {
+    doc: doc({ type: 'table', content: [
+      { type: 'tableRow', content: [{ type: 'tableHeader', content: [P(T('H1'))] }, { type: 'tableHeader', content: [P(T('H2'))] }] },
+      { type: 'tableRow', content: [{ type: 'tableCell', content: [P(T('C1'))] }, { type: 'tableCell', content: [P(T('C2'))] }] }] }),
+    primary: 'tableCell',
+  },
+  mathBlock: { doc: doc({ type: 'mathBlock', attrs: { math: 'x^2' } }), primary: 'mathBlock' },
+  mathInline: { doc: doc(P({ type: 'mathInline', attrs: { math: 'x^2' } })), primary: 'mathInline' },
+  mention: { doc: doc(P({ type: 'mention', attrs: { id: 'u1', label: 'Bob', entityType: 'user', entityId: 'u1' } })), primary: 'mention' },
+  drawio: { doc: doc({ type: 'drawio', attrs: { src: '/f/d.drawio', attachmentId: 'a1' } }), primary: 'drawio' },
+  excalidraw: { doc: doc({ type: 'excalidraw', attrs: { src: '/f/e.excalidraw', attachmentId: 'a1' } }), primary: 'excalidraw' },
+  embed: { doc: doc({ type: 'embed', attrs: { src: 'https://youtube.com/x', provider: 'iframe' } }), primary: 'embed' },
+  pdf: { doc: doc({ type: 'pdf', attrs: { src: '/f/x.pdf', attachmentId: 'a1' } }), primary: 'pdf' },
+  video: { doc: doc({ type: 'video', attrs: { src: '/f/v.mp4', width: '640' } }), primary: 'video' },
+  audio: { doc: doc({ type: 'audio', attrs: { src: '/f/a.mp3' } }), primary: 'audio' },
+  attachment: { doc: doc({ type: 'attachment', attrs: { url: '/f/x.zip', name: 'x.zip', attachmentId: 'a1' } }), primary: 'attachment' },
+  youtube: { doc: doc({ type: 'youtube', attrs: { src: 'https://youtube.com/watch?v=x' } }), primary: 'youtube' },
+  subpages: { doc: doc({ type: 'subpages' }), primary: 'subpages' },
+  pageBreak: { doc: doc({ type: 'pageBreak' }), primary: 'pageBreak' },
+  htmlEmbed: { doc: doc({ type: 'htmlEmbed', attrs: { source: '<b>hi</b>' } }), primary: 'htmlEmbed' },
+  pageEmbed: { doc: doc({ type: 'pageEmbed', attrs: { pageId: 'p1' } }), primary: 'pageEmbed' },
+  // transclusionSource: the schema reads `id` (NOT `pageId`) and its content is
+  // `+` (at least one block child), so give it both or it never re-parses.
+  transclusion: { doc: doc({ type: 'transclusionSource', attrs: { id: 't1' }, content: [P(T('shared'))] }), primary: 'transclusionSource' },
+  transclusionReference: { doc: doc({ type: 'transclusionReference', attrs: { sourcePageId: 'p1', transclusionId: 't1' } }), primary: 'transclusionReference' },
+  footnote: {
+    doc: doc(
+      P(T('x'), { type: 'footnoteReference', attrs: { id: 'fn1' } }),
+      { type: 'footnotesList', content: [{ type: 'footnoteDefinition', attrs: { id: 'fn1' }, content: [P(T('note'))] }] }),
+    primary: 'footnoteReference',
+  },
+  status: { doc: doc(P({ type: 'status', attrs: { text: 'Done', color: 'green' } })), primary: 'status' },
+  // marks
+  bold: { doc: doc(P(T('b', [{ type: 'bold' }]))), primary: 'bold' },
+  italic: { doc: doc(P(T('i', [{ type: 'italic' }]))), primary: 'italic' },
+  strike: { doc: doc(P(T('s', [{ type: 'strike' }]))), primary: 'strike' },
+  code: { doc: doc(P(T('c', [{ type: 'code' }]))), primary: 'code' },
+  underline: { doc: doc(P(T('u', [{ type: 'underline' }]))), primary: 'underline' },
+  superscript: { doc: doc(P(T('x', [{ type: 'superscript' }]))), primary: 'superscript' },
+  subscript: { doc: doc(P(T('x', [{ type: 'subscript' }]))), primary: 'subscript' },
+  highlight: { doc: doc(P(T('h', [{ type: 'highlight', attrs: { color: 'yellow' } }]))), primary: 'highlight' },
+  link: { doc: doc(P(T('l', [{ type: 'link', attrs: { href: 'https://x.com' } }]))), primary: 'link' },
+};
+
+function collectTypes(n: any, set = new Set<string>()): Set<string> {
+  if (!n || typeof n !== 'object') return set;
+  if (n.type) set.add(n.type);
+  if (Array.isArray(n.content)) n.content.forEach((c: any) => collectTypes(c, set));
+  if (Array.isArray(n.marks)) n.marks.forEach((m: any) => m?.type && set.add(m.type));
+  return set;
+}
+
+describe('git-sync converter: every node/mark type survives a Markdown round trip', () => {
+  for (const [name, { doc: original, primary }] of Object.entries(FIXTURES)) {
+    it(`round-trips ${name} (keeps the ${primary} node/mark, no literal leak)`, async () => {
+      const md = convertProseMirrorToMarkdown(original);
+      // The lossy old form serialized embeds to `{{...}}` literals that never
+      // re-parsed; no node may export to one.
+      expect(md).not.toMatch(/\{\{.*\}\}/);
+      const back = await markdownToProseMirror(md);
+      const types = collectTypes(back);
+      expect(types.has(primary)).toBe(true);
+    });
+  }
+});
+
+// A node surviving as the right TYPE is necessary but not sufficient — its
+// attributes must survive too. Each case carries a DISTINCTIVE attribute value
+// (real attr names, verified against the schema) that must reappear after a
+// round trip. This caught `subpages.recursive` and `details.open` being dropped.
+describe('git-sync converter: node ATTRIBUTES survive a Markdown round trip', () => {
+  const ATTR_CASES: Array<{ name: string; doc: any; needles: string[] }> = [
+    { name: 'callout type', doc: doc({ type: 'callout', attrs: { type: 'warning' }, content: [P(T('x'))] }), needles: ['warning'] },
+    { name: 'image dimensions/align/attachmentId', doc: doc({ type: 'image', attrs: { src: '/f/x.png', width: '777', height: '555', align: 'right', attachmentId: 'ATT777' } }), needles: ['777', '555', 'right', 'ATT777'] },
+    { name: 'subpages recursive', doc: doc({ type: 'subpages', attrs: { recursive: true } }), needles: ['"recursive":true'] },
+    { name: 'details open', doc: doc({ type: 'details', attrs: { open: true }, content: [{ type: 'detailsSummary', content: [T('S')] }, { type: 'detailsContent', content: [P(T('b'))] }] }), needles: ['"open":'] },
+    { name: 'mathInline formula', doc: doc(P({ type: 'mathInline', attrs: { text: 'E=mc^7' } })), needles: ['E=mc^7'] },
+    { name: 'mathBlock formula', doc: doc({ type: 'mathBlock', attrs: { text: '\\sum_7' } }), needles: ['sum_7'] },
+    { name: 'pageEmbed sourcePageId', doc: doc({ type: 'pageEmbed', attrs: { sourcePageId: 'PAGE777' } }), needles: ['PAGE777'] },
+    { name: 'video dimensions/attachmentId', doc: doc({ type: 'video', attrs: { src: '/f/v.mp4', width: '888', attachmentId: 'VID888' } }), needles: ['888', 'VID888'] },
+    { name: 'status text/color', doc: doc(P({ type: 'status', attrs: { text: 'InProgress777', color: 'orange' } })), needles: ['InProgress777', 'orange'] },
+    { name: 'mention entityId/label', doc: doc(P({ type: 'mention', attrs: { id: 'M1', label: 'Alice', entityType: 'user', entityId: 'ENT777' } })), needles: ['Alice', 'ENT777'] },
+    { name: 'columns widths', doc: doc({ type: 'columns', content: [{ type: 'column', attrs: { width: '37%' }, content: [P(T('L'))] }, { type: 'column', attrs: { width: '63%' }, content: [P(T('R'))] }] }), needles: ['37%', '63%'] },
+    { name: 'highlight color', doc: doc(P(T('x', [{ type: 'highlight', attrs: { color: '#abcdef' } }]))), needles: ['#abcdef'] },
+  ];
+  for (const { name, doc: original, needles } of ATTR_CASES) {
+    it(`preserves ${name}`, async () => {
+      const md = convertProseMirrorToMarkdown(original);
+      const back = JSON.stringify(await markdownToProseMirror(md));
+      for (const needle of needles) {
+        // The value must survive in the re-imported doc (or in the markdown the
+        // schema parses it back from).
+        expect(`${back} ${md}`).toContain(needle);
+      }
+    });
+  }
+});
+
+// Find the FIRST node of a given type anywhere in a ProseMirror tree (depth
+// first). Used by the structural round-trip assertions below that need the
+// re-imported node's concrete attrs/content, not just "the type is present".
+function findNode(n: any, type: string): any {
+  if (!n || typeof n !== 'object') return undefined;
+  if (n.type === type) return n;
+  if (Array.isArray(n.content)) {
+    for (const c of n.content) {
+      const hit = findNode(c, type);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+// Collect every text run reachable under a node (concatenated). Lets a test
+// assert a footnote definition's note BODY survived, not just the wrapper.
+function allText(n: any): string {
+  if (!n || typeof n !== 'object') return '';
+  if (n.type === 'text') return n.text || '';
+  if (Array.isArray(n.content)) return n.content.map(allText).join('');
+  return '';
+}
+
+// Attributes survive as the TYPE-correct value, not just as a substring of the
+// serialized blob. These re-import and assert on the concrete re-parsed node.
+describe('git-sync converter: lose-prone atoms keep their VALUES across a round trip', () => {
+  it('A: a NESTED details (inside columns) keeps open:true', async () => {
+    // The raw-HTML path (detailsToHtml) is used for a details nested in a
+    // column/spanned cell — distinct from the top-level details case. Before the
+    // fix it emitted a bare <details>, dropping open every round trip.
+    const original = doc({
+      type: 'columns',
+      content: [
+        {
+          type: 'column',
+          attrs: { width: '100%' },
+          content: [
+            {
+              type: 'details',
+              attrs: { open: true },
+              content: [
+                { type: 'detailsSummary', content: [T('S')] },
+                { type: 'detailsContent', content: [P(T('b'))] },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    // detailsToHtml must emit the `open` attribute (RED before the fix: it
+    // emitted a bare <details> inside the column).
+    expect(md).toContain('<details open>');
+    const back = await markdownToProseMirror(md);
+    const details = findNode(back, 'details');
+    expect(details).toBeDefined();
+    // `open` must round-trip as a STRICT boolean `true` — not "" (the old raw
+    // getAttribute value) and not the default `false` (a dropped attribute).
+    // Before the schema parseHTML fix (hasAttribute), `<details open>` parsed to
+    // "" — falsy, so it rendered as a bare <details> and collapsed. RED before
+    // the fix (open was "" or false, never === true).
+    expect(details.attrs?.open).toBe(true);
+  });
+
+  it('B: a TOP-LEVEL details keeps open as strict boolean true', async () => {
+    const original = doc({
+      type: 'details',
+      attrs: { open: true },
+      content: [
+        { type: 'detailsSummary', content: [T('S')] },
+        { type: 'detailsContent', content: [P(T('b'))] },
+      ],
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    const back = await markdownToProseMirror(md);
+    const details = findNode(back, 'details');
+    expect(details).toBeDefined();
+    // Strict boolean, proving the value survives as `true` (not ""/false).
+    // RED before the fix: parseHTML returned getAttribute("open") === "".
+    expect(details.attrs?.open).toBe(true);
+  });
+
+  it('D: htmlEmbed source VALUE and height survive', async () => {
+    const original = doc({
+      type: 'htmlEmbed',
+      attrs: { source: '<b>hi</b>', height: 300 },
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    const back = await markdownToProseMirror(md);
+    const embed = findNode(back, 'htmlEmbed');
+    expect(embed).toBeDefined();
+    // The exact raw source must decode back identically (base64 round trip).
+    expect(embed.attrs?.source).toBe('<b>hi</b>');
+    expect(embed.attrs?.height).toBe(300);
+  });
+
+  it('E: footnote definition BODY survives and its id matches the reference', async () => {
+    const original = doc(
+      P(T('x'), { type: 'footnoteReference', attrs: { id: 'fn1' } }),
+      {
+        type: 'footnotesList',
+        content: [
+          {
+            type: 'footnoteDefinition',
+            attrs: { id: 'fn1' },
+            content: [P(T('note'))],
+          },
+        ],
+      },
+    );
+    const md = convertProseMirrorToMarkdown(original);
+    const back = await markdownToProseMirror(md);
+    const list = findNode(back, 'footnotesList');
+    const def = findNode(back, 'footnoteDefinition');
+    const ref = findNode(back, 'footnoteReference');
+    expect(list).toBeDefined();
+    expect(def).toBeDefined();
+    expect(ref).toBeDefined();
+    // The note text rode along, not just the empty wrapper.
+    expect(allText(def)).toContain('note');
+    // The reference still points at the matching definition.
+    expect(ref.attrs?.id).toBe(def.attrs?.id);
+  });
+
+  it('F: transclusionReference keeps BOTH sourcePageId and transclusionId', async () => {
+    const original = doc({
+      type: 'transclusionReference',
+      attrs: { sourcePageId: 'PAGE_X', transclusionId: 'TR_Y' },
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    const back = await markdownToProseMirror(md);
+    const ref = findNode(back, 'transclusionReference');
+    expect(ref).toBeDefined();
+    expect(ref.attrs?.sourcePageId).toBe('PAGE_X');
+    expect(ref.attrs?.transclusionId).toBe('TR_Y');
+  });
+
+  it('F: transclusionSource keeps its id and re-parses its child body', async () => {
+    const original = doc({
+      type: 'transclusionSource',
+      attrs: { id: 'SRC_Z' },
+      content: [P(T('shared body'))],
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    const back = await markdownToProseMirror(md);
+    const src = findNode(back, 'transclusionSource');
+    expect(src).toBeDefined();
+    expect(src.attrs?.id).toBe('SRC_Z');
+    expect(allText(src)).toContain('shared body');
+  });
+});
diff --git a/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts b/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
new file mode 100644
index 00000000..b715b170
--- /dev/null
+++ b/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+  docsCanonicallyEqual,
+} from 'docmost-client';
+
+// Resolve fixtures relative to this test file so the test is CWD-independent.
+const here = dirname(fileURLToPath(import.meta.url));
+const CORPUS_DIR = join(here, 'fixtures', 'corpus');
+const KNOWN_LIMITATIONS_DIR = join(here, 'fixtures', 'known-limitations');
+
+/** Run a single document through export -> import -> export. */
+async function roundTrip(doc: any) {
+  const md1 = convertProseMirrorToMarkdown(doc);
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, md2, doc2 };
+}
+
+describe('round-trip corpus (SPEC §11)', () => {
+  // Discover the corpus synchronously at collection time so each fixture gets
+  // its own `it` with the file name in the test title.
+  const files = readdirSync(CORPUS_DIR)
+    .filter((name) => name.endsWith('.json'))
+    .sort();
+
+  it('has a non-empty corpus', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  for (const name of files) {
+    it(`${name}: markdown byte-stable AND canonically stable`, async () => {
+      const doc = JSON.parse(await readFile(join(CORPUS_DIR, name), 'utf8'));
+      const { md1, md2, doc2 } = await roundTrip(doc);
+
+      // 1) The byte-stable markdown property git actually needs.
+      expect(md2, `${name}: markdown not byte-stable`).toBe(md1);
+      // 2) Semantic stability (block ids stripped, default-null normalized).
+      expect(
+        docsCanonicallyEqual(doc, doc2),
+        `${name}: document not canonically stable`,
+      ).toBe(true);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// KNOWN CONVERTER LIMITATIONS (isolated so they do NOT make CI red).
+//
+// SPEC §11 explicitly flags images and diagrams as high round-trip risk. These
+// fixtures are kept OUT of the green corpus above and asserted with `it.fails`
+// so the documented divergence is locked in (the test FAILS if the converter
+// ever starts round-tripping them — at which point promote the fixture into
+// the corpus). The precise divergences for `image-diagrams.json` are:
+//
+//   * A BLOCK-LEVEL image preceded by a paragraph is NOT byte-stable on the
+//     FIRST re-export. The HTML re-parser hoists the block <img> out of its
+//     line and leaves an empty paragraph behind, so `paragraph` + `![..](..)`
+//     re-imports as paragraph + empty-paragraph + image; the empty paragraph
+//     adds one blank line, so export #2 grows by a one-time "\n\n" (md1 !== md2).
+//     This is NOT non-convergence: the growth happens exactly ONCE. The doc
+//     CONVERGES to a fixpoint after one extra `export→import→export` pass — the
+//     empty paragraph is already present after the first import, so export #2
+//     and export #3 are byte-identical (md2 === md3, verified).
+//
+//   * drawio / excalidraw diagrams gain `data-align="center"` on the second
+//     export: the schema's diagram `align` attribute has a NON-null default of
+//     "center", which materializes on import; the converter only emits
+//     data-align when set, so it appears on export #2 but not #1. Like the
+//     image case, this is one-time and converges after one extra pass.
+//
+//   * A STANDALONE block image (no preceding paragraph) IS byte-stable from
+//     export #1 (md1 === md2) — but it is still NOT canonically stable: on
+//     import the bare <img> is wrapped, gaining a leading EMPTY paragraph, so
+//     the canonical doc differs by that spurious paragraph node even though the
+//     markdown bytes match.
+//
+// Resolution (SPEC §11, "normalize-on-write"): rather than deep-fixing the
+// converter, the engine runs ONE `export→import→export` pass when writing into
+// the vault; from that fixpoint onward the form is byte-stable, so git sees no
+// phantom diff. The green corpus above avoids these one-time asymmetries by
+// pre-authoring the materialized defaults (e.g. `align: "center"` on the
+// diagrams in 06-diagrams.json) so a single pass is already at the fixpoint.
+// ---------------------------------------------------------------------------
+describe('round-trip KNOWN LIMITATIONS (SPEC §11 image/diagram risk)', () => {
+  it.fails(
+    'image-diagrams.json is NOT byte-stable on export #1 (block image hoist + diagram align default; converges after one extra pass — SPEC §11 normalize-on-write)',
+    async () => {
+      const doc = JSON.parse(
+        await readFile(join(KNOWN_LIMITATIONS_DIR, 'image-diagrams.json'), 'utf8'),
+      );
+      const { md1, md2 } = await roundTrip(doc);
+      // This assertion FAILS today (documented divergence). `it.fails` turns a
+      // failing body into a PASS; if the converter is fixed this flips and the
+      // test goes red, prompting promotion into the green corpus.
+      expect(md2).toBe(md1);
+    },
+  );
+});
diff --git a/packages/prosemirror-markdown/test/roundtrip-helpers.ts b/packages/prosemirror-markdown/test/roundtrip-helpers.ts
new file mode 100644
index 00000000..20eb490f
--- /dev/null
+++ b/packages/prosemirror-markdown/test/roundtrip-helpers.ts
@@ -0,0 +1,75 @@
+/**
+ * Pure, IO-free comparison helpers for the idempotency round-trip checks. The
+ * round-trip harness that drives these lives in the package's tests, not in the
+ * engine.
+ */
+
+/**
+ * Recursively strip every `attrs.id` from a ProseMirror node tree. Block ids
+ * are regenerated by `markdownToProseMirror` (SPEC §11), so they must be
+ * ignored when comparing the semantic shape of two documents. Returns a NEW
+ * tree; the input is not mutated.
+ */
+export function stripBlockIds(node: any): any {
+  if (Array.isArray(node)) {
+    return node.map(stripBlockIds);
+  }
+  if (node && typeof node === "object") {
+    const out: any = {};
+    for (const key of Object.keys(node)) {
+      if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
+        // Drop the `id` attr; keep every other attribute.
+        const { id, ...rest } = node.attrs as Record<string, unknown>;
+        void id;
+        out.attrs = stripBlockIds(rest);
+      } else {
+        out[key] = stripBlockIds(node[key]);
+      }
+    }
+    return out;
+  }
+  return node;
+}
+
+/**
+ * Find the first divergence between two values via a recursive deep compare.
+ * Returns a short path + the two differing values, or null if they are equal.
+ */
+export function firstDivergence(
+  a: any,
+  b: any,
+  path = "$",
+): { path: string; a: any; b: any } | null {
+  if (a === b) return null;
+
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta !== tb || a === null || b === null) {
+    return { path, a, b };
+  }
+  if (ta !== "object") {
+    return { path, a, b };
+  }
+
+  const aIsArr = Array.isArray(a);
+  const bIsArr = Array.isArray(b);
+  if (aIsArr !== bIsArr) return { path, a, b };
+
+  if (aIsArr) {
+    if (a.length !== b.length) {
+      return { path: `${path}.length`, a: a.length, b: b.length };
+    }
+    for (let i = 0; i < a.length; i++) {
+      const d = firstDivergence(a[i], b[i], `${path}[${i}]`);
+      if (d) return d;
+    }
+    return null;
+  }
+
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    const d = firstDivergence(a[k], b[k], `${path}.${k}`);
+    if (d) return d;
+  }
+  return null;
+}
diff --git a/packages/prosemirror-markdown/test/roundtrip.test.ts b/packages/prosemirror-markdown/test/roundtrip.test.ts
new file mode 100644
index 00000000..62db34b3
--- /dev/null
+++ b/packages/prosemirror-markdown/test/roundtrip.test.ts
@@ -0,0 +1,168 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+} from 'docmost-client';
+// Import canonical-equality DIRECTLY from src so we exercise the real
+// implementation alongside the converter pair above (the barrel re-exports the
+// same symbol; importing from src keeps these round-trip assertions pinned to
+// the package source rather than the published surface).
+import { docsCanonicallyEqual } from '../src/lib/canonicalize.js';
+
+// Resolve the fixture relative to this test file so the test is CWD-independent.
+const here = dirname(fileURLToPath(import.meta.url));
+const FIXTURE = join(here, 'fixtures', 'sample-doc.json');
+
+describe('round-trip idempotency (SPEC §11)', () => {
+  it('markdown is byte-stable across export -> import -> export', async () => {
+    const doc = JSON.parse(await readFile(FIXTURE, 'utf8'));
+
+    // export -> import -> export
+    const md1 = convertProseMirrorToMarkdown(doc);
+    const doc2 = await markdownToProseMirror(md1);
+    const md2 = convertProseMirrorToMarkdown(doc2);
+
+    // The property git actually needs: a second export reproduces the first
+    // byte-for-byte. We intentionally do NOT deep-equal doc vs doc2 — the
+    // converter reconstructs schema default attrs (e.g. indent:null), a known
+    // SPEC §11 divergence that does not affect markdown stability.
+    expect(md2).toBe(md1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full export -> import -> export round-trips for the schema's HTML-carried
+// atoms/blocks (math, mention, details). The existing markdown-converter unit
+// tests only assert the one-way emit string; here we additionally pin that the
+// re-import (generateJSON via the docmost schema) rebuilds the correct node and
+// that a second export reproduces the first byte-for-byte. Helpers mirror the
+// converter unit tests (a single-node doc renders exactly that node, trimmed).
+// ---------------------------------------------------------------------------
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string) => ({ type: 'text', text: t });
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// Run the canonical export -> import -> export cycle for a single block node.
+async function roundTrip(
+  node: any,
+): Promise<{ md1: string; doc2: any; md2: string }> {
+  const md1 = convertProseMirrorToMarkdown(doc(node));
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, doc2, md2 };
+}
+
+describe('math round-trip (mathBlock + mathInline)', () => {
+  it('mathBlock survives export -> import -> export with LaTeX recovered', async () => {
+    const source = { type: 'mathBlock', attrs: { text: 'a^2+b^2' } };
+    const { md1, doc2, md2 } = await roundTrip(source);
+
+    // One-way emit: LaTeX rides in the `text` HTML attribute, data-katex flag set.
+    expect(md1).toBe(
+      '<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>',
+    );
+    // Byte-stable: the second export reproduces the first exactly.
+    expect(md2).toBe(md1);
+
+    // The re-imported doc's only block is a mathBlock whose LaTeX was recovered
+    // from the text= attribute by the schema's default parser.
+    const block = doc2.content[0];
+    expect(block.type).toBe('mathBlock');
+    expect(block.attrs.text).toBe('a^2+b^2');
+
+    // Canonical equality: source and re-imported doc are the same node.
+    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
+  });
+
+  it('mathInline (inside a paragraph) survives export -> import -> export', async () => {
+    const source = para({ type: 'mathInline', attrs: { text: 'x_i' } });
+    const { md1, doc2, md2 } = await roundTrip(source);
+
+    expect(md1).toBe(
+      '<span data-type="mathInline" data-katex="true" text="x_i"></span>',
+    );
+    expect(md2).toBe(md1);
+
+    // The re-imported paragraph's child is a mathInline with the LaTeX recovered.
+    const paragraph = doc2.content[0];
+    expect(paragraph.type).toBe('paragraph');
+    const inline = paragraph.content[0];
+    expect(inline.type).toBe('mathInline');
+    expect(inline.attrs.text).toBe('x_i');
+
+    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
+  });
+});
+
+describe('mention round-trip', () => {
+  it('mention survives export -> import -> export with data-* re-parsed', async () => {
+    const source = para({
+      type: 'mention',
+      attrs: { id: 'u1', label: 'Alice', entityType: 'user' },
+    });
+    const { md1, doc2, md2 } = await roundTrip(source);
+
+    // One-way emit: schema span with data-* attrs and the visible '@Alice' text.
+    expect(md1).toBe(
+      '<span data-type="mention" data-id="u1" data-label="Alice" data-entity-type="user">@Alice</span>',
+    );
+    // Byte-stable.
+    expect(md2).toBe(md1);
+
+    // The visible '@Alice' is cosmetic; generateJSON rebuilds a mention node from
+    // the data-* attributes. The unset attrs fall back to their schema defaults.
+    const paragraph = doc2.content[0];
+    expect(paragraph.type).toBe('paragraph');
+    const mention = paragraph.content[0];
+    expect(mention.type).toBe('mention');
+    expect(mention.attrs.id).toBe('u1');
+    expect(mention.attrs.label).toBe('Alice');
+    expect(mention.attrs.entityType).toBe('user');
+    expect(mention.attrs.entityId).toBeNull();
+    expect(mention.attrs.slugId).toBeNull();
+    expect(mention.attrs.creatorId).toBeNull();
+    expect(mention.attrs.anchorId).toBeNull();
+
+    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
+  });
+});
+
+describe('details open-attribute round-trip', () => {
+  it('the markdown details fence never carries an open flag and stays byte-stable', async () => {
+    // Source details is OPEN (attrs.open: ''), but the top-level markdown path
+    // emits a plain '<details>' fence (no 'open' attribute) — see converter
+    // case "detailsSummary" which hardcodes '<details>\n<summary>...'.
+    const source = {
+      type: 'details',
+      attrs: { open: '' },
+      content: [
+        { type: 'detailsSummary', content: [text('S')] },
+        { type: 'detailsContent', content: [para(text('body'))] },
+      ],
+    };
+    const { md1, doc2, md2 } = await roundTrip(source);
+
+    // The emitted fence drops the open flag entirely.
+    expect(md1).toBe('<details>\n<summary>S</summary>\n\nbody\n</details>');
+    expect(md1).not.toContain('open');
+
+    // Byte-stable: re-export reproduces the same fence.
+    expect(md2).toBe(md1);
+
+    // NOTE(review): the spec text says doc2's details attrs.open should be
+    // `null` (the raw return of el.getAttribute('open') on a plain <details>,
+    // schema src ~L438). In practice generateJSON applies the schema attribute
+    // default when the parseHTML result is null, so the materialised node carries
+    // attrs.open === false (the declared default at src ~L437), NOT null. We
+    // assert the ACTUAL value. The load-bearing point of the spec still holds:
+    // a plain <details> import does NOT recover the open flag (no truthy value),
+    // so renderHTML's `attrs.open ? {open:''} : {}` keeps the round-trip clean.
+    const details = doc2.content[0];
+    expect(details.type).toBe('details');
+    expect(details.attrs.open).toBe(false);
+    expect(details.attrs.open).toBeFalsy();
+  });
+});
diff --git a/packages/prosemirror-markdown/test/schema-editor-ext-contract.test.ts b/packages/prosemirror-markdown/test/schema-editor-ext-contract.test.ts
new file mode 100644
index 00000000..4778ea5c
--- /dev/null
+++ b/packages/prosemirror-markdown/test/schema-editor-ext-contract.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { getSchema } from "@tiptap/core";
+
+import { docmostExtensions } from "../src/lib/docmost-schema.js";
+import * as editorExt from "@docmost/editor-ext";
+
+// CROSS-PACKAGE SCHEMA CONTRACT (data-loss-sensitive).
+//
+// `src/lib/docmost-schema.ts` is a hand-synced VENDORED MIRROR of the canonical
+// Docmost schema in `@docmost/editor-ext`. The sibling `schema-surface-snapshot`
+// test pins the mirror's FULL surface (names + attrs) against an inline
+// reference, but that reference is hand-curated and does not mechanically tie to
+// editor-ext. This test closes that gap from the other side: it reads the ACTUAL
+// Tiptap node/mark definitions exported by `@docmost/editor-ext` and asserts the
+// vendored mirror is a SUPERSET of their type NAMES — so a Docmost-specific node
+// or mark added upstream that the mirror forgets to vendor fails CI loudly
+// (otherwise it is silently dropped on the markdown <-> ProseMirror round-trip).
+//
+// LIMITATION (intentional, see schema-surface-snapshot.test.ts): this is a
+// NAME-LEVEL contract only, not a full attribute-level structural compare.
+// editor-ext's Tiptap representation (node views, commands, suggestion plugins,
+// addGlobalAttributes spread across separate extensions) differs from this
+// minimal mirror, so a mechanical attribute-by-attribute equality would be
+// fragile and produce false drift. Attribute parity is guarded by the inline
+// surface snapshot (reviewed in every diff); this test guards that no canonical
+// node/mark TYPE goes unmirrored. StarterKit-provided types (paragraph, bold,
+// heading, …) are contributed by @tiptap/starter-kit in the mirror rather than
+// by editor-ext, so they are naturally covered by the mirror's superset.
+//
+// NOT COVERED here (deferred): (1) the THIRD copy in `packages/mcp` — a separate
+// package guarded by its own surface snapshot; (2) attribute *behaviour* drift,
+// e.g. the details `open` attr read via getAttribute vs hasAttribute (PR #119
+// review #2) — a name-level compare cannot see parseHTML/renderHTML differences.
+// Mechanically guarding behavioural parity across all THREE copies needs the
+// single framework-free "schema core" refactor (deferred — see AGENTS.md); until
+// then each copy's header carries the manual keep-in-sync requirement.
+
+/** Tiptap Node/Mark instances expose a `.name` and a `.type` of 'node'|'mark'. */
+function isTiptapNodeOrMark(
+  value: unknown,
+): value is { name: string; type: "node" | "mark" } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "name" in value &&
+    typeof (value as { name: unknown }).name === "string" &&
+    "type" in value &&
+    ((value as { type: unknown }).type === "node" ||
+      (value as { type: unknown }).type === "mark")
+  );
+}
+
+/** The set of node/mark type names the vendored mirror actually registers. */
+function vendoredNames(): Set<string> {
+  const schema = getSchema(docmostExtensions as never);
+  return new Set([
+    ...Object.keys(schema.nodes),
+    ...Object.keys(schema.marks),
+  ]);
+}
+
+/** The Docmost-specific node/mark type names exported by @docmost/editor-ext. */
+function editorExtNames(): Set<string> {
+  const names = new Set<string>();
+  for (const value of Object.values(editorExt)) {
+    if (isTiptapNodeOrMark(value)) names.add(value.name);
+  }
+  return names;
+}
+
+describe("docmost schema vs @docmost/editor-ext (name-level contract)", () => {
+  it("exposes Tiptap node/mark definitions from editor-ext (guards against the import going dark)", () => {
+    // If editor-ext ever stops exporting concrete node/mark objects (e.g. a
+    // barrel refactor), this contract would vacuously pass — assert it found a
+    // meaningful set so the test cannot silently become a no-op.
+    expect(editorExtNames().size).toBeGreaterThan(5);
+  });
+
+  it("vendors every Docmost-specific node/mark type defined in editor-ext (no silently-dropped types)", () => {
+    const vendored = vendoredNames();
+    const missing = [...editorExtNames()].filter((n) => !vendored.has(n)).sort();
+    // missing must be empty: any name here exists in editor-ext but NOT in the
+    // vendored mirror, so documents using it would lose that node/mark on a
+    // git-sync round-trip. Re-sync src/lib/docmost-schema.ts before clearing.
+    expect(missing).toEqual([]);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/schema-surface-snapshot.test.ts b/packages/prosemirror-markdown/test/schema-surface-snapshot.test.ts
new file mode 100644
index 00000000..f6d4b748
--- /dev/null
+++ b/packages/prosemirror-markdown/test/schema-surface-snapshot.test.ts
@@ -0,0 +1,125 @@
+import { describe, it, expect } from "vitest";
+import { getSchema } from "@tiptap/core";
+
+import { docmostExtensions } from "../src/lib/docmost-schema.js";
+
+// SCHEMA-DRIFT GUARD (must-review gate).
+//
+// `src/lib/docmost-schema.ts` is a VENDORED MIRROR of the canonical Docmost
+// document schema defined in `@docmost/editor-ext`. git-sync uses it to convert
+// pages to/from ProseMirror JSON; any node, mark, or attribute that exists in
+// the canonical schema but is missing here is silently dropped on a round-trip
+// (data loss). The reverse — a node/mark/attr here that no longer exists in the
+// canonical schema — is dead surface that can mask drift.
+//
+// This test derives a stable, sorted "schema surface" (every node/mark name and
+// its sorted attribute keys) and pins it against an INLINE expected constant.
+// It is intentionally a LOUD must-review gate rather than an automatic
+// editor-ext diff: editor-ext's Tiptap representation differs from this
+// vendored copy, so a cross-representation compare would be fragile. We do NOT
+// use toMatchSnapshot so the reference lives in this file and is reviewed in the
+// diff of every change.
+//
+// WHEN THIS TEST FAILS: do NOT blindly update `expectedSurface`. First confirm
+// the change matches `@docmost/editor-ext` (the canonical schema) so the
+// markdown <-> ProseMirror round-trip stays lossless, THEN copy the new surface
+// into the expected constant below.
+
+interface SurfaceEntry {
+  name: string;
+  kind: "node" | "mark";
+  attrs: string[];
+}
+
+/** Derive the deterministic schema surface from the vendored extension set. */
+function deriveSurface(): SurfaceEntry[] {
+  const schema = getSchema(docmostExtensions as never);
+  const surface: SurfaceEntry[] = [];
+  for (const [name, type] of Object.entries(schema.nodes)) {
+    surface.push({
+      name,
+      kind: "node",
+      attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
+    });
+  }
+  for (const [name, type] of Object.entries(schema.marks)) {
+    surface.push({
+      name,
+      kind: "mark",
+      attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
+    });
+  }
+  // Sort by name, then by kind, for a representation-independent ordering.
+  surface.sort((a, b) =>
+    a.name === b.name ? a.kind.localeCompare(b.kind) : a.name.localeCompare(b.name),
+  );
+  return surface;
+}
+
+// The committed reference surface. Built from the ACTUAL current schema; review
+// every change to this constant against `@docmost/editor-ext`.
+const expectedSurface: SurfaceEntry[] = [
+  { name: "attachment", kind: "node", attrs: ["attachmentId", "mime", "name", "placeholder", "size", "url"] },
+  { name: "audio", kind: "node", attrs: ["attachmentId", "placeholder", "size", "src"] },
+  { name: "blockquote", kind: "node", attrs: [] },
+  { name: "bold", kind: "mark", attrs: [] },
+  { name: "bulletList", kind: "node", attrs: [] },
+  { name: "callout", kind: "node", attrs: ["icon", "type"] },
+  { name: "code", kind: "mark", attrs: [] },
+  { name: "codeBlock", kind: "node", attrs: ["language"] },
+  { name: "column", kind: "node", attrs: ["width"] },
+  { name: "columns", kind: "node", attrs: ["layout", "widthMode"] },
+  { name: "comment", kind: "mark", attrs: ["commentId", "resolved"] },
+  { name: "details", kind: "node", attrs: ["open"] },
+  { name: "detailsContent", kind: "node", attrs: [] },
+  { name: "detailsSummary", kind: "node", attrs: [] },
+  { name: "doc", kind: "node", attrs: [] },
+  { name: "drawio", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
+  { name: "embed", kind: "node", attrs: ["align", "height", "provider", "src", "width"] },
+  { name: "excalidraw", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
+  { name: "footnoteDefinition", kind: "node", attrs: ["id"] },
+  { name: "footnoteReference", kind: "node", attrs: ["id"] },
+  { name: "footnotesList", kind: "node", attrs: [] },
+  { name: "hardBreak", kind: "node", attrs: [] },
+  { name: "heading", kind: "node", attrs: ["id", "indent", "level", "textAlign"] },
+  { name: "highlight", kind: "mark", attrs: ["color"] },
+  { name: "horizontalRule", kind: "node", attrs: [] },
+  { name: "htmlEmbed", kind: "node", attrs: ["height", "source"] },
+  { name: "image", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "caption", "height", "placeholder", "size", "src", "title", "width"] },
+  { name: "italic", kind: "mark", attrs: [] },
+  { name: "link", kind: "mark", attrs: ["class", "href", "internal", "rel", "target", "title"] },
+  { name: "listItem", kind: "node", attrs: [] },
+  { name: "mathBlock", kind: "node", attrs: ["text"] },
+  { name: "mathInline", kind: "node", attrs: ["text"] },
+  { name: "mention", kind: "node", attrs: ["anchorId", "creatorId", "entityId", "entityType", "id", "label", "slugId"] },
+  { name: "orderedList", kind: "node", attrs: ["start", "type"] },
+  { name: "pageBreak", kind: "node", attrs: [] },
+  { name: "pageEmbed", kind: "node", attrs: ["sourcePageId"] },
+  { name: "paragraph", kind: "node", attrs: ["id", "indent", "textAlign"] },
+  { name: "pdf", kind: "node", attrs: ["attachmentId", "height", "name", "placeholder", "size", "src", "width"] },
+  { name: "spoiler", kind: "mark", attrs: [] },
+  { name: "status", kind: "node", attrs: ["color", "text"] },
+  { name: "strike", kind: "mark", attrs: [] },
+  { name: "subpages", kind: "node", attrs: ["recursive"] },
+  { name: "subscript", kind: "mark", attrs: [] },
+  { name: "superscript", kind: "mark", attrs: [] },
+  { name: "table", kind: "node", attrs: [] },
+  { name: "tableCell", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
+  { name: "tableHeader", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
+  { name: "tableRow", kind: "node", attrs: [] },
+  { name: "taskItem", kind: "node", attrs: ["checked"] },
+  { name: "taskList", kind: "node", attrs: [] },
+  { name: "text", kind: "node", attrs: [] },
+  { name: "textStyle", kind: "mark", attrs: ["color"] },
+  { name: "transclusionReference", kind: "node", attrs: ["sourcePageId", "transclusionId"] },
+  { name: "transclusionSource", kind: "node", attrs: ["id"] },
+  { name: "underline", kind: "mark", attrs: [] },
+  { name: "video", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "placeholder", "size", "src", "width"] },
+  { name: "youtube", kind: "node", attrs: ["align", "height", "src", "width"] },
+];
+
+describe("docmost schema surface", () => {
+  it("matches the committed reference surface (re-verify against @docmost/editor-ext on change)", () => {
+    expect(deriveSurface()).toEqual(expectedSurface);
+  });
+});
diff --git a/packages/prosemirror-markdown/tsconfig.json b/packages/prosemirror-markdown/tsconfig.json
new file mode 100644
index 00000000..c58cbd9d
--- /dev/null
+++ b/packages/prosemirror-markdown/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}
diff --git a/packages/prosemirror-markdown/tsconfig.vitest.json b/packages/prosemirror-markdown/tsconfig.vitest.json
new file mode 100644
index 00000000..5a116942
--- /dev/null
+++ b/packages/prosemirror-markdown/tsconfig.vitest.json
@@ -0,0 +1,15 @@
+{
+  // Test-infra tsconfig used ONLY by vitest's `test.typecheck` pass (Finding #1).
+  // The build tsconfig (`tsconfig.json`) scopes the compiler to `src/**` with
+  // `rootDir: ./src`, so it never type-checks the `test/` tree. This config
+  // inherits the same strict compiler options but widens the file set to the
+  // type-test files so `vitest run` can run `tsc` over them. It is NOT used by
+  // `npm run build` (that still uses `tsconfig.json`), so it has no effect on the
+  // shipped output.
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["test/**/*.test-d.ts", "src/**/*"]
+}
diff --git a/packages/prosemirror-markdown/vitest.config.ts b/packages/prosemirror-markdown/vitest.config.ts
new file mode 100644
index 00000000..1c63f4e3
--- /dev/null
+++ b/packages/prosemirror-markdown/vitest.config.ts
@@ -0,0 +1,40 @@
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { defineConfig } from 'vitest/config';
+
+// Ported docmost-sync tests import the converter through the upstream package
+// barrel specifier `docmost-client`. We vendored only the PURE half of that
+// package into `src/lib`, so alias the barrel specifier to our local lib
+// barrel; everything those tests use (converter, canonicalize, markdown
+// envelope, markdownToProseMirror) is re-exported there.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const libBarrel = path.resolve(here, 'src/lib/index.ts');
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      'docmost-client': libBarrel,
+    },
+  },
+  test: {
+    environment: 'node',
+    // Runtime suites. The `.test.ts` glob deliberately EXCLUDES the type-only
+    // contract file (`*.test-d.ts`), which is enforced by the typecheck pass
+    // below instead — so the 35 runtime suites are never typechecked.
+    include: ['test/**/*.test.ts'],
+    // Type-level contract enforcement (Finding #1). Vitest runs `tsc` over the
+    // `.test-d.ts` files so the `expectTypeOf`/`@ts-expect-error` guards in
+    // git-sync-client.contract.test-d.ts become REAL build-time assertions: a
+    // drift in the GitSyncClient result shapes makes `npx vitest run` FAIL with
+    // a type error. Scoped to `*.test-d.ts` so the runtime suites stay
+    // untouched, and pointed at the package tsconfig for the strict options.
+    typecheck: {
+      enabled: true,
+      include: ['test/**/*.test-d.ts'],
+      // A dedicated test-infra tsconfig (NOT the build one) that widens the file
+      // set to include `test/**` — the build tsconfig scopes `tsc` to `src/**`
+      // (rootDir ./src), so without this the type-test file is never checked.
+      tsconfig: './tsconfig.vitest.json',
+    },
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7540bafe..cffcd8d0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1030,6 +1030,67 @@ importers:
         specifier: ^5.0.0
         version: 5.9.3
 
+  packages/prosemirror-markdown:
+    dependencies:
+      '@tiptap/core':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/pm@3.20.4)
+      '@tiptap/extension-highlight':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))
+      '@tiptap/extension-image':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))
+      '@tiptap/extension-subscript':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)
+      '@tiptap/extension-superscript':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)
+      '@tiptap/extension-task-item':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/extension-list@3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4))
+      '@tiptap/extension-task-list':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/extension-list@3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4))
+      '@tiptap/html':
+        specifier: 3.20.4
+        version: 3.20.4(@tiptap/core@3.20.4(@tiptap/pm@3.20.4))(@tiptap/pm@3.20.4)(happy-dom@20.8.9)
+      '@tiptap/pm':
+        specifier: 3.20.4
+        version: 3.20.4
+      '@tiptap/starter-kit':
+        specifier: 3.20.4
+        version: 3.20.4
+      jsdom:
+        specifier: 25.0.0
+        version: 25.0.0
+      marked:
+        specifier: 17.0.5
+        version: 17.0.5
+      zod:
+        specifier: 4.3.6
+        version: 4.3.6
+    devDependencies:
+      '@docmost/editor-ext':
+        specifier: workspace:*
+        version: link:../editor-ext
+      '@types/jsdom':
+        specifier: ^21.1.7
+        version: 21.1.7
+      '@types/node':
+        specifier: ^20.0.0
+        version: 20.19.43
+      fast-check:
+        specifier: ^4.8.0
+        version: 4.8.0
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+      vitest:
+        specifier: 4.1.6
+        version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@20.19.43)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@20.19.43)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
+
 packages:
 
   '@aashutoshrathi/word-wrap@1.2.6':
-- 
2.52.0


From 6dcc19ce5933980d40eac5d300c933c31970f600 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 07:18:44 +0300
Subject: [PATCH 02/17] refactor(git-sync): consume
 @docmost/prosemirror-markdown, drop the duplicate lib (#293 stage 3 / no-op)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git-sync's converter-core (src/lib) was a byte-identical duplicate of the new
@docmost/prosemirror-markdown package (created in the previous commit). Switch
git-sync to consume the package and delete its copy — ending the duplication
that the whole #293 effort targets. Pure no-op: NO format/behavior change.

- git-sync depends on @docmost/prosemirror-markdown (workspace:*); engine
  (stabilize/push/pull) + src/index barrel + 12 engine tests re-point their
  converter imports to the package.
- Delete git-sync/src/lib (8 files) and the 23 duplicate converter-core test
  files + their fixtures — the converter and its ~440 tests now live once, in the
  package. git-sync keeps only its ENGINE tests, which exercise the converter
  through the package (the no-op proof). Kept roundtrip-helpers.ts (an engine
  test imports firstDivergence from it; pure helper, no double-run).
- Added docmostExtensions to the package barrel (a kept engine schema-validity
  test needs it).

Verified: editor-ext + prosemirror-markdown + git-sync all tsc EXIT 0;
git-sync vitest 28 files, 268 passed, 0 failures (engine cycle/roundtrip/push/
pull/reconcile green = no-op proof); prosemirror-markdown vitest still 443 passed
| 1 expected-fail; pnpm --frozen-lockfile EXIT 0; no ../lib refs remain in git-sync.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |    2 +-
 packages/git-sync/package.json                |    1 +
 packages/git-sync/src/engine/pull.ts          |    2 +-
 packages/git-sync/src/engine/push.ts          |    7 +-
 packages/git-sync/src/engine/stabilize.ts     |    2 +-
 packages/git-sync/src/index.ts                |   10 +-
 packages/git-sync/src/lib/canonicalize.ts     |  247 ---
 packages/git-sync/src/lib/docmost-schema.ts   | 1544 -----------------
 packages/git-sync/src/lib/index.ts            |   26 -
 .../git-sync/src/lib/markdown-converter.ts    | 1130 ------------
 .../git-sync/src/lib/markdown-document.ts     |  154 --
 .../src/lib/markdown-to-prosemirror.ts        |  365 ----
 packages/git-sync/src/lib/node-ops.ts         |  897 ----------
 packages/git-sync/src/lib/page-file.ts        |   81 -
 .../git-sync/test/apply-push-actions.test.ts  |    2 +-
 .../git-sync/test/canonicalize-extra.test.ts  |  205 ---
 packages/git-sync/test/canonicalize.test.ts   |  302 ----
 .../test/classify-rename-moves.test.ts        |    2 +-
 .../test/compute-push-actions.test.ts         |    2 +-
 .../git-sync/test/cycle-roundtrip.test.ts     |    2 +-
 .../git-sync/test/diagram-roundtrip.test.ts   |  109 --
 .../test/docmost-schema-attrs.test.ts         |  124 --
 packages/git-sync/test/engine-gaps.test.ts    |    2 +-
 .../corpus/01-headings-paragraphs.json        |   36 -
 .../test/fixtures/corpus/02-inline-marks.json |   62 -
 .../test/fixtures/corpus/03-lists.json        |  113 --
 .../test/fixtures/corpus/04-blocks.json       |   38 -
 .../test/fixtures/corpus/05-table.json        |   85 -
 .../test/fixtures/corpus/06-diagrams.json     |   17 -
 .../fixtures/corpus/07-textstyle-mention.json |   35 -
 .../test/fixtures/corpus/08-details.json      |   15 -
 .../test/fixtures/corpus/09-columns.json      |   17 -
 .../corpus/10-mention-in-heading.json         |   13 -
 .../known-limitations/image-diagrams.json     |   21 -
 .../git-sync/test/fixtures/sample-doc.json    |  151 --
 .../test/markdown-converter-gaps.test.ts      |  845 ---------
 .../test/markdown-converter-golden.test.ts    |  402 -----
 .../markdown-converter-html-marks.test.ts     |  223 ---
 .../git-sync/test/markdown-converter.test.ts  |  645 -------
 .../test/markdown-document-envelope.test.ts   |  218 ---
 .../git-sync/test/markdown-document.test.ts   |   66 -
 ...markdown-roundtrip-spoiler-caption.test.ts |  129 --
 .../test/markdown-roundtrip.property.test.ts  |  698 --------
 .../test/markdown-to-prosemirror-gaps.test.ts |  535 ------
 .../git-sync/test/media-roundtrip.test.ts     |  275 ---
 packages/git-sync/test/node-ops-extra.test.ts |  268 ---
 packages/git-sync/test/node-ops.test.ts       |  908 ----------
 packages/git-sync/test/page-file.test.ts      |   33 -
 packages/git-sync/test/read-existing.test.ts  |    2 +-
 .../git-sync/test/redteam-converter.test.ts   |   89 -
 .../test/redteam-layout-title.test.ts         |    2 +-
 .../git-sync/test/redteam-push-cycle.test.ts  |    2 +-
 .../git-sync/test/roundtrip-all-nodes.test.ts |  297 ----
 .../git-sync/test/roundtrip-corpus.test.ts    |  104 --
 packages/git-sync/test/roundtrip.test.ts      |  168 --
 .../git-sync/test/run-push-realgit.test.ts    |    2 +-
 packages/git-sync/test/run-push.test.ts       |    2 +-
 .../test/schema-editor-ext-contract.test.ts   |   87 -
 .../test/schema-surface-snapshot.test.ts      |  125 --
 packages/git-sync/test/stabilize.test.ts      |    4 +-
 .../strip-empty-paragraphs-validity.test.ts   |    4 +-
 .../prosemirror-markdown/src/lib/index.ts     |    5 +
 pnpm-lock.yaml                                |    3 +
 63 files changed, 38 insertions(+), 11924 deletions(-)
 delete mode 100644 packages/git-sync/src/lib/canonicalize.ts
 delete mode 100644 packages/git-sync/src/lib/docmost-schema.ts
 delete mode 100644 packages/git-sync/src/lib/index.ts
 delete mode 100644 packages/git-sync/src/lib/markdown-converter.ts
 delete mode 100644 packages/git-sync/src/lib/markdown-document.ts
 delete mode 100644 packages/git-sync/src/lib/markdown-to-prosemirror.ts
 delete mode 100644 packages/git-sync/src/lib/node-ops.ts
 delete mode 100644 packages/git-sync/src/lib/page-file.ts
 delete mode 100644 packages/git-sync/test/canonicalize-extra.test.ts
 delete mode 100644 packages/git-sync/test/canonicalize.test.ts
 delete mode 100644 packages/git-sync/test/diagram-roundtrip.test.ts
 delete mode 100644 packages/git-sync/test/docmost-schema-attrs.test.ts
 delete mode 100644 packages/git-sync/test/fixtures/corpus/01-headings-paragraphs.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/02-inline-marks.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/03-lists.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/04-blocks.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/05-table.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/06-diagrams.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/07-textstyle-mention.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/08-details.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/09-columns.json
 delete mode 100644 packages/git-sync/test/fixtures/corpus/10-mention-in-heading.json
 delete mode 100644 packages/git-sync/test/fixtures/known-limitations/image-diagrams.json
 delete mode 100644 packages/git-sync/test/fixtures/sample-doc.json
 delete mode 100644 packages/git-sync/test/markdown-converter-gaps.test.ts
 delete mode 100644 packages/git-sync/test/markdown-converter-golden.test.ts
 delete mode 100644 packages/git-sync/test/markdown-converter-html-marks.test.ts
 delete mode 100644 packages/git-sync/test/markdown-converter.test.ts
 delete mode 100644 packages/git-sync/test/markdown-document-envelope.test.ts
 delete mode 100644 packages/git-sync/test/markdown-document.test.ts
 delete mode 100644 packages/git-sync/test/markdown-roundtrip-spoiler-caption.test.ts
 delete mode 100644 packages/git-sync/test/markdown-roundtrip.property.test.ts
 delete mode 100644 packages/git-sync/test/markdown-to-prosemirror-gaps.test.ts
 delete mode 100644 packages/git-sync/test/media-roundtrip.test.ts
 delete mode 100644 packages/git-sync/test/node-ops-extra.test.ts
 delete mode 100644 packages/git-sync/test/node-ops.test.ts
 delete mode 100644 packages/git-sync/test/page-file.test.ts
 delete mode 100644 packages/git-sync/test/redteam-converter.test.ts
 delete mode 100644 packages/git-sync/test/roundtrip-all-nodes.test.ts
 delete mode 100644 packages/git-sync/test/roundtrip-corpus.test.ts
 delete mode 100644 packages/git-sync/test/roundtrip.test.ts
 delete mode 100644 packages/git-sync/test/schema-editor-ext-contract.test.ts
 delete mode 100644 packages/git-sync/test/schema-surface-snapshot.test.ts

diff --git a/.gitignore b/.gitignore
index 2619e48e..6db827eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,7 @@
 data
 # compiled output
 /dist
-node_modules/
+node_modules
 
 # git-sync compiled output (built in CI/Docker via `pnpm build`, never committed,
 # so src/ and prod can never silently diverge).
diff --git a/packages/git-sync/package.json b/packages/git-sync/package.json
index cce08975..251725c5 100644
--- a/packages/git-sync/package.json
+++ b/packages/git-sync/package.json
@@ -20,6 +20,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@docmost/prosemirror-markdown": "workspace:*",
     "@tiptap/core": "3.20.4",
     "@tiptap/extension-highlight": "3.20.4",
     "@tiptap/extension-image": "3.20.4",
diff --git a/packages/git-sync/src/engine/pull.ts b/packages/git-sync/src/engine/pull.ts
index b541c67a..3d7868d5 100644
--- a/packages/git-sync/src/engine/pull.ts
+++ b/packages/git-sync/src/engine/pull.ts
@@ -31,7 +31,7 @@
  */
 import { dirname } from "node:path";
 import { sep } from "node:path";
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import { parsePageFile, serializePageFile } from "@docmost/prosemirror-markdown";
 import type { GitSyncClient } from "./client.types.js";
 import { buildVaultLayout, type PageNode } from "./layout.js";
 import {
diff --git a/packages/git-sync/src/engine/push.ts b/packages/git-sync/src/engine/push.ts
index 63d28530..903931be 100644
--- a/packages/git-sync/src/engine/push.ts
+++ b/packages/git-sync/src/engine/push.ts
@@ -26,8 +26,11 @@
  * the gitmost server drives the engine in-process (there is no standalone CLI
  * entry point).
  */
-import { type DocmostMdMeta } from "../lib/index.js";
-import { parsePageFile, serializePageFile } from "../lib/page-file.js";
+import {
+  type DocmostMdMeta,
+  parsePageFile,
+  serializePageFile,
+} from "@docmost/prosemirror-markdown";
 import type { GitSyncClient } from "./client.types.js";
 import type { DiffEntry } from "./git.js";
 import { VaultGit, DEFAULT_BRANCH } from "./git.js";
diff --git a/packages/git-sync/src/engine/stabilize.ts b/packages/git-sync/src/engine/stabilize.ts
index a075b634..ce1acdcf 100644
--- a/packages/git-sync/src/engine/stabilize.ts
+++ b/packages/git-sync/src/engine/stabilize.ts
@@ -17,7 +17,7 @@ import {
   markdownToProseMirror,
   serializeDocmostMarkdownBody,
   type DocmostMdMeta,
-} from "../lib/index.js";
+} from "@docmost/prosemirror-markdown";
 
 /**
  * Meta object as `exportPageBody` builds it (SPEC §4). Kept byte-for-byte
diff --git a/packages/git-sync/src/index.ts b/packages/git-sync/src/index.ts
index a52ca8d3..8c9e87eb 100644
--- a/packages/git-sync/src/index.ts
+++ b/packages/git-sync/src/index.ts
@@ -8,6 +8,10 @@
  */
 
 // Pure converter (markdown <-> ProseMirror, file envelope, canonicalization).
+// Re-exported from the standalone `@docmost/prosemirror-markdown` package,
+// which is the single source of truth for the converter core; git-sync keeps
+// only the engine (vault/git/orchestrator) and re-surfaces the converter for
+// in-process consumers of the git-sync barrel.
 export {
   serializeDocmostMarkdown,
   serializeDocmostMarkdownBody,
@@ -16,8 +20,8 @@ export {
   markdownToProseMirror,
   canonicalizeContent,
   docsCanonicallyEqual,
-} from "./lib/index.js";
-export type { DocmostMdMeta } from "./lib/index.js";
+} from "@docmost/prosemirror-markdown";
+export type { DocmostMdMeta } from "@docmost/prosemirror-markdown";
 
 // Pure engine (no IO): reconcile planner, vault layout, sanitize, stabilize,
 // loop-guard body hash.
@@ -123,4 +127,4 @@ export {
 } from "./engine/path-guard.js";
 export type { PathGuardIo, VaultPathUnsafeReason } from "./engine/path-guard.js";
 
-export { parsePageFile, serializePageFile } from "./lib/page-file.js";
+export { parsePageFile, serializePageFile } from "@docmost/prosemirror-markdown";
diff --git a/packages/git-sync/src/lib/canonicalize.ts b/packages/git-sync/src/lib/canonicalize.ts
deleted file mode 100644
index 99ff5bc6..00000000
--- a/packages/git-sync/src/lib/canonicalize.ts
+++ /dev/null
@@ -1,247 +0,0 @@
-/**
- * Semantic canonicalization of ProseMirror/TipTap documents for the round-trip
- * idempotency check (SPEC §11, "Task #0", option (b): compare a CANONICALIZED
- * form rather than raw bytes).
- *
- * `markdownToProseMirror` reconstructs schema DEFAULT attributes (e.g.
- * `indent: null` where the source omitted it) and regenerates per-block ids on
- * every import. A raw deep-equal of the source doc against the re-imported doc
- * therefore diverges even when the two are semantically identical. This module
- * normalizes a document so that two semantically-equal docs compare deep-equal
- * regardless of block ids and absent-vs-explicit-default-null attributes.
- *
- * It is a self-contained module with no external dependencies.
- */
-
-/**
- * Known NON-NULL schema defaults that `markdownToProseMirror` materializes on
- * import, keyed by node/mark type → { attr: defaultValue }.
- *
- * Why this exists: `canonicalizeAttrs` already treats an absent attr as
- * equivalent to an explicit `null`/`undefined`. But several Docmost schema
- * attributes default to a NON-null value, so import fills them in even when the
- * source omitted them — making "attr absent" diverge from "attr at its default
- * value" under a raw deep-equal. To keep "absent ≡ explicit-default", we ALSO
- * drop any attr whose value equals its known schema default. A non-default
- * value (e.g. `orderedList.start: 5`) is NOT a default, so it is KEPT.
- *
- * Every entry below was read from `packages/docmost-client/src/lib/
- * docmost-schema.ts` (the line refs are the exact `default:` declarations) and
- * confirmed to be materialized by an export→import→export round-trip:
- *   - mark `link`    target / rel  — DocmostAttributes + StarterKit link.
- *       StarterKit's link extension defaults `target: "_blank"` and
- *       `rel: "noopener noreferrer nofollow"`; both materialize on import
- *       (empirically confirmed) even when the source had only `href`.
- *   - mark `comment` resolved      — docmost-schema.ts L213-214 (`default: false`).
- *   - node `orderedList` start     — provided by StarterKit's orderedList
- *       (`default: 1`); materializes on import (empirically confirmed).
- *   - node `drawio`/`excalidraw`/`video`/`youtube`/`embed` align — the diagram
- *       attribute set and the media nodes declare `align: { default: "center" }`
- *       (docmost-schema.ts L745-750 diagramAttributes; L564 video; L626 youtube;
- *       L667 embed). The diagram `align` is the one the round-trip materializes
- *       (docmost-schema.ts L745); the media/embed entries normalize the SAME
- *       `align` default for consistency. Note: this only normalizes `align` —
- *       full canonical stability of `embed` is separately limited by the
- *       converter coercing numeric `width`/`height` to strings, which is outside
- *       canonicalize's scope.
- *
- * NOTE: `image` has NO non-null align default — its `align` defaults to `null`
- * (docmost-schema.ts L174), so it is already handled by the null-drop rule and
- * is intentionally NOT listed here.
- */
-const KNOWN_DEFAULTS: Record<string, Record<string, unknown>> = {
-  // mark types
-  link: {
-    target: "_blank",
-    rel: "noopener noreferrer nofollow",
-  },
-  comment: {
-    resolved: false,
-  },
-  // node types
-  orderedList: {
-    start: 1,
-  },
-  drawio: {
-    align: "center",
-  },
-  excalidraw: {
-    align: "center",
-  },
-  video: {
-    align: "center",
-  },
-  youtube: {
-    align: "center",
-  },
-  embed: {
-    align: "center",
-  },
-};
-
-/**
- * Prune an `attrs` object in place on a fresh copy: drop keys whose value is
- * `null` or `undefined` (an absent attribute and an explicit default of `null`
- * are semantically equivalent here). Optionally also drop a node-level `id`
- * (block ids are regenerated on import, SPEC §11). ALSO drop any attr whose
- * value equals the node/mark `type`'s known NON-null schema default
- * (`KNOWN_DEFAULTS`), so "attr absent" ≡ "attr at its default value" — without
- * this, the import-materialized `link.target`/`comment.resolved`/
- * `orderedList.start`/diagram `align` defaults would be a phantom diff. Every
- * non-default attribute value is KEPT (level, language, src, href, commentId,
- * width, a non-default `start`/`align`, ...).
- *
- * Returns the pruned attrs object, or `undefined` if nothing meaningful is
- * left (so the caller can drop the `attrs` key entirely: `{attrs:{}}` ≡ no
- * attrs).
- */
-function canonicalizeAttrs(
-  attrs: Record<string, unknown>,
-  dropId: boolean,
-  type: string | undefined,
-): Record<string, unknown> | undefined {
-  const defaults = type ? KNOWN_DEFAULTS[type] : undefined;
-  const out: Record<string, unknown> = {};
-  // Stable key order so a JSON.stringify of the canonical form is comparable
-  // regardless of the input's key order.
-  for (const key of Object.keys(attrs).sort()) {
-    // Block ids are regenerated on import; drop them on NODE attrs only.
-    if (dropId && key === "id") continue;
-    const value = attrs[key];
-    // Absent ≡ explicit-default-null/undefined.
-    if (value === null || value === undefined) continue;
-    // Absent ≡ explicit known non-null default (e.g. link.target="_blank").
-    // A non-default value (e.g. orderedList.start=5) does NOT match, so it is
-    // kept. The `comment` mark's `commentId` is never a default, so it always
-    // survives (SPEC §3); only its `resolved: false` default is normalized away.
-    if (defaults && key in defaults && value === defaults[key]) continue;
-    out[key] = value;
-  }
-  return Object.keys(out).length > 0 ? out : undefined;
-}
-
-/**
- * Return a DEEP COPY of a ProseMirror node tree, canonicalized so that two
- * semantically-equal documents compare deep-equal. Rules (applied recursively
- * to the node, its `content`, and its `marks`):
- *
- *  1. Remove node-level `attrs.id` (regenerated on import). Mark attrs are NOT
- *     touched for `id` (marks carry no block id; only their meaningful attrs).
- *  2. In any `attrs` object (node OR mark) drop keys whose value is `null`/
- *     `undefined` (absent ≡ explicit default null) OR equals that node/mark
- *     type's known non-null schema default (absent ≡ explicit default).
- *     Keep every non-default value. The type is passed into the attrs
- *     normalizer so it can look up `KNOWN_DEFAULTS`.
- *  3. If an `attrs` object becomes empty after pruning, drop the `attrs` key.
- *  4. Preserve `marks` (including the `comment` mark and its `commentId` — a
- *     meaningful anchor per SPEC §3; never strip it).
- *  5. Preserve `text`, `type`, and `content` order exactly.
- *  6. Never mutate the input.
- */
-export function canonicalizeContent(node: any): any {
-  if (Array.isArray(node)) {
-    return node.map((child) => canonicalizeContent(child));
-  }
-  if (node === null || typeof node !== "object") {
-    // Primitive leaf (string/number/boolean/null): returned as-is.
-    return node;
-  }
-
-  // A node is a mark when it has a `type` but never carries block `content`
-  // and lives inside a `marks` array. We cannot tell from the node alone, so
-  // we distinguish at the recursion site: node `attrs` drop `id`, mark `attrs`
-  // do not. This is handled by passing a `dropId` flag down for the `attrs`
-  // key specifically (nodes) vs the `marks[].attrs` path (marks).
-  const out: Record<string, unknown> = {};
-  for (const key of Object.keys(node)) {
-    if (key === "attrs" && node.attrs && typeof node.attrs === "object") {
-      // Node-level attrs: drop the block id, null/undefined attrs, and any
-      // attr at this node type's known non-null schema default.
-      const canon = canonicalizeAttrs(
-        node.attrs as Record<string, unknown>,
-        true,
-        typeof node.type === "string" ? node.type : undefined,
-      );
-      if (canon !== undefined) out.attrs = canon;
-      // else: drop the `attrs` key entirely (rule 3).
-    } else if (key === "marks" && Array.isArray(node.marks)) {
-      // Marks: keep them all (incl. comment); canonicalize their attrs but do
-      // NOT drop `id` (a mark's `id` would be a meaningful attr, not a block
-      // id). An empty marks array is dropped so `marks:[]` ≡ no marks.
-      const marks = (node.marks as any[]).map((mark) => canonicalizeMark(mark));
-      if (marks.length > 0) out.marks = marks;
-    } else {
-      out[key] = canonicalizeContent(node[key]);
-    }
-  }
-  return out;
-}
-
-/**
- * Canonicalize a single mark: keep `type`, prune its `attrs` (null/undefined
- * AND known non-null defaults dropped, empty attrs removed) but NEVER drop a
- * mark's attribute as a "block id" — marks have no block id, only meaningful
- * attrs (href, commentId, color, level, ...). Meaningful NON-default attrs
- * survive (the `comment` mark's `commentId` is never a default, so it always
- * survives — SPEC §3); only known defaults like `link.target="_blank"`,
- * `link.rel="noopener…"` and `comment.resolved=false` are normalized away.
- */
-function canonicalizeMark(mark: any): any {
-  if (mark === null || typeof mark !== "object") return mark;
-  const out: Record<string, unknown> = {};
-  for (const key of Object.keys(mark)) {
-    if (key === "attrs" && mark.attrs && typeof mark.attrs === "object") {
-      const canon = canonicalizeAttrs(
-        mark.attrs as Record<string, unknown>,
-        false,
-        typeof mark.type === "string" ? mark.type : undefined,
-      );
-      if (canon !== undefined) out.attrs = canon;
-    } else {
-      out[key] = canonicalizeContent(mark[key]);
-    }
-  }
-  return out;
-}
-
-/**
- * Deep structural equality of two values that is key-order-insensitive.
- * Used to compare canonical forms. (`canonicalizeContent` already emits
- * `attrs` in a stable key order, but the top-level node keys preserve input
- * order, so we compare structurally rather than by string.)
- */
-function deepEqual(a: any, b: any): boolean {
-  if (a === b) return true;
-  if (typeof a !== typeof b) return false;
-  if (a === null || b === null) return a === b;
-  if (typeof a !== "object") return false;
-
-  const aIsArr = Array.isArray(a);
-  const bIsArr = Array.isArray(b);
-  if (aIsArr !== bIsArr) return false;
-
-  if (aIsArr) {
-    if (a.length !== b.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!deepEqual(a[i], b[i])) return false;
-    }
-    return true;
-  }
-
-  const aKeys = Object.keys(a);
-  const bKeys = Object.keys(b);
-  if (aKeys.length !== bKeys.length) return false;
-  for (const k of aKeys) {
-    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
-    if (!deepEqual(a[k], b[k])) return false;
-  }
-  return true;
-}
-
-/**
- * True when two ProseMirror documents are semantically equal: equal after
- * canonicalization (block ids stripped, absent-vs-default-null normalized).
- */
-export function docsCanonicallyEqual(a: any, b: any): boolean {
-  return deepEqual(canonicalizeContent(a), canonicalizeContent(b));
-}
diff --git a/packages/git-sync/src/lib/docmost-schema.ts b/packages/git-sync/src/lib/docmost-schema.ts
deleted file mode 100644
index 276efe90..00000000
--- a/packages/git-sync/src/lib/docmost-schema.ts
+++ /dev/null
@@ -1,1544 +0,0 @@
-/**
- * Full TipTap extension set matching the real Docmost document schema.
- *
- * The default StarterKit-only schema silently destroys Docmost-specific
- * nodes (callout, table) and drops attributes it does not know about
- * (node ids, image sizing, link targets). Every code path that converts
- * to or from ProseMirror JSON must use THIS set, otherwise a round-trip
- * loses content.
- *
- * PROVENANCE / KEEP IN SYNC: this file is a VENDORED MIRROR of the canonical
- * Docmost document schema in `@docmost/editor-ext`. The node/mark/attribute
- * surface MUST be kept in sync with editor-ext — anything present there but
- * missing here is silently dropped on a round-trip (data loss). The exported
- * `docmostExtensions` surface is guarded by `test/schema-surface-snapshot.test.ts`,
- * which fails loudly on any drift; when it does, re-verify parity against
- * `@docmost/editor-ext` before updating the snapshot.
- */
-import StarterKit from "@tiptap/starter-kit";
-import Image from "@tiptap/extension-image";
-import TaskList from "@tiptap/extension-task-list";
-import TaskItem from "@tiptap/extension-task-item";
-import Highlight from "@tiptap/extension-highlight";
-import Subscript from "@tiptap/extension-subscript";
-import Superscript from "@tiptap/extension-superscript";
-import { Node, Extension, Mark } from "@tiptap/core";
-
-// Inlined from @tiptap/core's getStyleProperty (added after 3.20.x) so this
-// package can stay on the same @tiptap/core version as the editor and avoid a
-// duplicate-tiptap version split in the monorepo. Reads a single declaration
-// from an element's inline `style` attribute, last-wins, case-insensitive.
-function getStyleProperty(element: HTMLElement, propertyName: string): string | null {
-  const styleAttr = element.getAttribute("style");
-  if (!styleAttr) {
-    return null;
-  }
-  const decls = styleAttr.split(";").map((decl) => decl.trim()).filter(Boolean);
-  const target = propertyName.toLowerCase();
-  for (let i = decls.length - 1; i >= 0; i -= 1) {
-    const decl = decls[i];
-    const colonIndex = decl.indexOf(":");
-    if (colonIndex === -1) {
-      continue;
-    }
-    const prop = decl.slice(0, colonIndex).trim().toLowerCase();
-    if (prop === target) {
-      return decl.slice(colonIndex + 1).trim();
-    }
-  }
-  return null;
-}
-
-/**
- * Allowed Docmost callout types; anything else falls back to "info".
- *
- * This MUST stay in lockstep with the editor's canonical set
- * (`getValidCalloutType` in `@docmost/editor-ext` callout/utils.ts:
- * default | info | note | success | warning | danger). A type missing here is
- * silently flattened to "info" on the markdown -> ProseMirror round-trip, so a
- * `[!note]` / `[!default]` callout authored in the editor would come back as
- * `[!info]` after a git sync (the QA "callout type -> [!info]" fidelity loss).
- * `note` and `default` were previously absent and so were being flattened.
- *
- * The editor SCHEMA genuinely only supports these six banner types — there is no
- * `tip`/`caution`/`important`/`question` callout node. So those are NOT first-
- * class types we can round-trip literally; they are INPUT ALIASES (GitHub/Obsidian
- * alert syntax). The editor's own paste/import path maps them onto the supported
- * set (see `GITHUB_ALERT_TYPE_MAP` in
- * `@docmost/editor-ext` markdown/utils/github-callout.marked.ts:
- * tip -> success, caution -> danger, important -> info). We mirror that aliasing
- * here so an ingested `> [!tip]` / `> [!caution]` lands on the closest real banner
- * (success / danger) instead of flatly collapsing to `info` — matching exactly how
- * the editor itself would interpret the same alias. A schema type always maps to
- * itself first (idempotent round-trip); the alias map only rewrites NON-schema
- * names; anything still unknown falls back to `info`.
- */
-const CALLOUT_TYPES = ["default", "info", "note", "success", "warning", "danger"];
-/**
- * NON-schema callout aliases -> their closest supported banner. Mirrors the
- * editor's `GITHUB_ALERT_TYPE_MAP` for the names that are NOT already schema
- * types (a schema type is preserved as-is and never consulted here). Keeping
- * these in lockstep means git-sync ingest and an editor paste interpret the same
- * `> [!alias]` identically.
- */
-const CALLOUT_TYPE_ALIASES: Record<string, string> = {
-  tip: "success",
-  caution: "danger",
-  important: "info",
-};
-export const clampCalloutType = (value: string | null | undefined): string => {
-  if (!value) return "info";
-  const lower = value.toLowerCase();
-  // A real schema type round-trips to itself (idempotent).
-  if (CALLOUT_TYPES.includes(lower)) return lower;
-  // A known GitHub/Obsidian alias maps to the editor's closest banner.
-  if (CALLOUT_TYPE_ALIASES[lower]) return CALLOUT_TYPE_ALIASES[lower];
-  // Anything else is collapsed to the safe default (matches the editor).
-  return "info";
-};
-
-/**
- * Allowlist guard for CSS color values imported from HTML.
- *
- * Docmost interpolates stored mark colors straight into an inline style
- * attribute (e.g. style="background-color: ${color}" / "color: ${color}").
- * An unsanitized value such as `red; --x: url(...)` or `red"><script>` would
- * let a crafted document break out of the style attribute. We therefore only
- * accept a narrow, well-formed subset of CSS <color> syntax and reject (-> null)
- * anything else.
- *
- * Accepted forms:
- *   - named colors:           letters only, e.g. "red", "rebeccapurple"
- *   - hex:                    #rgb, #rgba, #rrggbb, #rrggbbaa
- *   - functional notation:    rgb()/rgba()/hsl()/hsla() containing only
- *                             digits, %, ., commas, spaces and slashes
- */
-const SAFE_COLOR_RE =
-  /^(?:[a-zA-Z]+|#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgb|rgba|hsl|hsla)\([0-9.,%/\s]+\))$/;
-export const sanitizeCssColor = (
-  value: string | null | undefined,
-): string | null => {
-  if (typeof value !== "string") return null;
-  const color = value.trim();
-  return color && SAFE_COLOR_RE.test(color) ? color : null;
-};
-
-/** Docmost callout (info/warning/danger/success banner). */
-const Callout = Node.create({
-  name: "callout",
-  group: "block",
-  content: "block+",
-  defining: true,
-  addAttributes() {
-    return {
-      // Read the type from data-callout-type so generateJSON(html) preserves
-      // it; without an explicit parseHTML every imported callout became "info".
-      type: {
-        default: "info",
-        parseHTML: (el: HTMLElement) =>
-          clampCalloutType(el.getAttribute("data-callout-type")),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-callout-type": clampCalloutType(attrs.type),
-        }),
-      },
-      icon: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-icon"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.icon ? { "data-icon": attrs.icon } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="callout"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "callout", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Minimal table family: enough for schema round-trips and HTML parsing. */
-const Table = Node.create({
-  name: "table",
-  group: "block",
-  content: "tableRow+",
-  isolating: true,
-  parseHTML() {
-    return [{ tag: "table" }];
-  },
-  renderHTML() {
-    return ["table", ["tbody", 0]];
-  },
-});
-
-const TableRow = Node.create({
-  name: "tableRow",
-  content: "(tableCell | tableHeader)*",
-  parseHTML() {
-    return [{ tag: "tr" }];
-  },
-  renderHTML() {
-    return ["tr", 0];
-  },
-});
-
-const cellAttributes = () => ({
-  colspan: { default: 1 },
-  rowspan: { default: 1 },
-  colwidth: { default: null },
-  backgroundColor: { default: null },
-  backgroundColorName: { default: null },
-  // Column alignment so GFM aligned tables (|:--|:-:|--:|) round-trip.
-  align: {
-    default: null,
-    parseHTML: (el: HTMLElement) =>
-      el.getAttribute("align") || el.style.textAlign || null,
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.align ? { align: attrs.align } : {},
-  },
-});
-
-const TableCell = Node.create({
-  name: "tableCell",
-  content: "block+",
-  isolating: true,
-  addAttributes: cellAttributes,
-  parseHTML() {
-    return [{ tag: "td" }];
-  },
-  renderHTML() {
-    return ["td", 0];
-  },
-});
-
-const TableHeader = Node.create({
-  name: "tableHeader",
-  content: "block+",
-  isolating: true,
-  addAttributes: cellAttributes,
-  parseHTML() {
-    return [{ tag: "th" }];
-  },
-  renderHTML() {
-    return ["th", 0];
-  },
-});
-
-/**
- * Attributes Docmost stores on standard nodes that the stock extensions
- * do not declare. Without these, Node.fromJSON silently drops them —
- * including the block ids that heading anchors rely on.
- */
-const DocmostAttributes = Extension.create({
-  name: "docmostAttributes",
-  addGlobalAttributes() {
-    return [
-      {
-        types: ["heading", "paragraph"],
-        attributes: {
-          id: { default: null },
-          indent: { default: null },
-          // textAlign must round-trip the exported `<p style="text-align:…">`
-          // (and the legacy `<... align="…">`) form (review #10). Without an
-          // explicit parseHTML the default reads a bare `textAlign` attribute
-          // (never present), so alignment was silently dropped on every import.
-          textAlign: {
-            default: null,
-            parseHTML: (el: HTMLElement) =>
-              el.style?.textAlign || el.getAttribute("align") || null,
-            renderHTML: (attrs: Record<string, any>) =>
-              attrs.textAlign
-                ? { style: `text-align: ${attrs.textAlign}` }
-                : {},
-          },
-        },
-      },
-      {
-        types: ["image"],
-        attributes: {
-          align: { default: null },
-          // imageToHtml emits these Docmost-specific image attrs as data-*; map
-          // them back explicitly so a top-level image (or one inside a column)
-          // round-trips them. Without a parseHTML the default reads the bare
-          // attribute name (e.g. getAttribute("attachmentId") -> null) and the
-          // value — including the attachmentId that links the image to its
-          // stored file — is silently dropped on every round-trip (data loss).
-          attachmentId: {
-            default: null,
-            parseHTML: (el: HTMLElement) =>
-              el.getAttribute("data-attachment-id"),
-            renderHTML: (attrs: Record<string, any>) =>
-              attrs.attachmentId
-                ? { "data-attachment-id": attrs.attachmentId }
-                : {},
-          },
-          aspectRatio: {
-            default: null,
-            parseHTML: (el: HTMLElement) =>
-              el.getAttribute("data-aspect-ratio"),
-            renderHTML: (attrs: Record<string, any>) =>
-              attrs.aspectRatio != null
-                ? { "data-aspect-ratio": attrs.aspectRatio }
-                : {},
-          },
-          // Plain-text image caption (issue #221). editor-ext's image node
-          // serializes it as `data-caption` on the <img>; mirror that mapping so
-          // a captioned image survives the markdown <-> ProseMirror round-trip.
-          // Emit data-caption only when set, so caption-less images stay clean.
-          caption: {
-            default: null,
-            parseHTML: (el: HTMLElement) =>
-              el.getAttribute("data-caption") || null,
-            renderHTML: (attrs: Record<string, any>) =>
-              attrs.caption ? { "data-caption": attrs.caption } : {},
-          },
-          height: { default: null },
-          placeholder: { default: null },
-          size: {
-            default: null,
-            parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-            renderHTML: (attrs: Record<string, any>) =>
-              attrs.size != null ? { "data-size": attrs.size } : {},
-          },
-          width: { default: null },
-        },
-      },
-      {
-        types: ["orderedList"],
-        attributes: { type: { default: null } },
-      },
-      {
-        types: ["link"],
-        attributes: { internal: { default: null }, title: { default: null } },
-      },
-    ];
-  },
-});
-
-/**
- * Docmost inline comment mark. Anchors a comment thread to a text range via
- * `commentId`. Without it, any document containing comment highlights fails to
- * round-trip through the schema ("There is no mark type comment in this schema"),
- * which breaks update_page_json and edit_page_text on every commented page.
- * Mirrors Docmost's @docmost/editor-ext comment mark (commentId / resolved).
- */
-const Comment = Mark.create({
-  name: "comment",
-  exitable: true,
-  inclusive: false,
-  addAttributes() {
-    return {
-      commentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-comment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.commentId ? { "data-comment-id": attrs.commentId } : {},
-      },
-      resolved: {
-        default: false,
-        parseHTML: (el: HTMLElement) =>
-          el.getAttribute("data-resolved") === "true",
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.resolved ? { "data-resolved": "true" } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "span[data-comment-id]" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", { class: "comment-mark", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Inline spoiler mark (issue #259). Mirrors the @docmost/editor-ext `spoiler`
- * mark so a document carrying a spoiler survives the git-sync round-trip.
- * Markdown has no native spoiler syntax, so the markdown-converter emits it as
- * raw inline HTML (`<span data-spoiler="true">…</span>`); without this mark the
- * span re-parses as plain text and the spoiler is silently dropped on import.
- * It parses span[data-spoiler] and re-renders the same span[data-spoiler][class].
- */
-const Spoiler = Mark.create({
-  name: "spoiler",
-  inclusive: false,
-  parseHTML() {
-    return [{ tag: "span[data-spoiler]" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", { "data-spoiler": "true", class: "spoiler", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Text color mark. The markdown-converter emits colored text as
- * <span style="color: ...">, but with no mark parsing it back the color was
- * silently dropped on import. This mirrors TipTap's @tiptap/extension-text-style
- * `textStyle` mark (the name Docmost expects) and carries a single `color`
- * attribute. The parsed color is passed through the allowlist guard so a crafted
- * style cannot break out of the attribute when Docmost re-renders it.
- */
-const TextStyle = Mark.create({
-  name: "textStyle",
-  addAttributes() {
-    return {
-      color: {
-        default: null,
-        parseHTML: (el: HTMLElement) =>
-          sanitizeCssColor(
-            el.style.color || el.getAttribute("data-color"),
-          ),
-        renderHTML: (attrs: Record<string, any>) => {
-          const color = sanitizeCssColor(attrs.color);
-          return color ? { style: `color: ${color}` } : {};
-        },
-      },
-    };
-  },
-  parseHTML() {
-    return [
-      {
-        tag: "span",
-        // Only claim a plain colored span. Do NOT match spans that are already a
-        // comment mark (data-comment-id) or a mention node (data-type=mention),
-        // otherwise importing such HTML would silently drop the comment/mention.
-        getAttrs: (el: HTMLElement) =>
-          el.style.color &&
-          !el.getAttribute("data-comment-id") &&
-          el.getAttribute("data-type") !== "mention"
-            ? {}
-            : false,
-      },
-    ];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", HTMLAttributes, 0];
-  },
-});
-
-/**
- * Passthrough definitions for the remaining Docmost-specific nodes.
- *
- * TiptapTransformer.toYdoc (the write path every mutation uses) throws
- * "Unknown node type: X" for any node not registered here, so editing ANY
- * page that contains one of these nodes used to fail outright. The read path
- * (fromYdoc) accepts them, which is why they appear in real documents.
- *
- * Each node below mirrors the real @docmost/editor-ext definition's name,
- * group, content, inline/atom flags and attribute keys (with the same data-*
- * HTML mapping) so that a fromYdoc -> transform -> toYdoc round-trip both
- * validates and preserves attributes faithfully. Interactive concerns
- * (node views, commands, keyboard shortcuts, input rules, suggestion plugins)
- * are intentionally omitted: the MCP server never renders these nodes, it only
- * needs the schema to accept and carry them. The Callout node above is the
- * pattern these follow.
- */
-
-/** Docmost @mention (user/page reference). Inline atom. */
-const Mention = Node.create({
-  name: "mention",
-  group: "inline",
-  inline: true,
-  selectable: true,
-  atom: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      id: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.id ? { "data-id": attrs.id } : {},
-      },
-      label: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-label"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.label ? { "data-label": attrs.label } : {},
-      },
-      entityType: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-type"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.entityType ? { "data-entity-type": attrs.entityType } : {},
-      },
-      entityId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.entityId ? { "data-entity-id": attrs.entityId } : {},
-      },
-      slugId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-slug-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.slugId ? { "data-slug-id": attrs.slugId } : {},
-      },
-      creatorId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-creator-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.creatorId ? { "data-creator-id": attrs.creatorId } : {},
-      },
-      anchorId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-anchor-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.anchorId ? { "data-anchor-id": attrs.anchorId } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'span[data-type="mention"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", { "data-type": "mention", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Inline KaTeX expression. Carries the LaTeX source in `text`. */
-const MathInline = Node.create({
-  name: "mathInline",
-  group: "inline",
-  inline: true,
-  atom: true,
-  addAttributes() {
-    return {
-      text: { default: "" },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'span[data-type="mathInline"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "span",
-      { "data-type": "mathInline", "data-katex": "true" },
-      `${HTMLAttributes.text ?? ""}`,
-    ];
-  },
-});
-
-/** Block KaTeX expression. Carries the LaTeX source in `text`. */
-const MathBlock = Node.create({
-  name: "mathBlock",
-  group: "block",
-  atom: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      text: { default: "" },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="mathBlock"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "div",
-      { "data-type": "mathBlock", "data-katex": "true" },
-      `${HTMLAttributes.text ?? ""}`,
-    ];
-  },
-});
-
-/** Collapsible <details> wrapper: summary + content children. */
-const Details = Node.create({
-  name: "details",
-  group: "block",
-  content: "detailsSummary detailsContent",
-  defining: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      open: {
-        default: false,
-        parseHTML: (el: HTMLElement) => el.hasAttribute("open"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.open ? { open: "" } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "details" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["details", { ...HTMLAttributes }, 0];
-  },
-});
-
-/** Clickable summary line of a <details> block. */
-const DetailsSummary = Node.create({
-  name: "detailsSummary",
-  group: "block",
-  content: "inline*",
-  defining: true,
-  isolating: true,
-  selectable: false,
-  parseHTML() {
-    return [{ tag: "summary" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["summary", { "data-type": "detailsSummary", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Body of a <details> block. Permissive content so fromYdoc output validates. */
-const DetailsContent = Node.create({
-  name: "detailsContent",
-  group: "block",
-  // Docmost declares block* (an empty details body is valid); block+ would
-  // reject a collapsed/empty details on round-trip.
-  content: "block*",
-  defining: true,
-  selectable: false,
-  parseHTML() {
-    return [{ tag: 'div[data-type="detailsContent"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "detailsContent", ...HTMLAttributes }, 0];
-  },
-});
-
-/** File attachment card (non-image upload). Block atom. */
-const Attachment = Node.create({
-  name: "attachment",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      url: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-url"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-attachment-url": attrs.url ?? "",
-        }),
-      },
-      name: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-name"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.name ? { "data-attachment-name": attrs.name } : {},
-      },
-      mime: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-mime"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.mime ? { "data-attachment-mime": attrs.mime } : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-attachment-size": attrs.size } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      // Docmost declares `placeholder` (a transient upload key, not rendered
-      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="attachment"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "attachment", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Uploaded <video> player. Block atom. */
-const Video = Node.create({
-  name: "video",
-  group: "block",
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      alt: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("aria-label"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.alt ? { "aria-label": attrs.alt } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { width: attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { height: attrs.height } : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.align ? { "data-align": attrs.align } : {},
-      },
-      aspectRatio: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.aspectRatio != null
-            ? { "data-aspect-ratio": attrs.aspectRatio }
-            : {},
-      },
-      // Docmost declares `placeholder` (a transient upload key, not rendered
-      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "video" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["video", { controls: "true", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Defensive passthrough for a `youtube` node. Docmost itself has no dedicated
- * youtube node (YouTube is handled via `embed`), but the converter read path
- * references this type, so accept it as a generic block atom that preserves
- * its src so legacy/external documents survive a round-trip.
- */
-const Youtube = Node.create({
-  name: "youtube",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-src": attrs.src ?? "",
-        }),
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { "data-width": attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { "data-height": attrs.height } : {},
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.align ? { "data-align": attrs.align } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="youtube"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "youtube", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Generic embed (provider iframe). Block atom. */
-const Embed = Node.create({
-  name: "embed",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-src": attrs.src ?? "",
-        }),
-      },
-      provider: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-provider"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-provider": attrs.provider ?? "",
-        }),
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-align": attrs.align ?? "center",
-        }),
-      },
-      width: {
-        default: 800,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-width": attrs.width,
-        }),
-      },
-      height: {
-        default: 600,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-height": attrs.height,
-        }),
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="embed"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "embed", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Shared attribute set for drawio/excalidraw diagram nodes. */
-const diagramAttributes = () => ({
-  src: {
-    default: "",
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-    renderHTML: (attrs: Record<string, any>) => ({
-      "data-src": attrs.src ?? "",
-    }),
-  },
-  title: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-title"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.title ? { "data-title": attrs.title } : {},
-  },
-  alt: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-alt"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.alt ? { "data-alt": attrs.alt } : {},
-  },
-  width: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.width != null ? { "data-width": attrs.width } : {},
-  },
-  height: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.height != null ? { "data-height": attrs.height } : {},
-  },
-  size: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.size != null ? { "data-size": attrs.size } : {},
-  },
-  aspectRatio: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.aspectRatio != null
-        ? { "data-aspect-ratio": attrs.aspectRatio }
-        : {},
-  },
-  align: {
-    default: "center",
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.align ? { "data-align": attrs.align } : {},
-  },
-  attachmentId: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.attachmentId ? { "data-attachment-id": attrs.attachmentId } : {},
-  },
-});
-
-/** draw.io diagram. Block atom (image-backed). */
-const Drawio = Node.create({
-  name: "drawio",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes: diagramAttributes,
-  parseHTML() {
-    return [{ tag: 'div[data-type="drawio"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "drawio", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Excalidraw diagram. Block atom (image-backed). */
-const Excalidraw = Node.create({
-  name: "excalidraw",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes: diagramAttributes,
-  parseHTML() {
-    return [{ tag: 'div[data-type="excalidraw"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "excalidraw", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Multi-column layout container holding one or more `column` children. */
-const Columns = Node.create({
-  name: "columns",
-  group: "block",
-  content: "column+",
-  defining: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      layout: {
-        default: "two_equal",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-layout"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.layout ? { "data-layout": attrs.layout } : {},
-      },
-      widthMode: {
-        default: "normal",
-        parseHTML: (el: HTMLElement) =>
-          el.getAttribute("data-width-mode") || "normal",
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.widthMode && attrs.widthMode !== "normal"
-            ? { "data-width-mode": attrs.widthMode }
-            : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="columns"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "columns", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Single column within a `columns` layout. */
-const Column = Node.create({
-  name: "column",
-  group: "block",
-  content: "block+",
-  defining: true,
-  isolating: true,
-  selectable: false,
-  addAttributes() {
-    return {
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => {
-          const value = el.getAttribute("data-width");
-          return value ? parseFloat(value) : null;
-        },
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width ? { "data-width": attrs.width } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="column"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "column", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Subpages listing block (auto-generated index of child pages). Docmost
- * declares no attributes; the markdown-converter has a `case "subpages"`, so
- * the read path can emit it and toYdoc must accept it. Block atom.
- */
-const Subpages = Node.create({
-  name: "subpages",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      recursive: {
-        default: false,
-        parseHTML: (el: HTMLElement) =>
-          el.getAttribute("data-recursive") === "true",
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.recursive ? { "data-recursive": "true" } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="subpages"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "subpages", ...HTMLAttributes }];
-  },
-});
-
-/** Uploaded <audio> player. Block atom. Mirrors Docmost audio attrs. */
-const Audio = Node.create({
-  name: "audio",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      // Transient upload key Docmost declares with rendered:false; carried so
-      // a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "audio" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["audio", { controls: "true", ...HTMLAttributes }];
-  },
-});
-
-/** Embedded PDF viewer. Block atom. Mirrors Docmost pdf attrs. */
-const Pdf = Node.create({
-  name: "pdf",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      name: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-name"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.name ? { "data-name": attrs.name } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { width: attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { height: attrs.height } : {},
-      },
-      // Transient upload key Docmost declares with rendered:false; carried so
-      // a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="pdf"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "pdf", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Page break (print/export divider). Block atom; Docmost declares no attrs. */
-const PageBreak = Node.create({
-  name: "pageBreak",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  parseHTML() {
-    return [{ tag: 'div[data-type="pageBreak"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "pageBreak", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Footnote feature (mirror of @docmost/editor-ext footnote, matching the MCP
- * schema mirror). 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. The
- * <sup> parse rule uses priority 100 so it beats the Superscript mark's <sup>
- * rule (otherwise an empty reference parses as an empty superscript and drops).
- */
-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];
-  },
-});
-
-/**
- * Encode/decode the htmlEmbed `source` (arbitrary HTML/CSS/JS) to/from base64
- * for the `data-source` attribute. Ported from @docmost/editor-ext so the
- * markdown-converter HTML path (generateJSON via parseHTML) round-trips the
- * raw source losslessly and keeps it inert while it sits in the attribute.
- * `encodeURIComponent`/`decodeURIComponent` wrap btoa/atob so UTF-8 survives.
- */
-export function encodeHtmlEmbedSource(source: string): string {
-  if (!source) return "";
-  try {
-    if (typeof btoa === "function") {
-      return btoa(encodeURIComponent(source));
-    }
-    return Buffer.from(encodeURIComponent(source), "utf-8").toString("base64");
-  } catch {
-    return "";
-  }
-}
-
-export function decodeHtmlEmbedSource(encoded: string): string {
-  if (!encoded) return "";
-  try {
-    if (typeof atob === "function") {
-      return decodeURIComponent(atob(encoded));
-    }
-    return decodeURIComponent(Buffer.from(encoded, "base64").toString("utf-8"));
-  } catch {
-    return "";
-  }
-}
-
-/**
- * Docmost raw HTML embed. Block atom; the client renders `source` inside a
- * sandboxed iframe. Mirrors the @docmost/editor-ext node — `source` rides the
- * `data-source` attribute base64-encoded (this is an HTML/generateJSON path, so
- * it MUST use base64 to avoid double-encoding / injection).
- */
-const HtmlEmbed = Node.create({
-  name: "htmlEmbed",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      source: {
-        default: "",
-        parseHTML: (el: HTMLElement) =>
-          decodeHtmlEmbedSource(el.getAttribute("data-source") || ""),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-source": encodeHtmlEmbedSource(attrs.source || ""),
-        }),
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => {
-          const v = el.getAttribute("data-height");
-          if (!v) return null;
-          const n = parseInt(v, 10);
-          return Number.isFinite(n) ? n : null;
-        },
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { "data-height": String(attrs.height) } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="htmlEmbed"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "htmlEmbed", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Inline status pill. Mirrors @docmost/editor-ext status: the label rides in
- * the element's TEXT content (not an attribute) and the color in data-color.
- */
-const Status = Node.create({
-  name: "status",
-  group: "inline",
-  inline: true,
-  atom: true,
-  selectable: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      text: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.textContent || "",
-      },
-      color: {
-        default: "gray",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-color") || "gray",
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-color": attrs.color ?? "gray",
-        }),
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'span[data-type="status"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "span",
-      { "data-type": "status", "data-color": HTMLAttributes["data-color"] },
-      `${HTMLAttributes.text ?? ""}`,
-    ];
-  },
-});
-
-/**
- * Whole-page live embed. Holds only a `sourcePageId` reference. Mirrors
- * @docmost/editor-ext pageEmbed. Block atom.
- */
-const PageEmbed = Node.create({
-  name: "pageEmbed",
-  group: "block",
-  atom: true,
-  isolating: true,
-  selectable: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      sourcePageId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-source-page-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.sourcePageId
-            ? { "data-source-page-id": attrs.sourcePageId }
-            : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="pageEmbed"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "pageEmbed", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Block node types allowed inside a `transclusionSource` (mirrors
- * @docmost/editor-ext transclusion constants). Excludes transclusion nodes
- * (no nesting) and child-only nodes.
- */
-const TRANSCLUSION_SOURCE_CONTENT_EXPRESSION =
-  "(paragraph | heading | blockquote | codeBlock | horizontalRule | bulletList" +
-  " | orderedList | taskList | image | video | audio | attachment | callout" +
-  " | details | embed | mathBlock | table | drawio | excalidraw | pdf" +
-  " | subpages | columns | youtube)+";
-
-/** Sync-source block: editable content shared into transclusion references. */
-const TransclusionSource = Node.create({
-  name: "transclusionSource",
-  group: "block",
-  content: TRANSCLUSION_SOURCE_CONTENT_EXPRESSION,
-  defining: true,
-  isolating: true,
-  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-type="transclusionSource"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "transclusionSource", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Live reference to a transcluded block/page. Block atom. */
-const TransclusionReference = Node.create({
-  name: "transclusionReference",
-  group: "block",
-  atom: true,
-  selectable: true,
-  draggable: false,
-  addAttributes() {
-    return {
-      sourcePageId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-source-page-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.sourcePageId
-            ? { "data-source-page-id": attrs.sourcePageId }
-            : {},
-      },
-      transclusionId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-transclusion-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.transclusionId
-            ? { "data-transclusion-id": attrs.transclusionId }
-            : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="transclusionReference"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "div",
-      { "data-type": "transclusionReference", ...HTMLAttributes },
-    ];
-  },
-});
-
-/**
- * Full extension list. Image is block-level (matches Docmost); the
- * ProseMirror DOM parser hoists <img> found inside <p> automatically.
- * StarterKit v3 already bundles the link extension, configured here.
- */
-export const docmostExtensions = [
-  StarterKit.configure({
-    codeBlock: {},
-    heading: {},
-    link: { openOnClick: false },
-  }),
-  // Preserve image width/height as the AUTHORED string. Without an explicit
-  // parseHTML the stock Image node attribute falls back to tiptap core's
-  // `fromString`, which coerces a numeric width like "320" into the number 320
-  // — changing the stored type on every markdown round-trip (Docmost stores
-  // these as strings, e.g. "320" or "50%", matching how video/audio/pdf are
-  // handled in this mirror). The node attribute is applied AFTER the global
-  // DocmostAttributes one, so the fix must live on the Image node itself.
-  Image.extend({
-    addAttributes() {
-      const parent = (this.parent?.() ?? {}) as Record<string, any>;
-      return {
-        ...parent,
-        width: {
-          ...parent.width,
-          parseHTML: (el: HTMLElement) => el.getAttribute("width"),
-        },
-        height: {
-          ...parent.height,
-          parseHTML: (el: HTMLElement) => el.getAttribute("height"),
-        },
-      };
-    },
-  }).configure({ inline: false }),
-  TaskList,
-  TaskItem.configure({ nested: true }),
-  // Highlight stores its color unescaped and Docmost interpolates it into
-  // style="background-color: ${color}". Wrap the color attribute's parseHTML
-  // with the same allowlist guard used by textStyle so a crafted import color
-  // cannot break out of the style attribute. Multicolor behavior is preserved.
-  Highlight.extend({
-    addAttributes() {
-      const parent = this.parent?.() ?? {};
-      return {
-        ...parent,
-        color: {
-          ...(parent as Record<string, any>).color,
-          parseHTML: (el: HTMLElement) =>
-            sanitizeCssColor(
-              el.getAttribute("data-color") ||
-                getStyleProperty(el, "background-color") ||
-                el.style.backgroundColor,
-            ),
-        },
-      };
-    },
-  }).configure({ multicolor: true }),
-  Subscript,
-  Superscript,
-  // StarterKit does not provide a textStyle mark, so register ours; without it
-  // generateJSON drops <span style="color: ...">, defeating the color import.
-  TextStyle,
-  Comment,
-  Spoiler,
-  Callout,
-  Table,
-  TableRow,
-  TableCell,
-  TableHeader,
-  Mention,
-  MathInline,
-  MathBlock,
-  Details,
-  DetailsSummary,
-  DetailsContent,
-  Attachment,
-  Video,
-  Youtube,
-  Embed,
-  Drawio,
-  Excalidraw,
-  Columns,
-  Column,
-  Subpages,
-  Audio,
-  Pdf,
-  PageBreak,
-  FootnoteReference,
-  FootnotesList,
-  FootnoteDefinition,
-  HtmlEmbed,
-  Status,
-  PageEmbed,
-  TransclusionSource,
-  TransclusionReference,
-  DocmostAttributes,
-];
diff --git a/packages/git-sync/src/lib/index.ts b/packages/git-sync/src/lib/index.ts
deleted file mode 100644
index 9e797a26..00000000
--- a/packages/git-sync/src/lib/index.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-/**
- * Public surface of the pure converter (`lib/`). This barrel re-exports the
- * PURE, IO-free pieces the sync engine needs: the self-contained markdown
- * (de)serializers, the lossless ProseMirror <-> Markdown converter, the
- * markdown -> ProseMirror import path, and semantic canonicalization for the
- * round-trip idempotency check (SPEC §11).
- *
- * There is no REST client, websocket/collab write-path, auth-utils or page-lock
- * here — the gitmost server writes natively.
- */
-export {
-  serializeDocmostMarkdown,
-  parseDocmostMarkdown,
-  serializeDocmostMarkdownBody,
-} from "./markdown-document.js";
-export type { DocmostMdMeta } from "./markdown-document.js";
-
-export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
-
-export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
-
-export {
-  canonicalizeContent,
-  docsCanonicallyEqual,
-} from "./canonicalize.js";
-export { parsePageFile, serializePageFile } from "./page-file.js";
diff --git a/packages/git-sync/src/lib/markdown-converter.ts b/packages/git-sync/src/lib/markdown-converter.ts
deleted file mode 100644
index 013a54f3..00000000
--- a/packages/git-sync/src/lib/markdown-converter.ts
+++ /dev/null
@@ -1,1130 +0,0 @@
-import { encodeHtmlEmbedSource } from "./docmost-schema.js";
-
-/**
- * Hard cap on processNode recursion depth (see the depth guard below).
- *
- * Chosen well above any realistic document (the deepest legitimate nesting the
- * editor can produce is far shallower) yet far below the point where the
- * converter's own call stack overflows. The heaviest shape (deeply nested
- * lists) costs ~5 JS frames per level and the runtime stack holds ~10k frames,
- * so the measured overflow is around level ~650 (deeply nested lists); 400
- * leaves a comfortable margin while still rendering pathological-but-bounded
- * docs in full (the 200-level stress fixture reaches depth ~204).
- */
-const MAX_NODE_DEPTH = 400;
-
-/**
- * Convert ProseMirror/TipTap JSON content to Markdown
- * Supports all Docmost-specific node types and extensions
- */
-export function convertProseMirrorToMarkdown(content: any): string {
-  if (!content || !content.content) return "";
-
-  // Escape a value interpolated into an HTML double-quoted attribute value
-  // (textAlign, colors, image src, math `text`, all data-* attrs, etc.). In the
-  // ATTRIBUTE context only the quote that delimits the value and the ampersand
-  // that starts an entity are special, so we escape ONLY & " (and ' for safety
-  // when single-quoted delimiters are used). We deliberately do NOT escape < or
-  // >: the HTML re-parser (parse5/jsdom via @tiptap/html) does NOT decode
-  // &lt;/&gt; back inside attribute values, so escaping them would corrupt the
-  // stored data (e.g. a math node's LaTeX `a < b`) and ACCUMULATE escapes on
-  // every round-trip (`a < b` -> `a &lt; b` -> `a &amp;lt; b`). Escaping & "
-  // keeps the value inert against attribute-injection while staying idempotent.
-  // NOTE: escape ONLY & and " here. The value is always wrapped in double
-  // quotes, so " is the only delimiter; ' is NOT special in a double-quoted
-  // value, and parse5 does not decode &#39; back inside attribute values, so
-  // escaping ' would (like < >) corrupt the value and accumulate &amp; on every
-  // round-trip. Escaping & and " is idempotent (parse5 decodes them back).
-  const escapeAttr = (value: unknown): string =>
-    String(value)
-      .replace(/&/g, "&amp;")
-      .replace(/"/g, "&quot;");
-
-  // Escape a value placed as HTML element TEXT content (between tags), where
-  // <, >, and & are all significant. Used for text rendered inside raw-HTML
-  // blocks (table cells / columns) so stored characters cannot inject markup.
-  const escapeHtmlText = (value: unknown): string =>
-    String(value)
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;");
-
-  // Percent-encode characters that would break out of a markdown URL target
-  // (...) — whitespace/newlines and parentheses — so a stored src stays a
-  // single inert token (used for image/video/youtube srcs).
-  const encodeMdUrl = (value: unknown): string =>
-    String(value || "")
-      .replace(/\s/g, (c: string) => (c === " " ? "%20" : encodeURIComponent(c)))
-      .replace(/\(/g, "%28")
-      .replace(/\)/g, "%29");
-
-  // Recursion depth guard. processNode is mutually recursive (directly and via
-  // processListItem/processTaskItem/blockToHtml), and a pathologically nested
-  // document (e.g. tens of thousands of nested blockquotes) would otherwise
-  // overflow the call stack and throw a RangeError, which would abort the sync
-  // and prevent the page from ever being written. We track the live nesting
-  // depth in a closure counter (the wrapper below) so we NEVER throw: past the
-  // limit we stop recursing and emit the node's own text (or nothing) instead.
-  // Normal documents never approach MAX_NODE_DEPTH, so their output is byte-
-  // identical. NOTE: the wrapper signature is (node) only — several callers use
-  // `.map(processNode)`, which would otherwise pass the array index as a second
-  // argument; the wrapper ignores extra arguments so that is harmless.
-  let nodeDepth = 0;
-
-  // A table cell whose content is NOT a single plain paragraph — a list, code
-  // block, blockquote, multiple paragraphs, etc. A GFM pipe cell can only hold
-  // inline content on one line, so such a cell must force the HTML <table> form
-  // or its structure is flattened/lost on round trip (review #8).
-  const cellIsMultiBlock = (cell: any): boolean => {
-    const blocks = cell.content || [];
-    if (blocks.length > 1) return true;
-    const only = blocks[0];
-    return only != null && only.type !== "paragraph";
-  };
-
-  // Render a whole table as raw HTML `<table>` (round-trips via the schema's
-  // table-family parseHTML). Used when a GFM pipe table would be wrong: merged
-  // cells (colspan/rowspan), multi-block cells (#8), OR the table sits inside a
-  // raw-HTML container like a column (marked does not parse markdown inside raw
-  // HTML, so a GFM pipe table there becomes literal "| a | b |" text — #7).
-  // `blockToHtml` is referenced lazily (defined below; only called at runtime).
-  const tableToHtml = (tableRows: any[]): string => {
-    const renderHtmlCell = (cell: any): string => {
-      const tag = cell.type === "tableHeader" ? "th" : "td";
-      const a = cell.attrs || {};
-      const cellParts: string[] = [];
-      if ((a.colspan ?? 1) > 1)
-        cellParts.push(`colspan="${escapeAttr(a.colspan)}"`);
-      if ((a.rowspan ?? 1) > 1)
-        cellParts.push(`rowspan="${escapeAttr(a.rowspan)}"`);
-      if (a.align) cellParts.push(`align="${escapeAttr(a.align)}"`);
-      const open = cellParts.length
-        ? `<${tag} ${cellParts.join(" ")}>`
-        : `<${tag}>`;
-      const inner = (cell.content || [])
-        .map((block: any) => blockToHtml(block))
-        .join("");
-      return `${open}${inner}</${tag}>`;
-    };
-    const htmlRows = tableRows
-      .map(
-        (row: any) =>
-          `<tr>${(row.content || []).map(renderHtmlCell).join("")}</tr>`,
-      )
-      .join("");
-    return `<table><tbody>${htmlRows}</tbody></table>`;
-  };
-
-  const processNode = (node: any): string => {
-    if (nodeDepth >= MAX_NODE_DEPTH) {
-      // Bail out of deeper recursion without throwing. A text node still has
-      // its own content worth keeping; a container at the limit collapses to
-      // "" (its already-too-deep subtree is dropped) rather than overflowing.
-      return typeof node?.text === "string" ? node.text : "";
-    }
-    nodeDepth++;
-    try {
-      return processNodeInner(node);
-    } finally {
-      nodeDepth--;
-    }
-  };
-
-  const processNodeInner = (node: any): string => {
-    const type = node.type;
-    const nodeContent = node.content || [];
-
-    switch (type) {
-      case "doc":
-        return nodeContent.map(processNode).join("\n\n");
-
-      case "paragraph":
-        const text = nodeContent.map(processNode).join("");
-        const align = node.attrs?.textAlign;
-        if (align && align !== "left") {
-          // Emit alignment as a styled `<p>` (review #10). The old
-          // `<div align="…">` had NO matching import parse rule — the div was
-          // unwrapped and alignment lost on every round trip. A styled `<p>`
-          // round-trips: the paragraph parse rule (tag:"p") matches and the
-          // textAlign global-attribute parseHTML (docmost-schema) reads the style.
-          return `<p style="text-align:${escapeAttr(align)}">${text}</p>`;
-        }
-        return text || "";
-
-      case "heading":
-        const level = node.attrs?.level || 1;
-        const headingText = nodeContent.map(processNode).join("");
-        const headingAlign = node.attrs?.textAlign;
-        if (headingAlign && headingAlign !== "left") {
-          // Emit alignment as a styled `<hN>` so it round-trips losslessly,
-          // symmetric to the paragraph case above (review F5/A1). The bare
-          // `## text` markdown form carries NO alignment, so an aligned heading
-          // would silently drop textAlign on export. A styled `<hN>` re-parses:
-          // the heading parse rule (tag:"h1".."h6") matches and the textAlign
-          // global-attribute parseHTML (docmost-schema) reads the style back,
-          // preserving BOTH level and textAlign. escapeAttr keeps the align
-          // value injection-safe, exactly like the paragraph arm.
-          return `<h${level} style="text-align:${escapeAttr(headingAlign)}">${headingText}</h${level}>`;
-        }
-        // No alignment (or the default "left"): keep the plain `## text`
-        // markdown form — HTML-ifying an unaligned heading would be needless
-        // churn, exactly as the paragraph case keeps plain text when unaligned.
-        return "#".repeat(level) + " " + headingText;
-
-      case "text":
-        let textContent = node.text || "";
-        // Apply marks (bold, italic, code, etc.)
-        if (node.marks) {
-          // The schema's `code` mark declares `excludes: "_"` — it excludes every
-          // other inline mark — so the editor can NEVER produce a text run that
-          // carries `code` together with another mark, and on import any
-          // co-occurring mark is always dropped (the run comes back as code-only).
-          // The lossless, byte-stable behavior is therefore: when a run has the
-          // `code` mark, emit ONLY the backtick code span and ignore every other
-          // mark, so md1 is already code-only and md2 === md1. Runs WITHOUT a code
-          // mark are rendered exactly as before.
-          const markTypes = node.marks.map((m: any) => m.type);
-          const hasCode = markTypes.includes("code");
-          if (hasCode) {
-            textContent = `\`${textContent}\``;
-            return textContent;
-          }
-          const codeCombined = false;
-          for (const mark of node.marks) {
-            switch (mark.type) {
-              case "bold":
-                textContent = codeCombined
-                  ? `<strong>${textContent}</strong>`
-                  : `**${textContent}**`;
-                break;
-              case "italic":
-                textContent = codeCombined
-                  ? `<em>${textContent}</em>`
-                  : `*${textContent}*`;
-                break;
-              case "code":
-                // When combined with another mark, wrap as <code> so the
-                // surrounding HTML marks can nest around it; otherwise use the
-                // plain backtick span.
-                textContent = codeCombined
-                  ? `<code>${textContent}</code>`
-                  : `\`${textContent}\``;
-                break;
-              case "link": {
-                const href = mark.attrs?.href || "";
-                const title = mark.attrs?.title;
-                if (codeCombined) {
-                  // Emit an HTML anchor so it can wrap the nested <code>.
-                  const safeHref = escapeAttr(href);
-                  if (title) {
-                    textContent = `<a href="${safeHref}" title="${escapeAttr(String(title))}">${textContent}</a>`;
-                  } else {
-                    textContent = `<a href="${safeHref}">${textContent}</a>`;
-                  }
-                } else if (title) {
-                  // Emit the optional markdown link title; escape an embedded
-                  // double-quote so it cannot terminate the title string early.
-                  const safeTitle = String(title).replace(/"/g, '\\"');
-                  textContent = `[${textContent}](${href} "${safeTitle}")`;
-                } else {
-                  textContent = `[${textContent}](${href})`;
-                }
-                break;
-              }
-              case "strike":
-                textContent = codeCombined
-                  ? `<s>${textContent}</s>`
-                  : `~~${textContent}~~`;
-                break;
-              case "underline":
-                textContent = `<u>${textContent}</u>`;
-                break;
-              case "subscript":
-                textContent = `<sub>${textContent}</sub>`;
-                break;
-              case "superscript":
-                textContent = `<sup>${textContent}</sup>`;
-                break;
-              case "highlight": {
-                // Preserve a null/empty color as a plain highlight (a bare
-                // <mark> with no background-color); only emit the style when a
-                // color is actually set, so a plain highlight is not forced to
-                // yellow on export.
-                const color = mark.attrs?.color;
-                textContent = color
-                  ? `<mark style="background-color: ${escapeAttr(color)}">${textContent}</mark>`
-                  : `<mark>${textContent}</mark>`;
-                break;
-              }
-              case "textStyle":
-                if (mark.attrs?.color) {
-                  textContent = `<span style="color: ${escapeAttr(mark.attrs.color)}">${textContent}</span>`;
-                }
-                break;
-              case "spoiler":
-                // Markdown has no native spoiler syntax, so emit the same raw
-                // inline HTML the editor-ext/MCP stack uses. The schema's Spoiler
-                // mark parses span[data-spoiler] back on import, so the mark
-                // survives the PM -> MD -> PM round-trip.
-                textContent = `<span data-spoiler="true">${textContent}</span>`;
-                break;
-              case "comment": {
-                // Emit the inline comment anchor so highlights round-trip. The
-                // schema's Comment mark parses span[data-comment-id] (attrs
-                // commentId/resolved).
-                const cid = mark.attrs?.commentId;
-                if (cid) {
-                  const resolvedAttr = mark.attrs?.resolved
-                    ? ` data-resolved="true"`
-                    : "";
-                  textContent = `<span data-comment-id="${escapeAttr(cid)}"${resolvedAttr}>${textContent}</span>`;
-                }
-                break;
-              }
-            }
-          }
-        }
-        return textContent;
-
-      case "codeBlock":
-        const language = node.attrs?.language || "";
-        // Strip ALL trailing newlines so the export is idempotent: marked
-        // re-adds exactly one trailing "\n" on import, so trimming only one
-        // here would let the text grow by "\n" on each round-trip. Removing
-        // every trailing newline makes repeated cycles stable.
-        const code = nodeContent
-          .map(processNode)
-          .join("")
-          .replace(/\n+$/, "");
-        // CommonMark: an inner ``` run inside the code would prematurely close
-        // a 3-backtick fence (corrupting the block on re-import). Use an outer
-        // fence one backtick longer than the longest backtick run in the code
-        // (minimum 3) so the inner fence is always content.
-        const longestBacktickRun = (code.match(/`+/g) || []).reduce(
-          (max: number, run: string) => Math.max(max, run.length),
-          0,
-        );
-        const fence = "`".repeat(Math.max(3, longestBacktickRun + 1));
-        return fence + language + "\n" + code + "\n" + fence;
-
-      case "bulletList":
-        return nodeContent
-          .map((item: any) => processListItem(item, "-"))
-          .join("\n");
-
-      case "orderedList":
-        return nodeContent
-          .map((item: any, index: number) =>
-            processListItem(item, `${index + 1}.`),
-          )
-          .join("\n");
-
-      case "taskList":
-        return nodeContent.map((item: any) => processTaskItem(item)).join("\n");
-
-      case "taskItem":
-        // Delegate to the same helper used by taskList so multi-block and
-        // nested task items render and indent consistently.
-        return processTaskItem(node);
-
-      case "listItem":
-        return nodeContent.map(processNode).join("\n");
-
-      case "blockquote":
-        // Prefix EVERY line of EVERY child with "> " and separate block-level
-        // children with a blank ">" line so code blocks / multi-paragraph
-        // quotes round-trip correctly.
-        return nodeContent
-          .map((n: any) =>
-            processNode(n)
-              .split("\n")
-              .map((line: string) => (line.length ? `> ${line}` : ">"))
-              .join("\n"),
-          )
-          .join("\n>\n");
-
-      case "horizontalRule":
-        return "---";
-
-      case "hardBreak":
-        // Two trailing spaces before the newline encode a markdown hard break;
-        // a bare "\n" would be reimported as a soft break and lost.
-        return "  \n";
-
-      case "image": {
-        const imgAttrs = node.attrs || {};
-        // A top-level image with layout/identity attrs beyond src/alt cannot be
-        // expressed by markdown `![](src)` — width/height/align/size/
-        // attachmentId/aspectRatio would be silently dropped on export and lost
-        // on re-import. Emit the SAME schema-matching <img> used inside columns
-        // (imageToHtml) so those attrs survive the round-trip. A bare image
-        // (only src/alt, optionally a title — which has no schema attr) keeps
-        // the lighter markdown form so existing image round-trip tests hold.
-        const hasLayoutAttrs =
-          imgAttrs.width != null ||
-          imgAttrs.height != null ||
-          imgAttrs.align ||
-          imgAttrs.size != null ||
-          imgAttrs.attachmentId ||
-          imgAttrs.aspectRatio != null ||
-          // A caption (issue #221) cannot be expressed by markdown `![](src)`,
-          // so route a captioned image through imageToHtml's raw <img> form
-          // (data-caption) — the same lossless form used for the other
-          // Docmost-specific image attrs.
-          imgAttrs.caption;
-        if (hasLayoutAttrs) {
-          return imageToHtml(node);
-        }
-        const imgAlt = imgAttrs.alt || "";
-        // Neutralize characters that could break out of the markdown image
-        // URL: spaces/newlines and parentheses would terminate the (...) target
-        // and let a stored src inject following markdown/HTML. Percent-encode
-        // them so the URL stays a single inert token.
-        const imgSrc = encodeMdUrl(imgAttrs.src);
-        // A bare image (only src/alt, optionally a title) has no caption, so the
-        // lighter markdown form is lossless here; captioned images took the
-        // imageToHtml branch above.
-        return `![${imgAlt}](${imgSrc})`;
-      }
-
-      case "video": {
-        // Emit the schema-matching <video> element so generateJSON rebuilds the
-        // node with its attrs intact. The schema's parseHTML reads src/aria-label
-        // from the standard attributes and the remaining attrs from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.alt) parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        // Wrap in a block <div> so marked treats it as a block (a bare <video>
-        // is inline-level HTML and marked wraps it in <p>, leaving a spurious
-        // empty paragraph beside the hoisted block atom). The wrapper has no
-        // data-type, so the schema parser ignores it and just hoists the video.
-        return `<div><video ${parts.join(" ")}></video></div>`;
-      }
-
-      case "youtube": {
-        // Emit the schema-matching div[data-type="youtube"]; the schema reads
-        // src from data-src and width/height/align from data-* attributes.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="youtube"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "table": {
-        // A GFM pipe table cannot represent merged cells. If ANY cell carries
-        // colspan>1 or rowspan>1, a pipe table would corrupt the grid on
-        // re-import, so emit the WHOLE table as raw HTML <table> instead: the
-        // schema's table family parseHTML (tag table/tr/td/th, with colspan/
-        // rowspan read from the same-named HTML attrs and align via parseHTML)
-        // round-trips it faithfully. Otherwise keep the lighter GFM pipe table.
-        const tableRows: any[] = nodeContent;
-        if (tableRows.length === 0) return "";
-        const hasSpan = tableRows.some((row: any) =>
-          (row.content || []).some(
-            (cell: any) =>
-              (cell.attrs?.colspan ?? 1) > 1 || (cell.attrs?.rowspan ?? 1) > 1,
-          ),
-        );
-        // A GFM pipe table also cannot hold a cell with block content (a list,
-        // code block, paragraphs) — it would be flattened to one line and lost
-        // (review #8). Force the HTML form for those too.
-        const hasMultiBlockCell = tableRows.some((row: any) =>
-          (row.content || []).some((cell: any) => cellIsMultiBlock(cell)),
-        );
-
-        if (hasSpan || hasMultiBlockCell) {
-          return tableToHtml(tableRows);
-        }
-
-        // No merged cells: emit a GFM table (header row + separator) so the
-        // markdown can be parsed back into a table on re-import.
-        const rows = tableRows.map(processNode);
-        const headerCells = tableRows[0]?.content || [];
-        const columns = headerCells.length || 1;
-        // Derive alignment markers (:--, :-:, --:) from each header cell.
-        const markers = Array.from({ length: columns }, (_, i) => {
-          const align = headerCells[i]?.attrs?.align;
-          switch (align) {
-            case "left":
-              return ":--";
-            case "center":
-              return ":-:";
-            case "right":
-              return "--:";
-            default:
-              return "---";
-          }
-        });
-        const separator = "| " + markers.join(" | ") + " |";
-        return [rows[0], separator, ...rows.slice(1)].join("\n");
-      }
-
-      case "tableRow":
-        return "| " + nodeContent.map(processNode).join(" | ") + " |";
-
-      case "tableCell":
-      case "tableHeader": {
-        // Join multiple block children with a space (not "") so adjacent blocks
-        // like a paragraph followed by a list don't collide into "line1- a".
-        // Then collapse newlines and escape pipes so a cell containing "|" or a
-        // line break cannot corrupt the surrounding GFM row.
-        return nodeContent
-          .map(processNode)
-          .join(" ")
-          .replace(/\r?\n/g, " ")
-          .replace(/\|/g, "\\|");
-      }
-
-      case "callout": {
-        // Obsidian-native callout: `> [!type]` opener + a blockquote (`>`-prefixed)
-        // body, so it renders as a callout in Obsidian. The importer parses both
-        // this and the legacy `:::type` fence (existing vaults). Each body line is
-        // blockquote-prefixed; a blank line becomes a bare `>` so the callout is
-        // not split.
-        const calloutType = (node.attrs?.type || "info").toLowerCase();
-        const calloutBody = nodeContent
-          .map(processNode)
-          .join("\n")
-          .split("\n")
-          .map((l: string) => (l.length ? `> ${l}` : ">"))
-          .join("\n");
-        return `> [!${calloutType}]\n${calloutBody}`;
-      }
-
-      case "details": {
-        // The `open` (collapsed/expanded) state lives on the details node, NOT on
-        // the summary, so emit the <details> wrapper HERE carrying it — otherwise
-        // the open state is dropped on a round trip. The schema's details node
-        // parses `open` back from the attribute.
-        const open = node.attrs?.open ? " open" : "";
-        return `<details${open}>\n${nodeContent.map(processNode).join("")}</details>`;
-      }
-
-      case "detailsSummary":
-        return `<summary>${nodeContent.map(processNode).join("")}</summary>\n\n`;
-
-      case "detailsContent":
-        return `${nodeContent.map(processNode).join("\n")}\n`;
-
-      case "mathInline": {
-        // The schema's `text` attribute has no parseHTML, so TipTap's default
-        // parser reads it from the `text` HTML attribute (NOT the element's text
-        // content). Emit span[data-type="mathInline"] carrying the LaTeX in a
-        // `text="..."` attribute so it round-trips. marked cannot parse $...$
-        // back, so the previous form was lossy.
-        const inlineMath = node.attrs?.text || "";
-        return `<span data-type="mathInline" data-katex="true" text="${escapeAttr(inlineMath)}"></span>`;
-      }
-
-      case "mathBlock": {
-        // Same as mathInline: the LaTeX must ride in the `text` HTML attribute
-        // for the schema's default parser to recover it.
-        const blockMath = node.attrs?.text || "";
-        return `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(blockMath)}"></div>`;
-      }
-
-      case "mention": {
-        // Emit span[data-type="mention"] with the schema's data-* attributes so
-        // generateJSON rebuilds the mention node instead of leaving "@label"
-        // plain text that cannot re-parse.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="mention"`];
-        if (attrs.id) parts.push(`data-id="${escapeAttr(attrs.id)}"`);
-        if (attrs.label)
-          parts.push(`data-label="${escapeAttr(attrs.label)}"`);
-        if (attrs.entityType)
-          parts.push(`data-entity-type="${escapeAttr(attrs.entityType)}"`);
-        if (attrs.entityId)
-          parts.push(`data-entity-id="${escapeAttr(attrs.entityId)}"`);
-        if (attrs.slugId)
-          parts.push(`data-slug-id="${escapeAttr(attrs.slugId)}"`);
-        if (attrs.creatorId)
-          parts.push(`data-creator-id="${escapeAttr(attrs.creatorId)}"`);
-        if (attrs.anchorId)
-          parts.push(`data-anchor-id="${escapeAttr(attrs.anchorId)}"`);
-        // Keep the label as visible text content too; the schema reads attrs
-        // from data-*, so the inner text is purely cosmetic and harmless.
-        const mentionLabel = attrs.label || attrs.id || "";
-        // The label is visible element TEXT content here (the data-* attrs above
-        // carry the real values), so escape it for the text context, not attrs.
-        return `<span ${parts.join(" ")}>@${escapeHtmlText(mentionLabel)}</span>`;
-      }
-
-      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
-        // schema-matching div[data-type="attachment"] with data-attachment-*
-        // attrs so the node round-trips instead of degrading to a markdown link.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="attachment"`,
-          `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
-        ];
-        if (attrs.name)
-          parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.mime)
-          parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
-        if (attrs.size != null)
-          parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "drawio":
-      case "excalidraw": {
-        // Emit the schema-matching div[data-type=...] carrying the diagram's
-        // attrs as data-* (the schema's diagramAttributes reads src/title/alt/
-        // width/height/size/aspectRatio/align/attachmentId from data-*), so the
-        // diagram round-trips instead of degrading to a lossy placeholder.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="${type}"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.title != null)
-          parts.push(`data-title="${escapeAttr(attrs.title)}"`);
-        if (attrs.alt != null) parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "embed": {
-        // Emit the schema-matching div[data-type="embed"]; the schema reads
-        // src/provider/align/width/height from data-* attributes so the node
-        // (and its provider iframe info) survives the round-trip.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="embed"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-          `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
-        ];
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "audio": {
-        // Emit the schema-matching <audio> element (was emitting nothing). The
-        // schema reads src from src and attachmentId/size from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        // Wrap in a block <div> for the same reason as video: a bare <audio> is
-        // inline-level HTML that marked would wrap in <p>.
-        return `<div><audio ${parts.join(" ")}></audio></div>`;
-      }
-
-      case "pdf": {
-        // Emit the schema-matching div[data-type="pdf"] (was emitting nothing).
-        // The schema reads src/width/height from standard attrs and name/
-        // attachmentId/size from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="pdf"`,
-          `src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.name) parts.push(`data-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "columns": {
-        // Emit the schema-matching div[data-type="columns"] wrapper so the
-        // multi-column layout survives. Without a case the children were
-        // concatenated with no separator and the text merged. The schema reads
-        // layout from data-layout and widthMode from data-width-mode. The whole
-        // block is raw HTML, so render children via blockToHtml (NOT markdown,
-        // which marked would not re-parse inside a raw HTML block).
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="columns"`];
-        if (attrs.layout)
-          parts.push(`data-layout="${escapeAttr(attrs.layout)}"`);
-        if (attrs.widthMode && attrs.widthMode !== "normal")
-          parts.push(`data-width-mode="${escapeAttr(attrs.widthMode)}"`);
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div ${parts.join(" ")}>${inner}</div>`;
-      }
-
-      case "column": {
-        // Emit the schema-matching div[data-type="column"]; the schema reads the
-        // column width from data-width. Children are rendered as HTML so their
-        // formatting survives inside this raw HTML block.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="column"`];
-        if (attrs.width)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div ${parts.join(" ")}>${inner}</div>`;
-      }
-
-      case "pageBreak":
-        // Emit the schema-matching div[data-type="pageBreak"] so marked passes
-        // it through as a block and generateJSON rebuilds the pageBreak atom.
-        // Without this case the node fell through to `default` and rendered ""
-        // (the divider silently disappeared and could not round-trip).
-        return `<div data-type="pageBreak"></div>`;
-
-      case "subpages": {
-        // Emit the schema-matching div[data-type="subpages"] so marked passes it
-        // through as a block and generateJSON rebuilds the subpages atom. The old
-        // `{{SUBPAGES}}` literal had no parseHTML inverse, so on import it stayed
-        // as plain text — the embed rendered as the literal "{{SUBPAGES}}" on the
-        // page after a round-trip (red-team: subpages round-trip data loss).
-        // `data-recursive` carries the recursive toggle so it round-trips too.
-        const recursive = node.attrs?.recursive ? ` data-recursive="true"` : "";
-        return `<div data-type="subpages"${recursive}></div>`;
-      }
-
-      case "status": {
-        // Inline status pill. The schema reads the label from the element's
-        // TEXT content and the color from data-color, so emit both; without a
-        // case this inline atom fell through to `default` and collapsed to "".
-        const attrs = node.attrs || {};
-        const statusColor = attrs.color || "gray";
-        return `<span data-type="status" data-color="${escapeAttr(statusColor)}">${escapeHtmlText(attrs.text ?? "")}</span>`;
-      }
-
-      case "htmlEmbed": {
-        // Block atom; the schema reads the raw source from a base64-encoded
-        // data-source attribute (and an optional fixed height from data-height).
-        // Encode with the shared helper so it decodes symmetrically on import.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="htmlEmbed"`,
-          `data-source="${escapeAttr(encodeHtmlEmbedSource(attrs.source ?? ""))}"`,
-        ];
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "footnoteReference": {
-        // Inline atom marker. The schema reads its id from data-id on a
-        // sup[data-footnote-ref]; the visible number is derived, not stored.
-        const attrs = node.attrs || {};
-        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
-        return `<sup data-footnote-ref${idAttr}></sup>`;
-      }
-
-      case "footnotesList": {
-        // Bottom container of footnote definitions (section[data-footnotes]).
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<section data-footnotes>${inner}</section>`;
-      }
-
-      case "footnoteDefinition": {
-        // One footnote note keyed by id (div[data-footnote-def]).
-        const attrs = node.attrs || {};
-        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div data-footnote-def${idAttr}>${inner}</div>`;
-      }
-
-      case "pageEmbed": {
-        // Whole-page live embed; the schema reads data-source-page-id.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="pageEmbed"`];
-        if (attrs.sourcePageId)
-          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "transclusionReference": {
-        // Live reference to a transcluded block/page. Block atom; the schema
-        // reads data-source-page-id and data-transclusion-id.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="transclusionReference"`];
-        if (attrs.sourcePageId)
-          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
-        if (attrs.transclusionId)
-          parts.push(
-            `data-transclusion-id="${escapeAttr(attrs.transclusionId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "transclusionSource": {
-        // Sync-source container; the schema reads data-id and re-parses its
-        // block children, so render them as schema-matching HTML.
-        const attrs = node.attrs || {};
-        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div data-type="transclusionSource"${idAttr}>${inner}</div>`;
-      }
-
-      default:
-        // Fallback: process children
-        return nodeContent.map(processNode).join("");
-    }
-  };
-
-  // Render inline content (text runs + their marks) to HTML. Used by the raw
-  // HTML fallbacks (spanned tables, columns) where marked will NOT re-parse
-  // markdown, so backtick/asterisk/bracket syntax would otherwise leak as
-  // literal characters. Each mark is mirrored to the HTML the schema's parseHTML
-  // accepts so it re-imports as the matching ProseMirror mark.
-  const inlineToHtml = (inlineNodes: any[]): string =>
-    (inlineNodes || [])
-      .map((n: any) => {
-        if (n.type === "hardBreak") return "<br>";
-        if (n.type !== "text") {
-          // Inline atoms (mention, mathInline) already emit schema HTML.
-          return processNode(n);
-        }
-        let t = escapeHtmlText(n.text || "");
-        for (const mark of n.marks || []) {
-          switch (mark.type) {
-            case "bold":
-              t = `<strong>${t}</strong>`;
-              break;
-            case "italic":
-              t = `<em>${t}</em>`;
-              break;
-            case "code":
-              t = `<code>${t}</code>`;
-              break;
-            case "strike":
-              t = `<s>${t}</s>`;
-              break;
-            case "underline":
-              t = `<u>${t}</u>`;
-              break;
-            case "subscript":
-              t = `<sub>${t}</sub>`;
-              break;
-            case "superscript":
-              t = `<sup>${t}</sup>`;
-              break;
-            case "link":
-              t = `<a href="${escapeAttr(mark.attrs?.href || "")}">${t}</a>`;
-              break;
-            case "highlight":
-              t = mark.attrs?.color
-                ? `<mark style="background-color: ${escapeAttr(mark.attrs.color)}">${t}</mark>`
-                : `<mark>${t}</mark>`;
-              break;
-            case "textStyle":
-              if (mark.attrs?.color)
-                t = `<span style="color: ${escapeAttr(mark.attrs.color)}">${t}</span>`;
-              break;
-            case "comment":
-              // Inline comment anchor inside a raw-HTML container (columns /
-              // spanned table cells), so commented text there also round-trips.
-              if (mark.attrs?.commentId) {
-                const r = mark.attrs?.resolved ? ` data-resolved="true"` : "";
-                t = `<span data-comment-id="${escapeAttr(mark.attrs.commentId)}"${r}>${t}</span>`;
-              }
-              break;
-          }
-        }
-        return t;
-      })
-      .join("");
-
-  // Emit the schema-matching <img> for an image node. Shared so the image is
-  // emitted as real HTML wherever a raw-HTML container needs it (inside a column
-  // or a spanned table cell), where markdown `![](...)` would NOT be re-parsed
-  // and would survive as literal text. The Image extension reads src/alt from
-  // the standard attributes; the Docmost extra attrs (width/height/align/size/
-  // attachmentId/aspectRatio) are global attributes read from same-named DOM
-  // attributes, so emit them by name.
-  const imageToHtml = (node: any): string => {
-    const attrs = node.attrs || {};
-    const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-    if (attrs.alt) parts.push(`alt="${escapeAttr(attrs.alt)}"`);
-    if (attrs.title) parts.push(`title="${escapeAttr(attrs.title)}"`);
-    if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
-    if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
-    if (attrs.align) parts.push(`align="${escapeAttr(attrs.align)}"`);
-    if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-    if (attrs.attachmentId)
-      parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-    if (attrs.aspectRatio != null)
-      parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-    // Plain-text caption (issue #221). Markdown `![](src)` cannot carry it, so
-    // emit it as data-caption; the schema's image `caption` attr parses it back.
-    if (attrs.caption) parts.push(`data-caption="${escapeAttr(attrs.caption)}"`);
-    return `<img ${parts.join(" ")}>`;
-  };
-
-  // Emit the schema-matching div[data-type="callout"] for a callout node. The
-  // schema reads the banner type from data-callout-type. Children are rendered
-  // as HTML so they survive inside a raw-HTML container.
-  const calloutToHtml = (node: any): string => {
-    const type = (node.attrs?.type || "info").toLowerCase();
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<div data-type="callout" data-callout-type="${escapeAttr(type)}">${inner}</div>`;
-  };
-
-  // Emit a schema-matching <details> tree. The schema parses <details>,
-  // summary[data-type="detailsSummary"], and div[data-type="detailsContent"].
-  // The `open` (collapsed/expanded) state lives on the details node and the
-  // schema parses it back from the attribute, so emit it here too — mirroring
-  // the top-level `details` case — or a NESTED details (inside columns/cells)
-  // would silently drop `open:true` every round trip.
-  const detailsToHtml = (node: any): string => {
-    const open = node.attrs?.open ? " open" : "";
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<details${open}>${inner}</details>`;
-  };
-  const detailsSummaryToHtml = (node: any): string =>
-    `<summary data-type="detailsSummary">${inlineToHtml(node.content || [])}</summary>`;
-  const detailsContentToHtml = (node: any): string => {
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<div data-type="detailsContent">${inner}</div>`;
-  };
-
-  // Emit the schema-matching taskList/taskItem HTML. bridgeTaskLists (in
-  // collaboration.ts) recognizes ul[data-type="taskList"] with
-  // li[data-type="taskItem"][data-checked]; emitting that directly here keeps
-  // task lists inside columns/cells from degrading to literal "- [ ]" text.
-  const taskListToHtml = (node: any): string => {
-    const items = (node.content || [])
-      .map((it: any) => {
-        const checked = it.attrs?.checked ? "true" : "false";
-        return `<li data-type="taskItem" data-checked="${checked}">${blockChildrenToHtml(it)}</li>`;
-      })
-      .join("");
-    return `<ul data-type="taskList">${items}</ul>`;
-  };
-
-  // Render a block node to HTML for the raw-HTML containers (spanned tables,
-  // columns). marked does NOT re-parse markdown inside a raw-HTML block, so
-  // EVERY block type that can appear inside a column or a spanned cell must be
-  // emitted as schema-matching HTML here — never as markdown, or it would land
-  // as literal text on re-import. Nodes whose processNode case already produces
-  // schema-matching HTML (math/media/embed/attachment/nested columns/spanned
-  // table) are delegated to processNode; the markdown-emitting cases
-  // (image/blockquote/callout/details/hr/taskList) get explicit HTML here.
-  const blockToHtml = (block: any): string => {
-    const children = block.content || [];
-    switch (block.type) {
-      case "paragraph": {
-        // Carry textAlign here too (symmetric with the processNode paragraph
-        // case): a paragraph nested inside an HTML container (column/table/
-        // callout) would otherwise drop its alignment on the round trip.
-        const pAlign = block.attrs?.textAlign;
-        const pStyle =
-          pAlign && pAlign !== "left"
-            ? ` style="text-align:${escapeAttr(pAlign)}"`
-            : "";
-        return `<p${pStyle}>${inlineToHtml(children)}</p>`;
-      }
-      case "heading": {
-        // Same for a heading nested in an HTML container: emit the alignment as
-        // an inline style (symmetric with the processNode heading case) so it is
-        // not silently dropped. Clamp the level to a valid HTML heading tag.
-        const level = Math.min(6, Math.max(1, block.attrs?.level || 1));
-        const hAlign = block.attrs?.textAlign;
-        const hStyle =
-          hAlign && hAlign !== "left"
-            ? ` style="text-align:${escapeAttr(hAlign)}"`
-            : "";
-        return `<h${level}${hStyle}>${inlineToHtml(children)}</h${level}>`;
-      }
-      case "bulletList":
-        return `<ul>${children
-          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
-          .join("")}</ul>`;
-      case "orderedList":
-        return `<ol>${children
-          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
-          .join("")}</ol>`;
-      case "codeBlock": {
-        const lang = block.attrs?.language || "";
-        // The code itself is element TEXT content (between <code> tags), so it
-        // must escape < > & — NOT the attribute escaper. The language rides in
-        // a class ATTRIBUTE, so it uses escapeAttr.
-        const code = escapeHtmlText(
-          children
-            .map(processNode)
-            .join("")
-            .replace(/\n+$/, ""),
-        );
-        const cls = lang ? ` class="language-${escapeAttr(lang)}"` : "";
-        return `<pre><code${cls}>${code}</code></pre>`;
-      }
-      case "image":
-        return imageToHtml(block);
-      case "blockquote":
-        return `<blockquote>${children.map(blockToHtml).join("")}</blockquote>`;
-      case "horizontalRule":
-        return "<hr>";
-      case "callout":
-        return calloutToHtml(block);
-      case "details":
-        return detailsToHtml(block);
-      case "detailsSummary":
-        return detailsSummaryToHtml(block);
-      case "detailsContent":
-        return detailsContentToHtml(block);
-      case "taskList":
-        return taskListToHtml(block);
-      case "taskItem":
-        // A bare taskItem (outside a taskList) still needs a wrapping list so
-        // the schema parses it; wrap it in a single-item taskList.
-        return taskListToHtml({ content: [block] });
-      // A table nested in a raw-HTML block (e.g. inside a column) MUST be the
-      // HTML <table> form — a GFM pipe table here would not be re-parsed by
-      // marked and would round-trip as literal "| a | b |" text (review #7).
-      case "table":
-        return tableToHtml(block.content || []);
-      // columns/column, math, media, embed, attachment, mention, etc. already
-      // emit schema-matching HTML from processNode.
-      case "columns":
-      case "column":
-      case "mathBlock":
-      case "video":
-      case "audio":
-      case "pdf":
-      case "youtube":
-      case "embed":
-      case "attachment":
-      case "drawio":
-      case "excalidraw":
-      case "htmlEmbed":
-      case "footnotesList":
-      case "footnoteDefinition":
-      case "pageEmbed":
-      case "transclusionSource":
-      case "transclusionReference":
-        return processNode(block);
-      default:
-        // Any still-unhandled block type: NEVER fall back to markdown inside a
-        // raw-HTML block (it would become literal text). Wrap its rendered
-        // children in a <div> so their content is preserved; if it has no block
-        // children, render its inline content instead.
-        if (children.length && children.some((c: any) => c.type !== "text")) {
-          return `<div>${children.map(blockToHtml).join("")}</div>`;
-        }
-        return `<div>${inlineToHtml(children)}</div>`;
-    }
-  };
-
-  // Render the block children of a list item to HTML (a listItem holds block+
-  // content). Mirrors processListItem but for the HTML fallback path.
-  const blockChildrenToHtml = (item: any): string =>
-    (item.content || []).map((b: any) => blockToHtml(b)).join("");
-
-  // Indent the rendered children of a list item under a marker prefix.
-  // Each child block is a (possibly multi-line) string. The very first physical
-  // line of the first child carries the marker (e.g. "- " or "1. "); EVERY
-  // other line — the remaining lines of the first child AND all lines of every
-  // subsequent child (nested lists, code blocks, extra paragraphs) — is indented
-  // to align under the marker. Without indenting these continuation lines, the
-  // 2nd/3rd line of a nested child collapses to column 0 and escapes the list.
-  //
-  // The continuation indent MUST equal the LIST marker width, which is not the
-  // same as the visible prefix width:
-  //   - bullet "- "          -> 2 columns
-  //   - task   "- [ ] "      -> marker is still "- " (the "[ ] " is content), 2
-  //   - ordered "1. "/"10. " -> 3/4 columns, scaling with the number's digits
-  // CommonMark anchors nested content to the marker column, so an ordered item
-  // indented to only 2 columns would be re-parsed as a sibling/loose content on
-  // re-import. Callers therefore pass the exact indent width to use.
-  const indentItemChildren = (
-    childStrings: string[],
-    prefix: string,
-    indentWidth: number,
-  ): string => {
-    const indent = " ".repeat(indentWidth);
-    const lines: string[] = [];
-    childStrings.forEach((child, childIndex) => {
-      child.split("\n").forEach((line, lineIndex) => {
-        if (childIndex === 0 && lineIndex === 0) {
-          // First physical line of the first block gets the marker.
-          lines.push(`${prefix} ${line}`);
-        } else {
-          // Indent every continuation line by the marker width; keep blank
-          // lines blank rather than emitting trailing whitespace.
-          lines.push(line.length ? `${indent}${line}` : "");
-        }
-      });
-    });
-    return lines.join("\n");
-  };
-
-  const processListItem = (item: any, prefix: string): string => {
-    const itemContent = item.content || [];
-    const childStrings = itemContent.map(processNode);
-    if (childStrings.length === 0) return prefix;
-    // The rendered marker is `${prefix} ` (prefix + one space), so its width —
-    // and thus the continuation indent — is prefix.length + 1. This is correct
-    // for both bullet ("-" -> 2) and ordered ("1." -> 3, "10." -> 4) markers,
-    // since for those the visible prefix IS the list marker.
-    return indentItemChildren(childStrings, prefix, prefix.length + 1);
-  };
-
-  const processTaskItem = (item: any): string => {
-    const checked = item.attrs?.checked || false;
-    const checkbox = checked ? "[x]" : "[ ]";
-    const prefix = `- ${checkbox}`;
-    const itemContent = item.content || [];
-    const childStrings = itemContent.map(processNode);
-    // An empty task item still needs its checkbox marker; without this guard
-    // the indent below produces "" and the "- [ ]"/"- [x]" row disappears.
-    if (childStrings.length === 0) return prefix;
-    // The list marker for a task item is just "- " (2 columns); the "[ ] "/"[x] "
-    // checkbox is item content, NOT part of the marker. So the continuation
-    // indent is a fixed 2 — do NOT derive it from the wider prefix.length.
-    return indentItemChildren(childStrings, prefix, 2);
-  };
-
-  return processNode(content).trim();
-}
diff --git a/packages/git-sync/src/lib/markdown-document.ts b/packages/git-sync/src/lib/markdown-document.ts
deleted file mode 100644
index 8f4953ea..00000000
--- a/packages/git-sync/src/lib/markdown-document.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-/**
- * Self-contained Docmost-flavoured Markdown document (custom extensions).
- *
- * A single `.md` file that packages everything needed to losslessly round-trip
- * a page through "download -> edit body -> re-upload":
- *   - a leading `docmost:meta` block: a one-line JSON object with page identity;
- *   - the Markdown body (carrying inline comment anchors and diagrams as HTML);
- *   - a trailing `docmost:comments` block: a one-line JSON array of comment
- *     threads.
- *
- * Both metadata blocks are HTML comments on purpose: `marked`/`generateJSON`
- * drop HTML comments, so even if the WHOLE file were ever fed straight to the
- * importer without first stripping the blocks, the metadata cannot leak into the
- * document. (A fenced ```docmost-comments``` block would WRONGLY become a
- * codeBlock node, so a fenced block is deliberately NOT used.)
- *
- * The delimiter literals may legitimately appear in the BODY too (e.g. a user
- * re-pastes an exported `.md` into a page, or a page documents this very
- * format). To stay robust, parsing treats only the FINAL, document-ending
- * `docmost:comments` block as metadata: it is the last `<!-- docmost:comments`
- * opener whose closing `-->` sits at the very end of the file. Any earlier
- * literal occurrence is left in the body untouched.
- *
- * NOTE on comments: in this version the comment THREAD records are preserved in
- * the file but are NOT pushed back to the server on import — only the inline
- * comment marks (anchors) embedded in the body are restored. Managing comment
- * records stays with the comment tools/UI.
- */
-
-export interface DocmostMdMeta {
-  version: number;
-  pageId?: string;
-  slugId?: string;
-  title?: string;
-  spaceId?: string;
-  parentPageId?: string | null;
-}
-
-// Match the leading meta block (allow leading whitespace). Capture group 1 is
-// the JSON text between the markers.
-const META_RE = /^\s*<!--\s*docmost:meta\s*\n([\s\S]*?)\n-->/;
-// Match a `docmost:comments` opener. Used globally to scan for the LAST opener
-// rather than end-anchoring a single regex (which would mis-capture across a
-// literal opener that appears earlier in the body).
-const COMMENTS_OPEN_RE = /<!--[ \t]*docmost:comments[ \t]*\r?\n/g;
-
-/**
- * Assemble the full self-contained markdown file: meta block, body, and the
- * comments block. The meta block is always emitted; the comments block is always
- * emitted too (with `[]` when there are no comments) so the format stays uniform
- * and parsing stays simple.
- */
-export function serializeDocmostMarkdown(
-  meta: DocmostMdMeta,
-  body: string,
-  comments: any[],
-): string {
-  const metaJson = JSON.stringify(meta);
-  const commentsJson = JSON.stringify(Array.isArray(comments) ? comments : []);
-  const trimmedBody = (body ?? "").trim();
-  return (
-    `<!-- docmost:meta\n${metaJson}\n-->\n\n` +
-    `${trimmedBody}\n\n` +
-    `<!-- docmost:comments\n${commentsJson}\n-->\n`
-  );
-}
-
-/**
- * Split a self-contained file back into its parts. Tolerant: if the meta or
- * comments block is missing (e.g. a hand-written plain-markdown file), the
- * corresponding value is returned as `null` and the whole input is treated as
- * the body. This never throws on a MISSING block; only a `JSON.parse` failure
- * inside a block that IS present is surfaced as a thrown Error with a clear
- * message. Robust to `\r\n` line endings.
- */
-export function parseDocmostMarkdown(full: string): {
-  meta: DocmostMdMeta | null;
-  body: string;
-  comments: any[] | null;
-} {
-  // Normalize line endings so the anchored regexes work regardless of CRLF.
-  const normalized = (full ?? "").replace(/\r\n/g, "\n");
-
-  // Extract the leading meta block (start-anchored — already unambiguous).
-  let meta: DocmostMdMeta | null = null;
-  let metaEnd = 0;
-  const metaMatch = normalized.match(META_RE);
-  if (metaMatch) {
-    try {
-      meta = JSON.parse(metaMatch[1]);
-    } catch (e) {
-      throw new Error(
-        `Invalid docmost:meta JSON block: ${
-          e instanceof Error ? e.message : String(e)
-        }`,
-      );
-    }
-    // Body starts right after the matched meta block.
-    metaEnd = (metaMatch.index ?? 0) + metaMatch[0].length;
-  }
-
-  // Find the LAST `<!-- docmost:comments` opener; the real file-level block is
-  // the final one whose closing `-->` ends the document. Any earlier literal
-  // occurrence inside the body (e.g. a re-pasted export) is left in the body.
-  let lastOpenStart = -1;
-  let lastOpenEnd = -1;
-  let m: RegExpExecArray | null;
-  COMMENTS_OPEN_RE.lastIndex = 0;
-  while ((m = COMMENTS_OPEN_RE.exec(normalized)) !== null) {
-    lastOpenStart = m.index;
-    lastOpenEnd = m.index + m[0].length;
-  }
-
-  let comments: any[] | null = null;
-  let bodyEnd = normalized.length;
-  if (lastOpenStart !== -1) {
-    const rest = normalized.slice(lastOpenEnd);
-    const close = rest.match(/\r?\n-->[ \t]*\r?\n?\s*$/); // closer must end the doc
-    if (close) {
-      const jsonText = rest.slice(0, close.index);
-      try {
-        comments = JSON.parse(jsonText);
-      } catch (e) {
-        throw new Error(
-          `Invalid docmost:comments JSON block: ${
-            e instanceof Error ? e.message : String(e)
-          }`,
-        );
-      }
-      bodyEnd = lastOpenStart; // strip from the opener to end of document
-    }
-  }
-
-  const body = normalized.slice(metaEnd, bodyEnd).trim();
-  return { meta, body, comments };
-}
-
-/**
- * Serialize a self-contained markdown file with the meta block + body ONLY —
- * NO trailing `docmost:comments` block. The sync engine never touches
- * `/comments` (SPEC §3): the synced file carries just page identity (meta) and
- * the body, where comment threads survive only as inline `<span
- * data-comment-id>` anchor marks inside the body.
- *
- * `parseDocmostMarkdown` already tolerates a missing comments block (it returns
- * `comments: null` and treats the rest as body), so a file produced here
- * round-trips cleanly through the parser.
- */
-export function serializeDocmostMarkdownBody(
-  meta: DocmostMdMeta,
-  body: string,
-): string {
-  return `<!-- docmost:meta\n${JSON.stringify(meta)}\n-->\n\n${(body ?? "").trim()}\n`;
-}
diff --git a/packages/git-sync/src/lib/markdown-to-prosemirror.ts b/packages/git-sync/src/lib/markdown-to-prosemirror.ts
deleted file mode 100644
index 4466edf4..00000000
--- a/packages/git-sync/src/lib/markdown-to-prosemirror.ts
+++ /dev/null
@@ -1,365 +0,0 @@
-/**
- * Pure markdown -> ProseMirror conversion.
- *
- * The converter path is `markdownToProseMirror` (marked -> HTML ->
- * generateJSON) plus the two pre/post processors it needs (`preprocessCallouts`,
- * `bridgeTaskLists`). The gitmost server writes the resulting page bodies
- * natively through the collab gateway, so no websocket/Yjs write-path lives
- * here.
- */
-import { generateJSON } from "@tiptap/html";
-import { JSDOM } from "jsdom";
-import { marked } from "marked";
-import { docmostExtensions } from "./docmost-schema.js";
-
-// Setup DOM environment for Tiptap HTML parsing in Node.js
-const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
-global.window = dom.window as any;
-global.document = dom.window.document;
-// @ts-ignore
-global.Element = dom.window.Element;
-
-/**
- * Hard ceiling above which we skip callout preprocessing entirely. The linear
- * scanner below has no quadratic blow-up, but we still cap input defensively so
- * a pathological multi-megabyte payload cannot tie up the event loop; in that
- * case the markdown is passed through verbatim (callouts are simply not
- * detected) rather than risking a slow scan.
- */
-const MAX_CALLOUT_PREPROCESS_BYTES = 4 * 1024 * 1024; // 4 MB
-
-/** Matches an opening callout fence: `:::type` (type captured, lower-cased). */
-const CALLOUT_OPEN_RE = /^:::\s*(\w+)\s*$/;
-/** Matches a bare closing callout fence: `:::`. */
-const CALLOUT_CLOSE_RE = /^:::\s*$/;
-/**
- * Matches an Obsidian-native callout opener: `> [!type]` (type captured). An
- * optional title after the type is allowed but ignored (the Docmost callout
- * schema has no title). The body is the following contiguous blockquote lines.
- */
-const CALLOUT_BQ_OPEN_RE = /^>\s*\[!(\w+)\]/;
-/** Matches any blockquote continuation line (`>` … ). */
-const BLOCKQUOTE_LINE_RE = /^>/;
-/** Matches the start/end of a code fence (``` or ~~~), capturing the marker. */
-const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
-
-/**
- * Pre-process Docmost-flavoured markdown: convert `:::type ... :::`
- * callout blocks (the syntax our markdown export produces) into HTML
- * divs that the callout extension parses. The inner content is rendered
- * through marked as regular markdown.
- *
- * Implemented as a single linear pass over the lines (no quadratic regex
- * rescan). It:
- *   - tracks fenced code regions (```...``` and ~~~...~~~) and never treats a
- *     `:::` line that lives inside a code fence as a callout delimiter, so a
- *     callout body that itself contains a fenced code block with a `:::` line is
- *     no longer corrupted;
- *   - matches an opening `:::type` line with the next CLOSING `:::` at the SAME
- *     nesting level, supporting NESTED callouts via a depth counter (an inner
- *     `:::type` opens a deeper level and consumes a matching `:::`);
- *   - emits the same `<div data-type="callout" data-callout-type="TYPE">` output
- *     (inner rendered through marked) as the previous regex implementation.
- */
-async function preprocessCallouts(markdown: string): Promise<string> {
-  // Defensive cap: skip preprocessing for pathologically large inputs.
-  if (markdown.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-    return markdown;
-  }
-
-  // Recursively transform a slice of lines, converting top-level callouts in
-  // that slice into <div> blocks and rendering their inner content (which may
-  // itself contain nested callouts) through this same function.
-  const transform = async (lines: string[]): Promise<string> => {
-    const out: string[] = [];
-    let inCodeFence = false;
-    let codeFenceMarker = ""; // the exact run of backticks/tildes that opened it
-    let i = 0;
-
-    while (i < lines.length) {
-      const line = lines[i];
-
-      // Inside a code fence, only its matching closing fence is significant;
-      // everything else (including `:::` lines) is copied through verbatim.
-      if (inCodeFence) {
-        out.push(line);
-        const fence = line.match(CODE_FENCE_RE);
-        if (fence && fence[2].startsWith(codeFenceMarker[0]) &&
-            fence[2].length >= codeFenceMarker.length) {
-          inCodeFence = false;
-          codeFenceMarker = "";
-        }
-        i++;
-        continue;
-      }
-
-      // A code fence opening outside any callout body: enter code-fence mode.
-      const fenceOpen = line.match(CODE_FENCE_RE);
-      if (fenceOpen) {
-        inCodeFence = true;
-        codeFenceMarker = fenceOpen[2];
-        out.push(line);
-        i++;
-        continue;
-      }
-
-      // An opening callout fence: scan forward (with code-fence and nested
-      // callout awareness) for its matching closing `:::` at the same level.
-      const open = line.match(CALLOUT_OPEN_RE);
-      if (open) {
-        const type = open[1].toLowerCase();
-        const bodyLines: string[] = [];
-        let depth = 1;
-        let innerInCodeFence = false;
-        let innerCodeFenceMarker = "";
-        let j = i + 1;
-        for (; j < lines.length; j++) {
-          const bl = lines[j];
-          if (innerInCodeFence) {
-            const f = bl.match(CODE_FENCE_RE);
-            if (f && f[2].startsWith(innerCodeFenceMarker[0]) &&
-                f[2].length >= innerCodeFenceMarker.length) {
-              innerInCodeFence = false;
-              innerCodeFenceMarker = "";
-            }
-            bodyLines.push(bl);
-            continue;
-          }
-          const innerFence = bl.match(CODE_FENCE_RE);
-          if (innerFence) {
-            innerInCodeFence = true;
-            innerCodeFenceMarker = innerFence[2];
-            bodyLines.push(bl);
-            continue;
-          }
-          if (CALLOUT_OPEN_RE.test(bl)) {
-            depth++;
-            bodyLines.push(bl);
-            continue;
-          }
-          if (CALLOUT_CLOSE_RE.test(bl)) {
-            depth--;
-            if (depth === 0) break; // matching close for THIS callout
-            bodyLines.push(bl);
-            continue;
-          }
-          bodyLines.push(bl);
-        }
-
-        if (j < lines.length) {
-          // Found the matching closing fence: render the body (recursively, so
-          // nested callouts are handled) and emit the callout div.
-          const inner = await transform(bodyLines);
-          const renderedInner = await marked.parse(inner);
-          out.push(
-            `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
-          );
-          i = j + 1; // skip past the closing `:::`
-          continue;
-        }
-        // No matching close (unterminated callout): treat the opener as a
-        // literal line and continue, preserving the original text.
-        out.push(line);
-        i++;
-        continue;
-      }
-
-      // An Obsidian-native callout: `> [!type]` opener; the body is the following
-      // CONTIGUOUS blockquote (`>`-prefixed) lines. Strip ONE blockquote level and
-      // recurse so nested callouts (`> > [!type]`) are handled, then emit the same
-      // callout div the `:::` path produces. A normal blockquote (no `[!type]` on
-      // its first line) does not match and stays a blockquote.
-      const bqOpen = line.match(CALLOUT_BQ_OPEN_RE);
-      if (bqOpen) {
-        const type = bqOpen[1].toLowerCase();
-        const bodyLines: string[] = [];
-        let j = i + 1;
-        for (; j < lines.length; j++) {
-          if (!BLOCKQUOTE_LINE_RE.test(lines[j])) break;
-          bodyLines.push(lines[j].replace(/^>\s?/, ""));
-        }
-        const inner = await transform(bodyLines);
-        const renderedInner = await marked.parse(inner);
-        out.push(
-          `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
-        );
-        i = j;
-        continue;
-      }
-
-      out.push(line);
-      i++;
-    }
-
-    return out.join("\n");
-  };
-
-  return transform(markdown.split("\n"));
-}
-
-/**
- * Bridge marked's checkbox lists to TipTap task lists.
- *
- * marked renders GitHub task list items (`- [x] done`) as a plain
- * `<ul><li><p><input type="checkbox" checked> text</p></li></ul>` WITHOUT the
- * markup TipTap's TaskList/TaskItem extensions parse. This rewrites such lists
- * into the shape those extensions expect:
- *   TaskList parseHTML matches `ul[data-type="taskList"]`,
- *   TaskItem matches `li[data-type="taskItem"]`,
- *   the checked state is read from `data-checked === "true"`.
- *
- * A list is only converted when it has at least one `<li>` and EVERY direct
- * `<li>` contains a checkbox input. Both `<ul>` and `<ol>` are considered: a
- * numbered checklist (`1. [x] a`, which marked renders as an `<ol>` of checkbox
- * `<li>`s) would otherwise lose its task state. TipTap task lists are unordered,
- * so a matching `<ol>` is emitted as `data-type="taskList"` exactly like a
- * `<ul>`. Mixed or ordinary lists (including ordinary `<ol>` lists) are left
- * untouched so they keep rendering as bullet/numbered lists. The marked `<p>`
- * wrapper is kept inside the `<li>` because TaskItem content allows paragraphs.
- */
-function bridgeTaskLists(html: string): string {
-  // Cheap early-out: if the markup contains no checkbox input at all there is
-  // nothing to bridge, so skip the expensive JSDOM parse entirely. This is the
-  // common case (most pages have no task lists).
-  if (!/type=["']?checkbox/i.test(html)) {
-    return html;
-  }
-  // Defensive cap (consistent with preprocessCallouts): skip the bridge for
-  // pathologically large inputs rather than running a second expensive JSDOM
-  // parse on a multi-megabyte payload. The markup is passed through verbatim.
-  if (html.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-    return html;
-  }
-  const dom = new JSDOM(html);
-  const document = dom.window.document;
-  // Collect the checkbox(es) that belong to THIS <li> directly: either direct
-  // child <input type="checkbox"> elements or ones inside the <li>'s direct <p>
-  // child (the shape marked emits: `<li><p><input type="checkbox"> text</p></li>`).
-  // Checkboxes nested deeper (e.g. inside a child <ul>/<ol>) are excluded so a
-  // bullet <li> that merely contains a nested task sublist is not misdetected.
-  // Raw inline HTML can put more than one checkbox in a single <li>; we gather
-  // ALL of them so none survive into the converted item.
-  const directCheckboxes = (li: Element): Element[] => {
-    const found: Element[] = [];
-    for (const child of Array.from(li.children)) {
-      if (
-        child.tagName === "INPUT" &&
-        child.getAttribute("type") === "checkbox"
-      ) {
-        found.push(child);
-        continue;
-      }
-      if (child.tagName === "P") {
-        for (const inp of Array.from(
-          child.querySelectorAll(":scope > input[type='checkbox']"),
-        )) {
-          found.push(inp);
-        }
-      }
-    }
-    return found;
-  };
-  // Both <ul> and <ol> are candidates: an <ol> whose every direct <li> carries
-  // its own checkbox is a numbered checklist that must also become a taskList.
-  const lists = Array.from(document.querySelectorAll("ul, ol"));
-  for (const list of lists) {
-    // Only consider DIRECT child <li> elements; nested lists are handled by
-    // their own iteration of the outer loop.
-    const items = Array.from(list.children).filter(
-      (child) => child.tagName === "LI",
-    );
-    if (items.length === 0) continue;
-    const itemCheckboxes = items.map((li) => directCheckboxes(li));
-    // Convert only when every direct <li> carries at least one OWN checkbox.
-    if (!itemCheckboxes.every((boxes) => boxes.length > 0)) continue;
-
-    // A numbered checklist arrives as an <ol>. We must NOT leave the tag as
-    // <ol> while tagging it data-type="taskList": generateJSON would then match
-    // BOTH the orderedList rule (tag ol) and the taskList rule (data-type),
-    // emitting a phantom empty orderedList beside the real taskList. So rename a
-    // qualifying <ol> to a <ul> — move its <li> children over and replace it —
-    // leaving only the taskList rule to match. Already-<ul> lists are unchanged.
-    let target: Element = list;
-    if (list.tagName === "OL") {
-      const ul = document.createElement("ul");
-      // Carry over existing attributes (e.g. class) so nothing is silently lost.
-      for (const attr of Array.from(list.attributes)) {
-        ul.setAttribute(attr.name, attr.value);
-      }
-      // Move every child node (including the <li>s we collected) into the <ul>.
-      while (list.firstChild) {
-        ul.appendChild(list.firstChild);
-      }
-      list.replaceWith(ul);
-      target = ul;
-    }
-
-    target.setAttribute("data-type", "taskList");
-    items.forEach((li, index) => {
-      const boxes = itemCheckboxes[index];
-      // The first checkbox determines the checked state (matches the previous
-      // single-checkbox behaviour); any extras only need removing.
-      const input = boxes[0] ?? null;
-      li.setAttribute("data-type", "taskItem");
-      const checked =
-        input != null &&
-        (input.hasAttribute("checked") || (input as any).checked);
-      li.setAttribute("data-checked", checked ? "true" : "false");
-      // Remove ALL direct checkbox inputs so none survive into the content
-      // (a raw-inline-HTML <li> may carry more than one).
-      for (const box of boxes) {
-        box.remove();
-      }
-    });
-  }
-  return document.body.innerHTML;
-}
-
-/**
- * Recursively strip content-less paragraph nodes from a generated doc.
- *
- * A block-level atom whose markdown form is INLINE (e.g. the block `image`'s
- * `![](url)`, or a bare media element) is wrapped by marked in a <p>; the schema
- * then HOISTS the block atom out of that paragraph, leaving an EMPTY paragraph
- * sibling. On the next export that empty `<p>` renders to "" and the doc "\n\n"
- * join injects a phantom blank gap, so the markdown is not byte-stable.
- *
- * Markdown blank lines are separators, never content, so generateJSON only ever
- * produces an empty paragraph as such a hoist artifact — removing them is safe
- * and general (it also subsumes the <div>-wrapper workaround the `video` case
- * uses). We remove ONLY `type === 'paragraph'` nodes whose `content` is absent
- * or an empty array; every other node (including atoms without `content`) is
- * preserved, and we recurse into the content of any node that has children.
- */
-function stripEmptyParagraphs(node: any): any {
-  if (!node || !Array.isArray(node.content)) {
-    // Atom / leaf node (no children to recurse into): keep as-is.
-    return node;
-  }
-  const mapped = node.content.map((child: any) => stripEmptyParagraphs(child));
-  const isEmptyParagraph = (child: any): boolean =>
-    !!child &&
-    child.type === "paragraph" &&
-    (!Array.isArray(child.content) || child.content.length === 0);
-  const filtered = mapped.filter((child: any) => !isEmptyParagraph(child));
-  // Schema-validity guard: several nodes require NON-empty block content
-  // (`content: "block+"` — tableCell, tableHeader, blockquote, column, callout,
-  // and the doc root). For an empty one of those, generateJSON materializes a
-  // single empty paragraph as its OBLIGATORY content — that is not a hoist
-  // artifact. If stripping would empty the container, keep ONE empty paragraph
-  // so the result stays schema-valid (an empty cell/quote must not become `[]`).
-  const cleaned =
-    filtered.length === 0 && mapped.length > 0 ? [mapped[0]] : filtered;
-  return { ...node, content: cleaned };
-}
-
-/** 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 bridged = bridgeTaskLists(html);
-  const doc = generateJSON(bridged, docmostExtensions);
-  return stripEmptyParagraphs(doc);
-}
diff --git a/packages/git-sync/src/lib/node-ops.ts b/packages/git-sync/src/lib/node-ops.ts
deleted file mode 100644
index 4934b216..00000000
--- a/packages/git-sync/src/lib/node-ops.ts
+++ /dev/null
@@ -1,897 +0,0 @@
-/**
- * Pure, network-free helpers for manipulating a ProseMirror/TipTap document
- * tree by node id.
- *
- * A ProseMirror node here is a plain JSON object of the shape produced by
- * Docmost: `{ type, attrs?, content?, text?, marks? }`. Children live in the
- * `content` array; a node carries a stable id in `attrs.id`. Callouts and
- * table cells hold their children in `content` just like any other block, so a
- * single recursive walk reaches them all.
- *
- * Every exported function operates on a DEEP CLONE of the input document and
- * returns the new document. The input doc and any `newNode`/`node` argument are
- * never mutated. All functions are defensively null-safe: missing/!Array
- * `content`, non-object nodes, and absent `attrs` are tolerated.
- */
-
-/** Deep-clone a JSON-serializable value without mutating the original. */
-function clone<T>(value: T): T {
-  if (typeof structuredClone === "function") {
-    return structuredClone(value);
-  }
-  // Fallback for environments without structuredClone.
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-/** True if `value` is a non-null object (and not an array). */
-function isObject(value: any): value is Record<string, any> {
-  return value != null && typeof value === "object" && !Array.isArray(value);
-}
-
-/** True if `node` carries the given id in `node.attrs.id`. */
-function matchesId(node: any, nodeId: string): boolean {
-  return isObject(node) && isObject(node.attrs) && node.attrs.id === nodeId;
-}
-
-/**
- * Recursively concatenate all text contained in a node.
- *
- * Text nodes contribute their `text` string; container nodes contribute the
- * joined `blockPlainText` of their `content` children. Returns "" for nullish
- * or non-object inputs.
- */
-export function blockPlainText(node: any): string {
-  if (!isObject(node)) return "";
-  let out = "";
-  if (typeof node.text === "string") {
-    out += node.text;
-  }
-  if (Array.isArray(node.content)) {
-    for (const child of node.content) {
-      out += blockPlainText(child);
-    }
-  }
-  return out;
-}
-
-/** Truncate `text` to at most `n` chars, appending an ellipsis when cut. */
-function truncate(text: string, n: number): string {
-  return text.length > n ? text.slice(0, n) + "…" : text;
-}
-
-/** One compact outline entry for a single top-level block. */
-export interface OutlineEntry {
-  index: number;
-  type: string | undefined;
-  id: string | null;
-  firstText: string;
-  /** Present for headings only. */
-  level?: number | null;
-  /** Present for tables only. */
-  rows?: number;
-  cols?: number;
-  header?: string[];
-  /** Present for list blocks only (bulletList/orderedList/taskList). */
-  items?: number;
-}
-
-/**
- * Build a COMPACT outline of the TOP-LEVEL blocks of `doc` (the entries in
- * `doc.content`). Deliberately does NOT recurse into paragraphs, list items, or
- * table cells — compactness is the point; use `getNodeByRef` to drill into a
- * specific block.
- *
- * Each entry carries `{ index, type, id, firstText }`, plus type-specific
- * extras: headings add `level`; tables add `rows`/`cols` and the first row's
- * cell texts as `header`; list blocks (types ending in "List") add `items`.
- * `firstText` is the block's plain text truncated to 100 chars. Null-safe:
- * a missing or non-object doc/content yields `[]`.
- */
-export function buildOutline(doc: any): OutlineEntry[] {
-  if (!isObject(doc) || !Array.isArray(doc.content)) return [];
-
-  const out: OutlineEntry[] = [];
-  for (let i = 0; i < doc.content.length; i++) {
-    const block = doc.content[i];
-    const type = isObject(block) ? block.type : undefined;
-    const entry: OutlineEntry = {
-      index: i,
-      type,
-      id: isObject(block) && isObject(block.attrs) ? block.attrs.id ?? null : null,
-      firstText: truncate(blockPlainText(block), 100),
-    };
-
-    if (type === "heading") {
-      entry.level = isObject(block.attrs) ? block.attrs.level ?? null : null;
-    } else if (type === "table") {
-      const headerRow = block.content?.[0]?.content ?? [];
-      entry.rows = block.content?.length ?? 0;
-      entry.cols = block.content?.[0]?.content?.length ?? 0;
-      entry.header = headerRow.map((cell: any) =>
-        truncate(blockPlainText(cell), 40),
-      );
-    } else if (typeof type === "string" && type.endsWith("List")) {
-      entry.items = block.content?.length ?? 0;
-    }
-
-    out.push(entry);
-  }
-  return out;
-}
-
-/**
- * Resolve a single node by reference and return `{ node, path, type }`, or
- * `null` when nothing matches.
- *
- * - `ref` of the form `#<n>` (e.g. `#2`) selects the TOP-LEVEL block at index
- *   `n` in `doc.content`. This is the only way to address table/tableRow/
- *   tableCell nodes, which carry no `attrs.id`.
- * - Otherwise `ref` is treated as a block id: the FIRST node anywhere in the
- *   tree with `attrs.id === ref` is returned.
- *
- * `path` is the array of child indices from the doc root down to the node
- * (so a top-level block is `[index]`). The returned `node` is a DEEP CLONE,
- * so callers can mutate it without touching the input doc. Null-safe.
- */
-export function getNodeByRef(
-  doc: any,
-  ref: string,
-): { node: any; path: number[]; type: string | undefined } | null {
-  if (!isObject(doc)) return null;
-
-  // "#<n>": index into the top-level content array.
-  const indexMatch = typeof ref === "string" ? ref.match(/^#(\d+)$/) : null;
-  if (indexMatch) {
-    const index = Number(indexMatch[1]);
-    const block = Array.isArray(doc.content) ? doc.content[index] : undefined;
-    if (!isObject(block)) return null;
-    return { node: clone(block), path: [index], type: block.type };
-  }
-
-  // Otherwise: depth-first search for the first node with attrs.id === ref.
-  const search = (
-    node: any,
-    trail: number[],
-  ): { node: any; path: number[]; type: string } | null => {
-    if (!isObject(node)) return null;
-    if (Array.isArray(node.content)) {
-      for (let i = 0; i < node.content.length; i++) {
-        const child = node.content[i];
-        const path = [...trail, i];
-        if (matchesId(child, ref)) {
-          return { node: clone(child), path, type: child.type };
-        }
-        const hit = search(child, path);
-        if (hit != null) return hit;
-      }
-    }
-    return null;
-  };
-
-  return search(doc, []);
-}
-
-/**
- * Replace EVERY node whose `attrs.id === nodeId` with a deep clone of
- * `newNode`, anywhere in the tree (including inside callouts and table cells).
- *
- * Operates on a clone of `doc`; returns `{ doc, replaced }` where `replaced`
- * is the number of nodes substituted. A fresh clone of `newNode` is used for
- * each match so they do not share references.
- */
-export function replaceNodeById(
-  doc: any,
-  nodeId: string,
-  newNode: any,
-): { doc: any; replaced: number } {
-  const out = clone(doc);
-  let replaced = 0;
-
-  // Walk a content array, replacing direct matches and recursing into the
-  // (possibly new) children of non-matching nodes.
-  const walkContent = (content: any[]): void => {
-    for (let i = 0; i < content.length; i++) {
-      const child = content[i];
-      if (matchesId(child, nodeId)) {
-        content[i] = clone(newNode);
-        replaced++;
-        // Do not recurse into a freshly substituted node.
-        continue;
-      }
-      if (isObject(child) && Array.isArray(child.content)) {
-        walkContent(child.content);
-      }
-    }
-  };
-
-  if (isObject(out) && Array.isArray(out.content)) {
-    walkContent(out.content);
-  }
-  return { doc: out, replaced };
-}
-
-/**
- * Remove EVERY node whose `attrs.id === nodeId` from its parent `content`
- * array, anywhere in the tree (recursive, including callouts and tables).
- *
- * Operates on a clone of `doc`; returns `{ doc, deleted }` where `deleted` is
- * the number of nodes removed.
- */
-export function deleteNodeById(
-  doc: any,
-  nodeId: string,
-): { doc: any; deleted: number } {
-  const out = clone(doc);
-  let deleted = 0;
-
-  // Filter a content array in place, dropping matches and recursing into the
-  // surviving children.
-  const walkContent = (content: any[]): any[] => {
-    const kept: any[] = [];
-    for (const child of content) {
-      if (matchesId(child, nodeId)) {
-        deleted++;
-        continue;
-      }
-      if (isObject(child) && Array.isArray(child.content)) {
-        child.content = walkContent(child.content);
-      }
-      kept.push(child);
-    }
-    return kept;
-  };
-
-  if (isObject(out) && Array.isArray(out.content)) {
-    out.content = walkContent(out.content);
-  }
-  return { doc: out, deleted };
-}
-
-/**
- * Deep-clone `doc` and strip every node/mark attribute whose value is strictly
- * `undefined`, so the result is safe to hand to Yjs (which throws an opaque
- * "Unexpected content type" when asked to store an `undefined` attribute value).
- *
- * Only `undefined` keys are removed; `null`, `false`, `0`, and `""` are all
- * legitimate JSON-storable values and are preserved. Operates on a clone and
- * returns it; the input is never mutated. Defensively null-safe like the rest
- * of the file.
- */
-export function sanitizeForYjs(doc: any): any {
-  const out = clone(doc);
-
-  // Drop every key whose value is strictly `undefined` from an attrs object.
-  const stripUndefined = (attrs: any): void => {
-    if (!isObject(attrs)) return;
-    for (const key of Object.keys(attrs)) {
-      if (attrs[key] === undefined) {
-        delete attrs[key];
-      }
-    }
-  };
-
-  const walk = (node: any): void => {
-    if (!isObject(node)) return;
-    stripUndefined(node.attrs);
-    if (Array.isArray(node.marks)) {
-      for (const mark of node.marks) {
-        if (isObject(mark)) stripUndefined(mark.attrs);
-      }
-    }
-    if (Array.isArray(node.content)) {
-      for (const child of node.content) {
-        walk(child);
-      }
-    }
-  };
-
-  walk(out);
-  return out;
-}
-
-/**
- * Diagnostics helper: walk the tree and return a human-readable path string for
- * the FIRST attribute value (in any `node.attrs` or `mark.attrs`) that Yjs
- * cannot store — i.e. `undefined`, a `function`, a `symbol`, or a `bigint`
- * (e.g. `content[3].content[0].attrs.indent (undefined)`). Returns `null` when
- * every attribute is storable. Null-safe.
- */
-export function findUnstorableAttr(doc: any): string | null {
-  const isUnstorable = (value: any): string | null => {
-    if (value === undefined) return "undefined";
-    const t = typeof value;
-    if (t === "function") return "function";
-    if (t === "symbol") return "symbol";
-    if (t === "bigint") return "bigint";
-    return null;
-  };
-
-  // Check an attrs object; return the offending sub-path or null.
-  const checkAttrs = (attrs: any, basePath: string): string | null => {
-    if (!isObject(attrs)) return null;
-    for (const key of Object.keys(attrs)) {
-      const kind = isUnstorable(attrs[key]);
-      if (kind != null) return `${basePath}.${key} (${kind})`;
-    }
-    return null;
-  };
-
-  const walk = (node: any, path: string): string | null => {
-    if (!isObject(node)) return null;
-    const attrHit = checkAttrs(node.attrs, `${path}.attrs`);
-    if (attrHit != null) return attrHit;
-    if (Array.isArray(node.marks)) {
-      for (let i = 0; i < node.marks.length; i++) {
-        const markHit = checkAttrs(
-          node.marks[i]?.attrs,
-          `${path}.marks[${i}].attrs`,
-        );
-        if (markHit != null) return markHit;
-      }
-    }
-    if (Array.isArray(node.content)) {
-      for (let i = 0; i < node.content.length; i++) {
-        const childHit = walk(node.content[i], `${path}.content[${i}]`);
-        if (childHit != null) return childHit;
-      }
-    }
-    return null;
-  };
-
-  // The root doc node carries no useful index, so start the path at "doc".
-  if (!isObject(doc)) return null;
-  const attrHit = checkAttrs(doc.attrs, "attrs");
-  if (attrHit != null) return attrHit;
-  if (Array.isArray(doc.content)) {
-    for (let i = 0; i < doc.content.length; i++) {
-      const childHit = walk(doc.content[i], `content[${i}]`);
-      if (childHit != null) return childHit;
-    }
-  }
-  return null;
-}
-
-/**
- * Table structural node types and the container each must live directly inside.
- * Used by `insertNodeRelative` to splice rows/cells into the correct ancestor
- * rather than blindly into the anchor's direct parent (which would corrupt the
- * table's nesting).
- */
-const STRUCTURAL_TYPES = new Set(["tableRow", "tableCell", "tableHeader"]);
-const REQUIRED_CONTAINER: Record<string, string> = {
-  tableRow: "table",
-  tableCell: "tableRow",
-  tableHeader: "tableRow",
-};
-
-/**
- * Locate an anchor and return its ancestor chain (from `doc` down to and
- * including the matched node). Each chain entry is `{ node, index }` where
- * `index` is the node's position inside its parent's `content` array (the root
- * doc has index -1). Returns `null` when the anchor cannot be resolved.
- */
-function findAnchorChain(
-  doc: any,
-  opts: InsertOptions,
-): { node: any; index: number }[] | null {
-  if (!isObject(doc)) return null;
-
-  // DFS by id anywhere in the tree, accumulating the path.
-  if (opts.anchorNodeId != null) {
-    const targetId = opts.anchorNodeId;
-    const search = (
-      node: any,
-      index: number,
-      trail: { node: any; index: number }[],
-    ): { node: any; index: number }[] | null => {
-      if (!isObject(node)) return null;
-      const here = [...trail, { node, index }];
-      if (matchesId(node, targetId)) return here;
-      if (Array.isArray(node.content)) {
-        for (let i = 0; i < node.content.length; i++) {
-          const hit = search(node.content[i], i, here);
-          if (hit != null) return hit;
-        }
-      }
-      return null;
-    };
-    return search(doc, -1, []);
-  }
-
-  // By text: only top-level blocks are scanned (same rule as the JSON path).
-  if (opts.anchorText != null && Array.isArray(doc.content)) {
-    for (let i = 0; i < doc.content.length; i++) {
-      if (blockPlainText(doc.content[i]).includes(opts.anchorText)) {
-        return [
-          { node: doc, index: -1 },
-          { node: doc.content[i], index: i },
-        ];
-      }
-    }
-  }
-
-  return null;
-}
-
-/** Options controlling where `insertNodeRelative` places the new node. */
-export interface InsertOptions {
-  position: "before" | "after" | "append";
-  /** Resolve the anchor by node id anywhere in the tree (preferred). */
-  anchorNodeId?: string;
-  /** Fallback: first TOP-LEVEL block whose plain text includes this string. */
-  anchorText?: string;
-}
-
-/**
- * Insert a deep clone of `node` relative to an anchor.
- *
- * - position "append": push the node onto the top-level `doc.content`.
- * - position "before"/"after": locate the anchor and splice the node into the
- *   anchor's parent `content` array immediately before / after it.
- *
- * Anchor resolution for before/after:
- *   - if `anchorNodeId` is given, find the node with `attrs.id === anchorNodeId`
- *     anywhere in the tree (recursive);
- *   - otherwise, if `anchorText` is given, scan only TOP-LEVEL `doc.content`
- *     blocks and pick the first whose `blockPlainText` includes `anchorText`.
- *
- * Operates on a clone of `doc`; returns `{ doc, inserted }`. `inserted` is
- * false when the anchor could not be resolved (the doc is returned unchanged
- * apart from being cloned).
- */
-export function insertNodeRelative(
-  doc: any,
-  node: any,
-  opts: InsertOptions,
-): { doc: any; inserted: boolean } {
-  const out = clone(doc);
-  const fresh = clone(node);
-
-  // Defensive: stay null-safe like the other exports — a missing opts means
-  // there is nothing actionable to do.
-  if (!isObject(opts)) return { doc: out, inserted: false };
-
-  const isStructural = isObject(node) && STRUCTURAL_TYPES.has(node.type);
-
-  // "append": top-level push.
-  if (opts.position === "append") {
-    // Structural table nodes (tableRow/tableCell/tableHeader) cannot live at the
-    // top level — appending one would produce invalid nesting.
-    if (isStructural) {
-      throw new Error(
-        `insert_node: cannot append a ${node.type} at the top level; use ` +
-          `position before/after with an anchor inside the target table`,
-      );
-    }
-    if (isObject(out)) {
-      if (!Array.isArray(out.content)) out.content = [];
-      out.content.push(fresh);
-      return { doc: out, inserted: true };
-    }
-    return { doc: out, inserted: false };
-  }
-
-  const offset = opts.position === "after" ? 1 : 0;
-
-  // Structural insert (before/after a tableRow/tableCell/tableHeader): splice
-  // into the nearest enclosing table/tableRow rather than the anchor's direct
-  // parent, so the row/cell lands at the correct level of the table.
-  if (isStructural) {
-    const containerType = REQUIRED_CONTAINER[node.type];
-    const chain = findAnchorChain(out, opts);
-    // Anchor not resolved at all — keep the existing "anchor not found" path.
-    if (chain == null) return { doc: out, inserted: false };
-
-    // Find the DEEPEST ancestor (including the anchor itself) of the required
-    // container type.
-    let containerIdx = -1;
-    for (let i = chain.length - 1; i >= 0; i--) {
-      if (isObject(chain[i].node) && chain[i].node.type === containerType) {
-        containerIdx = i;
-        break;
-      }
-    }
-
-    if (containerIdx === -1) {
-      throw new Error(
-        `insert_node: cannot insert a ${node.type} here — the anchor is not ` +
-          `inside a ${containerType}. Anchor on a cell's text or a block id ` +
-          `that lives inside the target table.`,
-      );
-    }
-
-    const container = chain[containerIdx].node;
-    if (!Array.isArray(container.content)) container.content = [];
-
-    if (containerIdx === chain.length - 1) {
-      // The matched container IS the anchor node itself (e.g. anchorText
-      // resolved to the table block): append/prepend within it.
-      const at = opts.position === "after" ? container.content.length : 0;
-      container.content.splice(at, 0, fresh);
-    } else {
-      // The immediate child on the path leading to the anchor is the row/cell
-      // to splice next to.
-      const enclosingChildIndex = chain[containerIdx + 1].index;
-      container.content.splice(enclosingChildIndex + offset, 0, fresh);
-    }
-    return { doc: out, inserted: true };
-  }
-
-  // Resolve by id anywhere in the tree: splice into the parent content array.
-  if (opts.anchorNodeId != null) {
-    let inserted = false;
-    const walkContent = (content: any[]): void => {
-      for (let i = 0; i < content.length; i++) {
-        const child = content[i];
-        if (matchesId(child, opts.anchorNodeId as string)) {
-          content.splice(i + offset, 0, fresh);
-          inserted = true;
-          return;
-        }
-        if (isObject(child) && Array.isArray(child.content)) {
-          walkContent(child.content);
-          if (inserted) return;
-        }
-      }
-    };
-    if (isObject(out) && Array.isArray(out.content)) {
-      walkContent(out.content);
-    }
-    return { doc: out, inserted };
-  }
-
-  // Resolve by text: only top-level doc.content blocks are scanned.
-  if (opts.anchorText != null && isObject(out) && Array.isArray(out.content)) {
-    for (let i = 0; i < out.content.length; i++) {
-      if (blockPlainText(out.content[i]).includes(opts.anchorText)) {
-        out.content.splice(i + offset, 0, fresh);
-        return { doc: out, inserted: true };
-      }
-    }
-  }
-
-  return { doc: out, inserted: false };
-}
-
-// ===========================================================================
-// Table editing helpers
-//
-// A Docmost table is a ProseMirror subtree with NO ids on the structural nodes:
-//   table   -> { type:"table",     content:[tableRow...] }
-//   row     -> { type:"tableRow",  content:[tableCell|tableHeader...] }
-//   cell    -> { type:"tableCell"|"tableHeader", attrs:{colspan,rowspan,colwidth},
-//                content:[paragraph...] }
-//   para    -> { type:"paragraph", attrs:{id,indent}, content:[textNode...] }
-// Only paragraphs/headings carry an `attrs.id`, so a cell is addressed via the
-// id of the paragraph inside it. The helpers below all operate on a DEEP CLONE
-// of the input doc (via `clone`) and never mutate their inputs.
-// ===========================================================================
-
-/**
- * Collect EVERY `attrs.id` present anywhere in `node` into `used`. Used to seed
- * `makeFreshId` so generated paragraph ids never collide with existing ones.
- */
-function collectIds(node: any, used: Set<string>): void {
-  if (!isObject(node)) return;
-  if (isObject(node.attrs) && typeof node.attrs.id === "string") {
-    used.add(node.attrs.id);
-  }
-  if (Array.isArray(node.content)) {
-    for (const child of node.content) collectIds(child, used);
-  }
-}
-
-/**
- * Fresh-id generator: returns a random Docmost-style id (12 chars from
- * lowercase `a-z0-9`) that is not already in `used`, and records it. On the
- * rare collision the id is regenerated. Callers rely on uniqueness, not on the
- * exact string, so randomness is fine — and unlike a module-local counter it
- * needs no reset and cannot become predictable across calls.
- */
-function makeFreshId(used: Set<string>): string {
-  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
-  let id: string;
-  do {
-    id = "";
-    for (let i = 0; i < 12; i++) {
-      id += alphabet[Math.floor(Math.random() * alphabet.length)];
-    }
-  } while (used.has(id) || id === "");
-  used.add(id);
-  return id;
-}
-
-/**
- * Resolve a table reference against an ALREADY-CLONED doc and return the LIVE
- * table node (a reference inside `rootClone`, so the caller may mutate it) plus
- * its index path. Returns null when no table matches.
- *
- * - `#<n>`: the top-level block at index `n`, only if its `type === "table"`.
- * - otherwise: DFS for the node with `attrs.id === tableRef`, then walk UP its
- *   ancestor chain to the nearest `type === "table"` ancestor.
- */
-function locateTable(
-  rootClone: any,
-  tableRef: string,
-): { table: any; path: number[] } | null {
-  if (!isObject(rootClone)) return null;
-
-  // "#<n>": index into the top-level content array; must be a table.
-  const indexMatch = typeof tableRef === "string" ? tableRef.match(/^#(\d+)$/) : null;
-  if (indexMatch) {
-    const index = Number(indexMatch[1]);
-    const block = Array.isArray(rootClone.content)
-      ? rootClone.content[index]
-      : undefined;
-    if (isObject(block) && block.type === "table") {
-      return { table: block, path: [index] };
-    }
-    return null;
-  }
-
-  // Otherwise: DFS for attrs.id === tableRef, tracking the ancestor chain, then
-  // climb to the nearest enclosing table.
-  const search = (
-    node: any,
-    trail: { node: any; index: number }[],
-  ): { table: any; path: number[] } | null => {
-    if (!isObject(node)) return null;
-    if (Array.isArray(node.content)) {
-      for (let i = 0; i < node.content.length; i++) {
-        const child = node.content[i];
-        const here = [...trail, { node: child, index: i }];
-        if (matchesId(child, tableRef)) {
-          // Walk UP to the nearest table ancestor (including the match itself).
-          for (let j = here.length - 1; j >= 0; j--) {
-            if (isObject(here[j].node) && here[j].node.type === "table") {
-              return {
-                table: here[j].node,
-                path: here.slice(0, j + 1).map((e) => e.index),
-              };
-            }
-          }
-          return null; // id found but no enclosing table
-        }
-        const hit = search(child, here);
-        if (hit != null) return hit;
-      }
-    }
-    return null;
-  };
-
-  return search(rootClone, []);
-}
-
-/** Build the plain-text → single-paragraph cell content used by all writers. */
-function makeCellParagraph(id: string, text: string): any {
-  return {
-    type: "paragraph",
-    attrs: { id, indent: 0 },
-    // Empty string → a paragraph with an empty content array.
-    content: text ? [{ type: "text", text }] : [],
-  };
-}
-
-/**
- * Read a table as a matrix. Returns null when `tableRef` resolves to no table.
- *
- * - `rows`/`cols`: the table's row count and the column count of its FIRST row.
- *   Tables may be ragged (rows of differing length), so `cols` reflects only
- *   row 0; use the per-row length of `cells`/`cellIds` for each row's actual
- *   width.
- * - `cells`: `string[][]` of each cell's `blockPlainText`.
- * - `cellIds`: `(string|null)[][]` of each cell's FIRST paragraph id (or null),
- *   so callers can `patch_node` a cell for rich-formatted edits.
- * - `path`: index path of the table within the doc.
- */
-export function readTable(
-  doc: any,
-  tableRef: string,
-): {
-  rows: number;
-  cols: number;
-  cells: string[][];
-  cellIds: (string | null)[][];
-  path: number[];
-} | null {
-  const root = clone(doc);
-  const located = locateTable(root, tableRef);
-  if (located == null) return null;
-  const { table, path } = located;
-
-  const rowNodes = Array.isArray(table.content) ? table.content : [];
-  const rows = rowNodes.length;
-  const cols = rowNodes[0]?.content?.length ?? 0;
-
-  const cells: string[][] = [];
-  const cellIds: (string | null)[][] = [];
-  for (const rowNode of rowNodes) {
-    const cellNodes = Array.isArray(rowNode?.content) ? rowNode.content : [];
-    const rowText: string[] = [];
-    const rowIds: (string | null)[] = [];
-    for (const cellNode of cellNodes) {
-      rowText.push(blockPlainText(cellNode));
-      // The cell's first paragraph carries the id used for patch_node.
-      const firstPara = Array.isArray(cellNode?.content)
-        ? cellNode.content[0]
-        : undefined;
-      const id =
-        isObject(firstPara) && isObject(firstPara.attrs)
-          ? firstPara.attrs.id ?? null
-          : null;
-      rowIds.push(id);
-    }
-    cells.push(rowText);
-    cellIds.push(rowIds);
-  }
-
-  return { rows, cols, cells, cellIds, path };
-}
-
-/**
- * Insert a row of plain-text cells into a table. Returns `{ doc, inserted }`.
- *
- * The row is padded to the table's column count (`cells[i] ?? ""`); supplying
- * MORE cells than columns throws. Each new cell copies `colwidth` for its
- * column from the header row when present, gets a fresh-id paragraph, and a
- * `colspan:1, rowspan:1` attrs. `index` (when an integer in `[0, rows]`) splices
- * the row there; otherwise the row is appended at the end.
- */
-export function insertTableRow(
-  doc: any,
-  tableRef: string,
-  cells: string[],
-  index?: number,
-): { doc: any; inserted: boolean } {
-  const out = clone(doc);
-  const located = locateTable(out, tableRef);
-  if (located == null) return { doc: out, inserted: false };
-  const { table } = located;
-
-  if (!Array.isArray(table.content)) table.content = [];
-  const rows = table.content.length;
-  const headerRow = table.content[0];
-  const headerCells = Array.isArray(headerRow?.content) ? headerRow.content : [];
-
-  // Column count is the WIDEST existing row, so the guard below stays
-  // meaningful for ragged tables and the new row matches the table's width.
-  // Fall back to the supplied cell count only when the table has no rows.
-  let colCount = 0;
-  for (const r of table.content) {
-    if (isObject(r) && Array.isArray(r.content)) colCount = Math.max(colCount, r.content.length);
-  }
-  if (colCount === 0) colCount = Array.isArray(cells) ? cells.length : 0;
-
-  if (Array.isArray(cells) && cells.length > colCount) {
-    throw new Error(
-      `table_insert_row: got ${cells.length} cell(s) but the table has ${colCount} column(s)`,
-    );
-  }
-
-  // Resolve the landing index up front so the cell-type decision and the splice
-  // below agree: a valid integer in [0, rows] splices there, else we append.
-  const landingIndex =
-    typeof index === "number" && Number.isInteger(index) && index >= 0 && index <= rows
-      ? index
-      : rows;
-
-  // Seed the id generator with every id already in the doc so the new cell
-  // paragraph ids are unique within the whole document.
-  const used = new Set<string>();
-  collectIds(out, used);
-
-  const newCells: any[] = [];
-  for (let i = 0; i < colCount; i++) {
-    const text = (Array.isArray(cells) ? cells[i] : undefined) ?? "";
-    const attrs: Record<string, any> = { colspan: 1, rowspan: 1 };
-    // Copy this column's colwidth from the header row's cell when present.
-    const colwidth = headerCells[i]?.attrs?.colwidth;
-    if (colwidth !== undefined) attrs.colwidth = colwidth;
-    // A row landing at index 0 becomes the new header row, so inherit the
-    // current header cell's type per column (Docmost uses "tableHeader" there);
-    // every other position is a plain data cell.
-    const cellType = landingIndex === 0 ? headerCells[i]?.type ?? "tableCell" : "tableCell";
-    newCells.push({
-      type: cellType,
-      attrs,
-      content: [makeCellParagraph(makeFreshId(used), text)],
-    });
-  }
-
-  const newRow = { type: "tableRow", content: newCells };
-
-  // Splice at the resolved landing index (append when index was omitted/invalid).
-  table.content.splice(landingIndex, 0, newRow);
-
-  return { doc: out, inserted: true };
-}
-
-/**
- * Delete the row at 0-based `index` from a table. Returns `{ doc, deleted }`.
- * `deleted` is false only when the table cannot be located. Throws on an
- * out-of-range index, and refuses to delete the table's only row.
- */
-export function deleteTableRow(
-  doc: any,
-  tableRef: string,
-  index: number,
-): { doc: any; deleted: boolean } {
-  const out = clone(doc);
-  const located = locateTable(out, tableRef);
-  if (located == null) return { doc: out, deleted: false };
-  const { table } = located;
-
-  if (!Array.isArray(table.content)) table.content = [];
-  const rows = table.content.length;
-
-  if (!Number.isInteger(index) || index < 0 || index >= rows) {
-    throw new Error(
-      `table_delete_row: row index ${index} out of range (table has ${rows} row(s))`,
-    );
-  }
-  if (rows <= 1) {
-    throw new Error(
-      "table_delete_row: refusing to delete the only row of the table",
-    );
-  }
-
-  table.content.splice(index, 1);
-  return { doc: out, deleted: true };
-}
-
-/**
- * Set the plain-text content of cell `[row, col]` (0-based) to `text`. Returns
- * `{ doc, updated }`; `updated` is false only when the table cannot be located.
- * Throws when `row`/`col` is out of range. The cell's own attrs (colspan/
- * rowspan/colwidth) are preserved; its content becomes a single text paragraph
- * that reuses the cell's existing first-paragraph id when present, else a fresh
- * one.
- */
-export function updateTableCell(
-  doc: any,
-  tableRef: string,
-  row: number,
-  col: number,
-  text: string,
-): { doc: any; updated: boolean } {
-  const out = clone(doc);
-  const located = locateTable(out, tableRef);
-  if (located == null) return { doc: out, updated: false };
-  const { table } = located;
-
-  const rowNodes = Array.isArray(table.content) ? table.content : [];
-  const rows = rowNodes.length;
-  const rowNode = rowNodes[row];
-  const cols = isObject(rowNode) && Array.isArray(rowNode.content)
-    ? rowNode.content.length
-    : 0;
-
-  if (
-    !Number.isInteger(row) ||
-    row < 0 ||
-    row >= rows ||
-    !Number.isInteger(col) ||
-    col < 0 ||
-    col >= cols
-  ) {
-    throw new Error(`table_update_cell: cell [${row},${col}] out of range`);
-  }
-
-  const cellNode = rowNode.content[col];
-  // Reuse the cell's existing first-paragraph id, or mint a fresh unique one.
-  const existingPara = Array.isArray(cellNode?.content)
-    ? cellNode.content[0]
-    : undefined;
-  let id =
-    isObject(existingPara) && isObject(existingPara.attrs)
-      ? existingPara.attrs.id
-      : undefined;
-  if (typeof id !== "string" || id.length === 0) {
-    const used = new Set<string>();
-    collectIds(out, used);
-    id = makeFreshId(used);
-  }
-
-  cellNode.content = [makeCellParagraph(id, text)];
-  return { doc: out, updated: true };
-}
diff --git a/packages/git-sync/src/lib/page-file.ts b/packages/git-sync/src/lib/page-file.ts
deleted file mode 100644
index 26e43776..00000000
--- a/packages/git-sync/src/lib/page-file.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-/**
- * The native-Obsidian page-file format (design: docs/backlog/git-sync-thin-meta.md).
- * A page file is CLEAN markdown with a minimal YAML frontmatter carrying ONLY the
- * page's durable identity:
- *
- *   ---
- *   gitmost_id: 019ef6fc-2638-7ce1-9ce3-2756ce038480
- *   ---
- *   <clean markdown body>
- *
- * Everything else is derived (title = filename, parentPageId = enclosing folder,
- * spaceId = the vault, updatedAt = git). `gitmost_id` (a Docmost pageId) is the
- * only non-derivable bit and travels WITH the file so identity survives any move,
- * even one git's rename detection misses. Third-party editors (Obsidian, …) see
- * clean markdown; the frontmatter is hidden in their preview.
- *
- * No backward-compat with the old `docmost:meta` format: vaults are a cache, wiped
- * and rebuilt native. A file WITHOUT a `gitmost_id` frontmatter is an un-tracked
- * (e.g. hand-written) file -> the caller ADOPTS it (creates a page, writes the id).
- */
-
-/**
- * The frontmatter key carrying the Docmost pageId. NAMESPACED (not a bare `id`)
- * so it never collides with a user's own frontmatter fields.
- */
-export const ID_KEY = "gitmost_id";
-
-/** Leading YAML frontmatter block: `---\n…\n---` at the very start of the file. */
-const FRONTMATTER_RE = /^?---\n([\s\S]*?)\n---\n?/;
-
-/** The top-level `<ID_KEY>: <value>` line inside the frontmatter (quotes optional). */
-function readIdFromYaml(yaml: string): string | null {
-  const re = new RegExp(`^${ID_KEY}:\\s*(.+?)\\s*$`);
-  for (const line of yaml.split("\n")) {
-    const m = line.match(re);
-    if (m) {
-      const v = m[1].trim().replace(/^["']|["']$/g, "");
-      return v === "" ? null : v;
-    }
-  }
-  return null;
-}
-
-/**
- * Parse a page file into its identity (`id`) and clean markdown `body`. Tolerant:
- * a file with no frontmatter (a hand-written third-party file) returns `id: null`
- * and the whole text as the body — the caller then ADOPTS it (creates a page,
- * writes the id back).
- *
- * KNOWN LIMITATION (phase 4 — adoption, see docs/backlog/git-sync-thin-meta.md):
- * a leading frontmatter block is stripped from `body` even when it carries NO
- * `gitmost_id` but DOES carry the user's own Obsidian properties (`tags:` etc.).
- * On adoption those fields are not yet round-tripped — `serializePageFile`
- * write-back persists only `gitmost_id`. Preserving arbitrary user frontmatter
- * across the Docmost round-trip (BOTH adoption write-back AND the next pull's
- * re-serialize) is deferred to the adoption phase; until then, do NOT roll the
- * native format onto a real Obsidian vault whose notes carry properties.
- */
-export function parsePageFile(full: string): {
-  id: string | null;
-  body: string;
-} {
-  const text = (full ?? "").replace(/\r\n/g, "\n");
-
-  // Native format: a `gitmost_id` YAML frontmatter. Anything else (no frontmatter,
-  // or frontmatter without the key) is an un-tracked file -> adopt.
-  const fm = text.match(FRONTMATTER_RE);
-  if (fm) {
-    return { id: readIdFromYaml(fm[1]), body: text.slice(fm[0].length).trim() };
-  }
-  return { id: null, body: text.trim() };
-}
-
-/**
- * Serialize a page into the thin format: `id` frontmatter + a blank line + the
- * clean body + a trailing newline. Deterministic so an unchanged page re-syncs to
- * byte-identical output (no churn — the loop-guard relies on it).
- */
-export function serializePageFile(id: string, body: string): string {
-  return `---\n${ID_KEY}: ${id}\n---\n\n${body.trim()}\n`;
-}
diff --git a/packages/git-sync/test/apply-push-actions.test.ts b/packages/git-sync/test/apply-push-actions.test.ts
index 1f0a8d9b..4e95d761 100644
--- a/packages/git-sync/test/apply-push-actions.test.ts
+++ b/packages/git-sync/test/apply-push-actions.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 import { applyPushActions, LAST_PUSHED_REF } from '../src/engine/push';
 import { bodyHash } from '../src/engine/loop-guard';
 import type { ApplyPushDeps, PushActions } from '../src/engine/push';
-import { parsePageFile, serializePageFile } from '../src/lib/page-file';
+import { parsePageFile, serializePageFile } from '@docmost/prosemirror-markdown';
 
 // The Docmost space this vault mirrors (native files carry no spaceId; the run
 // supplies it). A CREATE targets this space.
diff --git a/packages/git-sync/test/canonicalize-extra.test.ts b/packages/git-sync/test/canonicalize-extra.test.ts
deleted file mode 100644
index e2103f80..00000000
--- a/packages/git-sync/test/canonicalize-extra.test.ts
+++ /dev/null
@@ -1,205 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fc from 'fast-check';
-// Barrel import (R-Infra alias resolves this to packages/docmost-client/src so
-// coverage measures the real source, not stale dist).
-import { canonicalizeContent, docsCanonicallyEqual } from 'docmost-client';
-
-// ---------------------------------------------------------------------------
-// Gaps NOT covered by canonicalize.test.ts (test-strategy report §2 diff):
-//   - the *.align family (drawio/excalidraw/video/youtube/embed): a "center"
-//     default is dropped, a non-default value is kept;
-//   - comment.resolved: TRUE is PRESERVED (only resolved:false is normalized);
-//   - link.target / link.rel NON-default values are kept;
-//   - property: canonicalizeContent is a fixpoint, docsCanonicallyEqual is
-//     reflexive and symmetric.
-// The base file already covers id-stripping, null-drop, link/comment/orderedList
-// default-drop, key-order insensitivity, and a real-diff negative — not re-added.
-// ---------------------------------------------------------------------------
-
-describe('canonicalizeContent — *.align default family', () => {
-  // Every diagram/media node whose schema `align` defaults to "center".
-  const alignTypes = ['drawio', 'excalidraw', 'video', 'youtube', 'embed'];
-
-  for (const type of alignTypes) {
-    it(`${type}: align "center" (the schema default) is dropped`, () => {
-      const out = canonicalizeContent({
-        type,
-        attrs: { id: 'n-1', src: '/x', align: 'center' },
-      });
-      // align==default removed; the meaningful src survives.
-      expect(out.attrs).toEqual({ src: '/x' });
-    });
-
-    it(`${type}: a NON-default align (e.g. "right") is kept`, () => {
-      const out = canonicalizeContent({
-        type,
-        attrs: { id: 'n-1', src: '/x', align: 'right' },
-      });
-      expect(out.attrs).toEqual({ src: '/x', align: 'right' });
-    });
-  }
-
-  it('image align is NOT in KNOWN_DEFAULTS: a non-null align survives, null is dropped', () => {
-    // image.align defaults to null, so it is handled by the null-drop rule and
-    // a real value ("left") must be kept (no spurious default match).
-    const kept = canonicalizeContent({
-      type: 'image',
-      attrs: { id: 'i-1', src: '/a.png', align: 'left' },
-    });
-    expect(kept.attrs).toEqual({ src: '/a.png', align: 'left' });
-    // An image with align:"center" must KEEP it (center is NOT a default for
-    // image, only for the diagram/media family) — guards against over-matching.
-    const center = canonicalizeContent({
-      type: 'image',
-      attrs: { id: 'i-2', src: '/b.png', align: 'center' },
-    });
-    expect(center.attrs).toEqual({ src: '/b.png', align: 'center' });
-  });
-});
-
-describe('canonicalizeContent — comment.resolved:true preserved (SPEC §11 L66)', () => {
-  it('keeps resolved:true (a legitimate change, not a default to normalize away)', () => {
-    const out = canonicalizeContent({
-      type: 'text',
-      text: 'anchored',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1', resolved: true } }],
-    });
-    // resolved:true is NON-default; it must survive alongside the commentId so a
-    // resolve-vs-unresolved divergence is not falsely reported as equal.
-    expect(out.marks).toEqual([
-      { type: 'comment', attrs: { commentId: 'cmt-1', resolved: true } },
-    ]);
-  });
-
-  it('a resolved:true comment is NOT canonically equal to an unresolved one', () => {
-    const resolved = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'c', resolved: true } }],
-    };
-    const open = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'c' } }],
-    };
-    expect(docsCanonicallyEqual(resolved, open)).toBe(false);
-  });
-});
-
-describe('canonicalizeContent — link non-default target/rel kept', () => {
-  it('keeps a NON-default link.target (e.g. "_self")', () => {
-    const out = canonicalizeContent({
-      type: 'text',
-      text: 'l',
-      marks: [{ type: 'link', attrs: { href: 'https://e.com', target: '_self' } }],
-    });
-    // _self != the "_blank" default, so target must survive.
-    expect(out.marks).toEqual([
-      { type: 'link', attrs: { href: 'https://e.com', target: '_self' } },
-    ]);
-  });
-
-  it('keeps a NON-default link.rel', () => {
-    const out = canonicalizeContent({
-      type: 'text',
-      text: 'l',
-      marks: [{ type: 'link', attrs: { href: 'https://e.com', rel: 'nofollow' } }],
-    });
-    expect(out.marks).toEqual([
-      { type: 'link', attrs: { href: 'https://e.com', rel: 'nofollow' } },
-    ]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Property-based oracle checks (SPEC §11). The generated trees mix node/mark
-// types, ids, null attrs, known-default attrs and meaningful attrs, so the
-// invariants are exercised across the whole canonicalization surface.
-// ---------------------------------------------------------------------------
-
-// An attribute value: a meaningful value, a null/undefined, a block id, or a
-// known schema default — so pruning, id-drop, null-drop and default-drop all
-// fire during shrinking.
-const attrValueArb = fc.oneof(
-  fc.string({ minLength: 1, maxLength: 6 }),
-  fc.integer({ min: 0, max: 9 }),
-  fc.boolean(),
-  fc.constant(null),
-);
-
-// A recursive ProseMirror-ish node arbitrary (bounded depth) with type, attrs
-// (incl. an id and possibly a known default), optional marks and content.
-const nodeArb: fc.Arbitrary<any> = fc.letrec((tie) => ({
-  node: fc.record(
-    {
-      type: fc.constantFrom(
-        'paragraph',
-        'heading',
-        'orderedList',
-        'drawio',
-        'video',
-        'text',
-      ),
-      text: fc.option(fc.string({ minLength: 0, maxLength: 5 }), { nil: undefined }),
-      attrs: fc.option(
-        fc.dictionary(
-          fc.constantFrom('id', 'level', 'start', 'align', 'src', 'indent', 'keep'),
-          attrValueArb,
-          { maxKeys: 4 },
-        ),
-        { nil: undefined },
-      ),
-      marks: fc.option(
-        fc.array(
-          fc.record({
-            type: fc.constantFrom('bold', 'link', 'comment'),
-            attrs: fc.option(
-              fc.dictionary(
-                fc.constantFrom('href', 'target', 'rel', 'commentId', 'resolved'),
-                fc.oneof(attrValueArb, fc.constant('_blank')),
-                { maxKeys: 3 },
-              ),
-              { nil: undefined },
-            ),
-          }),
-          { maxLength: 2 },
-        ),
-        { nil: undefined },
-      ),
-      content: fc.option(fc.array(tie('node'), { maxLength: 2 }), { nil: undefined }),
-    },
-    { requiredKeys: ['type'] },
-  ),
-})).node;
-
-describe('canonicalizeContent — property invariants (SPEC §11 oracle)', () => {
-  it('is a fixpoint: f(f(x)) === f(x)', () => {
-    fc.assert(
-      fc.property(nodeArb, (node) => {
-        const once = canonicalizeContent(node);
-        const twice = canonicalizeContent(once);
-        // The canonical form must already be stable under a second pass.
-        expect(twice).toEqual(once);
-      }),
-      { numRuns: 300 },
-    );
-  });
-
-  it('docsCanonicallyEqual is reflexive: equal(x, x) is always true', () => {
-    fc.assert(
-      fc.property(nodeArb, (node) => {
-        expect(docsCanonicallyEqual(node, node)).toBe(true);
-      }),
-      { numRuns: 300 },
-    );
-  });
-
-  it('docsCanonicallyEqual is symmetric: equal(a, b) === equal(b, a)', () => {
-    fc.assert(
-      fc.property(nodeArb, nodeArb, (a, b) => {
-        expect(docsCanonicallyEqual(a, b)).toBe(docsCanonicallyEqual(b, a));
-      }),
-      { numRuns: 300 },
-    );
-  });
-});
diff --git a/packages/git-sync/test/canonicalize.test.ts b/packages/git-sync/test/canonicalize.test.ts
deleted file mode 100644
index cec5da49..00000000
--- a/packages/git-sync/test/canonicalize.test.ts
+++ /dev/null
@@ -1,302 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import via the package barrel to also assert the symbols are re-exported.
-import { canonicalizeContent, docsCanonicallyEqual } from 'docmost-client';
-
-describe('canonicalizeContent', () => {
-  it('strips node-level attrs.id, recursively', () => {
-    const input = {
-      type: 'doc',
-      content: [
-        {
-          type: 'heading',
-          attrs: { id: 'h-1', level: 2 },
-          content: [{ type: 'text', text: 'Title' }],
-        },
-      ],
-    };
-    const out = canonicalizeContent(input);
-    expect(out.content[0].attrs).toEqual({ level: 2 });
-    // No `id` survives anywhere in the canonical tree.
-    expect(JSON.stringify(out)).not.toContain('"id"');
-  });
-
-  it('drops null/undefined attrs but keeps every non-null attr', () => {
-    const out = canonicalizeContent({
-      type: 'paragraph',
-      attrs: {
-        id: 'p-1',
-        indent: null,
-        textAlign: undefined,
-        level: 0,
-        keep: 'yes',
-      },
-      content: [],
-    });
-    // null/undefined gone; non-null values (incl. 0 and false) kept.
-    expect(out.attrs).toEqual({ keep: 'yes', level: 0 });
-  });
-
-  it('removes an attrs object that becomes empty after pruning', () => {
-    const out = canonicalizeContent({
-      type: 'paragraph',
-      attrs: { id: 'p-1', indent: null, textAlign: null },
-      content: [{ type: 'text', text: 'x' }],
-    });
-    // attrs had only an id + null defaults -> the whole attrs key is dropped.
-    expect('attrs' in out).toBe(false);
-    expect(out).toEqual({
-      type: 'paragraph',
-      content: [{ type: 'text', text: 'x' }],
-    });
-  });
-
-  it('treats {attrs:{}} as equivalent to no attrs', () => {
-    const withEmpty = canonicalizeContent({ type: 'paragraph', attrs: {} });
-    const without = canonicalizeContent({ type: 'paragraph' });
-    expect(withEmpty).toEqual(without);
-  });
-
-  it('keeps comment marks + commentId but normalizes resolved:false default (SPEC §3 anchor)', () => {
-    const out = canonicalizeContent({
-      type: 'text',
-      text: 'anchored',
-      marks: [
-        { type: 'comment', attrs: { commentId: 'cmt-1', resolved: false } },
-      ],
-    });
-    // The comment mark is preserved; commentId (a meaningful anchor) survives,
-    // but the `resolved: false` schema default is normalized away.
-    expect(out.marks).toEqual([
-      { type: 'comment', attrs: { commentId: 'cmt-1' } },
-    ]);
-  });
-
-  it('drops known non-null schema defaults (link target/rel, comment resolved)', () => {
-    const out = canonicalizeContent({
-      type: 'text',
-      text: 'a link',
-      marks: [
-        {
-          type: 'link',
-          attrs: {
-            href: 'https://example.com/page',
-            target: '_blank',
-            rel: 'noopener noreferrer nofollow',
-          },
-        },
-      ],
-    });
-    // href (non-default) kept; target/rel (schema defaults) dropped.
-    expect(out.marks).toEqual([
-      { type: 'link', attrs: { href: 'https://example.com/page' } },
-    ]);
-  });
-
-  it('keeps a NON-default value that happens to share an attr name (orderedList start:5)', () => {
-    const out = canonicalizeContent({
-      type: 'orderedList',
-      attrs: { id: 'ol-1', start: 5 },
-      content: [],
-    });
-    // start:5 is NOT the default (1), so it must survive.
-    expect(out.attrs).toEqual({ start: 5 });
-  });
-
-  it('keeps meaningful node/mark attrs (level, language, href, src, width)', () => {
-    const out = canonicalizeContent({
-      type: 'doc',
-      content: [
-        {
-          type: 'codeBlock',
-          attrs: { id: 'c-1', language: 'js' },
-          content: [{ type: 'text', text: 'x' }],
-        },
-        {
-          type: 'image',
-          attrs: { id: 'i-1', src: '/a.png', width: 100, height: null },
-        },
-        {
-          type: 'paragraph',
-          content: [
-            {
-              type: 'text',
-              text: 'link',
-              marks: [{ type: 'link', attrs: { href: 'https://e.com' } }],
-            },
-          ],
-        },
-      ],
-    });
-    expect(out.content[0].attrs).toEqual({ language: 'js' });
-    expect(out.content[1].attrs).toEqual({ src: '/a.png', width: 100 });
-    expect(out.content[2].content[0].marks[0].attrs).toEqual({
-      href: 'https://e.com',
-    });
-  });
-
-  it('preserves text, type and content order exactly', () => {
-    const input = {
-      type: 'paragraph',
-      content: [
-        { type: 'text', text: 'one' },
-        { type: 'text', text: 'two', marks: [{ type: 'bold' }] },
-        { type: 'text', text: 'three' },
-      ],
-    };
-    const out = canonicalizeContent(input);
-    expect(out.content.map((n: any) => n.text)).toEqual([
-      'one',
-      'two',
-      'three',
-    ]);
-    expect(out.content[1].marks).toEqual([{ type: 'bold' }]);
-  });
-
-  it('drops an empty marks array (marks:[] === no marks)', () => {
-    const out = canonicalizeContent({ type: 'text', text: 'x', marks: [] });
-    expect('marks' in out).toBe(false);
-  });
-
-  it('does not mutate its input (frozen tree passes through unchanged)', () => {
-    const input = Object.freeze({
-      type: 'doc',
-      content: Object.freeze([
-        Object.freeze({
-          type: 'paragraph',
-          attrs: Object.freeze({ id: 'p-1', indent: null }),
-          content: Object.freeze([Object.freeze({ type: 'text', text: 'x' })]),
-        }),
-      ]),
-    });
-    const before = JSON.stringify(input);
-    const out = canonicalizeContent(input);
-    // Input is structurally identical after the call.
-    expect(JSON.stringify(input)).toBe(before);
-    // A fresh tree is returned.
-    expect(out).not.toBe(input);
-    expect('attrs' in out.content[0]).toBe(false);
-  });
-});
-
-describe('docsCanonicallyEqual', () => {
-  it('is true when docs differ only by block ids', () => {
-    const a = {
-      type: 'doc',
-      content: [
-        { type: 'heading', attrs: { id: 'h-1', level: 1 }, content: [] },
-      ],
-    };
-    const b = {
-      type: 'doc',
-      content: [
-        { type: 'heading', attrs: { id: 'h-DIFFERENT', level: 1 }, content: [] },
-      ],
-    };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is true when one side omits an attr the other sets to default null', () => {
-    const a = {
-      type: 'paragraph',
-      attrs: { id: 'p-1' },
-      content: [{ type: 'text', text: 'x' }],
-    };
-    const b = {
-      type: 'paragraph',
-      attrs: { id: 'p-2', indent: null, textAlign: null },
-      content: [{ type: 'text', text: 'x' }],
-    };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is key-order-insensitive for attrs', () => {
-    const a = { type: 'image', attrs: { src: '/a.png', width: 10 } };
-    const b = { type: 'image', attrs: { width: 10, src: '/a.png' } };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is false for a real text difference', () => {
-    const a = { type: 'text', text: 'hello' };
-    const b = { type: 'text', text: 'world' };
-    expect(docsCanonicallyEqual(a, b)).toBe(false);
-  });
-
-  it('is false for a real attr difference (different level)', () => {
-    const a = { type: 'heading', attrs: { id: 'x', level: 1 } };
-    const b = { type: 'heading', attrs: { id: 'y', level: 2 } };
-    expect(docsCanonicallyEqual(a, b)).toBe(false);
-  });
-
-  it('is false when a meaningful mark attr differs (commentId)', () => {
-    const a = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
-    };
-    const b = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-2' } }],
-    };
-    expect(docsCanonicallyEqual(a, b)).toBe(false);
-  });
-
-  it('is true when a link has only href vs one with the schema-default target/rel', () => {
-    const a = {
-      type: 'text',
-      text: 'link',
-      marks: [{ type: 'link', attrs: { href: 'https://example.com' } }],
-    };
-    const b = {
-      type: 'text',
-      text: 'link',
-      marks: [
-        {
-          type: 'link',
-          attrs: {
-            href: 'https://example.com',
-            target: '_blank',
-            rel: 'noopener noreferrer nofollow',
-          },
-        },
-      ],
-    };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is true when an orderedList omits start vs one with the default start:1', () => {
-    const a = { type: 'orderedList', content: [] };
-    const b = { type: 'orderedList', attrs: { start: 1 }, content: [] };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is false when an orderedList has a non-default start (5 vs absent)', () => {
-    const a = { type: 'orderedList', content: [] };
-    const b = { type: 'orderedList', attrs: { start: 5 }, content: [] };
-    expect(docsCanonicallyEqual(a, b)).toBe(false);
-  });
-
-  it('is true when a comment mark omits resolved vs one with the default false', () => {
-    const a = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
-    };
-    const b = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1', resolved: false } }],
-    };
-    expect(docsCanonicallyEqual(a, b)).toBe(true);
-  });
-
-  it('is false when a comment mark is dropped entirely', () => {
-    const a = {
-      type: 'text',
-      text: 'x',
-      marks: [{ type: 'comment', attrs: { commentId: 'cmt-1' } }],
-    };
-    const b = { type: 'text', text: 'x' };
-    expect(docsCanonicallyEqual(a, b)).toBe(false);
-  });
-});
diff --git a/packages/git-sync/test/classify-rename-moves.test.ts b/packages/git-sync/test/classify-rename-moves.test.ts
index ceb00285..12fc34bd 100644
--- a/packages/git-sync/test/classify-rename-moves.test.ts
+++ b/packages/git-sync/test/classify-rename-moves.test.ts
@@ -5,7 +5,7 @@ import type {
   MetaSide,
   RenameMoveAction,
 } from '../src/engine/push';
-import type { DocmostMdMeta } from '../src/lib/index';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // FS→Docmost push #3 (SPEC §5/§6/§16). `classifyRenameMoves` is the PURE half of
 // the move/rename apply: it resolves each `{pageId, oldPath, newPath}` into the
diff --git a/packages/git-sync/test/compute-push-actions.test.ts b/packages/git-sync/test/compute-push-actions.test.ts
index 28a2b59e..74a785a0 100644
--- a/packages/git-sync/test/compute-push-actions.test.ts
+++ b/packages/git-sync/test/compute-push-actions.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { computePushActions } from '../src/engine/push';
 import type { DiffEntry, MetaSide } from '../src/engine/push';
-import type { DocmostMdMeta } from '../src/lib/index';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // FS→Docmost push, FIRST increment (SPEC §6). `computePushActions` is the PURE
 // half: it classifies each `git diff --name-status` row into a Docmost action by
diff --git a/packages/git-sync/test/cycle-roundtrip.test.ts b/packages/git-sync/test/cycle-roundtrip.test.ts
index b1d7ca40..4c281b03 100644
--- a/packages/git-sync/test/cycle-roundtrip.test.ts
+++ b/packages/git-sync/test/cycle-roundtrip.test.ts
@@ -8,7 +8,7 @@ import { runCycle } from "../src/engine/cycle";
 import type { CycleFs } from "../src/engine/cycle";
 import { VaultGit } from "../src/engine/git";
 import type { Settings } from "../src/engine/settings";
-import { serializeDocmostMarkdownBody } from "../src/lib/index";
+import { serializeDocmostMarkdownBody } from "@docmost/prosemirror-markdown";
 
 const execFileAsync = promisify(execFile);
 
diff --git a/packages/git-sync/test/diagram-roundtrip.test.ts b/packages/git-sync/test/diagram-roundtrip.test.ts
deleted file mode 100644
index d8ffc5fe..00000000
--- a/packages/git-sync/test/diagram-roundtrip.test.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-  docsCanonicallyEqual,
-} from 'docmost-client';
-
-// Helper mirroring the convention in markdown-converter.test.ts: wrap atoms in
-// a top-level doc node so convertProseMirrorToMarkdown (which requires
-// content.content) walks them.
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-
-describe('diagram round-trip (docmost-schema diagramAttributes)', () => {
-  // SPEC case 1: drawio carrying the full numeric-attr surface
-  // (data-width/data-height/data-size/data-aspect-ratio) that it shares with
-  // audio/video/pdf but which no fixture exercises on a diagram node.
-  it('drawio round-trips numeric attrs, coercing number -> string via getAttribute', async () => {
-    const input = doc({
-      type: 'drawio',
-      attrs: {
-        src: '/d.drawio',
-        attachmentId: 'att-1',
-        width: 640,
-        height: 480,
-        size: 1234,
-        aspectRatio: 1.777,
-        align: 'center',
-      },
-    });
-
-    const md1 = convertProseMirrorToMarkdown(input);
-    const doc2 = await markdownToProseMirror(md1);
-    const md2 = convertProseMirrorToMarkdown(doc2);
-
-    // Exact serialized form: numbers render as bare data-* values; attribute
-    // order follows the converter's emit order (src, then width/height/size/
-    // aspect-ratio/align, then attachment-id).
-    expect(md1).toBe(
-      '<div data-type="drawio" data-src="/d.drawio" data-width="640" data-height="480" data-size="1234" data-aspect-ratio="1.777" data-align="center" data-attachment-id="att-1"></div>',
-    );
-
-    // A second export reproduces the first byte-for-byte (drawio align default
-    // is already "center", so nothing new materializes on import).
-    expect(md2).toBe(md1);
-
-    // Re-import coerces every numeric attr to a STRING because parseHTML reads
-    // them via getAttribute(). This is the gap the reviewer flagged: the
-    // number -> string coercion on a diagram node is otherwise untested.
-    const attrs2 = doc2.content[0].attrs;
-    expect(attrs2.width).toBe('640');
-    expect(attrs2.height).toBe('480');
-    expect(attrs2.size).toBe('1234');
-    expect(attrs2.aspectRatio).toBe('1.777');
-    expect(typeof attrs2.width).toBe('string');
-    expect(typeof attrs2.aspectRatio).toBe('string');
-    // String attrs pass through unchanged.
-    expect(attrs2.align).toBe('center');
-    expect(attrs2.attachmentId).toBe('att-1');
-
-    // Canonically NOT equal: the numeric -> string coercion survives
-    // canonicalization (only align='center' is normalized away via
-    // KNOWN_DEFAULTS.drawio), so 640 !== '640' makes the docs differ.
-    expect(docsCanonicallyEqual(input, doc2)).toBe(false);
-  });
-
-  // SPEC case 2: minimal excalidraw atom with ONLY string attrs (no align, no
-  // numeric attrs). Locks the one-time export divergence (align='center'
-  // default materializes only on import) plus escapeAttr of title/alt through
-  // the data-title/data-alt path.
-  it('excalidraw materializes align default only on import and escapes title/alt', async () => {
-    const input = doc({
-      type: 'excalidraw',
-      attrs: {
-        src: '/e.excalidraw',
-        title: 'My "Diagram"',
-        alt: 'a&b',
-      },
-    });
-
-    const md1 = convertProseMirrorToMarkdown(input);
-    const doc2 = await markdownToProseMirror(md1);
-    const md2 = convertProseMirrorToMarkdown(doc2);
-
-    // First export: no align emitted (the input doc carries no align), and the
-    // " in title becomes &quot;, the & in alt becomes &amp; via escapeAttr.
-    expect(md1).toBe(
-      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b"></div>',
-    );
-
-    // Second export: align='center' has now materialized (the schema's
-    // diagramAttributes default), so md2 gains a data-align="center" suffix and
-    // is NOT byte-equal to md1. This one-time divergence is the diagram quirk.
-    expect(md2).toBe(
-      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b" data-align="center"></div>',
-    );
-    expect(md2).not.toBe(md1);
-
-    // Re-import decodes the escaped entities back to the original characters.
-    const attrs2 = doc2.content[0].attrs;
-    expect(attrs2.title).toBe('My "Diagram"');
-    expect(attrs2.alt).toBe('a&b');
-    expect(attrs2.align).toBe('center');
-
-    // Canonically EQUAL: align='center' is normalized away via
-    // KNOWN_DEFAULTS.excalidraw, and title/alt are non-default strings that
-    // survive on both sides, so the docs are semantically equal.
-    expect(docsCanonicallyEqual(input, doc2)).toBe(true);
-  });
-});
diff --git a/packages/git-sync/test/docmost-schema-attrs.test.ts b/packages/git-sync/test/docmost-schema-attrs.test.ts
deleted file mode 100644
index fb7a3591..00000000
--- a/packages/git-sync/test/docmost-schema-attrs.test.ts
+++ /dev/null
@@ -1,124 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  sanitizeCssColor,
-  clampCalloutType,
-  encodeHtmlEmbedSource,
-  decodeHtmlEmbedSource,
-} from '../src/lib/docmost-schema.js';
-
-// These tests pin the two security/normalization helpers that Docmost
-// interpolates into inline style and the callout banner type on re-render.
-// They are the allowlist guard (XSS/style-breakout boundary) and the
-// case-insensitive callout normalizer, both otherwise only exercised
-// indirectly through parseHTML/renderHTML.
-
-describe('sanitizeCssColor', () => {
-  it('accepts a plain named color unchanged', () => {
-    expect(sanitizeCssColor('red')).toBe('red');
-  });
-
-  it('accepts 3-digit and 6-digit hex colors unchanged', () => {
-    expect(sanitizeCssColor('#abc')).toBe('#abc');
-    expect(sanitizeCssColor('#aabbcc')).toBe('#aabbcc');
-  });
-
-  it('accepts well-formed functional notation unchanged', () => {
-    expect(sanitizeCssColor('rgb(1,2,3)')).toBe('rgb(1,2,3)');
-    expect(sanitizeCssColor('rgba(0,0,0,0.5)')).toBe('rgba(0,0,0,0.5)');
-    expect(sanitizeCssColor('hsl(120,50%,50%)')).toBe('hsl(120,50%,50%)');
-  });
-
-  it('trims surrounding whitespace before matching', () => {
-    // '  blue  ' trims to 'blue', which is a valid named color.
-    expect(sanitizeCssColor('  blue  ')).toBe('blue');
-  });
-
-  it('rejects a style-injection payload (returns null)', () => {
-    expect(sanitizeCssColor('red; --x: url(x)')).toBeNull();
-  });
-
-  it('rejects an attribute-breakout payload (returns null)', () => {
-    expect(sanitizeCssColor('red"><script>')).toBeNull();
-  });
-
-  it('rejects the empty string (returns null)', () => {
-    expect(sanitizeCssColor('')).toBeNull();
-  });
-
-  it('rejects non-string input via the typeof guard (returns null)', () => {
-    // @ts-expect-error deliberately passing a non-string to exercise the guard
-    expect(sanitizeCssColor(123)).toBeNull();
-  });
-});
-
-describe('clampCalloutType', () => {
-  it('lowercases an uppercase valid type', () => {
-    expect(clampCalloutType('INFO')).toBe('info');
-  });
-
-  it('lowercases a mixed-case valid type', () => {
-    expect(clampCalloutType('Warning')).toBe('warning');
-  });
-
-  it('passes through already-lowercase valid types', () => {
-    expect(clampCalloutType('danger')).toBe('danger');
-    expect(clampCalloutType('success')).toBe('success');
-  });
-
-  it('PRESERVES every editor-canonical type (note/default no longer flattened)', () => {
-    // Regression for the QA "callout type -> [!info]" fidelity loss: `note` and
-    // `default` are valid editor callout types and must survive the git
-    // round-trip, not collapse to `info`.
-    expect(clampCalloutType('note')).toBe('note');
-    expect(clampCalloutType('default')).toBe('default');
-    expect(clampCalloutType('info')).toBe('info');
-    expect(clampCalloutType('warning')).toBe('warning');
-    expect(clampCalloutType('danger')).toBe('danger');
-    expect(clampCalloutType('success')).toBe('success');
-  });
-
-  it('maps GitHub/Obsidian alert ALIASES to the editor banner (not flatly info)', () => {
-    // The editor schema has no tip/caution/important callout node — they are input
-    // aliases the editor's own paste path maps onto the supported set
-    // (GITHUB_ALERT_TYPE_MAP in editor-ext). git-sync mirrors that aliasing so an
-    // ingested `> [!tip]` / `> [!caution]` lands on the closest real banner instead
-    // of collapsing everything to `info`.
-    expect(clampCalloutType('tip')).toBe('success');
-    expect(clampCalloutType('TIP')).toBe('success');
-    expect(clampCalloutType('caution')).toBe('danger');
-    expect(clampCalloutType('important')).toBe('info');
-  });
-
-  it('falls back to "info" for genuinely unknown types', () => {
-    expect(clampCalloutType('question')).toBe('info');
-    expect(clampCalloutType('banana')).toBe('info');
-  });
-
-  it('falls back to "info" for empty string and null', () => {
-    expect(clampCalloutType('')).toBe('info');
-    expect(clampCalloutType(null)).toBe('info');
-  });
-});
-
-// The htmlEmbed `source` rides the data-source attribute base64-encoded so the
-// raw HTML/CSS/JS stays inert and double-encoding-free across a round trip.
-// Encode/decode MUST be exact inverses (incl. UTF-8) or the embed body corrupts.
-describe('encode/decodeHtmlEmbedSource', () => {
-  it('round-trips ASCII HTML losslessly', () => {
-    const src = '<b>hi</b>';
-    expect(decodeHtmlEmbedSource(encodeHtmlEmbedSource(src))).toBe(src);
-  });
-
-  it('round-trips multi-byte UTF-8 (Cyrillic + emoji) losslessly', () => {
-    const src = '<p>Привет, мир 🌍 — café</p>';
-    const encoded = encodeHtmlEmbedSource(src);
-    // It is actually encoded (not passed through verbatim).
-    expect(encoded).not.toBe(src);
-    expect(decodeHtmlEmbedSource(encoded)).toBe(src);
-  });
-
-  it('maps empty string to empty string both ways', () => {
-    expect(encodeHtmlEmbedSource('')).toBe('');
-    expect(decodeHtmlEmbedSource('')).toBe('');
-  });
-});
diff --git a/packages/git-sync/test/engine-gaps.test.ts b/packages/git-sync/test/engine-gaps.test.ts
index 3bb209eb..f582c9c7 100644
--- a/packages/git-sync/test/engine-gaps.test.ts
+++ b/packages/git-sync/test/engine-gaps.test.ts
@@ -8,7 +8,7 @@ import { firstDivergence } from './roundtrip-helpers';
 import { applyPullActions } from '../src/engine/pull';
 import type { PullActions, ApplyPullActionsDeps } from '../src/engine/pull';
 import type { DeletionDecision } from '../src/engine/reconcile';
-import { serializePageFile, parsePageFile } from '../src/lib/page-file';
+import { serializePageFile, parsePageFile } from '@docmost/prosemirror-markdown';
 
 // Engine-layer coverage gaps flagged by the PR #119 reviewers (test-strategy
 // report, Module 2 `src/engine`). Each block targets a specific under-covered
diff --git a/packages/git-sync/test/fixtures/corpus/01-headings-paragraphs.json b/packages/git-sync/test/fixtures/corpus/01-headings-paragraphs.json
deleted file mode 100644
index ebacda0e..00000000
--- a/packages/git-sync/test/fixtures/corpus/01-headings-paragraphs.json
+++ /dev/null
@@ -1,36 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "heading",
-      "attrs": { "level": 1 },
-      "content": [{ "type": "text", "text": "Level one heading" }]
-    },
-    {
-      "type": "paragraph",
-      "content": [{ "type": "text", "text": "A plain paragraph of text." }]
-    },
-    {
-      "type": "heading",
-      "attrs": { "level": 2 },
-      "content": [{ "type": "text", "text": "Level two heading" }]
-    },
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "First line of a paragraph" },
-        { "type": "hardBreak" },
-        { "type": "text", "text": "second line after a hard break." }
-      ]
-    },
-    {
-      "type": "heading",
-      "attrs": { "level": 3 },
-      "content": [{ "type": "text", "text": "Level three heading" }]
-    },
-    {
-      "type": "paragraph",
-      "content": [{ "type": "text", "text": "Closing paragraph." }]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/02-inline-marks.json b/packages/git-sync/test/fixtures/corpus/02-inline-marks.json
deleted file mode 100644
index 41a9e618..00000000
--- a/packages/git-sync/test/fixtures/corpus/02-inline-marks.json
+++ /dev/null
@@ -1,62 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "marks": [{ "type": "bold" }], "text": "bold" },
-        { "type": "text", "text": " " },
-        { "type": "text", "marks": [{ "type": "italic" }], "text": "italic" },
-        { "type": "text", "text": " " },
-        { "type": "text", "marks": [{ "type": "code" }], "text": "code" },
-        { "type": "text", "text": " " },
-        { "type": "text", "marks": [{ "type": "strike" }], "text": "strike" }
-      ]
-    },
-    {
-      "type": "paragraph",
-      "content": [
-        {
-          "type": "text",
-          "marks": [
-            {
-              "type": "link",
-              "attrs": {
-                "href": "https://example.com/page"
-              }
-            }
-          ],
-          "text": "a link"
-        },
-        { "type": "text", "text": ", " },
-        {
-          "type": "text",
-          "marks": [{ "type": "highlight" }],
-          "text": "highlighted"
-        },
-        { "type": "text", "text": ", base" },
-        { "type": "text", "marks": [{ "type": "subscript" }], "text": "sub" },
-        { "type": "text", "text": " and base" },
-        { "type": "text", "marks": [{ "type": "superscript" }], "text": "sup" },
-        { "type": "text", "text": "." }
-      ]
-    },
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "Here is a " },
-        {
-          "type": "text",
-          "marks": [
-            {
-              "type": "comment",
-              "attrs": { "commentId": "cmt-xyz789" }
-            }
-          ],
-          "text": "commented anchor span"
-        },
-        { "type": "text", "text": " that must survive (SPEC §3)." }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/03-lists.json b/packages/git-sync/test/fixtures/corpus/03-lists.json
deleted file mode 100644
index 2b7209b5..00000000
--- a/packages/git-sync/test/fixtures/corpus/03-lists.json
+++ /dev/null
@@ -1,113 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "bulletList",
-      "content": [
-        {
-          "type": "listItem",
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "First bullet" }]
-            }
-          ]
-        },
-        {
-          "type": "listItem",
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "Second bullet with a nested list" }]
-            },
-            {
-              "type": "bulletList",
-              "content": [
-                {
-                  "type": "listItem",
-                  "content": [
-                    {
-                      "type": "paragraph",
-                      "content": [{ "type": "text", "text": "Nested bullet A" }]
-                    }
-                  ]
-                },
-                {
-                  "type": "listItem",
-                  "content": [
-                    {
-                      "type": "paragraph",
-                      "content": [{ "type": "text", "text": "Nested bullet B" }]
-                    }
-                  ]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "orderedList",
-      "content": [
-        {
-          "type": "listItem",
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "First ordered item" }]
-            }
-          ]
-        },
-        {
-          "type": "listItem",
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "Second ordered item" }]
-            },
-            {
-              "type": "orderedList",
-              "content": [
-                {
-                  "type": "listItem",
-                  "content": [
-                    {
-                      "type": "paragraph",
-                      "content": [{ "type": "text", "text": "Nested ordered one" }]
-                    }
-                  ]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "taskList",
-      "content": [
-        {
-          "type": "taskItem",
-          "attrs": { "checked": true },
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "Done task" }]
-            }
-          ]
-        },
-        {
-          "type": "taskItem",
-          "attrs": { "checked": false },
-          "content": [
-            {
-              "type": "paragraph",
-              "content": [{ "type": "text", "text": "Pending task" }]
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/04-blocks.json b/packages/git-sync/test/fixtures/corpus/04-blocks.json
deleted file mode 100644
index 4eb8a7e6..00000000
--- a/packages/git-sync/test/fixtures/corpus/04-blocks.json
+++ /dev/null
@@ -1,38 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "blockquote",
-      "content": [
-        {
-          "type": "paragraph",
-          "content": [{ "type": "text", "text": "A quoted line." }]
-        },
-        {
-          "type": "paragraph",
-          "content": [{ "type": "text", "text": "A second quoted paragraph." }]
-        }
-      ]
-    },
-    {
-      "type": "horizontalRule"
-    },
-    {
-      "type": "codeBlock",
-      "attrs": { "language": "js" },
-      "content": [
-        { "type": "text", "text": "const a = 1;\nconsole.log(a);\n" }
-      ]
-    },
-    {
-      "type": "callout",
-      "attrs": { "type": "warning" },
-      "content": [
-        {
-          "type": "paragraph",
-          "content": [{ "type": "text", "text": "This is a warning callout." }]
-        }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/05-table.json b/packages/git-sync/test/fixtures/corpus/05-table.json
deleted file mode 100644
index 3a062e7b..00000000
--- a/packages/git-sync/test/fixtures/corpus/05-table.json
+++ /dev/null
@@ -1,85 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "table",
-      "content": [
-        {
-          "type": "tableRow",
-          "content": [
-            {
-              "type": "tableHeader",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "Name" }]
-                }
-              ]
-            },
-            {
-              "type": "tableHeader",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "Value" }]
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "type": "tableRow",
-          "content": [
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "alpha" }]
-                }
-              ]
-            },
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "1" }]
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "type": "tableRow",
-          "content": [
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "beta" }]
-                }
-              ]
-            },
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "2" }]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/06-diagrams.json b/packages/git-sync/test/fixtures/corpus/06-diagrams.json
deleted file mode 100644
index ea069091..00000000
--- a/packages/git-sync/test/fixtures/corpus/06-diagrams.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "paragraph",
-      "content": [{ "type": "text", "text": "A drawio and an excalidraw diagram follow." }]
-    },
-    {
-      "type": "drawio",
-      "attrs": { "src": "/api/files/def/flow.drawio", "align": "center", "attachmentId": "att-1" }
-    },
-    {
-      "type": "excalidraw",
-      "attrs": { "src": "/api/files/ghi/sketch.excalidraw", "align": "center", "attachmentId": "att-2" }
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/07-textstyle-mention.json b/packages/git-sync/test/fixtures/corpus/07-textstyle-mention.json
deleted file mode 100644
index 9cfbcc8d..00000000
--- a/packages/git-sync/test/fixtures/corpus/07-textstyle-mention.json
+++ /dev/null
@@ -1,35 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "Some " },
-        {
-          "type": "text",
-          "marks": [{ "type": "textStyle", "attrs": { "color": "#ff0000" } }],
-          "text": "red colored"
-        },
-        { "type": "text", "text": " text." }
-      ]
-    },
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "Ping " },
-        {
-          "type": "mention",
-          "attrs": {
-            "id": "m-1",
-            "label": "Alice",
-            "entityType": "user",
-            "entityId": "u-1",
-            "slugId": "s-1",
-            "creatorId": "c-1"
-          }
-        },
-        { "type": "text", "text": " please." }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/08-details.json b/packages/git-sync/test/fixtures/corpus/08-details.json
deleted file mode 100644
index 74c26682..00000000
--- a/packages/git-sync/test/fixtures/corpus/08-details.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "details",
-      "attrs": { "open": false },
-      "content": [
-        { "type": "detailsSummary", "content": [{ "type": "text", "text": "Click to expand" }] },
-        { "type": "detailsContent", "content": [
-          { "type": "paragraph", "content": [{ "type": "text", "text": "Hidden body paragraph." }] }
-        ]}
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/09-columns.json b/packages/git-sync/test/fixtures/corpus/09-columns.json
deleted file mode 100644
index 49c0abe6..00000000
--- a/packages/git-sync/test/fixtures/corpus/09-columns.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "columns",
-      "attrs": { "layout": "two", "widthMode": "normal" },
-      "content": [
-        { "type": "column", "attrs": { "width": 50 }, "content": [
-          { "type": "paragraph", "content": [{ "type": "text", "text": "Left column." }] }
-        ]},
-        { "type": "column", "attrs": { "width": 50 }, "content": [
-          { "type": "paragraph", "content": [{ "type": "text", "text": "Right column." }] }
-        ]}
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/corpus/10-mention-in-heading.json b/packages/git-sync/test/fixtures/corpus/10-mention-in-heading.json
deleted file mode 100644
index 18fb0600..00000000
--- a/packages/git-sync/test/fixtures/corpus/10-mention-in-heading.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "heading",
-      "attrs": { "level": 2 },
-      "content": [
-        { "type": "text", "text": "Notes for " },
-        { "type": "mention", "attrs": { "id": "m-2", "label": "Bob", "entityType": "user", "entityId": "u-2", "slugId": "s-2", "creatorId": "c-2" } }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/known-limitations/image-diagrams.json b/packages/git-sync/test/fixtures/known-limitations/image-diagrams.json
deleted file mode 100644
index 2d8e12b7..00000000
--- a/packages/git-sync/test/fixtures/known-limitations/image-diagrams.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "paragraph",
-      "content": [{ "type": "text", "text": "An image followed by two diagrams." }]
-    },
-    {
-      "type": "image",
-      "attrs": { "src": "/api/files/abc/diagram.png", "alt": "A picture" }
-    },
-    {
-      "type": "drawio",
-      "attrs": { "src": "/api/files/def/flow.drawio", "attachmentId": "att-1" }
-    },
-    {
-      "type": "excalidraw",
-      "attrs": { "src": "/api/files/ghi/sketch.excalidraw", "attachmentId": "att-2" }
-    }
-  ]
-}
diff --git a/packages/git-sync/test/fixtures/sample-doc.json b/packages/git-sync/test/fixtures/sample-doc.json
deleted file mode 100644
index 137a6bd0..00000000
--- a/packages/git-sync/test/fixtures/sample-doc.json
+++ /dev/null
@@ -1,151 +0,0 @@
-{
-  "type": "doc",
-  "content": [
-    {
-      "type": "heading",
-      "attrs": { "level": 1, "id": "h-1" },
-      "content": [{ "type": "text", "text": "Round-trip sample" }]
-    },
-    {
-      "type": "paragraph",
-      "attrs": { "id": "p-1" },
-      "content": [
-        { "type": "text", "text": "This paragraph has " },
-        { "type": "text", "marks": [{ "type": "bold" }], "text": "bold" },
-        { "type": "text", "text": ", " },
-        { "type": "text", "marks": [{ "type": "italic" }], "text": "italic" },
-        { "type": "text", "text": " and a " },
-        {
-          "type": "text",
-          "marks": [
-            {
-              "type": "link",
-              "attrs": {
-                "href": "https://example.com"
-              }
-            }
-          ],
-          "text": "link"
-        },
-        { "type": "text", "text": "." }
-      ]
-    },
-    {
-      "type": "paragraph",
-      "attrs": { "id": "p-2" },
-      "content": [
-        { "type": "text", "text": "Here is a " },
-        {
-          "type": "text",
-          "marks": [
-            { "type": "comment", "attrs": { "commentId": "cmt-abc123", "resolved": false } }
-          ],
-          "text": "commented span"
-        },
-        { "type": "text", "text": " that must survive the round-trip." }
-      ]
-    },
-    {
-      "type": "bulletList",
-      "attrs": { "id": "ul-1" },
-      "content": [
-        {
-          "type": "listItem",
-          "attrs": { "id": "li-1" },
-          "content": [
-            {
-              "type": "paragraph",
-              "attrs": { "id": "p-3" },
-              "content": [{ "type": "text", "text": "First bullet" }]
-            }
-          ]
-        },
-        {
-          "type": "listItem",
-          "attrs": { "id": "li-2" },
-          "content": [
-            {
-              "type": "paragraph",
-              "attrs": { "id": "p-4" },
-              "content": [{ "type": "text", "text": "Second bullet" }]
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "table",
-      "attrs": { "id": "tbl-1" },
-      "content": [
-        {
-          "type": "tableRow",
-          "content": [
-            {
-              "type": "tableHeader",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "Name" }]
-                }
-              ]
-            },
-            {
-              "type": "tableHeader",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "Value" }]
-                }
-              ]
-            }
-          ]
-        },
-        {
-          "type": "tableRow",
-          "content": [
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "alpha" }]
-                }
-              ]
-            },
-            {
-              "type": "tableCell",
-              "attrs": { "colspan": 1, "rowspan": 1 },
-              "content": [
-                {
-                  "type": "paragraph",
-                  "content": [{ "type": "text", "text": "1" }]
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "callout",
-      "attrs": { "type": "info", "id": "callout-1" },
-      "content": [
-        {
-          "type": "paragraph",
-          "attrs": { "id": "p-5" },
-          "content": [{ "type": "text", "text": "This is an info callout." }]
-        }
-      ]
-    },
-    {
-      "type": "codeBlock",
-      "attrs": { "language": "js", "id": "code-1" },
-      "content": [
-        { "type": "text", "text": "const a = 1;\nconsole.log(a);\n" }
-      ]
-    }
-  ]
-}
diff --git a/packages/git-sync/test/markdown-converter-gaps.test.ts b/packages/git-sync/test/markdown-converter-gaps.test.ts
deleted file mode 100644
index 47ab05bc..00000000
--- a/packages/git-sync/test/markdown-converter-gaps.test.ts
+++ /dev/null
@@ -1,845 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
-// pulls in collaboration.ts and mutates the global DOM at import time), matching
-// the other converter unit tests. markdownToProseMirror is imported for the
-// round-trip cases; loading it mutates the global DOM via jsdom (required for
-// @tiptap/html's generateJSON under Node) — this is expected.
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-
-// Wrap one or more nodes in a minimal ProseMirror doc. The top-level converter
-// joins doc children with "\n\n" then .trim()s, so a single-node doc yields
-// exactly that node's rendered (trimmed) string.
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-const text = (t: string) => ({ type: 'text', text: t });
-const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
-
-// Run a full export -> import -> export cycle and return both markdown strings
-// plus the intermediate ProseMirror doc (mirrors the property test's helper).
-async function roundTrip(node: any): Promise<{ md1: string; doc2: any; md2: string }> {
-  const md1 = convertProseMirrorToMarkdown(doc(node));
-  const doc2 = await markdownToProseMirror(md1);
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  return { md1, doc2, md2 };
-}
-
-// ---------------------------------------------------------------------------
-// 1. pageBreak DATA LOSS (markdown-converter.ts has NO `case "pageBreak"`).
-//
-// The schema declares a `pageBreak` block atom (docmost-schema.ts ~L1009), so a
-// real document CAN legally contain one. The converter's switch has no branch
-// for it, so it falls through to `default`, which renders only the node's
-// children — and a pageBreak atom has NONE. It therefore exports to "" and the
-// node silently disappears: an exported markdown file can never carry a page
-// break, and a round-trip cannot reconstruct it. We pin this as a known
-// divergence with an `it.fails` round-trip repro (mirroring the package's two
-// existing documented `it.fails` bugs in markdown-roundtrip.property.test.ts).
-// ---------------------------------------------------------------------------
-describe('pageBreak data loss (no converter case — SPEC §11 divergence)', () => {
-  it('exports a pageBreak node to the schema-matching block div', () => {
-    // FIXED: a standalone pageBreak now emits the block-level HTML div so the
-    // node survives instead of being erased to "".
-    expect(convertProseMirrorToMarkdown(doc({ type: 'pageBreak' }))).toBe(
-      '<div data-type="pageBreak"></div>',
-    );
-  });
-
-  it('keeps a pageBreak sitting BETWEEN two paragraphs on export', () => {
-    // FIXED: with surrounding content the divider is emitted as its own block
-    // between the two paragraphs (joined by the doc "\n\n"), no longer dropped.
-    const out = convertProseMirrorToMarkdown(
-      doc(para(text('before')), { type: 'pageBreak' }, para(text('after'))),
-    );
-    expect(out).toBe(
-      'before\n\n<div data-type="pageBreak"></div>\n\nafter',
-    );
-    expect(out).toContain('pageBreak');
-  });
-
-  // FIXED: a pageBreak node now survives an export -> import -> export cycle
-  // because the FIRST export emits the schema-matching block div, which marked
-  // passes through and generateJSON rebuilds into a pageBreak node again.
-  it('a pageBreak node round-trips (export -> import yields a pageBreak)', async () => {
-    const { md1, doc2 } = await roundTrip({ type: 'pageBreak' });
-    expect(md1).not.toBe('');
-    const types = (doc2.content || []).map((n: any) => n.type);
-    expect(types).toContain('pageBreak');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 2. subpages round-trip (`case "subpages"` emits the schema-matching div).
-//
-// It used to emit the literal `{{SUBPAGES}}`, which has no markdown/HTML meaning,
-// so on re-import the subpages BLOCK came back as a plain PARAGRAPH carrying the
-// literal string (the embed rendered as visible "{{SUBPAGES}}" text on the page
-// after a sync — data loss). It now emits `<div data-type="subpages">` like the
-// other embed nodes, so the schema's parseHTML rebuilds the subpages node.
-// ---------------------------------------------------------------------------
-describe('subpages round-trip (schema-matching div)', () => {
-  it('emits the subpages div and re-imports as a subpages node (no literal leak)', async () => {
-    const { md1, doc2 } = await roundTrip({ type: 'subpages' });
-    expect(md1).toBe('<div data-type="subpages"></div>');
-
-    const collect = (n: any): string[] => [
-      n.type,
-      ...((n.content || []) as any[]).flatMap(collect),
-    ];
-    const allTypes = (doc2.content || []).flatMap(collect);
-    // The subpages node survives, and no literal {{SUBPAGES}} text leaked back.
-    expect(allTypes).toContain('subpages');
-    expect(JSON.stringify(doc2)).not.toContain('{{SUBPAGES}}');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 3. column.width number<->string drift (`case "column"` + width parseHTML).
-//
-// The converter emits the width verbatim into `data-width="..."` (a STRING in
-// the HTML, as all HTML attributes are). On import the schema's `column.width`
-// parseHTML does `parseFloat(value)`, so the attribute always comes back as a
-// NUMBER. A document authored/stored with a STRING fractional width therefore
-// DRIFTS to a number across a round-trip at the ProseMirror-doc level — even
-// though the emitted MARKDOWN stays byte-stable (the number prints the same).
-// Pinned here as a documented attribute-type divergence (SPEC §11).
-// ---------------------------------------------------------------------------
-describe('column.width number<->string drift (schema parseFloat — SPEC §11)', () => {
-  const columnsWith = (width: any) => ({
-    type: 'columns',
-    attrs: { layout: 'two' },
-    content: [
-      { type: 'column', attrs: { width }, content: [para(text('L'))] },
-      { type: 'column', content: [para(text('R'))] },
-    ],
-  });
-
-  it('a STRING fractional width drifts to a NUMBER across the round-trip', async () => {
-    const { md1, doc2, md2 } = await roundTrip(columnsWith('33.3'));
-
-    // The emitted markdown carries the value as an HTML attribute string and is
-    // byte-stable across the cycle (the divergence is at the doc level only).
-    expect(md1).toContain('data-width="33.3"');
-    expect(md2).toBe(md1);
-
-    // But the doc attribute type changed: authored as string "33.3", it comes
-    // back as the number 33.3 (schema's parseFloat). This is the drift.
-    const rtWidth = doc2.content?.[0]?.content?.[0]?.attrs?.width;
-    expect(typeof rtWidth).toBe('number');
-    expect(rtWidth).toBe(33.3);
-  });
-
-  it('a NUMBER fractional width keeps its value (no precision loss) and is byte-stable', async () => {
-    const { md1, doc2, md2 } = await roundTrip(columnsWith(33.333333));
-    expect(md1).toContain('data-width="33.333333"');
-    expect(md2).toBe(md1);
-    const rtWidth = doc2.content?.[0]?.content?.[0]?.attrs?.width;
-    expect(typeof rtWidth).toBe('number');
-    expect(rtWidth).toBe(33.333333);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 5b. EMPTY detailsContent (`case "details"` with an empty body).
-//
-// detailsContent's schema content is `block*` (docmost-schema.ts ~L474), so an
-// empty details body is legal. The converter must handle a `detailsContent`
-// with no children without crashing and without emitting invalid output that
-// breaks the round-trip. This pins that an empty details body exports cleanly
-// and re-imports as a valid `details` whose body is an empty `detailsContent`.
-// ---------------------------------------------------------------------------
-describe('empty detailsContent (schema allows block*)', () => {
-  const emptyDetails = doc({
-    type: 'details',
-    content: [
-      { type: 'detailsSummary', content: [text('Summary')] },
-      { type: 'detailsContent', content: [] },
-    ],
-  });
-
-  it('exports an empty details body without crashing or producing junk', () => {
-    const md = convertProseMirrorToMarkdown(emptyDetails);
-    // The summary survives and the <details> wrapper closes; the empty body adds
-    // no content of its own.
-    expect(md).toContain('<summary>Summary</summary>');
-    expect(md).toContain('</details>');
-    expect(md).not.toContain('undefined');
-    expect(md).not.toContain('null');
-  });
-
-  it('round-trips to a valid details with an empty detailsContent body', async () => {
-    const md1 = convertProseMirrorToMarkdown(emptyDetails);
-    const doc2 = await markdownToProseMirror(md1);
-    const md2 = convertProseMirrorToMarkdown(doc2);
-    // Export is byte-stable (no growth / no junk on the second pass).
-    expect(md2).toBe(md1);
-
-    // The re-imported tree is a details with summary + an empty content body.
-    const details = doc2.content?.[0];
-    expect(details?.type).toBe('details');
-    const childTypes = (details?.content || []).map((c: any) => c.type);
-    expect(childTypes).toEqual(['detailsSummary', 'detailsContent']);
-    const detailsContent = details.content.find(
-      (c: any) => c.type === 'detailsContent',
-    );
-    // block* — an empty body has no (or empty) content, which is valid.
-    expect(detailsContent.content == null || detailsContent.content.length === 0).toBe(
-      true,
-    );
-  });
-});
-
-// ===========================================================================
-// CONVERTER GAP COVERAGE (specs 1–29)
-//
-// These describe the converter's exact emission for under-tested branches and,
-// for the round-trip cases, pin export byte-stability and/or documented data
-// loss. docsCanonicallyEqual is imported here (not at the top) to keep the
-// existing block's imports untouched. heading/col are local helpers; doc/text/
-// para are reused from the top of the file.
-// ===========================================================================
-import { docsCanonicallyEqual } from '../src/lib/canonicalize.js';
-
-const heading = (level: number, ...inline: any[]) => ({
-  type: 'heading',
-  attrs: { level },
-  content: inline,
-});
-// A two-layout columns block carrying a single column with exactly one child —
-// the shared shape for the raw-HTML-container round-trip specs (15, 17–29).
-const oneColumn = (child: any) => ({
-  type: 'columns',
-  attrs: { layout: 'two' },
-  content: [{ type: 'column', content: [child] }],
-});
-// Extract the single column's single child node from a round-tripped doc.
-const colChildOf = (doc2: any) =>
-  doc2?.content?.[0]?.content?.[0]?.content?.[0];
-
-describe('converter gap coverage — emission branches (specs 1–11)', () => {
-  // 1. orderedList renders index+1 and DROPS the start attribute.
-  it('orderedList start:5 restarts numbering at 1 (start attr ignored)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'orderedList',
-        attrs: { start: 5 },
-        content: [
-          { type: 'listItem', content: [para(text('a'))] },
-          { type: 'listItem', content: [para(text('b'))] },
-        ],
-      }),
-    );
-    expect(out).toBe('1. a\n2. b');
-  });
-
-  // 2. An empty paragraph contributes an empty segment between two "\n\n" joins.
-  it('an empty paragraph between two paragraphs yields doubled blank lines', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(para(text('a')), { type: 'paragraph' }, para(text('b'))),
-    );
-    expect(out).toBe('a\n\n\n\nb');
-  });
-
-  // 3. A code block inside a blockquote: every physical line gets "> ".
-  it('a codeBlock inside a blockquote prefixes every fence/code line with "> "', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'blockquote',
-        content: [
-          {
-            type: 'codeBlock',
-            attrs: { language: 'js' },
-            content: [text('a\nb')],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe('> ```js\n> a\n> b\n> ```');
-  });
-
-  // 4. A body cell with TWO block children (paragraph + bulletList) cannot be a
-  //    GFM pipe row (inline-only). #8 emits the WHOLE table as HTML <table> so
-  //    the paragraph and the list each survive as their own block instead of
-  //    being lossily flattened into one "p1 - a" pipe cell.
-  it('a table cell with paragraph+list emits an HTML <table> (blocks preserved)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'table',
-        content: [
-          {
-            type: 'tableRow',
-            content: [{ type: 'tableHeader', content: [para(text('h'))] }],
-          },
-          {
-            type: 'tableRow',
-            content: [
-              {
-                type: 'tableCell',
-                content: [
-                  para(text('p1')),
-                  {
-                    type: 'bulletList',
-                    content: [{ type: 'listItem', content: [para(text('a'))] }],
-                  },
-                ],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe(
-      '<table><tbody><tr><th><p>h</p></th></tr><tr><td><p>p1</p><ul><li><p>a</p></li></ul></td></tr></tbody></table>',
-    );
-  });
-
-  // 5. code + link co-occur: the schema's `code` mark excludes all other marks
-  //    (including link), so the link cannot survive import. The lossless,
-  //    byte-stable behavior is to emit ONLY the backtick code span (code wins).
-  it('a code+link run emits the backtick code form (code wins, link dropped)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(
-        para({
-          type: 'text',
-          text: 'x',
-          marks: [
-            { type: 'code' },
-            { type: 'link', attrs: { href: 'http://a?b&c"d' } },
-          ],
-        }),
-      ),
-    );
-    expect(out).toBe('`x`');
-  });
-
-  // 6. hardBreak inside a heading: prefix applied once, "  \n" between a and b.
-  it('a hardBreak inside an h2 heading produces "## a  \\nb"', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(heading(2, text('a'), { type: 'hardBreak' }, text('b'))),
-    );
-    expect(out).toBe('## a  \nb');
-  });
-
-  // 7. encodeMdUrl's non-space whitespace sub-path: a newline -> %0A.
-  it('an image src containing a newline percent-encodes it to %0A', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({ type: 'image', attrs: { alt: 'cap', src: '/a\nb.png' } }),
-    );
-    expect(out).toBe('![cap](/a%0Ab.png)');
-  });
-
-  // 8. spanned-table HTML fallback: rowspan>1 AND align cell-attr branches, <td>.
-  it('a spanned cell with rowspan+align emits <td rowspan align> in that order', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'table',
-        content: [
-          {
-            type: 'tableRow',
-            content: [
-              {
-                type: 'tableCell',
-                attrs: { rowspan: 2, align: 'center' },
-                content: [para(text('m'))],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe(
-      '<table><tbody><tr><td rowspan="2" align="center"><p>m</p></td></tr></tbody></table>',
-    );
-  });
-
-  // 9. taskItem fixed indent width of 2 (NOT prefix.length+1) for a nested sublist.
-  it('a task item with a nested bullet sublist indents the sublist by 2 columns', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'taskList',
-        content: [
-          {
-            type: 'taskItem',
-            attrs: { checked: false },
-            content: [
-              para(text('top')),
-              {
-                type: 'bulletList',
-                content: [
-                  { type: 'listItem', content: [para(text('child'))] },
-                ],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe('- [ ] top\n  - child');
-  });
-
-  // 10. A bulletList inside a blockquote: each list line independently prefixed.
-  it('a bulletList inside a blockquote prefixes every list line with "> "', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'blockquote',
-        content: [
-          {
-            type: 'bulletList',
-            content: [
-              { type: 'listItem', content: [para(text('x'))] },
-              { type: 'listItem', content: [para(text('y'))] },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe('> - x\n> - y');
-  });
-
-  // 11. A non-spanned cell with TWO block paragraphs: #8 emits the whole table
-  //     as HTML <table>, so each paragraph stays its own <p> and the literal
-  //     pipe needs no escaping inside HTML text (the old GFM path space-joined
-  //     the blocks into one line and escaped the pipe to \|).
-  it('a table cell with two paragraphs emits an HTML <table> (blocks kept, no pipe-escape)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'table',
-        content: [
-          {
-            type: 'tableRow',
-            content: [{ type: 'tableHeader', content: [para(text('h'))] }],
-          },
-          {
-            type: 'tableRow',
-            content: [
-              {
-                type: 'tableCell',
-                content: [para(text('a|b')), para(text('c'))],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe(
-      '<table><tbody><tr><th><p>h</p></th></tr><tr><td><p>a|b</p><p>c</p></td></tr></tbody></table>',
-    );
-  });
-});
-
-describe('converter gap coverage — documented round-trip data loss (specs 12–14)', () => {
-  // 12. A 3-backtick fence inside a codeBlock body is now lengthened: the outer
-  //     fence widens to (longest inner run + 1) backticks per CommonMark, so the
-  //     inner ``` is treated as content and the block survives as ONE node.
-  it('a triple-backtick fence inside a codeBlock body round-trips via a widened fence', async () => {
-    const d = doc({
-      type: 'codeBlock',
-      attrs: { language: 'js' },
-      content: [{ type: 'text', text: '```\ninner\n```' }],
-    });
-    const md1 = convertProseMirrorToMarkdown(d);
-    // Outer fence widened to 4 backticks; the inner 3-backtick fence is content.
-    expect(md1).toBe('````js\n```\ninner\n```\n````');
-
-    const doc2 = await markdownToProseMirror(md1);
-    // The block survives as a SINGLE code block (no premature split).
-    const top = doc2.content || [];
-    expect(top).toHaveLength(1);
-    expect(top[0].type).toBe('codeBlock');
-    expect(top[0].attrs?.language).toBe('js');
-    expect(top[0].content?.[0]?.text).toContain('```\ninner\n```');
-
-    const md2 = convertProseMirrorToMarkdown(doc2);
-    expect(md2).toBe(md1); // byte-stable
-    // Canonically the re-imported code text gains a single trailing newline
-    // (marked re-adds it; the exporter strips it back, hence byte stability).
-    // The fence is no longer lossy: the inner fence and content fully survive.
-    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
-  });
-
-  // 13. A leading ordered-list marker in paragraph text is NOT escaped, so a
-  //     plain paragraph silently becomes an orderedList on re-import.
-  it('a paragraph starting with "1. " is promoted to an orderedList on re-import', async () => {
-    const d = doc({
-      type: 'paragraph',
-      content: [{ type: 'text', text: '1. not a list' }],
-    });
-    const md1 = convertProseMirrorToMarkdown(d);
-    expect(md1).toBe('1. not a list'); // no backslash escape
-
-    const doc2 = await markdownToProseMirror(md1);
-    expect(doc2.content?.[0]?.type).toBe('orderedList');
-    const li = doc2.content[0].content?.[0];
-    expect(li?.type).toBe('listItem');
-    expect(li.content?.[0]?.content?.[0]).toMatchObject({
-      type: 'text',
-      text: 'not a list', // the "1. " was consumed as a list marker
-    });
-    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
-  });
-
-  // 14. The image emitter drops the title attribute (silently lost on round-trip).
-  it('an image title attribute is dropped on export and lost on re-import', async () => {
-    const d = doc({
-      type: 'image',
-      attrs: { src: '/i.png', alt: 'a', title: 't"q' },
-    });
-    const md1 = convertProseMirrorToMarkdown(d);
-    expect(md1).toBe('![a](/i.png)'); // no title, no quotes
-
-    const doc2 = await markdownToProseMirror(md1);
-    const img = (doc2.content || []).find((n: any) => n.type === 'image');
-    expect(img).toBeTruthy();
-    expect(img.attrs?.title).toBeNull(); // the original 't"q' was dropped
-    expect(img.attrs?.src).toBe('/i.png');
-    expect(img.attrs?.alt).toBe('a');
-    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
-  });
-});
-
-describe('converter gap coverage — raw-HTML container round-trips (specs 15–29)', () => {
-  // 15. image inside a column: imageToHtml width+align arms; byte-stable; no
-  //     literal-markdown text node leaks.
-  it('an image in a column emits <img> (width/align arms) and round-trips byte-stable', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({
-        type: 'image',
-        attrs: { src: '/i.png', alt: 'cap', width: 320, align: 'center' },
-      }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><img src="/i.png" alt="cap" width="320" align="center"></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('image');
-  });
-
-  // 16. image inside a SPANNED table cell (the other raw-HTML container).
-  it('an image in a spanned table cell emits <img> (width arm) and round-trips byte-stable', async () => {
-    const { md1, md2 } = await roundTrip({
-      type: 'table',
-      content: [
-        {
-          type: 'tableRow',
-          content: [
-            {
-              type: 'tableCell',
-              attrs: { colspan: 2 },
-              content: [
-                {
-                  type: 'image',
-                  attrs: { src: '/i.png', alt: 'x', width: 100 },
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    });
-    expect(md1).toBe(
-      '<table><tbody><tr><td colspan="2"><img src="/i.png" alt="x" width="100"></td></tr></tbody></table>',
-    );
-    expect(md2).toBe(md1);
-  });
-
-  // 17. callout inside a column: calloutToHtml lower-cases the type; byte-stable.
-  it('a callout in a column emits the HTML div (type lower-cased) and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({
-        type: 'callout',
-        attrs: { type: 'WARNING' },
-        content: [para(text('a'))],
-      }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><div data-type="callout" data-callout-type="warning"><p>a</p></div></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('callout');
-  });
-
-  // 18. details tree inside a column: summary via inlineToHtml, content via blockToHtml.
-  it('a details tree in a column emits <details>/<summary>/<div detailsContent> and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({
-        type: 'details',
-        content: [
-          { type: 'detailsSummary', content: [text('S')] },
-          { type: 'detailsContent', content: [para(text('body'))] },
-        ],
-      }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><details><summary data-type="detailsSummary">S</summary><div data-type="detailsContent"><p>body</p></div></details></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('details');
-  });
-
-  // 19. taskList inside a column: BOTH checked:true and checked:false arms.
-  it('a taskList in a column emits both data-checked arms and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({
-        type: 'taskList',
-        content: [
-          {
-            type: 'taskItem',
-            attrs: { checked: true },
-            content: [para(text('done'))],
-          },
-          {
-            type: 'taskItem',
-            attrs: { checked: false },
-            content: [para(text('todo'))],
-          },
-        ],
-      }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><ul data-type="taskList"><li data-type="taskItem" data-checked="true"><p>done</p></li><li data-type="taskItem" data-checked="false"><p>todo</p></li></ul></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('taskList');
-  });
-
-  // 20. bare taskItem (no wrapping taskList) inside a column self-wraps.
-  it('a bare taskItem in a column self-wraps in a single-item taskList and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({
-        type: 'taskItem',
-        attrs: { checked: false },
-        content: [para(text('lone'))],
-      }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><ul data-type="taskList"><li data-type="taskItem" data-checked="false"><p>lone</p></li></ul></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('taskList');
-  });
-
-  // 21. blockquote inside a column: real <blockquote>, not markdown "> q".
-  it('a blockquote in a column emits <blockquote> and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({ type: 'blockquote', content: [para(text('q'))] }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><blockquote><p>q</p></blockquote></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('blockquote');
-  });
-
-  // 22. horizontalRule inside a column: literal <hr>, not markdown "---".
-  it('a horizontalRule in a column emits <hr> and round-trips', async () => {
-    const { md1, doc2, md2 } = await roundTrip(
-      oneColumn({ type: 'horizontalRule' }),
-    );
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><hr></div></div>',
-    );
-    expect(md2).toBe(md1);
-    expect(colChildOf(doc2)?.type).toBe('horizontalRule');
-  });
-
-  // 23. Unknown block type with NON-text block children -> <div>-wrap of children.
-  it('an unknown block with block children wraps them in <div> (no markdown leak)', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn({
-          type: 'someFutureBlock',
-          content: [para(text('a')), para(text('b'))],
-        }),
-      ),
-    );
-    expect(md1).toContain('<div><p>a</p><p>b</p></div>');
-    // No markdown paragraph separator survives inside the raw-HTML column.
-    expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><div><p>a</p><p>b</p></div></div></div>',
-    );
-  });
-
-  // 24. Unknown block with ONLY inline/text children -> <div>inlineToHtml</div>.
-  it('an unknown block with only inline children renders inline as HTML (marks not markdown)', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn({
-          type: 'someInlineOnlyBlock',
-          content: [text('hi'), { type: 'text', text: '!', marks: [{ type: 'bold' }] }],
-        }),
-      ),
-    );
-    expect(md1).toContain('<div>hi<strong>!</strong></div>');
-  });
-
-  // 25. mathBlock inside a column delegates through processNode (NOT $$ fence).
-  it('a mathBlock in a column delegates to processNode (HTML div, no $$ fence)', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(oneColumn({ type: 'mathBlock', attrs: { text: 'a^2+b^2' } })),
-    );
-    expect(md1).toContain(
-      '<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>',
-    );
-    expect(md1).not.toContain('$$');
-  });
-
-  // 26. SPANNED table inside a column delegates to processNode -> raw <table>.
-  it('a spanned table in a column delegates to raw <table> HTML (no GFM pipes)', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn({
-          type: 'table',
-          content: [
-            {
-              type: 'tableRow',
-              content: [
-                {
-                  type: 'tableCell',
-                  attrs: { colspan: 2 },
-                  content: [para(text('x'))],
-                },
-              ],
-            },
-          ],
-        }),
-      ),
-    );
-    expect(md1).toContain('<table');
-    expect(md1).toContain('colspan="2"');
-    // No GFM pipe-table separator leaked into the raw-HTML column.
-    expect(md1).not.toContain('| --- |');
-  });
-
-  // 27. list item with TWO block children (paragraph + codeBlock) -> blockChildrenToHtml.
-  it('a list item with paragraph+codeBlock in a column emits both blocks as HTML', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn({
-          type: 'bulletList',
-          content: [
-            {
-              type: 'listItem',
-              content: [
-                para(text('p')),
-                {
-                  type: 'codeBlock',
-                  attrs: { language: 'js' },
-                  content: [text('a\nb')],
-                },
-              ],
-            },
-          ],
-        }),
-      ),
-    );
-    expect(md1).toContain('<p>p</p>');
-    expect(md1).toContain('<pre><code class="language-js">a\nb</code></pre>');
-    // The two blocks appear sequentially inside the same <li>.
-    expect(md1).toContain(
-      '<li><p>p</p><pre><code class="language-js">a\nb</code></pre></li>',
-    );
-  });
-
-  // 28. ordered list item whose 2nd block child is a NESTED bulletList.
-  it('an ordered list item with a nested bulletList in a column emits nested <ul> HTML', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn({
-          type: 'orderedList',
-          content: [
-            {
-              type: 'listItem',
-              content: [
-                para(text('p1')),
-                {
-                  type: 'bulletList',
-                  content: [
-                    { type: 'listItem', content: [para(text('nested'))] },
-                  ],
-                },
-              ],
-            },
-          ],
-        }),
-      ),
-    );
-    // NOTE(review): the spec's expected literal said '<ul><li>nested</li></ul>',
-    // but blockChildrenToHtml renders the nested listItem's paragraph child as a
-    // real <p>, so the actual (correct) emission is '<ul><li><p>nested</p></li></ul>'.
-    expect(md1).toContain(
-      '<ol><li><p>p1</p><ul><li><p>nested</p></li></ul></li></ol>',
-    );
-    // No markdown list markers leaked into the raw-HTML column.
-    expect(md1).not.toContain('1. ');
-    expect(md1).not.toContain('- nested');
-  });
-
-  // 29. mathInline atom inside a column paragraph -> inlineToHtml delegates via processNode.
-  it('a mathInline atom in a column paragraph emits schema HTML (no $...$ fence)', () => {
-    const md1 = convertProseMirrorToMarkdown(
-      doc(oneColumn(para(text('eq: '), { type: 'mathInline', attrs: { text: 'x_i' } }))),
-    );
-    expect(md1).toContain(
-      '<p>eq: <span data-type="mathInline" data-katex="true" text="x_i"></span></p>',
-    );
-    expect(md1).not.toContain('$x_i$');
-  });
-});
-
-// ===========================================================================
-// 30. heading.textAlign round-trip (A1). The paragraph case already exports a
-// non-default alignment as a styled `<p style="text-align:…">` that re-parses
-// losslessly; headings used to emit only the bare `## text` form, silently
-// DROPPING textAlign on export. The heading case is now symmetric: an aligned
-// heading exports as `<hN style="text-align:…">` and re-parses back to a heading
-// carrying BOTH the level and the textAlign, so the round-trip is lossless; an
-// UNaligned heading still emits the bare `## text` markdown form (no churn).
-// ===========================================================================
-const alignedHeading = (level: number, align: string, ...inline: any[]) => ({
-  type: 'heading',
-  attrs: { level, textAlign: align },
-  content: inline,
-});
-
-describe('heading.textAlign round-trip (A1)', () => {
-  it('an aligned heading exports as <hN style="text-align:…"> (not bare ##)', () => {
-    expect(convertProseMirrorToMarkdown(doc(alignedHeading(2, 'center', text('Title'))))).toBe(
-      '<h2 style="text-align:center">Title</h2>',
-    );
-  });
-
-  it('survives export -> import -> export losslessly (level AND textAlign preserved)', async () => {
-    const input = alignedHeading(2, 'center', text('Title'));
-    const { md1, doc2, md2 } = await roundTrip(input);
-    // Export direction: a styled <hN>, injection-safe via escapeAttr.
-    expect(md1).toBe('<h2 style="text-align:center">Title</h2>');
-    // Import direction: re-parses to a heading node with the level AND textAlign
-    // (the raw <hN style> HTML block flows through marked -> generateJSON, where
-    // the heading parse rule matches and the textAlign global attr reads the
-    // style back). Byte-stable second export closes the loop.
-    const h = doc2.content[0];
-    expect(h.type).toBe('heading');
-    expect(h.attrs.level).toBe(2);
-    expect(h.attrs.textAlign).toBe('center');
-    expect(md2).toBe(md1);
-    // Canonical equality of the re-parsed doc against the original input doc.
-    expect(docsCanonicallyEqual(doc2, doc(input))).toBe(true);
-  });
-
-  it('a right-aligned h3 round-trips its level and alignment', async () => {
-    const { doc2 } = await roundTrip(alignedHeading(3, 'right', text('Head')));
-    const h = doc2.content[0];
-    expect(h.type).toBe('heading');
-    expect(h.attrs.level).toBe(3);
-    expect(h.attrs.textAlign).toBe('right');
-  });
-
-  it('an UNaligned heading still emits the bare "## text" form (no HTML churn)', () => {
-    const bare = convertProseMirrorToMarkdown(doc(heading(2, text('Plain'))));
-    expect(bare).toBe('## Plain');
-    expect(bare).not.toContain('<h2');
-    // The default "left" alignment is likewise NOT wrapped.
-    expect(
-      convertProseMirrorToMarkdown(doc(alignedHeading(2, 'left', text('Plain')))),
-    ).toBe('## Plain');
-  });
-});
diff --git a/packages/git-sync/test/markdown-converter-golden.test.ts b/packages/git-sync/test/markdown-converter-golden.test.ts
deleted file mode 100644
index f8ba6b76..00000000
--- a/packages/git-sync/test/markdown-converter-golden.test.ts
+++ /dev/null
@@ -1,402 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
-// collaboration.ts and mutates global DOM at import time).
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-
-// markdown-converter.ts is the weakest pure module (report §2). These golden
-// tests close the gaps the base markdown-converter.test.ts leaves open:
-// columns/column wrapper, embed/audio/pdf (used to emit nothing), drawio/
-// excalidraw data-align presence rule, the remaining inline-mark matrix,
-// paragraph.textAlign, subpages + unknown-in-container fallback, escaping
-// idempotence, table-cell pipe/newline sanitization, and empty/single-column
-// tables. Cases already asserted in the base file are NOT repeated.
-
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-const c = (node: any) => convertProseMirrorToMarkdown(doc(node));
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
-
-describe('columns / column (raw-HTML layout wrapper)', () => {
-  it('wraps a multi-column layout as nested data-type divs with the children inside (regression: children unwrapped)', () => {
-    const out = c({
-      type: 'columns',
-      attrs: { layout: 'two' },
-      content: [
-        { type: 'column', attrs: { width: 50 }, content: [para(text('L'))] },
-        { type: 'column', content: [para(text('R'))] },
-      ],
-    });
-    expect(out).toBe(
-      '<div data-type="columns" data-layout="two">' +
-        '<div data-type="column" data-width="50"><p>L</p></div>' +
-        '<div data-type="column"><p>R</p></div>' +
-        '</div>',
-    );
-  });
-
-  it('omits the default widthMode "normal" but emits a non-default one', () => {
-    const normal = c({
-      type: 'columns',
-      attrs: { layout: 'two', widthMode: 'normal' },
-      content: [{ type: 'column', content: [para(text('x'))] }],
-    });
-    expect(normal).not.toContain('data-width-mode');
-    const wide = c({
-      type: 'columns',
-      attrs: { layout: 'two', widthMode: 'full' },
-      content: [{ type: 'column', content: [para(text('x'))] }],
-    });
-    expect(wide).toContain('data-width-mode="full"');
-  });
-});
-
-describe('embed / audio / pdf (previously emitted nothing — invisible regression)', () => {
-  it('embed emits div[data-type="embed"] with src/provider', () => {
-    expect(c({ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } })).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
-    );
-  });
-
-  it('audio emits a div-wrapped <audio> with src', () => {
-    expect(c({ type: 'audio', attrs: { src: '/a.mp3' } })).toBe(
-      '<div><audio src="/a.mp3"></audio></div>',
-    );
-  });
-
-  it('pdf emits div[data-type="pdf"] with src and name', () => {
-    expect(c({ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf' } })).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf"></div>',
-    );
-  });
-});
-
-describe('drawio / excalidraw data-align asymmetry (SPEC §11)', () => {
-  it('drawio: data-align is ABSENT when align is unset', () => {
-    const out = c({ type: 'drawio', attrs: { src: '/d.drawio' } });
-    expect(out).toBe('<div data-type="drawio" data-src="/d.drawio"></div>');
-    expect(out).not.toContain('data-align');
-  });
-
-  it('drawio: data-align is PRESENT for a non-default align', () => {
-    expect(c({ type: 'drawio', attrs: { src: '/d.drawio', align: 'right' } })).toBe(
-      '<div data-type="drawio" data-src="/d.drawio" data-align="right"></div>',
-    );
-  });
-
-  it('excalidraw: data-align is ABSENT when align is unset', () => {
-    const out = c({ type: 'excalidraw', attrs: { src: '/e.excalidraw' } });
-    expect(out).toBe('<div data-type="excalidraw" data-src="/e.excalidraw"></div>');
-    expect(out).not.toContain('data-align');
-  });
-});
-
-describe('inline-mark matrix (underline/sub/sup/highlight±color/textStyle/comment)', () => {
-  it('emits the schema HTML for each remaining inline mark in one matrix', () => {
-    const cases: [any[], string][] = [
-      [[{ type: 'underline' }], '<u>m</u>'],
-      [[{ type: 'subscript' }], '<sub>m</sub>'],
-      [[{ type: 'superscript' }], '<sup>m</sup>'],
-      [[{ type: 'highlight' }], '<mark>m</mark>'],
-      [
-        [{ type: 'highlight', attrs: { color: '#ff0000' } }],
-        '<mark style="background-color: #ff0000">m</mark>',
-      ],
-      [
-        [{ type: 'textStyle', attrs: { color: '#00ff00' } }],
-        '<span style="color: #00ff00">m</span>',
-      ],
-      [
-        [{ type: 'comment', attrs: { commentId: 'cid-1' } }],
-        '<span data-comment-id="cid-1">m</span>',
-      ],
-      [
-        [{ type: 'comment', attrs: { commentId: 'cid-1', resolved: true } }],
-        '<span data-comment-id="cid-1" data-resolved="true">m</span>',
-      ],
-    ];
-    for (const [marks, expected] of cases) {
-      expect(c(para(text('m', marks)))).toBe(expected);
-    }
-  });
-
-  it('a textStyle mark with no color emits nothing (plain text passes through)', () => {
-    expect(c(para(text('plain', [{ type: 'textStyle', attrs: {} }])))).toBe('plain');
-  });
-
-  it('a comment mark with no commentId emits nothing (plain text)', () => {
-    expect(c(para(text('plain', [{ type: 'comment', attrs: {} }])))).toBe('plain');
-  });
-});
-
-describe('paragraph.textAlign -> <p style="text-align:...">', () => {
-  it('non-default alignment emits an HTML <p style="text-align:...">', () => {
-    // #7 fix: a non-default paragraph alignment now round-trips. It is exported
-    // as an HTML `<p style="text-align:center">` (the schema's paragraph
-    // parseHTML reads `style="text-align"` back onto `textAlign` on import), so
-    // the alignment survives instead of collapsing to bare text. (The old
-    // `<div align="center">` form was NOT re-parsed onto the paragraph and was
-    // therefore lossy.)
-    expect(c({ type: 'paragraph', attrs: { textAlign: 'center' }, content: [text('x')] })).toBe(
-      '<p style="text-align:center">x</p>',
-    );
-  });
-
-  it('textAlign "left" (the default) is NOT wrapped', () => {
-    expect(c({ type: 'paragraph', attrs: { textAlign: 'left' }, content: [text('x')] })).toBe('x');
-  });
-});
-
-describe('subpages token + unknown-in-container fallback', () => {
-  it('subpages emits the schema-matching div (round-trips, unlike the old {{SUBPAGES}} literal)', () => {
-    expect(c({ type: 'subpages' })).toBe('<div data-type="subpages"></div>');
-  });
-
-  it('an unknown block inside a raw-HTML container is wrapped in <div> (never markdown)', () => {
-    // Inside columns the children are rendered as HTML; an unknown block type
-    // must NOT fall back to markdown (which would land as literal text on
-    // re-import). It is wrapped in a <div> so its children survive.
-    const out = c({
-      type: 'columns',
-      attrs: { layout: 'two' },
-      content: [
-        { type: 'column', content: [{ type: 'weirdBlock', content: [para(text('kept'))] }] },
-      ],
-    });
-    expect(out).toBe(
-      '<div data-type="columns" data-layout="two">' +
-        '<div data-type="column"><div><p>kept</p></div></div>' +
-        '</div>',
-    );
-  });
-
-  it('an unknown TOP-LEVEL block falls back to its children only (markdown context)', () => {
-    expect(c({ type: 'totallyUnknown', content: [text('inner')] })).toBe('inner');
-  });
-});
-
-describe('escaping idempotence (SPEC §11 phantom-diff guard)', () => {
-  it('escapeAttr escapes ONLY & and " in an attribute context, and is idempotent', () => {
-    // The mathBlock `text` attr goes through escapeAttr. & -> &amp;, " -> &quot;.
-    const once = c({ type: 'mathBlock', attrs: { text: 'a & "b"' } });
-    expect(once).toBe(
-      '<div data-type="mathBlock" data-katex="true" text="a &amp; &quot;b&quot;"></div>',
-    );
-    // < and > are deliberately NOT escaped (would accumulate on round-trips).
-    const angled = c({ type: 'mathBlock', attrs: { text: 'a < b > c' } });
-    expect(angled).toContain('text="a < b > c"');
-    expect(angled).not.toContain('&lt;');
-    expect(angled).not.toContain('&gt;');
-  });
-
-  it('encodeMdUrl turns a space into %20 in an image src (single inert URL token)', () => {
-    expect(c({ type: 'image', attrs: { alt: 'c', src: '/my pic.png' } })).toBe(
-      '![c](/my%20pic.png)',
-    );
-  });
-});
-
-describe('multi-block table cell -> HTML <table> (#8: GFM pipes cannot hold block content)', () => {
-  it('emits the whole table as HTML <table> so a multi-paragraph cell survives', () => {
-    // A cell holding TWO block paragraphs cannot be represented by a GFM pipe
-    // row (one inline line only) — the old GFM path collapsed the two blocks
-    // into one line ("a\|b c"), losing the block boundary and forcing a fragile
-    // pipe-escape. #8 emits the WHOLE table as raw HTML <table> instead: the
-    // schema's table-family parseHTML round-trips it, each paragraph stays its
-    // own <p>, and the literal pipe needs no escaping inside HTML text.
-    const out = c({
-      type: 'table',
-      content: [
-        { type: 'tableRow', content: [
-          { type: 'tableHeader', content: [para(text('H'))] },
-        ]},
-        { type: 'tableRow', content: [
-          { type: 'tableCell', content: [para(text('a|b')), para(text('c'))] },
-        ]},
-      ],
-    });
-    expect(out).toBe(
-      '<table><tbody><tr><th><p>H</p></th></tr><tr><td><p>a|b</p><p>c</p></td></tr></tbody></table>',
-    );
-  });
-});
-
-describe('empty / single-column tables', () => {
-  it('a table with no rows renders as the empty string', () => {
-    expect(c({ type: 'table', content: [] })).toBe('');
-  });
-
-  it('a single-column GFM table emits one column with a "---" separator', () => {
-    const out = c({
-      type: 'table',
-      content: [
-        { type: 'tableRow', content: [{ type: 'tableHeader', content: [para(text('Only'))] }] },
-        { type: 'tableRow', content: [{ type: 'tableCell', content: [para(text('v'))] }] },
-      ],
-    });
-    expect(out).toBe('| Only |\n| --- |\n| v |');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Media / attachment / container full-attribute coverage. The base golden file
-// only sets the minimal attrs for each media node (src, or src+name), so the
-// optional-attribute emission branches and their exact ORDERING are uncovered.
-// These cases pin the full ordered attribute string for video/youtube/embed/
-// audio/pdf/attachment plus the all-absent side of every optional guard, and
-// the distinct HTML-container (blockToHtml / inlineToHtml) paths for an
-// orderedList and a hardBreak inside a column.
-// ---------------------------------------------------------------------------
-describe('media / attachment / container full-attribute golden coverage', () => {
-  it('video: emits all optional attrs in source order (alt->aria-label, attachmentId/size/align/aspectRatio->data-*)', () => {
-    expect(
-      c({
-        type: 'video',
-        attrs: {
-          src: '/v.mp4',
-          alt: 'clip',
-          attachmentId: 'att-1',
-          width: 640,
-          height: 480,
-          size: 1234,
-          align: 'center',
-          aspectRatio: 1.777,
-        },
-      }),
-    ).toBe(
-      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
-    );
-  });
-
-  it('video: with only src, every optional guard takes its false branch (src-only <video>, no data-type on wrapper)', () => {
-    expect(c({ type: 'video', attrs: { src: '/v.mp4' } })).toBe(
-      '<div><video src="/v.mp4"></video></div>',
-    );
-  });
-
-  it('youtube + embed: each emits its full optional attr set in source order', () => {
-    // (a) youtube: width/height/align all present -> data-* in order.
-    expect(
-      c({
-        type: 'youtube',
-        attrs: { src: 'https://youtu.be/abc', width: 560, height: 315, align: 'right' },
-      }),
-    ).toBe(
-      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
-    );
-    // (b) embed: align/width/height optional branches after src+provider.
-    expect(
-      c({
-        type: 'embed',
-        attrs: { src: 'https://x.com/e', provider: 'iframe', align: 'left', width: 600, height: 400 },
-      }),
-    ).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
-    );
-  });
-
-  it('audio: emits data-attachment-id then data-size after src when both are set', () => {
-    expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7', size: 9001 } })).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
-    );
-  });
-
-  it('audio: with attachmentId but no size, data-size is suppressed (size != null false branch)', () => {
-    expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7' } })).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7"></audio></div>',
-    );
-  });
-
-  it('pdf: emits the full optional attr set in order (data-name, data-attachment-id, data-size, width, height)', () => {
-    expect(
-      c({
-        type: 'pdf',
-        attrs: {
-          src: '/d.pdf',
-          name: 'd.pdf',
-          attachmentId: 'att-9',
-          size: 2048,
-          width: 800,
-          height: 600,
-        },
-      }),
-    ).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9" data-size="2048" width="800" height="600"></div>',
-    );
-  });
-
-  it('attachment: emits data-attachment-name/mime/size/id in order after the always-present url', () => {
-    expect(
-      c({
-        type: 'attachment',
-        attrs: {
-          url: '/f.zip',
-          name: 'f.zip',
-          mime: 'application/zip',
-          size: 512,
-          attachmentId: 'att-3',
-        },
-      }),
-    ).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
-    );
-  });
-
-  it('attachment: with only a url, no spurious data-attachment-name/mime/size/id appear (all guards false)', () => {
-    expect(c({ type: 'attachment', attrs: { url: '/f.zip' } })).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip"></div>',
-    );
-  });
-
-  it('orderedList inside a column renders via blockToHtml as <ol> (start attr DROPPED) with bold->strong, code->code', () => {
-    const out = c({
-      type: 'columns',
-      attrs: { layout: 'two' },
-      content: [
-        {
-          type: 'column',
-          content: [
-            {
-              type: 'orderedList',
-              attrs: { start: 3 },
-              content: [
-                {
-                  type: 'listItem',
-                  content: [para(text('a', [{ type: 'bold' }]))],
-                },
-                {
-                  type: 'listItem',
-                  content: [para(text('b', [{ type: 'code' }]))],
-                },
-              ],
-            },
-          ],
-        },
-      ],
-    });
-    // blockToHtml orderedList path emits a plain <ol> with no start attribute,
-    // and inlineToHtml maps bold->strong, code->code.
-    expect(out).toContain(
-      '<ol><li><p><strong>a</strong></p></li><li><p><code>b</code></p></li></ol>',
-    );
-    // The start:3 attr is NOT preserved in the HTML/column container path.
-    expect(out).not.toContain('start=');
-  });
-
-  it('hardBreak inside a column renders as <br> via inlineToHtml (not the markdown two-space form)', () => {
-    const out = c({
-      type: 'columns',
-      attrs: { layout: 'two' },
-      content: [
-        {
-          type: 'column',
-          content: [para(text('a'), { type: 'hardBreak' }, text('b'))],
-        },
-      ],
-    });
-    expect(out).toContain('<p>a<br>b</p>');
-    // The processNode markdown "  \n" hard-break form must NOT appear in the
-    // raw-HTML column container path.
-    expect(out).not.toContain('  \n');
-  });
-});
diff --git a/packages/git-sync/test/markdown-converter-html-marks.test.ts b/packages/git-sync/test/markdown-converter-html-marks.test.ts
deleted file mode 100644
index 8c011d9c..00000000
--- a/packages/git-sync/test/markdown-converter-html-marks.test.ts
+++ /dev/null
@@ -1,223 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
-// pulls in collaboration.ts and mutates the global DOM at import time), matching
-// the other converter unit tests (see markdown-converter-gaps.test.ts).
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-
-// Minimal ProseMirror builders. The top-level converter joins doc children with
-// "\n\n" then .trim()s, so a single-node doc yields exactly that node's rendered
-// (trimmed) string.
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
-
-// A columns node carrying a SINGLE column, whose content is the supplied block
-// children. columns/column are raw-HTML containers, so their children render via
-// blockToHtml -> inlineToHtml (the HTML-mirroring path under test).
-const oneColumn = (...blocks: any[]) => ({
-  type: 'columns',
-  attrs: { layout: 'two' },
-  content: [{ type: 'column', content: blocks }],
-});
-
-// Extract the inner HTML of the single column from a rendered columns string.
-// Output shape is:
-//   <div data-type="columns" data-layout="two"><div data-type="column">INNER</div></div>
-const COLUMN_PREFIX =
-  '<div data-type="columns" data-layout="two"><div data-type="column">';
-const COLUMN_SUFFIX = '</div></div>';
-const columnInner = (rendered: string): string => {
-  expect(rendered.startsWith(COLUMN_PREFIX)).toBe(true);
-  expect(rendered.endsWith(COLUMN_SUFFIX)).toBe(true);
-  return rendered.slice(COLUMN_PREFIX.length, rendered.length - COLUMN_SUFFIX.length);
-};
-
-// ---------------------------------------------------------------------------
-// 1. inlineToHtml mark-mirroring INSIDE a raw-HTML container (columns).
-//
-// At the TOP level the `text` case emits markdown markers (**, *, ``, ~~) for
-// bold/italic/code/strike. But inside columns (and spanned table cells) the
-// content is raw HTML that marked will NOT re-parse, so inlineToHtml
-// (markdown-converter.ts lines 599-619) MUST mirror each mark to HTML instead:
-// bold-><strong>, italic-><em>, code-><code>, strike-><s>, underline-><u>. This
-// is a DISTINCT branch from the top-level mark path; if it leaked markdown, the
-// literal ** / `` would survive as text on re-import.
-// ---------------------------------------------------------------------------
-describe('inlineToHtml: bold/italic/code/strike/underline -> HTML inside columns', () => {
-  it('mirrors each single-mark run to its schema HTML tag (not markdown markers)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn(
-          para(
-            text('b', [{ type: 'bold' }]),
-            text('i', [{ type: 'italic' }]),
-            text('c', [{ type: 'code' }]),
-            text('s', [{ type: 'strike' }]),
-            text('u', [{ type: 'underline' }]),
-          ),
-        ),
-      ),
-    );
-    expect(out).toBe(
-      '<div data-type="columns" data-layout="two">' +
-        '<div data-type="column">' +
-        '<p><strong>b</strong><em>i</em><code>c</code><s>s</s><u>u</u></p>' +
-        '</div></div>',
-    );
-    // Belt-and-suspenders: none of the top-level markdown markers leaked.
-    expect(out).not.toContain('**');
-    expect(out).not.toContain('~~');
-    expect(out).not.toContain('`');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 2. inlineToHtml: link/hardBreak/highlight/textStyle/comment inside columns.
-//
-// Exercises the remaining inlineToHtml branches that are uncovered inside a
-// raw-HTML container: link href escaping via escapeAttr (line 621; & -> &amp;,
-// " -> &quot;), hardBreak -> <br> (line 591), highlight WITH vs WITHOUT color
-// (624-626), textStyle color (628-630), and comment with data-resolved (632-638).
-// ---------------------------------------------------------------------------
-describe('inlineToHtml: link/hardBreak/highlight/textStyle/comment inside columns', () => {
-  it('escapes link hrefs, emits <br>, plain/colored <mark>, span color, and resolved comment', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn(
-          para(
-            text('lnk', [{ type: 'link', attrs: { href: 'http://a?b&c"d' } }]),
-            { type: 'hardBreak' },
-            text('hl', [{ type: 'highlight', attrs: { color: '#ff0000' } }]),
-            text('plain', [{ type: 'highlight' }]),
-            text('clr', [{ type: 'textStyle', attrs: { color: 'red' } }]),
-            text('cm', [
-              { type: 'comment', attrs: { commentId: 'c1', resolved: true } },
-            ]),
-          ),
-        ),
-      ),
-    );
-    expect(columnInner(out)).toBe(
-      '<p>' +
-        '<a href="http://a?b&amp;c&quot;d">lnk</a>' +
-        '<br>' +
-        '<mark style="background-color: #ff0000">hl</mark>' +
-        '<mark>plain</mark>' +
-        '<span style="color: red">clr</span>' +
-        '<span data-comment-id="c1" data-resolved="true">cm</span>' +
-        '</p>',
-    );
-  });
-
-  it('omits data-resolved when the comment is not resolved', () => {
-    // The resolved sub-branch (632-638) is load-bearing: an unresolved comment
-    // must emit a bare data-comment-id span with NO data-resolved attribute.
-    const out = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn(
-          para(
-            text('cm', [
-              { type: 'comment', attrs: { commentId: 'c1', resolved: false } },
-            ]),
-          ),
-        ),
-      ),
-    );
-    expect(columnInner(out)).toBe('<p><span data-comment-id="c1">cm</span></p>');
-    expect(out).not.toContain('data-resolved');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 3. blockToHtml non-paragraph branches inside columns: heading / codeBlock /
-//    bulletList.
-//
-// heading -> <hN> (718-721), codeBlock with-language vs no-language class fork
-// (730-742; the no-language `cls = ''` branch at 741 yields a BARE <code> with
-// no class), and bulletList -> <ul><li><p>...</p></li></ul> (722-725). Code text
-// is element TEXT content, so it is escapeHtmlText-escaped (not the attr escaper),
-// and embedded newlines are preserved verbatim.
-// ---------------------------------------------------------------------------
-describe('blockToHtml: heading / codeBlock(lang & no-lang) / bulletList inside columns', () => {
-  it('emits <hN>, language vs bare <pre><code>, and <ul><li><p>..</p></li>', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc(
-        oneColumn(
-          { type: 'heading', attrs: { level: 2 }, content: [text('H')] },
-          {
-            type: 'codeBlock',
-            attrs: { language: 'js' },
-            content: [text('a\nb')],
-          },
-          { type: 'codeBlock', content: [text('plain')] },
-          {
-            type: 'bulletList',
-            content: [
-              { type: 'listItem', content: [para(text('item'))] },
-            ],
-          },
-        ),
-      ),
-    );
-    expect(columnInner(out)).toBe(
-      '<h2>H</h2>' +
-        '<pre><code class="language-js">a\nb</code></pre>' +
-        '<pre><code>plain</code></pre>' +
-        '<ul><li><p>item</p></li></ul>',
-    );
-    // The no-language codeBlock must NOT carry a class attribute (the cls=''
-    // fork at line 741): its <code> opens bare.
-    expect(out).toContain('<pre><code>plain</code></pre>');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 4. Spanned-table renderHtmlCell + orderedList block child (HTML fallback).
-//
-// A colspan>1 cell forces the WHOLE table to the raw-<table> HTML fallback
-// (markdown-converter.ts ~287-331). renderHtmlCell emits colspan + align attrs
-// (312-316) and renders each block child via blockToHtml. An orderedList child
-// hits the blockToHtml orderedList branch (726-729), which emits
-// <ol><li><p>..</p></li>..</ol> — the schema's `start` attr is NOT emitted by
-// this HTML <ol> branch.
-// ---------------------------------------------------------------------------
-describe('spanned table: renderHtmlCell colspan/align + orderedList block child', () => {
-  it('renders the colspan/align cell with an <ol> (start attr is dropped)', () => {
-    const out = convertProseMirrorToMarkdown(
-      doc({
-        type: 'table',
-        content: [
-          {
-            type: 'tableRow',
-            content: [
-              {
-                type: 'tableCell',
-                attrs: { colspan: 2, align: 'center' },
-                content: [
-                  {
-                    type: 'orderedList',
-                    attrs: { start: 3 },
-                    content: [
-                      { type: 'listItem', content: [para(text('one'))] },
-                      { type: 'listItem', content: [para(text('two'))] },
-                    ],
-                  },
-                ],
-              },
-            ],
-          },
-        ],
-      }),
-    );
-    expect(out).toBe(
-      '<table><tbody><tr>' +
-        '<td colspan="2" align="center">' +
-        '<ol><li><p>one</p></li><li><p>two</p></li></ol>' +
-        '</td>' +
-        '</tr></tbody></table>',
-    );
-    // The HTML <ol> branch does not propagate the ProseMirror `start` attribute.
-    expect(out).not.toContain('start');
-  });
-});
diff --git a/packages/git-sync/test/markdown-converter.test.ts b/packages/git-sync/test/markdown-converter.test.ts
deleted file mode 100644
index 98cb88c0..00000000
--- a/packages/git-sync/test/markdown-converter.test.ts
+++ /dev/null
@@ -1,645 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
-// collaboration.ts and mutates global DOM at import time).
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-
-// Wrap a single node in a minimal ProseMirror doc. The top-level converter
-// joins doc children with "\n\n" and then .trim()s the whole output, so a
-// single-node doc yields exactly that node's rendered (and trimmed) string.
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-// Convenience: a text node, optionally with marks.
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-// Convenience: a paragraph wrapping inline children.
-const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
-
-describe('convertProseMirrorToMarkdown', () => {
-  // ---------------------------------------------------------------------------
-  describe('headings', () => {
-    it('emits the right number of "#" for levels 1-6', () => {
-      for (let level = 1; level <= 6; level++) {
-        const out = convertProseMirrorToMarkdown(
-          doc({ type: 'heading', attrs: { level }, content: [text('H')] }),
-        );
-        expect(out).toBe('#'.repeat(level) + ' H');
-      }
-    });
-
-    it('defaults to level 1 when level is missing', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'heading', content: [text('NoLevel')] }),
-      );
-      expect(out).toBe('# NoLevel');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('text marks', () => {
-    it('bold', () => {
-      expect(
-        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'bold' }])))),
-      ).toBe('**x**');
-    });
-
-    it('italic', () => {
-      expect(
-        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'italic' }])))),
-      ).toBe('*x*');
-    });
-
-    it('strike', () => {
-      expect(
-        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'strike' }])))),
-      ).toBe('~~x~~');
-    });
-
-    it('inline code (sole mark) uses backtick span', () => {
-      expect(
-        convertProseMirrorToMarkdown(doc(para(text('x', [{ type: 'code' }])))),
-      ).toBe('`x`');
-    });
-
-    it('code + another mark emits the backtick code form (code wins)', () => {
-      // The schema's `code` mark excludes all other marks, so the editor can
-      // never produce code+bold on one run and import always drops the co-mark.
-      // The lossless, byte-stable behavior is to emit ONLY the backtick code
-      // span and ignore the co-occurring mark.
-      const out = convertProseMirrorToMarkdown(
-        doc(para(text('x', [{ type: 'bold' }, { type: 'code' }]))),
-      );
-      expect(out).toBe('`x`');
-    });
-
-    it('code + strike combo emits the backtick code form (code wins)', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(para(text('x', [{ type: 'strike' }, { type: 'code' }]))),
-      );
-      expect(out).toBe('`x`');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('links', () => {
-    it('href only', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(para(text('site', [{ type: 'link', attrs: { href: 'https://e.com' } }]))),
-      );
-      expect(out).toBe('[site](https://e.com)');
-    });
-
-    it('href + title with an embedded double quote is escaped', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(
-          para(
-            text('site', [
-              { type: 'link', attrs: { href: 'https://e.com', title: 'a "b" c' } },
-            ]),
-          ),
-        ),
-      );
-      // The markdown link-title form escapes the inner " as \".
-      expect(out).toBe('[site](https://e.com "a \\"b\\" c")');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('image', () => {
-    it('percent-encodes spaces and parentheses in src', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'image',
-          attrs: { alt: 'cap', src: '/files/my pic (1).png' },
-        }),
-      );
-      // space -> %20, ( -> %28, ) -> %29
-      expect(out).toBe('![cap](/files/my%20pic%20%281%29.png)');
-    });
-
-    it('empty alt and missing src render harmlessly', () => {
-      const out = convertProseMirrorToMarkdown(doc({ type: 'image', attrs: {} }));
-      expect(out).toBe('![]()');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('codeBlock', () => {
-    it('with language', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'codeBlock',
-          attrs: { language: 'ts' },
-          content: [text('const a = 1;')],
-        }),
-      );
-      expect(out).toBe('```ts\nconst a = 1;\n```');
-    });
-
-    it('without language emits empty info string', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'codeBlock', content: [text('plain')] }),
-      );
-      expect(out).toBe('```\nplain\n```');
-    });
-
-    it('strips ALL trailing newlines for idempotency', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'codeBlock', content: [text('a\n\n\n')] }),
-      );
-      // Every trailing "\n" is removed, then exactly one is re-added by the fence.
-      expect(out).toBe('```\na\n```');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('lists', () => {
-    it('bullet list', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'bulletList',
-          content: [
-            { type: 'listItem', content: [para(text('one'))] },
-            { type: 'listItem', content: [para(text('two'))] },
-          ],
-        }),
-      );
-      expect(out).toBe('- one\n- two');
-    });
-
-    it('ordered list numbers items sequentially', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'orderedList',
-          content: [
-            { type: 'listItem', content: [para(text('a'))] },
-            { type: 'listItem', content: [para(text('b'))] },
-            { type: 'listItem', content: [para(text('c'))] },
-          ],
-        }),
-      );
-      expect(out).toBe('1. a\n2. b\n3. c');
-    });
-
-    it('nested bullet list indents the child by the 2-col marker width', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'bulletList',
-          content: [
-            {
-              type: 'listItem',
-              content: [
-                para(text('parent')),
-                {
-                  type: 'bulletList',
-                  content: [{ type: 'listItem', content: [para(text('child'))] }],
-                },
-              ],
-            },
-          ],
-        }),
-      );
-      // First line carries the marker; the nested list is indented 2 columns.
-      expect(out).toBe('- parent\n  - child');
-    });
-
-    it('nested ordered list indents by the wider 3-col marker width', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'orderedList',
-          content: [
-            {
-              type: 'listItem',
-              content: [
-                para(text('parent')),
-                {
-                  type: 'orderedList',
-                  content: [{ type: 'listItem', content: [para(text('child'))] }],
-                },
-              ],
-            },
-          ],
-        }),
-      );
-      // "1. " is 3 columns wide, so the continuation indent is 3 spaces.
-      expect(out).toBe('1. parent\n   1. child');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('task list', () => {
-    it('unchecked and checked items', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'taskList',
-          content: [
-            { type: 'taskItem', attrs: { checked: false }, content: [para(text('todo'))] },
-            { type: 'taskItem', attrs: { checked: true }, content: [para(text('done'))] },
-          ],
-        }),
-      );
-      expect(out).toBe('- [ ] todo\n- [x] done');
-    });
-
-    it('empty task item keeps its marker', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'taskList',
-          content: [{ type: 'taskItem', attrs: { checked: false }, content: [] }],
-        }),
-      );
-      expect(out).toBe('- [ ]');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('blockquote', () => {
-    it('single paragraph quote prefixes the line', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'blockquote', content: [para(text('quoted'))] }),
-      );
-      expect(out).toBe('> quoted');
-    });
-
-    it('multi-paragraph quote separates blocks with a bare ">" line', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'blockquote',
-          content: [para(text('first')), para(text('second'))],
-        }),
-      );
-      expect(out).toBe('> first\n>\n> second');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('breaks and rules', () => {
-    it('horizontal rule', () => {
-      expect(
-        convertProseMirrorToMarkdown(doc({ type: 'horizontalRule' })),
-      ).toBe('---');
-    });
-
-    it('hard break emits two trailing spaces then newline', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(para(text('a'), { type: 'hardBreak' }, text('b'))),
-      );
-      expect(out).toBe('a  \nb');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('tables', () => {
-    it('GFM table emits alignment markers derived from header cells', () => {
-      const headerRow = {
-        type: 'tableRow',
-        content: [
-          { type: 'tableHeader', attrs: { align: 'left' }, content: [para(text('L'))] },
-          { type: 'tableHeader', attrs: { align: 'center' }, content: [para(text('C'))] },
-          { type: 'tableHeader', attrs: { align: 'right' }, content: [para(text('R'))] },
-          { type: 'tableHeader', content: [para(text('N'))] },
-        ],
-      };
-      const bodyRow = {
-        type: 'tableRow',
-        content: [
-          { type: 'tableCell', content: [para(text('1'))] },
-          { type: 'tableCell', content: [para(text('2'))] },
-          { type: 'tableCell', content: [para(text('3'))] },
-          { type: 'tableCell', content: [para(text('4'))] },
-        ],
-      };
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'table', content: [headerRow, bodyRow] }),
-      );
-      expect(out).toBe(
-        [
-          '| L | C | R | N |',
-          '| :-- | :-: | --: | --- |',
-          '| 1 | 2 | 3 | 4 |',
-        ].join('\n'),
-      );
-    });
-
-    it('spanned table (colspan/rowspan) emits raw <table> HTML', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'table',
-          content: [
-            {
-              type: 'tableRow',
-              content: [
-                {
-                  type: 'tableHeader',
-                  attrs: { colspan: 2 },
-                  content: [para(text('wide'))],
-                },
-              ],
-            },
-            {
-              type: 'tableRow',
-              content: [
-                { type: 'tableCell', content: [para(text('a'))] },
-                { type: 'tableCell', content: [para(text('b'))] },
-              ],
-            },
-          ],
-        }),
-      );
-      expect(out).toBe(
-        '<table><tbody>' +
-          '<tr><th colspan="2"><p>wide</p></th></tr>' +
-          '<tr><td><p>a</p></td><td><p>b</p></td></tr>' +
-          '</tbody></table>',
-      );
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('callout and details', () => {
-    it('callout uses lowercased type fence', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'callout',
-          attrs: { type: 'WARNING' },
-          content: [para(text('beware'))],
-        }),
-      );
-      expect(out).toBe('> [!warning]\n> beware');
-    });
-
-    it('callout defaults to info', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'callout', content: [para(text('hi'))] }),
-      );
-      expect(out).toBe('> [!info]\n> hi');
-    });
-
-    it('details emits summary + content wrapped in <details>', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'details',
-          content: [
-            { type: 'detailsSummary', content: [text('Title')] },
-            { type: 'detailsContent', content: [para(text('Body'))] },
-          ],
-        }),
-      );
-      // details joins its children with "\n"; summary opens, content closes.
-      expect(out).toBe('<details>\n<summary>Title</summary>\n\nBody\n</details>');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('math', () => {
-    it('inline math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(para({ type: 'mathInline', attrs: { text: 'a < b' } })),
-      );
-      // < and > must NOT be HTML-escaped (idempotency); only & and " would be.
-      expect(out).toBe(
-        '<span data-type="mathInline" data-katex="true" text="a < b"></span>',
-      );
-      expect(out).not.toContain('&lt;');
-    });
-
-    it('block math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'mathBlock', attrs: { text: 'x > y & z' } }),
-      );
-      // & IS escaped (entity-significant), but < and > are NOT.
-      expect(out).toBe(
-        '<div data-type="mathBlock" data-katex="true" text="x > y &amp; z"></div>',
-      );
-      expect(out).not.toContain('&lt;');
-      expect(out).not.toContain('&gt;');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('inline atoms and media', () => {
-    it('mention emits schema span with data-* attrs and visible label', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(
-          para({
-            type: 'mention',
-            attrs: { id: 'u1', label: 'Alice', entityType: 'user' },
-          }),
-        ),
-      );
-      expect(out).toBe(
-        '<span data-type="mention" data-id="u1" data-label="Alice" data-entity-type="user">@Alice</span>',
-      );
-    });
-
-    it('attachment emits div with schema data-attachment-* attrs', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'attachment',
-          attrs: { url: '/files/x.zip', name: 'x.zip', mime: 'application/zip', size: 99 },
-        }),
-      );
-      expect(out).toBe(
-        '<div data-type="attachment" data-attachment-url="/files/x.zip" ' +
-          'data-attachment-name="x.zip" data-attachment-mime="application/zip" ' +
-          'data-attachment-size="99"></div>',
-      );
-    });
-
-    it('video emits a <div>-wrapped <video> with schema attrs', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'video',
-          attrs: { src: '/v.mp4', alt: 'clip', width: 640 },
-        }),
-      );
-      expect(out).toBe(
-        '<div><video src="/v.mp4" aria-label="clip" width="640"></video></div>',
-      );
-    });
-
-    it('youtube emits a div[data-type="youtube"] with data-src', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'youtube',
-          attrs: { src: 'https://youtu.be/abc', width: 560, height: 315 },
-        }),
-      );
-      expect(out).toBe(
-        '<div data-type="youtube" data-src="https://youtu.be/abc" ' +
-          'data-width="560" data-height="315"></div>',
-      );
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('edge cases', () => {
-    it('null content returns ""', () => {
-      expect(convertProseMirrorToMarkdown(null)).toBe('');
-    });
-
-    it('empty object returns ""', () => {
-      expect(convertProseMirrorToMarkdown({})).toBe('');
-    });
-
-    it('doc with no content returns ""', () => {
-      expect(convertProseMirrorToMarkdown({ type: 'doc' })).toBe('');
-    });
-
-    it('unknown node type falls back to children-only (no throw, text preserved)', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'totallyUnknownType', content: [text('kept')] }),
-      );
-      expect(out).toBe('kept');
-    });
-
-    it('deeply nested structure does not stack-overflow', () => {
-      // Build a deeply nested bullet list (each level holds one nested list).
-      let node: any = { type: 'listItem', content: [para(text('leaf'))] };
-      for (let i = 0; i < 200; i++) {
-        node = {
-          type: 'listItem',
-          content: [para(text('lvl')), { type: 'bulletList', content: [node] }],
-        };
-      }
-      const root = doc({ type: 'bulletList', content: [node] });
-      expect(() => convertProseMirrorToMarkdown(root)).not.toThrow();
-      const out = convertProseMirrorToMarkdown(root);
-      expect(out).toContain('leaf');
-      expect(out.startsWith('- lvl')).toBe(true);
-    });
-  });
-
-  // ===========================================================================
-  // Targeted coverage for marker-width-scaled list indent, the markdown
-  // link-title escape branch, the markdown callout fence, and the blockquote
-  // per-line prefixer over a multi-line nested-block child. Grounded against
-  // the real converter output (verified empirically) — see processListItem /
-  // indentItemChildren (src 812-843), the link mark branch (src 117-121), the
-  // callout case (src 373-376), and the blockquote prefixer (src 210-221).
-  describe('marker-width / link-title / callout / blockquote-nested', () => {
-    // Spec 1 — two-digit ordered marker scales the continuation indent to 4.
-    it('indents a nested ordered sublist under item 10 by 4 spaces (marker "10. ")', () => {
-      // Items 1..10 ("a".."j"); the 10th additionally holds a nested
-      // orderedList with one paragraph "x".
-      const items: any[] = [];
-      for (let i = 0; i < 9; i++) {
-        items.push({
-          type: 'listItem',
-          content: [para(text(String.fromCharCode(97 + i)))], // 'a'..'i'
-        });
-      }
-      items.push({
-        type: 'listItem',
-        content: [
-          para(text('j')),
-          {
-            type: 'orderedList',
-            content: [{ type: 'listItem', content: [para(text('x'))] }],
-          },
-        ],
-      });
-
-      const out = convertProseMirrorToMarkdown(
-        doc({ type: 'orderedList', content: items }),
-      );
-
-      // The 10th marker is the 4-column "10. "; the nested sublist line must be
-      // indented exactly 4 spaces (prefix.length 3 + 1), NOT 3.
-      expect(out).toContain('10. j\n    1. x');
-      // Guard against the off-by-one (3-space) regression that would re-parse
-      // the sublist as loose/sibling content on import.
-      expect(out).not.toContain('10. j\n   1. x');
-      // And the single-digit items keep the narrower 3-column marker (no body
-      // continuation here, but the marker itself must stay "1. ".."9. ").
-      expect(out.startsWith('1. a\n2. b\n')).toBe(true);
-      expect(out).toContain('\n9. i\n10. j');
-    });
-
-    // Spec 2 — markdown link-title branch escapes an embedded double quote and
-    // emits the href raw.
-    it('escapes an embedded double-quote in a markdown link title and emits href raw', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc(
-          para(
-            text('lbl', [
-              {
-                type: 'link',
-                attrs: { href: 'http://a', title: 'he said "hi"' },
-              },
-            ]),
-          ),
-        ),
-      );
-      // The title's " is backslash-escaped (.replace(/"/g,'\\"')) so it cannot
-      // terminate the (url "title") syntax early; the href is RAW (not escaped).
-      expect(out).toBe('[lbl](http://a "he said \\"hi\\"")');
-    });
-
-    // Spec 3 — markdown callout fence lowercases the type and joins multiple
-    // paragraph children.
-    it('lowercases an uppercase callout type and joins its paragraphs', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'callout',
-          attrs: { type: 'WARNING' },
-          content: [para(text('line1')), para(text('line2'))],
-        }),
-      );
-      // NOTE(review): the spec predicted ':::warning\nline1\n\nline2\n:::' (a
-      // The converter joins the callout's rendered children with a single '\n'
-      // and emits an Obsidian-native callout: a `> [!type]` opener plus one
-      // `>`-prefixed body line per content line. We pin the lowercasing
-      // (WARNING -> warning) and the multi-child join.
-      expect(out).toBe('> [!warning]\n> line1\n> line2');
-      // The type is lowercased (an uppercase `[!WARNING]` would not re-import).
-      expect(out.startsWith('> [!warning]\n')).toBe(true);
-      expect(out).not.toContain('[!WARNING]');
-      // Both paragraph children are present, each blockquote-prefixed.
-      expect(out).toContain('> line1\n> line2');
-    });
-
-    // Spec 4 — blockquote per-line prefixer over a multi-line nested callout.
-    it('prefixes every line of a nested callout child with "> "', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'blockquote',
-          content: [
-            {
-              type: 'callout',
-              attrs: { type: 'INFO' },
-              content: [para(text('a')), para(text('b'))],
-            },
-          ],
-        }),
-      );
-      // NOTE(review): the spec predicted '> :::info\n> a\n>\n> b\n> :::',
-      // assuming the nested callout body contains a blank line between 'a' and
-      // The nested callout renders as an Obsidian callout '> [!info]\n> a\n> b'
-      // (single-'\n' join, no blank line). The outer blockquote prefixer then
-      // prefixes each of those lines with '> ' again, yielding a doubly-nested
-      // blockquote — the realistic per-line-prefix loop over a multi-line child.
-      expect(out).toBe('> > [!info]\n> > a\n> > b');
-      // Every produced line carries the '> ' prefix (no line escapes to col 0).
-      for (const line of out.split('\n')) {
-        expect(line.startsWith('>')).toBe(true);
-      }
-    });
-
-    // The empty-line '>' branch from Spec 4's intent IS reachable — just not via
-    // the nested callout (whose body has no blank line). A two-paragraph
-    // blockquote DOES separate its block children with a bare '>' line, which is
-    // the branch the spec wanted to protect. Pin it directly so the
-    // (line.length ? '> ' : '>') empty-line path stays covered.
-    it('maps an internal blank line to a bare ">" (not "> ") in a multi-block quote', () => {
-      const out = convertProseMirrorToMarkdown(
-        doc({
-          type: 'blockquote',
-          content: [para(text('p1')), para(text('p2'))],
-        }),
-      );
-      expect(out).toBe('> p1\n>\n> p2');
-      // The separator line is exactly '>' with NO trailing space.
-      expect(out.split('\n')).toContain('>');
-      expect(out).not.toContain('> \n');
-    });
-  });
-});
diff --git a/packages/git-sync/test/markdown-document-envelope.test.ts b/packages/git-sync/test/markdown-document-envelope.test.ts
deleted file mode 100644
index 05698a08..00000000
--- a/packages/git-sync/test/markdown-document-envelope.test.ts
+++ /dev/null
@@ -1,218 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
-// collaboration.ts and mutates global DOM at import time).
-import {
-  serializeDocmostMarkdown,
-  parseDocmostMarkdown,
-  serializeDocmostMarkdownBody,
-  type DocmostMdMeta,
-} from '../src/lib/markdown-document.js';
-
-const meta: DocmostMdMeta = {
-  version: 1,
-  pageId: 'p1',
-  slugId: 's1',
-  title: 'Hello',
-  spaceId: 'sp1',
-  parentPageId: null,
-};
-
-describe('serializeDocmostMarkdown / parseDocmostMarkdown', () => {
-  // ---------------------------------------------------------------------------
-  describe('round-trip', () => {
-    it('round-trips meta, body, and comments', () => {
-      const body = '# Title\n\nSome **body** text.';
-      const comments = [{ id: 'c1', text: 'a note' }];
-      const full = serializeDocmostMarkdown(meta, body, comments);
-      const parsed = parseDocmostMarkdown(full);
-      expect(parsed.meta).toEqual(meta);
-      expect(parsed.body).toBe(body);
-      expect(parsed.comments).toEqual(comments);
-    });
-
-    it('emits a comments block with [] even when there are no comments', () => {
-      const full = serializeDocmostMarkdown(meta, 'body', []);
-      expect(full).toContain('<!-- docmost:comments\n[]\n-->');
-      const parsed = parseDocmostMarkdown(full);
-      expect(parsed.comments).toEqual([]);
-      expect(parsed.body).toBe('body');
-    });
-
-    it('non-array comments arg is normalized to [] in the serialized output', () => {
-      const full = serializeDocmostMarkdown(meta, 'body', null as any);
-      expect(full).toContain('<!-- docmost:comments\n[]\n-->');
-    });
-
-    it('trims surrounding whitespace from the body on serialize', () => {
-      const full = serializeDocmostMarkdown(meta, '\n\n  body  \n\n', []);
-      const parsed = parseDocmostMarkdown(full);
-      expect(parsed.body).toBe('body');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('missing blocks (tolerant parsing)', () => {
-    it('missing meta block yields meta:null', () => {
-      const input = 'Just a body.\n\n<!-- docmost:comments\n[]\n-->\n';
-      const parsed = parseDocmostMarkdown(input);
-      expect(parsed.meta).toBeNull();
-      expect(parsed.body).toBe('Just a body.');
-      expect(parsed.comments).toEqual([]);
-    });
-
-    it('missing comments block yields comments:null and treats all as body', () => {
-      const input =
-        '<!-- docmost:meta\n' + JSON.stringify(meta) + '\n-->\n\nbody only';
-      const parsed = parseDocmostMarkdown(input);
-      expect(parsed.meta).toEqual(meta);
-      expect(parsed.comments).toBeNull();
-      expect(parsed.body).toBe('body only');
-    });
-
-    it('plain markdown with neither block: meta and comments null, whole input is body', () => {
-      const input = '# Plain\n\nNo envelope here.';
-      const parsed = parseDocmostMarkdown(input);
-      expect(parsed.meta).toBeNull();
-      expect(parsed.comments).toBeNull();
-      expect(parsed.body).toBe(input);
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('CRLF normalization', () => {
-    it('parses a CRLF-encoded document the same as LF', () => {
-      const lf = serializeDocmostMarkdown(meta, 'line one\nline two', [
-        { id: 'c1' },
-      ]);
-      const crlf = lf.replace(/\n/g, '\r\n');
-      const parsed = parseDocmostMarkdown(crlf);
-      expect(parsed.meta).toEqual(meta);
-      expect(parsed.body).toBe('line one\nline two');
-      expect(parsed.comments).toEqual([{ id: 'c1' }]);
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('only the final document-ending comments block is captured', () => {
-    it('an earlier literal docmost:comments opener inside the body stays in the body', () => {
-      // The body documents the format and contains a literal opener that does
-      // NOT end the document. Only the trailing block is treated as metadata.
-      const bodyWithLiteral =
-        'Here is how the format looks:\n\n<!-- docmost:comments\n[{"fake":true}]\n-->\n\nand more prose after it.';
-      const full = serializeDocmostMarkdown(meta, bodyWithLiteral, [
-        { id: 'real' },
-      ]);
-      const parsed = parseDocmostMarkdown(full);
-      // The real (final) block parses into the comments...
-      expect(parsed.comments).toEqual([{ id: 'real' }]);
-      // ...and the earlier literal opener is preserved verbatim in the body.
-      expect(parsed.body).toContain(
-        '<!-- docmost:comments\n[{"fake":true}]\n-->',
-      );
-      expect(parsed.body).toContain('and more prose after it.');
-    });
-
-    it('a literal opener whose closer does NOT end the doc is left entirely in the body', () => {
-      // No real trailing block: the opener is not document-ending, so comments
-      // stays null and nothing is stripped.
-      const input =
-        '<!-- docmost:meta\n' +
-        JSON.stringify(meta) +
-        '\n-->\n\nbody start\n\n<!-- docmost:comments\n[]\n-->\n\ntrailing text not ending the doc';
-      const parsed = parseDocmostMarkdown(input);
-      expect(parsed.comments).toBeNull();
-      expect(parsed.body).toContain('<!-- docmost:comments');
-      expect(parsed.body).toContain('trailing text not ending the doc');
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('end-anchored comments closer tolerates CRLF + trailing whitespace', () => {
-    it('captures the final comments block when its "-->" closer has CRLF and trailing spaces', () => {
-      // The closer regex is /\r?\n-->[ \t]*\r?\n?\s*$/. Build a document whose
-      // trailing comments block uses CRLF line endings AND has trailing spaces
-      // after the "-->" closer, then assert it is still recognised as the
-      // document-ending block (and the body is not polluted by it).
-      const metaLine = JSON.stringify(meta);
-      const crlfDoc =
-        `<!-- docmost:meta\r\n${metaLine}\r\n-->\r\n\r\n` +
-        `the body line\r\n\r\n` +
-        `<!-- docmost:comments\r\n[{"id":"c-crlf"}]\r\n-->  \r\n`;
-      const parsed = parseDocmostMarkdown(crlfDoc);
-      expect(parsed.meta).toEqual(meta);
-      expect(parsed.body).toBe('the body line');
-      expect(parsed.comments).toEqual([{ id: 'c-crlf' }]);
-    });
-  });
-
-  // ---------------------------------------------------------------------------
-  describe('malformed JSON throws a clear error', () => {
-    it('throws on malformed meta JSON', () => {
-      const input = '<!-- docmost:meta\n{not valid json}\n-->\n\nbody';
-      expect(() => parseDocmostMarkdown(input)).toThrow(/docmost:meta JSON/);
-    });
-
-    it('throws on malformed comments JSON', () => {
-      const input = 'body\n\n<!-- docmost:comments\n[not, valid]\n-->\n';
-      expect(() => parseDocmostMarkdown(input)).toThrow(/docmost:comments JSON/);
-    });
-  });
-});
-
-describe('serializeDocmostMarkdownBody', () => {
-  it('emits NO comments block', () => {
-    const out = serializeDocmostMarkdownBody(meta, 'just the body');
-    expect(out).not.toContain('docmost:comments');
-    expect(out).toContain('<!-- docmost:meta');
-  });
-
-  it('serialize -> parse preserves meta and the trimmed body, comments null (SPEC §3)', () => {
-    const fullMeta: DocmostMdMeta = {
-      version: 1,
-      pageId: 'page-123',
-      slugId: 'slug-abc',
-      title: 'My Page',
-      spaceId: 'space-1',
-      parentPageId: 'parent-9',
-    };
-    const body = 'Hello\n\nWorld';
-    const out = serializeDocmostMarkdownBody(fullMeta, body);
-    const parsed = parseDocmostMarkdown(out);
-    expect(parsed.meta).toEqual(fullMeta);
-    expect(parsed.body).toBe(body);
-    expect(parsed.comments).toBeNull();
-  });
-
-  it('preserves a null parentPageId for a root page', () => {
-    const out = serializeDocmostMarkdownBody(meta, 'body text');
-    const parsed = parseDocmostMarkdown(out);
-    expect(parsed.meta).toEqual(meta);
-    expect(parsed.comments).toBeNull();
-  });
-
-  it('produces a parseable file for an empty or missing body', () => {
-    const minimal: DocmostMdMeta = { version: 1, pageId: 'p-empty' };
-
-    const emptyFile = serializeDocmostMarkdownBody(minimal, '');
-    const parsedEmpty = parseDocmostMarkdown(emptyFile);
-    expect(parsedEmpty.meta).toEqual(minimal);
-    expect(parsedEmpty.body).toBe('');
-    expect(parsedEmpty.comments).toBeNull();
-
-    // Missing body (undefined) — serializer coalesces to "".
-    const missingFile = serializeDocmostMarkdownBody(
-      minimal,
-      undefined as unknown as string,
-    );
-    const parsedMissing = parseDocmostMarkdown(missingFile);
-    expect(parsedMissing.meta).toEqual(minimal);
-    expect(parsedMissing.body).toBe('');
-    expect(parsedMissing.comments).toBeNull();
-  });
-
-  it('trims the body', () => {
-    const out = serializeDocmostMarkdownBody(meta, '\n\n  hi  \n');
-    const parsed = parseDocmostMarkdown(out);
-    expect(parsed.body).toBe('hi');
-  });
-});
diff --git a/packages/git-sync/test/markdown-document.test.ts b/packages/git-sync/test/markdown-document.test.ts
deleted file mode 100644
index c23447d9..00000000
--- a/packages/git-sync/test/markdown-document.test.ts
+++ /dev/null
@@ -1,66 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  serializeDocmostMarkdownBody,
-  parseDocmostMarkdown,
-  type DocmostMdMeta,
-} from 'docmost-client';
-
-describe('serializeDocmostMarkdownBody round-trip (SPEC §3)', () => {
-  it('serialize -> parse preserves meta and the trimmed body, with no comments block', () => {
-    const meta: DocmostMdMeta = {
-      version: 1,
-      pageId: 'page-123',
-      slugId: 'slug-abc',
-      title: 'My Page',
-      spaceId: 'space-1',
-      parentPageId: 'parent-9',
-    };
-    const body = 'Hello\n\nWorld';
-
-    const file = serializeDocmostMarkdownBody(meta, body);
-    const parsed = parseDocmostMarkdown(file);
-
-    expect(parsed.meta).toEqual(meta);
-    expect(parsed.body).toBe(body);
-    // No trailing docmost:comments block was emitted (SPEC §3).
-    expect(parsed.comments).toBeNull();
-  });
-
-  it('preserves a null parentPageId for a root page', () => {
-    const meta: DocmostMdMeta = {
-      version: 1,
-      pageId: 'root-1',
-      slugId: 'root-slug',
-      title: 'Root',
-      spaceId: 'space-1',
-      parentPageId: null,
-    };
-    const file = serializeDocmostMarkdownBody(meta, 'body text');
-    const parsed = parseDocmostMarkdown(file);
-    expect(parsed.meta).toEqual(meta);
-    expect(parsed.comments).toBeNull();
-  });
-
-  it('produces a parseable file for an empty/missing body', () => {
-    const meta: DocmostMdMeta = { version: 1, pageId: 'p-empty' };
-
-    // Empty string body.
-    const emptyFile = serializeDocmostMarkdownBody(meta, '');
-    expect(() => parseDocmostMarkdown(emptyFile)).not.toThrow();
-    const parsedEmpty = parseDocmostMarkdown(emptyFile);
-    expect(parsedEmpty.meta).toEqual(meta);
-    expect(parsedEmpty.body).toBe('');
-    expect(parsedEmpty.comments).toBeNull();
-
-    // Missing body (undefined) — serializer coalesces to "".
-    const missingFile = serializeDocmostMarkdownBody(
-      meta,
-      undefined as unknown as string,
-    );
-    expect(() => parseDocmostMarkdown(missingFile)).not.toThrow();
-    const parsedMissing = parseDocmostMarkdown(missingFile);
-    expect(parsedMissing.meta).toEqual(meta);
-    expect(parsedMissing.body).toBe('');
-    expect(parsedMissing.comments).toBeNull();
-  });
-});
diff --git a/packages/git-sync/test/markdown-roundtrip-spoiler-caption.test.ts b/packages/git-sync/test/markdown-roundtrip-spoiler-caption.test.ts
deleted file mode 100644
index ea6b4c00..00000000
--- a/packages/git-sync/test/markdown-roundtrip-spoiler-caption.test.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-} from "docmost-client";
-
-// Round-trip coverage for the two editor features git-sync's converter
-// predated and must now preserve losslessly:
-//   - the `spoiler` inline mark (issue #259), emitted as raw inline HTML
-//     `<span data-spoiler="true">…</span>` (Markdown has no native syntax);
-//   - the image `caption` attribute (issue #221), emitted as `data-caption`
-//     on the raw <img> (Markdown `![](src)` cannot carry it).
-// We exercise the real export -> import -> export cycle: a PM doc must survive
-// PM -> MD -> PM unchanged, and the raw-HTML forms in incoming Markdown must
-// parse back to the mark/attribute.
-
-const doc = (...nodes: any[]) => ({ type: "doc", content: nodes });
-const text = (t: string, marks?: any[]) =>
-  marks ? { type: "text", text: t, marks } : { type: "text", text: t };
-const para = (...inline: any[]) => ({ type: "paragraph", content: inline });
-
-// Count text nodes carrying a `spoiler` mark anywhere in a PM JSON doc.
-function countSpoilerMarks(node: any): number {
-  let count = 0;
-  const walk = (n: any) => {
-    if (!n || typeof n !== "object") return;
-    if (Array.isArray(n.marks)) {
-      for (const mark of n.marks) if (mark?.type === "spoiler") count++;
-    }
-    if (Array.isArray(n.content)) n.content.forEach(walk);
-  };
-  walk(node);
-  return count;
-}
-
-// Find the first image node anywhere in a PM JSON doc.
-function findImage(node: any): any | null {
-  if (!node || typeof node !== "object") return null;
-  if (node.type === "image") return node;
-  if (Array.isArray(node.content)) {
-    for (const child of node.content) {
-      const hit = findImage(child);
-      if (hit) return hit;
-    }
-  }
-  return null;
-}
-
-describe("spoiler mark round-trip (#259)", () => {
-  it("survives export -> import -> export unchanged", async () => {
-    const source = doc(
-      para(
-        text("before "),
-        text("hidden", [{ type: "spoiler" }]),
-        text(" after"),
-      ),
-    );
-
-    const md1 = convertProseMirrorToMarkdown(source);
-    // Lossless raw inline HTML form.
-    expect(md1).toContain('<span data-spoiler="true">hidden</span>');
-
-    const doc2 = await markdownToProseMirror(md1);
-    // The spoiler mark was recovered on import.
-    expect(countSpoilerMarks(doc2)).toBe(1);
-    expect(JSON.stringify(doc2)).toContain("hidden");
-
-    // Byte-stable: a second export reproduces the first exactly.
-    const md2 = convertProseMirrorToMarkdown(doc2);
-    expect(md2).toBe(md1);
-  });
-
-  it("keeps the spoiler intact when it intersects a bold mark", async () => {
-    const source = doc(
-      para(text("secret", [{ type: "bold" }, { type: "spoiler" }])),
-    );
-
-    const md1 = convertProseMirrorToMarkdown(source);
-    expect(md1).toContain('data-spoiler="true"');
-
-    const doc2 = await markdownToProseMirror(md1);
-    expect(countSpoilerMarks(doc2)).toBe(1);
-    // Bold survives alongside the spoiler.
-    expect(JSON.stringify(doc2)).toContain('"bold"');
-  });
-
-  it("parses a raw <span data-spoiler> in incoming Markdown back to the mark", async () => {
-    const incoming = 'before <span data-spoiler="true">hidden</span> after';
-    const parsed = await markdownToProseMirror(incoming);
-    expect(countSpoilerMarks(parsed)).toBe(1);
-  });
-});
-
-describe("image caption round-trip (#221)", () => {
-  it("survives export -> import -> export with the caption preserved", async () => {
-    const source = doc({
-      type: "image",
-      attrs: { src: "/files/a.png", alt: "cat", caption: "A grey cat" },
-    });
-
-    const md1 = convertProseMirrorToMarkdown(source);
-    // A captioned image takes the raw <img> form so data-caption can ride along.
-    expect(md1).toContain('data-caption="A grey cat"');
-
-    const doc2 = await markdownToProseMirror(md1);
-    const img = findImage(doc2);
-    expect(img).toBeTruthy();
-    expect(img.attrs?.caption).toBe("A grey cat");
-
-    // Byte-stable: a second export reproduces the first exactly.
-    const md2 = convertProseMirrorToMarkdown(doc2);
-    expect(md2).toBe(md1);
-  });
-
-  it("parses a raw <img data-caption> in incoming Markdown back to the caption", async () => {
-    const incoming = '<img src="/files/a.png" alt="cat" data-caption="A grey cat">';
-    const parsed = await markdownToProseMirror(incoming);
-    const img = findImage(parsed);
-    expect(img).toBeTruthy();
-    expect(img.attrs?.caption).toBe("A grey cat");
-  });
-
-  it("leaves a caption-less image on the lighter markdown form", () => {
-    const md = convertProseMirrorToMarkdown(
-      doc({ type: "image", attrs: { src: "/files/a.png", alt: "cat" } }),
-    );
-    expect(md).toBe("![cat](/files/a.png)");
-  });
-});
diff --git a/packages/git-sync/test/markdown-roundtrip.property.test.ts b/packages/git-sync/test/markdown-roundtrip.property.test.ts
deleted file mode 100644
index 50f83d73..00000000
--- a/packages/git-sync/test/markdown-roundtrip.property.test.ts
+++ /dev/null
@@ -1,698 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import fc from 'fast-check';
-
-// These property tests run real ProseMirror<->Markdown conversion × NUM_RUNS, so
-// each takes ~4–5s. Inputs are DETERMINISTIC (fixed SEED below) — the only source
-// of flakiness is wall-clock: under the full suite's parallel worker load they can
-// exceed vitest's default 5000ms per-test timeout. Give them ample headroom so CI
-// (which gates the docker build, AGENTS.md) is deterministic regardless of load.
-vi.setConfig({ testTimeout: 30000 });
-// Import the converter DIRECTLY from src (NOT the docmost-client barrel) so we
-// match the path used by the other converter unit tests.
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-// markdownToProseMirror lives in collaboration.ts; importing it mutates the
-// global DOM via jsdom at module load time — this is expected and required for
-// @tiptap/html's generateJSON to run under Node.
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-import { stripBlockIds } from './roundtrip-helpers.js';
-
-// ---------------------------------------------------------------------------
-// WHY THIS TEST EXISTS (SPEC §11 / "Задача №0")
-//
-// git is the state store, and git diffs byte-for-byte. The sync daemon does
-// `export(markdown) -> import(ProseMirror) -> export(markdown)` on every pull,
-// so if the *second* export differs from the first by even one byte, every
-// pull produces a phantom diff -> endless commits/conflicts. The single
-// property git actually needs is therefore MARKDOWN BYTE-STABILITY:
-//
-//     md2 := export(import(export(doc)))   MUST equal   md1 := export(doc)
-//
-// This file fuzzes that invariant with fast-check over randomly generated,
-// representative Docmost ProseMirror documents.
-//
-// ---------------------------------------------------------------------------
-// THE "SUPPORTED SPACE" PROBLEM
-//
-// A NAIVE generator surfaces two different kinds of `md2 !== md1`:
-//
-//   (a) GENUINE converter limitations — documented below as `it.fails` repros.
-//   (b) Inputs the converter LEGITIMATELY normalizes, i.e. markdown that is
-//       ambiguous or that the schema rewrites to a canonical form. These are
-//       NOT byte-stable by construction and are NOT bugs; the fix is to keep
-//       the generator inside the byte-stable / supported space.
-//
-// The following were all empirically confirmed (by probing the live converter)
-// and are EXCLUDED from / canonicalized by the byte-stable arbitrary. Each is a
-// markdown ambiguity or a schema/ProseMirror normalization, NOT a converter bug.
-//
-//   * Text that re-triggers block/inline markdown syntax on re-parse:
-//       - a leading `>`/`*`/`-`/`#`/`1.` turns a paragraph into a blockquote/
-//         list/heading;
-//       - `a  b` (2+ spaces) collapses to `a b`;
-//       - `<b>` / `</div>` parse as real HTML tags (and run-concatenation can
-//         form `<word>` across a run boundary);
-//       - `&amp;` / `&lt;` decode back to `&` / `<`;
-//       - a lone backtick is a code-span delimiter and re-pairs globally.
-//     -> The text arbitrary emits space-joined tokens that BEGIN and END with an
-//        alphanumeric word, with any single special char confined to the middle
-//        (space-flanked). Every char the task requires (* _ [ ] ( ) | < > &, and
-//        more) is covered this way; the backtick is exercised via code spans.
-//   * A purely numeric image `alt` ("0") or link `title` ("0") is parsed back as
-//     a NUMBER and dropped by the converter's `value || ""` -> alt/title always
-//     carry at least one letter.
-//   * Callout types other than info/success/warning/danger normalize to `info`
-//     (schema only knows those four) -> generator restricts to those four.
-//   * A list item / callout / blockquote with MULTIPLE block children: the
-//     converter joins them with a single "\n", which marked re-parses as ONE
-//     merged paragraph ("- p1\n  p2" -> "- p1 p2"). -> container bodies hold a
-//     SINGLE paragraph, optionally plus ONE nested list for lists.
-//   * `orderedList.start` / `1)` markers normalize to `1.` -> not emitted.
-//   * Two sibling lists sharing a marker family (bullet/task use "-", ordered
-//     uses "1.") MERGE into one list -> no two list blocks are adjacent.
-//   * TWO consecutive hard breaks render a blank line that marked eats as a
-//     paragraph break, and a trailing hard break is trimmed -> consecutive/
-//     trailing hard breaks are collapsed/removed.
-//   * Adjacent text runs with IDENTICAL marks ("**a****b****c**" -> "**abc**").
-//     A real ProseMirror doc never stores split same-mark runs (the editor
-//     coalesces them) -> the generator merges them too (normalizeInline).
-//
-// The GENUINE, real-but-intentional non-roundtrip limitations are kept HONEST as
-// `it.fails` blocks below (so the suite stays green only because they are marked
-// expected-to-fail, never by hiding them):
-//
-//   1. The `code` mark COMBINED with any other mark. The converter emits nested
-//      HTML (`<strong><code>x</code></strong>`), but the schema's `code` mark
-//      declares `excludes: "_"`, so on import every co-occurring mark is dropped
-//      and the run comes back as `code` only -> md2 == "`x`". Acknowledged in
-//      markdown-converter.ts (the long comment above the marks switch);
-//      impossible to round-trip both while `code` excludes them.
-//   2. A BLOCK-level `image` placed BETWEEN other blocks. The Docmost image node
-//      is block-level but `![](url)` is inline; marked wraps it in a <p>, the
-//      schema hoists the <img> out and leaves an empty paragraph sibling, which
-//      injects an extra blank gap on the second export. An image IS byte-stable
-//      as the sole block (edge artifacts get trimmed) — covered by a green test.
-// ---------------------------------------------------------------------------
-
-// Run a full export -> import -> export cycle and return both markdown strings.
-async function roundTrip(doc: unknown): Promise<{ md1: string; md2: string; doc2: any }> {
-  const md1 = convertProseMirrorToMarkdown(doc);
-  const doc2 = await markdownToProseMirror(md1);
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  return { md1, md2, doc2 };
-}
-
-const SEED = 42;
-const NUM_RUNS = 100;
-
-// ---------------------------------------------------------------------------
-// Inline text arbitraries
-// ---------------------------------------------------------------------------
-
-// Alphanumeric "word" (no markdown-significant characters). Length 1..6.
-const wordArb = fc
-  .stringMatching(/^[A-Za-z0-9]{1,6}$/)
-  .filter((w) => w.length > 0);
-
-// A SINGLE markdown-significant character, emitted only as an isolated,
-// space-flanked token. Every char the task calls out plus a few more; each was
-// verified byte-stable in this position.
-//
-// NOTE: the backtick (`) is DELIBERATELY excluded from free-floating plain
-// text. A lone backtick is a markdown code-span DELIMITER, so its round-trip
-// depends on GLOBAL backtick pairing: a stray backtick in running text adjacent
-// to a real code span ("A ` " + `code`) re-pairs into a different code span and
-// loses a space — genuinely outside the byte-stable space. The backtick is
-// still fully exercised as the `code`-mark delimiter and inside code blocks.
-const specialCharArb = fc.constantFrom(
-  '*', '_', '[', ']', '(', ')', '{', '}', '|', '<', '>', '&', '#', '!', '~', '=', '+', '-',
-);
-
-// Build a "safe special" text string: a space-joined sequence of tokens that
-// always BEGINS and ENDS with an alphanumeric word, with any isolated special
-// chars confined to the MIDDLE (each space-flanked by words).
-//
-// Both boundary guarantees matter:
-//   * Leading word: the line never opens with a block/inline trigger
-//     (">", "*", "-", "#", "1." ...).
-//   * Trailing word: adjacent text runs CONCATENATE with no separator, so a run
-//     ending in a bare "<" beside a run starting with a letter would form a fake
-//     HTML tag ("...0 <" + "A >" -> "0 <A >"), which marked/jsdom strips. Ending
-//     every run with an alphanumeric word keeps every special internal and
-//     space-flanked even after concatenation.
-const safeTextArb: fc.Arbitrary<string> = fc
-  .tuple(
-    wordArb,
-    fc.array(fc.oneof(wordArb, specialCharArb), { minLength: 0, maxLength: 3 }),
-    wordArb,
-  )
-  .map(([first, middle, last]) => [first, ...middle, last].join(' '));
-
-// A plain alphanumeric phrase (1..3 words) for places where even isolated
-// specials are not wanted (e.g. code-block language, mention labels).
-const phraseArb: fc.Arbitrary<string> = fc
-  .array(wordArb, { minLength: 1, maxLength: 3 })
-  .map((ws) => ws.join(' '));
-
-// A phrase guaranteed to contain at least one letter. Used for image alt text:
-// a PURELY numeric alt (e.g. "0", "00") is parsed back by the schema as a
-// NUMBER, and the converter's `alt || ""` then treats the number 0 as falsy and
-// DROPS the alt ("![0](u)" -> "![](u)") — not byte-stable. A letter anywhere in
-// the alt keeps it a string and avoids the coercion.
-const letterPhraseArb: fc.Arbitrary<string> = fc
-  .tuple(
-    fc.stringMatching(/^[A-Za-z]{1,4}$/),
-    fc.array(wordArb, { minLength: 0, maxLength: 2 }),
-  )
-  .map(([head, rest]) => [head, ...rest].join(' '));
-
-
-// A text run with an OPTIONAL single non-code mark (bold/italic/strike), or a
-// SOLE `code` mark, or a link. `code` is never combined with another mark in
-// the byte-stable arbitrary (that combination is the known bug, exercised
-// separately in the it.fails block). Marks wrap safe text, which stays stable
-// even when it contains isolated specials.
-const markedTextRunArb: fc.Arbitrary<any> = fc.oneof(
-  // Plain text.
-  safeTextArb.map((t) => ({ type: 'text', text: t })),
-  // Single formatting mark.
-  fc
-    .tuple(safeTextArb, fc.constantFrom('bold', 'italic', 'strike'))
-    .map(([t, m]) => ({ type: 'text', text: t, marks: [{ type: m }] })),
-  // Sole code mark (backtick span). safeTextArb is already backtick-free, so the
-  // code span content cannot contain an inner backtick (which would be
-  // ambiguous to re-parse).
-  safeTextArb.map((t) => ({ type: 'text', text: t, marks: [{ type: 'code' }] })),
-  // Link with safe text and a paren/space-free href, optionally with a title.
-  // The title rides in a markdown link-title attribute; a purely numeric title
-  // is coerced to a number and dropped on re-import (same class of quirk as the
-  // image alt), so the title always carries at least one letter.
-  fc
-    .tuple(
-      phraseArb,
-      fc.webUrl().filter((u) => !/[()\s]/.test(u)),
-      fc.option(letterPhraseArb, { nil: undefined }),
-    )
-    .map(([t, href, title]) => ({
-      type: 'text',
-      text: t,
-      marks: [{ type: 'link', attrs: title ? { href, title } : { href } }],
-    })),
-  // Inline COMMENT anchor (SPEC §3): a span[data-comment-id] that must survive
-  // the round-trip byte-for-byte. The commentId is an alphanumeric token (no
-  // attribute-breaking chars), and `resolved` rides as data-resolved="true"
-  // only when true — both forms were verified byte-stable.
-  fc
-    .tuple(safeTextArb, fc.stringMatching(/^[A-Za-z0-9]{4,10}$/), fc.boolean())
-    .map(([t, commentId, resolved]) => ({
-      type: 'text',
-      text: t,
-      marks: [
-        {
-          type: 'comment',
-          attrs: resolved ? { commentId, resolved: true } : { commentId },
-        },
-      ],
-    })),
-);
-
-// Inline math node carrying LaTeX that includes the `a < b` the task asks for.
-const mathInlineArb: fc.Arbitrary<any> = fc
-  .constantFrom('a < b', 'x^2 + y^2', 'a < b < c', '\\frac{1}{2}', 'E = mc^2')
-  .map((text) => ({ type: 'mathInline', attrs: { text } }));
-
-// Mention node (schema attrs); label/id are plain phrases.
-const mentionArb: fc.Arbitrary<any> = fc
-  .tuple(phraseArb, fc.uuid(), fc.uuid())
-  .map(([label, id, entityId]) => ({
-    type: 'mention',
-    attrs: { id, label, entityType: 'user', entityId },
-  }));
-
-const hardBreakArb: fc.Arbitrary<any> = fc.constant({ type: 'hardBreak' });
-
-// Canonicalize a generated inline-content array the way ProseMirror itself
-// stores inline content, then trim the markdown-fragile edges. Applied to both
-// paragraph and heading inline content.
-//
-//   1) MERGE adjacent `text` runs that carry IDENTICAL marks. A real
-//      ProseMirror document never stores two neighbouring runs with the same
-//      mark set — the editor coalesces them into one. A naive generator that
-//      leaves them split produces UNREALISTIC docs AND breaks byte-stability:
-//      three adjacent bold runs export as "**a****b****c**", whose inner
-//      "****" boundaries are ambiguous and re-parse as a single "**abc**".
-//      Merging makes the generated doc canonical and the markdown stable.
-//   2) Collapse CONSECUTIVE hard breaks. Two in a row render as "  \n  \n",
-//      whose middle whitespace-only line marked treats as a paragraph break, so
-//      "a  \n  \nb" re-parses to "a\n\nb". A SINGLE hard break round-trips.
-//   3) Drop a TRAILING hard break: "...  \n" sits at the paragraph edge and is
-//      removed by the converter's .trim().
-const sameMarks = (a: any[] | undefined, b: any[] | undefined): boolean =>
-  JSON.stringify(a ?? []) === JSON.stringify(b ?? []);
-
-function normalizeInline(nodes: any[]): any[] {
-  const out: any[] = [];
-  for (const node of nodes) {
-    const prev = out[out.length - 1];
-    // Collapse a second consecutive hard break.
-    if (node.type === 'hardBreak' && prev && prev.type === 'hardBreak') {
-      continue;
-    }
-    // Merge an adjacent text run with the same marks.
-    if (
-      node.type === 'text' &&
-      prev &&
-      prev.type === 'text' &&
-      sameMarks(prev.marks, node.marks)
-    ) {
-      prev.text += node.text;
-      continue;
-    }
-    // Clone text nodes so the in-place merge above never mutates a shared value.
-    out.push(node.type === 'text' ? { ...node } : node);
-  }
-  while (out.length > 1 && out[out.length - 1].type === 'hardBreak') {
-    out.pop();
-  }
-  return out;
-}
-
-// Inline content for a paragraph: at least one marked text run, optionally with
-// inline atoms (math/mention) and hard breaks interspersed. Always starts with a
-// text run so the paragraph never opens with a block trigger.
-const inlineContentArb: fc.Arbitrary<any[]> = fc
-  .tuple(
-    markedTextRunArb,
-    fc.array(
-      fc.oneof(
-        { weight: 5, arbitrary: markedTextRunArb },
-        { weight: 1, arbitrary: mathInlineArb },
-        { weight: 1, arbitrary: mentionArb },
-        { weight: 1, arbitrary: hardBreakArb },
-      ),
-      { minLength: 0, maxLength: 4 },
-    ),
-  )
-  .map(([first, rest]) => normalizeInline([first, ...rest]));
-
-// Inline content for a HEADING — identical to a paragraph's, but WITHOUT hard
-// breaks. A hard break inside an ATX heading ("# a  \nb") is NOT byte-stable:
-// marked does not honour a hard break inside a heading, so it re-parses as the
-// heading "# a" plus a separate paragraph "b" (md2 = "# a\n\nb"). math/mention/
-// link inside a heading are fine (verified) and stay in the menu.
-const headingInlineContentArb: fc.Arbitrary<any[]> = fc
-  .tuple(
-    markedTextRunArb,
-    fc.array(
-      fc.oneof(
-        { weight: 5, arbitrary: markedTextRunArb },
-        { weight: 1, arbitrary: mathInlineArb },
-        { weight: 1, arbitrary: mentionArb },
-      ),
-      { minLength: 0, maxLength: 4 },
-    ),
-  )
-  .map(([first, rest]) => normalizeInline([first, ...rest]));
-
-// ---------------------------------------------------------------------------
-// Block arbitraries
-// ---------------------------------------------------------------------------
-
-const paragraphArb: fc.Arbitrary<any> = inlineContentArb.map((content) => ({
-  type: 'paragraph',
-  content,
-}));
-
-const headingArb: fc.Arbitrary<any> = fc
-  .tuple(fc.integer({ min: 1, max: 6 }), headingInlineContentArb)
-  .map(([level, content]) => ({ type: 'heading', attrs: { level }, content }));
-
-// Code block content: 1..4 lines of plain phrases (may contain specials inline,
-// which are inert inside a fenced block). Language is optional and is a single
-// lowercase token.
-const codeBlockArb: fc.Arbitrary<any> = fc
-  .tuple(
-    fc.option(fc.constantFrom('js', 'ts', 'python', 'go', 'rust', 'bash'), {
-      nil: '',
-    }),
-    fc
-      .array(safeTextArb, { minLength: 1, maxLength: 4 })
-      .map((lines) => lines.join('\n')),
-  )
-  .map(([language, code]) => ({
-    type: 'codeBlock',
-    attrs: { language },
-    content: [{ type: 'text', text: code }],
-  }));
-
-const blockquoteArb: fc.Arbitrary<any> = paragraphArb.map((p) => ({
-  type: 'blockquote',
-  content: [p],
-}));
-
-const horizontalRuleArb: fc.Arbitrary<any> = fc.constant({
-  type: 'horizontalRule',
-});
-
-// Callout: ONE paragraph child; type restricted to the four the schema knows.
-const calloutArb: fc.Arbitrary<any> = fc
-  .tuple(
-    fc.constantFrom('info', 'success', 'warning', 'danger'),
-    paragraphArb,
-  )
-  .map(([type, p]) => ({ type: 'callout', attrs: { type }, content: [p] }));
-
-const mathBlockArb: fc.Arbitrary<any> = fc
-  .constantFrom('a < b', 'a < b < c', '\\sum_{i=0}^{n} i', 'x = \\frac{-b}{2a}', '')
-  .map((text) => ({ type: 'mathBlock', attrs: { text } }));
-
-const imageArb: fc.Arbitrary<any> = fc
-  .tuple(
-    fc.webUrl(),
-    // alt is a letter-bearing phrase OR empty. Brackets/parens leak into the
-    // markdown image syntax (not byte-stable) so they are excluded, and a purely
-    // numeric alt is coerced to a number and dropped (see letterPhraseArb), so
-    // alt always carries at least one letter when non-empty.
-    fc.option(letterPhraseArb, { nil: '' }),
-  )
-  .map(([src, alt]) => ({ type: 'image', attrs: { src, alt } }));
-
-// A simple list item: ONE paragraph, optionally followed by ONE nested bullet
-// list (single level of nesting). depth controls whether nesting is allowed.
-function listItemArb(allowNest: boolean): fc.Arbitrary<any> {
-  if (!allowNest) {
-    return paragraphArb.map((p) => ({ type: 'listItem', content: [p] }));
-  }
-  return fc
-    .tuple(
-      paragraphArb,
-      fc.option(
-        fc.array(
-          paragraphArb.map((p) => ({ type: 'listItem', content: [p] })),
-          { minLength: 1, maxLength: 3 },
-        ),
-        { nil: undefined },
-      ),
-    )
-    .map(([p, nested]) => ({
-      type: 'listItem',
-      content: nested
-        ? [p, { type: 'bulletList', content: nested }]
-        : [p],
-    }));
-}
-
-const bulletListArb: fc.Arbitrary<any> = fc
-  .array(listItemArb(true), { minLength: 1, maxLength: 4 })
-  .map((items) => ({ type: 'bulletList', content: items }));
-
-const orderedListArb: fc.Arbitrary<any> = fc
-  .array(listItemArb(true), { minLength: 1, maxLength: 4 })
-  .map((items) => ({ type: 'orderedList', content: items }));
-
-// Task item: ONE paragraph, optional ONE nested bullet list.
-const taskItemArb: fc.Arbitrary<any> = fc
-  .tuple(
-    fc.boolean(),
-    paragraphArb,
-    fc.option(
-      fc.array(listItemArb(false), { minLength: 1, maxLength: 2 }),
-      { nil: undefined },
-    ),
-  )
-  .map(([checked, p, nested]) => ({
-    type: 'taskItem',
-    attrs: { checked },
-    content: nested ? [p, { type: 'bulletList', content: nested }] : [p],
-  }));
-
-const taskListArb: fc.Arbitrary<any> = fc
-  .array(taskItemArb, { minLength: 1, maxLength: 4 })
-  .map((items) => ({ type: 'taskList', content: items }));
-
-// GFM table: a header row + 1..3 body rows, with a fixed column count (1..3) and
-// per-column alignment. Cells hold a single short paragraph of safe text.
-const tableArb: fc.Arbitrary<any> = fc
-  .integer({ min: 1, max: 3 })
-  .chain((cols) => {
-    const cellArb = (header: boolean, align?: string) =>
-      phraseArb.map((t) => ({
-        type: header ? 'tableHeader' : 'tableCell',
-        attrs: align ? { align } : {},
-        content: [{ type: 'paragraph', content: [{ type: 'text', text: t }] }],
-      }));
-    const alignsArb = fc.array(
-      fc.constantFrom(undefined, 'left', 'center', 'right'),
-      { minLength: cols, maxLength: cols },
-    );
-    return fc
-      .tuple(
-        alignsArb,
-        fc.array(
-          fc.constant(null), // body-row placeholders; cells filled below
-          { minLength: 1, maxLength: 3 },
-        ),
-      )
-      .chain(([aligns, bodyRows]) => {
-        const headerRow = fc
-          .tuple(...aligns.map((a) => cellArb(true, a)))
-          .map((cells) => ({ type: 'tableRow', content: cells }));
-        const bodyRowArbs = bodyRows.map(() =>
-          fc
-            .tuple(...aligns.map(() => cellArb(false)))
-            .map((cells) => ({ type: 'tableRow', content: cells })),
-        );
-        return fc
-          .tuple(headerRow, fc.tuple(...bodyRowArbs))
-          .map(([h, body]) => ({ type: 'table', content: [h, ...body] }));
-      });
-  });
-
-// ---------------------------------------------------------------------------
-// Top-level document arbitrary
-// ---------------------------------------------------------------------------
-
-// The full menu of block nodes that are byte-stable when SEQUENCED with other
-// blocks. NOTE: `image` is deliberately NOT in this menu — see the dedicated
-// image tests below. The Docmost `image` node is BLOCK-level, but its markdown
-// form `![](url)` is INLINE; marked wraps it in a <p>, the schema then hoists
-// the block <img> out and leaves an EMPTY paragraph beside it, so on the second
-// export the stray empty paragraph injects extra blank lines between siblings
-// ("p\n\n![](u)\n\nq" -> "p\n\n\n\n![](u)\n\nq"). An image is only byte-stable
-// when it is the SOLE block (the edge artifacts get .trim()'d away). It is
-// therefore covered by its own targeted tests, not mixed into multi-block docs.
-const blockArb: fc.Arbitrary<any> = fc.oneof(
-  { weight: 6, arbitrary: paragraphArb },
-  { weight: 3, arbitrary: headingArb },
-  { weight: 2, arbitrary: codeBlockArb },
-  { weight: 2, arbitrary: bulletListArb },
-  { weight: 2, arbitrary: orderedListArb },
-  { weight: 2, arbitrary: taskListArb },
-  { weight: 2, arbitrary: blockquoteArb },
-  { weight: 2, arbitrary: tableArb },
-  { weight: 2, arbitrary: calloutArb },
-  { weight: 1, arbitrary: horizontalRuleArb },
-  { weight: 1, arbitrary: mathBlockArb },
-);
-
-const LIST_TYPES = new Set(['bulletList', 'orderedList', 'taskList']);
-
-// A bounded document: 1..8 block nodes. Kept small so each run is cheap (each
-// run does a real marked + jsdom parse) and shrinking stays fast.
-//
-// Post-process: never let two LIST blocks sit directly adjacent. Two sibling
-// lists that share a marker family — bullet/task both use "-", ordered uses
-// "1." — are MERGED by markdown into a single list when only a blank line
-// separates them ("- a\n\n- b" -> one list -> "- a\n- b"), which is not
-// byte-stable. (A non-list block between two lists separates them fine, as does
-// a different marker family, but dropping every back-to-back list is the clean,
-// always-correct rule.) We drop a list block whenever the previously kept block
-// is also a list.
-const docArb: fc.Arbitrary<any> = fc
-  .array(blockArb, { minLength: 1, maxLength: 8 })
-  .map((content) => {
-    const out: any[] = [];
-    for (const block of content) {
-      const prev = out[out.length - 1];
-      if (
-        prev &&
-        LIST_TYPES.has(prev.type) &&
-        LIST_TYPES.has(block.type)
-      ) {
-        continue; // skip a list that would sit right after another list
-      }
-      out.push(block);
-    }
-    // Guarantee a non-empty document even if filtering removed everything but a
-    // single dropped block (cannot happen here since the first block is always
-    // kept, but keep the invariant explicit).
-    return { type: 'doc', content: out.length ? out : content.slice(0, 1) };
-  });
-
-// ---------------------------------------------------------------------------
-// The properties
-// ---------------------------------------------------------------------------
-
-describe('markdown <-> ProseMirror round-trip (property-based)', () => {
-  it('the generator covers every targeted node type at least once', () => {
-    // A sanity check that the arbitrary actually exercises the intended node
-    // variety within NUM_RUNS — not a correctness property, just coverage.
-    const seen = new Set<string>();
-    const collect = (node: any) => {
-      if (!node || typeof node !== 'object') return;
-      if (node.type) seen.add(node.type);
-      for (const m of node.marks ?? []) seen.add(`mark:${m.type}`);
-      for (const c of node.content ?? []) collect(c);
-    };
-    fc.assert(
-      fc.property(docArb, (doc) => {
-        collect(doc);
-        return true;
-      }),
-      { numRuns: NUM_RUNS, seed: SEED },
-    );
-    // Core block types and marks we expect to appear.
-    for (const t of [
-      'paragraph',
-      'heading',
-      'codeBlock',
-      'bulletList',
-      'orderedList',
-      'taskList',
-      'blockquote',
-      'table',
-      'callout',
-      'horizontalRule',
-      'mathBlock',
-      // 'image' is covered by its own dedicated tests, not docArb.
-      'mention',
-      'mathInline',
-      'hardBreak',
-      'mark:bold',
-      'mark:italic',
-      'mark:strike',
-      'mark:code',
-      'mark:link',
-      'mark:comment',
-    ]) {
-      expect(seen, `expected the generator to produce ${t}`).toContain(t);
-    }
-  });
-
-  it('markdown is byte-stable across export -> import -> export', async () => {
-    // The property git needs: a second export reproduces the first byte-for-byte.
-    await fc.assert(
-      fc.asyncProperty(docArb, async (doc) => {
-        const { md1, md2 } = await roundTrip(doc);
-        expect(md2).toBe(md1);
-      }),
-      { numRuns: NUM_RUNS, seed: SEED },
-    );
-  });
-
-  it('the document is semantically stable on a second cycle (ids stripped)', async () => {
-    // Optional, stronger-feeling property. We do NOT compare doc vs doc2: the
-    // converter reconstructs schema default attrs on the FIRST import (a known
-    // SPEC §11 divergence). But once the markdown is byte-stable, importing the
-    // SAME markdown twice must yield structurally identical docs (modulo the
-    // regenerated block ids). So we compare doc2 (import of md1) with doc3
-    // (import of md2 == md1) after stripping ids.
-    await fc.assert(
-      fc.asyncProperty(docArb, async (doc) => {
-        const md1 = convertProseMirrorToMarkdown(doc);
-        const doc2 = await markdownToProseMirror(md1);
-        const md2 = convertProseMirrorToMarkdown(doc2);
-        // Guard: this property only makes sense when md is byte-stable.
-        expect(md2).toBe(md1);
-        const doc3 = await markdownToProseMirror(md2);
-        expect(stripBlockIds(doc3)).toEqual(stripBlockIds(doc2));
-      }),
-      { numRuns: NUM_RUNS, seed: SEED },
-    );
-  });
-
-  it('a SOLE image block is byte-stable', async () => {
-    // An image is byte-stable when it is the only block in the document: the
-    // stray empty paragraph the schema leaves beside the hoisted block <img>
-    // sits at a document edge and is removed by the converter's final .trim().
-    await fc.assert(
-      fc.asyncProperty(imageArb, async (image) => {
-        const doc = { type: 'doc', content: [image] };
-        const { md1, md2 } = await roundTrip(doc);
-        expect(md2).toBe(md1);
-      }),
-      { numRuns: NUM_RUNS, seed: SEED },
-    );
-  });
-
-  // -------------------------------------------------------------------------
-  // KNOWN, DOCUMENTED non-roundtrip bug #2 (kept honest as it.fails).
-  //
-  // BUG: a block-level `image` placed BETWEEN other blocks is not byte-stable.
-  // The Docmost image node is BLOCK-level but its markdown form `![](url)` is
-  // INLINE. marked wraps the inline image in a <p>; the schema then hoists the
-  // block <img> out of that <p>, leaving an EMPTY paragraph as a sibling. On the
-  // second export that empty paragraph renders as "" and the "\n\n" doc join
-  // injects an extra blank gap:
-  //   "p\n\n![x](u)\n\nq"  ->  "p\n\n\n\n![x](u)\n\nq"   (=> md2 !== md1).
-  // Minimal repro doc:
-  //   { type:'doc', content:[
-  //       { type:'paragraph', content:[{type:'text',text:'p'}] },
-  //       { type:'image', attrs:{ src:'http://a.aa', alt:'x' } },
-  //       { type:'paragraph', content:[{type:'text',text:'q'}] } ] }
-  // Not "fixed" — the source must not change; documented and exercised here.
-  // -------------------------------------------------------------------------
-  it('a block image between other blocks is byte-stable', async () => {
-    const doc = {
-      type: 'doc',
-      content: [
-        { type: 'paragraph', content: [{ type: 'text', text: 'p' }] },
-        { type: 'image', attrs: { src: 'http://a.aa', alt: 'x' } },
-        { type: 'paragraph', content: [{ type: 'text', text: 'q' }] },
-      ],
-    };
-    const { md1, md2 } = await roundTrip(doc);
-    expect(md2).toBe(md1);
-  });
-
-  // -------------------------------------------------------------------------
-  // KNOWN, DOCUMENTED non-roundtrip bug #1 (kept honest as it.fails).
-  //
-  // BUG: the `code` mark combined with ANY other mark does NOT round-trip.
-  // The converter emits nested HTML so the output is well-formed, e.g.
-  //   marks [code, bold]  ->  md1 = "<strong><code>x</code></strong>"
-  // but the schema's `code` mark declares `excludes: "_"`, so on import the
-  // co-occurring mark is dropped and the run comes back as code-only:
-  //   md2 = "`x`"   (=> md2 !== md1).
-  // Minimal repro doc:
-  //   { type:'doc', content:[ { type:'paragraph', content:[
-  //       { type:'text', text:'x', marks:[{type:'code'},{type:'bold'}] } ] } ] }
-  // This is acknowledged in markdown-converter.ts (the long comment above the
-  // marks switch): preserving both marks is impossible while `code` excludes
-  // them. Documented here, not "fixed", because the source must not change.
-  // -------------------------------------------------------------------------
-  it(
-    'code mark combined with another mark is byte-stable',
-    async () => {
-      const codeComboArb = fc
-        .tuple(safeTextArb, fc.constantFrom('bold', 'italic', 'strike'))
-        .map(([t, other]) => ({
-          type: 'doc',
-          content: [
-            {
-              type: 'paragraph',
-              content: [
-                { type: 'text', text: t, marks: [{ type: 'code' }, { type: other }] },
-              ],
-            },
-          ],
-        }));
-      await fc.assert(
-        fc.asyncProperty(codeComboArb, async (doc) => {
-          const { md1, md2 } = await roundTrip(doc);
-          expect(md2).toBe(md1);
-        }),
-        { numRuns: 20, seed: SEED },
-      );
-    },
-  );
-});
diff --git a/packages/git-sync/test/markdown-to-prosemirror-gaps.test.ts b/packages/git-sync/test/markdown-to-prosemirror-gaps.test.ts
deleted file mode 100644
index 7fdf29e9..00000000
--- a/packages/git-sync/test/markdown-to-prosemirror-gaps.test.ts
+++ /dev/null
@@ -1,535 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// markdownToProseMirror lives next to the markdown->HTML preprocessors
-// (preprocessCallouts, bridgeTaskLists). Those helpers are NOT exported, so we
-// exercise them through the public entry point, which runs the full
-// markdown -> preprocessCallouts -> marked -> bridgeTaskLists -> generateJSON
-// pipeline. Importing this module mutates the global DOM via jsdom (required for
-// @tiptap/html under Node) — expected, same as the property test.
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-// The export side (ProseMirror -> markdown) is pulled in for the round-trip
-// specs below (underline/sub/sup marks, heading levels, link title). Imported
-// directly from src/lib (not the barrel) like the other converter unit tests.
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-
-// Find every node of a given type anywhere in a ProseMirror doc tree.
-const findAll = (node: any, type: string, acc: any[] = []): any[] => {
-  if (node && node.type === type) acc.push(node);
-  for (const child of node?.content || []) findAll(child, type, acc);
-  return acc;
-};
-// Concatenate all text within a subtree (order-preserving).
-const allText = (node: any): string => {
-  if (node?.type === 'text') return node.text || '';
-  return (node?.content || []).map(allText).join('');
-};
-
-// ---------------------------------------------------------------------------
-// Obsidian-native callouts: the export emits `> [!type]` (a blockquote callout,
-// which renders as a callout in Obsidian) and the importer parses it back —
-// alongside the legacy `:::type` fence so existing vaults keep working.
-// ---------------------------------------------------------------------------
-describe('preprocessCallouts: Obsidian `> [!type]` callouts', () => {
-  it('imports `> [!type]` as a callout node (not a plain blockquote)', async () => {
-    const md = ['> [!warning]', '> be careful', '> second line'].join('\n');
-    const docNode = await markdownToProseMirror(md);
-    const callouts = findAll(docNode, 'callout');
-    expect(callouts).toHaveLength(1);
-    expect(callouts[0].attrs?.type).toBe('warning');
-    expect(findAll(docNode, 'blockquote')).toHaveLength(0);
-    expect(allText(callouts[0])).toContain('be careful');
-  });
-
-  it('imports a nested `> > [!type]` callout inside another', async () => {
-    const md = ['> [!info]', '> outer', '> > [!danger]', '> > inner'].join('\n');
-    const docNode = await markdownToProseMirror(md);
-    const outer = docNode.content?.[0];
-    expect(outer?.type).toBe('callout');
-    expect(outer?.attrs?.type).toBe('info');
-    const inner = (outer?.content || []).filter(
-      (n: any) => n.type === 'callout',
-    );
-    expect(inner).toHaveLength(1);
-    expect(inner[0].attrs?.type).toBe('danger');
-    expect(allText(inner[0])).toContain('inner');
-  });
-
-  it('round-trips a callout: export -> `> [!type]` -> import keeps type + body', async () => {
-    const original = {
-      type: 'doc',
-      content: [
-        {
-          type: 'callout',
-          attrs: { type: 'success' },
-          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'done' }] }],
-        },
-      ],
-    };
-    const md = convertProseMirrorToMarkdown(original);
-    expect(md).toBe('> [!success]\n> done');
-    const back = await markdownToProseMirror(md);
-    const callouts = findAll(back, 'callout');
-    expect(callouts).toHaveLength(1);
-    expect(callouts[0].attrs?.type).toBe('success');
-    expect(allText(callouts[0])).toContain('done');
-  });
-
-  it('a plain blockquote (no `[!type]`) stays a blockquote', async () => {
-    const back = await markdownToProseMirror('> just a quote\n> more');
-    expect(findAll(back, 'callout')).toHaveLength(0);
-    expect(findAll(back, 'blockquote')).toHaveLength(1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 3. preprocessCallouts — two uncovered branches.
-//
-// (a) NESTED callouts: an inner `:::type ... :::` inside an outer callout body
-//     must be matched at its own nesting level (the depth counter) and emerge as
-//     a callout NESTED inside the outer callout — not flattened or mis-closed.
-// (b) A `:::` line INSIDE a fenced code block must NOT be treated as a callout
-//     delimiter: the scanner tracks code fences and copies their lines verbatim,
-//     so the outer callout's matching `:::` is the one AFTER the fence closes.
-// ---------------------------------------------------------------------------
-describe('preprocessCallouts: nested callouts + code-fenced ":::"', () => {
-  it('(a) parses a callout nested inside another callout', async () => {
-    const md = [
-      ':::info',
-      'outer text',
-      ':::warning',
-      'inner text',
-      ':::',
-      ':::',
-    ].join('\n');
-
-    const docNode = await markdownToProseMirror(md);
-
-    // Exactly two callouts, and one is nested inside the other.
-    const callouts = findAll(docNode, 'callout');
-    expect(callouts).toHaveLength(2);
-
-    const outer = docNode.content?.[0];
-    expect(outer?.type).toBe('callout');
-    expect(outer?.attrs?.type).toBe('info');
-
-    // The inner callout is a CHILD of the outer one (not a sibling at doc level).
-    const innerCallouts = (outer?.content || []).filter(
-      (n: any) => n.type === 'callout',
-    );
-    expect(innerCallouts).toHaveLength(1);
-    expect(innerCallouts[0].attrs?.type).toBe('warning');
-
-    // Both bodies kept their text.
-    expect(allText(outer)).toContain('outer text');
-    expect(allText(innerCallouts[0])).toContain('inner text');
-  });
-
-  it('(b) a ":::" line inside a fenced code block is NOT a callout delimiter', async () => {
-    // The inner ``` ... ``` fence contains a `:::` line. If preprocessCallouts
-    // treated it as the closing fence, the callout would terminate early and the
-    // code text would leak out. The correct behavior: the fence content survives
-    // verbatim in a codeBlock, and the callout closes at the LAST ":::".
-    const md = [
-      ':::info',
-      'before code',
-      '```',
-      ':::',
-      'still inside the code fence',
-      '```',
-      'after code',
-      ':::',
-    ].join('\n');
-
-    const docNode = await markdownToProseMirror(md);
-
-    // One callout wrapping everything (it did not close early on the fenced ":::")
-    const callouts = findAll(docNode, 'callout');
-    expect(callouts).toHaveLength(1);
-    const callout = callouts[0];
-
-    // The code block is a CHILD of the callout and still contains the ":::" line.
-    const codeBlocks = findAll(callout, 'codeBlock');
-    expect(codeBlocks).toHaveLength(1);
-    expect(allText(codeBlocks[0])).toContain(':::');
-    expect(allText(codeBlocks[0])).toContain('still inside the code fence');
-
-    // The text before and after the fence is part of the callout, not a stray
-    // top-level paragraph created by an early close.
-    expect(allText(callout)).toContain('before code');
-    expect(allText(callout)).toContain('after code');
-  });
-
-  it('(c) an UNCLOSED ":::" opener is treated as a literal line, not a callout', async () => {
-    // Realistic input: a hand-edited vault file with a `:::info` opener and no
-    // matching closing `:::`. The fallback emits the opener as a LITERAL line
-    // rather than swallowing the rest of the document into a phantom callout —
-    // previously uncovered (markdown-to-prosemirror.ts).
-    const md = [':::info', 'orphan body line', 'another line'].join('\n');
-
-    const docNode = await markdownToProseMirror(md);
-
-    // No callout node was created (the opener never closed).
-    expect(findAll(docNode, 'callout')).toHaveLength(0);
-    // The opener survives as literal text and the body lines are preserved (the
-    // rest of the document was NOT eaten by an unterminated callout).
-    const text = allText(docNode);
-    expect(text).toContain(':::info');
-    expect(text).toContain('orphan body line');
-    expect(text).toContain('another line');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// 4. bridgeTaskLists — numbered checklist + mixed-list negative.
-//
-// (a) A NUMBERED checklist (`1. [x] ...`) is rendered by marked as an <ol> of
-//     checkbox <li>s. The bridge must convert it to a taskList AND rename the
-//     <ol> to a <ul> so generateJSON does NOT also match the orderedList rule
-//     and emit a phantom empty orderedList beside the real taskList.
-// (b) NEGATIVE: a MIXED list (some items have checkboxes, some don't) must NOT
-//     be converted — it stays an ordinary bullet/numbered list.
-// ---------------------------------------------------------------------------
-describe('bridgeTaskLists: numbered checklist + mixed-list negative', () => {
-  it('(a) a numbered <ol> checklist becomes a taskList with NO phantom orderedList', async () => {
-    const md = ['1. [x] done', '2. [ ] todo'].join('\n');
-
-    const docNode = await markdownToProseMirror(md);
-
-    // It became a taskList...
-    const taskLists = findAll(docNode, 'taskList');
-    expect(taskLists).toHaveLength(1);
-
-    const items = (taskLists[0].content || []).filter(
-      (n: any) => n.type === 'taskItem',
-    );
-    expect(items).toHaveLength(2);
-    expect(items[0].attrs?.checked).toBe(true);
-    expect(items[1].attrs?.checked).toBe(false);
-    expect(allText(items[0])).toContain('done');
-    expect(allText(items[1])).toContain('todo');
-
-    // ...and NO phantom (empty) orderedList survived the <ol> -> <ul> rename.
-    const orderedLists = findAll(docNode, 'orderedList');
-    expect(orderedLists).toHaveLength(0);
-  });
-
-  it('(b) a MIXED list (some items checkboxed, some not) is NOT converted to a taskList', async () => {
-    const md = ['- [x] checked item', '- plain item'].join('\n');
-
-    const docNode = await markdownToProseMirror(md);
-
-    // The bridge requires EVERY direct <li> to carry its own checkbox; one plain
-    // item disqualifies the whole list, so it stays a bulletList.
-    expect(findAll(docNode, 'taskList')).toHaveLength(0);
-    expect(findAll(docNode, 'taskItem')).toHaveLength(0);
-
-    const bulletLists = findAll(docNode, 'bulletList');
-    expect(bulletLists).toHaveLength(1);
-    const listItems = findAll(bulletLists[0], 'listItem');
-    expect(listItems).toHaveLength(2);
-    // Both items survive as ordinary list items (text preserved).
-    expect(allText(bulletLists[0])).toContain('checked item');
-    expect(allText(bulletLists[0])).toContain('plain item');
-  });
-});
-
-// Find the first mark of a given type on a text node anywhere in the tree.
-const firstMark = (node: any, markType: string): any => {
-  if (node?.type === 'text') {
-    for (const m of node.marks || []) if (m.type === markType) return m;
-  }
-  for (const child of node?.content || []) {
-    const found = firstMark(child, markType);
-    if (found) return found;
-  }
-  return null;
-};
-
-// ---------------------------------------------------------------------------
-// Spec 1. IMPORT-side color sanitization for the highlight + textStyle marks.
-//
-// The Highlight.extend / TextStyle parseHTML run attacker-controlled colors
-// through sanitizeCssColor when generateJSON re-parses stored HTML. This is the
-// real defense that strips a crafted color on IMPORT (the export-side emission
-// is tested elsewhere; the parse path was not).
-// ---------------------------------------------------------------------------
-describe('import: highlight/textStyle color sanitization (parseHTML)', () => {
-  it('strips the unsafe "--x:1" declaration but keeps the safe "red" background-color', async () => {
-    const doc = await markdownToProseMirror(
-      '<mark style="background-color: red; --x:1">x</mark>',
-    );
-    const mark = firstMark(doc, 'highlight');
-    // The highlight mark IS present on the text run.
-    expect(mark).not.toBeNull();
-    expect(allText(doc)).toContain('x');
-    // NOTE(review): Spec 1 expected attrs.color === null for this input. The
-    // ACTUAL behavior is attrs.color === 'red': the schema's Highlight.extend
-    // reads the color via getStyleProperty(el, 'background-color'), which
-    // isolates the `background-color: red` declaration and DROPS the separate
-    // unsafe `--x:1` declaration. sanitizeCssColor('red') then accepts the bare
-    // named color. So the injection ('--x:1') is stripped (the defense holds)
-    // but the legitimate 'red' survives — color is 'red', not null. The
-    // color-dropped-to-null path is exercised by the data-color variant below,
-    // where the whole "red; --x:1" string reaches sanitizeCssColor and fails.
-    expect(mark.attrs.color).toBe('red');
-  });
-
-  it('drops a crafted color carried whole in data-color (sanitizeCssColor -> null)', async () => {
-    // Here the entire unsafe string is the candidate color (no per-declaration
-    // splitting), so sanitizeCssColor rejects it and the highlight color is null
-    // while the highlight mark itself is still applied.
-    const doc = await markdownToProseMirror(
-      '<mark data-color="red; --x:1">x</mark>',
-    );
-    const mark = firstMark(doc, 'highlight');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.color).toBeNull();
-  });
-
-  it("imports '#ff0000' as the highlight mark color verbatim", async () => {
-    const doc = await markdownToProseMirror(
-      '<mark style="background-color: #ff0000">x</mark>',
-    );
-    const mark = firstMark(doc, 'highlight');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.color).toBe('#ff0000');
-  });
-
-  it("imports a colored span as a textStyle mark with the sanitized color", async () => {
-    const doc = await markdownToProseMirror(
-      '<span style="color: rebeccapurple">y</span>',
-    );
-    const mark = firstMark(doc, 'textStyle');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.color).toBe('rebeccapurple');
-    // It is carried on a real text node containing the span's text.
-    expect(allText(doc)).toContain('y');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 2. Importing a non-schema callout fence resolves the type via the editor's
-// alias map (known GitHub/Obsidian aliases) or clamps to 'info' (unknown).
-//
-// preprocessCallouts emits div[data-type=callout][data-callout-type=<type>]; the
-// schema's Callout.type parseHTML pipes it through clampCalloutType. A known alias
-// (`tip`) maps to the editor's banner (`success`); a genuinely unknown type
-// (`banana`) clamps to the 'info' default. End-to-end import-side resolution.
-// ---------------------------------------------------------------------------
-describe('import: non-schema callout fence resolves via alias map / clamps to info', () => {
-  it("imports ':::tip' as a callout whose attrs.type === 'success' (alias)", async () => {
-    const doc = await markdownToProseMirror(':::tip\nhello\n:::');
-    const callouts = findAll(doc, 'callout');
-    expect(callouts).toHaveLength(1);
-    expect(callouts[0].attrs.type).toBe('success');
-    // The body paragraph survived inside the callout.
-    expect(allText(callouts[0])).toContain('hello');
-    const paras = findAll(callouts[0], 'paragraph');
-    expect(paras.length).toBeGreaterThanOrEqual(1);
-  });
-
-  it("imports ':::banana' (unknown) as a callout whose attrs.type === 'info'", async () => {
-    const doc = await markdownToProseMirror(':::banana\nhello\n:::');
-    const callouts = findAll(doc, 'callout');
-    expect(callouts).toHaveLength(1);
-    expect(callouts[0].attrs.type).toBe('info');
-    expect(allText(callouts[0])).toContain('hello');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 3. Importing a columns layout with a string data-width yields a numeric
-// column width, and the columns wrapper carries its default layout/widthMode.
-// ---------------------------------------------------------------------------
-describe('import: columns layout with string data-width -> numeric width', () => {
-  it('parses data-width="33.5" to the number 33.5 and populates columns defaults', async () => {
-    const doc = await markdownToProseMirror(
-      '<div data-type="columns"><div data-type="column" data-width="33.5"><p>a</p></div></div>',
-    );
-    const columns = findAll(doc, 'columns');
-    expect(columns).toHaveLength(1);
-    // Columns default attrs are populated (not undefined).
-    expect(columns[0].attrs.widthMode).toBe('normal');
-    expect(columns[0].attrs.layout).not.toBeNull();
-    expect(columns[0].attrs.layout).toBe('two_equal');
-
-    const cols = findAll(columns[0], 'column');
-    expect(cols).toHaveLength(1);
-    // parseFloat('33.5') -> 33.5 as a NUMBER, not the string '33.5'.
-    expect(cols[0].attrs.width).toBe(33.5);
-    expect(typeof cols[0].attrs.width).toBe('number');
-    expect(allText(cols[0])).toContain('a');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 4. Comment mark resolved-attribute boolean coercion on import.
-//
-// The comment mark's resolved attr parseHTML compares
-// el.getAttribute('data-resolved') === 'true', so a missing attribute yields
-// false (default) and the literal 'true' yields boolean true.
-// ---------------------------------------------------------------------------
-describe('import: comment mark commentId + resolved boolean coercion', () => {
-  it("data-resolved='true' -> resolved:true with the parsed commentId", async () => {
-    const doc = await markdownToProseMirror(
-      '<span data-comment-id="c1" data-resolved="true">x</span>',
-    );
-    const mark = firstMark(doc, 'comment');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.commentId).toBe('c1');
-    expect(mark.attrs.resolved).toBe(true);
-  });
-
-  it('a missing data-resolved -> resolved:false (default)', async () => {
-    const doc = await markdownToProseMirror(
-      '<span data-comment-id="c2">y</span>',
-    );
-    const mark = firstMark(doc, 'comment');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.commentId).toBe('c2');
-    expect(mark.attrs.resolved).toBe(false);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 5. A NON-numeric truthy data-width reaches parseFloat and yields NaN.
-//
-// Column.width parseHTML is `value ? parseFloat(value) : null`; 'abc' is truthy
-// so parseFloat('abc') -> NaN leaks through as the raw attribute value rather
-// than falling back to the null default. (JSON.stringify would serialize NaN to
-// null — see the assertion below — so the leak is invisible in serialized JSON.)
-// ---------------------------------------------------------------------------
-describe('import: malformed non-numeric data-width leaks NaN', () => {
-  it("data-width='abc' -> column width is NaN (typeof number), not null", async () => {
-    const doc = await markdownToProseMirror(
-      '<div data-type="columns"><div data-type="column" data-width="abc"><p>x</p></div></div>',
-    );
-    const width = doc.content[0].content[0].attrs.width;
-    expect(typeof width).toBe('number');
-    expect(Number.isNaN(width)).toBe(true);
-    // Document that the leak is masked by JSON serialization: NaN -> null.
-    expect(JSON.parse(JSON.stringify(doc)).content[0].content[0].attrs.width).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 6. A column with NO data-width attribute lands on the null default.
-//
-// The else branch of `value ? parseFloat(value) : null` (getAttribute -> null)
-// must yield exactly null (not NaN/undefined), and the columns wrapper carries
-// its layout/widthMode defaults.
-// ---------------------------------------------------------------------------
-describe('import: width-less column lands on null default', () => {
-  it('no data-width -> column width === null, columns defaults populated', async () => {
-    const doc = await markdownToProseMirror(
-      '<div data-type="columns"><div data-type="column"><p>y</p></div></div>',
-    );
-    expect(doc.content[0].content[0].attrs.width).toBe(null);
-    expect(doc.content[0].attrs.layout).toBe('two_equal');
-    expect(doc.content[0].attrs.widthMode).toBe('normal');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 7. A structural callout div with missing/empty data-callout-type clamps
-// to 'info' via clampCalloutType (the parseHTML getAttrs fallback), with no icon.
-// ---------------------------------------------------------------------------
-describe('import: callout div with missing/empty data-callout-type clamps to info', () => {
-  it('a callout div with NO data-callout-type -> type:info, icon:null', async () => {
-    const doc = await markdownToProseMirror(
-      '<div data-type="callout"><p>z</p></div>',
-    );
-    expect(doc.content[0].type).toBe('callout');
-    expect(doc.content[0].attrs.type).toBe('info');
-    expect(doc.content[0].attrs.icon).toBeNull();
-  });
-
-  it('a callout div with EMPTY data-callout-type -> type:info, icon:null', async () => {
-    const doc = await markdownToProseMirror(
-      '<div data-type="callout" data-callout-type=""><p>w</p></div>',
-    );
-    expect(doc.content[0].type).toBe('callout');
-    expect(doc.content[0].attrs.type).toBe('info');
-    expect(doc.content[0].attrs.icon).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 8. A plain <td> with no align/colspan/rowspan/colwidth lands on the
-// schema defaults (align null via the `||` fallback arm; spans default to 1).
-// ---------------------------------------------------------------------------
-describe('import: span/align-less table cell lands on defaults', () => {
-  it('a bare td -> align:null, colspan:1, rowspan:1, colwidth:null', async () => {
-    const doc = await markdownToProseMirror(
-      '<table><tbody><tr><td><p>c</p></td></tr></tbody></table>',
-    );
-    const cells = findAll(doc, 'tableCell');
-    expect(cells).toHaveLength(1);
-    const attrs = cells[0].attrs;
-    expect(attrs.align).toBeNull();
-    expect(attrs.colspan).toBe(1);
-    expect(attrs.rowspan).toBe(1);
-    expect(attrs.colwidth).toBeNull();
-    expect(allText(cells[0])).toContain('c');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 9. underline/subscript/superscript marks survive import and re-export.
-// (inlineToHtml src 611-619 renders them back to <u>/<sub>/<sup>.)
-// ---------------------------------------------------------------------------
-describe('import+export: underline/subscript/superscript marks round-trip', () => {
-  it('<u>/<sub>/<sup> import to the right marks and re-export unchanged', async () => {
-    const doc = await markdownToProseMirror('<p><u>a</u><sub>b</sub><sup>c</sup></p>');
-    const para = findAll(doc, 'paragraph')[0];
-    const texts = (para.content || []).filter((n: any) => n.type === 'text');
-    expect(texts).toHaveLength(3);
-    expect(texts[0].text).toBe('a');
-    expect((texts[0].marks || []).map((m: any) => m.type)).toEqual(['underline']);
-    expect(texts[1].text).toBe('b');
-    expect((texts[1].marks || []).map((m: any) => m.type)).toEqual(['subscript']);
-    expect(texts[2].text).toBe('c');
-    expect((texts[2].marks || []).map((m: any) => m.type)).toEqual(['superscript']);
-
-    const md = convertProseMirrorToMarkdown(doc);
-    expect(md).toContain('<u>a</u>');
-    expect(md).toContain('<sub>b</sub>');
-    expect(md).toContain('<sup>c</sup>');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 10. Heading level attribute fidelity (h1/h2/h6) on import and re-export.
-// ---------------------------------------------------------------------------
-describe('import+export: heading levels 1/2/6 round-trip', () => {
-  it('parses # / ## / ###### to level 1/2/6 and re-emits them', async () => {
-    const doc = await markdownToProseMirror('# H1\n\n## H2\n\n###### H6');
-    const headings = findAll(doc, 'heading');
-    expect(headings).toHaveLength(3);
-    expect(headings[0].attrs.level).toBe(1);
-    expect(headings[1].attrs.level).toBe(2);
-    expect(headings[2].attrs.level).toBe(6);
-
-    const md = convertProseMirrorToMarkdown(doc);
-    const blocks = md.split('\n\n');
-    expect(blocks).toContain('# H1');
-    expect(blocks).toContain('## H2');
-    expect(blocks).toContain('###### H6');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Spec 11. Link mark recovers BOTH href and title on import and round-trips.
-// ---------------------------------------------------------------------------
-describe('import+export: link mark href + title round-trip', () => {
-  it('parses [lbl](http://a "the title") with href+title and re-emits it', async () => {
-    const doc = await markdownToProseMirror('[lbl](http://a "the title")');
-    const mark = firstMark(doc, 'link');
-    expect(mark).not.toBeNull();
-    expect(mark.attrs.href).toBe('http://a');
-    expect(mark.attrs.title).toBe('the title');
-    expect(allText(doc)).toContain('lbl');
-
-    const md = convertProseMirrorToMarkdown(doc);
-    expect(md).toContain('[lbl](http://a "the title")');
-  });
-});
diff --git a/packages/git-sync/test/media-roundtrip.test.ts b/packages/git-sync/test/media-roundtrip.test.ts
deleted file mode 100644
index cc687704..00000000
--- a/packages/git-sync/test/media-roundtrip.test.ts
+++ /dev/null
@@ -1,275 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-  docsCanonicallyEqual,
-} from 'docmost-client';
-
-// ---------------------------------------------------------------------------
-// Media / atom node round-trip coverage (audio, video, pdf, attachment, embed,
-// youtube). The existing specs (corpus + property test) exercise the EXPORT
-// direction of these nodes only; their parseHTML branches (the INVERSE parse of
-// the exported HTML) are otherwise unprotected. Each test runs the full
-// export -> import -> export pipeline and pins:
-//   - the exact md1 byte string the converter emits,
-//   - whether md2 is byte-stable (md2 === md1) or grows by a materialized
-//     schema default on the first import,
-//   - the re-parsed doc2 attrs (NOTE: parseHTML reads via getAttribute and so
-//     returns STRINGS for numeric attrs, which is what breaks naive canonical
-//     equality), and
-//   - docsCanonicallyEqual(doc, doc2) where the spec asserts a specific result.
-//
-// `convertProseMirrorToMarkdown` requires a full doc ({type:'doc', content:[]}),
-// so each spec's `doc=[...]` content array is wrapped via mkDoc().
-// ---------------------------------------------------------------------------
-
-/** Wrap a content array (as the specs express `doc`) into a real PM doc. */
-const mkDoc = (content: any[]) => ({ type: 'doc', content });
-
-/** export -> import -> export, returning both markdowns and the re-parsed doc. */
-async function roundTrip(doc: any) {
-  const md1 = convertProseMirrorToMarkdown(doc);
-  const doc2 = await markdownToProseMirror(md1);
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  return { md1, md2, doc2 };
-}
-
-/** Find the first node of a given type anywhere in a PM doc tree. */
-const findFirst = (node: any, type: string): any => {
-  if (node && node.type === type) return node;
-  for (const child of node?.content || []) {
-    const hit = findFirst(child, type);
-    if (hit) return hit;
-  }
-  return null;
-};
-
-describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', () => {
-  // 1. audio with ALL optional attrs ---------------------------------------
-  it('audio with src+attachmentId+size: byte-stable, size re-parses to the STRING "9001"', async () => {
-    const doc = mkDoc([
-      { type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7', size: 9001 } },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
-    );
-    // Byte-stable: a second export reproduces the first exactly.
-    expect(md2).toBe(md1);
-
-    const audio = findFirst(doc2, 'audio');
-    expect(audio).not.toBeNull();
-    expect(audio.type).toBe('audio');
-    expect(audio.attrs.src).toBe('/a.mp3');
-    expect(audio.attrs.attachmentId).toBe('att-7');
-    // NOTE: the schema's data-size parseHTML returns getAttribute() -> a STRING,
-    // so the number 9001 comes back as the string '9001'.
-    expect(audio.attrs.size).toBe('9001');
-  });
-
-  // 2. fully-populated video -----------------------------------------------
-  it('video with all attrs: byte-stable; numeric attrs re-parse to STRINGS; canonical equality FALSE', async () => {
-    const doc = mkDoc([
-      {
-        type: 'video',
-        attrs: {
-          src: '/v.mp4',
-          alt: 'clip',
-          attachmentId: 'att-1',
-          width: 640,
-          height: 480,
-          size: 1234,
-          align: 'center',
-          aspectRatio: 1.777,
-        },
-      },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
-    );
-    expect(md2).toBe(md1);
-
-    const video = findFirst(doc2, 'video');
-    expect(video).not.toBeNull();
-    expect(video.attrs.alt).toBe('clip');
-    // All numeric attrs come back as STRINGS via getAttribute().
-    expect(video.attrs.width).toBe('640');
-    expect(video.attrs.height).toBe('480');
-    expect(video.attrs.size).toBe('1234');
-    expect(video.attrs.aspectRatio).toBe('1.777');
-
-    // Byte-stable export but NOT canonically equal: the numeric width/height/
-    // size/aspectRatio came back as strings, so deep-equal of the canonical
-    // forms fails (align:'center' is normalized away, the numbers are not).
-    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
-  });
-
-  // 3. minimal video (only src) --------------------------------------------
-  it('minimal video (src only): NOT byte-stable (gains data-align="center") but canonically equal', async () => {
-    const doc = mkDoc([{ type: 'video', attrs: { src: '/v.mp4' } }]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe('<div><video src="/v.mp4"></video></div>');
-    // video.align has a non-null schema default 'center' that materializes on
-    // import; the converter only emits data-align when set, so export #2 grows
-    // by data-align="center" exactly once (the documented one-time asymmetry).
-    expect(md2).toBe('<div><video src="/v.mp4" data-align="center"></video></div>');
-    expect(md2).not.toBe(md1);
-
-    // align:'center' is normalized away via KNOWN_DEFAULTS.video, so despite the
-    // byte growth the documents ARE canonically equal.
-    expect(docsCanonicallyEqual(doc, doc2)).toBe(true);
-  });
-
-  // 4. pdf with no numeric attrs (positive control) -------------------------
-  it('pdf with src+name+attachmentId (no numerics): byte- AND canonically-stable', async () => {
-    const doc = mkDoc([
-      { type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf', attachmentId: 'att-9' } },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9"></div>',
-    );
-    expect(md2).toBe(md1);
-
-    const pdf = findFirst(doc2, 'pdf');
-    expect(pdf).not.toBeNull();
-    expect(pdf.attrs.src).toBe('/d.pdf');
-    expect(pdf.attrs.name).toBe('d.pdf');
-    expect(pdf.attrs.attachmentId).toBe('att-9');
-
-    // No numeric attrs to coerce to strings, so the round-trip is BOTH byte- and
-    // canonically-stable (the positive control vs. the numeric-divergence cases).
-    expect(docsCanonicallyEqual(doc, doc2)).toBe(true);
-  });
-
-  // 5. attachment with numeric size ----------------------------------------
-  it('attachment with url+name+mime+size+attachmentId: byte-stable; size STRING; canonical FALSE', async () => {
-    const doc = mkDoc([
-      {
-        type: 'attachment',
-        attrs: {
-          url: '/f.zip',
-          name: 'f.zip',
-          mime: 'application/zip',
-          size: 512,
-          attachmentId: 'att-3',
-        },
-      },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
-    );
-    expect(md2).toBe(md1);
-
-    const att = findFirst(doc2, 'attachment');
-    expect(att).not.toBeNull();
-    expect(att.attrs.url).toBe('/f.zip');
-    expect(att.attrs.name).toBe('f.zip');
-    expect(att.attrs.mime).toBe('application/zip');
-    expect(att.attrs.attachmentId).toBe('att-3');
-    // data-attachment-size parseHTML -> getAttribute() -> STRING.
-    expect(att.attrs.size).toBe('512');
-
-    // The numeric size coerced to a string breaks canonical equality.
-    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
-  });
-
-  // 6. embed WITH explicit width/height/align (byte-stable) ----------------
-  it('embed with explicit src+provider+align+width+height: byte-stable; width/height STRINGS', async () => {
-    const doc = mkDoc([
-      {
-        type: 'embed',
-        attrs: {
-          src: 'https://x.com/e',
-          provider: 'iframe',
-          align: 'left',
-          width: 600,
-          height: 400,
-        },
-      },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
-    );
-    expect(md2).toBe(md1);
-
-    const embed = findFirst(doc2, 'embed');
-    expect(embed).not.toBeNull();
-    expect(embed.attrs.src).toBe('https://x.com/e');
-    expect(embed.attrs.provider).toBe('iframe');
-    expect(embed.attrs.align).toBe('left');
-    // data-width / data-height parseHTML -> getAttribute() -> STRINGS.
-    expect(embed.attrs.width).toBe('600');
-    expect(embed.attrs.height).toBe('400');
-  });
-
-  // 7. minimal embed (only src+provider) -----------------------------------
-  it('minimal embed (src+provider): NOT byte-stable; defaults width/height materialize as NUMBERS 800/600', async () => {
-    const doc = mkDoc([
-      { type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
-    );
-    // embed has non-null schema defaults align='center', width=800, height=600
-    // that the converter never emits on export #1 but materialize on import, so
-    // export #2 grows by three data-* attrs (a one-time divergence).
-    expect(md2).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="center" data-width="800" data-height="600"></div>',
-    );
-    expect(md2).not.toBe(md1);
-
-    const embed = findFirst(doc2, 'embed');
-    expect(embed).not.toBeNull();
-    expect(embed.attrs.align).toBe('center');
-    // NOTE: these come from the addAttributes default (NOT parseHTML), so on the
-    // FIRST import they are the NUMBERS 800/600, not strings — parseHTML only
-    // runs when the attribute is actually present on the imported element.
-    expect(embed.attrs.width).toBe(800);
-    expect(embed.attrs.height).toBe(600);
-  });
-
-  // 8. youtube with src+width+height+align ---------------------------------
-  it('youtube with src+width+height+align(right): byte-stable; width/height STRINGS; canonical FALSE', async () => {
-    const doc = mkDoc([
-      {
-        type: 'youtube',
-        attrs: {
-          src: 'https://youtu.be/abc',
-          width: 560,
-          height: 315,
-          align: 'right',
-        },
-      },
-    ]);
-    const { md1, md2, doc2 } = await roundTrip(doc);
-
-    expect(md1).toBe(
-      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
-    );
-    expect(md2).toBe(md1);
-
-    const yt = findFirst(doc2, 'youtube');
-    expect(yt).not.toBeNull();
-    expect(yt.attrs.src).toBe('https://youtu.be/abc');
-    expect(yt.attrs.align).toBe('right');
-    // data-width / data-height parseHTML -> getAttribute() -> STRINGS.
-    expect(yt.attrs.width).toBe('560');
-    expect(yt.attrs.height).toBe('315');
-
-    // Numeric width/height coerced to strings; align='right' is non-default so
-    // it is kept (not in KNOWN_DEFAULTS.youtube's normalization). Canonical FALSE.
-    expect(docsCanonicallyEqual(doc, doc2)).toBe(false);
-  });
-});
diff --git a/packages/git-sync/test/node-ops-extra.test.ts b/packages/git-sync/test/node-ops-extra.test.ts
deleted file mode 100644
index fbdb058a..00000000
--- a/packages/git-sync/test/node-ops-extra.test.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import fc from 'fast-check';
-import {
-  getNodeByRef,
-  replaceNodeById,
-  insertNodeRelative,
-  insertTableRow,
-  updateTableCell,
-  sanitizeForYjs,
-  findUnstorableAttr,
-  buildOutline,
-} from '../src/lib/node-ops.js';
-
-// Gaps NOT covered by node-ops.test.ts (test-strategy report §2). The base file
-// is comprehensive; these add only the missing edges: newNode-arg immutability,
-// anchor-is-container routing, malformed opts, ragged/empty/no-colwidth/non-int
-// insertTableRow, getNodeByRef non-object/#-1, updateTableCell empty-id refresh,
-// outline 100/40 boundary, malformed marks, and the makeFreshId property.
-
-const text = (value: string, marks?: any[]): any => {
-  const node: any = { type: 'text', text: value };
-  if (marks) node.marks = marks;
-  return node;
-};
-const para = (id: string, value = ''): any => ({
-  type: 'paragraph',
-  attrs: { id, indent: 0 },
-  content: value ? [text(value)] : [],
-});
-const cell = (
-  type: 'tableCell' | 'tableHeader',
-  paraId: string | null,
-  value = '',
-  extraAttrs: Record<string, any> = {},
-): any => ({
-  type,
-  attrs: { colspan: 1, rowspan: 1, ...extraAttrs },
-  content: paraId == null ? [] : [para(paraId, value)],
-});
-const row = (cells: any[]): any => ({ type: 'tableRow', content: cells });
-const doc = (...content: any[]): any => ({ type: 'doc', content });
-
-// ===========================================================================
-describe('replaceNodeById — newNode ARGUMENT immutability', () => {
-  it('does not mutate the caller-supplied newNode after replacement', () => {
-    // The doc-argument immutability is covered in the base file; this pins the
-    // OTHER input — the replacement node must be deep-cloned, so mutating the
-    // result never reaches the caller's newNode (and vice versa).
-    const d = doc(para('p0', 'old'), para('p1', 'old2'));
-    const newNode = { type: 'paragraph', attrs: { id: 'new' }, content: [text('NEW')] };
-    const snapshot = structuredClone(newNode);
-    const res = replaceNodeById(d, 'p0', newNode);
-    // Mutating the inserted copy must not touch the argument...
-    res.doc.content[0].content.push(text('mutated'));
-    expect(newNode).toEqual(snapshot);
-    // ...and mutating the argument afterwards must not touch the inserted copy.
-    newNode.content.push(text('later'));
-    expect(res.doc.content[0].content).toEqual([text('NEW'), text('mutated')]);
-  });
-});
-
-// ===========================================================================
-describe('insertNodeRelative — container routing and malformed opts', () => {
-  it('routes a structural row when anchorText resolves to the TABLE block itself', () => {
-    // anchorText only scans top-level blocks, so it resolves to the whole table;
-    // the matched container IS the anchor (containerIdx === chain.length-1), so
-    // a row "after" must be appended inside the table, not spliced beside a row.
-    const table = { type: 'table', content: [row([cell('tableCell', 'r0', 'hello cell')])] };
-    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
-    const res = insertNodeRelative(doc(table), newRow, {
-      position: 'after',
-      anchorText: 'hello cell',
-    });
-    expect(res.inserted).toBe(true);
-    const firstCellId = (r: any) => r.content[0].content[0].attrs.id;
-    expect(res.doc.content[0].content.map(firstCellId)).toEqual(['r0', 'rNew']);
-  });
-
-  it('prepends a structural row when anchorText resolves to the table and position is "before"', () => {
-    const table = { type: 'table', content: [row([cell('tableCell', 'r0', 'hello cell')])] };
-    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
-    const res = insertNodeRelative(doc(table), newRow, {
-      position: 'before',
-      anchorText: 'hello cell',
-    });
-    const firstCellId = (r: any) => r.content[0].content[0].attrs.id;
-    expect(res.doc.content[0].content.map(firstCellId)).toEqual(['rNew', 'r0']);
-  });
-
-  it('is a no-op (inserted:false) for a malformed opts object', () => {
-    const d = doc(para('p0'));
-    const res = insertNodeRelative(d, para('n'), null as any);
-    expect(res.inserted).toBe(false);
-    expect(res.doc).toEqual(d);
-  });
-});
-
-// ===========================================================================
-describe('insertTableRow — column count and index edge cases', () => {
-  const ragged = () => ({
-    type: 'table',
-    content: [
-      row([cell('tableHeader', 'h0', 'H0')]), // 1 col
-      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]), // 2 cols
-    ],
-  });
-
-  it('derives the column count from the WIDEST row (ragged table)', () => {
-    // The guard counts against the widest row (2), so 3 cells throws...
-    expect(() => insertTableRow(doc(ragged()), '#0', ['X', 'Y', 'Z'])).toThrow(
-      /got 3 cell\(s\) but the table has 2 column\(s\)/,
-    );
-    // ...and a 2-cell row is padded to the widest width (2), not the header's 1.
-    const res = insertTableRow(doc(ragged()), '#0', ['X', 'Y']);
-    expect(res.doc.content[0].content[2].content).toHaveLength(2);
-  });
-
-  it('an EMPTY table falls back to the supplied cell count', () => {
-    const res = insertTableRow(doc({ type: 'table', content: [] }), '#0', ['A', 'B']);
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content[0].content[0].content).toHaveLength(2);
-  });
-
-  it('omits colwidth entirely when the header cell has none (no undefined leak)', () => {
-    const noColwidth = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'h0', 'H')]),
-        row([cell('tableCell', 'c0', 'A')]),
-      ],
-    };
-    const res = insertTableRow(doc(noColwidth), '#0', ['X']);
-    const newCellAttrs = res.doc.content[0].content[2].content[0].attrs;
-    expect('colwidth' in newCellAttrs).toBe(false); // not colwidth:undefined
-  });
-
-  it('APPENDS for a non-integer or negative index (does not throw)', () => {
-    const t = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'h0', 'H')]),
-        row([cell('tableCell', 'c0', 'A')]),
-      ],
-    };
-    const frac = insertTableRow(doc(t), '#0', ['X'], 1.5);
-    expect(frac.inserted).toBe(true);
-    expect(frac.doc.content[0].content).toHaveLength(3); // appended at the end
-    const neg = insertTableRow(doc(t), '#0', ['X'], -1);
-    expect(neg.doc.content[0].content).toHaveLength(3);
-  });
-});
-
-// ===========================================================================
-describe('getNodeByRef — malformed refs', () => {
-  it('returns null for a non-object block at a valid #n index', () => {
-    const d = { type: 'doc', content: [null] };
-    expect(getNodeByRef(d, '#0')).toBeNull();
-  });
-
-  it('returns null for "#-1" (the index regex does not match a negative)', () => {
-    const d = doc(para('p0'));
-    // "#-1" matches neither the "#<digits>" form nor any block id -> null.
-    expect(getNodeByRef(d, '#-1')).toBeNull();
-  });
-});
-
-// ===========================================================================
-describe('updateTableCell — fresh id when the first paragraph has an empty id', () => {
-  it('mints a fresh id when the existing first paragraph id is the empty string', () => {
-    const table = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'h0', 'H')]),
-        row([
-          {
-            type: 'tableCell',
-            attrs: { colspan: 1, rowspan: 1 },
-            content: [{ type: 'paragraph', attrs: { id: '' }, content: [text('old')] }],
-          },
-        ]),
-      ],
-    };
-    const res = updateTableCell(doc(table), '#0', 1, 0, 'new');
-    const newId = res.doc.content[0].content[1].content[0].content[0].attrs.id;
-    // An empty id is treated as missing -> a fresh Docmost-style id is minted.
-    expect(newId).toMatch(/^[a-z0-9]{12}$/);
-    expect(newId).not.toBe('');
-  });
-});
-
-// ===========================================================================
-describe('buildOutline — exact 100 / 40 char truncation boundaries', () => {
-  it('does NOT truncate firstText at exactly 100 chars but DOES at 101', () => {
-    const at100 = buildOutline(doc(para('p', 'x'.repeat(100))));
-    expect(at100[0].firstText).toBe('x'.repeat(100)); // boundary: not cut
-    expect(at100[0].firstText.endsWith('…')).toBe(false);
-    const at101 = buildOutline(doc(para('p', 'x'.repeat(101))));
-    expect(at101[0].firstText).toBe('x'.repeat(100) + '…'); // first char over the cap
-  });
-
-  it('does NOT truncate a header cell at exactly 40 chars but DOES at 41', () => {
-    const tableAt40 = {
-      type: 'table',
-      content: [row([cell('tableHeader', 'h', 'y'.repeat(40))])],
-    };
-    expect(buildOutline(doc(tableAt40))[0].header).toEqual(['y'.repeat(40)]);
-    const tableAt41 = {
-      type: 'table',
-      content: [row([cell('tableHeader', 'h', 'y'.repeat(41))])],
-    };
-    expect(buildOutline(doc(tableAt41))[0].header).toEqual(['y'.repeat(40) + '…']);
-  });
-});
-
-// ===========================================================================
-describe('sanitizeForYjs / findUnstorableAttr — malformed marks array', () => {
-  const malformed = () =>
-    doc({
-      type: 'paragraph',
-      attrs: { id: 'p' },
-      content: [
-        text('x', [null, { type: 'link', attrs: { href: 'u', gone: undefined } }]),
-      ],
-    });
-
-  it('sanitizeForYjs skips a null mark and strips undefined on the real one', () => {
-    const res = sanitizeForYjs(malformed());
-    const marks = res.content[0].content[0].marks;
-    expect(marks[0]).toBeNull(); // the null mark is left untouched, not crashed on
-    expect(marks[1].attrs).toEqual({ href: 'u' }); // undefined dropped
-  });
-
-  it('findUnstorableAttr skips a null mark and reports the real undefined attr path', () => {
-    expect(findUnstorableAttr(malformed())).toBe(
-      'content[0].content[0].marks[1].attrs.gone (undefined)',
-    );
-  });
-});
-
-// ===========================================================================
-describe('makeFreshId — format and uniqueness (property, via insertTableRow)', () => {
-  it('every minted cell-paragraph id matches ^[a-z0-9]{12}$ and is globally unique', () => {
-    fc.assert(
-      fc.property(fc.integer({ min: 1, max: 5 }), (cols) => {
-        // Build an empty-id table of `cols` columns; the inserted row mints a
-        // fresh id per cell. The doc carries one pre-existing id to also assert
-        // the new ids never collide with it.
-        const headerCells = Array.from({ length: cols }, (_, i) =>
-          cell('tableHeader', `pre-${i}`, `H${i}`),
-        );
-        const d = doc({ type: 'table', content: [row(headerCells)] });
-        const res = insertTableRow(d, '#0', Array.from({ length: cols }, () => 'v'), 1);
-        const ids = res.doc.content[0].content[1].content.map(
-          (c: any) => c.content[0].attrs.id,
-        );
-        for (const id of ids) {
-          expect(id).toMatch(/^[a-z0-9]{12}$/);
-        }
-        // Unique within the new row AND distinct from the pre-existing ids.
-        expect(new Set(ids).size).toBe(ids.length);
-        for (const id of ids) {
-          expect(id.startsWith('pre-')).toBe(false);
-        }
-      }),
-      { numRuns: 100 },
-    );
-  });
-});
diff --git a/packages/git-sync/test/node-ops.test.ts b/packages/git-sync/test/node-ops.test.ts
deleted file mode 100644
index 52d302f1..00000000
--- a/packages/git-sync/test/node-ops.test.ts
+++ /dev/null
@@ -1,908 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  blockPlainText,
-  buildOutline,
-  getNodeByRef,
-  replaceNodeById,
-  deleteNodeById,
-  sanitizeForYjs,
-  findUnstorableAttr,
-  insertNodeRelative,
-  readTable,
-  insertTableRow,
-  deleteTableRow,
-  updateTableCell,
-} from '../src/lib/node-ops.js';
-
-// ---------------------------------------------------------------------------
-// Tiny ProseMirror/TipTap JSON fixture builders. These produce the exact plain
-// JSON shape Docmost uses: { type, attrs?, content?, text?, marks? }.
-// ---------------------------------------------------------------------------
-
-/** A text leaf node, optionally carrying marks. */
-function text(value: string, marks?: any[]): any {
-  const node: any = { type: 'text', text: value };
-  if (marks) node.marks = marks;
-  return node;
-}
-
-/** A paragraph block with an id and a single text child (or empty). */
-function para(id: string, value = ''): any {
-  return {
-    type: 'paragraph',
-    attrs: { id, indent: 0 },
-    content: value ? [text(value)] : [],
-  };
-}
-
-/** A heading block. */
-function heading(id: string, level: number, value: string): any {
-  return {
-    type: 'heading',
-    attrs: { id, level },
-    content: [text(value)],
-  };
-}
-
-/** A table cell (or header) wrapping a single paragraph; extra attrs merged in. */
-function cell(
-  type: 'tableCell' | 'tableHeader',
-  paraId: string | null,
-  value = '',
-  extraAttrs: Record<string, any> = {},
-): any {
-  const attrs = { colspan: 1, rowspan: 1, ...extraAttrs };
-  return {
-    type,
-    attrs,
-    content: paraId == null ? [] : [para(paraId, value)],
-  };
-}
-
-/** A table row. */
-function row(cells: any[]): any {
-  return { type: 'tableRow', content: cells };
-}
-
-/** A doc root with the given top-level blocks. */
-function doc(...content: any[]): any {
-  return { type: 'doc', content };
-}
-
-// ===========================================================================
-// blockPlainText
-// ===========================================================================
-describe('blockPlainText', () => {
-  it('returns the text of a plain text node', () => {
-    expect(blockPlainText(text('hello'))).toBe('hello');
-  });
-
-  it('concatenates text from nested containers', () => {
-    const node = {
-      type: 'paragraph',
-      content: [text('foo'), text('bar'), { type: 'span', content: [text('baz')] }],
-    };
-    expect(blockPlainText(node)).toBe('foobarbaz');
-  });
-
-  it('returns "" for nullish or non-object inputs', () => {
-    expect(blockPlainText(null)).toBe('');
-    expect(blockPlainText(undefined)).toBe('');
-    expect(blockPlainText('a string')).toBe('');
-    expect(blockPlainText(42)).toBe('');
-    expect(blockPlainText([text('x')])).toBe(''); // arrays are not objects here
-  });
-
-  it('uses BOTH text and nested content of a node, text first', () => {
-    const node = { type: 'weird', text: 'A', content: [text('B'), text('C')] };
-    expect(blockPlainText(node)).toBe('ABC');
-  });
-});
-
-// ===========================================================================
-// buildOutline
-// ===========================================================================
-describe('buildOutline', () => {
-  it('captures heading level, id and firstText', () => {
-    const outline = buildOutline(doc(heading('h1', 2, 'Title')));
-    expect(outline).toEqual([
-      { index: 0, type: 'heading', id: 'h1', firstText: 'Title', level: 2 },
-    ]);
-  });
-
-  it('reports table rows/cols and header texts (cols from row 0)', () => {
-    const table = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'a', 'H1'), cell('tableHeader', 'b', 'H2')]),
-        row([cell('tableCell', 'c', 'x'), cell('tableCell', 'd', 'y')]),
-      ],
-    };
-    const [entry] = buildOutline(doc(table));
-    expect(entry.type).toBe('table');
-    expect(entry.rows).toBe(2);
-    expect(entry.cols).toBe(2);
-    expect(entry.header).toEqual(['H1', 'H2']);
-  });
-
-  it('derives cols from row 0 for a ragged table', () => {
-    const table = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'a', 'H1')]), // row 0 has 1 col
-        row([cell('tableCell', 'b', 'x'), cell('tableCell', 'c', 'y')]), // 2 cols
-      ],
-    };
-    const [entry] = buildOutline(doc(table));
-    expect(entry.rows).toBe(2);
-    expect(entry.cols).toBe(1); // cols reflect ONLY row 0
-    expect(entry.header).toEqual(['H1']);
-  });
-
-  it('reports item count for any *List block', () => {
-    const list = {
-      type: 'bulletList',
-      attrs: { id: 'l1' },
-      content: [{ type: 'listItem' }, { type: 'listItem' }, { type: 'listItem' }],
-    };
-    const [entry] = buildOutline(doc(list));
-    expect(entry.type).toBe('bulletList');
-    expect(entry.items).toBe(3);
-  });
-
-  it('returns [] for an empty or non-object doc', () => {
-    expect(buildOutline(null)).toEqual([]);
-    expect(buildOutline({ type: 'doc' })).toEqual([]); // no content array
-    expect(buildOutline({ type: 'doc', content: [] })).toEqual([]);
-    expect(buildOutline('nope')).toEqual([]);
-  });
-
-  it('falls back to null id when a block has no attrs.id', () => {
-    const [entry] = buildOutline(doc({ type: 'paragraph', content: [text('hi')] }));
-    expect(entry.id).toBeNull();
-    expect(entry.firstText).toBe('hi');
-  });
-
-  it('truncates firstText to 100 chars with an ellipsis', () => {
-    const long = 'x'.repeat(150);
-    const [entry] = buildOutline(doc(para('p', long)));
-    expect(entry.firstText).toBe('x'.repeat(100) + '…');
-    expect(entry.firstText.length).toBe(101); // 100 chars + ellipsis
-  });
-
-  it('truncates table header cell text to 40 chars', () => {
-    const long = 'y'.repeat(60);
-    const table = {
-      type: 'table',
-      content: [row([cell('tableHeader', 'a', long)])],
-    };
-    const [entry] = buildOutline(doc(table));
-    expect(entry.header).toEqual(['y'.repeat(40) + '…']);
-  });
-});
-
-// ===========================================================================
-// getNodeByRef
-// ===========================================================================
-describe('getNodeByRef', () => {
-  it('resolves a top-level block by #n', () => {
-    const d = doc(para('p0', 'zero'), para('p1', 'one'));
-    const hit = getNodeByRef(d, '#1');
-    expect(hit).not.toBeNull();
-    expect(hit!.path).toEqual([1]);
-    expect(hit!.type).toBe('paragraph');
-    expect(hit!.node.attrs.id).toBe('p1');
-  });
-
-  it('returns null for #n out of range', () => {
-    const d = doc(para('p0'));
-    expect(getNodeByRef(d, '#5')).toBeNull();
-    expect(getNodeByRef(d, '#1')).toBeNull();
-  });
-
-  it('finds a nested node by id with the correct path', () => {
-    const table = {
-      type: 'table',
-      content: [row([cell('tableCell', 'deep', 'found me')])],
-    };
-    const d = doc(para('p0'), table);
-    const hit = getNodeByRef(d, 'deep');
-    expect(hit).not.toBeNull();
-    // doc.content[1] -> table.content[0] -> row.content[0] -> cell.content[0]
-    expect(hit!.path).toEqual([1, 0, 0, 0]);
-    expect(hit!.type).toBe('paragraph');
-  });
-
-  it('returns null when the id is not found', () => {
-    const d = doc(para('p0'));
-    expect(getNodeByRef(d, 'missing')).toBeNull();
-  });
-
-  it('returns the FIRST node for a duplicate id', () => {
-    const d = doc(para('dup', 'first'), para('dup', 'second'));
-    const hit = getNodeByRef(d, 'dup');
-    expect(hit!.path).toEqual([0]);
-    expect(blockPlainText(hit!.node)).toBe('first');
-  });
-
-  it('returns null for a non-object doc', () => {
-    expect(getNodeByRef(null, '#0')).toBeNull();
-    expect(getNodeByRef('x', 'id')).toBeNull();
-  });
-
-  it('returns a CLONE — mutating it does not touch the input doc', () => {
-    const d = doc(para('p0', 'orig'));
-    const snapshot = structuredClone(d);
-    const hit = getNodeByRef(d, 'p0');
-    hit!.node.attrs.id = 'mutated';
-    hit!.node.content.push(text('extra'));
-    expect(d).toEqual(snapshot);
-  });
-});
-
-// ===========================================================================
-// replaceNodeById
-// ===========================================================================
-describe('replaceNodeById', () => {
-  const newNode = () => ({ type: 'paragraph', attrs: { id: 'new' }, content: [text('NEW')] });
-
-  it('reports replaced:0 when nothing matches', () => {
-    const d = doc(para('p0'));
-    const res = replaceNodeById(d, 'missing', newNode());
-    expect(res.replaced).toBe(0);
-    expect(res.doc).toEqual(d);
-  });
-
-  it('replaces a single match', () => {
-    const d = doc(para('p0', 'old'), para('p1'));
-    const res = replaceNodeById(d, 'p0', newNode());
-    expect(res.replaced).toBe(1);
-    expect(res.doc.content[0]).toEqual(newNode());
-    expect(res.doc.content[1].attrs.id).toBe('p1');
-  });
-
-  it('replaces N matches', () => {
-    const d = doc(para('dup', 'a'), para('keep'), para('dup', 'b'));
-    const res = replaceNodeById(d, 'dup', newNode());
-    expect(res.replaced).toBe(2);
-    expect(res.doc.content[0]).toEqual(newNode());
-    expect(res.doc.content[1].attrs.id).toBe('keep');
-    expect(res.doc.content[2]).toEqual(newNode());
-  });
-
-  it('replaces a nested match inside a table cell', () => {
-    const table = {
-      type: 'table',
-      content: [row([cell('tableCell', 'inner', 'x')])],
-    };
-    const d = doc(table);
-    const res = replaceNodeById(d, 'inner', newNode());
-    expect(res.replaced).toBe(1);
-    expect(res.doc.content[0].content[0].content[0].content[0]).toEqual(newNode());
-  });
-
-  it('does NOT recurse into the substituted node', () => {
-    // The replacement itself carries the same id; it must not be re-replaced.
-    const d = doc(para('target'));
-    const replacement = { type: 'paragraph', attrs: { id: 'target' }, content: [text('R')] };
-    const res = replaceNodeById(d, 'target', replacement);
-    expect(res.replaced).toBe(1); // not 2 — no recursion into the new node
-  });
-
-  it('gives each match a SEPARATE clone', () => {
-    const d = doc(para('dup'), para('dup'));
-    const res = replaceNodeById(d, 'dup', newNode());
-    res.doc.content[0].content.push(text('mutated'));
-    // The second replacement must be untouched.
-    expect(res.doc.content[1]).toEqual(newNode());
-  });
-
-  it('does not mutate the input doc', () => {
-    const d = doc(para('p0', 'old'));
-    const snapshot = structuredClone(d);
-    replaceNodeById(d, 'p0', newNode());
-    expect(d).toEqual(snapshot);
-  });
-});
-
-// ===========================================================================
-// deleteNodeById
-// ===========================================================================
-describe('deleteNodeById', () => {
-  it('reports deleted:0 when nothing matches', () => {
-    const d = doc(para('p0'));
-    const res = deleteNodeById(d, 'missing');
-    expect(res.deleted).toBe(0);
-    expect(res.doc).toEqual(d);
-  });
-
-  it('deletes a single match', () => {
-    const d = doc(para('p0'), para('p1'), para('p2'));
-    const res = deleteNodeById(d, 'p1');
-    expect(res.deleted).toBe(1);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'p2']);
-  });
-
-  it('deletes N matches', () => {
-    const d = doc(para('dup'), para('keep'), para('dup'));
-    const res = deleteNodeById(d, 'dup');
-    expect(res.deleted).toBe(2);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['keep']);
-  });
-
-  it('deletes a nested node and preserves sibling order', () => {
-    // A callout-style container holding three paragraph children; deleting the
-    // middle one must leave the outer siblings in order.
-    const callout = {
-      type: 'callout',
-      attrs: { id: 'cal' },
-      content: [para('a', 'A'), para('b', 'B'), para('c', 'C')],
-    };
-    const d = doc(para('outer0'), callout, para('outer1'));
-    const res = deleteNodeById(d, 'b');
-    expect(res.deleted).toBe(1);
-    // Inner siblings keep their order.
-    const innerIds = res.doc.content[1].content.map((cl: any) => cl.attrs.id);
-    expect(innerIds).toEqual(['a', 'c']);
-    // Outer siblings are untouched and in order.
-    const outerIds = res.doc.content.map((cl: any) => cl.attrs.id);
-    expect(outerIds).toEqual(['outer0', 'cal', 'outer1']);
-  });
-
-  it('does not mutate the input doc (deep-equal before/after)', () => {
-    const d = doc(para('p0'), para('p1'));
-    const snapshot = structuredClone(d);
-    deleteNodeById(d, 'p0');
-    expect(d).toEqual(snapshot);
-  });
-});
-
-// ===========================================================================
-// sanitizeForYjs
-// ===========================================================================
-describe('sanitizeForYjs', () => {
-  it('strips undefined keys from node.attrs', () => {
-    const d = doc({ type: 'paragraph', attrs: { id: 'p', gone: undefined, kept: 1 } });
-    const res = sanitizeForYjs(d);
-    expect('gone' in res.content[0].attrs).toBe(false);
-    expect(res.content[0].attrs).toEqual({ id: 'p', kept: 1 });
-  });
-
-  it('strips undefined keys from mark.attrs', () => {
-    const d = doc({
-      type: 'paragraph',
-      attrs: { id: 'p' },
-      content: [text('hi', [{ type: 'link', attrs: { href: 'u', gone: undefined } }])],
-    });
-    const res = sanitizeForYjs(d);
-    expect('gone' in res.content[0].content[0].marks[0].attrs).toBe(false);
-    expect(res.content[0].content[0].marks[0].attrs).toEqual({ href: 'u' });
-  });
-
-  it('PRESERVES null, false, 0 and "" (only undefined is dropped)', () => {
-    const d = doc({
-      type: 'paragraph',
-      attrs: { a: null, b: false, c: 0, d: '', e: undefined },
-    });
-    const res = sanitizeForYjs(d);
-    expect(res.content[0].attrs).toEqual({ a: null, b: false, c: 0, d: '' });
-  });
-
-  it('recurses into nested content', () => {
-    const d = doc({
-      type: 'table',
-      content: [row([cell('tableCell', null, '', { gone: undefined, colwidth: null })])],
-    });
-    const res = sanitizeForYjs(d);
-    const cellAttrs = res.content[0].content[0].content[0].attrs;
-    expect('gone' in cellAttrs).toBe(false);
-    expect(cellAttrs.colwidth).toBeNull();
-  });
-
-  it('does not mutate the input doc', () => {
-    const d = doc({ type: 'paragraph', attrs: { id: 'p', gone: undefined } });
-    // structuredClone preserves an explicit `undefined` value key, so snapshot it.
-    const snapshot = structuredClone(d);
-    sanitizeForYjs(d);
-    expect(d).toEqual(snapshot);
-    expect('gone' in d.content[0].attrs).toBe(true); // still present on the input
-  });
-});
-
-// ===========================================================================
-// findUnstorableAttr
-// ===========================================================================
-describe('findUnstorableAttr', () => {
-  it('returns null for a fully storable doc', () => {
-    const d = doc(para('p0', 'clean'));
-    expect(findUnstorableAttr(d)).toBeNull();
-  });
-
-  it('detects an undefined node attr with its path and kind', () => {
-    const d = doc(para('a'), para('b'), { type: 'paragraph', attrs: { id: 'c', x: undefined } });
-    expect(findUnstorableAttr(d)).toBe('content[2].attrs.x (undefined)');
-  });
-
-  it('detects a function attr', () => {
-    const d = doc({ type: 'paragraph', attrs: { fn: () => 1 } });
-    expect(findUnstorableAttr(d)).toBe('content[0].attrs.fn (function)');
-  });
-
-  it('detects a symbol attr', () => {
-    const d = doc({ type: 'paragraph', attrs: { s: Symbol('x') } });
-    expect(findUnstorableAttr(d)).toBe('content[0].attrs.s (symbol)');
-  });
-
-  it('detects a bigint attr', () => {
-    const d = doc({ type: 'paragraph', attrs: { big: 10n } });
-    expect(findUnstorableAttr(d)).toBe('content[0].attrs.big (bigint)');
-  });
-
-  it('detects an unstorable mark attr with the marks[i] path', () => {
-    const d = doc({
-      type: 'paragraph',
-      attrs: { id: 'p' },
-      content: [text('hi'), text('yo', [{ type: 'link', attrs: { x: undefined } }])],
-    });
-    expect(findUnstorableAttr(d)).toBe('content[0].content[1].marks[0].attrs.x (undefined)');
-  });
-
-  it('returns the FIRST hit only', () => {
-    const d = doc(
-      { type: 'paragraph', attrs: { first: undefined } },
-      { type: 'paragraph', attrs: { second: undefined } },
-    );
-    expect(findUnstorableAttr(d)).toBe('content[0].attrs.first (undefined)');
-  });
-
-  it('returns null for a non-object doc', () => {
-    expect(findUnstorableAttr(null)).toBeNull();
-    expect(findUnstorableAttr('x')).toBeNull();
-  });
-});
-
-// ===========================================================================
-// insertNodeRelative
-// ===========================================================================
-describe('insertNodeRelative', () => {
-  const block = (id: string, value = '') => para(id, value);
-
-  it('appends a node to top-level content', () => {
-    const d = doc(para('p0'));
-    const res = insertNodeRelative(d, block('new', 'N'), { position: 'append' });
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new']);
-  });
-
-  it('creates a content array when appending to a doc without one', () => {
-    const res = insertNodeRelative({ type: 'doc' }, block('new'), { position: 'append' });
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['new']);
-  });
-
-  it('inserts before a node by id (top level)', () => {
-    const d = doc(para('p0'), para('p1'));
-    const res = insertNodeRelative(d, block('new'), { position: 'before', anchorNodeId: 'p1' });
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
-  });
-
-  it('inserts after a node by id (top level)', () => {
-    const d = doc(para('p0'), para('p1'));
-    const res = insertNodeRelative(d, block('new'), { position: 'after', anchorNodeId: 'p0' });
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
-  });
-
-  it('inserts before a NESTED anchor by id, into its own parent content', () => {
-    const table = {
-      type: 'table',
-      content: [row([cell('tableCell', 'inner', 'x')])],
-    };
-    const d = doc(table);
-    const res = insertNodeRelative(d, block('new'), { position: 'before', anchorNodeId: 'inner' });
-    expect(res.inserted).toBe(true);
-    // The new (non-structural) node is spliced into the cell's content before the paragraph.
-    const cellContent = res.doc.content[0].content[0].content[0].content;
-    expect(cellContent.map((c: any) => c.attrs.id)).toEqual(['new', 'inner']);
-  });
-
-  it('inserts by anchorText against top-level blocks (substring match)', () => {
-    const d = doc(para('p0', 'hello world'), para('p1', 'other'));
-    const res = insertNodeRelative(d, block('new'), { position: 'after', anchorText: 'world' });
-    expect(res.inserted).toBe(true);
-    expect(res.doc.content.map((c: any) => c.attrs.id)).toEqual(['p0', 'new', 'p1']);
-  });
-
-  it('returns inserted:false when the anchor cannot be resolved', () => {
-    const d = doc(para('p0'));
-    const byId = insertNodeRelative(d, block('new'), { position: 'after', anchorNodeId: 'nope' });
-    expect(byId.inserted).toBe(false);
-    expect(byId.doc).toEqual(d);
-
-    const byText = insertNodeRelative(d, block('new'), { position: 'before', anchorText: 'zzz' });
-    expect(byText.inserted).toBe(false);
-    expect(byText.doc).toEqual(d);
-  });
-
-  it('routes a structural tableRow to the nearest table container', () => {
-    const table = {
-      type: 'table',
-      content: [
-        row([cell('tableCell', 'r0c0', 'A')]),
-        row([cell('tableCell', 'r1c0', 'B')]),
-      ],
-    };
-    const d = doc(table);
-    const newRow = row([cell('tableCell', 'rNew', 'NEW')]);
-    // Anchor on a cell paragraph inside row 0; "after" should put the row after row 0.
-    const res = insertNodeRelative(d, newRow, { position: 'after', anchorNodeId: 'r0c0' });
-    expect(res.inserted).toBe(true);
-    const rowFirstCellId = (r: any) => r.content[0].content[0].attrs.id;
-    expect(res.doc.content[0].content.map(rowFirstCellId)).toEqual(['r0c0', 'rNew', 'r1c0']);
-  });
-
-  it('throws when appending a structural node at the top level', () => {
-    const d = doc(para('p0'));
-    const newRow = row([cell('tableCell', 'x', 'X')]);
-    expect(() => insertNodeRelative(d, newRow, { position: 'append' })).toThrow(
-      /cannot append a tableRow at the top level/,
-    );
-  });
-
-  it('throws when a structural anchor is not inside the required container', () => {
-    // Anchor resolves to a top-level paragraph that is not inside any table.
-    const d = doc(para('p0', 'loose'));
-    const newRow = row([cell('tableCell', 'x', 'X')]);
-    expect(() =>
-      insertNodeRelative(d, newRow, { position: 'after', anchorNodeId: 'p0' }),
-    ).toThrow(/the anchor is not inside a table/);
-  });
-
-  it('honours offset: before vs after place the node on the correct side', () => {
-    const d = doc(para('a'), para('b'), para('c'));
-    const before = insertNodeRelative(d, block('N'), { position: 'before', anchorNodeId: 'b' });
-    expect(before.doc.content.map((c: any) => c.attrs.id)).toEqual(['a', 'N', 'b', 'c']);
-    const after = insertNodeRelative(d, block('N'), { position: 'after', anchorNodeId: 'b' });
-    expect(after.doc.content.map((c: any) => c.attrs.id)).toEqual(['a', 'b', 'N', 'c']);
-  });
-
-  it('does not mutate the input doc or the node argument', () => {
-    const d = doc(para('p0'));
-    const dSnapshot = structuredClone(d);
-    const node = block('new', 'N');
-    const nodeSnapshot = structuredClone(node);
-    insertNodeRelative(d, node, { position: 'append' });
-    expect(d).toEqual(dSnapshot);
-    expect(node).toEqual(nodeSnapshot);
-  });
-});
-
-// ===========================================================================
-// readTable
-// ===========================================================================
-describe('readTable', () => {
-  const makeTable = () => ({
-    type: 'table',
-    content: [
-      row([cell('tableHeader', 'h0', 'H0'), cell('tableHeader', 'h1', 'H1')]),
-      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
-    ],
-  });
-
-  it('reads a table by #n', () => {
-    const d = doc(para('p0'), makeTable());
-    const res = readTable(d, '#1');
-    expect(res).not.toBeNull();
-    expect(res!.rows).toBe(2);
-    expect(res!.cols).toBe(2);
-    expect(res!.cells).toEqual([['H0', 'H1'], ['A', 'B']]);
-    expect(res!.cellIds).toEqual([['h0', 'h1'], ['c0', 'c1']]);
-    expect(res!.path).toEqual([1]);
-  });
-
-  it('climbs from an inner paragraph id up to the table', () => {
-    const d = doc(makeTable());
-    const res = readTable(d, 'c1'); // id of a paragraph inside a data cell
-    expect(res).not.toBeNull();
-    expect(res!.path).toEqual([0]);
-    expect(res!.cells).toEqual([['H0', 'H1'], ['A', 'B']]);
-  });
-
-  it('reports per-row widths via cells for a ragged table', () => {
-    const table = {
-      type: 'table',
-      content: [
-        row([cell('tableHeader', 'h0', 'H0')]),
-        row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
-      ],
-    };
-    const res = readTable(doc(table), '#0');
-    expect(res!.cols).toBe(1); // cols comes from row 0
-    expect(res!.cells).toEqual([['H0'], ['A', 'B']]); // actual per-row widths preserved
-    expect(res!.cellIds).toEqual([['h0'], ['c0', 'c1']]);
-  });
-
-  it('reports null cellId for an empty cell with no paragraph', () => {
-    const table = {
-      type: 'table',
-      content: [row([cell('tableCell', null), cell('tableCell', 'c1', 'B')])],
-    };
-    const res = readTable(doc(table), '#0');
-    expect(res!.cells).toEqual([['', 'B']]);
-    expect(res!.cellIds).toEqual([[null, 'c1']]);
-  });
-
-  it('returns null when the ref matches no table', () => {
-    const d = doc(para('p0'));
-    expect(readTable(d, '#0')).toBeNull(); // #0 is a paragraph, not a table
-    expect(readTable(d, 'missing')).toBeNull();
-    expect(readTable(d, 'p0')).toBeNull(); // id found but no enclosing table
-  });
-});
-
-// ===========================================================================
-// insertTableRow
-// ===========================================================================
-describe('insertTableRow', () => {
-  const makeTable = () => ({
-    type: 'table',
-    content: [
-      row([
-        cell('tableHeader', 'h0', 'H0', { colwidth: [120] }),
-        cell('tableHeader', 'h1', 'H1', { colwidth: [240] }),
-      ]),
-      row([cell('tableCell', 'c0', 'A'), cell('tableCell', 'c1', 'B')]),
-    ],
-  });
-
-  /** First-paragraph ids of every cell in a row, for ordering assertions. */
-  const rowCellParaIds = (r: any): (string | undefined)[] =>
-    r.content.map((c: any) => c.content[0]?.attrs?.id);
-  /** Cell text of a row. */
-  const rowTexts = (r: any): string[] =>
-    r.content.map((c: any) => blockPlainText(c));
-
-  it('appends a row when index is omitted', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y']);
-    expect(res.inserted).toBe(true);
-    const rows = res.doc.content[0].content;
-    expect(rows.length).toBe(3);
-    expect(rowTexts(rows[2])).toEqual(['X', 'Y']);
-  });
-
-  it('splices at a middle index', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y'], 1);
-    const rows = res.doc.content[0].content;
-    expect(rows.length).toBe(3);
-    expect(rowTexts(rows[1])).toEqual(['X', 'Y']); // new row at index 1
-    expect(rowTexts(rows[2])).toEqual(['A', 'B']); // old data row pushed down
-  });
-
-  it('splices at the end index', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y'], 2); // rows == 2, valid end index
-    const rows = res.doc.content[0].content;
-    expect(rows.length).toBe(3);
-    expect(rowTexts(rows[2])).toEqual(['X', 'Y']);
-  });
-
-  it('APPENDS (does not throw) for an out-of-range index', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y'], 99);
-    const rows = res.doc.content[0].content;
-    expect(res.inserted).toBe(true);
-    expect(rows.length).toBe(3);
-    expect(rowTexts(rows[2])).toEqual(['X', 'Y']); // appended at the end
-  });
-
-  it('throws when given more cells than columns', () => {
-    const d = doc(makeTable());
-    expect(() => insertTableRow(d, '#0', ['X', 'Y', 'Z'])).toThrow(
-      /got 3 cell\(s\) but the table has 2 column\(s\)/,
-    );
-  });
-
-  it('pads a short row to the column count', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['only']);
-    const rows = res.doc.content[0].content;
-    expect(rowTexts(rows[2])).toEqual(['only', '']); // padded with empty cell
-  });
-
-  it('copies colwidth from the header row for each column', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y']);
-    const newRow = res.doc.content[0].content[2];
-    expect(newRow.content[0].attrs.colwidth).toEqual([120]);
-    expect(newRow.content[1].attrs.colwidth).toEqual([240]);
-    expect(newRow.content[0].attrs).toMatchObject({ colspan: 1, rowspan: 1 });
-  });
-
-  it('index 0 inherits the header cell TYPE', () => {
-    const d = doc(makeTable());
-    const res = insertTableRow(d, '#0', ['X', 'Y'], 0);
-    const newRow = res.doc.content[0].content[0];
-    expect(newRow.content.every((c: any) => c.type === 'tableHeader')).toBe(true);
-    // A non-zero index produces plain data cells instead.
-    const res2 = insertTableRow(d, '#0', ['X', 'Y'], 1);
-    const dataRow = res2.doc.content[0].content[1];
-    expect(dataRow.content.every((c: any) => c.type === 'tableCell')).toBe(true);
-  });
-
-  it('mints unique, well-formed paragraph ids for new cells', () => {
-    const d = doc(makeTable());
-    const existing = new Set(['h0', 'h1', 'c0', 'c1']);
-    const res = insertTableRow(d, '#0', ['X', 'Y']);
-    const newRow = res.doc.content[0].content[2];
-    const ids = rowCellParaIds(newRow) as string[];
-    for (const id of ids) {
-      expect(typeof id).toBe('string');
-      expect(id).toMatch(/^[a-z0-9]{12}$/); // Docmost-style 12-char id
-      expect(existing.has(id)).toBe(false); // unique vs pre-existing ids
-    }
-    expect(new Set(ids).size).toBe(ids.length); // unique within the row
-  });
-
-  it('returns inserted:false when the table cannot be located', () => {
-    const d = doc(para('p0'));
-    const res = insertTableRow(d, 'missing', ['X']);
-    expect(res.inserted).toBe(false);
-    expect(res.doc).toEqual(d);
-  });
-
-  it('does not mutate the input doc', () => {
-    const d = doc(makeTable());
-    const snapshot = structuredClone(d);
-    insertTableRow(d, '#0', ['X', 'Y'], 1);
-    expect(d).toEqual(snapshot);
-  });
-});
-
-// ===========================================================================
-// deleteTableRow
-// ===========================================================================
-describe('deleteTableRow', () => {
-  const makeTable = () => ({
-    type: 'table',
-    content: [
-      row([cell('tableHeader', 'h0', 'H')]),
-      row([cell('tableCell', 'c0', 'A')]),
-      row([cell('tableCell', 'c1', 'B')]),
-    ],
-  });
-  const firstId = (r: any) => r.content[0].content[0].attrs.id;
-
-  it('deletes a middle row and preserves siblings', () => {
-    const d = doc(makeTable());
-    const res = deleteTableRow(d, '#0', 1);
-    expect(res.deleted).toBe(true);
-    expect(res.doc.content[0].content.map(firstId)).toEqual(['h0', 'c1']);
-  });
-
-  it('deletes the first row', () => {
-    const d = doc(makeTable());
-    const res = deleteTableRow(d, '#0', 0);
-    expect(res.doc.content[0].content.map(firstId)).toEqual(['c0', 'c1']);
-  });
-
-  it('deletes the last row', () => {
-    const d = doc(makeTable());
-    const res = deleteTableRow(d, '#0', 2);
-    expect(res.doc.content[0].content.map(firstId)).toEqual(['h0', 'c0']);
-  });
-
-  it('throws on an out-of-range index', () => {
-    const d = doc(makeTable());
-    expect(() => deleteTableRow(d, '#0', 99)).toThrow(/out of range/);
-    expect(() => deleteTableRow(d, '#0', -1)).toThrow(/out of range/);
-  });
-
-  it('throws when asked to delete the only row', () => {
-    const single = {
-      type: 'table',
-      content: [row([cell('tableCell', 'c0', 'A')])],
-    };
-    expect(() => deleteTableRow(doc(single), '#0', 0)).toThrow(
-      /refusing to delete the only row/,
-    );
-  });
-
-  it('returns deleted:false when the table cannot be located', () => {
-    const d = doc(para('p0'));
-    const res = deleteTableRow(d, 'missing', 0);
-    expect(res.deleted).toBe(false);
-    expect(res.doc).toEqual(d);
-  });
-
-  it('does not mutate the input doc', () => {
-    const d = doc(makeTable());
-    const snapshot = structuredClone(d);
-    deleteTableRow(d, '#0', 1);
-    expect(d).toEqual(snapshot);
-  });
-});
-
-// ===========================================================================
-// updateTableCell
-// ===========================================================================
-describe('updateTableCell', () => {
-  const makeTable = () => ({
-    type: 'table',
-    content: [
-      row([cell('tableHeader', 'h0', 'H0'), cell('tableHeader', 'h1', 'H1')]),
-      row([
-        cell('tableCell', 'c0', 'A', { colspan: 2, rowspan: 3, colwidth: [200] }),
-        cell('tableCell', 'c1', 'B'),
-      ]),
-    ],
-  });
-
-  it('sets the cell text', () => {
-    const d = doc(makeTable());
-    const res = updateTableCell(d, '#0', 1, 1, 'NEW');
-    expect(res.updated).toBe(true);
-    expect(blockPlainText(res.doc.content[0].content[1].content[1])).toBe('NEW');
-  });
-
-  it('REUSES the existing first-paragraph id', () => {
-    const d = doc(makeTable());
-    const res = updateTableCell(d, '#0', 1, 0, 'changed');
-    const para0 = res.doc.content[0].content[1].content[0].content[0];
-    expect(para0.attrs.id).toBe('c0'); // critical: id reused, not regenerated
-    expect(para0.content[0].text).toBe('changed');
-  });
-
-  it('mints a fresh id when the cell had no paragraph', () => {
-    const table = {
-      type: 'table',
-      content: [row([cell('tableCell', null), cell('tableCell', 'c1', 'B')])],
-    };
-    const d = doc(table);
-    const res = updateTableCell(d, '#0', 0, 0, 'now has text');
-    const newPara = res.doc.content[0].content[0].content[0].content[0];
-    expect(typeof newPara.attrs.id).toBe('string');
-    expect(newPara.attrs.id).toMatch(/^[a-z0-9]{12}$/);
-    expect(newPara.attrs.id).not.toBe('c1'); // unique vs existing ids
-    expect(newPara.content[0].text).toBe('now has text');
-  });
-
-  it('PRESERVES the cell colspan/rowspan/colwidth (only content replaced)', () => {
-    const d = doc(makeTable());
-    const res = updateTableCell(d, '#0', 1, 0, 'x');
-    const cellNode = res.doc.content[0].content[1].content[0];
-    expect(cellNode.attrs).toEqual({ colspan: 2, rowspan: 3, colwidth: [200] });
-  });
-
-  it('throws when row or col is out of range', () => {
-    const d = doc(makeTable());
-    expect(() => updateTableCell(d, '#0', 5, 0, 'x')).toThrow(/out of range/);
-    expect(() => updateTableCell(d, '#0', 0, 5, 'x')).toThrow(/out of range/);
-    expect(() => updateTableCell(d, '#0', -1, 0, 'x')).toThrow(/out of range/);
-  });
-
-  it('an empty string yields an empty paragraph content array', () => {
-    const d = doc(makeTable());
-    const res = updateTableCell(d, '#0', 1, 1, '');
-    const cellPara = res.doc.content[0].content[1].content[1].content[0];
-    expect(cellPara.type).toBe('paragraph');
-    expect(cellPara.content).toEqual([]); // empty string -> empty content
-    expect(cellPara.attrs.id).toBe('c1'); // id still reused
-  });
-
-  it('returns updated:false when the table cannot be located', () => {
-    const d = doc(para('p0'));
-    const res = updateTableCell(d, 'missing', 0, 0, 'x');
-    expect(res.updated).toBe(false);
-    expect(res.doc).toEqual(d);
-  });
-
-  it('does not mutate the input doc', () => {
-    const d = doc(makeTable());
-    const snapshot = structuredClone(d);
-    updateTableCell(d, '#0', 1, 1, 'NEW');
-    expect(d).toEqual(snapshot);
-  });
-});
diff --git a/packages/git-sync/test/page-file.test.ts b/packages/git-sync/test/page-file.test.ts
deleted file mode 100644
index 9cd54efc..00000000
--- a/packages/git-sync/test/page-file.test.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { parsePageFile, serializePageFile } from "../src/lib/page-file";
-
-describe("page-file thin format", () => {
-  it("round-trips id frontmatter + clean body", () => {
-    const text = serializePageFile("019ef6fc-2638", "# Hello\n\nbody text");
-    expect(text.startsWith("---\ngitmost_id: 019ef6fc-2638\n---\n")).toBe(true);
-    const { id, body } = parsePageFile(text);
-    expect(id).toBe("019ef6fc-2638");
-    expect(body).toBe("# Hello\n\nbody text");
-  });
-
-  it("serialization is deterministic (byte-identical for the same input)", () => {
-    expect(serializePageFile("p", "x")).toBe(serializePageFile("p", "x"));
-  });
-
-  it("reads id from frontmatter with quotes / extra fields", () => {
-    expect(parsePageFile('---\ngitmost_id: "abc"\ntitle: ignored\n---\nbody').id).toBe("abc");
-    expect(parsePageFile("---\ngitmost_id: 'xyz'\n---\nbody").id).toBe("xyz");
-  });
-
-
-  it("ADOPT: a plain hand-written file has no id and keeps its whole body", () => {
-    const { id, body } = parsePageFile("# Just a note\n\nwritten in Obsidian");
-    expect(id).toBeNull();
-    expect(body).toBe("# Just a note\n\nwritten in Obsidian");
-  });
-
-  it("tolerates empty / whitespace input", () => {
-    expect(parsePageFile("").id).toBeNull();
-    expect(parsePageFile("   \n  ").body).toBe("");
-  });
-});
diff --git a/packages/git-sync/test/read-existing.test.ts b/packages/git-sync/test/read-existing.test.ts
index 4d2fabd1..af72d159 100644
--- a/packages/git-sync/test/read-existing.test.ts
+++ b/packages/git-sync/test/read-existing.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { readExisting } from '../src/engine/pull';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 // R-Pull-1 (test-strategy report §5): `readExisting` now takes injectable IO
 // (`listTracked` / `readFile`), so its parsing + skip rules are unit-testable
diff --git a/packages/git-sync/test/redteam-converter.test.ts b/packages/git-sync/test/redteam-converter.test.ts
deleted file mode 100644
index a6f88f68..00000000
--- a/packages/git-sync/test/redteam-converter.test.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-import { describe, expect, it } from 'vitest';
-// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
-// pulls in collaboration.ts and mutates the global DOM at import time), matching
-// the other converter unit tests. markdownToProseMirror is imported for the
-// round-trip cases; loading it mutates the global DOM via jsdom (required for
-// @tiptap/html's generateJSON under Node) — this is expected.
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-
-// ---------------------------------------------------------------------------
-// #1 editor-ext atoms dropped: the `default` branch (markdown-converter.ts
-// ~584-586) collapses unknown atoms to "" by mapping their (empty) children.
-// ---------------------------------------------------------------------------
-describe('#1 editor-ext atoms dropped', () => {
-  it('preserves an inline status atom text', () => {
-    const d = doc({
-      type: 'paragraph',
-      content: [{ type: 'status', attrs: { text: 'Done' } }],
-    });
-    expect(convertProseMirrorToMarkdown(d)).toContain('Done');
-  });
-
-  it('preserves a block htmlEmbed atom', () => {
-    const d = doc({ type: 'htmlEmbed', attrs: { source: '<b>hi</b>' } });
-    expect(convertProseMirrorToMarkdown(d)).not.toBe('');
-  });
-
-  it('preserves a footnoteReference atom', () => {
-    const d = doc({
-      type: 'paragraph',
-      content: [{ type: 'footnoteReference', attrs: { id: 'fn1', referenceNumber: 1 } }],
-    });
-    expect(convertProseMirrorToMarkdown(d)).not.toBe('');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// #2 top-level image attrs lost: a top-level image emits markdown ![](src),
-// which carries no width/height/align/attachmentId.
-// ---------------------------------------------------------------------------
-describe('#2 top-level image attrs lost', () => {
-  it('keeps width through export and re-import', async () => {
-    const d = doc({
-      type: 'image',
-      attrs: { src: '/files/x.png', width: '320', height: '200', align: 'right', attachmentId: 'a1' },
-    });
-    const md = convertProseMirrorToMarkdown(d);
-    expect(md).toContain('320');
-    const back = await markdownToProseMirror(md);
-    expect(back.content[0].attrs.width).toBe('320');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// #3 code-fence corruption: a code block whose TEXT contains a ``` fence must
-// be emitted with a wider outer fence so the inner fence survives.
-// ---------------------------------------------------------------------------
-describe('#3 code-fence corruption', () => {
-  it('round-trips a code block containing an inner fence', async () => {
-    const code = '```js\nfoo()\n```';
-    const d = doc({
-      type: 'codeBlock',
-      attrs: { language: '' },
-      content: [{ type: 'text', text: code }],
-    });
-    const md1 = convertProseMirrorToMarkdown(d);
-    const back = await markdownToProseMirror(md1);
-    const md2 = convertProseMirrorToMarkdown(back);
-    expect(md2).toBe(md1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// #16 depth guard: deep recursion in processNode overflows the stack (today a
-// RangeError) instead of being guarded.
-// ---------------------------------------------------------------------------
-describe('#16 depth guard', () => {
-  it('does not throw on a deeply nested blockquote doc', () => {
-    const DEPTH = 50000;
-    let node: any = { type: 'paragraph', content: [{ type: 'text', text: 'x' }] };
-    for (let i = 0; i < DEPTH; i++) {
-      node = { type: 'blockquote', content: [node] };
-    }
-    const d = doc(node);
-    expect(() => convertProseMirrorToMarkdown(d)).not.toThrow();
-  });
-});
diff --git a/packages/git-sync/test/redteam-layout-title.test.ts b/packages/git-sync/test/redteam-layout-title.test.ts
index 3473145d..e505557c 100644
--- a/packages/git-sync/test/redteam-layout-title.test.ts
+++ b/packages/git-sync/test/redteam-layout-title.test.ts
@@ -6,7 +6,7 @@ import type {
   MetaSide,
   RenameMoveAction,
 } from '../src/engine/push.js';
-import type { DocmostMdMeta } from '../src/lib/index.js';
+import type { DocmostMdMeta } from '@docmost/prosemirror-markdown';
 
 // RED-TEAM finding #4 (two facets):
 //   (a) buildVaultLayout disambiguation is ORDER-DEPENDENT: which of two
diff --git a/packages/git-sync/test/redteam-push-cycle.test.ts b/packages/git-sync/test/redteam-push-cycle.test.ts
index c8b0bfe2..df202242 100644
--- a/packages/git-sync/test/redteam-push-cycle.test.ts
+++ b/packages/git-sync/test/redteam-push-cycle.test.ts
@@ -8,7 +8,7 @@ import {
 import type { PushDeps } from '../src/engine/push';
 import type { Settings } from '../src/engine/settings';
 import { runCycle, type RunCycleDeps } from '../src/engine/cycle';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 // Red-team confirmations for PR #119 (git-sync). Each test asserts the DESIRED
 // behavior, so it FAILS today iff the bug is real.
diff --git a/packages/git-sync/test/roundtrip-all-nodes.test.ts b/packages/git-sync/test/roundtrip-all-nodes.test.ts
deleted file mode 100644
index 6bc634a9..00000000
--- a/packages/git-sync/test/roundtrip-all-nodes.test.ts
+++ /dev/null
@@ -1,297 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-
-/**
- * Exhaustive serialize -> deserialize round trip for EVERY node and mark type the
- * Docmost document schema supports. The git-sync converter exports a page body to
- * Markdown and imports it back; any node type that has no parseHTML inverse (or is
- * serialized to a literal that never re-parses) silently degrades to plain text on
- * a round trip — e.g. `subpages` used to export as the literal `{{SUBPAGES}}` and
- * came back as the visible text "{{SUBPAGES}}" instead of the embed.
- *
- * This guards the whole class: for one representative fixture per type, the node
- * (or mark) MUST still be present after convert -> import, and the exported
- * Markdown must not contain a `{{...}}` template literal (the old lossy form).
- */
-
-const T = (t: string, marks?: any[]) =>
-  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
-const P = (...c: any[]) => ({ type: 'paragraph', content: c });
-const doc = (...c: any[]) => ({ type: 'doc', content: c });
-
-// `primary` is the node/mark type that must survive the round trip.
-const FIXTURES: Record<string, { doc: any; primary: string }> = {
-  paragraph: { doc: doc(P(T('hello'))), primary: 'paragraph' },
-  heading: { doc: doc({ type: 'heading', attrs: { level: 2 }, content: [T('H2')] }), primary: 'heading' },
-  blockquote: { doc: doc({ type: 'blockquote', content: [P(T('q'))] }), primary: 'blockquote' },
-  codeBlock: { doc: doc({ type: 'codeBlock', attrs: { language: 'js' }, content: [T('foo()')] }), primary: 'codeBlock' },
-  bulletList: { doc: doc({ type: 'bulletList', content: [{ type: 'listItem', content: [P(T('a'))] }] }), primary: 'bulletList' },
-  orderedList: { doc: doc({ type: 'orderedList', attrs: { start: 1 }, content: [{ type: 'listItem', content: [P(T('a'))] }] }), primary: 'orderedList' },
-  taskList: { doc: doc({ type: 'taskList', content: [{ type: 'taskItem', attrs: { checked: true }, content: [P(T('done'))] }] }), primary: 'taskList' },
-  horizontalRule: { doc: doc({ type: 'horizontalRule' }), primary: 'horizontalRule' },
-  image: { doc: doc({ type: 'image', attrs: { src: '/f/x.png', width: '320', align: 'center' } }), primary: 'image' },
-  hardBreak: { doc: doc(P(T('a'), { type: 'hardBreak' }, T('b'))), primary: 'hardBreak' },
-  callout: { doc: doc({ type: 'callout', attrs: { type: 'info' }, content: [P(T('note'))] }), primary: 'callout' },
-  columns: {
-    doc: doc({ type: 'columns', content: [
-      { type: 'column', attrs: { width: '50%' }, content: [P(T('L'))] },
-      { type: 'column', attrs: { width: '50%' }, content: [P(T('R'))] }] }),
-    primary: 'column',
-  },
-  details: {
-    doc: doc({ type: 'details', content: [
-      { type: 'detailsSummary', content: [T('Sum')] },
-      { type: 'detailsContent', content: [P(T('body'))] }] }),
-    primary: 'details',
-  },
-  table: {
-    doc: doc({ type: 'table', content: [
-      { type: 'tableRow', content: [{ type: 'tableHeader', content: [P(T('H1'))] }, { type: 'tableHeader', content: [P(T('H2'))] }] },
-      { type: 'tableRow', content: [{ type: 'tableCell', content: [P(T('C1'))] }, { type: 'tableCell', content: [P(T('C2'))] }] }] }),
-    primary: 'tableCell',
-  },
-  mathBlock: { doc: doc({ type: 'mathBlock', attrs: { math: 'x^2' } }), primary: 'mathBlock' },
-  mathInline: { doc: doc(P({ type: 'mathInline', attrs: { math: 'x^2' } })), primary: 'mathInline' },
-  mention: { doc: doc(P({ type: 'mention', attrs: { id: 'u1', label: 'Bob', entityType: 'user', entityId: 'u1' } })), primary: 'mention' },
-  drawio: { doc: doc({ type: 'drawio', attrs: { src: '/f/d.drawio', attachmentId: 'a1' } }), primary: 'drawio' },
-  excalidraw: { doc: doc({ type: 'excalidraw', attrs: { src: '/f/e.excalidraw', attachmentId: 'a1' } }), primary: 'excalidraw' },
-  embed: { doc: doc({ type: 'embed', attrs: { src: 'https://youtube.com/x', provider: 'iframe' } }), primary: 'embed' },
-  pdf: { doc: doc({ type: 'pdf', attrs: { src: '/f/x.pdf', attachmentId: 'a1' } }), primary: 'pdf' },
-  video: { doc: doc({ type: 'video', attrs: { src: '/f/v.mp4', width: '640' } }), primary: 'video' },
-  audio: { doc: doc({ type: 'audio', attrs: { src: '/f/a.mp3' } }), primary: 'audio' },
-  attachment: { doc: doc({ type: 'attachment', attrs: { url: '/f/x.zip', name: 'x.zip', attachmentId: 'a1' } }), primary: 'attachment' },
-  youtube: { doc: doc({ type: 'youtube', attrs: { src: 'https://youtube.com/watch?v=x' } }), primary: 'youtube' },
-  subpages: { doc: doc({ type: 'subpages' }), primary: 'subpages' },
-  pageBreak: { doc: doc({ type: 'pageBreak' }), primary: 'pageBreak' },
-  htmlEmbed: { doc: doc({ type: 'htmlEmbed', attrs: { source: '<b>hi</b>' } }), primary: 'htmlEmbed' },
-  pageEmbed: { doc: doc({ type: 'pageEmbed', attrs: { pageId: 'p1' } }), primary: 'pageEmbed' },
-  // transclusionSource: the schema reads `id` (NOT `pageId`) and its content is
-  // `+` (at least one block child), so give it both or it never re-parses.
-  transclusion: { doc: doc({ type: 'transclusionSource', attrs: { id: 't1' }, content: [P(T('shared'))] }), primary: 'transclusionSource' },
-  transclusionReference: { doc: doc({ type: 'transclusionReference', attrs: { sourcePageId: 'p1', transclusionId: 't1' } }), primary: 'transclusionReference' },
-  footnote: {
-    doc: doc(
-      P(T('x'), { type: 'footnoteReference', attrs: { id: 'fn1' } }),
-      { type: 'footnotesList', content: [{ type: 'footnoteDefinition', attrs: { id: 'fn1' }, content: [P(T('note'))] }] }),
-    primary: 'footnoteReference',
-  },
-  status: { doc: doc(P({ type: 'status', attrs: { text: 'Done', color: 'green' } })), primary: 'status' },
-  // marks
-  bold: { doc: doc(P(T('b', [{ type: 'bold' }]))), primary: 'bold' },
-  italic: { doc: doc(P(T('i', [{ type: 'italic' }]))), primary: 'italic' },
-  strike: { doc: doc(P(T('s', [{ type: 'strike' }]))), primary: 'strike' },
-  code: { doc: doc(P(T('c', [{ type: 'code' }]))), primary: 'code' },
-  underline: { doc: doc(P(T('u', [{ type: 'underline' }]))), primary: 'underline' },
-  superscript: { doc: doc(P(T('x', [{ type: 'superscript' }]))), primary: 'superscript' },
-  subscript: { doc: doc(P(T('x', [{ type: 'subscript' }]))), primary: 'subscript' },
-  highlight: { doc: doc(P(T('h', [{ type: 'highlight', attrs: { color: 'yellow' } }]))), primary: 'highlight' },
-  link: { doc: doc(P(T('l', [{ type: 'link', attrs: { href: 'https://x.com' } }]))), primary: 'link' },
-};
-
-function collectTypes(n: any, set = new Set<string>()): Set<string> {
-  if (!n || typeof n !== 'object') return set;
-  if (n.type) set.add(n.type);
-  if (Array.isArray(n.content)) n.content.forEach((c: any) => collectTypes(c, set));
-  if (Array.isArray(n.marks)) n.marks.forEach((m: any) => m?.type && set.add(m.type));
-  return set;
-}
-
-describe('git-sync converter: every node/mark type survives a Markdown round trip', () => {
-  for (const [name, { doc: original, primary }] of Object.entries(FIXTURES)) {
-    it(`round-trips ${name} (keeps the ${primary} node/mark, no literal leak)`, async () => {
-      const md = convertProseMirrorToMarkdown(original);
-      // The lossy old form serialized embeds to `{{...}}` literals that never
-      // re-parsed; no node may export to one.
-      expect(md).not.toMatch(/\{\{.*\}\}/);
-      const back = await markdownToProseMirror(md);
-      const types = collectTypes(back);
-      expect(types.has(primary)).toBe(true);
-    });
-  }
-});
-
-// A node surviving as the right TYPE is necessary but not sufficient — its
-// attributes must survive too. Each case carries a DISTINCTIVE attribute value
-// (real attr names, verified against the schema) that must reappear after a
-// round trip. This caught `subpages.recursive` and `details.open` being dropped.
-describe('git-sync converter: node ATTRIBUTES survive a Markdown round trip', () => {
-  const ATTR_CASES: Array<{ name: string; doc: any; needles: string[] }> = [
-    { name: 'callout type', doc: doc({ type: 'callout', attrs: { type: 'warning' }, content: [P(T('x'))] }), needles: ['warning'] },
-    { name: 'image dimensions/align/attachmentId', doc: doc({ type: 'image', attrs: { src: '/f/x.png', width: '777', height: '555', align: 'right', attachmentId: 'ATT777' } }), needles: ['777', '555', 'right', 'ATT777'] },
-    { name: 'subpages recursive', doc: doc({ type: 'subpages', attrs: { recursive: true } }), needles: ['"recursive":true'] },
-    { name: 'details open', doc: doc({ type: 'details', attrs: { open: true }, content: [{ type: 'detailsSummary', content: [T('S')] }, { type: 'detailsContent', content: [P(T('b'))] }] }), needles: ['"open":'] },
-    { name: 'mathInline formula', doc: doc(P({ type: 'mathInline', attrs: { text: 'E=mc^7' } })), needles: ['E=mc^7'] },
-    { name: 'mathBlock formula', doc: doc({ type: 'mathBlock', attrs: { text: '\\sum_7' } }), needles: ['sum_7'] },
-    { name: 'pageEmbed sourcePageId', doc: doc({ type: 'pageEmbed', attrs: { sourcePageId: 'PAGE777' } }), needles: ['PAGE777'] },
-    { name: 'video dimensions/attachmentId', doc: doc({ type: 'video', attrs: { src: '/f/v.mp4', width: '888', attachmentId: 'VID888' } }), needles: ['888', 'VID888'] },
-    { name: 'status text/color', doc: doc(P({ type: 'status', attrs: { text: 'InProgress777', color: 'orange' } })), needles: ['InProgress777', 'orange'] },
-    { name: 'mention entityId/label', doc: doc(P({ type: 'mention', attrs: { id: 'M1', label: 'Alice', entityType: 'user', entityId: 'ENT777' } })), needles: ['Alice', 'ENT777'] },
-    { name: 'columns widths', doc: doc({ type: 'columns', content: [{ type: 'column', attrs: { width: '37%' }, content: [P(T('L'))] }, { type: 'column', attrs: { width: '63%' }, content: [P(T('R'))] }] }), needles: ['37%', '63%'] },
-    { name: 'highlight color', doc: doc(P(T('x', [{ type: 'highlight', attrs: { color: '#abcdef' } }]))), needles: ['#abcdef'] },
-  ];
-  for (const { name, doc: original, needles } of ATTR_CASES) {
-    it(`preserves ${name}`, async () => {
-      const md = convertProseMirrorToMarkdown(original);
-      const back = JSON.stringify(await markdownToProseMirror(md));
-      for (const needle of needles) {
-        // The value must survive in the re-imported doc (or in the markdown the
-        // schema parses it back from).
-        expect(`${back} ${md}`).toContain(needle);
-      }
-    });
-  }
-});
-
-// Find the FIRST node of a given type anywhere in a ProseMirror tree (depth
-// first). Used by the structural round-trip assertions below that need the
-// re-imported node's concrete attrs/content, not just "the type is present".
-function findNode(n: any, type: string): any {
-  if (!n || typeof n !== 'object') return undefined;
-  if (n.type === type) return n;
-  if (Array.isArray(n.content)) {
-    for (const c of n.content) {
-      const hit = findNode(c, type);
-      if (hit) return hit;
-    }
-  }
-  return undefined;
-}
-
-// Collect every text run reachable under a node (concatenated). Lets a test
-// assert a footnote definition's note BODY survived, not just the wrapper.
-function allText(n: any): string {
-  if (!n || typeof n !== 'object') return '';
-  if (n.type === 'text') return n.text || '';
-  if (Array.isArray(n.content)) return n.content.map(allText).join('');
-  return '';
-}
-
-// Attributes survive as the TYPE-correct value, not just as a substring of the
-// serialized blob. These re-import and assert on the concrete re-parsed node.
-describe('git-sync converter: lose-prone atoms keep their VALUES across a round trip', () => {
-  it('A: a NESTED details (inside columns) keeps open:true', async () => {
-    // The raw-HTML path (detailsToHtml) is used for a details nested in a
-    // column/spanned cell — distinct from the top-level details case. Before the
-    // fix it emitted a bare <details>, dropping open every round trip.
-    const original = doc({
-      type: 'columns',
-      content: [
-        {
-          type: 'column',
-          attrs: { width: '100%' },
-          content: [
-            {
-              type: 'details',
-              attrs: { open: true },
-              content: [
-                { type: 'detailsSummary', content: [T('S')] },
-                { type: 'detailsContent', content: [P(T('b'))] },
-              ],
-            },
-          ],
-        },
-      ],
-    });
-    const md = convertProseMirrorToMarkdown(original);
-    // detailsToHtml must emit the `open` attribute (RED before the fix: it
-    // emitted a bare <details> inside the column).
-    expect(md).toContain('<details open>');
-    const back = await markdownToProseMirror(md);
-    const details = findNode(back, 'details');
-    expect(details).toBeDefined();
-    // `open` must round-trip as a STRICT boolean `true` — not "" (the old raw
-    // getAttribute value) and not the default `false` (a dropped attribute).
-    // Before the schema parseHTML fix (hasAttribute), `<details open>` parsed to
-    // "" — falsy, so it rendered as a bare <details> and collapsed. RED before
-    // the fix (open was "" or false, never === true).
-    expect(details.attrs?.open).toBe(true);
-  });
-
-  it('B: a TOP-LEVEL details keeps open as strict boolean true', async () => {
-    const original = doc({
-      type: 'details',
-      attrs: { open: true },
-      content: [
-        { type: 'detailsSummary', content: [T('S')] },
-        { type: 'detailsContent', content: [P(T('b'))] },
-      ],
-    });
-    const md = convertProseMirrorToMarkdown(original);
-    const back = await markdownToProseMirror(md);
-    const details = findNode(back, 'details');
-    expect(details).toBeDefined();
-    // Strict boolean, proving the value survives as `true` (not ""/false).
-    // RED before the fix: parseHTML returned getAttribute("open") === "".
-    expect(details.attrs?.open).toBe(true);
-  });
-
-  it('D: htmlEmbed source VALUE and height survive', async () => {
-    const original = doc({
-      type: 'htmlEmbed',
-      attrs: { source: '<b>hi</b>', height: 300 },
-    });
-    const md = convertProseMirrorToMarkdown(original);
-    const back = await markdownToProseMirror(md);
-    const embed = findNode(back, 'htmlEmbed');
-    expect(embed).toBeDefined();
-    // The exact raw source must decode back identically (base64 round trip).
-    expect(embed.attrs?.source).toBe('<b>hi</b>');
-    expect(embed.attrs?.height).toBe(300);
-  });
-
-  it('E: footnote definition BODY survives and its id matches the reference', async () => {
-    const original = doc(
-      P(T('x'), { type: 'footnoteReference', attrs: { id: 'fn1' } }),
-      {
-        type: 'footnotesList',
-        content: [
-          {
-            type: 'footnoteDefinition',
-            attrs: { id: 'fn1' },
-            content: [P(T('note'))],
-          },
-        ],
-      },
-    );
-    const md = convertProseMirrorToMarkdown(original);
-    const back = await markdownToProseMirror(md);
-    const list = findNode(back, 'footnotesList');
-    const def = findNode(back, 'footnoteDefinition');
-    const ref = findNode(back, 'footnoteReference');
-    expect(list).toBeDefined();
-    expect(def).toBeDefined();
-    expect(ref).toBeDefined();
-    // The note text rode along, not just the empty wrapper.
-    expect(allText(def)).toContain('note');
-    // The reference still points at the matching definition.
-    expect(ref.attrs?.id).toBe(def.attrs?.id);
-  });
-
-  it('F: transclusionReference keeps BOTH sourcePageId and transclusionId', async () => {
-    const original = doc({
-      type: 'transclusionReference',
-      attrs: { sourcePageId: 'PAGE_X', transclusionId: 'TR_Y' },
-    });
-    const md = convertProseMirrorToMarkdown(original);
-    const back = await markdownToProseMirror(md);
-    const ref = findNode(back, 'transclusionReference');
-    expect(ref).toBeDefined();
-    expect(ref.attrs?.sourcePageId).toBe('PAGE_X');
-    expect(ref.attrs?.transclusionId).toBe('TR_Y');
-  });
-
-  it('F: transclusionSource keeps its id and re-parses its child body', async () => {
-    const original = doc({
-      type: 'transclusionSource',
-      attrs: { id: 'SRC_Z' },
-      content: [P(T('shared body'))],
-    });
-    const md = convertProseMirrorToMarkdown(original);
-    const back = await markdownToProseMirror(md);
-    const src = findNode(back, 'transclusionSource');
-    expect(src).toBeDefined();
-    expect(src.attrs?.id).toBe('SRC_Z');
-    expect(allText(src)).toContain('shared body');
-  });
-});
diff --git a/packages/git-sync/test/roundtrip-corpus.test.ts b/packages/git-sync/test/roundtrip-corpus.test.ts
deleted file mode 100644
index b715b170..00000000
--- a/packages/git-sync/test/roundtrip-corpus.test.ts
+++ /dev/null
@@ -1,104 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { readdirSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-  docsCanonicallyEqual,
-} from 'docmost-client';
-
-// Resolve fixtures relative to this test file so the test is CWD-independent.
-const here = dirname(fileURLToPath(import.meta.url));
-const CORPUS_DIR = join(here, 'fixtures', 'corpus');
-const KNOWN_LIMITATIONS_DIR = join(here, 'fixtures', 'known-limitations');
-
-/** Run a single document through export -> import -> export. */
-async function roundTrip(doc: any) {
-  const md1 = convertProseMirrorToMarkdown(doc);
-  const doc2 = await markdownToProseMirror(md1);
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  return { md1, md2, doc2 };
-}
-
-describe('round-trip corpus (SPEC §11)', () => {
-  // Discover the corpus synchronously at collection time so each fixture gets
-  // its own `it` with the file name in the test title.
-  const files = readdirSync(CORPUS_DIR)
-    .filter((name) => name.endsWith('.json'))
-    .sort();
-
-  it('has a non-empty corpus', () => {
-    expect(files.length).toBeGreaterThan(0);
-  });
-
-  for (const name of files) {
-    it(`${name}: markdown byte-stable AND canonically stable`, async () => {
-      const doc = JSON.parse(await readFile(join(CORPUS_DIR, name), 'utf8'));
-      const { md1, md2, doc2 } = await roundTrip(doc);
-
-      // 1) The byte-stable markdown property git actually needs.
-      expect(md2, `${name}: markdown not byte-stable`).toBe(md1);
-      // 2) Semantic stability (block ids stripped, default-null normalized).
-      expect(
-        docsCanonicallyEqual(doc, doc2),
-        `${name}: document not canonically stable`,
-      ).toBe(true);
-    });
-  }
-});
-
-// ---------------------------------------------------------------------------
-// KNOWN CONVERTER LIMITATIONS (isolated so they do NOT make CI red).
-//
-// SPEC §11 explicitly flags images and diagrams as high round-trip risk. These
-// fixtures are kept OUT of the green corpus above and asserted with `it.fails`
-// so the documented divergence is locked in (the test FAILS if the converter
-// ever starts round-tripping them — at which point promote the fixture into
-// the corpus). The precise divergences for `image-diagrams.json` are:
-//
-//   * A BLOCK-LEVEL image preceded by a paragraph is NOT byte-stable on the
-//     FIRST re-export. The HTML re-parser hoists the block <img> out of its
-//     line and leaves an empty paragraph behind, so `paragraph` + `![..](..)`
-//     re-imports as paragraph + empty-paragraph + image; the empty paragraph
-//     adds one blank line, so export #2 grows by a one-time "\n\n" (md1 !== md2).
-//     This is NOT non-convergence: the growth happens exactly ONCE. The doc
-//     CONVERGES to a fixpoint after one extra `export→import→export` pass — the
-//     empty paragraph is already present after the first import, so export #2
-//     and export #3 are byte-identical (md2 === md3, verified).
-//
-//   * drawio / excalidraw diagrams gain `data-align="center"` on the second
-//     export: the schema's diagram `align` attribute has a NON-null default of
-//     "center", which materializes on import; the converter only emits
-//     data-align when set, so it appears on export #2 but not #1. Like the
-//     image case, this is one-time and converges after one extra pass.
-//
-//   * A STANDALONE block image (no preceding paragraph) IS byte-stable from
-//     export #1 (md1 === md2) — but it is still NOT canonically stable: on
-//     import the bare <img> is wrapped, gaining a leading EMPTY paragraph, so
-//     the canonical doc differs by that spurious paragraph node even though the
-//     markdown bytes match.
-//
-// Resolution (SPEC §11, "normalize-on-write"): rather than deep-fixing the
-// converter, the engine runs ONE `export→import→export` pass when writing into
-// the vault; from that fixpoint onward the form is byte-stable, so git sees no
-// phantom diff. The green corpus above avoids these one-time asymmetries by
-// pre-authoring the materialized defaults (e.g. `align: "center"` on the
-// diagrams in 06-diagrams.json) so a single pass is already at the fixpoint.
-// ---------------------------------------------------------------------------
-describe('round-trip KNOWN LIMITATIONS (SPEC §11 image/diagram risk)', () => {
-  it.fails(
-    'image-diagrams.json is NOT byte-stable on export #1 (block image hoist + diagram align default; converges after one extra pass — SPEC §11 normalize-on-write)',
-    async () => {
-      const doc = JSON.parse(
-        await readFile(join(KNOWN_LIMITATIONS_DIR, 'image-diagrams.json'), 'utf8'),
-      );
-      const { md1, md2 } = await roundTrip(doc);
-      // This assertion FAILS today (documented divergence). `it.fails` turns a
-      // failing body into a PASS; if the converter is fixed this flips and the
-      // test goes red, prompting promotion into the green corpus.
-      expect(md2).toBe(md1);
-    },
-  );
-});
diff --git a/packages/git-sync/test/roundtrip.test.ts b/packages/git-sync/test/roundtrip.test.ts
deleted file mode 100644
index 62db34b3..00000000
--- a/packages/git-sync/test/roundtrip.test.ts
+++ /dev/null
@@ -1,168 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import {
-  convertProseMirrorToMarkdown,
-  markdownToProseMirror,
-} from 'docmost-client';
-// Import canonical-equality DIRECTLY from src so we exercise the real
-// implementation alongside the converter pair above (the barrel re-exports the
-// same symbol; importing from src keeps these round-trip assertions pinned to
-// the package source rather than the published surface).
-import { docsCanonicallyEqual } from '../src/lib/canonicalize.js';
-
-// Resolve the fixture relative to this test file so the test is CWD-independent.
-const here = dirname(fileURLToPath(import.meta.url));
-const FIXTURE = join(here, 'fixtures', 'sample-doc.json');
-
-describe('round-trip idempotency (SPEC §11)', () => {
-  it('markdown is byte-stable across export -> import -> export', async () => {
-    const doc = JSON.parse(await readFile(FIXTURE, 'utf8'));
-
-    // export -> import -> export
-    const md1 = convertProseMirrorToMarkdown(doc);
-    const doc2 = await markdownToProseMirror(md1);
-    const md2 = convertProseMirrorToMarkdown(doc2);
-
-    // The property git actually needs: a second export reproduces the first
-    // byte-for-byte. We intentionally do NOT deep-equal doc vs doc2 — the
-    // converter reconstructs schema default attrs (e.g. indent:null), a known
-    // SPEC §11 divergence that does not affect markdown stability.
-    expect(md2).toBe(md1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Full export -> import -> export round-trips for the schema's HTML-carried
-// atoms/blocks (math, mention, details). The existing markdown-converter unit
-// tests only assert the one-way emit string; here we additionally pin that the
-// re-import (generateJSON via the docmost schema) rebuilds the correct node and
-// that a second export reproduces the first byte-for-byte. Helpers mirror the
-// converter unit tests (a single-node doc renders exactly that node, trimmed).
-// ---------------------------------------------------------------------------
-const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
-const text = (t: string) => ({ type: 'text', text: t });
-const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
-
-// Run the canonical export -> import -> export cycle for a single block node.
-async function roundTrip(
-  node: any,
-): Promise<{ md1: string; doc2: any; md2: string }> {
-  const md1 = convertProseMirrorToMarkdown(doc(node));
-  const doc2 = await markdownToProseMirror(md1);
-  const md2 = convertProseMirrorToMarkdown(doc2);
-  return { md1, doc2, md2 };
-}
-
-describe('math round-trip (mathBlock + mathInline)', () => {
-  it('mathBlock survives export -> import -> export with LaTeX recovered', async () => {
-    const source = { type: 'mathBlock', attrs: { text: 'a^2+b^2' } };
-    const { md1, doc2, md2 } = await roundTrip(source);
-
-    // One-way emit: LaTeX rides in the `text` HTML attribute, data-katex flag set.
-    expect(md1).toBe(
-      '<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>',
-    );
-    // Byte-stable: the second export reproduces the first exactly.
-    expect(md2).toBe(md1);
-
-    // The re-imported doc's only block is a mathBlock whose LaTeX was recovered
-    // from the text= attribute by the schema's default parser.
-    const block = doc2.content[0];
-    expect(block.type).toBe('mathBlock');
-    expect(block.attrs.text).toBe('a^2+b^2');
-
-    // Canonical equality: source and re-imported doc are the same node.
-    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
-  });
-
-  it('mathInline (inside a paragraph) survives export -> import -> export', async () => {
-    const source = para({ type: 'mathInline', attrs: { text: 'x_i' } });
-    const { md1, doc2, md2 } = await roundTrip(source);
-
-    expect(md1).toBe(
-      '<span data-type="mathInline" data-katex="true" text="x_i"></span>',
-    );
-    expect(md2).toBe(md1);
-
-    // The re-imported paragraph's child is a mathInline with the LaTeX recovered.
-    const paragraph = doc2.content[0];
-    expect(paragraph.type).toBe('paragraph');
-    const inline = paragraph.content[0];
-    expect(inline.type).toBe('mathInline');
-    expect(inline.attrs.text).toBe('x_i');
-
-    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
-  });
-});
-
-describe('mention round-trip', () => {
-  it('mention survives export -> import -> export with data-* re-parsed', async () => {
-    const source = para({
-      type: 'mention',
-      attrs: { id: 'u1', label: 'Alice', entityType: 'user' },
-    });
-    const { md1, doc2, md2 } = await roundTrip(source);
-
-    // One-way emit: schema span with data-* attrs and the visible '@Alice' text.
-    expect(md1).toBe(
-      '<span data-type="mention" data-id="u1" data-label="Alice" data-entity-type="user">@Alice</span>',
-    );
-    // Byte-stable.
-    expect(md2).toBe(md1);
-
-    // The visible '@Alice' is cosmetic; generateJSON rebuilds a mention node from
-    // the data-* attributes. The unset attrs fall back to their schema defaults.
-    const paragraph = doc2.content[0];
-    expect(paragraph.type).toBe('paragraph');
-    const mention = paragraph.content[0];
-    expect(mention.type).toBe('mention');
-    expect(mention.attrs.id).toBe('u1');
-    expect(mention.attrs.label).toBe('Alice');
-    expect(mention.attrs.entityType).toBe('user');
-    expect(mention.attrs.entityId).toBeNull();
-    expect(mention.attrs.slugId).toBeNull();
-    expect(mention.attrs.creatorId).toBeNull();
-    expect(mention.attrs.anchorId).toBeNull();
-
-    expect(docsCanonicallyEqual(doc(source), doc2)).toBe(true);
-  });
-});
-
-describe('details open-attribute round-trip', () => {
-  it('the markdown details fence never carries an open flag and stays byte-stable', async () => {
-    // Source details is OPEN (attrs.open: ''), but the top-level markdown path
-    // emits a plain '<details>' fence (no 'open' attribute) — see converter
-    // case "detailsSummary" which hardcodes '<details>\n<summary>...'.
-    const source = {
-      type: 'details',
-      attrs: { open: '' },
-      content: [
-        { type: 'detailsSummary', content: [text('S')] },
-        { type: 'detailsContent', content: [para(text('body'))] },
-      ],
-    };
-    const { md1, doc2, md2 } = await roundTrip(source);
-
-    // The emitted fence drops the open flag entirely.
-    expect(md1).toBe('<details>\n<summary>S</summary>\n\nbody\n</details>');
-    expect(md1).not.toContain('open');
-
-    // Byte-stable: re-export reproduces the same fence.
-    expect(md2).toBe(md1);
-
-    // NOTE(review): the spec text says doc2's details attrs.open should be
-    // `null` (the raw return of el.getAttribute('open') on a plain <details>,
-    // schema src ~L438). In practice generateJSON applies the schema attribute
-    // default when the parseHTML result is null, so the materialised node carries
-    // attrs.open === false (the declared default at src ~L437), NOT null. We
-    // assert the ACTUAL value. The load-bearing point of the spec still holds:
-    // a plain <details> import does NOT recover the open flag (no truthy value),
-    // so renderHTML's `attrs.open ? {open:''} : {}` keeps the round-trip clean.
-    const details = doc2.content[0];
-    expect(details.type).toBe('details');
-    expect(details.attrs.open).toBe(false);
-    expect(details.attrs.open).toBeFalsy();
-  });
-});
diff --git a/packages/git-sync/test/run-push-realgit.test.ts b/packages/git-sync/test/run-push-realgit.test.ts
index 0dc36aed..3d94ba3a 100644
--- a/packages/git-sync/test/run-push-realgit.test.ts
+++ b/packages/git-sync/test/run-push-realgit.test.ts
@@ -8,7 +8,7 @@ import { runPush, LAST_PUSHED_REF } from '../src/engine/push';
 import type { PushDeps } from '../src/engine/push';
 import { VaultGit } from '../src/engine/git';
 import type { Settings } from '../src/engine/settings';
-import { serializeDocmostMarkdownBody } from '../src/lib/index';
+import { serializeDocmostMarkdownBody } from '@docmost/prosemirror-markdown';
 
 const execFileAsync = promisify(execFile);
 
diff --git a/packages/git-sync/test/run-push.test.ts b/packages/git-sync/test/run-push.test.ts
index c5c4f060..adaf4f2b 100644
--- a/packages/git-sync/test/run-push.test.ts
+++ b/packages/git-sync/test/run-push.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import { runPush, LAST_PUSHED_REF, DOCMOST_BRANCH } from '../src/engine/push';
 import type { PushDeps } from '../src/engine/push';
 import type { Settings } from '../src/engine/settings';
-import { serializePageFile } from '../src/lib/page-file';
+import { serializePageFile } from '@docmost/prosemirror-markdown';
 
 /** A native page file: `gitmost_id` frontmatter + clean body (title = filename). */
 function fileFor(pageId: string, body = 'body'): string {
diff --git a/packages/git-sync/test/schema-editor-ext-contract.test.ts b/packages/git-sync/test/schema-editor-ext-contract.test.ts
deleted file mode 100644
index 4778ea5c..00000000
--- a/packages/git-sync/test/schema-editor-ext-contract.test.ts
+++ /dev/null
@@ -1,87 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { getSchema } from "@tiptap/core";
-
-import { docmostExtensions } from "../src/lib/docmost-schema.js";
-import * as editorExt from "@docmost/editor-ext";
-
-// CROSS-PACKAGE SCHEMA CONTRACT (data-loss-sensitive).
-//
-// `src/lib/docmost-schema.ts` is a hand-synced VENDORED MIRROR of the canonical
-// Docmost schema in `@docmost/editor-ext`. The sibling `schema-surface-snapshot`
-// test pins the mirror's FULL surface (names + attrs) against an inline
-// reference, but that reference is hand-curated and does not mechanically tie to
-// editor-ext. This test closes that gap from the other side: it reads the ACTUAL
-// Tiptap node/mark definitions exported by `@docmost/editor-ext` and asserts the
-// vendored mirror is a SUPERSET of their type NAMES — so a Docmost-specific node
-// or mark added upstream that the mirror forgets to vendor fails CI loudly
-// (otherwise it is silently dropped on the markdown <-> ProseMirror round-trip).
-//
-// LIMITATION (intentional, see schema-surface-snapshot.test.ts): this is a
-// NAME-LEVEL contract only, not a full attribute-level structural compare.
-// editor-ext's Tiptap representation (node views, commands, suggestion plugins,
-// addGlobalAttributes spread across separate extensions) differs from this
-// minimal mirror, so a mechanical attribute-by-attribute equality would be
-// fragile and produce false drift. Attribute parity is guarded by the inline
-// surface snapshot (reviewed in every diff); this test guards that no canonical
-// node/mark TYPE goes unmirrored. StarterKit-provided types (paragraph, bold,
-// heading, …) are contributed by @tiptap/starter-kit in the mirror rather than
-// by editor-ext, so they are naturally covered by the mirror's superset.
-//
-// NOT COVERED here (deferred): (1) the THIRD copy in `packages/mcp` — a separate
-// package guarded by its own surface snapshot; (2) attribute *behaviour* drift,
-// e.g. the details `open` attr read via getAttribute vs hasAttribute (PR #119
-// review #2) — a name-level compare cannot see parseHTML/renderHTML differences.
-// Mechanically guarding behavioural parity across all THREE copies needs the
-// single framework-free "schema core" refactor (deferred — see AGENTS.md); until
-// then each copy's header carries the manual keep-in-sync requirement.
-
-/** Tiptap Node/Mark instances expose a `.name` and a `.type` of 'node'|'mark'. */
-function isTiptapNodeOrMark(
-  value: unknown,
-): value is { name: string; type: "node" | "mark" } {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    "name" in value &&
-    typeof (value as { name: unknown }).name === "string" &&
-    "type" in value &&
-    ((value as { type: unknown }).type === "node" ||
-      (value as { type: unknown }).type === "mark")
-  );
-}
-
-/** The set of node/mark type names the vendored mirror actually registers. */
-function vendoredNames(): Set<string> {
-  const schema = getSchema(docmostExtensions as never);
-  return new Set([
-    ...Object.keys(schema.nodes),
-    ...Object.keys(schema.marks),
-  ]);
-}
-
-/** The Docmost-specific node/mark type names exported by @docmost/editor-ext. */
-function editorExtNames(): Set<string> {
-  const names = new Set<string>();
-  for (const value of Object.values(editorExt)) {
-    if (isTiptapNodeOrMark(value)) names.add(value.name);
-  }
-  return names;
-}
-
-describe("docmost schema vs @docmost/editor-ext (name-level contract)", () => {
-  it("exposes Tiptap node/mark definitions from editor-ext (guards against the import going dark)", () => {
-    // If editor-ext ever stops exporting concrete node/mark objects (e.g. a
-    // barrel refactor), this contract would vacuously pass — assert it found a
-    // meaningful set so the test cannot silently become a no-op.
-    expect(editorExtNames().size).toBeGreaterThan(5);
-  });
-
-  it("vendors every Docmost-specific node/mark type defined in editor-ext (no silently-dropped types)", () => {
-    const vendored = vendoredNames();
-    const missing = [...editorExtNames()].filter((n) => !vendored.has(n)).sort();
-    // missing must be empty: any name here exists in editor-ext but NOT in the
-    // vendored mirror, so documents using it would lose that node/mark on a
-    // git-sync round-trip. Re-sync src/lib/docmost-schema.ts before clearing.
-    expect(missing).toEqual([]);
-  });
-});
diff --git a/packages/git-sync/test/schema-surface-snapshot.test.ts b/packages/git-sync/test/schema-surface-snapshot.test.ts
deleted file mode 100644
index f6d4b748..00000000
--- a/packages/git-sync/test/schema-surface-snapshot.test.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { getSchema } from "@tiptap/core";
-
-import { docmostExtensions } from "../src/lib/docmost-schema.js";
-
-// SCHEMA-DRIFT GUARD (must-review gate).
-//
-// `src/lib/docmost-schema.ts` is a VENDORED MIRROR of the canonical Docmost
-// document schema defined in `@docmost/editor-ext`. git-sync uses it to convert
-// pages to/from ProseMirror JSON; any node, mark, or attribute that exists in
-// the canonical schema but is missing here is silently dropped on a round-trip
-// (data loss). The reverse — a node/mark/attr here that no longer exists in the
-// canonical schema — is dead surface that can mask drift.
-//
-// This test derives a stable, sorted "schema surface" (every node/mark name and
-// its sorted attribute keys) and pins it against an INLINE expected constant.
-// It is intentionally a LOUD must-review gate rather than an automatic
-// editor-ext diff: editor-ext's Tiptap representation differs from this
-// vendored copy, so a cross-representation compare would be fragile. We do NOT
-// use toMatchSnapshot so the reference lives in this file and is reviewed in the
-// diff of every change.
-//
-// WHEN THIS TEST FAILS: do NOT blindly update `expectedSurface`. First confirm
-// the change matches `@docmost/editor-ext` (the canonical schema) so the
-// markdown <-> ProseMirror round-trip stays lossless, THEN copy the new surface
-// into the expected constant below.
-
-interface SurfaceEntry {
-  name: string;
-  kind: "node" | "mark";
-  attrs: string[];
-}
-
-/** Derive the deterministic schema surface from the vendored extension set. */
-function deriveSurface(): SurfaceEntry[] {
-  const schema = getSchema(docmostExtensions as never);
-  const surface: SurfaceEntry[] = [];
-  for (const [name, type] of Object.entries(schema.nodes)) {
-    surface.push({
-      name,
-      kind: "node",
-      attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
-    });
-  }
-  for (const [name, type] of Object.entries(schema.marks)) {
-    surface.push({
-      name,
-      kind: "mark",
-      attrs: Object.keys((type as { spec?: { attrs?: object } }).spec?.attrs ?? {}).sort(),
-    });
-  }
-  // Sort by name, then by kind, for a representation-independent ordering.
-  surface.sort((a, b) =>
-    a.name === b.name ? a.kind.localeCompare(b.kind) : a.name.localeCompare(b.name),
-  );
-  return surface;
-}
-
-// The committed reference surface. Built from the ACTUAL current schema; review
-// every change to this constant against `@docmost/editor-ext`.
-const expectedSurface: SurfaceEntry[] = [
-  { name: "attachment", kind: "node", attrs: ["attachmentId", "mime", "name", "placeholder", "size", "url"] },
-  { name: "audio", kind: "node", attrs: ["attachmentId", "placeholder", "size", "src"] },
-  { name: "blockquote", kind: "node", attrs: [] },
-  { name: "bold", kind: "mark", attrs: [] },
-  { name: "bulletList", kind: "node", attrs: [] },
-  { name: "callout", kind: "node", attrs: ["icon", "type"] },
-  { name: "code", kind: "mark", attrs: [] },
-  { name: "codeBlock", kind: "node", attrs: ["language"] },
-  { name: "column", kind: "node", attrs: ["width"] },
-  { name: "columns", kind: "node", attrs: ["layout", "widthMode"] },
-  { name: "comment", kind: "mark", attrs: ["commentId", "resolved"] },
-  { name: "details", kind: "node", attrs: ["open"] },
-  { name: "detailsContent", kind: "node", attrs: [] },
-  { name: "detailsSummary", kind: "node", attrs: [] },
-  { name: "doc", kind: "node", attrs: [] },
-  { name: "drawio", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
-  { name: "embed", kind: "node", attrs: ["align", "height", "provider", "src", "width"] },
-  { name: "excalidraw", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "size", "src", "title", "width"] },
-  { name: "footnoteDefinition", kind: "node", attrs: ["id"] },
-  { name: "footnoteReference", kind: "node", attrs: ["id"] },
-  { name: "footnotesList", kind: "node", attrs: [] },
-  { name: "hardBreak", kind: "node", attrs: [] },
-  { name: "heading", kind: "node", attrs: ["id", "indent", "level", "textAlign"] },
-  { name: "highlight", kind: "mark", attrs: ["color"] },
-  { name: "horizontalRule", kind: "node", attrs: [] },
-  { name: "htmlEmbed", kind: "node", attrs: ["height", "source"] },
-  { name: "image", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "caption", "height", "placeholder", "size", "src", "title", "width"] },
-  { name: "italic", kind: "mark", attrs: [] },
-  { name: "link", kind: "mark", attrs: ["class", "href", "internal", "rel", "target", "title"] },
-  { name: "listItem", kind: "node", attrs: [] },
-  { name: "mathBlock", kind: "node", attrs: ["text"] },
-  { name: "mathInline", kind: "node", attrs: ["text"] },
-  { name: "mention", kind: "node", attrs: ["anchorId", "creatorId", "entityId", "entityType", "id", "label", "slugId"] },
-  { name: "orderedList", kind: "node", attrs: ["start", "type"] },
-  { name: "pageBreak", kind: "node", attrs: [] },
-  { name: "pageEmbed", kind: "node", attrs: ["sourcePageId"] },
-  { name: "paragraph", kind: "node", attrs: ["id", "indent", "textAlign"] },
-  { name: "pdf", kind: "node", attrs: ["attachmentId", "height", "name", "placeholder", "size", "src", "width"] },
-  { name: "spoiler", kind: "mark", attrs: [] },
-  { name: "status", kind: "node", attrs: ["color", "text"] },
-  { name: "strike", kind: "mark", attrs: [] },
-  { name: "subpages", kind: "node", attrs: ["recursive"] },
-  { name: "subscript", kind: "mark", attrs: [] },
-  { name: "superscript", kind: "mark", attrs: [] },
-  { name: "table", kind: "node", attrs: [] },
-  { name: "tableCell", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
-  { name: "tableHeader", kind: "node", attrs: ["align", "backgroundColor", "backgroundColorName", "colspan", "colwidth", "rowspan"] },
-  { name: "tableRow", kind: "node", attrs: [] },
-  { name: "taskItem", kind: "node", attrs: ["checked"] },
-  { name: "taskList", kind: "node", attrs: [] },
-  { name: "text", kind: "node", attrs: [] },
-  { name: "textStyle", kind: "mark", attrs: ["color"] },
-  { name: "transclusionReference", kind: "node", attrs: ["sourcePageId", "transclusionId"] },
-  { name: "transclusionSource", kind: "node", attrs: ["id"] },
-  { name: "underline", kind: "mark", attrs: [] },
-  { name: "video", kind: "node", attrs: ["align", "alt", "aspectRatio", "attachmentId", "height", "placeholder", "size", "src", "width"] },
-  { name: "youtube", kind: "node", attrs: ["align", "height", "src", "width"] },
-];
-
-describe("docmost schema surface", () => {
-  it("matches the committed reference surface (re-verify against @docmost/editor-ext on change)", () => {
-    expect(deriveSurface()).toEqual(expectedSurface);
-  });
-});
diff --git a/packages/git-sync/test/stabilize.test.ts b/packages/git-sync/test/stabilize.test.ts
index ebc63d35..8a70e1b9 100644
--- a/packages/git-sync/test/stabilize.test.ts
+++ b/packages/git-sync/test/stabilize.test.ts
@@ -2,8 +2,8 @@ import { describe, expect, it } from 'vitest';
 import { stabilizePageFile, type PageMeta } from '../src/engine/stabilize.js';
 // markdownToProseMirror lives in collaboration.ts; importing it mutates the
 // global DOM via jsdom at module load time (required for @tiptap/html under Node).
-import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
-import { parseDocmostMarkdown } from '../src/lib/markdown-document.js';
+import { markdownToProseMirror } from '@docmost/prosemirror-markdown';
+import { parseDocmostMarkdown } from '@docmost/prosemirror-markdown';
 
 // stabilize.ts (SPEC §11 normalize-on-write) was 0% covered (only the gated e2e
 // touched it). stabilizePageFile is import-testable: build a small ProseMirror
diff --git a/packages/git-sync/test/strip-empty-paragraphs-validity.test.ts b/packages/git-sync/test/strip-empty-paragraphs-validity.test.ts
index e5514ec2..d1f48b87 100644
--- a/packages/git-sync/test/strip-empty-paragraphs-validity.test.ts
+++ b/packages/git-sync/test/strip-empty-paragraphs-validity.test.ts
@@ -1,8 +1,8 @@
 import { describe, it, expect } from "vitest";
 import { getSchema } from "@tiptap/core";
 
-import { markdownToProseMirror } from "../src/lib/markdown-to-prosemirror";
-import { docmostExtensions } from "../src/lib/docmost-schema";
+import { markdownToProseMirror } from "@docmost/prosemirror-markdown";
+import { docmostExtensions } from "@docmost/prosemirror-markdown";
 
 // REGRESSION LOCK for the stripEmptyParagraphs schema-validity guard.
 //
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
index 9e797a26..f02713e5 100644
--- a/packages/prosemirror-markdown/src/lib/index.ts
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -19,6 +19,11 @@ export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
 
 export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 
+// The Docmost tiptap schema mirror. Exposed so consumers (and the sync
+// engine's schema-validity regression tests) can build the exact ProseMirror
+// schema the converter targets.
+export { docmostExtensions } from "./docmost-schema.js";
+
 export {
   canonicalizeContent,
   docsCanonicallyEqual,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cffcd8d0..1f623946 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -889,6 +889,9 @@ importers:
 
   packages/git-sync:
     dependencies:
+      '@docmost/prosemirror-markdown':
+        specifier: workspace:*
+        version: link:../prosemirror-markdown
       '@tiptap/core':
         specifier: 3.20.4
         version: 3.20.4(@tiptap/pm@3.20.4)
-- 
2.52.0


From f1ab76e8796c25e812d9b0b9b106ea322ea5c250 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 07:39:29 +0300
Subject: [PATCH 03/17] feat(prosemirror-markdown): serialize textAlign as
 attached comment (#293 canon #9)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move paragraph/heading textAlign off the HTML-wrapper form
(<p style="text-align:…"> / <hN style=…>) onto a trailing attached HTML
comment on the block line: `text <!--attrs {"textAlign":"center"}-->`. This
keeps the readable markdown block form (plain `text` / `## Title`) while
preserving alignment losslessly. "left"/null stay bare (no churn).

Adds a reusable attached-comment primitive (attached-comment.ts) that #4
(image) and #8 (media) will reuse:
- attachedCommentFor(name, json) -> `<!--name {compact-json}-->`, escaping any
  `--` pair inside the JSON as -- so the payload can never close the
  comment early;
- parseAttachedComment(data) with grammar `^\s*([A-Za-z][\w-]*)(?:\s+({…}))?\s*$`
  whose name excludes `:`, so envelope comments (docmost:meta / docmost:comments)
  never match — fail-open on anything malformed.

On import, applyAttachedComments runs AFTER marked.parse but BEFORE generateJSON
(parse5 drops comments), re-expressing the attrs comment as an inline
text-align style on the parent block, then removing the comment node.

Guards: emit only when there is a visible element to attach to — paragraph
requires non-empty text, heading requires non-empty headingText (symmetry:
an empty aligned heading stays bare `##`, no orphan comment).

Goldens in markdown-converter-golden/gaps updated deliberately to the
attached-comment form (assertions stay strict: exact output + lossless
round-trip). New textalign.test.ts (19 tests) covers center/right/justify on
paragraph and heading, byte-stable re-export, and fail-open branches.

Raw-HTML containers (columns/cells/callout via blockToHtml) keep the inline
text-align form intentionally — comments are dropped inside raw HTML.

package vitest: 462 passed | 1 expected-fail; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/attached-comment.ts               |  88 ++++++++++
 .../prosemirror-markdown/src/lib/index.ts     |   9 +
 .../src/lib/markdown-converter.ts             |  54 +++---
 .../src/lib/markdown-to-prosemirror.ts        |  64 ++++++-
 .../test/markdown-converter-gaps.test.ts      |  25 +--
 .../test/markdown-converter-golden.test.ts    |  19 +--
 .../test/textalign.test.ts                    | 160 ++++++++++++++++++
 7 files changed, 373 insertions(+), 46 deletions(-)
 create mode 100644 packages/prosemirror-markdown/src/lib/attached-comment.ts
 create mode 100644 packages/prosemirror-markdown/test/textalign.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/attached-comment.ts b/packages/prosemirror-markdown/src/lib/attached-comment.ts
new file mode 100644
index 00000000..5df81d00
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/attached-comment.ts
@@ -0,0 +1,88 @@
+/**
+ * Attached-comment convention (#293 canon).
+ *
+ * Some block-level attributes have no native markdown syntax (paragraph/heading
+ * `textAlign` — #9; image/media attrs — #4/#8). Rather than HTML-wrapping the
+ * whole block (the old `<div align>` / `<p style>` forms, which the maintainer
+ * had to patch repeatedly and which did not round-trip cleanly), we ATTACH a
+ * compact HTML comment at the END of the block's rendered line:
+ *
+ *     Some paragraph text <!--attrs {"textAlign":"center"}-->
+ *
+ * The comment is invisible in any markdown renderer and is dropped by the
+ * DOM/generateJSON import stage, so it can never leak into the document body.
+ * The importer intercepts it BEFORE that stage (see markdown-to-prosemirror's
+ * applyAttachedComments) and re-applies the encoded attributes to the node.
+ *
+ * This module holds the two PURE, reusable primitives of the convention so the
+ * serializer, the parser, and future decisions (#4 image, #8 media) share ONE
+ * implementation:
+ *   - `attachedCommentFor(name, json)` — build the comment string.
+ *   - `parseAttachedComment(data)`     — parse a comment node's data back.
+ */
+
+/**
+ * A parsed attached comment: the leading `name` token and the decoded JSON
+ * object payload (empty object when the comment carried no JSON body).
+ */
+export interface AttachedComment {
+  name: string;
+  attrs: Record<string, unknown>;
+}
+
+/**
+ * Grammar of an attached comment's DATA (the text between `<!--` and `-->`):
+ * a leading name token (`attrs`, `img`, …) optionally followed by whitespace
+ * and a single JSON object. The name deliberately does NOT allow `:` so the
+ * file-level envelope comments (`docmost:meta` / `docmost:comments`) never match
+ * and stay inert here.
+ */
+const ATTACHED_COMMENT_RE = /^\s*([A-Za-z][\w-]*)(?:\s+(\{[\s\S]*\}))?\s*$/;
+
+/**
+ * Build an attached HTML comment `<!--name {compact-json}-->` for `json`.
+ *
+ * The JSON is emitted compactly (no spaces) via `JSON.stringify`. A string value
+ * may legitimately contain two consecutive hyphens `--`, which would prematurely
+ * close the HTML comment (`-->`). We defuse that WITHOUT changing the decoded
+ * value: each hyphen of every `--` pair is rewritten as the JSON unicode escape
+ * `-`, so `JSON.parse` on the reading side restores the exact original
+ * hyphens. `--` can only occur inside a JSON string (structural JSON never
+ * produces it), so a blanket replace over the stringified payload is safe.
+ */
+export function attachedCommentFor(name: string, json: object): string {
+  const raw = JSON.stringify(json);
+  // Escape every hyphen that is part of a `--` pair. Scanning left-to-right and
+  // replacing each `--` handles odd runs too (`---` -> two escapes + one bare
+  // `-`, still `---` after JSON.parse).
+  const safe = raw.replace(/--/g, "\\u002d\\u002d");
+  return `<!--${name} ${safe}-->`;
+}
+
+/**
+ * Parse the DATA of a comment node into `{ name, attrs }`, or `null` when it is
+ * not a well-formed attached comment.
+ *
+ * Fail-open by design (maintainer spec): a comment whose name token is missing,
+ * whose JSON body is malformed, or whose body is not a plain object returns
+ * `null` so the caller ignores it and keeps default attributes. Unknown keys in
+ * a valid object are preserved here and filtered by the caller.
+ */
+export function parseAttachedComment(data: string): AttachedComment | null {
+  const m = ATTACHED_COMMENT_RE.exec(data);
+  if (!m) return null;
+  const name = m[1];
+  if (m[2] === undefined) {
+    // Name-only comment (no JSON body): a valid attached marker with no attrs.
+    return { name, attrs: {} };
+  }
+  try {
+    const parsed = JSON.parse(m[2]);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { name, attrs: parsed as Record<string, unknown> };
+    }
+    return null; // fail-open: payload is not a plain object
+  } catch {
+    return null; // fail-open: malformed JSON -> ignore the comment
+  }
+}
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
index f02713e5..f37c47b5 100644
--- a/packages/prosemirror-markdown/src/lib/index.ts
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -24,6 +24,15 @@ export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 // schema the converter targets.
 export { docmostExtensions } from "./docmost-schema.js";
 
+// Attached-comment convention (#293 canon #9/#4/#8): the reusable primitives
+// the serializer/parser use to encode attrs that have no native markdown syntax
+// as trailing `<!--name {json}-->` comments.
+export {
+  attachedCommentFor,
+  parseAttachedComment,
+} from "./attached-comment.js";
+export type { AttachedComment } from "./attached-comment.js";
+
 export {
   canonicalizeContent,
   docsCanonicallyEqual,
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 013a54f3..2a2a290d 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -1,4 +1,5 @@
 import { encodeHtmlEmbedSource } from "./docmost-schema.js";
+import { attachedCommentFor } from "./attached-comment.js";
 
 /**
  * Hard cap on processNode recursion depth (see the depth guard below).
@@ -138,38 +139,45 @@ export function convertProseMirrorToMarkdown(content: any): string {
       case "doc":
         return nodeContent.map(processNode).join("\n\n");
 
-      case "paragraph":
+      case "paragraph": {
         const text = nodeContent.map(processNode).join("");
         const align = node.attrs?.textAlign;
-        if (align && align !== "left") {
-          // Emit alignment as a styled `<p>` (review #10). The old
-          // `<div align="…">` had NO matching import parse rule — the div was
-          // unwrapped and alignment lost on every round trip. A styled `<p>`
-          // round-trips: the paragraph parse rule (tag:"p") matches and the
-          // textAlign global-attribute parseHTML (docmost-schema) reads the style.
-          return `<p style="text-align:${escapeAttr(align)}">${text}</p>`;
+        // Non-default alignment round-trips as an ATTACHED HTML comment at the
+        // END of the block line (#293 canon #9):
+        //   `some text <!--attrs {"textAlign":"center"}-->`
+        // This replaces the old `<p style="text-align:…">` wrapper (review #10,
+        // itself a replacement for the never-parsed `<div align>`). The schema's
+        // textAlign default is `null`; "left" is the visual default the editor
+        // renders identically to null — neither emits a marker (no churn). The
+        // importer's applyAttachedComments step reads the comment back before the
+        // DOM stage drops it. We only attach when there is text to attach to: a
+        // lone comment on a blank line has no block to bind to on re-import.
+        if (align && align !== "left" && text) {
+          return `${text} ${attachedCommentFor("attrs", { textAlign: align })}`;
         }
         return text || "";
+      }
 
-      case "heading":
+      case "heading": {
         const level = node.attrs?.level || 1;
         const headingText = nodeContent.map(processNode).join("");
+        const headingLine = "#".repeat(level) + " " + headingText;
         const headingAlign = node.attrs?.textAlign;
-        if (headingAlign && headingAlign !== "left") {
-          // Emit alignment as a styled `<hN>` so it round-trips losslessly,
-          // symmetric to the paragraph case above (review F5/A1). The bare
-          // `## text` markdown form carries NO alignment, so an aligned heading
-          // would silently drop textAlign on export. A styled `<hN>` re-parses:
-          // the heading parse rule (tag:"h1".."h6") matches and the textAlign
-          // global-attribute parseHTML (docmost-schema) reads the style back,
-          // preserving BOTH level and textAlign. escapeAttr keeps the align
-          // value injection-safe, exactly like the paragraph arm.
-          return `<h${level} style="text-align:${escapeAttr(headingAlign)}">${headingText}</h${level}>`;
+        // A non-default heading alignment attaches the same trailing comment
+        // (#293 canon #9), keeping the readable `## text` markdown form:
+        //   `## Title <!--attrs {"textAlign":"center"}-->`
+        // Bare `## text` carries no alignment, so without this an aligned heading
+        // would silently drop textAlign on export. Replaces the old
+        // `<hN style="text-align:…">` HTML form. "left"/null stay bare (no churn).
+        // Require headingText so an empty aligned heading stays bare `##` rather
+        // than emitting a comment with no visible element to attach to (matches
+        // the paragraph guard's `text` check — a lone comment has no block to
+        // bind on re-import).
+        if (headingAlign && headingAlign !== "left" && headingText) {
+          return `${headingLine} ${attachedCommentFor("attrs", { textAlign: headingAlign })}`;
         }
-        // No alignment (or the default "left"): keep the plain `## text`
-        // markdown form — HTML-ifying an unaligned heading would be needless
-        // churn, exactly as the paragraph case keeps plain text when unaligned.
-        return "#".repeat(level) + " " + headingText;
+        return headingLine;
+      }
 
       case "text":
         let textContent = node.text || "";
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index 4466edf4..73ed5eb1 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -11,6 +11,7 @@ import { generateJSON } from "@tiptap/html";
 import { JSDOM } from "jsdom";
 import { marked } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
+import { parseAttachedComment } from "./attached-comment.js";
 
 // Setup DOM environment for Tiptap HTML parsing in Node.js
 const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
@@ -315,6 +316,64 @@ function bridgeTaskLists(html: string): string {
   return document.body.innerHTML;
 }
 
+/**
+ * Re-apply ATTACHED HTML comments (#293 canon) before the DOM/generateJSON
+ * stage drops them.
+ *
+ * The serializer appends attributes that have no native markdown syntax as a
+ * trailing `<!--name {json}-->` comment on the block's line (see
+ * attached-comment.ts). `marked` keeps that comment as an HTML comment NODE
+ * inside the block element (`<p>text <!--attrs {…}--></p>`), but the next stage
+ * (parse5/jsdom via generateJSON) discards comment nodes, so the attributes
+ * would be lost. This pass runs on the post-`marked` HTML: for every attached
+ * comment it re-expresses the encoded attributes in a form the schema's
+ * parseHTML already understands, then removes the comment so it cannot leak.
+ *
+ * For #9 the only handled name is `attrs`, and the only handled key is
+ * `textAlign` on a paragraph/heading: it is written as an inline
+ * `text-align` style on the parent element, which the docmost-schema textAlign
+ * global attribute reads back. Fail-open everywhere: a malformed comment (null
+ * from parseAttachedComment), an unknown name, a comment whose parent is not a
+ * `<p>`/`<hN>`, or an unknown/empty attr value is left inert (the comment is
+ * dropped by generateJSON anyway). Future decisions (#4/#8) extend the
+ * per-name handling here without changing the parse primitive.
+ */
+function applyAttachedComments(html: string): string {
+  // Cheap early-out: no comments at all -> nothing to intercept.
+  if (!html.includes("<!--")) return html;
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const nodeFilter = dom.window.NodeFilter;
+  // Collect comment nodes first (mutating the tree while walking is unsafe).
+  const walker = document.createTreeWalker(
+    document.body,
+    nodeFilter.SHOW_COMMENT,
+  );
+  const comments: any[] = [];
+  let current: any;
+  while ((current = walker.nextNode())) comments.push(current);
+
+  for (const comment of comments) {
+    const parsed = parseAttachedComment(comment.data);
+    if (!parsed || parsed.name !== "attrs") continue; // inert / not for #9
+    const parent = comment.parentElement as any;
+    if (!parent) continue;
+    const tag = String(parent.tagName || "").toLowerCase();
+    const isBlock = tag === "p" || /^h[1-6]$/.test(tag);
+    if (!isBlock) continue; // misplaced comment -> inert
+    const align = parsed.attrs.textAlign;
+    if (typeof align === "string" && align) {
+      // Re-express as an inline style; the schema's textAlign parseHTML reads
+      // `el.style.textAlign` back onto the paragraph/heading node.
+      parent.style.textAlign = align;
+    }
+    // Consume the marker regardless (unknown keys are simply ignored) so no
+    // attached comment ever survives into the parsed body.
+    comment.remove();
+  }
+  return document.body.innerHTML;
+}
+
 /**
  * Recursively strip content-less paragraph nodes from a generated doc.
  *
@@ -359,7 +418,10 @@ export async function markdownToProseMirror(
 ): Promise<any> {
   const withCallouts = await preprocessCallouts(markdownContent);
   const html = await marked.parse(withCallouts);
-  const bridged = bridgeTaskLists(html);
+  // Re-apply attached-comment attributes (#293 #9 textAlign, …) while the
+  // comment nodes still exist, before generateJSON drops them.
+  const withAttrs = applyAttachedComments(html);
+  const bridged = bridgeTaskLists(withAttrs);
   const doc = generateJSON(bridged, docmostExtensions);
   return stripEmptyParagraphs(doc);
 }
diff --git a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
index 47ab05bc..f3e69944 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
@@ -786,11 +786,11 @@ describe('converter gap coverage — raw-HTML container round-trips (specs 15–
 });
 
 // ===========================================================================
-// 30. heading.textAlign round-trip (A1). The paragraph case already exports a
-// non-default alignment as a styled `<p style="text-align:…">` that re-parses
-// losslessly; headings used to emit only the bare `## text` form, silently
-// DROPPING textAlign on export. The heading case is now symmetric: an aligned
-// heading exports as `<hN style="text-align:…">` and re-parses back to a heading
+// 30. heading.textAlign round-trip (A1). Bare `## text` markdown carries no
+// alignment, so an aligned heading used to silently DROP textAlign on export.
+// Per #293 canon #9 an aligned heading now keeps the readable `## text` form and
+// ATTACHES a trailing `<!--attrs {"textAlign":…}-->` comment (replacing the old
+// `<hN style="text-align:…">` HTML form). It re-parses back to a heading
 // carrying BOTH the level and the textAlign, so the round-trip is lossless; an
 // UNaligned heading still emits the bare `## text` markdown form (no churn).
 // ===========================================================================
@@ -801,21 +801,22 @@ const alignedHeading = (level: number, align: string, ...inline: any[]) => ({
 });
 
 describe('heading.textAlign round-trip (A1)', () => {
-  it('an aligned heading exports as <hN style="text-align:…"> (not bare ##)', () => {
+  it('an aligned heading keeps "## text" and attaches a <!--attrs--> comment (#293 #9)', () => {
     expect(convertProseMirrorToMarkdown(doc(alignedHeading(2, 'center', text('Title'))))).toBe(
-      '<h2 style="text-align:center">Title</h2>',
+      '## Title <!--attrs {"textAlign":"center"}-->',
     );
   });
 
   it('survives export -> import -> export losslessly (level AND textAlign preserved)', async () => {
     const input = alignedHeading(2, 'center', text('Title'));
     const { md1, doc2, md2 } = await roundTrip(input);
-    // Export direction: a styled <hN>, injection-safe via escapeAttr.
-    expect(md1).toBe('<h2 style="text-align:center">Title</h2>');
+    // Export direction: `## Title` plus the attached alignment comment (#293 #9).
+    expect(md1).toBe('## Title <!--attrs {"textAlign":"center"}-->');
     // Import direction: re-parses to a heading node with the level AND textAlign
-    // (the raw <hN style> HTML block flows through marked -> generateJSON, where
-    // the heading parse rule matches and the textAlign global attr reads the
-    // style back). Byte-stable second export closes the loop.
+    // (marked keeps the comment inside the <h2>; applyAttachedComments re-expresses
+    // it as an inline style before generateJSON, where the heading parse rule
+    // matches and the textAlign global attr reads it back). Byte-stable second
+    // export closes the loop.
     const h = doc2.content[0];
     expect(h.type).toBe('heading');
     expect(h.attrs.level).toBe(2);
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
index f8ba6b76..0a4b69c0 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -129,20 +129,19 @@ describe('inline-mark matrix (underline/sub/sup/highlight±color/textStyle/comme
   });
 });
 
-describe('paragraph.textAlign -> <p style="text-align:...">', () => {
-  it('non-default alignment emits an HTML <p style="text-align:...">', () => {
-    // #7 fix: a non-default paragraph alignment now round-trips. It is exported
-    // as an HTML `<p style="text-align:center">` (the schema's paragraph
-    // parseHTML reads `style="text-align"` back onto `textAlign` on import), so
-    // the alignment survives instead of collapsing to bare text. (The old
-    // `<div align="center">` form was NOT re-parsed onto the paragraph and was
-    // therefore lossy.)
+describe('paragraph.textAlign -> attached <!--attrs--> comment (#293 #9)', () => {
+  it('non-default alignment emits a trailing <!--attrs {"textAlign":…}--> comment', () => {
+    // #293 canon #9: a non-default paragraph alignment now round-trips as an
+    // ATTACHED HTML comment at the END of the block line instead of the old
+    // `<p style="text-align:center">` wrapper (which the maintainer had to patch
+    // A14->A15->A16). The importer's applyAttachedComments step reads the comment
+    // back onto `textAlign` before the DOM stage drops it.
     expect(c({ type: 'paragraph', attrs: { textAlign: 'center' }, content: [text('x')] })).toBe(
-      '<p style="text-align:center">x</p>',
+      'x <!--attrs {"textAlign":"center"}-->',
     );
   });
 
-  it('textAlign "left" (the default) is NOT wrapped', () => {
+  it('textAlign "left" (the default) emits NO comment', () => {
     expect(c({ type: 'paragraph', attrs: { textAlign: 'left' }, content: [text('x')] })).toBe('x');
   });
 });
diff --git a/packages/prosemirror-markdown/test/textalign.test.ts b/packages/prosemirror-markdown/test/textalign.test.ts
new file mode 100644
index 00000000..7c8dcb89
--- /dev/null
+++ b/packages/prosemirror-markdown/test/textalign.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates global DOM at import time).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+import {
+  attachedCommentFor,
+  parseAttachedComment,
+} from '../src/lib/attached-comment.js';
+
+// #293 canon decision #9: paragraph/heading `textAlign` serializes as an
+// ATTACHED HTML comment at the END of the block line —
+//   `some text <!--attrs {"textAlign":"center"}-->`
+// — replacing the old `<div align>` / `<p style="text-align:…">` wrappers, which
+// did NOT round-trip cleanly (alignment was lost on the first stabilize pass).
+// These tests are non-vacuous: they assert the EXACT emitted markdown (so they
+// fail against any wrapper form) AND that the alignment survives a full
+// PM -> MD -> PM round trip (which the old `<div align>` never did).
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string) => ({ type: 'text', text: t });
+const para = (align: string | null, ...inline: any[]) => ({
+  type: 'paragraph',
+  attrs: align === null ? {} : { textAlign: align },
+  content: inline,
+});
+const heading = (level: number, align: string | null, ...inline: any[]) => ({
+  type: 'heading',
+  attrs: align === null ? { level } : { level, textAlign: align },
+  content: inline,
+});
+
+// Find the first paragraph/heading node in a generated doc (skips the doc root).
+const firstBlock = (d: any) => d.content?.[0];
+
+describe('attached-comment primitives (reusable for #9/#4/#8)', () => {
+  it('attachedCommentFor emits a compact `<!--name {json}-->`', () => {
+    expect(attachedCommentFor('attrs', { textAlign: 'center' })).toBe(
+      '<!--attrs {"textAlign":"center"}-->',
+    );
+  });
+
+  it('attachedCommentFor escapes a `--` pair so it cannot close the comment early', () => {
+    // A string value containing `--` would otherwise inject `-->`. Each hyphen of
+    // the pair is emitted as the JSON unicode escape -; JSON.parse restores
+    // the original hyphens on the reading side.
+    const s = attachedCommentFor('img', { alt: 'a--b' });
+    expect(s).toBe('<!--img {"alt":"a\\u002d\\u002db"}-->');
+    // No premature `--` inside the payload (between the `<!--` opener and the
+    // `-->` closer), so the comment cannot terminate early.
+    expect(s.slice(4, -3)).not.toContain('--');
+    // Round-trip through the parser primitive restores the exact value.
+    const inner = s.slice('<!--'.length, -'-->'.length);
+    expect(parseAttachedComment(inner)).toEqual({ name: 'img', attrs: { alt: 'a--b' } });
+  });
+
+  it('parseAttachedComment fails open on malformed JSON and non-objects', () => {
+    expect(parseAttachedComment('attrs {not json}')).toBeNull();
+    expect(parseAttachedComment('attrs [1,2]')).toBeNull();
+    expect(parseAttachedComment('   ')).toBeNull();
+    // Name-only comment is a valid marker with empty attrs.
+    expect(parseAttachedComment('attrs')).toEqual({ name: 'attrs', attrs: {} });
+  });
+});
+
+describe('paragraph.textAlign serialization (#293 #9)', () => {
+  for (const align of ['center', 'right', 'justify']) {
+    it(`paragraph textAlign "${align}" -> trailing <!--attrs--> comment`, () => {
+      expect(convertProseMirrorToMarkdown(doc(para(align, text('hello'))))).toBe(
+        `hello <!--attrs {"textAlign":"${align}"}-->`,
+      );
+    });
+  }
+
+  it('default textAlign (null) emits NO comment', () => {
+    expect(convertProseMirrorToMarkdown(doc(para(null, text('hello'))))).toBe('hello');
+  });
+
+  it('"left" (visual default) emits NO comment', () => {
+    expect(convertProseMirrorToMarkdown(doc(para('left', text('hello'))))).toBe('hello');
+  });
+});
+
+describe('heading.textAlign serialization (#293 #9)', () => {
+  it('heading keeps "## text" and attaches the alignment comment', () => {
+    expect(convertProseMirrorToMarkdown(doc(heading(2, 'center', text('Title'))))).toBe(
+      '## Title <!--attrs {"textAlign":"center"}-->',
+    );
+  });
+
+  it('default heading emits the bare "## text" form', () => {
+    expect(convertProseMirrorToMarkdown(doc(heading(3, null, text('Plain'))))).toBe('### Plain');
+  });
+});
+
+describe('paragraph.textAlign round-trip PM -> MD -> PM (#293 #9)', () => {
+  for (const align of ['center', 'right', 'justify']) {
+    it(`preserves paragraph textAlign "${align}"`, async () => {
+      const md1 = convertProseMirrorToMarkdown(doc(para(align, text('hello'))));
+      expect(md1).toBe(`hello <!--attrs {"textAlign":"${align}"}-->`);
+      const doc2 = await markdownToProseMirror(md1);
+      const block = firstBlock(doc2);
+      expect(block.type).toBe('paragraph');
+      expect(block.attrs.textAlign).toBe(align);
+      // Text is intact (the trailing space before the comment is trimmed).
+      expect(block.content?.[0]?.text).toBe('hello');
+      // Byte-stable second export closes the loop.
+      expect(convertProseMirrorToMarkdown(doc2)).toBe(md1);
+    });
+  }
+
+  it('default paragraph re-imports with textAlign null (no comment survives)', async () => {
+    const md1 = convertProseMirrorToMarkdown(doc(para(null, text('hello'))));
+    const doc2 = await markdownToProseMirror(md1);
+    const block = firstBlock(doc2);
+    expect(block.type).toBe('paragraph');
+    expect(block.attrs.textAlign ?? null).toBeNull();
+  });
+});
+
+describe('heading.textAlign round-trip PM -> MD -> PM (#293 #9)', () => {
+  for (const [level, align] of [
+    [2, 'center'],
+    [3, 'right'],
+    [1, 'justify'],
+  ] as [number, string][]) {
+    it(`preserves h${level} textAlign "${align}"`, async () => {
+      const md1 = convertProseMirrorToMarkdown(doc(heading(level, align, text('Head'))));
+      expect(md1).toBe(`${'#'.repeat(level)} Head <!--attrs {"textAlign":"${align}"}-->`);
+      const doc2 = await markdownToProseMirror(md1);
+      const block = firstBlock(doc2);
+      expect(block.type).toBe('heading');
+      expect(block.attrs.level).toBe(level);
+      expect(block.attrs.textAlign).toBe(align);
+      expect(convertProseMirrorToMarkdown(doc2)).toBe(md1);
+    });
+  }
+});
+
+describe('attached-comment fail-open in the import pipeline (#293 #9)', () => {
+  it('a malformed attrs comment is ignored (default attrs kept)', async () => {
+    const doc2 = await markdownToProseMirror('hello <!--attrs {bad json}-->');
+    const block = firstBlock(doc2);
+    expect(block.type).toBe('paragraph');
+    expect(block.attrs.textAlign ?? null).toBeNull();
+    expect(block.content?.[0]?.text).toBe('hello');
+  });
+
+  it('an unknown key in a valid attrs comment is ignored, no comment leaks', async () => {
+    const doc2 = await markdownToProseMirror('hello <!--attrs {"bogus":"x"}-->');
+    const block = firstBlock(doc2);
+    expect(block.type).toBe('paragraph');
+    expect(block.attrs.textAlign ?? null).toBeNull();
+    // The unknown key and the comment marker must not survive into the body.
+    expect(block.content?.[0]?.text).toBe('hello');
+    const serialized = JSON.stringify(doc2);
+    expect(serialized).not.toContain('bogus');
+    expect(serialized).not.toContain('<!--');
+  });
+});
-- 
2.52.0


From e814bca24367288b1ab401a732f9d6e7dd9e7fac Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 07:56:40 +0300
Subject: [PATCH 04/17] feat(prosemirror-markdown): subpages/pageBreak as
 standalone comments (#293 canon #5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the two "invisible machinery" atoms off the <div data-type="..."> HTML
form onto standalone HTML comments on their own line, keeping the markdown
human-readable while still round-tripping:
  subpages  -> <!--subpages-->  /  <!--subpages {"recursive":true}-->
  pageBreak -> <!--pagebreak-->

Adds standaloneCommentFor(name, attrs?) to attached-comment.ts (emits
`<!--name-->` when attrs are empty/absent, else `<!--name {compact-json}-->`).
The `--`-escaping + compact-JSON logic is factored into a shared internal
escapeCommentJson() so standaloneCommentFor and attachedCommentFor cannot drift
(verified byte-identical output for attachedCommentFor — no #9 regression).

Position determines legality (canon #5): subpages/pagebreak are honored ONLY
standalone; the same comment attached after visible text is inert. The parser
pass (applyAttachedComments renamed applyCommentDirectives) now also
materializes these standalone comments into the schema `<div data-type=...>`
element before generateJSON drops the comment node. A LEADING standalone
comment is parsed at document level (outside <body>); the pass walks the whole
document and re-inserts leading comments into <body> in document order, so
block order is preserved.

Raw-HTML path: blockToHtml gains explicit subpages/pageBreak cases emitting the
`<div data-type=...>` form. Comments are dropped by the DOM parse stage inside
columns/cells, so the div-form must stay there — this also fixes a latent
default-fallthrough (`<div></div>`) that silently dropped these atoms inside a
column.

Tests: new machinery-comments.test.ts (primitive, subpages default/recursive
exact strings + round-trip, pageBreak, subpages-inside-column div-form,
fail-open for attached-position/malformed, and multi-node document-order
regression locking the leading/mid/trailing comment ordering). Top-level
goldens in markdown-converter-golden/gaps updated deliberately to the comment
form; the columns/raw-HTML goldens keep the div-form.

package vitest: 477 passed | 1 expected-fail; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/attached-comment.ts               |  48 ++++-
 .../prosemirror-markdown/src/lib/index.ts     |   1 +
 .../src/lib/markdown-converter.ts             |  51 +++--
 .../src/lib/markdown-to-prosemirror.ts        |  97 +++++++--
 .../test/machinery-comments.test.ts           | 194 ++++++++++++++++++
 .../test/markdown-converter-gaps.test.ts      |  31 +--
 .../test/markdown-converter-golden.test.ts    |   4 +-
 7 files changed, 367 insertions(+), 59 deletions(-)
 create mode 100644 packages/prosemirror-markdown/test/machinery-comments.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/attached-comment.ts b/packages/prosemirror-markdown/src/lib/attached-comment.ts
index 5df81d00..29c6eb91 100644
--- a/packages/prosemirror-markdown/src/lib/attached-comment.ts
+++ b/packages/prosemirror-markdown/src/lib/attached-comment.ts
@@ -51,12 +51,48 @@ const ATTACHED_COMMENT_RE = /^\s*([A-Za-z][\w-]*)(?:\s+(\{[\s\S]*\}))?\s*$/;
  * produces it), so a blanket replace over the stringified payload is safe.
  */
 export function attachedCommentFor(name: string, json: object): string {
-  const raw = JSON.stringify(json);
-  // Escape every hyphen that is part of a `--` pair. Scanning left-to-right and
-  // replacing each `--` handles odd runs too (`---` -> two escapes + one bare
-  // `-`, still `---` after JSON.parse).
-  const safe = raw.replace(/--/g, "\\u002d\\u002d");
-  return `<!--${name} ${safe}-->`;
+  return `<!--${name} ${escapeCommentJson(json)}-->`;
+}
+
+/**
+ * Compactly stringify `json` and defuse any `--` pair so the payload can never
+ * close the HTML comment early. Shared by `attachedCommentFor` (attached form)
+ * and `standaloneCommentFor` (standalone form) so both stay in sync.
+ *
+ * A string value may legitimately contain two consecutive hyphens `--`, which
+ * would prematurely close the comment (`-->`). We defuse that WITHOUT changing
+ * the decoded value: each hyphen of every `--` pair is rewritten as the JSON
+ * unicode escape `-`, so `JSON.parse` on the reading side restores the exact
+ * original hyphens. `--` can only occur inside a JSON string (structural JSON
+ * never produces it), so a blanket replace over the stringified payload is safe.
+ * Scanning left-to-right and replacing each `--` handles odd runs too (`---` ->
+ * two escapes + one bare `-`, still `---` after JSON.parse).
+ */
+function escapeCommentJson(json: object): string {
+  return JSON.stringify(json).replace(/--/g, "\\u002d\\u002d");
+}
+
+/**
+ * Build a STANDALONE machinery comment (#293 canon #5) for a block node that
+ * lives on its OWN line, e.g. `<!--pagebreak-->` or `<!--subpages-->`.
+ *
+ * Grammar is identical to the attached form (`<!--name {JSON?}-->`), but the
+ * JSON body is emitted ONLY when there are real attributes to carry:
+ *   - `standaloneCommentFor("pagebreak")`            -> `<!--pagebreak-->`
+ *   - `standaloneCommentFor("subpages")`             -> `<!--subpages-->`
+ *   - `standaloneCommentFor("subpages", {recursive:true})`
+ *                                    -> `<!--subpages {"recursive":true}-->`
+ *
+ * When `attrs` is undefined/null/empty-object the comment is name-only (no JSON,
+ * which parses back to default attrs). Otherwise the JSON body is emitted with
+ * the SAME `--`-escaping as `attachedCommentFor` (via `escapeCommentJson`), so
+ * the standalone and attached encoders can never diverge.
+ */
+export function standaloneCommentFor(name: string, attrs?: object | null): string {
+  if (!attrs || Object.keys(attrs).length === 0) {
+    return `<!--${name}-->`;
+  }
+  return `<!--${name} ${escapeCommentJson(attrs)}-->`;
 }
 
 /**
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
index f37c47b5..8cdf55cc 100644
--- a/packages/prosemirror-markdown/src/lib/index.ts
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -29,6 +29,7 @@ export { docmostExtensions } from "./docmost-schema.js";
 // as trailing `<!--name {json}-->` comments.
 export {
   attachedCommentFor,
+  standaloneCommentFor,
   parseAttachedComment,
 } from "./attached-comment.js";
 export type { AttachedComment } from "./attached-comment.js";
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 2a2a290d..7ae3b7ab 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -1,5 +1,8 @@
 import { encodeHtmlEmbedSource } from "./docmost-schema.js";
-import { attachedCommentFor } from "./attached-comment.js";
+import {
+  attachedCommentFor,
+  standaloneCommentFor,
+} from "./attached-comment.js";
 
 /**
  * Hard cap on processNode recursion depth (see the depth guard below).
@@ -722,22 +725,25 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       case "pageBreak":
-        // Emit the schema-matching div[data-type="pageBreak"] so marked passes
-        // it through as a block and generateJSON rebuilds the pageBreak atom.
-        // Without this case the node fell through to `default` and rendered ""
-        // (the divider silently disappeared and could not round-trip).
-        return `<div data-type="pageBreak"></div>`;
+        // #293 canon #5: a pageBreak is a STANDALONE machinery comment on its
+        // own line — `<!--pagebreak-->` — which is invisible in any markdown
+        // renderer yet round-trips (the importer materializes it back into the
+        // pageBreak atom; see markdown-to-prosemirror's applyCommentDirectives).
+        // This keeps the markdown readable instead of leaking a raw <div>. The
+        // schema div-form is still emitted on the raw-HTML path (blockToHtml),
+        // because DOM parsers drop comment nodes inside columns/cells.
+        return standaloneCommentFor("pagebreak");
 
-      case "subpages": {
-        // Emit the schema-matching div[data-type="subpages"] so marked passes it
-        // through as a block and generateJSON rebuilds the subpages atom. The old
-        // `{{SUBPAGES}}` literal had no parseHTML inverse, so on import it stayed
-        // as plain text — the embed rendered as the literal "{{SUBPAGES}}" on the
-        // page after a round-trip (red-team: subpages round-trip data loss).
-        // `data-recursive` carries the recursive toggle so it round-trips too.
-        const recursive = node.attrs?.recursive ? ` data-recursive="true"` : "";
-        return `<div data-type="subpages"${recursive}></div>`;
-      }
+      case "subpages":
+        // #293 canon #5: a subpages block serializes as a STANDALONE comment —
+        // `<!--subpages-->` by default, or `<!--subpages {"recursive":true}-->`
+        // when the recursive toggle is set. Same rationale as pageBreak: readable
+        // markdown, invisible in renderers, re-materialized on import. The div
+        // form (`<div data-type="subpages">`) is retained on the raw-HTML path
+        // (blockToHtml) since comments cannot survive a DOM parse inside columns.
+        return node.attrs?.recursive
+          ? standaloneCommentFor("subpages", { recursive: true })
+          : standaloneCommentFor("subpages");
 
       case "status": {
         // Inline status pill. The schema reads the label from the element's
@@ -1033,6 +1039,19 @@ export function convertProseMirrorToMarkdown(content: any): string {
       // marked and would round-trip as literal "| a | b |" text (review #7).
       case "table":
         return tableToHtml(block.content || []);
+      // #293 canon #5: on the TOP-LEVEL path (processNode) subpages/pageBreak
+      // serialize as standalone `<!--...-->` comments, but a comment node is
+      // discarded by the DOM parse stage (jsdom/parse5) that reads back a raw-
+      // HTML block — so inside a column/cell the comment form would silently
+      // vanish (latent data loss; these atoms previously fell through to the
+      // `default` <div></div>). Here we KEEP the schema-matching div-form so the
+      // node survives the raw-HTML round trip.
+      case "pageBreak":
+        return `<div data-type="pageBreak"></div>`;
+      case "subpages": {
+        const recursive = block.attrs?.recursive ? ` data-recursive="true"` : "";
+        return `<div data-type="subpages"${recursive}></div>`;
+      }
       // columns/column, math, media, embed, attachment, mention, etc. already
       // emit schema-matching HTML from processNode.
       case "columns":
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index 73ed5eb1..f401781b 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -329,36 +329,87 @@ function bridgeTaskLists(html: string): string {
  * comment it re-expresses the encoded attributes in a form the schema's
  * parseHTML already understands, then removes the comment so it cannot leak.
  *
- * For #9 the only handled name is `attrs`, and the only handled key is
- * `textAlign` on a paragraph/heading: it is written as an inline
- * `text-align` style on the parent element, which the docmost-schema textAlign
- * global attribute reads back. Fail-open everywhere: a malformed comment (null
- * from parseAttachedComment), an unknown name, a comment whose parent is not a
- * `<p>`/`<hN>`, or an unknown/empty attr value is left inert (the comment is
- * dropped by generateJSON anyway). Future decisions (#4/#8) extend the
- * per-name handling here without changing the parse primitive.
+ * This pass materializes BOTH comment conventions, discriminated by position:
+ *
+ *   - ATTACHED comments (#9 `attrs`): a comment sitting INSIDE a `<p>`/`<hN>`
+ *     (same rendered line as visible content). The only handled key is
+ *     `textAlign`, re-expressed as an inline `text-align` style on the parent,
+ *     which the docmost-schema textAlign global attribute reads back.
+ *   - STANDALONE machinery comments (#5 `subpages`/`pagebreak`): a lone comment
+ *     line, which `marked` renders as an HTML block so jsdom makes it a DIRECT
+ *     child of `<body>`. These are replaced with the schema-matching block div
+ *     (`<div data-type="pageBreak">` / `<div data-type="subpages" [data-recursive]>`)
+ *     that the schema's parseHTML rebuilds into the atom.
+ *
+ * Position determines legality: an `attrs` comment is honored only in attached
+ * position, a `subpages`/`pagebreak` comment only in standalone position; a
+ * comment in the wrong position is left INERT (generateJSON drops it). Fail-open
+ * everywhere: a malformed comment (null from parseAttachedComment), an unknown
+ * name, a wrong-position comment, or an unknown/empty attr value is ignored.
+ * Future decisions (#4/#8) extend the per-name handling here without changing
+ * the parse primitive.
  */
-function applyAttachedComments(html: string): string {
+function applyCommentDirectives(html: string): string {
   // Cheap early-out: no comments at all -> nothing to intercept.
   if (!html.includes("<!--")) return html;
   const dom = new JSDOM(html);
   const document = dom.window.document;
   const nodeFilter = dom.window.NodeFilter;
-  // Collect comment nodes first (mutating the tree while walking is unsafe).
-  const walker = document.createTreeWalker(
-    document.body,
-    nodeFilter.SHOW_COMMENT,
-  );
+  // Walk the WHOLE document, not just <body>: when a standalone machinery
+  // comment is the FIRST thing in the output (before any body content), the
+  // HTML parser places it at document level (a child of `#document`, before
+  // `<html>`), where it is outside `document.body` and would be lost. Attached
+  // attrs comments always live inside body, so this wider walk still finds them.
+  const walker = document.createTreeWalker(document, nodeFilter.SHOW_COMMENT);
   const comments: any[] = [];
   let current: any;
   while ((current = walker.nextNode())) comments.push(current);
 
+  // Standalone machinery comments that were parsed at document level (leading,
+  // before body content) must be MOVED into body — in document order — since we
+  // return `document.body.innerHTML`. Because the parser only puts LEADING
+  // comments at document level, prepending them to body preserves global order.
+  const leadingDivs: any[] = [];
+
   for (const comment of comments) {
     const parsed = parseAttachedComment(comment.data);
-    if (!parsed || parsed.name !== "attrs") continue; // inert / not for #9
+    if (!parsed) continue; // malformed -> inert (dropped by generateJSON)
     const parent = comment.parentElement as any;
-    if (!parent) continue;
-    const tag = String(parent.tagName || "").toLowerCase();
+    const tag = String(parent?.tagName || "").toLowerCase();
+
+    if (parsed.name === "subpages" || parsed.name === "pagebreak") {
+      // #293 canon #5 STANDALONE machinery. A lone comment line is rendered by
+      // marked as an HTML block; the parser places it either directly under
+      // <body> (when other content surrounds it) or at document level (when it
+      // leads the output). Both are STANDALONE position. A `subpages`/`pagebreak`
+      // comment sitting inside a `<p>`/`<hN>` (or any other element) is attached
+      // position -> INERT.
+      const standalone = tag === "" || tag === "body" || tag === "html";
+      if (!standalone) continue; // wrong position -> inert
+      const div = document.createElement("div");
+      if (parsed.name === "pagebreak") {
+        div.setAttribute("data-type", "pageBreak");
+      } else {
+        div.setAttribute("data-type", "subpages");
+        if (parsed.attrs.recursive === true) {
+          div.setAttribute("data-recursive", "true");
+        }
+      }
+      if (tag === "body") {
+        // In-body: replace in place so surrounding content keeps its order.
+        comment.replaceWith(div);
+      } else {
+        // Document-level (leading): drop the stray comment and queue the div to
+        // be prepended into body below.
+        comment.remove();
+        leadingDivs.push(div);
+      }
+      continue;
+    }
+
+    if (!parent) continue; // attrs comment must have an element parent
+    if (parsed.name !== "attrs") continue; // unknown name -> inert
+    // #293 canon #9 ATTACHED attrs: honored only in attached position.
     const isBlock = tag === "p" || /^h[1-6]$/.test(tag);
     if (!isBlock) continue; // misplaced comment -> inert
     const align = parsed.attrs.textAlign;
@@ -371,6 +422,11 @@ function applyAttachedComments(html: string): string {
     // attached comment ever survives into the parsed body.
     comment.remove();
   }
+  // Prepend any document-level (leading) standalone divs into body, preserving
+  // their document order relative to each other and ahead of existing content.
+  for (let i = leadingDivs.length - 1; i >= 0; i--) {
+    document.body.insertBefore(leadingDivs[i], document.body.firstChild);
+  }
   return document.body.innerHTML;
 }
 
@@ -418,9 +474,10 @@ export async function markdownToProseMirror(
 ): Promise<any> {
   const withCallouts = await preprocessCallouts(markdownContent);
   const html = await marked.parse(withCallouts);
-  // Re-apply attached-comment attributes (#293 #9 textAlign, …) while the
-  // comment nodes still exist, before generateJSON drops them.
-  const withAttrs = applyAttachedComments(html);
+  // Materialize comment directives (#293 #9 attached textAlign; #5 standalone
+  // subpages/pageBreak) while the comment nodes still exist, before generateJSON
+  // drops them.
+  const withAttrs = applyCommentDirectives(html);
   const bridged = bridgeTaskLists(withAttrs);
   const doc = generateJSON(bridged, docmostExtensions);
   return stripEmptyParagraphs(doc);
diff --git a/packages/prosemirror-markdown/test/machinery-comments.test.ts b/packages/prosemirror-markdown/test/machinery-comments.test.ts
new file mode 100644
index 00000000..f8674091
--- /dev/null
+++ b/packages/prosemirror-markdown/test/machinery-comments.test.ts
@@ -0,0 +1,194 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (NOT the docmost-client barrel, which pulls in
+// collaboration.ts and mutates the global DOM at import time), matching the
+// other converter unit tests.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+import { standaloneCommentFor } from '../src/lib/attached-comment.js';
+
+// #293 canon decision #5: `subpages` and `pageBreak` serialize as STANDALONE
+// HTML comments on their own line —
+//   <!--subpages-->            <!--subpages {"recursive":true}-->   <!--pagebreak-->
+// — invisible in any markdown renderer, yet round-tripping (the importer
+// materializes them back into the block atom before generateJSON drops the
+// comment). Position determines legality: they are honored ONLY standalone; a
+// comment attached after visible text is INERT. Inside a raw-HTML container
+// (columns/cells) the DOM parse stage discards comment nodes, so there the
+// schema `<div data-type="...">` form is emitted instead. These tests assert the
+// EXACT emitted markdown and a lossless round trip (non-vacuous).
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string) => ({ type: 'text', text: t });
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// Recursively collect every node type present in a doc.
+const collectTypes = (n: any, set = new Set<string>()): Set<string> => {
+  if (!n || typeof n !== 'object') return set;
+  if (n.type) set.add(n.type);
+  if (Array.isArray(n.content)) n.content.forEach((c: any) => collectTypes(c, set));
+  return set;
+};
+
+// Find the subpages node anywhere in a doc (for attribute assertions).
+const findNode = (n: any, type: string): any => {
+  if (!n || typeof n !== 'object') return undefined;
+  if (n.type === type) return n;
+  if (Array.isArray(n.content)) {
+    for (const c of n.content) {
+      const hit = findNode(c, type);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+};
+
+describe('standaloneCommentFor primitive (#293 #5)', () => {
+  it('emits a name-only comment when there are no attrs', () => {
+    expect(standaloneCommentFor('pagebreak')).toBe('<!--pagebreak-->');
+    expect(standaloneCommentFor('subpages')).toBe('<!--subpages-->');
+    expect(standaloneCommentFor('subpages', {})).toBe('<!--subpages-->');
+    expect(standaloneCommentFor('subpages', null)).toBe('<!--subpages-->');
+  });
+
+  it('emits a compact JSON body when attrs are present', () => {
+    expect(standaloneCommentFor('subpages', { recursive: true })).toBe(
+      '<!--subpages {"recursive":true}-->',
+    );
+  });
+
+  it('shares the attached encoder `--` escaping (payload cannot close early)', () => {
+    const s = standaloneCommentFor('subpages', { note: 'a--b' });
+    expect(s).toBe('<!--subpages {"note":"a\\u002d\\u002db"}-->');
+    // No premature `--` inside the payload -> the comment cannot terminate early.
+    expect(s.slice('<!--'.length, -'-->'.length)).not.toContain('--');
+  });
+});
+
+describe('subpages standalone serialization (#293 #5)', () => {
+  it('default subpages -> exactly <!--subpages-->', () => {
+    expect(convertProseMirrorToMarkdown(doc({ type: 'subpages' }))).toBe('<!--subpages-->');
+  });
+
+  it('markdown <!--subpages--> -> a subpages node, byte-stable re-export', async () => {
+    const md = '<!--subpages-->';
+    const doc2 = await markdownToProseMirror(md);
+    expect(collectTypes(doc2).has('subpages')).toBe(true);
+    expect(convertProseMirrorToMarkdown(doc2)).toBe(md);
+  });
+
+  it('recursive subpages -> <!--subpages {"recursive":true}--> and round-trips recursive:true', async () => {
+    const md = convertProseMirrorToMarkdown(
+      doc({ type: 'subpages', attrs: { recursive: true } }),
+    );
+    expect(md).toBe('<!--subpages {"recursive":true}-->');
+    const doc2 = await markdownToProseMirror(md);
+    const node = findNode(doc2, 'subpages');
+    expect(node).toBeTruthy();
+    expect(node.attrs.recursive).toBe(true);
+    // Byte-stable second export closes the loop.
+    expect(convertProseMirrorToMarkdown(doc2)).toBe(md);
+  });
+});
+
+describe('pageBreak standalone serialization (#293 #5)', () => {
+  it('pageBreak -> exactly <!--pagebreak-->', () => {
+    expect(convertProseMirrorToMarkdown(doc({ type: 'pageBreak' }))).toBe('<!--pagebreak-->');
+  });
+
+  it('markdown <!--pagebreak--> round-trips to a pageBreak node, byte-stable', async () => {
+    const md = '<!--pagebreak-->';
+    const doc2 = await markdownToProseMirror(md);
+    expect(collectTypes(doc2).has('pageBreak')).toBe(true);
+    expect(convertProseMirrorToMarkdown(doc2)).toBe(md);
+  });
+});
+
+describe('subpages inside a column uses the div-form, not a comment (#293 #5)', () => {
+  // A column is a raw-HTML block: the DOM parse stage discards comment nodes, so
+  // a comment inside it would silently vanish. The converter MUST emit the
+  // schema div-form there instead.
+  const columnsDoc = doc({
+    type: 'columns',
+    content: [
+      { type: 'column', attrs: { width: '50%' }, content: [{ type: 'subpages' }] },
+      { type: 'column', attrs: { width: '50%' }, content: [para(text('side'))] },
+    ],
+  });
+
+  it('serializes the column subpages as <div data-type="subpages">, not <!--subpages-->', () => {
+    const md = convertProseMirrorToMarkdown(columnsDoc);
+    expect(md).toContain('data-type="subpages"');
+    // The bare standalone comment must NOT appear inside the raw-HTML column.
+    expect(md).not.toContain('<!--subpages-->');
+  });
+
+  it('round-trips back to a subpages node still inside a column', async () => {
+    const md = convertProseMirrorToMarkdown(columnsDoc);
+    const doc2 = await markdownToProseMirror(md);
+    const column = findNode(doc2, 'column');
+    expect(column).toBeTruthy();
+    expect(collectTypes(column).has('subpages')).toBe(true);
+  });
+});
+
+describe('position legality / fail-open (#293 #5)', () => {
+  it('an ATTACHED <!--subpages--> after paragraph text is INERT (no subpages node)', async () => {
+    const doc2 = await markdownToProseMirror('para text <!--subpages-->');
+    expect(collectTypes(doc2).has('subpages')).toBe(false);
+    // The paragraph text survives, and no comment marker leaks into the body.
+    expect(JSON.stringify(doc2)).not.toContain('<!--');
+  });
+
+  it('a malformed <!--subpages {bad--> is INERT (no crash, no subpages node)', async () => {
+    const doc2 = await markdownToProseMirror('<!--subpages {bad-->');
+    expect(collectTypes(doc2).has('subpages')).toBe(false);
+  });
+});
+
+describe('multi-node document order across standalone comments (#293 #5)', () => {
+  // The riskiest part of the parser change: a LEADING standalone comment is
+  // parsed at document level (outside <body>) and must be re-inserted into the
+  // body in document order, interleaved correctly with real block content. A
+  // MID-document comment (pageBreak here) exercises the in-body branch. This
+  // locks the ordering the review flagged as covered only by manual checks.
+  const topTypes = (d: any) => (d.content || []).map((n: any) => n.type);
+
+  it('leading + mid + trailing standalone comments keep document order', async () => {
+    const d = doc(
+      { type: 'subpages' }, // leading -> parsed at document level
+      para(text('a')),
+      { type: 'pageBreak' }, // mid -> parsed in-body
+      para(text('b')),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe('<!--subpages-->\n\na\n\n<!--pagebreak-->\n\nb');
+    const d2 = await markdownToProseMirror(md);
+    // Order must be preserved exactly, not just membership.
+    expect(topTypes(d2)).toEqual([
+      'subpages',
+      'paragraph',
+      'pageBreak',
+      'paragraph',
+    ]);
+    // And byte-stable on re-export.
+    expect(convertProseMirrorToMarkdown(d2)).toBe(md);
+  });
+
+  it('two leading standalone comments keep their relative order', async () => {
+    const d = doc({ type: 'subpages' }, { type: 'pageBreak' }, para(text('x')));
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe('<!--subpages-->\n\n<!--pagebreak-->\n\nx');
+    const d2 = await markdownToProseMirror(md);
+    expect(topTypes(d2)).toEqual(['subpages', 'pageBreak', 'paragraph']);
+    expect(convertProseMirrorToMarkdown(d2)).toBe(md);
+  });
+
+  it('a trailing standalone comment stays last', async () => {
+    const d = doc(para(text('x')), { type: 'subpages' });
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe('x\n\n<!--subpages-->');
+    const d2 = await markdownToProseMirror(md);
+    expect(topTypes(d2)).toEqual(['paragraph', 'subpages']);
+    expect(convertProseMirrorToMarkdown(d2)).toBe(md);
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
index f3e69944..b3d8839b 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
@@ -36,29 +36,30 @@ async function roundTrip(node: any): Promise<{ md1: string; doc2: any; md2: stri
 // existing documented `it.fails` bugs in markdown-roundtrip.property.test.ts).
 // ---------------------------------------------------------------------------
 describe('pageBreak data loss (no converter case — SPEC §11 divergence)', () => {
-  it('exports a pageBreak node to the schema-matching block div', () => {
-    // FIXED: a standalone pageBreak now emits the block-level HTML div so the
-    // node survives instead of being erased to "".
+  it('exports a pageBreak node to the standalone comment (#293 #5)', () => {
+    // #293 canon #5: a standalone pageBreak now serializes as the readable,
+    // renderer-invisible comment `<!--pagebreak-->` (re-materialized on import),
+    // instead of the earlier raw <div> block.
     expect(convertProseMirrorToMarkdown(doc({ type: 'pageBreak' }))).toBe(
-      '<div data-type="pageBreak"></div>',
+      '<!--pagebreak-->',
     );
   });
 
   it('keeps a pageBreak sitting BETWEEN two paragraphs on export', () => {
-    // FIXED: with surrounding content the divider is emitted as its own block
+    // With surrounding content the divider is emitted as its own comment line
     // between the two paragraphs (joined by the doc "\n\n"), no longer dropped.
     const out = convertProseMirrorToMarkdown(
       doc(para(text('before')), { type: 'pageBreak' }, para(text('after'))),
     );
     expect(out).toBe(
-      'before\n\n<div data-type="pageBreak"></div>\n\nafter',
+      'before\n\n<!--pagebreak-->\n\nafter',
     );
-    expect(out).toContain('pageBreak');
+    expect(out).toContain('<!--pagebreak-->');
   });
 
   // FIXED: a pageBreak node now survives an export -> import -> export cycle
-  // because the FIRST export emits the schema-matching block div, which marked
-  // passes through and generateJSON rebuilds into a pageBreak node again.
+  // because the FIRST export emits the standalone comment, which the importer
+  // materializes back into a pageBreak node again.
   it('a pageBreak node round-trips (export -> import yields a pageBreak)', async () => {
     const { md1, doc2 } = await roundTrip({ type: 'pageBreak' });
     expect(md1).not.toBe('');
@@ -68,18 +69,18 @@ describe('pageBreak data loss (no converter case — SPEC §11 divergence)', ()
 });
 
 // ---------------------------------------------------------------------------
-// 2. subpages round-trip (`case "subpages"` emits the schema-matching div).
+// 2. subpages round-trip (#293 #5 standalone comment).
 //
 // It used to emit the literal `{{SUBPAGES}}`, which has no markdown/HTML meaning,
 // so on re-import the subpages BLOCK came back as a plain PARAGRAPH carrying the
 // literal string (the embed rendered as visible "{{SUBPAGES}}" text on the page
-// after a sync — data loss). It now emits `<div data-type="subpages">` like the
-// other embed nodes, so the schema's parseHTML rebuilds the subpages node.
+// after a sync — data loss). Per canon #5 it now emits the standalone comment
+// `<!--subpages-->`, which the importer materializes back into a subpages node.
 // ---------------------------------------------------------------------------
-describe('subpages round-trip (schema-matching div)', () => {
-  it('emits the subpages div and re-imports as a subpages node (no literal leak)', async () => {
+describe('subpages round-trip (standalone comment #293 #5)', () => {
+  it('emits the subpages comment and re-imports as a subpages node (no literal leak)', async () => {
     const { md1, doc2 } = await roundTrip({ type: 'subpages' });
-    expect(md1).toBe('<div data-type="subpages"></div>');
+    expect(md1).toBe('<!--subpages-->');
 
     const collect = (n: any): string[] => [
       n.type,
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
index 0a4b69c0..2a8ca1eb 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -147,8 +147,8 @@ describe('paragraph.textAlign -> attached <!--attrs--> comment (#293 #9)', () =>
 });
 
 describe('subpages token + unknown-in-container fallback', () => {
-  it('subpages emits the schema-matching div (round-trips, unlike the old {{SUBPAGES}} literal)', () => {
-    expect(c({ type: 'subpages' })).toBe('<div data-type="subpages"></div>');
+  it('subpages emits the standalone comment (#293 #5, unlike the old {{SUBPAGES}} literal)', () => {
+    expect(c({ type: 'subpages' })).toBe('<!--subpages-->');
   });
 
   it('an unknown block inside a raw-HTML container is wrapped in <div> (never markdown)', () => {
-- 
2.52.0


From d7d8db21026fb46698e3ed660a5b771a904927c1 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 08:16:28 +0300
Subject: [PATCH 05/17] feat(prosemirror-markdown): images as ![alt](src) +
 attached img-comment (#293 canon #4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every image now serializes as `![alt](src)`; non-default layout/identity attrs
that markdown cannot express ride along in an attached `<!--img {…}-->` comment
on the same line, replacing the prior "image-with-attrs -> raw <img>" split for
the top-level path:
  ![схема](/s.png) <!--img {"width":"420","align":"left","attachmentId":"…"}-->

Keys (emitted only when non-default, stable order): width, height, align, size,
aspectRatio, attachmentId, caption, title. Numeric sizing attrs are stringified
in the payload (the import side reads DOM attributes back as strings), so a
numeric `width:420` round-trips byte-stably instead of churning `420 -> "420"`.
attachedCommentFor defuses any `--` in a value (e.g. a caption containing the
comment-closing `-->`) so the payload can never close the comment early.

Align default unified to "center" (#293 canon #4): editor-ext declares
image.align default "center" while this package's schema declared null — keeping
null would make the clean `![](src)` form dead code (every editor image is
"center"). Now the schema default is "center" (docmost-schema image align, with
explicit parseHTML/renderHTML), canonicalize KNOWN_DEFAULTS drops align=="center"
for image, and the serializer omits align when it is null OR "center". A null
align collapses to "center" on re-import (a null align is not a distinct editor
state) — stable, no ping-pong. Only left/right emit a comment.

Import: applyCommentDirectives gains an `img` handler that targets the comment's
previousElementSibling <img> and writes each decoded key to the DOM attribute
the schema reads (align, width, height, data-size, data-aspect-ratio,
data-attachment-id, data-caption, title), then removes the comment. Attached
only: a standalone `<!--img-->` with no adjacent image is inert. Fail-open on
malformed JSON / unknown keys.

Raw-HTML path unchanged in spirit: images inside columns/cells keep the
`<img …>` form (comments are dropped by the DOM parse stage); imageToHtml now
omits a redundant align="center" to match the unified default.

Tests: new image-comment.test.ts (21 cases incl. caption == `-->`, numeric-size
byte-stability, image-in-column <img> form, fail-open). Goldens updated
deliberately: markdown-roundtrip-spoiler-caption (captioned image -> comment
form), markdown-converter-gaps spec 14/15 (title now round-trips via comment;
column image drops redundant align), canonicalize-extra (center+null dropped,
left kept).

package vitest: 498 passed | 1 expected-fail; tsc clean. git-sync (rebuilt
build): 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/canonicalize.ts                   |  11 +-
 .../src/lib/docmost-schema.ts                 |  17 +-
 .../src/lib/markdown-converter.ts             |  69 +++--
 .../src/lib/markdown-to-prosemirror.ts        |  38 +++
 .../test/canonicalize-extra.test.ts           |  21 +-
 .../test/image-comment.test.ts                | 244 ++++++++++++++++++
 .../test/markdown-converter-gaps.test.ts      |  16 +-
 ...markdown-roundtrip-spoiler-caption.test.ts |  10 +-
 8 files changed, 378 insertions(+), 48 deletions(-)
 create mode 100644 packages/prosemirror-markdown/test/image-comment.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/canonicalize.ts b/packages/prosemirror-markdown/src/lib/canonicalize.ts
index 99ff5bc6..25fbc921 100644
--- a/packages/prosemirror-markdown/src/lib/canonicalize.ts
+++ b/packages/prosemirror-markdown/src/lib/canonicalize.ts
@@ -45,9 +45,11 @@
  *       converter coercing numeric `width`/`height` to strings, which is outside
  *       canonicalize's scope.
  *
- * NOTE: `image` has NO non-null align default — its `align` defaults to `null`
- * (docmost-schema.ts L174), so it is already handled by the null-drop rule and
- * is intentionally NOT listed here.
+ * NOTE: `image` align now defaults to `"center"` — unified with editor-ext
+ * (#293 canon #4). It is listed below so a canonical image drops `align` when
+ * it equals "center" (absent ≡ default), exactly like the diagram/media nodes.
+ * A null align is likewise dropped by the null-drop rule and re-imports as the
+ * "center" default, so bare `![](src)` images stay canonically clean.
  */
 const KNOWN_DEFAULTS: Record<string, Record<string, unknown>> = {
   // mark types
@@ -62,6 +64,9 @@ const KNOWN_DEFAULTS: Record<string, Record<string, unknown>> = {
   orderedList: {
     start: 1,
   },
+  image: {
+    align: "center",
+  },
   drawio: {
     align: "center",
   },
diff --git a/packages/prosemirror-markdown/src/lib/docmost-schema.ts b/packages/prosemirror-markdown/src/lib/docmost-schema.ts
index 276efe90..1a63ec95 100644
--- a/packages/prosemirror-markdown/src/lib/docmost-schema.ts
+++ b/packages/prosemirror-markdown/src/lib/docmost-schema.ts
@@ -256,7 +256,22 @@ const DocmostAttributes = Extension.create({
       {
         types: ["image"],
         attributes: {
-          align: { default: null },
+          // #293 canon #4: the image `align` default is unified to "center"
+          // (matching editor-ext, the source of real user documents) so an
+          // editor-authored image — which is always align="center" — serializes
+          // as the clean `![](src)` form with NO attached comment, and only a
+          // genuinely non-default alignment (left/right) emits an `<!--img-->`
+          // comment. The DOM attribute name stays `align` (imageToHtml already
+          // round-trips it as align="…"); only the DEFAULT value changed from
+          // null to "center". parseHTML reads the `align` attribute so a bare
+          // <img> with no align falls back to "center", and <img align="left">
+          // reads "left".
+          align: {
+            default: "center",
+            parseHTML: (el: HTMLElement) => el.getAttribute("align") || "center",
+            renderHTML: (attrs: Record<string, any>) =>
+              attrs.align && attrs.align !== "center" ? { align: attrs.align } : {},
+          },
           // imageToHtml emits these Docmost-specific image attrs as data-*; map
           // them back explicitly so a top-level image (or one inside a column)
           // round-trips them. Without a parseHTML the default reads the bare
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 7ae3b7ab..60260bfa 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -364,38 +364,49 @@ export function convertProseMirrorToMarkdown(content: any): string {
 
       case "image": {
         const imgAttrs = node.attrs || {};
-        // A top-level image with layout/identity attrs beyond src/alt cannot be
-        // expressed by markdown `![](src)` — width/height/align/size/
-        // attachmentId/aspectRatio would be silently dropped on export and lost
-        // on re-import. Emit the SAME schema-matching <img> used inside columns
-        // (imageToHtml) so those attrs survive the round-trip. A bare image
-        // (only src/alt, optionally a title — which has no schema attr) keeps
-        // the lighter markdown form so existing image round-trip tests hold.
-        const hasLayoutAttrs =
-          imgAttrs.width != null ||
-          imgAttrs.height != null ||
-          imgAttrs.align ||
-          imgAttrs.size != null ||
-          imgAttrs.attachmentId ||
-          imgAttrs.aspectRatio != null ||
-          // A caption (issue #221) cannot be expressed by markdown `![](src)`,
-          // so route a captioned image through imageToHtml's raw <img> form
-          // (data-caption) — the same lossless form used for the other
-          // Docmost-specific image attrs.
-          imgAttrs.caption;
-        if (hasLayoutAttrs) {
-          return imageToHtml(node);
-        }
+        // #293 canon #4: a top-level image ALWAYS serializes as `![alt](src)`.
+        // Non-default layout/identity attrs (which markdown `![](src)` cannot
+        // express — width/height/align/size/attachmentId/aspectRatio/caption/
+        // title) are carried in an attached `<!--img {…}-->` comment on the SAME
+        // line, materialized back onto the <img> by markdown-to-prosemirror's
+        // applyCommentDirectives before generateJSON drops the comment.
         const imgAlt = imgAttrs.alt || "";
         // Neutralize characters that could break out of the markdown image
         // URL: spaces/newlines and parentheses would terminate the (...) target
         // and let a stored src inject following markdown/HTML. Percent-encode
         // them so the URL stays a single inert token.
         const imgSrc = encodeMdUrl(imgAttrs.src);
-        // A bare image (only src/alt, optionally a title) has no caption, so the
-        // lighter markdown form is lossless here; captioned images took the
-        // imageToHtml branch above.
-        return `![${imgAlt}](${imgSrc})`;
+        const base = `![${imgAlt}](${imgSrc})`;
+        // Build the img-comment JSON from the NON-DEFAULT attrs only, in a
+        // STABLE key order so the output is deterministic. An attr equal to its
+        // schema default is NOT emitted (predicate over the canonicalized attrs).
+        const json: Record<string, unknown> = {};
+        // Numeric sizing attrs are coerced to string in the payload: the import
+        // side (applyCommentDirectives) writes them as DOM attributes and the
+        // schema's parseHTML reads them back as strings, so a numeric value would
+        // otherwise round-trip as `420 -> "420"` and produce a one-time spurious
+        // git diff. Emitting the string form up front keeps the round-trip
+        // byte-stable whether the source attr was a number or a string (mirrors
+        // the legacy imageToHtml, which stringified via `width="…"`).
+        if (imgAttrs.width != null) json.width = String(imgAttrs.width);
+        if (imgAttrs.height != null) json.height = String(imgAttrs.height);
+        // align default is unified to "center" (#293 canon #4): treat BOTH null
+        // and "center" as the default and omit them, so a bare/center image stays
+        // clean `![](src)` and only left/right emits `"align"`.
+        if (imgAttrs.align != null && imgAttrs.align !== "center")
+          json.align = imgAttrs.align;
+        if (imgAttrs.size != null) json.size = String(imgAttrs.size);
+        if (imgAttrs.aspectRatio != null)
+          json.aspectRatio = String(imgAttrs.aspectRatio);
+        if (imgAttrs.attachmentId) json.attachmentId = imgAttrs.attachmentId;
+        if (imgAttrs.caption) json.caption = imgAttrs.caption;
+        if (imgAttrs.title) json.title = imgAttrs.title;
+        // No non-default attrs -> bare image, no trailing space, no comment.
+        if (Object.keys(json).length === 0) return base;
+        // attachedCommentFor defuses any `--` in a value (e.g. a caption that
+        // contains the comment-closing `-->`) so the payload can never close the
+        // HTML comment early; JSON.parse on the import side restores it verbatim.
+        return `${base} ${attachedCommentFor("img", json)}`;
       }
 
       case "video": {
@@ -905,7 +916,11 @@ export function convertProseMirrorToMarkdown(content: any): string {
     if (attrs.title) parts.push(`title="${escapeAttr(attrs.title)}"`);
     if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
     if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
-    if (attrs.align) parts.push(`align="${escapeAttr(attrs.align)}"`);
+    // #293 canon #4: image align default is unified to "center", so a center
+    // (or unset) image no longer emits a redundant align="center" here — only a
+    // genuinely non-default alignment (left/right) is written.
+    if (attrs.align && attrs.align !== "center")
+      parts.push(`align="${escapeAttr(attrs.align)}"`);
     if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
     if (attrs.attachmentId)
       parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index f401781b..cef0ad79 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -335,6 +335,12 @@ function bridgeTaskLists(html: string): string {
  *     (same rendered line as visible content). The only handled key is
  *     `textAlign`, re-expressed as an inline `text-align` style on the parent,
  *     which the docmost-schema textAlign global attribute reads back.
+ *   - ATTACHED image comments (#4 `img`): a comment bound to an `<img>` (its
+ *     previous element sibling), e.g. `![](src) <!--img {"align":"left"}-->`
+ *     rendered as `<p><img> <!--img …--></p>`. Each decoded key is written as
+ *     the DOM attribute the image schema's parseHTML reads back (align/width/
+ *     height/data-size/data-aspect-ratio/data-attachment-id/data-caption/title).
+ *     An `img` comment with no adjacent <img> is INERT.
  *   - STANDALONE machinery comments (#5 `subpages`/`pagebreak`): a lone comment
  *     line, which `marked` renders as an HTML block so jsdom makes it a DIRECT
  *     child of `<body>`. These are replaced with the schema-matching block div
@@ -407,6 +413,38 @@ function applyCommentDirectives(html: string): string {
       continue;
     }
 
+    if (parsed.name === "img") {
+      // #293 canon #4 ATTACHED image attrs. `![](src) <!--img {…}-->` renders
+      // as `<p><img …> <!--img …--></p>`, so the comment's target is the nearest
+      // preceding <img> — its previousElementSibling. An `img` comment with no
+      // adjacent <img> (e.g. a standalone `<!--img-->` at body level, or one
+      // whose previous sibling is not an image) is INERT.
+      const prev = comment.previousElementSibling as any;
+      const target =
+        prev && String(prev.tagName || "").toLowerCase() === "img"
+          ? prev
+          : null;
+      if (!target) continue; // no adjacent <img> -> inert
+      // Re-express each decoded key as the DOM attribute the schema's image
+      // parseHTML reads back (docmost-schema.ts image attrs). Unknown keys are
+      // ignored (fail-open); a bad JSON body already returned null above.
+      const a = parsed.attrs;
+      if (typeof a.align === "string" && a.align)
+        target.setAttribute("align", a.align);
+      if (a.width != null) target.setAttribute("width", String(a.width));
+      if (a.height != null) target.setAttribute("height", String(a.height));
+      if (a.size != null) target.setAttribute("data-size", String(a.size));
+      if (a.aspectRatio != null)
+        target.setAttribute("data-aspect-ratio", String(a.aspectRatio));
+      if (a.attachmentId != null)
+        target.setAttribute("data-attachment-id", String(a.attachmentId));
+      if (a.caption != null)
+        target.setAttribute("data-caption", String(a.caption));
+      if (a.title != null) target.setAttribute("title", String(a.title));
+      comment.remove();
+      continue;
+    }
+
     if (!parent) continue; // attrs comment must have an element parent
     if (parsed.name !== "attrs") continue; // unknown name -> inert
     // #293 canon #9 ATTACHED attrs: honored only in attached position.
diff --git a/packages/prosemirror-markdown/test/canonicalize-extra.test.ts b/packages/prosemirror-markdown/test/canonicalize-extra.test.ts
index e2103f80..fc3fa067 100644
--- a/packages/prosemirror-markdown/test/canonicalize-extra.test.ts
+++ b/packages/prosemirror-markdown/test/canonicalize-extra.test.ts
@@ -6,7 +6,8 @@ import { canonicalizeContent, docsCanonicallyEqual } from 'docmost-client';
 
 // ---------------------------------------------------------------------------
 // Gaps NOT covered by canonicalize.test.ts (test-strategy report §2 diff):
-//   - the *.align family (drawio/excalidraw/video/youtube/embed): a "center"
+//   - the *.align family (drawio/excalidraw/video/youtube/embed AND image, whose
+//     align default is unified to "center" per #293 canon #4): a "center"
 //     default is dropped, a non-default value is kept;
 //   - comment.resolved: TRUE is PRESERVED (only resolved:false is normalized);
 //   - link.target / link.rel NON-default values are kept;
@@ -39,21 +40,27 @@ describe('canonicalizeContent — *.align default family', () => {
     });
   }
 
-  it('image align is NOT in KNOWN_DEFAULTS: a non-null align survives, null is dropped', () => {
-    // image.align defaults to null, so it is handled by the null-drop rule and
-    // a real value ("left") must be kept (no spurious default match).
+  it('image align default is now "center" (#293 canon #4): center/null dropped, left kept', () => {
+    // A real non-default value ("left") must be kept.
     const kept = canonicalizeContent({
       type: 'image',
       attrs: { id: 'i-1', src: '/a.png', align: 'left' },
     });
     expect(kept.attrs).toEqual({ src: '/a.png', align: 'left' });
-    // An image with align:"center" must KEEP it (center is NOT a default for
-    // image, only for the diagram/media family) — guards against over-matching.
+    // #293 canon #4 unified the image align default to "center" (matching
+    // editor-ext), so a center image now DROPS align exactly like the diagram/
+    // media family — bare `![](src)` images stay canonically clean.
     const center = canonicalizeContent({
       type: 'image',
       attrs: { id: 'i-2', src: '/b.png', align: 'center' },
     });
-    expect(center.attrs).toEqual({ src: '/b.png', align: 'center' });
+    expect(center.attrs).toEqual({ src: '/b.png' });
+    // A null align is likewise dropped (null-drop rule) and re-imports as center.
+    const nullAlign = canonicalizeContent({
+      type: 'image',
+      attrs: { id: 'i-3', src: '/c.png', align: null },
+    });
+    expect(nullAlign.attrs).toEqual({ src: '/c.png' });
   });
 });
 
diff --git a/packages/prosemirror-markdown/test/image-comment.test.ts b/packages/prosemirror-markdown/test/image-comment.test.ts
new file mode 100644
index 00000000..77e9cb92
--- /dev/null
+++ b/packages/prosemirror-markdown/test/image-comment.test.ts
@@ -0,0 +1,244 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src (matching the other converter unit tests), not the
+// docmost-client barrel.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+// ---------------------------------------------------------------------------
+// #293 canon #4: images ALWAYS serialize as `![alt](src)`. Non-default attrs
+// ride along in an attached `<!--img {…}-->` comment on the SAME line, which the
+// importer materializes back onto the <img> before generateJSON drops it. An
+// attr equal to the schema default is NOT emitted. The image align default is
+// unified to "center" (matching editor-ext), so bare/center images stay clean
+// and only a genuinely non-default alignment (left/right) emits a comment.
+//
+// In raw-HTML contexts (inside a column / spanned cell) the prior `<img …>` form
+// is kept; comments are dropped by the DOM parse stage there.
+// ---------------------------------------------------------------------------
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const image = (attrs: any) => doc({ type: 'image', attrs: { src: '/i.png', ...attrs } });
+
+// Find the first image node anywhere in a PM JSON doc.
+function findImage(node: any): any | null {
+  if (!node || typeof node !== 'object') return null;
+  if (node.type === 'image') return node;
+  if (Array.isArray(node.content)) {
+    for (const child of node.content) {
+      const hit = findImage(child);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+// Export a doc, re-import it, and hand back the markdown + re-imported image.
+async function roundTrip(source: any): Promise<{ md: string; img: any; back: any }> {
+  const md = convertProseMirrorToMarkdown(source);
+  const back = await markdownToProseMirror(md);
+  return { md, img: findImage(back), back };
+}
+
+describe('#293 canon #4 — image serialization + attached img-comment', () => {
+  it('a bare image (src only) emits `![]()` with NO comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({}));
+    expect(md).toBe('![](/i.png)');
+    expect(md).not.toContain('<!--img');
+    expect(img).toBeTruthy();
+    expect(img.attrs.src).toBe('/i.png');
+    // align falls back to the unified "center" default on import.
+    expect(img.attrs.align).toBe('center');
+  });
+
+  it('src + alt emits `![alt](src)` with NO comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ alt: 'схема' }));
+    expect(md).toBe('![схема](/i.png)');
+    expect(md).not.toContain('<!--img');
+    expect(img.attrs.alt).toBe('схема');
+  });
+
+  it('align "center" (the default) emits a bare image, NO comment, round-trips to center', async () => {
+    const { md, img } = await roundTrip(image({ align: 'center' }));
+    expect(md).toBe('![](/i.png)');
+    expect(md).not.toContain('<!--img');
+    expect(img.attrs.align).toBe('center');
+  });
+
+  it('a null align emits a bare image and re-imports as the "center" default', async () => {
+    const { md, img } = await roundTrip(image({ align: null }));
+    expect(md).toBe('![](/i.png)');
+    expect(img.attrs.align).toBe('center');
+  });
+
+  it('align "left" emits an img-comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ align: 'left' }));
+    expect(md).toBe('![](/i.png) <!--img {"align":"left"}-->');
+    expect(img.attrs.align).toBe('left');
+  });
+
+  it('align "right" emits an img-comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ align: 'right' }));
+    expect(md).toBe('![](/i.png) <!--img {"align":"right"}-->');
+    expect(img.attrs.align).toBe('right');
+  });
+
+  it('width alone emits a single-key comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ width: '420' }));
+    expect(md).toBe('![](/i.png) <!--img {"width":"420"}-->');
+    expect(img.attrs.width).toBe('420');
+  });
+
+  it('height alone emits a single-key comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ height: '300' }));
+    expect(md).toBe('![](/i.png) <!--img {"height":"300"}-->');
+    expect(img.attrs.height).toBe('300');
+  });
+
+  it('size alone emits a single-key comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ size: '48' }));
+    expect(md).toBe('![](/i.png) <!--img {"size":"48"}-->');
+    expect(img.attrs.size).toBe('48');
+  });
+
+  it('aspectRatio alone emits a single-key comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ aspectRatio: '1.777' }));
+    expect(md).toBe('![](/i.png) <!--img {"aspectRatio":"1.777"}-->');
+    expect(img.attrs.aspectRatio).toBe('1.777');
+  });
+
+  it('attachmentId (the file link — data-loss critical) rides in the comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ attachmentId: 'att-777' }));
+    expect(md).toBe('![](/i.png) <!--img {"attachmentId":"att-777"}-->');
+    expect(img.attrs.attachmentId).toBe('att-777');
+  });
+
+  it('caption rides in the comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ caption: 'Рис. 1' }));
+    expect(md).toBe('![](/i.png) <!--img {"caption":"Рис. 1"}-->');
+    expect(img.attrs.caption).toBe('Рис. 1');
+  });
+
+  it('title rides in the comment and round-trips', async () => {
+    const { md, img } = await roundTrip(image({ title: 'a tooltip' }));
+    expect(md).toBe('![](/i.png) <!--img {"title":"a tooltip"}-->');
+    expect(img.attrs.title).toBe('a tooltip');
+  });
+
+  it('multiple attrs at once appear in the stable key order and round-trip', async () => {
+    const { md, img } = await roundTrip(
+      image({
+        alt: 'схема',
+        width: '420',
+        height: '300',
+        align: 'left',
+        size: '48',
+        aspectRatio: '1.5',
+        attachmentId: 'att-1',
+        caption: 'Рис. 1',
+        title: 'tip',
+      }),
+    );
+    // Stable order: width, height, align, size, aspectRatio, attachmentId, caption, title.
+    expect(md).toBe(
+      '![схема](/i.png) <!--img {"width":"420","height":"300","align":"left","size":"48","aspectRatio":"1.5","attachmentId":"att-1","caption":"Рис. 1","title":"tip"}-->',
+    );
+    expect(img.attrs.width).toBe('420');
+    expect(img.attrs.height).toBe('300');
+    expect(img.attrs.align).toBe('left');
+    expect(img.attrs.size).toBe('48');
+    expect(img.attrs.aspectRatio).toBe('1.5');
+    expect(img.attrs.attachmentId).toBe('att-1');
+    expect(img.attrs.caption).toBe('Рис. 1');
+    expect(img.attrs.title).toBe('tip');
+  });
+
+  // MANDATORY (#293 canon #4): a caption containing the comment-closing `-->`
+  // must be encoded so it can never break the HTML comment; JSON.parse restores
+  // it byte-exact on import.
+  it('a caption containing `-->` is escaped, does not break the comment, and round-trips byte-exact', async () => {
+    const caption = 'see --> here';
+    const { md, img } = await roundTrip(image({ caption }));
+    // The `--` pair is defused as the JSON unicode escape, so the literal
+    // caption text is NOT present verbatim and the comment cannot close early.
+    expect(md).toContain('\\u002d\\u002d');
+    expect(md).not.toContain('see --> here');
+    // The comment still closes exactly once, at the very end.
+    expect(md.endsWith('-->')).toBe(true);
+    // Restored byte-exact on re-import.
+    expect(img.attrs.caption).toBe('see --> here');
+  });
+
+  // A whole raw comment-closer as the caption is the adversarial edge.
+  it('a caption that IS `-->` round-trips byte-exact', async () => {
+    const { img } = await roundTrip(image({ caption: '-->' }));
+    expect(img.attrs.caption).toBe('-->');
+  });
+
+  it('an image INSIDE a column keeps the raw <img> form (no img-comment) and round-trips', async () => {
+    const source = doc({
+      type: 'columns',
+      attrs: { layout: 'two' },
+      content: [
+        {
+          type: 'column',
+          content: [
+            {
+              type: 'image',
+              attrs: { src: '/i.png', alt: 'c', width: '320', align: 'left', attachmentId: 'att-9' },
+            },
+          ],
+        },
+        { type: 'column', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'r' }] }] },
+      ],
+    });
+    const md = convertProseMirrorToMarkdown(source);
+    expect(md).toContain('<img');
+    expect(md).not.toContain('<!--img');
+    const back = await markdownToProseMirror(md);
+    const img = findImage(back);
+    expect(img).toBeTruthy();
+    expect(img.attrs.width).toBe('320');
+    expect(img.attrs.align).toBe('left');
+    expect(img.attrs.attachmentId).toBe('att-9');
+  });
+
+  // ---- Fail-open behavior ---------------------------------------------------
+
+  it('malformed JSON in an img-comment is ignored; the image keeps default attrs (no crash)', async () => {
+    const back = await markdownToProseMirror('![](/i.png) <!--img {bad-->');
+    const img = findImage(back);
+    expect(img).toBeTruthy();
+    expect(img.attrs.width).toBeNull();
+    expect(img.attrs.align).toBe('center'); // default
+  });
+
+  it('a STANDALONE img-comment (no adjacent <img>) is inert — no image materialized', async () => {
+    const back = await markdownToProseMirror('<!--img {"width":10}-->');
+    expect(findImage(back)).toBeNull();
+  });
+
+  it('unknown keys in a valid img-comment are ignored; the image is otherwise default', async () => {
+    const back = await markdownToProseMirror('![](/i.png) <!--img {"zzz":1}-->');
+    const img = findImage(back);
+    expect(img).toBeTruthy();
+    expect(img.attrs.width).toBeNull();
+    expect(img.attrs.align).toBe('center');
+    expect((img.attrs as any).zzz).toBeUndefined();
+  });
+
+  it('NUMERIC sizing attrs serialize as strings and round-trip byte-stably', () => {
+    // The import side reads DOM attributes back as strings, so a numeric source
+    // value must be stringified in the payload or the first round-trip churns
+    // `420 -> "420"` (a spurious one-time git diff). Assert the emitted string
+    // form AND that a second export is byte-identical to the first.
+    const d = image({ width: 420, height: 200, size: 80, aspectRatio: 1.5 });
+    const md1 = convertProseMirrorToMarkdown(d);
+    expect(md1).toBe(
+      '![](/i.png) <!--img {"width":"420","height":"200","size":"80","aspectRatio":"1.5"}-->',
+    );
+    return markdownToProseMirror(md1).then((back) => {
+      const md2 = convertProseMirrorToMarkdown(back);
+      expect(md2).toBe(md1); // byte-stable: no 420 -> "420" churn
+    });
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
index b3d8839b..4aae6b3b 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-gaps.test.ts
@@ -478,22 +478,24 @@ describe('converter gap coverage — documented round-trip data loss (specs 12
     expect(docsCanonicallyEqual(d, doc2)).toBe(false);
   });
 
-  // 14. The image emitter drops the title attribute (silently lost on round-trip).
-  it('an image title attribute is dropped on export and lost on re-import', async () => {
+  // 14. #293 canon #4: the image title now round-trips via the attached
+  //     `<!--img {…}-->` comment (previously silently dropped).
+  it('an image title attribute round-trips via the attached img-comment', async () => {
     const d = doc({
       type: 'image',
       attrs: { src: '/i.png', alt: 'a', title: 't"q' },
     });
     const md1 = convertProseMirrorToMarkdown(d);
-    expect(md1).toBe('![a](/i.png)'); // no title, no quotes
+    // The quote in the title is JSON-escaped inside the comment payload.
+    expect(md1).toBe('![a](/i.png) <!--img {"title":"t\\"q"}-->');
 
     const doc2 = await markdownToProseMirror(md1);
     const img = (doc2.content || []).find((n: any) => n.type === 'image');
     expect(img).toBeTruthy();
-    expect(img.attrs?.title).toBeNull(); // the original 't"q' was dropped
+    expect(img.attrs?.title).toBe('t"q'); // restored byte-exact
     expect(img.attrs?.src).toBe('/i.png');
     expect(img.attrs?.alt).toBe('a');
-    expect(docsCanonicallyEqual(d, doc2)).toBe(false);
+    expect(docsCanonicallyEqual(d, doc2)).toBe(true);
   });
 });
 
@@ -507,8 +509,10 @@ describe('converter gap coverage — raw-HTML container round-trips (specs 15–
         attrs: { src: '/i.png', alt: 'cap', width: 320, align: 'center' },
       }),
     );
+    // #293 canon #4: image align default is unified to "center", so a center
+    // image inside a column no longer emits a redundant align="center".
     expect(md1).toBe(
-      '<div data-type="columns" data-layout="two"><div data-type="column"><img src="/i.png" alt="cap" width="320" align="center"></div></div>',
+      '<div data-type="columns" data-layout="two"><div data-type="column"><img src="/i.png" alt="cap" width="320"></div></div>',
     );
     expect(md2).toBe(md1);
     expect(colChildOf(doc2)?.type).toBe('image');
diff --git a/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts b/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
index ea6b4c00..8802c610 100644
--- a/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-roundtrip-spoiler-caption.test.ts
@@ -8,8 +8,9 @@ import {
 // predated and must now preserve losslessly:
 //   - the `spoiler` inline mark (issue #259), emitted as raw inline HTML
 //     `<span data-spoiler="true">…</span>` (Markdown has no native syntax);
-//   - the image `caption` attribute (issue #221), emitted as `data-caption`
-//     on the raw <img> (Markdown `![](src)` cannot carry it).
+//   - the image `caption` attribute (issue #221). A top-level image now emits
+//     it in an attached `<!--img {…}-->` comment (#293 canon #4); a raw <img>
+//     with `data-caption` in incoming Markdown still parses it back too.
 // We exercise the real export -> import -> export cycle: a PM doc must survive
 // PM -> MD -> PM unchanged, and the raw-HTML forms in incoming Markdown must
 // parse back to the mark/attribute.
@@ -99,8 +100,9 @@ describe("image caption round-trip (#221)", () => {
     });
 
     const md1 = convertProseMirrorToMarkdown(source);
-    // A captioned image takes the raw <img> form so data-caption can ride along.
-    expect(md1).toContain('data-caption="A grey cat"');
+    // #293 canon #4: a top-level captioned image now serializes as the clean
+    // `![alt](src)` plus an attached `<!--img {…}-->` comment carrying caption.
+    expect(md1).toBe('![cat](/files/a.png) <!--img {"caption":"A grey cat"}-->');
 
     const doc2 = await markdownToProseMirror(md1);
     const img = findImage(doc2);
-- 
2.52.0


From e2a3b5fc4dc5b159842c22e6a2a9248d25b43521 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 08:52:02 +0300
Subject: [PATCH 06/17] feat(prosemirror-markdown): media family as md-form +
 discriminator comment (#293 canon #8)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ten media/embed node types move their TOP-LEVEL serialization off raw schema
HTML onto a readable markdown target plus an always-emitted discriminator
comment whose NAME selects the node type. The schema-HTML form is retained on
the raw-HTML/columns path (comments are dropped by the DOM parse stage there).

  image-form  ![](src)<!--name …-->   youtube, video, audio, drawio, excalidraw
  link-form   [text](src)<!--name …--> pdf, attachment, embed (text=filename/provider)
  standalone  <!--pageembed …--> / <!--transclusion …-->  pageEmbed, transclusionReference

The comment NAME is the node-type discriminator and is ALWAYS emitted, even when
the attr JSON is empty (`![](u)<!--youtube-->`), so a bare `![](u)` is never
mistaken for an `image` and a bare `[t](u)` stays a plain link — no URL-sniffing.
src rides in the markdown target; every other non-default attr (incl. the id
links attachmentId/sourcePageId/transclusionId) rides in the comment JSON
(stable key order, numerics stringified, align="center" omitted).

New src/lib/media-html.ts: byte-exact builders reproducing the schema HTML each
old processNode case returned. Both the serializer's raw-HTML path (blockToHtml,
now de-delegated from `return processNode(block)` to explicit per-type cases)
and the importer call these, so serialize and parse cannot drift.

Import (applyCommentDirectives): image-form binds the preceding <img> (src from
it), link-form the preceding <a> (src=href, text=filename/provider), standalone
replaces the comment (same leading-doc-level handling as #5). Each rebuilds the
schema element via the media-html builder, then swaps it in; the empty-<p> hoist
is absorbed by stripEmptyParagraphs. Fail-open: wrong element/position/name or
malformed JSON -> inert, no throw.

Link-form visible text is escaped (escapeLinkText) for the FULL set of
CommonMark inline-active punctuation (\ ` * _ ~ [ ] < & ! ( )), not just [ ] \:
the label is parsed as inline content, so a filename/provider like
`report *v2*.pdf` or `![shot](x).pdf` would otherwise lose the markup (or
fragment the parse) when the importer reads a.textContent back — a data-loss
regression vs the old data-attachment-name form. Adversarial round-trip fixtures
lock byte- and value-stability for emphasis/code/strike/autolink/entity/image
markers and nested-link names.

Tests: new media-comments.test.ts (40 cases: per-type exact md + lossless
byte-stable round-trip incl. id links, minimal-node discriminator-still-emitted,
in-column schema-HTML form, discriminator integrity, fail-open, active-punct
filenames). Goldens in media-roundtrip / markdown-converter-golden /
markdown-converter / diagram-roundtrip updated to the md+comment form (columns
stay schema-HTML). The former known-limitation image-diagrams fixture is now
byte- AND canonically-stable (canon #8 omits the diagram align="center" default)
and was promoted from an it.fails into the green corpus (11-image-diagrams.json).
git-sync stabilize.test.ts: the "diagram materializes data-align=center" fixpoint
moved into a column (where the raw-HTML asymmetry still holds), since top level
is now byte-stable.

package vitest: 540 passed; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/git-sync/test/stabilize.test.ts      |  21 +-
 .../src/lib/markdown-converter.ts             | 324 ++++++------
 .../src/lib/markdown-to-prosemirror.ts        | 150 +++++-
 .../src/lib/media-html.ts                     | 172 +++++++
 .../test/diagram-roundtrip.test.ts            |  40 +-
 .../11-image-diagrams.json}                   |   0
 .../test/markdown-converter-golden.test.ts    |  87 ++--
 .../test/markdown-converter.test.ts           |  19 +-
 .../test/media-comments.test.ts               | 474 ++++++++++++++++++
 .../test/media-roundtrip.test.ts              |  79 +--
 .../test/roundtrip-corpus.test.ts             |  64 +--
 11 files changed, 1113 insertions(+), 317 deletions(-)
 create mode 100644 packages/prosemirror-markdown/src/lib/media-html.ts
 rename packages/prosemirror-markdown/test/fixtures/{known-limitations/image-diagrams.json => corpus/11-image-diagrams.json} (100%)
 create mode 100644 packages/prosemirror-markdown/test/media-comments.test.ts

diff --git a/packages/git-sync/test/stabilize.test.ts b/packages/git-sync/test/stabilize.test.ts
index 8a70e1b9..d5303e9f 100644
--- a/packages/git-sync/test/stabilize.test.ts
+++ b/packages/git-sync/test/stabilize.test.ts
@@ -22,16 +22,27 @@ const meta: PageMeta = {
 
 describe('stabilizePageFile — normalize-on-write fixpoint (SPEC §11)', () => {
   it('reaches a byte-identical fixpoint after one extra export/import/export pass', async () => {
-    // A diagram is the canonical one-pass asymmetry: drawio's `align` default of
-    // "center" materializes on import, so a NAIVE export differs on the second
-    // export. stabilizePageFile runs the convergence pass at write time, so the
-    // written body must already be at the fixpoint: re-importing its body and
+    // A diagram inside a column is the canonical one-pass asymmetry: on the
+    // raw-HTML/columns path a diagram's `align` default of "center" materializes
+    // on import, so a NAIVE export differs on the second export. (#293 canon #8
+    // made the TOP-LEVEL diagram form — `![](src)<!--drawio …-->` — byte-stable by
+    // omitting the default, so the asymmetry now lives only on the columns path
+    // where the schema `<div data-type="drawio">` form is retained.)
+    // stabilizePageFile runs the convergence pass at write time, so the written
+    // body must already be at the fixpoint: re-importing its body and
     // re-stabilizing yields the exact same bytes.
     const content = {
       type: 'doc',
       content: [
         { type: 'paragraph', content: [{ type: 'text', text: 'intro' }] },
-        { type: 'drawio', attrs: { src: '/d.drawio' } },
+        {
+          type: 'columns',
+          attrs: { layout: 'two_equal' },
+          content: [
+            { type: 'column', content: [{ type: 'drawio', attrs: { src: '/d.drawio' } }] },
+            { type: 'column', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'side' }] }] },
+          ],
+        },
         { type: 'paragraph', content: [{ type: 'text', text: 'outro' }] },
       ],
     };
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 60260bfa..17ab21db 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -3,6 +3,17 @@ import {
   attachedCommentFor,
   standaloneCommentFor,
 } from "./attached-comment.js";
+import {
+  attachmentToHtml,
+  audioToHtml,
+  diagramToHtml,
+  embedToHtml,
+  pageEmbedToHtml,
+  pdfToHtml,
+  transclusionReferenceToHtml,
+  videoToHtml,
+  youtubeToHtml,
+} from "./media-html.js";
 
 /**
  * Hard cap on processNode recursion depth (see the depth guard below).
@@ -62,6 +73,24 @@ export function convertProseMirrorToMarkdown(content: any): string {
       .replace(/\(/g, "%28")
       .replace(/\)/g, "%29");
 
+  // Backslash-escape every character a markdown link's `[text]` label would
+  // otherwise INTERPRET, so a link-form media node's visible text (a filename or
+  // provider carried in `attrs.name`/`attrs.provider`) round-trips byte-exact
+  // (#293 canon #8 link-form). Escaping only `[ ] \` is NOT enough: the label is
+  // parsed as inline content, so emphasis (`* _`), code (`` ` ``), strikethrough
+  // (`~`), autolinks/raw-HTML (`<`), HTML entities (`&`), and image markers (`!`)
+  // would all be consumed and lost when the importer reads `a.textContent` back
+  // (e.g. `report *v2*.pdf` -> `report v2.pdf`). CommonMark treats a backslash
+  // before ANY ASCII punctuation as that literal char, so escaping this active
+  // set is always lossless on re-parse; the old `<div data-attachment-name>`
+  // form carried arbitrary strings via escapeAttr, so anything less is a
+  // data-loss regression on the git-sync data path. `( )` are escaped too: even
+  // with `[ ]` escaped, an unescaped `](x)` sequence inside the label (e.g. a
+  // name like `![shot](x).pdf`) forms a false nested-link destination and
+  // fragments the parse — escaping the parens removes that ambiguity entirely.
+  const escapeLinkText = (value: unknown): string =>
+    String(value ?? "").replace(/[\\`*_~[\]<&!()]/g, (c: string) => `\\${c}`);
+
   // Recursion depth guard. processNode is mutually recursive (directly and via
   // processListItem/processTaskItem/blockToHtml), and a pathologically nested
   // document (e.g. tens of thousands of nested blockquotes) would otherwise
@@ -410,48 +439,44 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       case "video": {
-        // Emit the schema-matching <video> element so generateJSON rebuilds the
-        // node with its attrs intact. The schema's parseHTML reads src/aria-label
-        // from the standard attributes and the remaining attrs from data-*.
+        // #293 canon #8 (image-form): a top-level video serializes as
+        // `![](src)<!--video {…}-->`. The bare `![](src)` is ALWAYS followed by
+        // the `video` discriminator comment — a bare image with NO comment is an
+        // `image`, never sniffed by URL — so the comment is REQUIRED even when
+        // there are no extra attrs (emitted name-only as `<!--video-->`). src
+        // lives in the markdown target; every OTHER non-default attr rides in the
+        // comment JSON (stable key order, numerics stringified for byte-stability
+        // exactly like canon #4). align default "center" is omitted. The schema
+        // `<div><video>` form is still emitted on the raw-HTML path (blockToHtml)
+        // via videoToHtml, since comment nodes are dropped inside columns/cells.
         const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.alt) parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+        const src = encodeMdUrl(attrs.src);
+        const json: Record<string, unknown> = {};
+        if (attrs.alt) json.alt = attrs.alt;
+        if (attrs.attachmentId) json.attachmentId = attrs.attachmentId;
+        if (attrs.width != null) json.width = String(attrs.width);
+        if (attrs.height != null) json.height = String(attrs.height);
+        if (attrs.size != null) json.size = String(attrs.size);
+        if (attrs.align != null && attrs.align !== "center")
+          json.align = attrs.align;
         if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        // Wrap in a block <div> so marked treats it as a block (a bare <video>
-        // is inline-level HTML and marked wraps it in <p>, leaving a spurious
-        // empty paragraph beside the hoisted block atom). The wrapper has no
-        // data-type, so the schema parser ignores it and just hoists the video.
-        return `<div><video ${parts.join(" ")}></video></div>`;
+          json.aspectRatio = String(attrs.aspectRatio);
+        return `![](${src})${standaloneCommentFor("video", json)}`;
       }
 
       case "youtube": {
-        // Emit the schema-matching div[data-type="youtube"]; the schema reads
-        // src from data-src and width/height/align from data-* attributes.
+        // #293 canon #8 (image-form): `![](url)<!--youtube {…}-->`. Same rules as
+        // video — src in the target, other non-default attrs (width/height/align,
+        // align!=center) in the ALWAYS-emitted discriminator comment. The
+        // div[data-type="youtube"] form stays on the raw-HTML path (youtubeToHtml).
         const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="youtube"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        return `<div ${parts.join(" ")}></div>`;
+        const src = encodeMdUrl(attrs.src);
+        const json: Record<string, unknown> = {};
+        if (attrs.width != null) json.width = String(attrs.width);
+        if (attrs.height != null) json.height = String(attrs.height);
+        if (attrs.align != null && attrs.align !== "center")
+          json.align = attrs.align;
+        return `![](${src})${standaloneCommentFor("youtube", json)}`;
       }
 
       case "table": {
@@ -595,115 +620,91 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       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
-        // schema-matching div[data-type="attachment"] with data-attachment-*
-        // attrs so the node round-trips instead of degrading to a markdown link.
+        // #293 canon #8 (link-form): `[filename](src)<!--attachment {…}-->`. The
+        // schema's `url` is the markdown target; the VISIBLE text is the filename
+        // (`attrs.name`, escaped so `[`/`]` cannot break the label). Every OTHER
+        // non-default attr (mime/size/attachmentId) rides in the ALWAYS-emitted
+        // discriminator comment — a bare `[text](src)` with no comment is a plain
+        // link, never an attachment. The div[data-type="attachment"] form stays
+        // on the raw-HTML path (attachmentToHtml) for columns/cells.
         const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="attachment"`,
-          `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
-        ];
-        if (attrs.name)
-          parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.mime)
-          parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
-        if (attrs.size != null)
-          parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
+        const src = encodeMdUrl(attrs.url);
+        const text = escapeLinkText(attrs.name ?? "");
+        const json: Record<string, unknown> = {};
+        if (attrs.mime) json.mime = attrs.mime;
+        if (attrs.size != null) json.size = String(attrs.size);
+        if (attrs.attachmentId) json.attachmentId = attrs.attachmentId;
+        return `[${text}](${src})${standaloneCommentFor("attachment", json)}`;
       }
 
       case "drawio":
       case "excalidraw": {
-        // Emit the schema-matching div[data-type=...] carrying the diagram's
-        // attrs as data-* (the schema's diagramAttributes reads src/title/alt/
-        // width/height/size/aspectRatio/align/attachmentId from data-*), so the
-        // diagram round-trips instead of degrading to a lossy placeholder.
+        // #293 canon #8 (image-form): `![](src)<!--drawio|excalidraw {…}-->`. src
+        // in the target; title/alt/width/height/size/aspectRatio/align(!=center)/
+        // attachmentId in the ALWAYS-emitted discriminator comment (the NAME
+        // selects drawio vs excalidraw). The div[data-type=…] form stays on the
+        // raw-HTML path (diagramToHtml).
         const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="${type}"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.title != null)
-          parts.push(`data-title="${escapeAttr(attrs.title)}"`);
-        if (attrs.alt != null) parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+        const src = encodeMdUrl(attrs.src);
+        const json: Record<string, unknown> = {};
+        if (attrs.title != null) json.title = attrs.title;
+        if (attrs.alt != null) json.alt = attrs.alt;
+        if (attrs.width != null) json.width = String(attrs.width);
+        if (attrs.height != null) json.height = String(attrs.height);
+        if (attrs.size != null) json.size = String(attrs.size);
         if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
+          json.aspectRatio = String(attrs.aspectRatio);
+        if (attrs.align != null && attrs.align !== "center")
+          json.align = attrs.align;
+        if (attrs.attachmentId) json.attachmentId = attrs.attachmentId;
+        return `![](${src})${standaloneCommentFor(type, json)}`;
       }
 
       case "embed": {
-        // Emit the schema-matching div[data-type="embed"]; the schema reads
-        // src/provider/align/width/height from data-* attributes so the node
-        // (and its provider iframe info) survives the round-trip.
+        // #293 canon #8 (link-form): `[provider](src)<!--embed {…}-->`. src in
+        // the target; the VISIBLE text is the provider (`attrs.provider`). align/
+        // width/height ride in the discriminator comment only when non-default
+        // (align "center", width 800, height 600 are the schema defaults). The
+        // div[data-type="embed"] form stays on the raw-HTML path (embedToHtml).
         const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="embed"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-          `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
-        ];
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
+        const src = encodeMdUrl(attrs.src);
+        const text = escapeLinkText(attrs.provider ?? "");
+        const json: Record<string, unknown> = {};
+        if (attrs.align != null && attrs.align !== "center")
+          json.align = attrs.align;
+        if (attrs.width != null && attrs.width !== 800)
+          json.width = String(attrs.width);
+        if (attrs.height != null && attrs.height !== 600)
+          json.height = String(attrs.height);
+        return `[${text}](${src})${standaloneCommentFor("embed", json)}`;
       }
 
       case "audio": {
-        // Emit the schema-matching <audio> element (was emitting nothing). The
-        // schema reads src from src and attachmentId/size from data-*.
+        // #293 canon #8 (image-form): `![](src)<!--audio {…}-->`. src in the
+        // target; attachmentId/size in the ALWAYS-emitted discriminator comment.
+        // The <div><audio> form stays on the raw-HTML path (audioToHtml).
         const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        // Wrap in a block <div> for the same reason as video: a bare <audio> is
-        // inline-level HTML that marked would wrap in <p>.
-        return `<div><audio ${parts.join(" ")}></audio></div>`;
+        const src = encodeMdUrl(attrs.src);
+        const json: Record<string, unknown> = {};
+        if (attrs.attachmentId) json.attachmentId = attrs.attachmentId;
+        if (attrs.size != null) json.size = String(attrs.size);
+        return `![](${src})${standaloneCommentFor("audio", json)}`;
       }
 
       case "pdf": {
-        // Emit the schema-matching div[data-type="pdf"] (was emitting nothing).
-        // The schema reads src/width/height from standard attrs and name/
-        // attachmentId/size from data-*.
+        // #293 canon #8 (link-form): `[filename](src)<!--pdf {…}-->`. src in the
+        // target; the VISIBLE text is the filename (`attrs.name`). attachmentId/
+        // size/width/height ride in the ALWAYS-emitted discriminator comment. The
+        // div[data-type="pdf"] form stays on the raw-HTML path (pdfToHtml).
         const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="pdf"`,
-          `src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.name) parts.push(`data-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
+        const src = encodeMdUrl(attrs.src);
+        const text = escapeLinkText(attrs.name ?? "");
+        const json: Record<string, unknown> = {};
+        if (attrs.attachmentId) json.attachmentId = attrs.attachmentId;
+        if (attrs.size != null) json.size = String(attrs.size);
+        if (attrs.width != null) json.width = String(attrs.width);
+        if (attrs.height != null) json.height = String(attrs.height);
+        return `[${text}](${src})${standaloneCommentFor("pdf", json)}`;
       }
 
       case "columns": {
@@ -802,26 +803,29 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       case "pageEmbed": {
-        // Whole-page live embed; the schema reads data-source-page-id.
+        // #293 canon #8 (standalone): a whole-page live embed serializes as a
+        // lone discriminator comment on its own line — `<!--pageembed-->` or
+        // `<!--pageembed {"sourcePageId":…}-->`. Readable markdown, invisible in
+        // renderers, re-materialized on import. The div[data-type="pageEmbed"]
+        // form stays on the raw-HTML path (pageEmbedToHtml) for columns/cells.
         const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="pageEmbed"`];
-        if (attrs.sourcePageId)
-          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
-        return `<div ${parts.join(" ")}></div>`;
+        const json: Record<string, unknown> = {};
+        if (attrs.sourcePageId) json.sourcePageId = attrs.sourcePageId;
+        return standaloneCommentFor("pageembed", json);
       }
 
       case "transclusionReference": {
-        // Live reference to a transcluded block/page. Block atom; the schema
-        // reads data-source-page-id and data-transclusion-id.
+        // #293 canon #8 (standalone): a live block/page reference serializes as a
+        // lone `<!--transclusion {…}-->` comment carrying sourcePageId +
+        // transclusionId (the data-loss-critical id links). The
+        // div[data-type="transclusionReference"] form stays on the raw-HTML path
+        // (transclusionReferenceToHtml). (transclusionSource is unchanged — it has
+        // block children and keeps recursing through processNode.)
         const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="transclusionReference"`];
-        if (attrs.sourcePageId)
-          parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
-        if (attrs.transclusionId)
-          parts.push(
-            `data-transclusion-id="${escapeAttr(attrs.transclusionId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
+        const json: Record<string, unknown> = {};
+        if (attrs.sourcePageId) json.sourcePageId = attrs.sourcePageId;
+        if (attrs.transclusionId) json.transclusionId = attrs.transclusionId;
+        return standaloneCommentFor("transclusion", json);
       }
 
       case "transclusionSource": {
@@ -1067,25 +1071,41 @@ export function convertProseMirrorToMarkdown(content: any): string {
         const recursive = block.attrs?.recursive ? ` data-recursive="true"` : "";
         return `<div data-type="subpages"${recursive}></div>`;
       }
-      // columns/column, math, media, embed, attachment, mention, etc. already
+      // #293 canon #8: the media/discriminator family now serializes at TOP LEVEL
+      // (processNode) as md-target + `<!--name-->` comment. A comment node is
+      // DROPPED by the DOM parse stage that reads a raw-HTML block back, so inside
+      // a column/cell the comment form would silently vanish (data loss). Give
+      // each an EXPLICIT schema-HTML case here (via the shared media-html builders
+      // — the SAME output processNode used to emit, and the same the importer
+      // rebuilds) instead of delegating to processNode's md+comment form.
+      case "video":
+        return videoToHtml(block.attrs || {});
+      case "audio":
+        return audioToHtml(block.attrs || {});
+      case "pdf":
+        return pdfToHtml(block.attrs || {});
+      case "youtube":
+        return youtubeToHtml(block.attrs || {});
+      case "embed":
+        return embedToHtml(block.attrs || {});
+      case "attachment":
+        return attachmentToHtml(block.attrs || {});
+      case "drawio":
+      case "excalidraw":
+        return diagramToHtml(block.type, block.attrs || {});
+      case "pageEmbed":
+        return pageEmbedToHtml(block.attrs || {});
+      case "transclusionReference":
+        return transclusionReferenceToHtml(block.attrs || {});
+      // columns/column, math, htmlEmbed, footnotes, transclusionSource already
       // emit schema-matching HTML from processNode.
       case "columns":
       case "column":
       case "mathBlock":
-      case "video":
-      case "audio":
-      case "pdf":
-      case "youtube":
-      case "embed":
-      case "attachment":
-      case "drawio":
-      case "excalidraw":
       case "htmlEmbed":
       case "footnotesList":
       case "footnoteDefinition":
-      case "pageEmbed":
       case "transclusionSource":
-      case "transclusionReference":
         return processNode(block);
       default:
         // Any still-unhandled block type: NEVER fall back to markdown inside a
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index cef0ad79..03034cdf 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -12,6 +12,17 @@ import { JSDOM } from "jsdom";
 import { marked } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
 import { parseAttachedComment } from "./attached-comment.js";
+import {
+  attachmentToHtml,
+  audioToHtml,
+  diagramToHtml,
+  embedToHtml,
+  pageEmbedToHtml,
+  pdfToHtml,
+  transclusionReferenceToHtml,
+  videoToHtml,
+  youtubeToHtml,
+} from "./media-html.js";
 
 // Setup DOM environment for Tiptap HTML parsing in Node.js
 const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
@@ -346,14 +357,24 @@ function bridgeTaskLists(html: string): string {
  *     child of `<body>`. These are replaced with the schema-matching block div
  *     (`<div data-type="pageBreak">` / `<div data-type="subpages" [data-recursive]>`)
  *     that the schema's parseHTML rebuilds into the atom.
+ *   - MEDIA DISCRIMINATOR comments (#8): the comment NAME selects the node type.
+ *     IMAGE-FORM (`youtube`/`video`/`audio`/`drawio`/`excalidraw`) binds to the
+ *     preceding `<img>` (`![](src)<!--name …-->`); LINK-FORM (`pdf`/`attachment`/
+ *     `embed`) binds to the preceding `<a>` (`[text](src)<!--name …-->`);
+ *     STANDALONE (`pageembed`/`transclusion`) is a lone comment line. Each is
+ *     re-expressed as the SAME schema HTML the serializer's raw-HTML path emits
+ *     (media-html.ts) — the img's `src`/the anchor's `href`+text plus the decoded
+ *     comment attrs — then swapped in for the `<img>`/`<a>`/comment. A bare
+ *     `![](url)`/`[text](src)` with NO following discriminator stays an `image`/
+ *     plain link (never sniffed by URL).
  *
  * Position determines legality: an `attrs` comment is honored only in attached
- * position, a `subpages`/`pagebreak` comment only in standalone position; a
- * comment in the wrong position is left INERT (generateJSON drops it). Fail-open
- * everywhere: a malformed comment (null from parseAttachedComment), an unknown
- * name, a wrong-position comment, or an unknown/empty attr value is ignored.
- * Future decisions (#4/#8) extend the per-name handling here without changing
- * the parse primitive.
+ * position, `subpages`/`pagebreak`/`pageembed`/`transclusion` only in standalone
+ * position, an image-form comment only next to an `<img>` and a link-form comment
+ * only next to an `<a>`; a comment in the wrong position/next to the wrong element
+ * is left INERT (generateJSON drops it). Fail-open everywhere: a malformed comment
+ * (null from parseAttachedComment), an unknown name, a wrong-position comment, or
+ * an unknown/empty attr value is ignored.
  */
 function applyCommentDirectives(html: string): string {
   // Cheap early-out: no comments at all -> nothing to intercept.
@@ -377,6 +398,43 @@ function applyCommentDirectives(html: string): string {
   // comments at document level, prepending them to body preserves global order.
   const leadingDivs: any[] = [];
 
+  // #293 canon #8 discriminator NAME -> node form. The comment NAME alone selects
+  // the node type; a bare `![](url)`/`[text](src)` with NO following comment is an
+  // `image`/plain link (never sniffed). These are materialized below by rebuilding
+  // the SAME schema HTML the serializer's raw-HTML path emits (media-html.ts), so
+  // serialize and parse cannot drift.
+  const IMAGE_FORM_NAMES = new Set([
+    "youtube",
+    "video",
+    "audio",
+    "drawio",
+    "excalidraw",
+  ]);
+  const LINK_FORM_NAMES = new Set(["pdf", "attachment", "embed"]);
+
+  // Parse a schema-HTML string (from a media-html builder) into its top-level
+  // element so it can be swapped in for the <img>/<a>/comment it replaces.
+  const buildElement = (htmlStr: string): any => {
+    const tmp = document.createElement("div");
+    tmp.innerHTML = htmlStr;
+    return tmp.firstElementChild;
+  };
+
+  // Build the image-form schema HTML for a given discriminator name, using the
+  // <img>'s src as the node src plus the decoded comment attrs.
+  const imageFormHtml = (name: string, attrs: Record<string, any>): string => {
+    switch (name) {
+      case "video":
+        return videoToHtml(attrs);
+      case "audio":
+        return audioToHtml(attrs);
+      case "youtube":
+        return youtubeToHtml(attrs);
+      default: // drawio | excalidraw
+        return diagramToHtml(name as "drawio" | "excalidraw", attrs);
+    }
+  };
+
   for (const comment of comments) {
     const parsed = parseAttachedComment(comment.data);
     if (!parsed) continue; // malformed -> inert (dropped by generateJSON)
@@ -413,6 +471,86 @@ function applyCommentDirectives(html: string): string {
       continue;
     }
 
+    if (parsed.name === "pageembed" || parsed.name === "transclusion") {
+      // #293 canon #8 STANDALONE media. Like subpages/pagebreak: a lone comment
+      // line placed under <body> or at document level (leading). An attached-
+      // position comment (inside a <p>/<hN> with a sibling) is INERT. We rebuild
+      // the schema div the raw-HTML path emits (media-html.ts) from the decoded
+      // attrs so serialize/parse stay in sync.
+      const standalone = tag === "" || tag === "body" || tag === "html";
+      if (!standalone) continue; // wrong position -> inert
+      const el = buildElement(
+        parsed.name === "pageembed"
+          ? pageEmbedToHtml({ sourcePageId: parsed.attrs.sourcePageId })
+          : transclusionReferenceToHtml({
+              sourcePageId: parsed.attrs.sourcePageId,
+              transclusionId: parsed.attrs.transclusionId,
+            }),
+      );
+      if (!el) continue; // defensive: builder always yields an element
+      if (tag === "body") {
+        comment.replaceWith(el);
+      } else {
+        comment.remove();
+        leadingDivs.push(el);
+      }
+      continue;
+    }
+
+    if (IMAGE_FORM_NAMES.has(parsed.name)) {
+      // #293 canon #8 IMAGE-FORM media (youtube/video/audio/drawio/excalidraw).
+      // `![](src)<!--name {…}-->` renders as `<p><img …><!--name …--></p>`, so
+      // the target is the comment's previous element sibling and it MUST be an
+      // <img>. We rebuild the schema element from the img's src + decoded attrs
+      // and swap it in for the <img>. No adjacent <img> -> INERT.
+      const prev = comment.previousElementSibling as any;
+      const target =
+        prev && String(prev.tagName || "").toLowerCase() === "img"
+          ? prev
+          : null;
+      if (!target) continue; // no adjacent <img> -> inert
+      const attrs = { ...parsed.attrs, src: target.getAttribute("src") || "" };
+      const el = buildElement(imageFormHtml(parsed.name, attrs));
+      if (!el) continue;
+      target.replaceWith(el);
+      comment.remove();
+      continue;
+    }
+
+    if (LINK_FORM_NAMES.has(parsed.name)) {
+      // #293 canon #8 LINK-FORM media (pdf/attachment/embed).
+      // `[text](src)<!--name {…}-->` renders as `<p><a href="src">text</a>
+      // <!--name …--></p>`, so the target is the previous element sibling and it
+      // MUST be an <a>. src = a.href; the visible text is the filename/provider.
+      // Not an <a> -> INERT.
+      const prev = comment.previousElementSibling as any;
+      const target =
+        prev && String(prev.tagName || "").toLowerCase() === "a" ? prev : null;
+      if (!target) continue; // no adjacent <a> -> inert
+      const src = target.getAttribute("href") || "";
+      const text = target.textContent || "";
+      let htmlStr: string;
+      if (parsed.name === "pdf") {
+        // pdf: src standard attr, filename in data-name (null when empty).
+        htmlStr = pdfToHtml({ ...parsed.attrs, src, name: text || null });
+      } else if (parsed.name === "attachment") {
+        // attachment: the schema field is `url`, filename in data-attachment-name.
+        htmlStr = attachmentToHtml({
+          ...parsed.attrs,
+          url: src,
+          name: text || null,
+        });
+      } else {
+        // embed: the visible text is the provider (schema default "").
+        htmlStr = embedToHtml({ ...parsed.attrs, src, provider: text });
+      }
+      const el = buildElement(htmlStr);
+      if (!el) continue;
+      target.replaceWith(el);
+      comment.remove();
+      continue;
+    }
+
     if (parsed.name === "img") {
       // #293 canon #4 ATTACHED image attrs. `![](src) <!--img {…}-->` renders
       // as `<p><img …> <!--img …--></p>`, so the comment's target is the nearest
diff --git a/packages/prosemirror-markdown/src/lib/media-html.ts b/packages/prosemirror-markdown/src/lib/media-html.ts
new file mode 100644
index 00000000..733f5aed
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/media-html.ts
@@ -0,0 +1,172 @@
+/**
+ * Shared schema-HTML builders for the media/discriminator family (#293 canon
+ * #8).
+ *
+ * Canon #8 gives ten node types (youtube/video/audio/drawio/excalidraw —
+ * image-form; pdf/attachment/embed — link-form; pageEmbed/transclusionReference
+ * — standalone) a readable markdown TOP-LEVEL form (`![](src)`/`[text](src)`/a
+ * bare comment) plus a discriminator `<!--name {…}-->` comment. But TWO other
+ * paths still need the RAW SCHEMA-HTML form of each node:
+ *
+ *   1. The serializer's raw-HTML/columns path (`blockToHtml`): a comment node is
+ *      dropped by the DOM parse stage that reads a raw-HTML block back, so inside
+ *      a column/cell these nodes MUST stay schema HTML or they vanish (data loss).
+ *   2. The importer's `applyCommentDirectives`: to materialize the discriminator
+ *      comment it rebuilds the SAME schema element the raw-HTML path emits, then
+ *      swaps it in for the `<img>`/`<a>`/comment.
+ *
+ * Keeping these builders in ONE module means the serializer's raw-HTML path and
+ * the importer's materialization can never drift: both call the same function.
+ * Each builder reproduces BYTE-FOR-BYTE the schema HTML the top-level
+ * `processNode` cases previously returned (so existing columns/raw-HTML goldens
+ * stay green), and each output round-trips through the matching schema parseHTML
+ * in docmost-schema.ts.
+ */
+
+/**
+ * Escape a value interpolated into an HTML double-quoted attribute value.
+ * Identical semantics to markdown-converter's `escapeAttr`: escape ONLY `&` and
+ * `"` (idempotent; parse5 decodes both back). `<`/`>`/`'` are deliberately left
+ * alone so values never accumulate escapes across round-trips.
+ */
+const escapeAttr = (value: unknown): string =>
+  String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+/**
+ * Uploaded `<video>` player. Emits `<div><video …></video></div>`; the outer
+ * `<div>` (no data-type) forces block treatment so marked does not wrap the
+ * inline `<video>` in a `<p>`. Mirrors the Video schema: src/aria-label standard
+ * attrs, the rest as data-*.
+ */
+export function videoToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
+  if (attrs.alt) parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
+  if (attrs.attachmentId)
+    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+  if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
+  if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
+  if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+  if (attrs.align) parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+  if (attrs.aspectRatio != null)
+    parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
+  return `<div><video ${parts.join(" ")}></video></div>`;
+}
+
+/** YouTube embed. Emits `div[data-type="youtube"]` (src via data-src). */
+export function youtubeToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [
+    `data-type="youtube"`,
+    `data-src="${escapeAttr(attrs.src ?? "")}"`,
+  ];
+  if (attrs.width != null)
+    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+  if (attrs.height != null)
+    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+  if (attrs.align) parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/** Uploaded `<audio>` player. Emits `<div><audio …></audio></div>`. */
+export function audioToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
+  if (attrs.attachmentId)
+    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+  if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+  return `<div><audio ${parts.join(" ")}></audio></div>`;
+}
+
+/**
+ * draw.io / excalidraw diagram (shared diagramAttributes). Emits
+ * `div[data-type="drawio"|"excalidraw"]` carrying src/title/alt/width/height/
+ * size/aspectRatio/align/attachmentId as data-*.
+ */
+export function diagramToHtml(
+  type: "drawio" | "excalidraw",
+  attrs: Record<string, any>,
+): string {
+  const parts: string[] = [
+    `data-type="${type}"`,
+    `data-src="${escapeAttr(attrs.src ?? "")}"`,
+  ];
+  if (attrs.title != null) parts.push(`data-title="${escapeAttr(attrs.title)}"`);
+  if (attrs.alt != null) parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
+  if (attrs.width != null)
+    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+  if (attrs.height != null)
+    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+  if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+  if (attrs.aspectRatio != null)
+    parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
+  if (attrs.align) parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+  if (attrs.attachmentId)
+    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/** Generic provider embed. Emits `div[data-type="embed"]` (src/provider/… data-*). */
+export function embedToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [
+    `data-type="embed"`,
+    `data-src="${escapeAttr(attrs.src ?? "")}"`,
+    `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
+  ];
+  if (attrs.align) parts.push(`data-align="${escapeAttr(attrs.align)}"`);
+  if (attrs.width != null)
+    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
+  if (attrs.height != null)
+    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/** Uploaded file attachment. Emits `div[data-type="attachment"]` (data-attachment-*). */
+export function attachmentToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [
+    `data-type="attachment"`,
+    `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
+  ];
+  if (attrs.name)
+    parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
+  if (attrs.mime)
+    parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
+  if (attrs.size != null)
+    parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
+  if (attrs.attachmentId)
+    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/** Embedded PDF viewer. Emits `div[data-type="pdf"]` (src std, name/… data-*). */
+export function pdfToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [
+    `data-type="pdf"`,
+    `src="${escapeAttr(attrs.src ?? "")}"`,
+  ];
+  if (attrs.name) parts.push(`data-name="${escapeAttr(attrs.name)}"`);
+  if (attrs.attachmentId)
+    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
+  if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
+  if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
+  if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/** Whole-page live embed. Emits `div[data-type="pageEmbed"]` (data-source-page-id). */
+export function pageEmbedToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [`data-type="pageEmbed"`];
+  if (attrs.sourcePageId)
+    parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
+
+/**
+ * Live transclusion reference. Emits `div[data-type="transclusionReference"]`
+ * (data-source-page-id + data-transclusion-id).
+ */
+export function transclusionReferenceToHtml(attrs: Record<string, any>): string {
+  const parts: string[] = [`data-type="transclusionReference"`];
+  if (attrs.sourcePageId)
+    parts.push(`data-source-page-id="${escapeAttr(attrs.sourcePageId)}"`);
+  if (attrs.transclusionId)
+    parts.push(`data-transclusion-id="${escapeAttr(attrs.transclusionId)}"`);
+  return `<div ${parts.join(" ")}></div>`;
+}
diff --git a/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts b/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
index d8ffc5fe..bcc55ff8 100644
--- a/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
+++ b/packages/prosemirror-markdown/test/diagram-roundtrip.test.ts
@@ -32,15 +32,16 @@ describe('diagram round-trip (docmost-schema diagramAttributes)', () => {
     const doc2 = await markdownToProseMirror(md1);
     const md2 = convertProseMirrorToMarkdown(doc2);
 
-    // Exact serialized form: numbers render as bare data-* values; attribute
-    // order follows the converter's emit order (src, then width/height/size/
-    // aspect-ratio/align, then attachment-id).
+    // #293 canon #8 (image-form): src is the markdown target; every OTHER
+    // non-default attr rides in the ALWAYS-emitted `drawio` discriminator comment
+    // (numerics stringified, stable key order width/height/size/aspectRatio then
+    // attachmentId). align="center" is the schema default, so it is OMITTED.
     expect(md1).toBe(
-      '<div data-type="drawio" data-src="/d.drawio" data-width="640" data-height="480" data-size="1234" data-aspect-ratio="1.777" data-align="center" data-attachment-id="att-1"></div>',
+      '![](/d.drawio)<!--drawio {"width":"640","height":"480","size":"1234","aspectRatio":"1.777","attachmentId":"att-1"}-->',
     );
 
-    // A second export reproduces the first byte-for-byte (drawio align default
-    // is already "center", so nothing new materializes on import).
+    // A second export reproduces the first byte-for-byte: align="center"
+    // re-materializes as the schema default on import and is omitted again.
     expect(md2).toBe(md1);
 
     // Re-import coerces every numeric attr to a STRING because parseHTML reads
@@ -64,10 +65,10 @@ describe('diagram round-trip (docmost-schema diagramAttributes)', () => {
   });
 
   // SPEC case 2: minimal excalidraw atom with ONLY string attrs (no align, no
-  // numeric attrs). Locks the one-time export divergence (align='center'
-  // default materializes only on import) plus escapeAttr of title/alt through
-  // the data-title/data-alt path.
-  it('excalidraw materializes align default only on import and escapes title/alt', async () => {
+  // numeric attrs). #293 canon #8 image-form: title/alt ride in the comment JSON
+  // (JSON-encoded, NOT HTML-escaped) and align='center' is omitted as the
+  // schema default — so the one-time divergence the OLD div-form had is GONE.
+  it('excalidraw round-trips title/alt via the discriminator comment (byte-stable, align default omitted)', async () => {
     const input = doc({
       type: 'excalidraw',
       attrs: {
@@ -81,21 +82,18 @@ describe('diagram round-trip (docmost-schema diagramAttributes)', () => {
     const doc2 = await markdownToProseMirror(md1);
     const md2 = convertProseMirrorToMarkdown(doc2);
 
-    // First export: no align emitted (the input doc carries no align), and the
-    // " in title becomes &quot;, the & in alt becomes &amp; via escapeAttr.
+    // #293 canon #8: src in the target; title/alt in the ALWAYS-emitted
+    // `excalidraw` comment as compact JSON (the " in title is JSON-escaped as \",
+    // the & in alt stays literal — JSON, not HTML). No align emitted (default).
     expect(md1).toBe(
-      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b"></div>',
+      '![](/e.excalidraw)<!--excalidraw {"title":"My \\"Diagram\\"","alt":"a&b"}-->',
     );
 
-    // Second export: align='center' has now materialized (the schema's
-    // diagramAttributes default), so md2 gains a data-align="center" suffix and
-    // is NOT byte-equal to md1. This one-time divergence is the diagram quirk.
-    expect(md2).toBe(
-      '<div data-type="excalidraw" data-src="/e.excalidraw" data-title="My &quot;Diagram&quot;" data-alt="a&amp;b" data-align="center"></div>',
-    );
-    expect(md2).not.toBe(md1);
+    // Byte-stable: align='center' re-materializes as the schema default on import
+    // and is omitted again on export #2, so md2 === md1 (no diagram quirk now).
+    expect(md2).toBe(md1);
 
-    // Re-import decodes the escaped entities back to the original characters.
+    // Re-import decodes the JSON payload back to the original characters.
     const attrs2 = doc2.content[0].attrs;
     expect(attrs2.title).toBe('My "Diagram"');
     expect(attrs2.alt).toBe('a&b');
diff --git a/packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json b/packages/prosemirror-markdown/test/fixtures/corpus/11-image-diagrams.json
similarity index 100%
rename from packages/prosemirror-markdown/test/fixtures/known-limitations/image-diagrams.json
rename to packages/prosemirror-markdown/test/fixtures/corpus/11-image-diagrams.json
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
index 2a8ca1eb..69c3cd8b 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -51,43 +51,49 @@ describe('columns / column (raw-HTML layout wrapper)', () => {
   });
 });
 
-describe('embed / audio / pdf (previously emitted nothing — invisible regression)', () => {
-  it('embed emits div[data-type="embed"] with src/provider', () => {
+describe('embed / audio / pdf top-level md-form + discriminator (#293 #8)', () => {
+  it('embed emits link-form [provider](src) + bare discriminator (defaults omitted)', () => {
+    // provider is the visible link text; align/width/height are all at their
+    // schema defaults (center/800/600), so the comment is name-only.
     expect(c({ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } })).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
+      '[iframe](https://x.com/e)<!--embed-->',
     );
   });
 
-  it('audio emits a div-wrapped <audio> with src', () => {
-    expect(c({ type: 'audio', attrs: { src: '/a.mp3' } })).toBe(
-      '<div><audio src="/a.mp3"></audio></div>',
-    );
+  it('audio emits image-form ![](src) + bare discriminator', () => {
+    expect(c({ type: 'audio', attrs: { src: '/a.mp3' } })).toBe('![](/a.mp3)<!--audio-->');
   });
 
-  it('pdf emits div[data-type="pdf"] with src and name', () => {
+  it('pdf emits link-form [name](src) + bare discriminator', () => {
     expect(c({ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf' } })).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf"></div>',
+      '[d.pdf](/d.pdf)<!--pdf-->',
     );
   });
 });
 
-describe('drawio / excalidraw data-align asymmetry (SPEC §11)', () => {
-  it('drawio: data-align is ABSENT when align is unset', () => {
+describe('drawio / excalidraw align emission in the discriminator comment (#293 #8)', () => {
+  it('drawio: NO align key when align is unset (bare discriminator)', () => {
     const out = c({ type: 'drawio', attrs: { src: '/d.drawio' } });
-    expect(out).toBe('<div data-type="drawio" data-src="/d.drawio"></div>');
-    expect(out).not.toContain('data-align');
+    expect(out).toBe('![](/d.drawio)<!--drawio-->');
+    expect(out).not.toContain('align');
   });
 
-  it('drawio: data-align is PRESENT for a non-default align', () => {
+  it('drawio: an "align" key IS present for a non-default align', () => {
     expect(c({ type: 'drawio', attrs: { src: '/d.drawio', align: 'right' } })).toBe(
-      '<div data-type="drawio" data-src="/d.drawio" data-align="right"></div>',
+      '![](/d.drawio)<!--drawio {"align":"right"}-->',
     );
   });
 
-  it('excalidraw: data-align is ABSENT when align is unset', () => {
+  it('drawio: the default align "center" is OMITTED (byte-stable image-form parity)', () => {
+    const out = c({ type: 'drawio', attrs: { src: '/d.drawio', align: 'center' } });
+    expect(out).toBe('![](/d.drawio)<!--drawio-->');
+    expect(out).not.toContain('align');
+  });
+
+  it('excalidraw: NO align key when align is unset (bare discriminator)', () => {
     const out = c({ type: 'excalidraw', attrs: { src: '/e.excalidraw' } });
-    expect(out).toBe('<div data-type="excalidraw" data-src="/e.excalidraw"></div>');
-    expect(out).not.toContain('data-align');
+    expect(out).toBe('![](/e.excalidraw)<!--excalidraw-->');
+    expect(out).not.toContain('align');
   });
 });
 
@@ -247,7 +253,10 @@ describe('empty / single-column tables', () => {
 // orderedList and a hardBreak inside a column.
 // ---------------------------------------------------------------------------
 describe('media / attachment / container full-attribute golden coverage', () => {
-  it('video: emits all optional attrs in source order (alt->aria-label, attachmentId/size/align/aspectRatio->data-*)', () => {
+  it('video: emits all optional attrs in the comment JSON in stable order (align center omitted)', () => {
+    // #293 canon #8 image-form: src in the target, all OTHER non-default attrs in
+    // the comment JSON (stable order alt/attachmentId/width/height/size/
+    // aspectRatio; align="center" is the default and is omitted).
     expect(
       c({
         type: 'video',
@@ -263,50 +272,49 @@ describe('media / attachment / container full-attribute golden coverage', () =>
         },
       }),
     ).toBe(
-      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
+      '![](/v.mp4)<!--video {"alt":"clip","attachmentId":"att-1","width":"640","height":"480","size":"1234","aspectRatio":"1.777"}-->',
     );
   });
 
-  it('video: with only src, every optional guard takes its false branch (src-only <video>, no data-type on wrapper)', () => {
-    expect(c({ type: 'video', attrs: { src: '/v.mp4' } })).toBe(
-      '<div><video src="/v.mp4"></video></div>',
-    );
+  it('video: with only src, the discriminator is still emitted name-only (bare ![](src)<!--video-->)', () => {
+    expect(c({ type: 'video', attrs: { src: '/v.mp4' } })).toBe('![](/v.mp4)<!--video-->');
   });
 
-  it('youtube + embed: each emits its full optional attr set in source order', () => {
-    // (a) youtube: width/height/align all present -> data-* in order.
+  it('youtube + embed: each emits its full optional attr set in the discriminator comment', () => {
+    // (a) youtube (image-form): width/height/align(right) in the comment JSON.
     expect(
       c({
         type: 'youtube',
         attrs: { src: 'https://youtu.be/abc', width: 560, height: 315, align: 'right' },
       }),
     ).toBe(
-      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
+      '![](https://youtu.be/abc)<!--youtube {"width":"560","height":"315","align":"right"}-->',
     );
-    // (b) embed: align/width/height optional branches after src+provider.
+    // (b) embed (link-form): provider is the visible text; a non-default align/
+    // width/height (left/600/400 — the defaults are center/800/600) ride in JSON.
     expect(
       c({
         type: 'embed',
         attrs: { src: 'https://x.com/e', provider: 'iframe', align: 'left', width: 600, height: 400 },
       }),
     ).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
+      '[iframe](https://x.com/e)<!--embed {"align":"left","width":"600","height":"400"}-->',
     );
   });
 
-  it('audio: emits data-attachment-id then data-size after src when both are set', () => {
+  it('audio: emits attachmentId then size in the comment JSON when both are set', () => {
     expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7', size: 9001 } })).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
+      '![](/a.mp3)<!--audio {"attachmentId":"att-7","size":"9001"}-->',
     );
   });
 
-  it('audio: with attachmentId but no size, data-size is suppressed (size != null false branch)', () => {
+  it('audio: with attachmentId but no size, the size key is suppressed (size != null false branch)', () => {
     expect(c({ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'att-7' } })).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7"></audio></div>',
+      '![](/a.mp3)<!--audio {"attachmentId":"att-7"}-->',
     );
   });
 
-  it('pdf: emits the full optional attr set in order (data-name, data-attachment-id, data-size, width, height)', () => {
+  it('pdf: emits the full optional attr set in the comment JSON (attachmentId, size, width, height)', () => {
     expect(
       c({
         type: 'pdf',
@@ -320,11 +328,11 @@ describe('media / attachment / container full-attribute golden coverage', () =>
         },
       }),
     ).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9" data-size="2048" width="800" height="600"></div>',
+      '[d.pdf](/d.pdf)<!--pdf {"attachmentId":"att-9","size":"2048","width":"800","height":"600"}-->',
     );
   });
 
-  it('attachment: emits data-attachment-name/mime/size/id in order after the always-present url', () => {
+  it('attachment: emits mime/size/attachmentId in the comment JSON after the [name](url) target', () => {
     expect(
       c({
         type: 'attachment',
@@ -337,13 +345,14 @@ describe('media / attachment / container full-attribute golden coverage', () =>
         },
       }),
     ).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
+      '[f.zip](/f.zip)<!--attachment {"mime":"application/zip","size":"512","attachmentId":"att-3"}-->',
     );
   });
 
-  it('attachment: with only a url, no spurious data-attachment-name/mime/size/id appear (all guards false)', () => {
+  it('attachment: with only a url, the link text is empty and the discriminator is name-only', () => {
+    // name is null -> empty visible text `[]`; no mime/size/id -> bare comment.
     expect(c({ type: 'attachment', attrs: { url: '/f.zip' } })).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip"></div>',
+      '[](/f.zip)<!--attachment-->',
     );
   });
 
diff --git a/packages/prosemirror-markdown/test/markdown-converter.test.ts b/packages/prosemirror-markdown/test/markdown-converter.test.ts
index 98cb88c0..5a8bddbb 100644
--- a/packages/prosemirror-markdown/test/markdown-converter.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter.test.ts
@@ -430,33 +430,31 @@ describe('convertProseMirrorToMarkdown', () => {
       );
     });
 
-    it('attachment emits div with schema data-attachment-* attrs', () => {
+    it('attachment emits link-form [name](url) + discriminator comment (#293 #8)', () => {
       const out = convertProseMirrorToMarkdown(
         doc({
           type: 'attachment',
           attrs: { url: '/files/x.zip', name: 'x.zip', mime: 'application/zip', size: 99 },
         }),
       );
+      // #293 canon #8: url is the markdown target, name is the visible link text,
+      // and every other attr rides in the ALWAYS-emitted `attachment` comment.
       expect(out).toBe(
-        '<div data-type="attachment" data-attachment-url="/files/x.zip" ' +
-          'data-attachment-name="x.zip" data-attachment-mime="application/zip" ' +
-          'data-attachment-size="99"></div>',
+        '[x.zip](/files/x.zip)<!--attachment {"mime":"application/zip","size":"99"}-->',
       );
     });
 
-    it('video emits a <div>-wrapped <video> with schema attrs', () => {
+    it('video emits image-form ![](src) + discriminator comment (#293 #8)', () => {
       const out = convertProseMirrorToMarkdown(
         doc({
           type: 'video',
           attrs: { src: '/v.mp4', alt: 'clip', width: 640 },
         }),
       );
-      expect(out).toBe(
-        '<div><video src="/v.mp4" aria-label="clip" width="640"></video></div>',
-      );
+      expect(out).toBe('![](/v.mp4)<!--video {"alt":"clip","width":"640"}-->');
     });
 
-    it('youtube emits a div[data-type="youtube"] with data-src', () => {
+    it('youtube emits image-form ![](src) + discriminator comment (#293 #8)', () => {
       const out = convertProseMirrorToMarkdown(
         doc({
           type: 'youtube',
@@ -464,8 +462,7 @@ describe('convertProseMirrorToMarkdown', () => {
         }),
       );
       expect(out).toBe(
-        '<div data-type="youtube" data-src="https://youtu.be/abc" ' +
-          'data-width="560" data-height="315"></div>',
+        '![](https://youtu.be/abc)<!--youtube {"width":"560","height":"315"}-->',
       );
     });
   });
diff --git a/packages/prosemirror-markdown/test/media-comments.test.ts b/packages/prosemirror-markdown/test/media-comments.test.ts
new file mode 100644
index 00000000..c8f8a2c5
--- /dev/null
+++ b/packages/prosemirror-markdown/test/media-comments.test.ts
@@ -0,0 +1,474 @@
+import { describe, expect, it } from 'vitest';
+import {
+  convertProseMirrorToMarkdown,
+  markdownToProseMirror,
+} from 'docmost-client';
+
+// ---------------------------------------------------------------------------
+// #293 canon #8 — media family -> md-form + discriminator comment.
+//
+// Ten node types move their TOP-LEVEL form from raw schema HTML to a readable
+// markdown target plus a discriminator `<!--name {…}-->` comment whose NAME
+// selects the node type:
+//
+//   IMAGE-FORM  `![](src)<!--name …-->`   youtube, video, audio, drawio, excalidraw
+//   LINK-FORM   `[text](src)<!--name …-->` pdf, attachment, embed
+//   STANDALONE  `<!--name …-->`            pageEmbed (pageembed), transclusionReference (transclusion)
+//
+// For EACH type this suite pins (1) a representative node -> exact md + a
+// byte-stable, lossless round-trip; (2) a MINIMAL node -> the discriminator is
+// STILL emitted and re-imports as the right TYPE (never an image/link); (3) the
+// same node INSIDE a column -> the schema-HTML form (no comment). Plus the
+// discriminator-integrity contract (a bare image / bare link with NO comment)
+// and fail-open behavior. The columns/raw-HTML form is the git-sync data path's
+// SAFETY net: a comment node is dropped inside a raw-HTML block, so these MUST
+// stay schema HTML there or the node vanishes.
+// ---------------------------------------------------------------------------
+
+const mkDoc = (content: any[]) => ({ type: 'doc', content });
+
+/** export -> import -> export, returning both markdowns and the re-parsed doc. */
+async function roundTrip(doc: any) {
+  const md1 = convertProseMirrorToMarkdown(doc);
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, md2, doc2 };
+}
+
+/** Find the first node of a given type anywhere in a PM doc tree. */
+const findFirst = (node: any, type: string): any => {
+  if (node && node.type === type) return node;
+  for (const child of node?.content || []) {
+    const hit = findFirst(child, type);
+    if (hit) return hit;
+  }
+  return null;
+};
+
+/** True when any text run in the tree carries a `link` MARK (links are marks). */
+const hasLinkMark = (node: any): boolean => {
+  if (Array.isArray(node?.marks) && node.marks.some((m: any) => m?.type === 'link'))
+    return true;
+  return (node?.content || []).some((c: any) => hasLinkMark(c));
+};
+
+/** Wrap a single node in a two-column layout (the raw-HTML container path). */
+const inColumn = (node: any) =>
+  mkDoc([
+    {
+      type: 'columns',
+      attrs: { layout: 'two_equal' },
+      content: [
+        { type: 'column', content: [node] },
+        { type: 'column', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'x' }] }] },
+      ],
+    },
+  ]);
+
+// ---------------------------------------------------------------------------
+// Per-type: exact md, lossless byte-stable round-trip, minimal-node
+// discriminator, and the in-column schema-HTML form.
+// ---------------------------------------------------------------------------
+
+describe('#293 #8 IMAGE-FORM: youtube', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip', async () => {
+    const doc = mkDoc([
+      { type: 'youtube', attrs: { src: 'https://youtu.be/abc', width: 560, height: 315, align: 'right' } },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+    expect(md1).toBe(
+      '![](https://youtu.be/abc)<!--youtube {"width":"560","height":"315","align":"right"}-->',
+    );
+    expect(md2).toBe(md1);
+    const yt = findFirst(doc2, 'youtube');
+    expect(yt).not.toBeNull();
+    expect(yt.attrs.src).toBe('https://youtu.be/abc');
+    expect(yt.attrs.width).toBe('560');
+    expect(yt.attrs.height).toBe('315');
+    expect(yt.attrs.align).toBe('right');
+  });
+
+  it('minimal node -> discriminator STILL emitted; round-trips to youtube (NOT image)', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'youtube', attrs: { src: '/y' } }]));
+    expect(md1).toBe('![](/y)<!--youtube-->');
+    expect(findFirst(doc2, 'youtube')).not.toBeNull();
+    expect(findFirst(doc2, 'image')).toBeNull();
+  });
+
+  it('inside a column -> schema-HTML form (data-type="youtube", NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'youtube', attrs: { src: '/y', width: 560 } }),
+    );
+    expect(md1).toContain('data-type="youtube"');
+    expect(md1).toContain('data-src="/y"');
+    expect(md1).not.toContain('<!--youtube');
+    expect(findFirst(doc2, 'youtube')).not.toBeNull();
+  });
+});
+
+describe('#293 #8 IMAGE-FORM: video', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip (attachmentId preserved)', async () => {
+    const doc = mkDoc([
+      {
+        type: 'video',
+        attrs: { src: '/v.mp4', alt: 'clip', attachmentId: 'ATT_V', width: 640, height: 480, size: 1234, aspectRatio: 1.777 },
+      },
+    ]);
+    const { md1, md2, doc2 } = await roundTrip(doc);
+    expect(md1).toBe(
+      '![](/v.mp4)<!--video {"alt":"clip","attachmentId":"ATT_V","width":"640","height":"480","size":"1234","aspectRatio":"1.777"}-->',
+    );
+    expect(md2).toBe(md1);
+    const v = findFirst(doc2, 'video');
+    expect(v.attrs.src).toBe('/v.mp4');
+    expect(v.attrs.alt).toBe('clip');
+    // Data-loss-critical id link survives.
+    expect(v.attrs.attachmentId).toBe('ATT_V');
+    expect(v.attrs.aspectRatio).toBe('1.777');
+  });
+
+  it('minimal node -> discriminator STILL emitted; round-trips to video (NOT image)', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'video', attrs: { src: '/v.mp4' } }]));
+    expect(md1).toBe('![](/v.mp4)<!--video-->');
+    expect(findFirst(doc2, 'video')).not.toBeNull();
+    expect(findFirst(doc2, 'image')).toBeNull();
+  });
+
+  it('inside a column -> schema-HTML <video> form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'video', attrs: { src: '/v.mp4', attachmentId: 'ATT_V' } }),
+    );
+    expect(md1).toContain('<video ');
+    expect(md1).toContain('data-attachment-id="ATT_V"');
+    expect(md1).not.toContain('<!--video');
+    expect(findFirst(doc2, 'video').attrs.attachmentId).toBe('ATT_V');
+  });
+});
+
+describe('#293 #8 IMAGE-FORM: audio', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'audio', attrs: { src: '/a.mp3', attachmentId: 'ATT_A', size: 9001 } }]),
+    );
+    expect(md1).toBe('![](/a.mp3)<!--audio {"attachmentId":"ATT_A","size":"9001"}-->');
+    expect(md2).toBe(md1);
+    const a = findFirst(doc2, 'audio');
+    expect(a.attrs.src).toBe('/a.mp3');
+    expect(a.attrs.attachmentId).toBe('ATT_A');
+    expect(a.attrs.size).toBe('9001');
+  });
+
+  it('minimal node -> discriminator STILL emitted; round-trips to audio (NOT image)', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'audio', attrs: { src: '/a.mp3' } }]));
+    expect(md1).toBe('![](/a.mp3)<!--audio-->');
+    expect(findFirst(doc2, 'audio')).not.toBeNull();
+    expect(findFirst(doc2, 'image')).toBeNull();
+  });
+
+  it('inside a column -> schema-HTML <audio> form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(inColumn({ type: 'audio', attrs: { src: '/a.mp3' } }));
+    expect(md1).toContain('<audio ');
+    expect(md1).not.toContain('<!--audio');
+    expect(findFirst(doc2, 'audio')).not.toBeNull();
+  });
+});
+
+describe('#293 #8 IMAGE-FORM: drawio / excalidraw (NAME discriminates the two)', () => {
+  for (const type of ['drawio', 'excalidraw'] as const) {
+    it(`${type}: representative node -> exact md + lossless byte-stable round-trip`, async () => {
+      const { md1, md2, doc2 } = await roundTrip(
+        mkDoc([{ type, attrs: { src: `/d.${type}`, title: 'T', width: 640, attachmentId: 'ATT_D' } }]),
+      );
+      expect(md1).toBe(`![](/d.${type})<!--${type} {"title":"T","width":"640","attachmentId":"ATT_D"}-->`);
+      expect(md2).toBe(md1);
+      const d = findFirst(doc2, type);
+      expect(d).not.toBeNull();
+      expect(d.attrs.src).toBe(`/d.${type}`);
+      expect(d.attrs.title).toBe('T');
+      expect(d.attrs.attachmentId).toBe('ATT_D');
+      // The OTHER diagram type must NOT appear (NAME is the discriminator).
+      expect(findFirst(doc2, type === 'drawio' ? 'excalidraw' : 'drawio')).toBeNull();
+    });
+
+    it(`${type}: minimal node -> discriminator STILL emitted; round-trips to ${type} (NOT image)`, async () => {
+      const { md1, doc2 } = await roundTrip(mkDoc([{ type, attrs: { src: `/d.${type}` } }]));
+      expect(md1).toBe(`![](/d.${type})<!--${type}-->`);
+      expect(findFirst(doc2, type)).not.toBeNull();
+      expect(findFirst(doc2, 'image')).toBeNull();
+    });
+
+    it(`${type}: inside a column -> schema-HTML data-type="${type}" form (NO comment)`, async () => {
+      const { md1, doc2 } = await roundTrip(
+        inColumn({ type, attrs: { src: `/d.${type}`, attachmentId: 'ATT_D' } }),
+      );
+      expect(md1).toContain(`data-type="${type}"`);
+      expect(md1).not.toContain(`<!--${type}`);
+      expect(findFirst(doc2, type).attrs.attachmentId).toBe('ATT_D');
+    });
+  }
+});
+
+describe('#293 #8 LINK-FORM: pdf', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf', attachmentId: 'ATT_P', size: 2048 } }]),
+    );
+    expect(md1).toBe('[d.pdf](/d.pdf)<!--pdf {"attachmentId":"ATT_P","size":"2048"}-->');
+    expect(md2).toBe(md1);
+    const p = findFirst(doc2, 'pdf');
+    expect(p.attrs.src).toBe('/d.pdf');
+    expect(p.attrs.name).toBe('d.pdf');
+    expect(p.attrs.attachmentId).toBe('ATT_P');
+    expect(p.attrs.size).toBe('2048');
+  });
+
+  it('minimal node -> discriminator STILL emitted; round-trips to pdf (NOT a plain link)', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf' } }]));
+    expect(md1).toBe('[d.pdf](/d.pdf)<!--pdf-->');
+    expect(findFirst(doc2, 'pdf')).not.toBeNull();
+    expect(hasLinkMark(doc2)).toBe(false);
+  });
+
+  it('a filename with []\\ is escaped in the link text and round-trips losslessly', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'pdf', attrs: { src: '/x', name: 'a]b[c.pdf' } }]));
+    expect(md1).toBe('[a\\]b\\[c.pdf](/x)<!--pdf-->');
+    expect(findFirst(doc2, 'pdf').attrs.name).toBe('a]b[c.pdf');
+  });
+
+  it('a filename with markdown-ACTIVE punctuation round-trips byte- AND value-stable', async () => {
+    // The link label is parsed as inline content, so emphasis/code/strike/
+    // autolink/entity/image markers would be consumed and lost via a.textContent
+    // if not escaped. Each of these names would corrupt without the full escape
+    // (e.g. `report *v2*.pdf` -> `report v2.pdf`). Assert both value AND byte
+    // stability (md2 === md1) so a real filename cannot silently churn a vault.
+    for (const name of [
+      'report *v2*.pdf',
+      'draft _final_.pdf',
+      'use `code`.pdf',
+      'a~~b~~.pdf',
+      'tag <x> & y.pdf',
+      'amp &amp; here.pdf',
+      '![shot](x).pdf',
+    ]) {
+      const { md1, md2, doc2 } = await roundTrip(mkDoc([{ type: 'pdf', attrs: { src: '/x', name } }]));
+      expect(md2).toBe(md1); // byte-stable, no churn
+      expect(findFirst(doc2, 'pdf').attrs.name).toBe(name); // exact value preserved
+    }
+  });
+
+  it('inside a column -> schema-HTML data-type="pdf" form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'pdf', attrs: { src: '/d.pdf', name: 'd.pdf', attachmentId: 'ATT_P' } }),
+    );
+    expect(md1).toContain('data-type="pdf"');
+    expect(md1).toContain('data-name="d.pdf"');
+    expect(md1).not.toContain('<!--pdf');
+    expect(findFirst(doc2, 'pdf').attrs.attachmentId).toBe('ATT_P');
+  });
+});
+
+describe('#293 #8 LINK-FORM: attachment', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'attachment', attrs: { url: '/f.zip', name: 'f.zip', mime: 'application/zip', size: 512, attachmentId: 'ATT_Z' } }]),
+    );
+    expect(md1).toBe(
+      '[f.zip](/f.zip)<!--attachment {"mime":"application/zip","size":"512","attachmentId":"ATT_Z"}-->',
+    );
+    expect(md2).toBe(md1);
+    const a = findFirst(doc2, 'attachment');
+    expect(a.attrs.url).toBe('/f.zip');
+    expect(a.attrs.name).toBe('f.zip');
+    expect(a.attrs.mime).toBe('application/zip');
+    expect(a.attrs.attachmentId).toBe('ATT_Z');
+  });
+
+  it('minimal node (url only) -> empty text + discriminator; round-trips to attachment (NOT a link)', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'attachment', attrs: { url: '/f.zip' } }]));
+    expect(md1).toBe('[](/f.zip)<!--attachment-->');
+    const a = findFirst(doc2, 'attachment');
+    expect(a).not.toBeNull();
+    expect(a.attrs.url).toBe('/f.zip');
+    expect(hasLinkMark(doc2)).toBe(false);
+  });
+
+  it('inside a column -> schema-HTML data-type="attachment" form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'attachment', attrs: { url: '/f.zip', name: 'f.zip', attachmentId: 'ATT_Z' } }),
+    );
+    expect(md1).toContain('data-type="attachment"');
+    expect(md1).toContain('data-attachment-url="/f.zip"');
+    expect(md1).not.toContain('<!--attachment');
+    expect(findFirst(doc2, 'attachment').attrs.attachmentId).toBe('ATT_Z');
+  });
+});
+
+describe('#293 #8 LINK-FORM: embed', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe', align: 'left', width: 600, height: 400 } }]),
+    );
+    expect(md1).toBe('[iframe](https://x.com/e)<!--embed {"align":"left","width":"600","height":"400"}-->');
+    expect(md2).toBe(md1);
+    const e = findFirst(doc2, 'embed');
+    expect(e.attrs.src).toBe('https://x.com/e');
+    expect(e.attrs.provider).toBe('iframe');
+    expect(e.attrs.align).toBe('left');
+  });
+
+  it('minimal node -> discriminator STILL emitted; round-trips to embed (NOT a link)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      mkDoc([{ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } }]),
+    );
+    expect(md1).toBe('[iframe](https://x.com/e)<!--embed-->');
+    const e = findFirst(doc2, 'embed');
+    expect(e).not.toBeNull();
+    expect(e.attrs.provider).toBe('iframe');
+    expect(hasLinkMark(doc2)).toBe(false);
+  });
+
+  it('inside a column -> schema-HTML data-type="embed" form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } }),
+    );
+    expect(md1).toContain('data-type="embed"');
+    expect(md1).toContain('data-provider="iframe"');
+    expect(md1).not.toContain('<!--embed');
+    expect(findFirst(doc2, 'embed').attrs.provider).toBe('iframe');
+  });
+});
+
+describe('#293 #8 STANDALONE: pageEmbed', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip (sourcePageId preserved)', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'pageEmbed', attrs: { sourcePageId: 'PAGE_X' } }]),
+    );
+    expect(md1).toBe('<!--pageembed {"sourcePageId":"PAGE_X"}-->');
+    expect(md2).toBe(md1);
+    const pe = findFirst(doc2, 'pageEmbed');
+    expect(pe).not.toBeNull();
+    expect(pe.attrs.sourcePageId).toBe('PAGE_X');
+  });
+
+  it('minimal node -> name-only discriminator; round-trips to pageEmbed', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'pageEmbed', attrs: {} }]));
+    expect(md1).toBe('<!--pageembed-->');
+    expect(findFirst(doc2, 'pageEmbed')).not.toBeNull();
+  });
+
+  it('inside a column -> schema-HTML data-type="pageEmbed" form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'pageEmbed', attrs: { sourcePageId: 'PAGE_X' } }),
+    );
+    expect(md1).toContain('data-type="pageEmbed"');
+    expect(md1).toContain('data-source-page-id="PAGE_X"');
+    expect(md1).not.toContain('<!--pageembed');
+    expect(findFirst(doc2, 'pageEmbed').attrs.sourcePageId).toBe('PAGE_X');
+  });
+});
+
+describe('#293 #8 STANDALONE: transclusionReference', () => {
+  it('representative node -> exact md + lossless byte-stable round-trip (both id links preserved)', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      mkDoc([{ type: 'transclusionReference', attrs: { sourcePageId: 'PAGE_X', transclusionId: 'TR_Y' } }]),
+    );
+    expect(md1).toBe('<!--transclusion {"sourcePageId":"PAGE_X","transclusionId":"TR_Y"}-->');
+    expect(md2).toBe(md1);
+    const tr = findFirst(doc2, 'transclusionReference');
+    expect(tr).not.toBeNull();
+    expect(tr.attrs.sourcePageId).toBe('PAGE_X');
+    expect(tr.attrs.transclusionId).toBe('TR_Y');
+  });
+
+  it('minimal node -> name-only discriminator; round-trips to transclusionReference', async () => {
+    const { md1, doc2 } = await roundTrip(mkDoc([{ type: 'transclusionReference', attrs: {} }]));
+    expect(md1).toBe('<!--transclusion-->');
+    expect(findFirst(doc2, 'transclusionReference')).not.toBeNull();
+  });
+
+  it('inside a column -> schema-HTML data-type="transclusionReference" form (NO comment)', async () => {
+    const { md1, doc2 } = await roundTrip(
+      inColumn({ type: 'transclusionReference', attrs: { sourcePageId: 'PAGE_X', transclusionId: 'TR_Y' } }),
+    );
+    expect(md1).toContain('data-type="transclusionReference"');
+    expect(md1).toContain('data-transclusion-id="TR_Y"');
+    expect(md1).not.toContain('<!--transclusion');
+    expect(findFirst(doc2, 'transclusionReference').attrs.transclusionId).toBe('TR_Y');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Discriminator integrity: the NAME is the ONLY type selector. A bare markdown
+// target with NO following comment is NEVER sniffed into a media type.
+// ---------------------------------------------------------------------------
+
+describe('#293 #8 discriminator integrity (no comment -> never a media type)', () => {
+  it('a bare ![](url) with NO comment is an IMAGE, never youtube/video/etc.', async () => {
+    const doc2 = await markdownToProseMirror('![](https://youtu.be/abc)');
+    expect(findFirst(doc2, 'image')).not.toBeNull();
+    for (const t of ['youtube', 'video', 'audio', 'drawio', 'excalidraw']) {
+      expect(findFirst(doc2, t)).toBeNull();
+    }
+  });
+
+  it('a bare [text](src) with NO comment is a plain link, never pdf/attachment/embed', async () => {
+    const doc2 = await markdownToProseMirror('[report.pdf](/files/report.pdf)');
+    // The link MARK survives; NO media node materializes.
+    expect(hasLinkMark(doc2)).toBe(true);
+    for (const t of ['pdf', 'attachment', 'embed']) {
+      expect(findFirst(doc2, t)).toBeNull();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Fail-open: malformed/misplaced discriminators never crash and never corrupt.
+// ---------------------------------------------------------------------------
+
+describe('#293 #8 fail-open', () => {
+  it('malformed JSON after an image-form target does not throw; stays an image', async () => {
+    const md = '![](u.png)<!--youtube {bad-->';
+    const doc2 = await markdownToProseMirror(md);
+    // The comment is inert (parseAttachedComment returns null), so the img is
+    // left as a plain image and nothing throws.
+    expect(findFirst(doc2, 'image')).not.toBeNull();
+    expect(findFirst(doc2, 'youtube')).toBeNull();
+    // Byte-stable on the way back out (no phantom growth).
+    const back = convertProseMirrorToMarkdown(doc2);
+    expect(convertProseMirrorToMarkdown(await markdownToProseMirror(back))).toBe(back);
+  });
+
+  it('malformed JSON after a link-form target does not throw; stays a plain link', async () => {
+    const doc2 = await markdownToProseMirror('[f](/x)<!--attachment {bad}-->');
+    expect(findFirst(doc2, 'attachment')).toBeNull();
+    expect(hasLinkMark(doc2)).toBe(true);
+  });
+
+  it('a malformed standalone discriminator does not throw and materializes no atom', async () => {
+    const doc2 = await markdownToProseMirror('<!--pageembed {oops-->');
+    expect(findFirst(doc2, 'pageEmbed')).toBeNull();
+    expect(findFirst(doc2, 'transclusionReference')).toBeNull();
+  });
+
+  it('an unknown key in a valid comment is ignored (fail-open); the node still materializes', async () => {
+    const doc2 = await markdownToProseMirror('![](/y)<!--youtube {"unknownKey":1,"width":"560"}-->');
+    const yt = findFirst(doc2, 'youtube');
+    expect(yt).not.toBeNull();
+    expect(yt.attrs.width).toBe('560');
+    expect(yt.attrs).not.toHaveProperty('unknownKey');
+  });
+
+  it('an image-form discriminator with NO adjacent <img> is inert', async () => {
+    // `text <!--youtube-->` puts the comment inside a <p> next to text, not an
+    // <img>: wrong element -> inert, no youtube node, no crash.
+    const doc2 = await markdownToProseMirror('some text <!--youtube-->');
+    expect(findFirst(doc2, 'youtube')).toBeNull();
+    expect(findFirst(doc2, 'paragraph')).not.toBeNull();
+  });
+
+  it('a standalone media discriminator in ATTACHED position (next to text) is inert', async () => {
+    const doc2 = await markdownToProseMirror('inline text <!--pageembed {"sourcePageId":"p1"}-->');
+    expect(findFirst(doc2, 'pageEmbed')).toBeNull();
+    expect(findFirst(doc2, 'paragraph')).not.toBeNull();
+  });
+});
diff --git a/packages/prosemirror-markdown/test/media-roundtrip.test.ts b/packages/prosemirror-markdown/test/media-roundtrip.test.ts
index cc687704..9cde5541 100644
--- a/packages/prosemirror-markdown/test/media-roundtrip.test.ts
+++ b/packages/prosemirror-markdown/test/media-roundtrip.test.ts
@@ -52,9 +52,9 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
-    expect(md1).toBe(
-      '<div><audio src="/a.mp3" data-attachment-id="att-7" data-size="9001"></audio></div>',
-    );
+    // #293 canon #8 image-form: `![](src)` + the ALWAYS-emitted `audio`
+    // discriminator carrying the other attrs as JSON (numerics stringified).
+    expect(md1).toBe('![](/a.mp3)<!--audio {"attachmentId":"att-7","size":"9001"}-->');
     // Byte-stable: a second export reproduces the first exactly.
     expect(md2).toBe(md1);
 
@@ -87,8 +87,10 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
+    // #293 canon #8 image-form: align="center" (the schema default) is OMITTED,
+    // so the whole optional set except align rides in the `video` comment JSON.
     expect(md1).toBe(
-      '<div><video src="/v.mp4" aria-label="clip" data-attachment-id="att-1" width="640" height="480" data-size="1234" data-align="center" data-aspect-ratio="1.777"></video></div>',
+      '![](/v.mp4)<!--video {"alt":"clip","attachmentId":"att-1","width":"640","height":"480","size":"1234","aspectRatio":"1.777"}-->',
     );
     expect(md2).toBe(md1);
 
@@ -108,19 +110,26 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
   });
 
   // 3. minimal video (only src) --------------------------------------------
-  it('minimal video (src only): NOT byte-stable (gains data-align="center") but canonically equal', async () => {
+  it('minimal video (src only): the discriminator is STILL emitted; byte-stable; round-trips to VIDEO not image', async () => {
     const doc = mkDoc([{ type: 'video', attrs: { src: '/v.mp4' } }]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
-    expect(md1).toBe('<div><video src="/v.mp4"></video></div>');
-    // video.align has a non-null schema default 'center' that materializes on
-    // import; the converter only emits data-align when set, so export #2 grows
-    // by data-align="center" exactly once (the documented one-time asymmetry).
-    expect(md2).toBe('<div><video src="/v.mp4" data-align="center"></video></div>');
-    expect(md2).not.toBe(md1);
+    // #293 canon #8: the comment is the type discriminator, so it is emitted even
+    // with no extra attrs (name-only). Without it a bare `![](src)` would be read
+    // as an `image`. align="center" default is omitted, so the form is byte-stable
+    // (unlike the old div-form, which gained data-align="center" on import).
+    expect(md1).toBe('![](/v.mp4)<!--video-->');
+    expect(md2).toBe(md1);
 
-    // align:'center' is normalized away via KNOWN_DEFAULTS.video, so despite the
-    // byte growth the documents ARE canonically equal.
+    // Critically: it round-trips to a VIDEO node, NOT an image.
+    const video = findFirst(doc2, 'video');
+    expect(video).not.toBeNull();
+    expect(video.type).toBe('video');
+    expect(findFirst(doc2, 'image')).toBeNull();
+    expect(video.attrs.src).toBe('/v.mp4');
+
+    // align:'center' is normalized away via KNOWN_DEFAULTS.video, so the
+    // documents ARE canonically equal.
     expect(docsCanonicallyEqual(doc, doc2)).toBe(true);
   });
 
@@ -131,9 +140,9 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
-    expect(md1).toBe(
-      '<div data-type="pdf" src="/d.pdf" data-name="d.pdf" data-attachment-id="att-9"></div>',
-    );
+    // #293 canon #8 link-form: `[name](src)` + the `pdf` discriminator; the id
+    // link (attachmentId) is data-loss-critical and rides in the comment JSON.
+    expect(md1).toBe('[d.pdf](/d.pdf)<!--pdf {"attachmentId":"att-9"}-->');
     expect(md2).toBe(md1);
 
     const pdf = findFirst(doc2, 'pdf');
@@ -163,8 +172,10 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
+    // #293 canon #8 link-form: url is the target, name the visible text, and
+    // mime/size/attachmentId ride in the `attachment` discriminator comment.
     expect(md1).toBe(
-      '<div data-type="attachment" data-attachment-url="/f.zip" data-attachment-name="f.zip" data-attachment-mime="application/zip" data-attachment-size="512" data-attachment-id="att-3"></div>',
+      '[f.zip](/f.zip)<!--attachment {"mime":"application/zip","size":"512","attachmentId":"att-3"}-->',
     );
     expect(md2).toBe(md1);
 
@@ -197,8 +208,10 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
+    // #293 canon #8 link-form: provider is the visible text; the non-default
+    // align/width/height (defaults center/800/600) ride in the comment JSON.
     expect(md1).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="left" data-width="600" data-height="400"></div>',
+      '[iframe](https://x.com/e)<!--embed {"align":"left","width":"600","height":"400"}-->',
     );
     expect(md2).toBe(md1);
 
@@ -213,29 +226,27 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
   });
 
   // 7. minimal embed (only src+provider) -----------------------------------
-  it('minimal embed (src+provider): NOT byte-stable; defaults width/height materialize as NUMBERS 800/600', async () => {
+  it('minimal embed (src+provider): discriminator still emitted; byte-stable; defaults materialize as NUMBERS 800/600', async () => {
     const doc = mkDoc([
       { type: 'embed', attrs: { src: 'https://x.com/e', provider: 'iframe' } },
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
-    expect(md1).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe"></div>',
-    );
-    // embed has non-null schema defaults align='center', width=800, height=600
-    // that the converter never emits on export #1 but materialize on import, so
-    // export #2 grows by three data-* attrs (a one-time divergence).
-    expect(md2).toBe(
-      '<div data-type="embed" data-src="https://x.com/e" data-provider="iframe" data-align="center" data-width="800" data-height="600"></div>',
-    );
-    expect(md2).not.toBe(md1);
+    // #293 canon #8: align/width/height are all at their schema defaults
+    // (center/800/600), so the discriminator is name-only. Unlike the old
+    // div-form (which grew three data-* attrs on import), the md-form OMITS the
+    // defaults on BOTH exports, so it is byte-stable from export #1.
+    expect(md1).toBe('[iframe](https://x.com/e)<!--embed-->');
+    expect(md2).toBe(md1);
 
     const embed = findFirst(doc2, 'embed');
     expect(embed).not.toBeNull();
+    expect(embed.type).toBe('embed');
+    // Round-trips to EMBED, not a plain link.
+    expect(embed.attrs.provider).toBe('iframe');
     expect(embed.attrs.align).toBe('center');
-    // NOTE: these come from the addAttributes default (NOT parseHTML), so on the
-    // FIRST import they are the NUMBERS 800/600, not strings — parseHTML only
-    // runs when the attribute is actually present on the imported element.
+    // NOTE: these come from the addAttributes default (NOT parseHTML), so they
+    // are the NUMBERS 800/600 — parseHTML only runs when the attribute is present.
     expect(embed.attrs.width).toBe(800);
     expect(embed.attrs.height).toBe(600);
   });
@@ -255,8 +266,10 @@ describe('media atom round-trip (audio/video/pdf/attachment/embed/youtube)', ()
     ]);
     const { md1, md2, doc2 } = await roundTrip(doc);
 
+    // #293 canon #8 image-form: width/height/align(right) ride in the `youtube`
+    // discriminator comment (align "right" is non-default so it is kept).
     expect(md1).toBe(
-      '<div data-type="youtube" data-src="https://youtu.be/abc" data-width="560" data-height="315" data-align="right"></div>',
+      '![](https://youtu.be/abc)<!--youtube {"width":"560","height":"315","align":"right"}-->',
     );
     expect(md2).toBe(md1);
 
diff --git a/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts b/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
index b715b170..05814d4a 100644
--- a/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
+++ b/packages/prosemirror-markdown/test/roundtrip-corpus.test.ts
@@ -12,7 +12,6 @@ import {
 // Resolve fixtures relative to this test file so the test is CWD-independent.
 const here = dirname(fileURLToPath(import.meta.url));
 const CORPUS_DIR = join(here, 'fixtures', 'corpus');
-const KNOWN_LIMITATIONS_DIR = join(here, 'fixtures', 'known-limitations');
 
 /** Run a single document through export -> import -> export. */
 async function roundTrip(doc: any) {
@@ -50,55 +49,20 @@ describe('round-trip corpus (SPEC §11)', () => {
 });
 
 // ---------------------------------------------------------------------------
-// KNOWN CONVERTER LIMITATIONS (isolated so they do NOT make CI red).
+// FORMER KNOWN LIMITATION — now promoted into the green corpus above.
 //
-// SPEC §11 explicitly flags images and diagrams as high round-trip risk. These
-// fixtures are kept OUT of the green corpus above and asserted with `it.fails`
-// so the documented divergence is locked in (the test FAILS if the converter
-// ever starts round-tripping them — at which point promote the fixture into
-// the corpus). The precise divergences for `image-diagrams.json` are:
+// SPEC §11 flagged images and diagrams as high round-trip risk, and
+// `image-diagrams.json` (a paragraph + block image + drawio + excalidraw) was
+// held out here with `it.fails` because it was not byte-stable on export #1: the
+// drawio/excalidraw `align` default "center" materialized on import, so export
+// #2 grew a `data-align="center"` suffix.
 //
-//   * A BLOCK-LEVEL image preceded by a paragraph is NOT byte-stable on the
-//     FIRST re-export. The HTML re-parser hoists the block <img> out of its
-//     line and leaves an empty paragraph behind, so `paragraph` + `![..](..)`
-//     re-imports as paragraph + empty-paragraph + image; the empty paragraph
-//     adds one blank line, so export #2 grows by a one-time "\n\n" (md1 !== md2).
-//     This is NOT non-convergence: the growth happens exactly ONCE. The doc
-//     CONVERGES to a fixpoint after one extra `export→import→export` pass — the
-//     empty paragraph is already present after the first import, so export #2
-//     and export #3 are byte-identical (md2 === md3, verified).
-//
-//   * drawio / excalidraw diagrams gain `data-align="center"` on the second
-//     export: the schema's diagram `align` attribute has a NON-null default of
-//     "center", which materializes on import; the converter only emits
-//     data-align when set, so it appears on export #2 but not #1. Like the
-//     image case, this is one-time and converges after one extra pass.
-//
-//   * A STANDALONE block image (no preceding paragraph) IS byte-stable from
-//     export #1 (md1 === md2) — but it is still NOT canonically stable: on
-//     import the bare <img> is wrapped, gaining a leading EMPTY paragraph, so
-//     the canonical doc differs by that spurious paragraph node even though the
-//     markdown bytes match.
-//
-// Resolution (SPEC §11, "normalize-on-write"): rather than deep-fixing the
-// converter, the engine runs ONE `export→import→export` pass when writing into
-// the vault; from that fixpoint onward the form is byte-stable, so git sees no
-// phantom diff. The green corpus above avoids these one-time asymmetries by
-// pre-authoring the materialized defaults (e.g. `align: "center"` on the
-// diagrams in 06-diagrams.json) so a single pass is already at the fixpoint.
+// #293 canon #8 removes that divergence. The diagram family now serializes at
+// TOP LEVEL as `![](src)<!--drawio|excalidraw {…}-->`, and — exactly like the
+// image `![](src)` form — a default `align:"center"` is OMITTED from the comment
+// JSON (it re-materializes as the schema default on import, then is omitted again
+// on re-export). The block-image hoist that once left a phantom empty paragraph
+// is already absorbed by `stripEmptyParagraphs`. The fixture is therefore now
+// BOTH byte-stable AND canonically stable, so it lives in fixtures/corpus as
+// `11-image-diagrams.json` and is exercised by the green corpus loop above.
 // ---------------------------------------------------------------------------
-describe('round-trip KNOWN LIMITATIONS (SPEC §11 image/diagram risk)', () => {
-  it.fails(
-    'image-diagrams.json is NOT byte-stable on export #1 (block image hoist + diagram align default; converges after one extra pass — SPEC §11 normalize-on-write)',
-    async () => {
-      const doc = JSON.parse(
-        await readFile(join(KNOWN_LIMITATIONS_DIR, 'image-diagrams.json'), 'utf8'),
-      );
-      const { md1, md2 } = await roundTrip(doc);
-      // This assertion FAILS today (documented divergence). `it.fails` turns a
-      // failing body into a PASS; if the converter is fixed this flips and the
-      // test goes red, prompting promotion into the green corpus.
-      expect(md2).toBe(md1);
-    },
-  );
-});
-- 
2.52.0


From 77f5224b552549a5eda56bd144e9e7f407748eff Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 09:12:18 +0300
Subject: [PATCH 07/17] feat(prosemirror-markdown): highlight without color as
 ==text== (#293 canon #7)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `highlight` mark WITHOUT a color now serializes as the Obsidian/GFM `==text==`
syntax (closing hand-authoring gap A19); a highlight WITH a color keeps the
`<mark style="background-color: …">` HTML form (condition is deterministic on
the color attr). On the raw-HTML path (columns/spanned cells) BOTH forms stay
`<mark>` via inlineToHtml — markdown is not re-parsed inside a raw-HTML block.

Parse: `==` is not standard markdown, so the importer uses a DEDICATED marked
instance (`new Marked().use({extensions:[highlightMark]})`) rather than the
global singleton — registered once, never leaks `==` behavior to other callers.
The inline extension tokenizes `==text==` (non-empty, non-space-leading inner,
lazy so `==a== ==b==` is two marks; inner re-tokenized so nested marks survive;
`====`/`==x` fail-open to literal) into `<mark>` with no color, which the schema
parses as a color-less highlight. Inline code (`` `a == b` ``) stays code via
marked token precedence. marked 17 defaults (gfm:true, breaks:false) are
identical for the fresh instance, so tables/strike/autolinks are unaffected.

Losslessness: a LITERAL `==` in a text run would otherwise be misparsed as a
highlight on the next import, so `case "text"` backslash-escapes each `=` of a
`==` pair (marked decodes `\=` back to `=`), and this round-trips byte-stably.
The escape does NOT run for inline-code runs, and — CRITICALLY — codeBlock now
reads its child text RAW (schema `content: "text*"`) instead of routing through
`case "text"`: marked does not decode `\=` inside a fence, so escaping there
would permanently stamp backslashes into any `==` comparison (ubiquitous in
source code) and corrupt the block on the git-sync data path.

Tests: new highlight.test.ts (19 cases incl. serialize forms, colored vs plain,
column `<mark>` path, nested marks, inline-code exclusion, literal-`==` escape,
fail-open, AND a codeBlock-with-`==` regression proving no backslash corruption
+ byte-stable round-trip). Golden inline-mark matrix flipped top-level no-color
highlight to `==m==`; the kept `<mark style=…>` assertions are the colored/
raw-HTML cases.

package vitest: 559 passed; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/markdown-converter.ts             |  40 ++-
 .../src/lib/markdown-to-prosemirror.ts        |  70 ++++-
 .../test/highlight.test.ts                    | 249 ++++++++++++++++++
 .../test/markdown-converter-golden.test.ts    |   4 +-
 4 files changed, 352 insertions(+), 11 deletions(-)
 create mode 100644 packages/prosemirror-markdown/test/highlight.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 17ab21db..8c35440c 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -213,6 +213,20 @@ export function convertProseMirrorToMarkdown(content: any): string {
 
       case "text":
         let textContent = node.text || "";
+        // #293 canon #7: `==` is now a LIVE inline highlight syntax on import (a
+        // marked inline extension turns `==text==` into a color-less highlight
+        // mark). A LITERAL `==` in a text run would therefore be misparsed as a
+        // highlight on the next import, so backslash-escape each `=` of a `==`
+        // pair; marked's escape tokenizer decodes `\=` back to a literal `=`, so
+        // a literal `==` round-trips as text (never materializes a phantom mark).
+        // This runs for BOTH unmarked text and marked non-code runs, but NOT for
+        // an inline code span (a run carrying the `code` mark returns a backtick
+        // span below with `==` verbatim, matching `` `a == b` `` staying code).
+        // A highlight run's own `==` delimiters are appended AFTER this in the
+        // marks loop, so they are never escaped; only the run's inner text is.
+        if (!(node.marks || []).some((m: any) => m.type === "code")) {
+          textContent = textContent.replace(/==/g, "\\=\\=");
+        }
         // Apply marks (bold, italic, code, etc.)
         if (node.marks) {
           // The schema's `code` mark declares `excludes: "_"` — it excludes every
@@ -286,14 +300,19 @@ export function convertProseMirrorToMarkdown(content: any): string {
                 textContent = `<sup>${textContent}</sup>`;
                 break;
               case "highlight": {
-                // Preserve a null/empty color as a plain highlight (a bare
-                // <mark> with no background-color); only emit the style when a
-                // color is actually set, so a plain highlight is not forced to
-                // yellow on export.
+                // #293 canon #7: a highlight WITHOUT a color serializes as the
+                // Obsidian/GFM `==text==` syntax (the importer's marked inline
+                // `==` extension parses it back to a color-less highlight mark).
+                // A highlight WITH a color keeps the `<mark style="background-
+                // color: …">` HTML form (the condition is deterministic on the
+                // `color` attr), so a colored highlight is not flattened. The
+                // inner textContent already had any literal `==` backslash-
+                // escaped above, so a highlight over text containing `==` still
+                // round-trips.
                 const color = mark.attrs?.color;
                 textContent = color
                   ? `<mark style="background-color: ${escapeAttr(color)}">${textContent}</mark>`
-                  : `<mark>${textContent}</mark>`;
+                  : `==${textContent}==`;
                 break;
               }
               case "textStyle":
@@ -332,8 +351,17 @@ export function convertProseMirrorToMarkdown(content: any): string {
         // re-adds exactly one trailing "\n" on import, so trimming only one
         // here would let the text grow by "\n" on each round-trip. Removing
         // every trailing newline makes repeated cycles stable.
+        //
+        // Read the child text RAW (schema codeBlock is `content: "text*"`), NOT
+        // through processNode: code-fence content is literal and markdown escapes
+        // do not apply inside a fence. In particular the canon #7 `==` -> `\=\=`
+        // escape (in `case "text"`) must NOT reach code — marked leaves `\=`
+        // verbatim inside a fence, so routing code through `case "text"` would
+        // permanently stamp backslashes into any `==` (a `==` comparison is
+        // extremely common in source), corrupting the block on the git-sync data
+        // path.
         const code = nodeContent
-          .map(processNode)
+          .map((child: any) => (typeof child?.text === "string" ? child.text : ""))
           .join("")
           .replace(/\n+$/, "");
         // CommonMark: an inner ``` run inside the code would prematurely close
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index 03034cdf..1c5af619 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -9,7 +9,8 @@
  */
 import { generateJSON } from "@tiptap/html";
 import { JSDOM } from "jsdom";
-import { marked } from "marked";
+import { Marked } from "marked";
+import type { TokenizerExtension, RendererExtension } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
 import { parseAttachedComment } from "./attached-comment.js";
 import {
@@ -24,6 +25,67 @@ import {
   youtubeToHtml,
 } from "./media-html.js";
 
+/**
+ * #293 canon #7: `==text==` (Obsidian/GFM highlight) inline syntax.
+ *
+ * `==` is NOT standard markdown, so we teach the parser to turn `==text==` into
+ * `<mark>text</mark>`, which the schema's Highlight extension parses back into a
+ * color-less `highlight` mark (see docmost-schema.ts). This mirrors the
+ * serializer's no-color highlight form, so a plain highlight round-trips.
+ *
+ * This is an INLINE extension (mid-line, must respect token precedence so it
+ * never fires inside an inline code span). The tokenizer requires a non-empty,
+ * non-space-leading inner and re-tokenizes that inner via `this.lexer.inline-
+ * Tokens`, so nested marks (bold/italic/links inside a highlight) round-trip.
+ * The renderer re-parses the inner tokens and wraps them in `<mark>`.
+ *
+ * It is registered on a DEDICATED `Marked` instance owned by this module
+ * (below), NOT the global `marked` singleton, so the `==` behavior cannot leak
+ * into unrelated callers that import `marked` elsewhere in the monorepo.
+ */
+interface HighlightMarkToken {
+  type: "highlightMark";
+  raw: string;
+  text: string;
+  tokens: any[];
+}
+
+const highlightMarkExtension: TokenizerExtension & RendererExtension = {
+  name: "highlightMark",
+  level: "inline",
+  // Point marked at the next `==` so the tokenizer is invoked at that offset.
+  start(src: string) {
+    const i = src.indexOf("==");
+    return i < 0 ? undefined : i;
+  },
+  tokenizer(src: string) {
+    // Require a non-empty, non-space-leading inner and a closing `==`. The lazy
+    // `+?` matches the SHORTEST inner, so `==a== ==b==` yields two marks. `====`
+    // (empty) and `==x` (unbalanced) do not match and stay literal text.
+    const match = /^==(?=\S)([\s\S]+?)==/.exec(src);
+    if (!match) return undefined;
+    const token: HighlightMarkToken = {
+      type: "highlightMark",
+      raw: match[0],
+      text: match[1],
+      tokens: [],
+    };
+    // Re-tokenize the inner so marks nested inside the highlight round-trip.
+    token.tokens = this.lexer.inlineTokens(match[1]);
+    return token as any;
+  },
+  renderer(token: any) {
+    return `<mark>${this.parser.parseInline(token.tokens)}</mark>`;
+  },
+};
+
+// Dedicated marked instance: default (GFM) options plus the `==` highlight
+// inline extension. Constructed once at module load so the extension is
+// registered exactly once and never mutates the global `marked` singleton.
+const markedInstance = new Marked().use({
+  extensions: [highlightMarkExtension],
+});
+
 // Setup DOM environment for Tiptap HTML parsing in Node.js
 const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
 global.window = dom.window as any;
@@ -162,7 +224,7 @@ async function preprocessCallouts(markdown: string): Promise<string> {
           // Found the matching closing fence: render the body (recursively, so
           // nested callouts are handled) and emit the callout div.
           const inner = await transform(bodyLines);
-          const renderedInner = await marked.parse(inner);
+          const renderedInner = await markedInstance.parse(inner);
           out.push(
             `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
           );
@@ -191,7 +253,7 @@ async function preprocessCallouts(markdown: string): Promise<string> {
           bodyLines.push(lines[j].replace(/^>\s?/, ""));
         }
         const inner = await transform(bodyLines);
-        const renderedInner = await marked.parse(inner);
+        const renderedInner = await markedInstance.parse(inner);
         out.push(
           `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
         );
@@ -649,7 +711,7 @@ export async function markdownToProseMirror(
   markdownContent: string,
 ): Promise<any> {
   const withCallouts = await preprocessCallouts(markdownContent);
-  const html = await marked.parse(withCallouts);
+  const html = await markedInstance.parse(withCallouts);
   // Materialize comment directives (#293 #9 attached textAlign; #5 standalone
   // subpages/pageBreak) while the comment nodes still exist, before generateJSON
   // drops them.
diff --git a/packages/prosemirror-markdown/test/highlight.test.ts b/packages/prosemirror-markdown/test/highlight.test.ts
new file mode 100644
index 00000000..012fcddc
--- /dev/null
+++ b/packages/prosemirror-markdown/test/highlight.test.ts
@@ -0,0 +1,249 @@
+import { describe, expect, it } from 'vitest';
+// Import both directions DIRECTLY from src (NOT the docmost-client barrel, which
+// pulls in collaboration.ts and mutates the global DOM at import time), matching
+// the other converter unit tests.
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+// #293 canon #7: a `highlight` mark WITHOUT a color serializes as the
+// Obsidian/GFM `==text==` syntax; a highlight WITH a color KEEPS the
+// `<mark style="background-color: …">` HTML form. On the raw-HTML path
+// (columns / spanned cells) BOTH forms stay `<mark>` because markdown is not
+// re-parsed there. This file locks the serialize form, the round-trip, and the
+// literal-`==` escape that keeps a literal `==` from becoming a phantom mark.
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// Find the first text node anywhere in a PM tree that carries a mark of `type`.
+const firstMarkedText = (node: any, type: string): any => {
+  if (node?.type === 'text' && (node.marks || []).some((m: any) => m.type === type)) {
+    return node;
+  }
+  for (const child of node?.content || []) {
+    const hit = firstMarkedText(child, type);
+    if (hit) return hit;
+  }
+  return null;
+};
+const mark = (textNode: any, type: string): any =>
+  (textNode?.marks || []).find((m: any) => m.type === type);
+// Concatenate all text within a subtree (order-preserving).
+const allText = (node: any): string => {
+  if (node?.type === 'text') return node.text || '';
+  return (node?.content || []).map(allText).join('');
+};
+// Does ANY text node in the tree carry a mark of `type`?
+const hasMark = (node: any, type: string): boolean => !!firstMarkedText(node, type);
+
+// PM -> MD -> PM round-trip.
+const roundTrip = async (d: any) => {
+  const md1 = convertProseMirrorToMarkdown(d);
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, doc2, md2 };
+};
+
+describe('#293 #7: no-color highlight <-> ==text==', () => {
+  it('serializes a no-color highlight as exactly ==text==', () => {
+    expect(convertProseMirrorToMarkdown(doc(para(text('important', [{ type: 'highlight' }]))))).toBe(
+      '==important==',
+    );
+  });
+
+  it('imports ==text== as a highlight mark with NO color', async () => {
+    const d = await markdownToProseMirror('==important==');
+    const t = firstMarkedText(d, 'highlight');
+    expect(t).toBeTruthy();
+    expect(t.text).toBe('important');
+    // A bare <mark> carries no background-color, so the color attr is null.
+    expect(mark(t, 'highlight').attrs?.color ?? null).toBeNull();
+  });
+
+  it('is byte-stable and re-imports as a color-less highlight', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      doc(para(text('a base '), text('hl', [{ type: 'highlight' }]), text(' tail'))),
+    );
+    expect(md1).toBe('a base ==hl== tail');
+    expect(md2).toBe(md1);
+    const t = firstMarkedText(doc2, 'highlight');
+    expect(t.text).toBe('hl');
+    expect(mark(t, 'highlight').attrs?.color ?? null).toBeNull();
+  });
+});
+
+describe('#293 #7: colored highlight keeps <mark style=…>', () => {
+  it('serializes a colored highlight as the <mark style=…> HTML form (NOT ==)', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(para(text('c', [{ type: 'highlight', attrs: { color: '#ff0000' } }]))),
+    );
+    expect(out).toBe('<mark style="background-color: #ff0000">c</mark>');
+    expect(out).not.toContain('==');
+  });
+
+  it('round-trips a colored highlight preserving its color', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      doc(para(text('c', [{ type: 'highlight', attrs: { color: '#abcdef' } }]))),
+    );
+    expect(md1).toBe('<mark style="background-color: #abcdef">c</mark>');
+    expect(md2).toBe(md1);
+    const t = firstMarkedText(doc2, 'highlight');
+    expect(mark(t, 'highlight').attrs?.color).toBe('#abcdef');
+  });
+});
+
+describe('#293 #7: raw-HTML path (columns) stays <mark>, never ==', () => {
+  const oneColumn = (...blocks: any[]) => ({
+    type: 'columns',
+    attrs: { layout: 'two' },
+    content: [{ type: 'column', content: blocks }],
+  });
+
+  it('a no-color highlight inside a column serializes as <mark> (inlineToHtml), not ==', () => {
+    const out = convertProseMirrorToMarkdown(doc(oneColumn(para(text('p', [{ type: 'highlight' }])))));
+    expect(out).toContain('<mark>p</mark>');
+    // The `==` markdown syntax must NOT leak into a raw-HTML container (it would
+    // survive as literal text there because columns are not re-parsed).
+    expect(out).not.toContain('==');
+  });
+
+  it('a colored highlight inside a column keeps <mark style=…>', () => {
+    const out = convertProseMirrorToMarkdown(
+      doc(oneColumn(para(text('p', [{ type: 'highlight', attrs: { color: '#00ff00' } }])))),
+    );
+    expect(out).toContain('<mark style="background-color: #00ff00">p</mark>');
+  });
+
+  it('round-trips a highlight inside a column (byte-stable, mark preserved)', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      doc(oneColumn(para(text('p', [{ type: 'highlight' }])))),
+    );
+    expect(md1).toContain('<mark>p</mark>');
+    expect(md2).toBe(md1);
+    expect(hasMark(doc2, 'highlight')).toBe(true);
+  });
+});
+
+describe('#293 #7: highlight wrapping other marks', () => {
+  it('serializes bold-inside-highlight as ==**x**== and round-trips both marks', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      doc(para(text('x', [{ type: 'bold' }, { type: 'highlight' }]))),
+    );
+    expect(md1).toBe('==**x**==');
+    expect(md2).toBe(md1);
+    const t = firstMarkedText(doc2, 'highlight');
+    expect(t).toBeTruthy();
+    expect((t.marks || []).some((m: any) => m.type === 'bold')).toBe(true);
+    expect(t.text).toBe('x');
+  });
+});
+
+describe('#293 #7: inline code containing == stays code, not a highlight', () => {
+  it('imports `a == b` as an inline code span, not a highlight', async () => {
+    const d = await markdownToProseMirror('`a == b`');
+    expect(hasMark(d, 'highlight')).toBe(false);
+    const codeText = firstMarkedText(d, 'code');
+    expect(codeText).toBeTruthy();
+    expect(codeText.text).toBe('a == b');
+  });
+
+  it('round-trips an inline code span carrying == (byte-stable, no highlight)', async () => {
+    const { md1, md2, doc2 } = await roundTrip(doc(para(text('a == b', [{ type: 'code' }]))));
+    expect(md1).toBe('`a == b`');
+    expect(md2).toBe(md1);
+    expect(hasMark(doc2, 'highlight')).toBe(false);
+    expect(firstMarkedText(doc2, 'code').text).toBe('a == b');
+  });
+});
+
+describe('#293 #7: literal == in plain prose round-trips as text (no phantom highlight)', () => {
+  it('a lone literal == (a == b) is escaped and re-imports as literal text', async () => {
+    const { md1, md2, doc2 } = await roundTrip(doc(para(text('a == b'))));
+    // Each `=` of the pair is backslash-escaped so marked decodes it back.
+    expect(md1).toBe('a \\=\\= b');
+    expect(md2).toBe(md1);
+    expect(hasMark(doc2, 'highlight')).toBe(false);
+    expect(allText(doc2)).toBe('a == b');
+  });
+
+  it('a literal ==...== pair in prose does NOT materialize a highlight', async () => {
+    const { md1, md2, doc2 } = await roundTrip(doc(para(text('x ==not hl== y'))));
+    expect(md1).toBe('x \\=\\=not hl\\=\\= y');
+    expect(md2).toBe(md1);
+    expect(hasMark(doc2, 'highlight')).toBe(false);
+    expect(allText(doc2)).toBe('x ==not hl== y');
+  });
+
+  it('a highlight over text that itself contains a literal == round-trips both', async () => {
+    const { md1, md2, doc2 } = await roundTrip(
+      doc(para(text('a == b', [{ type: 'highlight' }]))),
+    );
+    // The inner literal `==` is escaped; the highlight `==` delimiters are added
+    // AFTER escaping, so the mark's own delimiters are intact.
+    expect(md1).toBe('==a \\=\\= b==');
+    expect(md2).toBe(md1);
+    const t = firstMarkedText(doc2, 'highlight');
+    expect(t.text).toBe('a == b');
+  });
+});
+
+describe('#293 #7: fail-open edges (empty / unbalanced ==)', () => {
+  it('empty ==== does not crash and stays literal (no highlight)', async () => {
+    const d = await markdownToProseMirror('====');
+    expect(hasMark(d, 'highlight')).toBe(false);
+    expect(allText(d)).toBe('====');
+  });
+
+  it('unbalanced ==x does not crash and stays literal (no highlight)', async () => {
+    const d = await markdownToProseMirror('==x');
+    expect(hasMark(d, 'highlight')).toBe(false);
+    expect(allText(d)).toBe('==x');
+  });
+
+  it('two highlights on one line both parse (lazy inner)', async () => {
+    const d = await markdownToProseMirror('==a== ==b==');
+    const first = firstMarkedText(d, 'highlight');
+    expect(first.text).toBe('a');
+    // Both highlighted runs are present.
+    expect(allText(d)).toContain('a');
+    expect(allText(d)).toContain('b');
+  });
+});
+
+describe('#293 #7: a codeBlock containing == is NOT escaped (literal code preserved)', () => {
+  // Regression: the canon #7 `==` -> `\=\=` escape lives in `case "text"`, but
+  // code-fence content is literal and marked does NOT decode `\=` inside a fence,
+  // so routing code through that path would permanently stamp backslashes into a
+  // `==` comparison (ubiquitous in source). codeBlock must read raw child text.
+  const codeBlock = (t: string, language = '') => ({
+    type: 'codeBlock',
+    attrs: { language },
+    content: [{ type: 'text', text: t }],
+  });
+
+  it('exports `==` in code verbatim (no \\=\\=) and round-trips byte-stably', async () => {
+    const d = doc(codeBlock('if (a == b) return c == d;', 'js'));
+    const md1 = convertProseMirrorToMarkdown(d);
+    expect(md1).toBe('```js\nif (a == b) return c == d;\n```');
+    expect(md1).not.toContain('\\='); // no backslash corruption
+    const back = await markdownToProseMirror(md1);
+    // The code text survives with no backslash corruption and no phantom
+    // highlight (marked re-adds a trailing "\n" to fence content on import,
+    // which the serializer strips again — hence trimEnd here; byte-stability of
+    // the markdown is asserted separately below).
+    expect(allText(back).trimEnd()).toBe('if (a == b) return c == d;');
+    expect(allText(back)).not.toContain('\\=');
+    expect(hasMark(back, 'highlight')).toBe(false);
+    expect(convertProseMirrorToMarkdown(back)).toBe(md1); // byte-stable
+  });
+
+  it('a real markdown code block with == imports clean and re-exports clean', async () => {
+    const src = '```\nx == y\n```';
+    const back = await markdownToProseMirror(src);
+    expect(allText(back).trimEnd()).toBe('x == y');
+    expect(allText(back)).not.toContain('\\=');
+    expect(convertProseMirrorToMarkdown(back)).toBe(src); // byte-stable
+  });
+});
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
index 69c3cd8b..adc4a7a5 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -103,7 +103,9 @@ describe('inline-mark matrix (underline/sub/sup/highlight±color/textStyle/comme
       [[{ type: 'underline' }], '<u>m</u>'],
       [[{ type: 'subscript' }], '<sub>m</sub>'],
       [[{ type: 'superscript' }], '<sup>m</sup>'],
-      [[{ type: 'highlight' }], '<mark>m</mark>'],
+      // #293 canon #7: a no-color highlight now serializes as `==m==` (Obsidian
+      // syntax); only a COLORED highlight keeps the `<mark style=…>` HTML form.
+      [[{ type: 'highlight' }], '==m=='],
       [
         [{ type: 'highlight', attrs: { color: '#ff0000' } }],
         '<mark style="background-color: #ff0000">m</mark>',
-- 
2.52.0


From bfbd92786652048140ee8dc8699426cf95149d27 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 09:37:37 +0300
Subject: [PATCH 08/17] =?UTF-8?q?feat(prosemirror-markdown):=20math=20as?=
 =?UTF-8?q?=20$=E2=80=A6$=20/=20$$=E2=80=A6$$=20(#293=20canon=20#6)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mathInline serializes as `$LaTeX$` and mathBlock as an own-line `$$\n<latex>\n$$`
fence (multi-line safe), closing hand-authoring gap A18. The LaTeX still lives in
node.attrs.text; a literal `$` inside it is escaped `\$`. On the raw-HTML path
(columns/cells) math keeps the schema-HTML `<span data-type="mathInline">` /
`<div data-type="mathBlock">` form (markdown is not re-parsed inside raw HTML) —
blockToHtml gets an explicit mathBlock case and inlineToHtml a mathInline case,
sharing the mathInlineHtml/mathBlockHtml helpers with the fallbacks so the two
forms cannot drift.

Parse: mathInlineExtension (inline) + mathBlockExtension (block) are added to the
SAME dedicated marked instance introduced for canon #7 (global singleton
untouched). The inline extension uses a currency-safe PANDOC rule: an opening `$`
must not be followed by whitespace, and the closing `$` must not be preceded by
whitespace nor followed by a digit — so `$5`, `$5 and $10`, `a $5 b $6 c`, `100$`
stay literal text while `$x^2$` is math. The block extension matches a `$$` fence
line and captures multi-line LaTeX non-greedily up to the next `$$` line.

The pandoc boundary rule lives ONCE in the new math-inline.ts
(INLINE_MATH_SOURCE) and is shared by the import tokenizer (^-anchored) and the
export prose escaper (global), so parse and serialize cannot disagree about what
is math. escapeProseMath (case "text", non-code runs only) escapes ONLY the two
delimiting `$` of a span the rule WOULD match, so a would-be-math prose span like
`the set $A$` re-imports as literal text while currency `$5 and $10` is emitted
CLEAN (zero backslash churn). marked decodes `\$`→`$` on re-parse, byte-stable.

Fallbacks to the lossless schema-HTML form (all documented + tested):
mathInline → <span> when empty / whitespace-edged / multi-line / pre-existing
`\$` / trailing `\` / immediately before a digit-text sibling (renderInlineChildren
guard, so `$…$5` can't lose the node); mathBlock → <div> when the LaTeX contains
`$$`. Each fallback round-trips losslessly and byte-stably.

Code safety (guards the canon #7 regression class): codeBlock reads raw child
text and inline `code` runs are excluded from escapeProseMath, so `$5`/`$x$` in
code stay literal with no math and no backslash corruption. ReDoS-checked on
adversarial 40k-char inputs (0–1 ms).

Tests: new math.test.ts (26 cases: serialize exactness, multi-line block, `\$`
escaping, currency ×5 asserting no `\$`, prose escape, columns schema-HTML,
inline-code/codeBlock safety, fail-open). Goldens in roundtrip / markdown-converter
flipped top-level math to `$…$`/`$$…$$`; the escapeAttr-idempotence golden wraps
math in a column (still exercises escapeAttr); columns/raw-HTML math assertions
unchanged.

package vitest: 585 passed; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/markdown-converter.ts             | 111 ++++++--
 .../src/lib/markdown-to-prosemirror.ts        |  76 ++++-
 .../src/lib/math-inline.ts                    |  78 ++++++
 .../test/markdown-converter-golden.test.ts    |  15 +-
 .../test/markdown-converter.test.ts           |  23 +-
 .../prosemirror-markdown/test/math.test.ts    | 262 ++++++++++++++++++
 .../test/roundtrip.test.ts                    |  11 +-
 7 files changed, 534 insertions(+), 42 deletions(-)
 create mode 100644 packages/prosemirror-markdown/src/lib/math-inline.ts
 create mode 100644 packages/prosemirror-markdown/test/math.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 8c35440c..0011801d 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -3,6 +3,11 @@ import {
   attachedCommentFor,
   standaloneCommentFor,
 } from "./attached-comment.js";
+import {
+  encodeInlineMathLatex,
+  inlineMathGlobalRe,
+  inlineMathSerializable,
+} from "./math-inline.js";
 import {
   attachmentToHtml,
   audioToHtml,
@@ -91,6 +96,27 @@ export function convertProseMirrorToMarkdown(content: any): string {
   const escapeLinkText = (value: unknown): string =>
     String(value ?? "").replace(/[\\`*_~[\]<&!()]/g, (c: string) => `\\${c}`);
 
+  // #293 canon #6: the schema-HTML forms for math. These are the LOSSLESS forms
+  // the raw-HTML path (columns/cells) and the mathInline fallback emit, and the
+  // SAME shape the importer's schema parseHTML rebuilds (span/div carrying the
+  // LaTeX in a `text="…"` attribute). Kept as small helpers so the readable
+  // `$…$`/`$$…$$` markdown forms and the raw-HTML forms cannot drift apart.
+  const mathInlineHtml = (latex: string): string =>
+    `<span data-type="mathInline" data-katex="true" text="${escapeAttr(latex)}"></span>`;
+  const mathBlockHtml = (latex: string): string =>
+    `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(latex)}"></div>`;
+
+  // #293 canon #6: neutralize a would-be inline-math `$…$` span sitting in PROSE
+  // text so it re-imports as literal text (never a phantom math node). We escape
+  // ONLY the two delimiting `$` of a span the inline-math tokenizer WOULD match
+  // (shared rule, math-inline.ts), leaving the inner untouched. A currency `$`
+  // (`$5`, `$5 and $10`) has no VALID closing under the rule, so it never
+  // matches and is emitted CLEAN (no backslash churn). On re-import marked's
+  // escape tokenizer turns each `\$` back into a literal `$`, so `the set $A$`
+  // round-trips as text while `$5 and $10` stays exactly as written.
+  const escapeProseMath = (value: string): string =>
+    value.replace(inlineMathGlobalRe(), (_m, inner) => `\\$${inner}\\$`);
+
   // Recursion depth guard. processNode is mutually recursive (directly and via
   // processListItem/processTaskItem/blockToHtml), and a pathologically nested
   // document (e.g. tens of thousands of nested blockquotes) would otherwise
@@ -172,7 +198,7 @@ export function convertProseMirrorToMarkdown(content: any): string {
         return nodeContent.map(processNode).join("\n\n");
 
       case "paragraph": {
-        const text = nodeContent.map(processNode).join("");
+        const text = renderInlineChildren(nodeContent);
         const align = node.attrs?.textAlign;
         // Non-default alignment round-trips as an ATTACHED HTML comment at the
         // END of the block line (#293 canon #9):
@@ -192,7 +218,7 @@ export function convertProseMirrorToMarkdown(content: any): string {
 
       case "heading": {
         const level = node.attrs?.level || 1;
-        const headingText = nodeContent.map(processNode).join("");
+        const headingText = renderInlineChildren(nodeContent);
         const headingLine = "#".repeat(level) + " " + headingText;
         const headingAlign = node.attrs?.textAlign;
         // A non-default heading alignment attaches the same trailing comment
@@ -226,6 +252,12 @@ export function convertProseMirrorToMarkdown(content: any): string {
         // marks loop, so they are never escaped; only the run's inner text is.
         if (!(node.marks || []).some((m: any) => m.type === "code")) {
           textContent = textContent.replace(/==/g, "\\=\\=");
+          // #293 canon #6: escape a would-be inline-math `$…$` span so it stays
+          // literal text on re-import (currency `$5` is left clean — see
+          // escapeProseMath). Runs on the SAME non-code runs as the `==` escape
+          // above; an inline `code` run returns verbatim below, matching the
+          // codeBlock path (a `$…$` inside code must stay code, never math).
+          textContent = escapeProseMath(textContent);
         }
         // Apply marks (bold, italic, code, etc.)
         if (node.marks) {
@@ -598,26 +630,39 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       case "detailsSummary":
-        return `<summary>${nodeContent.map(processNode).join("")}</summary>\n\n`;
+        return `<summary>${renderInlineChildren(nodeContent)}</summary>\n\n`;
 
       case "detailsContent":
         return `${nodeContent.map(processNode).join("\n")}\n`;
 
       case "mathInline": {
-        // The schema's `text` attribute has no parseHTML, so TipTap's default
-        // parser reads it from the `text` HTML attribute (NOT the element's text
-        // content). Emit span[data-type="mathInline"] carrying the LaTeX in a
-        // `text="..."` attribute so it round-trips. marked cannot parse $...$
-        // back, so the previous form was lossy.
+        // #293 canon #6: inline math serializes as Obsidian-native `$LaTeX$`
+        // (readable, re-parsed by the importer's marked inline extension). A
+        // literal `$` inside the LaTeX is escaped `\$` so it cannot close the
+        // span early (the importer decodes `\$`→`$`). When the LaTeX cannot be
+        // safely fenced (empty, whitespace-edged, multi-line, or an ambiguous
+        // backslash-before-`$`), fall back to the LOSSLESS schema-HTML `<span>`
+        // form (inlineMathSerializable). A following-sibling digit — which would
+        // also break the pandoc closing rule — is handled by renderInlineChildren
+        // (this case cannot see siblings).
         const inlineMath = node.attrs?.text || "";
-        return `<span data-type="mathInline" data-katex="true" text="${escapeAttr(inlineMath)}"></span>`;
+        if (!inlineMathSerializable(inlineMath)) {
+          return mathInlineHtml(inlineMath);
+        }
+        return `$${encodeInlineMathLatex(inlineMath)}$`;
       }
 
       case "mathBlock": {
-        // Same as mathInline: the LaTeX must ride in the `text` HTML attribute
-        // for the schema's default parser to recover it.
+        // #293 canon #6: block math serializes as a `$$` fence on its own lines
+        // (`$$\n<latex>\n$$`), so multi-line LaTeX is preserved. If the LaTeX
+        // itself contains a `$$` (which would close the fence early — essentially
+        // never valid inside a single math node), fall back to the lossless
+        // schema-HTML `<div>` form.
         const blockMath = node.attrs?.text || "";
-        return `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(blockMath)}"></div>`;
+        if (blockMath.includes("$$")) {
+          return mathBlockHtml(blockMath);
+        }
+        return `$$\n${blockMath}\n$$`;
       }
 
       case "mention": {
@@ -871,6 +916,28 @@ export function convertProseMirrorToMarkdown(content: any): string {
     }
   };
 
+  // Render a run of inline children to MARKDOWN, with the #293 canon #6
+  // inline-math guard. A `mathInline` serialized as `$…$` whose FOLLOWING
+  // sibling renders starting with a DIGIT would put a digit right after the
+  // closing `$`, which the pandoc inline rule refuses to parse as math (the
+  // currency guard) — so the node would re-import as literal text (data loss).
+  // For that node ONLY we fall back to the lossless schema-HTML `<span>` form.
+  // Every other inline node is rendered exactly as processNode would, so output
+  // is unchanged whenever no math sits directly before a digit.
+  const renderInlineChildren = (nodes: any[]): string => {
+    const parts = nodes.map(processNode);
+    for (let i = 0; i < nodes.length - 1; i++) {
+      if (
+        nodes[i]?.type === "mathInline" &&
+        parts[i].startsWith("$") &&
+        /^[0-9]/.test(parts[i + 1] || "")
+      ) {
+        parts[i] = mathInlineHtml(nodes[i].attrs?.text || "");
+      }
+    }
+    return parts.join("");
+  };
+
   // Render inline content (text runs + their marks) to HTML. Used by the raw
   // HTML fallbacks (spanned tables, columns) where marked will NOT re-parse
   // markdown, so backtick/asterisk/bracket syntax would otherwise leak as
@@ -880,8 +947,13 @@ export function convertProseMirrorToMarkdown(content: any): string {
     (inlineNodes || [])
       .map((n: any) => {
         if (n.type === "hardBreak") return "<br>";
+        // #293 canon #6: on the raw-HTML path (columns/spanned cells) marked does
+        // NOT re-parse markdown, so inline math MUST stay the schema-HTML `<span>`
+        // form here — a `$…$` fence would land as literal text on re-import.
+        if (n.type === "mathInline") return mathInlineHtml(n.attrs?.text || "");
         if (n.type !== "text") {
-          // Inline atoms (mention, mathInline) already emit schema HTML.
+          // Other inline atoms (mention, status, footnoteRef) already emit
+          // schema HTML from processNode.
           return processNode(n);
         }
         let t = escapeHtmlText(n.text || "");
@@ -1125,11 +1197,18 @@ export function convertProseMirrorToMarkdown(content: any): string {
         return pageEmbedToHtml(block.attrs || {});
       case "transclusionReference":
         return transclusionReferenceToHtml(block.attrs || {});
-      // columns/column, math, htmlEmbed, footnotes, transclusionSource already
-      // emit schema-matching HTML from processNode.
+      // #293 canon #6: on the TOP-LEVEL path (processNode) mathBlock now
+      // serializes as a `$$…$$` fence, but marked does NOT re-parse markdown
+      // inside a raw-HTML block, so inside a column/cell it MUST stay the
+      // schema-HTML `<div>` form or it would land as literal `$$…$$` text on
+      // re-import. Give it an EXPLICIT case here (the same form the importer
+      // rebuilds) instead of delegating to processNode's fence form.
+      case "mathBlock":
+        return mathBlockHtml(block.attrs?.text || "");
+      // columns/column, htmlEmbed, footnotes, transclusionSource already emit
+      // schema-matching HTML from processNode.
       case "columns":
       case "column":
-      case "mathBlock":
       case "htmlEmbed":
       case "footnotesList":
       case "footnoteDefinition":
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index 1c5af619..d9a80b46 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -13,6 +13,11 @@ import { Marked } from "marked";
 import type { TokenizerExtension, RendererExtension } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
 import { parseAttachedComment } from "./attached-comment.js";
+import {
+  decodeInlineMathLatex,
+  escapeMathAttr,
+  inlineMathAnchoredRe,
+} from "./math-inline.js";
 import {
   attachmentToHtml,
   audioToHtml,
@@ -79,11 +84,76 @@ const highlightMarkExtension: TokenizerExtension & RendererExtension = {
   },
 };
 
+/**
+ * #293 canon #6: Obsidian-native math — `$LaTeX$` (inline) and `$$…$$` (block).
+ *
+ * INLINE `$…$` uses the SHARED pandoc currency-safe rule (math-inline.ts), the
+ * SAME rule the serializer's prose escaper uses, so currency (`$5`,
+ * `$5 and $10`) is NEVER math and a would-be-math prose `$x$` (escaped `\$x\$`
+ * on export) stays literal. The captured inner LaTeX is decoded (`\$`→`$`) and
+ * emitted as the schema's `span[data-type="mathInline"]` carrying the LaTeX in a
+ * `text="…"` attribute (the schema's default attribute parser reads it back).
+ *
+ * BLOCK `$$…$$` matches a `$$` fence on its own line(s), capturing multi-line
+ * LaTeX up to the next `$$` line, and emits `div[data-type="mathBlock"]`.
+ *
+ * Both fail OPEN: an unbalanced `$`/`$$`, or a currency `$`, returns undefined
+ * from the tokenizer and stays literal text with no crash. Registered on the
+ * SAME dedicated instance as the highlight extension (never the global marked
+ * singleton), so the `$`/`$$` behavior cannot leak into unrelated callers.
+ */
+const mathInlineExtension: TokenizerExtension & RendererExtension = {
+  name: "mathInline",
+  level: "inline",
+  start(src: string) {
+    const i = src.indexOf("$");
+    return i < 0 ? undefined : i;
+  },
+  tokenizer(src: string) {
+    const match = inlineMathAnchoredRe().exec(src);
+    if (!match) return undefined; // currency / unbalanced -> literal
+    return {
+      type: "mathInline",
+      raw: match[0],
+      text: decodeInlineMathLatex(match[1]),
+    } as any;
+  },
+  renderer(token: any) {
+    return `<span data-type="mathInline" data-katex="true" text="${escapeMathAttr(token.text)}"></span>`;
+  },
+};
+
+const mathBlockExtension: TokenizerExtension & RendererExtension = {
+  name: "mathBlock",
+  level: "block",
+  start(src: string) {
+    const m = /(?:^|\n)\$\$/.exec(src);
+    if (!m) return undefined;
+    return m.index + (m[0].startsWith("\n") ? 1 : 0);
+  },
+  tokenizer(src: string) {
+    // A `$$` fence on its own line, then the SHORTEST run up to the next `$$`
+    // line (non-greedy, so it never swallows across an unrelated later fence).
+    // The inner may be empty (an empty mathBlock) or multi-line.
+    const match = /^\$\$[^\S\n]*\n([\s\S]*?)\n\$\$[^\S\n]*(?:\n|$)/.exec(src);
+    if (!match) return undefined; // no closing fence -> literal
+    return {
+      type: "mathBlock",
+      raw: match[0],
+      text: match[1],
+    } as any;
+  },
+  renderer(token: any) {
+    return `<div data-type="mathBlock" data-katex="true" text="${escapeMathAttr(token.text)}"></div>`;
+  },
+};
+
 // Dedicated marked instance: default (GFM) options plus the `==` highlight
-// inline extension. Constructed once at module load so the extension is
-// registered exactly once and never mutates the global `marked` singleton.
+// inline extension and the `$…$` / `$$…$$` math extensions (#293 canon #6).
+// Constructed once at module load so the extensions are registered exactly once
+// and never mutate the global `marked` singleton.
 const markedInstance = new Marked().use({
-  extensions: [highlightMarkExtension],
+  extensions: [highlightMarkExtension, mathInlineExtension, mathBlockExtension],
 });
 
 // Setup DOM environment for Tiptap HTML parsing in Node.js
diff --git a/packages/prosemirror-markdown/src/lib/math-inline.ts b/packages/prosemirror-markdown/src/lib/math-inline.ts
new file mode 100644
index 00000000..4deb3621
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/math-inline.ts
@@ -0,0 +1,78 @@
+/**
+ * Shared inline-math boundary rule (#293 canon #6).
+ *
+ * Pandoc's inline-math rule lives here because it is used in TWO directions that
+ * MUST agree byte-for-byte on which `$…$` spans are math:
+ *
+ *   - the IMPORT tokenizer (markdown-to-prosemirror.ts) that turns `$LaTeX$`
+ *     into a `mathInline` node, and
+ *   - the EXPORT escaper (markdown-converter.ts) that backslash-escapes a
+ *     would-be-math `$…$` span sitting in PROSE text so it re-imports as literal
+ *     text instead of silently materializing a phantom math node.
+ *
+ * Defining the rule ONCE guarantees the two directions never drift: a span the
+ * tokenizer would match is EXACTLY a span the escaper neutralizes, so a prose
+ * `$x$` round-trips as literal text and math `$x^2$` round-trips as math.
+ *
+ * The rule (currency-safe, from pandoc): an opening `$` is NOT followed by
+ * whitespace; the closing `$` is NOT preceded by whitespace AND NOT immediately
+ * followed by a digit; the inner run is non-empty, single-line, and may embed an
+ * escaped `\$` (which never counts as the closer). Under this rule `$5`,
+ * `$5 and $10`, `price is $5`, `a $5 b $6 c` all stay literal (no VALID closing
+ * `$` exists — the `$` before a space-preceded amount fails the "not preceded by
+ * whitespace" test, and a lone `$` has no closer), while `$x^2$` is math.
+ */
+
+// Core pattern (unanchored). Escaping note for the string form:
+//   \\$        -> a literal `$`
+//   (?!\s)     -> opening `$` NOT followed by whitespace (also forces a
+//                 non-empty inner: the next char must exist and be non-space)
+//   (?:\\\\\\$|[^$\n])+?  -> inner: shortest run of either an escaped `\$`
+//                 (consumed as a unit so it is never the closer) or any char
+//                 that is neither an unescaped `$` nor a newline
+//   (?<!\s)    -> the char before the closing `$` is NOT whitespace
+//   \\$        -> closing `$`
+//   (?![0-9])  -> closing `$` NOT immediately followed by a digit (currency)
+export const INLINE_MATH_SOURCE =
+  "\\$(?!\\s)((?:\\\\\\$|[^$\\n])+?)(?<!\\s)\\$(?![0-9])";
+
+/** Global matcher for the export-side prose escaper. */
+export const inlineMathGlobalRe = (): RegExp =>
+  new RegExp(INLINE_MATH_SOURCE, "g");
+
+/** Anchored matcher for the import-side marked tokenizer. */
+export const inlineMathAnchoredRe = (): RegExp =>
+  new RegExp("^" + INLINE_MATH_SOURCE);
+
+/** Decode a tokenizer-captured inner LaTeX: an escaped `\$` becomes `$`. */
+export const decodeInlineMathLatex = (inner: string): string =>
+  inner.replace(/\\\$/g, "$");
+
+/** Escape LaTeX for the `$…$` inline form so a literal `$` cannot close early. */
+export const encodeInlineMathLatex = (latex: string): string =>
+  latex.replace(/\$/g, "\\$");
+
+/**
+ * Whether a `mathInline` node's LaTeX can be safely serialized as `$LaTeX$`
+ * (vs. the always-lossless schema-HTML `<span>` fallback). Requires:
+ *   - non-empty (an empty span has no readable `$…$` form),
+ *   - non-whitespace edges (pandoc's opening/closing whitespace rules),
+ *   - single line (inline math never spans lines),
+ *   - no pre-existing `\$` and no trailing `\` — either would make the
+ *     `$`→`\$` escape ambiguous on decode (a `\\$` sequence, or an escaped
+ *     closing `$`), so those rare cases take the `<span>` fallback instead.
+ * NOTE: a following-sibling digit (which would also break the pandoc closing
+ * rule) cannot be seen from the node alone; that case is handled by the
+ * serializer's inline-children pass, not here.
+ */
+export const inlineMathSerializable = (latex: string): boolean =>
+  latex.length > 0 &&
+  !/^\s/.test(latex) &&
+  !/\s$/.test(latex) &&
+  !/[\r\n]/.test(latex) &&
+  !latex.includes("\\$") &&
+  !/\\$/.test(latex);
+
+/** Escape a value for an HTML double-quoted attribute (only & and " matter). */
+export const escapeMathAttr = (value: string): string =>
+  value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
diff --git a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
index adc4a7a5..86a00e25 100644
--- a/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter-golden.test.ts
@@ -184,13 +184,20 @@ describe('subpages token + unknown-in-container fallback', () => {
 
 describe('escaping idempotence (SPEC §11 phantom-diff guard)', () => {
   it('escapeAttr escapes ONLY & and " in an attribute context, and is idempotent', () => {
-    // The mathBlock `text` attr goes through escapeAttr. & -> &amp;, " -> &quot;.
-    const once = c({ type: 'mathBlock', attrs: { text: 'a & "b"' } });
-    expect(once).toBe(
+    // #293 canon #6: a TOP-LEVEL mathBlock now serializes as a `$$` fence, so
+    // to exercise the schema-HTML `text` attr (which DOES go through escapeAttr)
+    // we wrap the math in a COLUMN — the raw-HTML path keeps the `<div>` form.
+    const col = (child: any) => ({
+      type: 'columns',
+      content: [{ type: 'column', content: [child] }],
+    });
+    // & -> &amp;, " -> &quot; in the attribute context.
+    const once = c(col({ type: 'mathBlock', attrs: { text: 'a & "b"' } }));
+    expect(once).toContain(
       '<div data-type="mathBlock" data-katex="true" text="a &amp; &quot;b&quot;"></div>',
     );
     // < and > are deliberately NOT escaped (would accumulate on round-trips).
-    const angled = c({ type: 'mathBlock', attrs: { text: 'a < b > c' } });
+    const angled = c(col({ type: 'mathBlock', attrs: { text: 'a < b > c' } }));
     expect(angled).toContain('text="a < b > c"');
     expect(angled).not.toContain('&lt;');
     expect(angled).not.toContain('&gt;');
diff --git a/packages/prosemirror-markdown/test/markdown-converter.test.ts b/packages/prosemirror-markdown/test/markdown-converter.test.ts
index 5a8bddbb..2a39de6c 100644
--- a/packages/prosemirror-markdown/test/markdown-converter.test.ts
+++ b/packages/prosemirror-markdown/test/markdown-converter.test.ts
@@ -390,27 +390,26 @@ describe('convertProseMirrorToMarkdown', () => {
 
   // ---------------------------------------------------------------------------
   describe('math', () => {
-    it('inline math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
+    it('inline math serializes as $LaTeX$ (Obsidian-native), no HTML escaping', () => {
       const out = convertProseMirrorToMarkdown(
         doc(para({ type: 'mathInline', attrs: { text: 'a < b' } })),
       );
-      // < and > must NOT be HTML-escaped (idempotency); only & and " would be.
-      expect(out).toBe(
-        '<span data-type="mathInline" data-katex="true" text="a < b"></span>',
-      );
+      // #293 canon #6: readable `$…$` form; the LaTeX is verbatim (no HTML
+      // attribute escaping of < or & in the fence form).
+      expect(out).toBe('$a < b$');
       expect(out).not.toContain('&lt;');
+      expect(out).not.toContain('<span');
     });
 
-    it('block math carries LaTeX in a text attr WITHOUT escaping < or >', () => {
+    it('block math serializes as a $$ fence on its own lines', () => {
       const out = convertProseMirrorToMarkdown(
         doc({ type: 'mathBlock', attrs: { text: 'x > y & z' } }),
       );
-      // & IS escaped (entity-significant), but < and > are NOT.
-      expect(out).toBe(
-        '<div data-type="mathBlock" data-katex="true" text="x > y &amp; z"></div>',
-      );
-      expect(out).not.toContain('&lt;');
-      expect(out).not.toContain('&gt;');
+      // #293 canon #6: `$$\n<latex>\n$$`. The LaTeX is verbatim inside the fence
+      // (plain markdown, so & is NOT entity-escaped as it would be in an attr).
+      expect(out).toBe('$$\nx > y & z\n$$');
+      expect(out).not.toContain('&amp;');
+      expect(out).not.toContain('<div');
     });
   });
 
diff --git a/packages/prosemirror-markdown/test/math.test.ts b/packages/prosemirror-markdown/test/math.test.ts
new file mode 100644
index 00000000..27d71e63
--- /dev/null
+++ b/packages/prosemirror-markdown/test/math.test.ts
@@ -0,0 +1,262 @@
+import { describe, expect, it } from 'vitest';
+// Import DIRECTLY from src so we exercise the real converter pair (the parser
+// lives in markdown-to-prosemirror.ts; importing it mutates the global DOM via
+// jsdom at module load, which @tiptap/html's generateJSON needs under Node).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+import { markdownToProseMirror } from '../src/lib/markdown-to-prosemirror.js';
+
+// ---------------------------------------------------------------------------
+// #293 canon #6: math -> `$…$` (inline) and `$$…$$` (block).
+//
+// The CENTRAL correctness constraint is that a single/currency `$` is NEVER
+// math (`$5`, `it costs $5 and $10` stay literal), and a would-be-math `$x$`
+// span in PROSE round-trips as literal text (never a phantom math node). These
+// tests pin the serialize forms, the pandoc currency rule, the low-churn prose
+// escape, the columns/raw-HTML schema-HTML form, and codeBlock/inline-code
+// safety, and assert byte-stable round-trips throughout.
+// ---------------------------------------------------------------------------
+
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+
+// export -> import -> export. Returns md1, the re-imported doc, and md2 (which
+// MUST equal md1 for the git-sync data path to be byte-stable).
+async function roundTrip(node: any) {
+  const md1 = convertProseMirrorToMarkdown(doc(node));
+  const doc2 = await markdownToProseMirror(md1);
+  const md2 = convertProseMirrorToMarkdown(doc2);
+  return { md1, doc2, md2 };
+}
+
+// Depth-first find the first node of a type in a re-imported doc.
+function findNode(n: any, type: string): any {
+  if (!n || typeof n !== 'object') return undefined;
+  if (n.type === type) return n;
+  if (Array.isArray(n.content)) {
+    for (const c of n.content) {
+      const hit = findNode(c, type);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+// Concatenate every text run under a node (for asserting text is preserved).
+function allText(n: any): string {
+  if (!n || typeof n !== 'object') return '';
+  if (n.type === 'text') return n.text || '';
+  if (Array.isArray(n.content)) return n.content.map(allText).join('');
+  return '';
+}
+
+describe('mathInline serialize + round-trip', () => {
+  it('mathInline x^2 -> exact $x^2$ and re-imports as mathInline attrs.text x^2', async () => {
+    const { md1, doc2, md2 } = await roundTrip(para({ type: 'mathInline', attrs: { text: 'x^2' } }));
+    expect(md1).toBe('$x^2$');
+    expect(md2).toBe(md1); // byte-stable
+    const math = findNode(doc2, 'mathInline');
+    expect(math).toBeDefined();
+    expect(math.attrs.text).toBe('x^2');
+    // No stray literal text, no math-shaped currency false positive.
+    expect(allText(doc2)).toBe('');
+  });
+
+  it('mathInline surrounded by prose round-trips as math (not currency)', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      para(text('let '), { type: 'mathInline', attrs: { text: 'x^2' } }, text(' be')),
+    );
+    expect(md1).toBe('let $x^2$ be');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline').attrs.text).toBe('x^2');
+  });
+
+  it('LaTeX containing a literal $ is escaped \\$ and round-trips exact', async () => {
+    const { md1, doc2, md2 } = await roundTrip(para({ type: 'mathInline', attrs: { text: 'a$b' } }));
+    expect(md1).toBe('$a\\$b$'); // inner $ escaped so it cannot close early
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline').attrs.text).toBe('a$b');
+  });
+
+  it('empty mathInline falls back to the lossless schema-HTML <span> form', async () => {
+    const { md1, doc2, md2 } = await roundTrip(para({ type: 'mathInline', attrs: { text: '' } }));
+    // An empty `$$` would look like a block; the span form is lossless.
+    expect(md1).toBe('<span data-type="mathInline" data-katex="true" text=""></span>');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline')).toBeDefined();
+  });
+
+  it('mathInline whose LaTeX carries a pre-existing \\$ takes the span fallback', async () => {
+    // `\$` before escaping would make the `$`→`\$` escape ambiguous, so this
+    // rare case uses the always-lossless schema-HTML form (documented fork).
+    const { md1, doc2, md2 } = await roundTrip(para({ type: 'mathInline', attrs: { text: '\\$100' } }));
+    expect(md1).toContain('<span data-type="mathInline"');
+    expect(md1).not.toContain('$\\$100$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline').attrs.text).toBe('\\$100');
+  });
+
+  it('mathInline immediately followed by a digit text run uses the span fallback (round-trips)', async () => {
+    // `$x^2$5` would fail the pandoc closing rule (digit after `$`), so the math
+    // node falls back to the lossless span form; the "5" stays literal text.
+    const { md1, doc2, md2 } = await roundTrip(
+      para({ type: 'mathInline', attrs: { text: 'x^2' } }, text('5')),
+    );
+    expect(md1).toBe('<span data-type="mathInline" data-katex="true" text="x^2"></span>5');
+    expect(md1).not.toContain('$x^2$5');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline').attrs.text).toBe('x^2');
+    expect(allText(doc2)).toBe('5');
+  });
+});
+
+describe('mathBlock serialize + round-trip', () => {
+  it('multi-line mathBlock -> $$ fence with LaTeX intact, byte-stable', async () => {
+    const latex = '\\int_0^1 f\n= 1';
+    const { md1, doc2, md2 } = await roundTrip({ type: 'mathBlock', attrs: { text: latex } });
+    expect(md1).toBe('$$\n\\int_0^1 f\n= 1\n$$');
+    expect(md2).toBe(md1);
+    const math = findNode(doc2, 'mathBlock');
+    expect(math).toBeDefined();
+    expect(math.attrs.text).toBe(latex); // multi-line preserved
+  });
+
+  it('single-line mathBlock round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip({ type: 'mathBlock', attrs: { text: 'a^2+b^2' } });
+    expect(md1).toBe('$$\na^2+b^2\n$$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathBlock').attrs.text).toBe('a^2+b^2');
+  });
+
+  it('empty mathBlock round-trips as an empty $$ fence', async () => {
+    const { md1, doc2, md2 } = await roundTrip({ type: 'mathBlock', attrs: { text: '' } });
+    expect(md1).toBe('$$\n\n$$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathBlock')).toBeDefined();
+  });
+
+  it('mathBlock whose LaTeX contains a $$ takes the lossless <div> fallback', async () => {
+    const { md1, doc2, md2 } = await roundTrip({ type: 'mathBlock', attrs: { text: 'a $$ b' } });
+    expect(md1).toContain('<div data-type="mathBlock"');
+    expect(md1).not.toBe('$$\na $$ b\n$$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathBlock').attrs.text).toBe('a $$ b');
+  });
+});
+
+describe('currency: a single/currency $ is NEVER math', () => {
+  const cases = ['it costs $5', '$5 and $10', 'a $5 b $6 c', 'price is $5', 'pay $5 now'];
+  for (const original of cases) {
+    it(`"${original}" stays literal text with NO backslashes and NO math node`, async () => {
+      const { md1, doc2, md2 } = await roundTrip(para(text(original)));
+      // Emitted markdown carries NO escaping (currency has no valid closing $).
+      expect(md1).toBe(original);
+      expect(md1).not.toContain('\\$');
+      expect(md2).toBe(md1);
+      // No math node materialized; the text is preserved EXACTLY.
+      expect(findNode(doc2, 'mathInline')).toBeUndefined();
+      expect(allText(doc2)).toBe(original);
+    });
+  }
+
+  it('a currency amount preserves the exact string across a round trip', async () => {
+    const { doc2 } = await roundTrip(para(text('$5 and $10')));
+    expect(allText(doc2)).toBe('$5 and $10');
+    expect(findNode(doc2, 'mathInline')).toBeUndefined();
+  });
+});
+
+describe('prose $x$ (would-be math) round-trips as literal text (escaped)', () => {
+  it('the set $A$ -> \\$A\\$ and re-imports as literal text, no math node', async () => {
+    const { md1, doc2, md2 } = await roundTrip(para(text('the set $A$ is closed')));
+    expect(md1).toBe('the set \\$A\\$ is closed');
+    expect(md2).toBe(md1); // byte-stable
+    expect(findNode(doc2, 'mathInline')).toBeUndefined();
+    // The literal text is preserved exactly (backslashes are a serialization
+    // detail, decoded back on import).
+    expect(allText(doc2)).toBe('the set $A$ is closed');
+  });
+});
+
+describe('math inside a column keeps the schema-HTML form (NOT $…$)', () => {
+  const oneColumn = (child: any) => ({
+    type: 'columns',
+    content: [{ type: 'column', content: [child] }],
+  });
+
+  it('mathBlock in a column emits <div> (no $$ fence), round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn({ type: 'mathBlock', attrs: { text: 'a^2+b^2' } }),
+    );
+    expect(md1).toContain('<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>');
+    expect(md1).not.toContain('$$');
+    // The schema-HTML math form survives the round trip (a re-imported column
+    // gains a default data-layout, so we assert the math div, not full equality).
+    expect(md2).toContain('<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>');
+    expect(md2).not.toContain('$$');
+    expect(findNode(doc2, 'mathBlock').attrs.text).toBe('a^2+b^2');
+  });
+
+  it('mathInline in a column paragraph emits <span> (no $…$), round-trips', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      oneColumn(para(text('eq: '), { type: 'mathInline', attrs: { text: 'x_i' } })),
+    );
+    expect(md1).toContain('<span data-type="mathInline" data-katex="true" text="x_i"></span>');
+    expect(md1).not.toContain('$x_i$');
+    expect(md2).toContain('<span data-type="mathInline" data-katex="true" text="x_i"></span>');
+    expect(md2).not.toContain('$x_i$');
+    expect(findNode(doc2, 'mathInline').attrs.text).toBe('x_i');
+  });
+});
+
+describe('code is never math (canon #7 codeBlock regression class)', () => {
+  it('inline `code` span containing $x$ / $5 stays code, no math, no backslashes', async () => {
+    const { md1, doc2, md2 } = await roundTrip(
+      para(text('$x$ and $5', [{ type: 'code' }])),
+    );
+    // A code run is emitted verbatim in a backtick span — no `$` escaping, no math.
+    expect(md1).toBe('`$x$ and $5`');
+    expect(md1).not.toContain('\\$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline')).toBeUndefined();
+    const codeRun = findNode(doc2, 'text');
+    expect(codeRun.marks?.some((m: any) => m.type === 'code')).toBe(true);
+    expect(codeRun.text).toBe('$x$ and $5');
+  });
+
+  it('codeBlock containing $…$ and $5 stays code, no math, no backslash corruption', async () => {
+    const code = 'cost = $5\nx = $y$';
+    const { md1, doc2, md2 } = await roundTrip({
+      type: 'codeBlock',
+      attrs: { language: 'python' },
+      content: [text(code)],
+    });
+    // Fenced code is literal: the `$` are verbatim, no escaping, no math node.
+    expect(md1).toContain('cost = $5');
+    expect(md1).toContain('x = $y$');
+    expect(md1).not.toContain('\\$');
+    expect(md2).toBe(md1);
+    expect(findNode(doc2, 'mathInline')).toBeUndefined();
+    expect(findNode(doc2, 'mathBlock')).toBeUndefined();
+    // The `$` are preserved verbatim inside the fence (marked re-adds one
+    // trailing newline the exporter strips again, so compare against that).
+    const codeText = allText(findNode(doc2, 'codeBlock'));
+    expect(codeText).toContain('cost = $5');
+    expect(codeText).toContain('x = $y$');
+    expect(codeText).not.toContain('\\$');
+  });
+});
+
+describe('fail-open: unbalanced / lone $ never crashes and stays literal', () => {
+  for (const src of ['$', '$$', 'a $ b', '$ x $', 'unbalanced $x here']) {
+    it(`"${src}" imports without crash and materializes no math node`, async () => {
+      const doc2 = await markdownToProseMirror(src);
+      expect(doc2).toBeDefined();
+      expect(findNode(doc2, 'mathInline')).toBeUndefined();
+      // `$$` alone would only ever be a fence with content; a lone `$$` line is
+      // not a valid fence, so no mathBlock either.
+      expect(findNode(doc2, 'mathBlock')).toBeUndefined();
+    });
+  }
+});
diff --git a/packages/prosemirror-markdown/test/roundtrip.test.ts b/packages/prosemirror-markdown/test/roundtrip.test.ts
index 62db34b3..3132f904 100644
--- a/packages/prosemirror-markdown/test/roundtrip.test.ts
+++ b/packages/prosemirror-markdown/test/roundtrip.test.ts
@@ -60,10 +60,8 @@ describe('math round-trip (mathBlock + mathInline)', () => {
     const source = { type: 'mathBlock', attrs: { text: 'a^2+b^2' } };
     const { md1, doc2, md2 } = await roundTrip(source);
 
-    // One-way emit: LaTeX rides in the `text` HTML attribute, data-katex flag set.
-    expect(md1).toBe(
-      '<div data-type="mathBlock" data-katex="true" text="a^2+b^2"></div>',
-    );
+    // #293 canon #6: block math emits a `$$` fence on its own lines.
+    expect(md1).toBe('$$\na^2+b^2\n$$');
     // Byte-stable: the second export reproduces the first exactly.
     expect(md2).toBe(md1);
 
@@ -81,9 +79,8 @@ describe('math round-trip (mathBlock + mathInline)', () => {
     const source = para({ type: 'mathInline', attrs: { text: 'x_i' } });
     const { md1, doc2, md2 } = await roundTrip(source);
 
-    expect(md1).toBe(
-      '<span data-type="mathInline" data-katex="true" text="x_i"></span>',
-    );
+    // #293 canon #6: inline math emits the Obsidian-native `$LaTeX$` form.
+    expect(md1).toBe('$x_i$');
     expect(md2).toBe(md1);
 
     // The re-imported paragraph's child is a mathInline with the LaTeX recovered.
-- 
2.52.0


From 65d81f745ad9bf06772129f46855661a5b1b4862 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 10:31:00 +0300
Subject: [PATCH 09/17] feat(prosemirror-markdown): inline footnotes ^[text]
 (#293 canon #2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Footnotes now use the single canonical Pandoc/Obsidian inline form: the note
body is written AT the reference as `^[body]`, and the separate
`<section data-footnotes>` list is NOT emitted in markdown — it is reassembled
on import. New shared module src/lib/footnote.ts.

Serialize (markdown-converter.ts): a top-of-convert pre-scan builds
Map<id, definition> from the footnotesList; a footnoteReference emits
`^[<rendered body>]` (body paragraphs joined by a literal `\n`, real
backslash-n written `\\n`, stray unbalanced `[`/`]` escaped via balanceBrackets
while a balanced `[link](url)` stays intact); footnotesList/footnoteDefinition
emit nothing; an ORPHAN definition (no ref) is appended at doc end as its own
`^[body]` line so bodies are never lost (intentional, documented). The raw-HTML
path (inlineToHtml, columns) emits `<sup data-footnote-ref data-fn-text="…">`,
carrying the text at the ref there too; blockToHtml keeps the schema
`<section>`/`<div>` form for a list nested in a column.

Parse (markdown-to-prosemirror.ts): a `^[…]` inline extension on the dedicated
marked instance BALANCES brackets with a depth counter (respecting `\`-escapes),
so `^[note [a] b]` captures the full content, unbalanced `^[` fails open to
literal text. A post-marked assembleFootnotes pass collects every
`<sup data-fn-text>`, dedups by the EXACT body string, assigns sequential ids
(fn-1, fn-2, … first-seen), builds one `<div data-footnote-def>` per unique body
in a single `<section data-footnotes>`, and strips data-fn-text. No hash is used
(F1): dedup keying on the exact text makes an id collision between DIFFERENT
bodies impossible, while identical bodies still merge; ids are never written to
markdown, so round-trips stay byte-stable, and all id assignment is local to the
one call (race-free).

Correctness hardening from internal review:
- F2: raw user backslashes in a footnote body are doubled (`\`->`\\`) at text
  emission (via a per-conversion inFootnoteBody closure flag) BEFORE the
  serializer's own escapes (`\[ \] \= \$`) are layered on, so a body ending in
  `\` (Windows path, LaTeX, regex) no longer breaks the `^[…]` envelope and
  round-trips exactly; parseInline decodes `\\`->`\`. The old `\n`->`\\n` step is
  subsumed by this and removed.
- N1: assembleFootnotes runs to a FIXED POINT — parseInline of a def body can
  spawn a nested `<sup data-fn-text>` (a legal nested footnote `^[a ^[b] c]`),
  so the section is attached before the loop (querySelectorAll only sees
  attached nodes) and the scan repeats until no pending sup remains; the dedup
  map persists across rounds. Nested and 3+-level footnotes now round-trip
  byte-stably instead of silently dropping the inner body. Bounded by
  MAX_FOOTNOTE_ROUNDS as a fail-open safety net.
- N2: the id counter is seeded past the highest existing fn-<N> so a reused
  section's ids can never collide with generated ones.
- A literal `^[` in prose text is escaped `^\[` so it does not become a phantom
  footnote on re-import (codeBlock/inline-code excluded).

No backward compat: reference form `[^id]`/`[^id]: def` is not parsed (stays
literal). No existing golden asserted the old footnote HTML output.

Tests: new footnote.test.ts (22 cases: basic byte-stable round-trip, bracket
balancing, multi-paragraph `\n`, real backslash-n, dedup both directions,
NESTED + 3-level nest, F1 hash-collision pair surviving as distinct defs, F2
backslash bodies byte-stable, N2 id-seed, column data-fn-text form, orphan def,
no-backward-compat, literal-`^[` prose, fail-open, empty `^[]`).

package vitest: 607 passed; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../prosemirror-markdown/src/lib/footnote.ts  |  61 +++
 .../src/lib/markdown-converter.ts             | 236 +++++++-
 .../src/lib/markdown-to-prosemirror.ts        | 231 +++++++-
 .../test/footnote.test.ts                     | 509 ++++++++++++++++++
 4 files changed, 1008 insertions(+), 29 deletions(-)
 create mode 100644 packages/prosemirror-markdown/src/lib/footnote.ts
 create mode 100644 packages/prosemirror-markdown/test/footnote.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/footnote.ts b/packages/prosemirror-markdown/src/lib/footnote.ts
new file mode 100644
index 00000000..d1732734
--- /dev/null
+++ b/packages/prosemirror-markdown/src/lib/footnote.ts
@@ -0,0 +1,61 @@
+/**
+ * #293 canon #2: inline footnotes `^[text]`.
+ *
+ * Shared, side-effect-free helpers used by BOTH the serializer
+ * (markdown-converter.ts) and the importer (markdown-to-prosemirror.ts) so the
+ * two directions cannot drift.
+ *
+ * The canonical markdown form is Pandoc/Obsidian inline footnotes: the note body
+ * is written AT the reference point as `^[body]`; there is no separate
+ * `[^id]: …` definition line and no bottom `<section>` list in the markdown. On
+ * import the body is re-assembled into the schema's doc-level
+ * `footnotesList`/`footnoteDefinition` so the editor sees the usual three-node
+ * footnote model, while identical bodies MERGE to a single definition shared by
+ * every reference. Ids are assigned by the importer's assembleFootnotes pass
+ * (dedup on the EXACT body text -> sequential `fn-N`), NOT derived from a hash,
+ * so two DIFFERENT bodies can never collide onto one definition (F1). The id is
+ * never written to markdown (`^[body]` carries only text), so the round trip
+ * stays byte-stable regardless of the concrete id.
+ */
+
+/**
+ * Split an ENCODED footnote body (the inner captured between `^[` and its
+ * matching `]`, or the value of a `data-fn-text` attribute) into its paragraph
+ * markdown strings.
+ *
+ * Paragraph boundaries are the two-character literal separator `\n` (backslash +
+ * n); a REAL backslash-n in the body was encoded as `\\n` (an escaped backslash
+ * followed by n) by the serializer, so it must NOT split. The scan therefore
+ * treats any `\<char>` as an escaped pair kept verbatim (so `\\` `n` stays a
+ * literal backslash-then-n and the trailing `n` is plain), and only an
+ * UNescaped `\n` is a separator. Every other backslash escape (`\=`, `\$`,
+ * `\[`, …) is preserved untouched so the per-paragraph `parseInline` decodes it.
+ */
+export function splitFootnoteParagraphs(encoded: string): string[] {
+  const paragraphs: string[] = [];
+  let current = "";
+  let i = 0;
+  while (i < encoded.length) {
+    const c = encoded[i];
+    if (c === "\\" && i + 1 < encoded.length) {
+      const next = encoded[i + 1];
+      if (next === "n") {
+        // Unescaped backslash-n: a paragraph separator.
+        paragraphs.push(current);
+        current = "";
+        i += 2;
+        continue;
+      }
+      // Any other escaped pair (including `\\`) is kept verbatim; consuming
+      // BOTH chars is what makes an encoded real `\n` (`\\n`) safe — the `\\`
+      // pair is taken here, leaving the following `n` as an ordinary literal.
+      current += c + next;
+      i += 2;
+      continue;
+    }
+    current += c;
+    i++;
+  }
+  paragraphs.push(current);
+  return paragraphs;
+}
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 0011801d..5a5521b3 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -117,6 +117,122 @@ export function convertProseMirrorToMarkdown(content: any): string {
   const escapeProseMath = (value: string): string =>
     value.replace(inlineMathGlobalRe(), (_m, inner) => `\\$${inner}\\$`);
 
+  // #293 canon #2 inline footnotes. PRE-SCAN the whole tree once: map every
+  // footnote DEFINITION by its id (first-wins) and collect every REFERENCED id.
+  // The canonical markdown form inlines a note's body AT its reference point as
+  // `^[body]`, so the serializer needs the body keyed by id when it reaches a
+  // `footnoteReference`, and needs to know which definitions are orphaned (no
+  // ref) so their bodies are not silently dropped (appended at the doc end).
+  const footnoteDefs = new Map<string, any>();
+  const referencedFootnoteIds = new Set<string>();
+  // ITERATIVE walk (explicit stack, not recursion): a pathologically deep
+  // document must not overflow the call stack here — the same reason processNode
+  // has its depth guard. This scan is unbounded but stack-safe.
+  const scanStack: any[] = [content];
+  while (scanStack.length) {
+    const n = scanStack.pop();
+    if (!n || typeof n !== "object") continue;
+    if (
+      n.type === "footnoteDefinition" &&
+      n.attrs?.id &&
+      !footnoteDefs.has(n.attrs.id)
+    ) {
+      footnoteDefs.set(n.attrs.id, n);
+    }
+    if (n.type === "footnoteReference" && n.attrs?.id) {
+      referencedFootnoteIds.add(n.attrs.id);
+    }
+    if (Array.isArray(n.content)) {
+      for (const child of n.content) scanStack.push(child);
+    }
+  }
+
+  // Balance `[`/`]` in a rendered footnote body so the whole thing stays a
+  // parseable `^[…]` capture (the importer's tokenizer counts brackets from `^[`
+  // to the matching `]`). A markdown link's `[text](url)` is already balanced
+  // and is left intact; only a STRAY unmatched `]` (or `[`) — e.g. a literal
+  // bracket in prose — is backslash-escaped so it cannot open/close the footnote
+  // early. Already backslash-escaped pairs are passed through untouched.
+  const balanceBrackets = (s: string): string => {
+    const out: string[] = [];
+    const openIndices: number[] = []; // positions in `out` of unmatched `[`
+    let i = 0;
+    while (i < s.length) {
+      const c = s[i];
+      if (c === "\\" && i + 1 < s.length) {
+        out.push(c + s[i + 1]); // keep an existing escaped pair verbatim
+        i += 2;
+        continue;
+      }
+      if (c === "[") {
+        openIndices.push(out.length);
+        out.push("[");
+        i++;
+        continue;
+      }
+      if (c === "]") {
+        if (openIndices.length > 0) {
+          openIndices.pop();
+          out.push("]");
+        } else {
+          out.push("\\]"); // stray close -> escape
+        }
+        i++;
+        continue;
+      }
+      out.push(c);
+      i++;
+    }
+    for (const idx of openIndices) out[idx] = "\\["; // stray opens -> escape
+    return out.join("");
+  };
+
+  // While TRUE, `case "text"` DOUBLES every RAW user backslash (`\` -> `\\`) in a
+  // text run BEFORE the intentional markdown/balance escapes are layered on (see
+  // the text case). This is the F2 fix: a body ending in `\` (Windows path,
+  // LaTeX, regex) must survive `^[…]`. Without it a trailing `\` serialized to
+  // `^[…\]`, whose `\]` the import tokenizer reads as an ESCAPED `]`, so the
+  // balance never closed and the whole footnote degraded to literal prose (and
+  // the `\` was lost). Doubling raw backslashes makes `parseInline` restore each
+  // (`\\`->`\`) on import while the serializer's OWN single escapes (`\[` `\]`
+  // `\=` `\$`, the `\n` paragraph separator) stay intact. It is a closure flag
+  // (per-conversion, not module state), so concurrent conversions never share it.
+  let inFootnoteBody = false;
+
+  // Render a footnote DEFINITION's `paragraph+` body to INLINE markdown suitable
+  // to sit inside `^[…]`. Each paragraph is rendered inline (so links/marks in
+  // the note round-trip) with raw backslashes doubled (via inFootnoteBody) and
+  // its brackets balanced; paragraphs are then joined with the literal two-char
+  // separator `\n`. Because raw backslashes are already doubled, a real
+  // backslash-n in the text is `\\n` and never mistaken for the separator (the
+  // only unescaped `\n` is the join inserted here). Footnotes are inline (single
+  // line) in markdown, so an embedded hard break collapses to a space.
+  const renderFootnoteBody = (def: any): string => {
+    const paras = (def?.content || []).filter(
+      (p: any) => p?.type === "paragraph",
+    );
+    // A definition with no paragraph still yields one (empty) segment so an
+    // empty note serializes as `^[]` and round-trips.
+    const segments = (paras.length ? paras : [{ content: [] }]).map(
+      (p: any) => {
+        const prev = inFootnoteBody;
+        inFootnoteBody = true;
+        let s: string;
+        try {
+          s = renderInlineChildren(p.content || []);
+        } finally {
+          inFootnoteBody = prev;
+        }
+        // Collapse any real newline (e.g. a hard break) so `^[…]` stays on one
+        // logical line for the inline tokenizer.
+        s = s.replace(/\r?\n/g, " ");
+        s = balanceBrackets(s);
+        return s;
+      },
+    );
+    return segments.join("\\n");
+  };
+
   // Recursion depth guard. processNode is mutually recursive (directly and via
   // processListItem/processTaskItem/blockToHtml), and a pathologically nested
   // document (e.g. tens of thousands of nested blockquotes) would otherwise
@@ -194,8 +310,28 @@ export function convertProseMirrorToMarkdown(content: any): string {
     const nodeContent = node.content || [];
 
     switch (type) {
-      case "doc":
-        return nodeContent.map(processNode).join("\n\n");
+      case "doc": {
+        // #293 canon #2: the `footnotesList` is NOT emitted in markdown — every
+        // note body is inlined at its `^[…]` reference. Skip the list entirely
+        // (emitting "" would inject a phantom blank gap via the "\n\n" join),
+        // then append any ORPHAN definition (one no reference points at) as its
+        // own `^[body]` line so its body is never silently lost.
+        // F3 (accepted, intentional): on re-import that orphan `^[body]` line
+        // becomes a reference + definition (an orphan def gains a ref). This is
+        // lossless (the body survives) and byte-stable (it re-exports identically),
+        // so it is deliberately not treated as data loss.
+        const parts: string[] = [];
+        for (const child of nodeContent) {
+          if (child?.type === "footnotesList") continue;
+          parts.push(processNode(child));
+        }
+        for (const [id, def] of footnoteDefs) {
+          if (!referencedFootnoteIds.has(id)) {
+            parts.push(`^[${renderFootnoteBody(def)}]`);
+          }
+        }
+        return parts.join("\n\n");
+      }
 
       case "paragraph": {
         const text = renderInlineChildren(nodeContent);
@@ -251,6 +387,17 @@ export function convertProseMirrorToMarkdown(content: any): string {
         // A highlight run's own `==` delimiters are appended AFTER this in the
         // marks loop, so they are never escaped; only the run's inner text is.
         if (!(node.marks || []).some((m: any) => m.type === "code")) {
+          // #293 canon #2 (F2): inside a footnote body, DOUBLE every RAW user
+          // backslash FIRST, so it survives `^[…]` (the import tokenizer treats
+          // `\<char>` as an escape when balancing brackets, and `parseInline`
+          // decodes escapes). Doing it before the intentional escapes below keeps
+          // the serializer's own single escapes (`\=` `\$` `^\[`, and the `\[`/
+          // `\]` balanceBrackets adds) single; only genuine user backslashes are
+          // doubled. Skipped for code runs (a code span's content is NOT decoded
+          // by parseInline, so its backslashes must stay verbatim).
+          if (inFootnoteBody) {
+            textContent = textContent.replace(/\\/g, "\\\\");
+          }
           textContent = textContent.replace(/==/g, "\\=\\=");
           // #293 canon #6: escape a would-be inline-math `$…$` span so it stays
           // literal text on re-import (currency `$5` is left clean — see
@@ -258,6 +405,16 @@ export function convertProseMirrorToMarkdown(content: any): string {
           // above; an inline `code` run returns verbatim below, matching the
           // codeBlock path (a `$…$` inside code must stay code, never math).
           textContent = escapeProseMath(textContent);
+          // #293 canon #2: `^[` opens a LIVE inline-footnote span on import
+          // (`^[text]` -> a footnote reference). A LITERAL `^[` in prose text
+          // would therefore materialize a phantom footnote on the next import, so
+          // backslash-escape the bracket (`^[` -> `^\[`); marked's escape
+          // tokenizer decodes `\[` back to `[`, so a literal `^[…]` round-trips
+          // as text and never opens a footnote. Only the OPENING `^[` needs
+          // breaking (the tokenizer requires it), so this is a minimal, idempotent
+          // escape. A real footnoteReference node emits `^[body]` from its own
+          // case, never through here.
+          textContent = textContent.replace(/\^\[/g, "^\\[");
         }
         // Apply marks (bold, italic, code, etc.)
         if (node.marks) {
@@ -854,26 +1011,29 @@ export function convertProseMirrorToMarkdown(content: any): string {
       }
 
       case "footnoteReference": {
-        // Inline atom marker. The schema reads its id from data-id on a
-        // sup[data-footnote-ref]; the visible number is derived, not stored.
-        const attrs = node.attrs || {};
-        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
-        return `<sup data-footnote-ref${idAttr}></sup>`;
+        // #293 canon #2: on the top-level/inline markdown path a footnote is
+        // written AT its reference as `^[body]` (Pandoc/Obsidian inline
+        // footnote). Look the body up by id in the pre-scanned definitions map
+        // and render it inline. An ORPHAN reference (no matching definition) has
+        // no body anywhere, so it emits `^[]` — a footnote with an empty body,
+        // the lossless choice (the id was already derived, never authored). The
+        // separate `<section data-footnotes>` list is NOT emitted (see the
+        // footnotesList/doc cases); the raw-HTML path carries the body on the
+        // <sup> instead (inlineToHtml).
+        const def = footnoteDefs.get(node.attrs?.id);
+        return `^[${def ? renderFootnoteBody(def) : ""}]`;
       }
 
-      case "footnotesList": {
-        // Bottom container of footnote definitions (section[data-footnotes]).
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<section data-footnotes>${inner}</section>`;
-      }
+      case "footnotesList":
+        // Bodies are inlined at their references (`^[…]`), so the bottom list
+        // emits NOTHING in markdown. The doc case skips it outright to avoid a
+        // phantom blank line; this case guards any non-doc-level occurrence.
+        return "";
 
-      case "footnoteDefinition": {
-        // One footnote note keyed by id (div[data-footnote-def]).
-        const attrs = node.attrs || {};
-        const idAttr = attrs.id ? ` data-id="${escapeAttr(attrs.id)}"` : "";
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div data-footnote-def${idAttr}>${inner}</div>`;
-      }
+      case "footnoteDefinition":
+        // Reached only via a footnotesList (handled above) — never rendered on
+        // its own on the markdown path; its body rides at the reference.
+        return "";
 
       case "pageEmbed": {
         // #293 canon #8 (standalone): a whole-page live embed serializes as a
@@ -951,9 +1111,22 @@ export function convertProseMirrorToMarkdown(content: any): string {
         // NOT re-parse markdown, so inline math MUST stay the schema-HTML `<span>`
         // form here — a `$…$` fence would land as literal text on re-import.
         if (n.type === "mathInline") return mathInlineHtml(n.attrs?.text || "");
+        if (n.type === "footnoteReference") {
+          // #293 canon #2 raw-HTML path (columns/spanned cells): marked does NOT
+          // re-parse `^[…]` inside raw HTML, so the note text rides ON the <sup>
+          // in a `data-fn-text` attribute (encoded exactly like the `^[…]`
+          // inner). NO id is emitted here (F1): the importer's footnote post-pass
+          // assigns ids by dedup-ing on the EXACT body text, so a column footnote
+          // and an inline `^[…]` with the same body merge to one definition and
+          // DIFFERENT bodies can never collide. The post-pass reads data-fn-text,
+          // sets data-id, builds the doc-level definition, and strips the attr.
+          const def = footnoteDefs.get(n.attrs?.id);
+          const body = def ? renderFootnoteBody(def) : "";
+          return `<sup data-footnote-ref data-fn-text="${escapeAttr(body)}"></sup>`;
+        }
         if (n.type !== "text") {
-          // Other inline atoms (mention, status, footnoteRef) already emit
-          // schema HTML from processNode.
+          // Other inline atoms (mention, status) already emit schema HTML from
+          // processNode.
           return processNode(n);
         }
         let t = escapeHtmlText(n.text || "");
@@ -1205,13 +1378,28 @@ export function convertProseMirrorToMarkdown(content: any): string {
       // rebuilds) instead of delegating to processNode's fence form.
       case "mathBlock":
         return mathBlockHtml(block.attrs?.text || "");
-      // columns/column, htmlEmbed, footnotes, transclusionSource already emit
+      // #293 canon #2: on the markdown path a footnotesList emits nothing (the
+      // note body rides at each `^[…]` reference). But a raw-HTML container
+      // drops comment/markdown reconstruction, so KEEP the schema-matching
+      // <section>/<div> HTML here so a footnotesList that ever lands inside a
+      // column/cell still round-trips via the schema's parseHTML instead of
+      // vanishing. (Normally the list is doc-level and never nests here.)
+      case "footnotesList": {
+        const inner = (block.content || []).map(blockToHtml).join("");
+        return `<section data-footnotes>${inner}</section>`;
+      }
+      case "footnoteDefinition": {
+        const idAttr = block.attrs?.id
+          ? ` data-id="${escapeAttr(block.attrs.id)}"`
+          : "";
+        const inner = (block.content || []).map(blockToHtml).join("");
+        return `<div data-footnote-def${idAttr}>${inner}</div>`;
+      }
+      // columns/column, htmlEmbed, transclusionSource already emit
       // schema-matching HTML from processNode.
       case "columns":
       case "column":
       case "htmlEmbed":
-      case "footnotesList":
-      case "footnoteDefinition":
       case "transclusionSource":
         return processNode(block);
       default:
diff --git a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
index d9a80b46..b5e0f2d7 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-to-prosemirror.ts
@@ -13,6 +13,7 @@ import { Marked } from "marked";
 import type { TokenizerExtension, RendererExtension } from "marked";
 import { docmostExtensions } from "./docmost-schema.js";
 import { parseAttachedComment } from "./attached-comment.js";
+import { splitFootnoteParagraphs } from "./footnote.js";
 import {
   decodeInlineMathLatex,
   escapeMathAttr,
@@ -148,12 +149,100 @@ const mathBlockExtension: TokenizerExtension & RendererExtension = {
   },
 };
 
+/**
+ * #293 canon #2: Pandoc/Obsidian inline footnotes — `^[note body]`.
+ *
+ * The single canonical markdown form carries the note body AT the reference
+ * point. The crux is the tokenizer: it BALANCES `[`/`]` (respecting
+ * backslash-escaped brackets) from the opening `^[` to its MATCHING `]`, so a
+ * body that itself contains a `[link](url)` is captured whole — a lazy
+ * `^\[([^\]]+)\]` would cut at the first inner `]` and fragment the parse.
+ *
+ * The renderer emits the schema's `<sup data-footnote-ref>` marker carrying the
+ * (still-encoded) body in a `data-fn-text` attribute and NO id. A later
+ * post-`marked` pass (assembleFootnotes) collects those sups, dedups by the EXACT
+ * body text, ASSIGNS sequential ids (fn-1, fn-2, … in first-seen order), and
+ * builds one doc-level `<div data-footnote-def>` per unique body inside a single
+ * `<section data-footnotes>`. Assigning ids from the exact text (rather than a
+ * hash) makes collisions between DIFFERENT bodies impossible (F1) while staying
+ * race-free — all ids are assigned inside that one call from the local DOM, no
+ * module state — and byte-stable (ids are never written to markdown; `^[body]`
+ * carries only text, so identical bodies still merge).
+ *
+ * Fail-open: an unbalanced `^[` with no matching `]` returns undefined from the
+ * tokenizer and stays literal text (no crash). `^[]` is a footnote with an empty
+ * body. The reference form `[^id]` / `[^id]: def` is NOT parsed (no `^[`), so it
+ * stays literal (an accepted hand-authoring gap; no backward compat). Registered
+ * on the SAME dedicated instance as the highlight/math extensions.
+ */
+const footnoteInlineExtension: TokenizerExtension & RendererExtension = {
+  name: "footnoteInline",
+  level: "inline",
+  start(src: string) {
+    const i = src.indexOf("^[");
+    return i < 0 ? undefined : i;
+  },
+  tokenizer(src: string) {
+    if (!src.startsWith("^[")) return undefined;
+    // Balance-scan from just after `^[` to the matching `]`. A backslash escapes
+    // the next character (so `\[` / `\]` do not affect the depth), matching the
+    // serializer's balanceBrackets.
+    let depth = 1;
+    let i = 2;
+    while (i < src.length) {
+      const c = src[i];
+      if (c === "\\" && i + 1 < src.length) {
+        i += 2;
+        continue;
+      }
+      if (c === "[") {
+        depth++;
+        i++;
+        continue;
+      }
+      if (c === "]") {
+        depth--;
+        if (depth === 0) break;
+        i++;
+        continue;
+      }
+      i++;
+    }
+    if (depth !== 0) return undefined; // unbalanced -> literal text (fail-open)
+    const inner = src.slice(2, i); // content between `^[` and the matching `]`
+    return {
+      type: "footnoteInline",
+      raw: src.slice(0, i + 1), // includes the closing `]`
+      text: inner,
+    } as any;
+  },
+  renderer(token: any) {
+    // No id here (F1): assembleFootnotes assigns ids by dedup-ing the exact body.
+    return `<sup data-footnote-ref data-fn-text="${escapeFootnoteAttr(token.text)}"></sup>`;
+  },
+};
+
+/**
+ * Escape a value placed in a double-quoted HTML attribute (footnote id /
+ * body). Only `&` and `"` are special in that context; escaping them keeps the
+ * attribute well-formed and is idempotent (jsdom decodes them back).
+ */
+function escapeFootnoteAttr(value: string): string {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+
 // Dedicated marked instance: default (GFM) options plus the `==` highlight
-// inline extension and the `$…$` / `$$…$$` math extensions (#293 canon #6).
-// Constructed once at module load so the extensions are registered exactly once
-// and never mutate the global `marked` singleton.
+// inline extension, the `$…$` / `$$…$$` math extensions (#293 canon #6), and the
+// `^[…]` inline-footnote extension (#293 canon #2). Constructed once at module
+// load so the extensions are registered exactly once and never mutate the global
+// `marked` singleton.
 const markedInstance = new Marked().use({
-  extensions: [highlightMarkExtension, mathInlineExtension, mathBlockExtension],
+  extensions: [
+    highlightMarkExtension,
+    mathInlineExtension,
+    mathBlockExtension,
+    footnoteInlineExtension,
+  ],
 });
 
 // Setup DOM environment for Tiptap HTML parsing in Node.js
@@ -738,6 +827,134 @@ function applyCommentDirectives(html: string): string {
   return document.body.innerHTML;
 }
 
+/**
+ * #293 canon #2: assemble the doc-level footnote list from the `<sup>` markers.
+ *
+ * The `^[…]` inline extension (and the raw-HTML column path) leave every
+ * footnote reference as `<sup data-footnote-ref data-fn-text>`, carrying the
+ * (encoded) note body ON the marker but NO id. This post-`marked` pass — a
+ * sibling of applyCommentDirectives, run before generateJSON — turns those into
+ * the schema's three-node model:
+ *
+ *   - collect every `<sup data-footnote-ref>` that carries a `data-fn-text`;
+ *   - DEDUP by the EXACT body text (first-seen order) and assign SEQUENTIAL ids
+ *     `fn-1`, `fn-2`, …; set `data-id` on each sup (matched by its body). This is
+ *     the F1 fix: distinct bodies get distinct ids, so DIFFERENT notes can never
+ *     merge (a hash-derived id could collide and silently drop one body), while
+ *     identical bodies still key to the same entry and MERGE (identical `^[text]`
+ *     merge; a column footnote and an inline one with the same body collapse to
+ *     one def);
+ *   - build one `<div data-footnote-def data-id>` per unique body — the decoded
+ *     `data-fn-text` split on the literal `\n` separator into `<p>`s, each parsed
+ *     as INLINE markdown so links/marks in the note round-trip;
+ *   - append those defs into a single doc-level `<section data-footnotes>` at the
+ *     END of `<body>` — reusing an existing one if the HTML already has a
+ *     footnotes section (F4: never emit a duplicate `<section>`);
+ *   - STRIP `data-fn-text` from every sup, leaving `<sup data-footnote-ref
+ *     data-id>` for the schema's FootnoteReference parseHTML.
+ *
+ * NESTED footnotes (N1): a body can itself contain a `^[…]` (Pandoc/Obsidian
+ * allow it, and the schema's `footnoteDefinition` body is `paragraph+` → inline →
+ * footnoteReference), so `parseInline` of a def body SPAWNS a new inner
+ * `<sup data-fn-text>` INSIDE the just-built definition. A single scan would
+ * leave that inner sup unassigned (dangling `footnoteReference{id:null}`, inner
+ * body lost). So the pass runs to a FIXED POINT: after each round it RE-SCANS for
+ * any `sup[data-footnote-ref][data-fn-text]` still lacking a `data-id` and
+ * processes those too, reusing the SAME exact-body dedup map so an inner body
+ * identical to another still merges. A large round cap bounds pathological input
+ * (fail-open: leftover sups stay inert rather than looping forever).
+ *
+ * Race-free by construction: ids are assigned inside this one call from the local
+ * DOM, so concurrent conversions share no mutable state. Fail-open: a sup without
+ * `data-fn-text` (e.g. a legacy `<sup data-footnote-ref data-id>` from the old
+ * `<section>` HTML form) is left untouched.
+ */
+// Hard cap on fixed-point rounds. Each round peels ONE nesting level, so this is
+// far above any realistic footnote nesting; it exists only so an adversarial
+// input can never spin unbounded. On hitting it we stop (leftover deeply-nested
+// sups stay inert) rather than hang.
+const MAX_FOOTNOTE_ROUNDS = 10000;
+
+function assembleFootnotes(html: string): string {
+  // Cheap early-out: nothing carries a footnote body -> nothing to assemble.
+  if (!html.includes("data-fn-text")) return html;
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  if (document.querySelector("sup[data-footnote-ref][data-fn-text]") == null) {
+    return html;
+  }
+
+  // F4: reuse an existing footnotes section if the HTML already has one (e.g. a
+  // legacy `<section data-footnotes>` from the old HTML form, or a footnotesList
+  // that landed inside a column via the raw-HTML path) so we never emit a
+  // duplicate. Otherwise create one at the END of <body>.
+  let section = document.querySelector("section[data-footnotes]");
+  if (!section) {
+    section = document.createElement("section");
+    section.setAttribute("data-footnotes", "");
+    // Attach it NOW (at the end of body), BEFORE the fixed-point loop: each def
+    // is appended into this section, and a def body's `parseInline` may spawn a
+    // nested `<sup data-fn-text>`. The re-scan below uses `document.query…`,
+    // which only sees ATTACHED nodes — so the section must live in the document
+    // for those inner sups to be found (N1). A detached section would hide them.
+    document.body.appendChild(section);
+  }
+
+  // N2: seed the sequential id counter PAST the highest `fn-<N>` id already
+  // present ANYWHERE in the document (a reused legacy section's defs, or existing
+  // refs), so a generated id can never collide with a pre-existing one and
+  // produce two defs sharing an id (ambiguous ref↔def).
+  let counter = 0;
+  for (const el of Array.from(document.querySelectorAll("[data-id]"))) {
+    const m = /^fn-(\d+)$/.exec(el.getAttribute("data-id") || "");
+    if (m) counter = Math.max(counter, parseInt(m[1], 10));
+  }
+
+  // Dedup by the EXACT body text (first-seen order) -> sequential id. Keyed on
+  // the string itself, so two DIFFERENT bodies can NEVER share an id (F1). The
+  // map persists ACROSS rounds so a nested inner body that equals an outer/other
+  // body merges to the same def (N1).
+  const idByBody = new Map<string, string>(); // exact body -> assigned id
+
+  for (let round = 0; round < MAX_FOOTNOTE_ROUNDS; round++) {
+    const pending = Array.from(
+      document.querySelectorAll("sup[data-footnote-ref][data-fn-text]"),
+    );
+    if (pending.length === 0) break;
+    for (const sup of pending) {
+      const body = sup.getAttribute("data-fn-text") || "";
+      let id = idByBody.get(body);
+      const isNew = id === undefined;
+      if (id === undefined) {
+        id = `fn-${++counter}`;
+        idByBody.set(body, id);
+      }
+      // Pin the id on the sup so the reference matches its definition, and strip
+      // the transient body attribute so it never re-matches / reaches generateJSON.
+      sup.setAttribute("data-id", id);
+      sup.removeAttribute("data-fn-text");
+      if (!isNew) continue; // this body already has its definition
+      // Build the definition. `parseInline` may inject a NEW inner
+      // `<sup data-fn-text>` into this def body — that is caught on the next
+      // round's re-scan (the fixed-point loop).
+      const def = document.createElement("div");
+      def.setAttribute("data-footnote-def", "");
+      def.setAttribute("data-id", id);
+      // Split the encoded body into paragraph markdown strings, then parse each
+      // inline so links/marks survive. An empty body yields one empty paragraph
+      // (the schema's footnoteDefinition requires `paragraph+`).
+      for (const paraMd of splitFootnoteParagraphs(body)) {
+        const p = document.createElement("p");
+        p.innerHTML = markedInstance.parseInline(paraMd) as string;
+        def.appendChild(p);
+      }
+      section.appendChild(def);
+    }
+  }
+
+  return document.body.innerHTML;
+}
+
 /**
  * Recursively strip content-less paragraph nodes from a generated doc.
  *
@@ -786,7 +1003,11 @@ export async function markdownToProseMirror(
   // subpages/pageBreak) while the comment nodes still exist, before generateJSON
   // drops them.
   const withAttrs = applyCommentDirectives(html);
-  const bridged = bridgeTaskLists(withAttrs);
+  // #293 canon #2: assemble the doc-level footnote list from the `<sup
+  // data-fn-text>` markers (from `^[…]` or the raw-HTML column form) before
+  // generateJSON, so references + definitions materialize into the schema model.
+  const withFootnotes = assembleFootnotes(withAttrs);
+  const bridged = bridgeTaskLists(withFootnotes);
   const doc = generateJSON(bridged, docmostExtensions);
   return stripEmptyParagraphs(doc);
 }
diff --git a/packages/prosemirror-markdown/test/footnote.test.ts b/packages/prosemirror-markdown/test/footnote.test.ts
new file mode 100644
index 00000000..7d6fe4db
--- /dev/null
+++ b/packages/prosemirror-markdown/test/footnote.test.ts
@@ -0,0 +1,509 @@
+import { describe, expect, it } from "vitest";
+// Import the converters DIRECTLY from src (NOT the docmost-client barrel, which
+// mutates the global DOM at import time), matching the other converter tests.
+import { convertProseMirrorToMarkdown } from "../src/lib/markdown-converter.js";
+import { markdownToProseMirror } from "../src/lib/markdown-to-prosemirror.js";
+
+// ---------------------------------------------------------------------------
+// Tiny builders (mirror the other converter tests).
+// ---------------------------------------------------------------------------
+const doc = (...nodes: any[]) => ({ type: "doc", content: nodes });
+const P = (...content: any[]) => ({ type: "paragraph", content });
+const T = (text: string, marks?: any[]) =>
+  marks ? { type: "text", text, marks } : { type: "text", text };
+const ref = (id: string) => ({ type: "footnoteReference", attrs: { id } });
+const list = (...defs: any[]) => ({ type: "footnotesList", content: defs });
+const def = (id: string, ...paras: any[]) => ({
+  type: "footnoteDefinition",
+  attrs: { id },
+  content: paras,
+});
+
+// Find the FIRST node of a type anywhere in a PM tree (depth first).
+function findNode(n: any, type: string): any {
+  if (!n || typeof n !== "object") return undefined;
+  if (n.type === type) return n;
+  if (Array.isArray(n.content)) {
+    for (const c of n.content) {
+      const hit = findNode(c, type);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+// Collect EVERY node of a type.
+function findAll(n: any, type: string, out: any[] = []): any[] {
+  if (!n || typeof n !== "object") return out;
+  if (n.type === type) out.push(n);
+  if (Array.isArray(n.content)) n.content.forEach((c: any) => findAll(c, type, out));
+  return out;
+}
+// Concatenate all text under a node.
+function allText(n: any): string {
+  if (!n || typeof n !== "object") return "";
+  if (n.type === "text") return n.text || "";
+  if (Array.isArray(n.content)) return n.content.map(allText).join("");
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// basic: `^[body]` at the reference point, byte-stable round trip.
+// ---------------------------------------------------------------------------
+describe("inline footnote: basic", () => {
+  it("serializes a ref + def to `text^[a note]` and re-imports losslessly", async () => {
+    const d = doc(P(T("text"), ref("fn1")), list(def("fn1", P(T("a note")))));
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe("text^[a note]");
+
+    const back = await markdownToProseMirror(md);
+    const r = findNode(back, "footnoteReference");
+    const l = findNode(back, "footnotesList");
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(r).toBeDefined();
+    expect(l).toBeDefined();
+    expect(dfn).toBeDefined();
+    // The note body rode along, not just the wrapper.
+    expect(allText(dfn)).toBe("a note");
+    // The reference points at the matching definition (derived id).
+    expect(r.attrs.id).toBe(dfn.attrs.id);
+    // Ids are assigned sequentially by the import post-pass (F1), not hashed.
+    expect(r.attrs.id).toBe("fn-1");
+
+    // Byte-stable: re-export equals the first export.
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// bracket balancing (MANDATORY): a `[link](url)` inside the body is captured
+// whole and survives as a link mark in the definition.
+// ---------------------------------------------------------------------------
+describe("inline footnote: bracket balancing", () => {
+  it("captures a full balanced `[link](url)` body and keeps the link", async () => {
+    const body = "note with a ";
+    const d = doc(
+      P(T("x"), ref("fn1")),
+      list(
+        def(
+          "fn1",
+          P(
+            T(body),
+            T("link", [{ type: "link", attrs: { href: "https://x" } }]),
+            T(" inside"),
+          ),
+        ),
+      ),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe("x^[note with a [link](https://x) inside]");
+
+    const back = await markdownToProseMirror(md);
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(allText(dfn)).toBe("note with a link inside");
+    // The link mark survived inside the definition (parser did NOT cut at the
+    // first inner `]`).
+    const linkText = findAll(dfn, "text").find((t: any) =>
+      (t.marks || []).some((m: any) => m.type === "link"),
+    );
+    expect(linkText).toBeDefined();
+    expect(linkText.text).toBe("link");
+    expect(linkText.marks[0].attrs.href).toBe("https://x");
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+
+  it("escapes a STRAY unbalanced `]`/`[` in body text and round-trips it", async () => {
+    const d = doc(
+      P(T("x"), ref("fn1")),
+      list(def("fn1", P(T("a ] and [ stray")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    // The stray brackets are backslash-escaped so `^[…]` stays parseable.
+    expect(md).toBe("x^[a \\] and \\[ stray]");
+
+    const back = await markdownToProseMirror(md);
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(allText(dfn)).toBe("a ] and [ stray");
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// multi-paragraph body -> literal `\n` separator.
+// ---------------------------------------------------------------------------
+describe("inline footnote: multi-paragraph body", () => {
+  it("joins two paragraphs with a literal `\\n` and re-splits them", async () => {
+    const d = doc(
+      P(T("x"), ref("fn1")),
+      list(def("fn1", P(T("para one")), P(T("para two")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    // The separator is the two literal characters backslash + n.
+    expect(md).toBe("x^[para one\\npara two]");
+    expect(md.includes("\\n")).toBe(true);
+    // NOT a real newline inside the footnote.
+    expect(md.includes("\n")).toBe(false);
+
+    const back = await markdownToProseMirror(md);
+    const dfn = findNode(back, "footnoteDefinition");
+    const paras = (dfn.content || []).filter((p: any) => p.type === "paragraph");
+    expect(paras.length).toBe(2);
+    expect(allText(paras[0])).toBe("para one");
+    expect(allText(paras[1])).toBe("para two");
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// real backslash-n escaping (MANDATORY): a literal `\n` in the body text is
+// emitted as `\\n` and round-trips to the literal text, NOT a paragraph break.
+// ---------------------------------------------------------------------------
+describe("inline footnote: real backslash-n escaping", () => {
+  it("escapes a literal `\\n` as `\\\\n` and keeps it a single paragraph", async () => {
+    // Body text contains the two literal characters: backslash, n.
+    const d = doc(
+      P(T("x"), ref("fn1")),
+      list(def("fn1", P(T("path C:\\new here")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    // The real backslash-n becomes an ESCAPED backslash-n (`\\n`).
+    expect(md).toBe("x^[path C:\\\\new here]");
+
+    const back = await markdownToProseMirror(md);
+    const dfn = findNode(back, "footnoteDefinition");
+    const paras = (dfn.content || []).filter((p: any) => p.type === "paragraph");
+    // A single paragraph — the `\n` was NOT read as a paragraph break.
+    expect(paras.length).toBe(1);
+    expect(allText(dfn)).toBe("path C:\\new here");
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dedup / multiple refs.
+// ---------------------------------------------------------------------------
+describe("inline footnote: dedup", () => {
+  it("two refs to the SAME def emit `^[same]` twice and MERGE on parse", async () => {
+    const d = doc(
+      P(T("a"), ref("fn1"), T(" b"), ref("fn1")),
+      list(def("fn1", P(T("same text")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe("a^[same text] b^[same text]");
+
+    const back = await markdownToProseMirror(md);
+    // Two references, ONE definition (merged), sharing the same id.
+    const refs = findAll(back, "footnoteReference");
+    const defs = findAll(back, "footnoteDefinition");
+    expect(refs.length).toBe(2);
+    expect(defs.length).toBe(1);
+    expect(refs[0].attrs.id).toBe(refs[1].attrs.id);
+    expect(refs[0].attrs.id).toBe(defs[0].attrs.id);
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+
+  it("two `^[identical]` in SOURCE merge to one definition", async () => {
+    const back = await markdownToProseMirror("a^[note] b^[note]");
+    const refs = findAll(back, "footnoteReference");
+    const defs = findAll(back, "footnoteDefinition");
+    expect(refs.length).toBe(2);
+    expect(defs.length).toBe(1);
+    expect(refs[0].attrs.id).toBe(defs[0].attrs.id);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// footnote inside a column -> raw-HTML `<sup data-fn-text>` form (NOT `^[…]`).
+// ---------------------------------------------------------------------------
+describe("inline footnote: inside a column", () => {
+  it("carries the body on `<sup data-fn-text>` and round-trips", async () => {
+    const d = doc(
+      {
+        type: "columns",
+        content: [
+          {
+            type: "column",
+            attrs: { width: "50%" },
+            content: [P(T("col "), ref("fn1"))],
+          },
+        ],
+      },
+      list(def("fn1", P(T("colnote")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    // Raw-HTML path: the ref carries its text ON the sup, NOT as `^[…]`.
+    expect(md).toContain('data-fn-text="colnote"');
+    expect(md).not.toContain("^[");
+
+    const back = await markdownToProseMirror(md);
+    // The reference stays inside the column; the definition is at doc level.
+    const col = findNode(back, "column");
+    expect(findNode(col, "footnoteReference")).toBeDefined();
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(allText(dfn)).toBe("colnote");
+    const r = findNode(back, "footnoteReference");
+    expect(r.attrs.id).toBe(dfn.attrs.id);
+
+    // The footnote portion is byte-stable on re-export (the surrounding columns
+    // node applies its own layout/width normalization, unrelated to footnotes).
+    // The raw-HTML column sup carries the body on data-fn-text and NO id (F1);
+    // the id is assigned by the import post-pass.
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toContain('data-fn-text="colnote"');
+    expect(md2).not.toContain("data-id=");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// orphan definition: a def with no reference is not silently lost.
+// ---------------------------------------------------------------------------
+describe("inline footnote: orphan definition", () => {
+  it("appends an unreferenced definition as its own `^[body]` line", async () => {
+    const d = doc(P(T("body text")), list(def("fnX", P(T("orphan note")))));
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe("body text\n\n^[orphan note]");
+
+    const back = await markdownToProseMirror(md);
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(dfn).toBeDefined();
+    expect(allText(dfn)).toBe("orphan note");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// no backward compat: `[^id]` / `[^id]: def` stay literal (no footnote node).
+// ---------------------------------------------------------------------------
+describe("inline footnote: no backward compat for the reference form", () => {
+  it("does not parse `[^1]` into a footnote node", async () => {
+    const back = await markdownToProseMirror("see [^1] here");
+    expect(findNode(back, "footnoteReference")).toBeUndefined();
+    expect(findNode(back, "footnotesList")).toBeUndefined();
+    // The literal text survives.
+    expect(allText(back)).toContain("[^1]");
+  });
+
+  it("does not parse a `[^1]: def` definition line into a footnote node", async () => {
+    const back = await markdownToProseMirror("text\n\n[^1]: a definition");
+    expect(findNode(back, "footnoteReference")).toBeUndefined();
+    expect(findNode(back, "footnoteDefinition")).toBeUndefined();
+    expect(findNode(back, "footnotesList")).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// literal `^[` in prose must NOT materialize a phantom footnote on re-import.
+// ---------------------------------------------------------------------------
+describe("inline footnote: literal `^[` in prose", () => {
+  it("escapes a literal `^[…]` in text so it stays text, byte-stable", async () => {
+    const d = doc(P(T("see ^[not a note] here")));
+    const md = convertProseMirrorToMarkdown(d);
+    // The opening `^[` is broken with a backslash so the tokenizer never fires.
+    expect(md).toBe("see ^\\[not a note] here");
+
+    const back = await markdownToProseMirror(md);
+    expect(findNode(back, "footnoteReference")).toBeUndefined();
+    expect(allText(back)).toBe("see ^[not a note] here");
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fail-open: unbalanced `^[` and empty `^[]` do not crash.
+// ---------------------------------------------------------------------------
+describe("inline footnote: fail-open", () => {
+  it("leaves an unbalanced `^[` as literal text, no crash", async () => {
+    const back = await markdownToProseMirror("dangling ^[ open bracket");
+    expect(findNode(back, "footnoteReference")).toBeUndefined();
+    expect(allText(back)).toContain("^[ open bracket");
+  });
+
+  it("treats `^[]` as a footnote with an empty body, no crash", async () => {
+    const back = await markdownToProseMirror("empty^[]");
+    const r = findNode(back, "footnoteReference");
+    const dfn = findNode(back, "footnoteDefinition");
+    expect(r).toBeDefined();
+    expect(dfn).toBeDefined();
+    expect(allText(dfn)).toBe("");
+    // Byte-stable: an empty-body footnote re-exports as `^[]`.
+    expect(convertProseMirrorToMarkdown(back)).toBe("empty^[]");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F1 (CRITICAL): DIFFERENT bodies must NEVER merge — dedup keys on exact text,
+// not a 32-bit hash (the old djb2 hash collided `"sgrs rj"` / `"a gtkfr"`).
+// ---------------------------------------------------------------------------
+describe("inline footnote: distinct bodies never merge (F1)", () => {
+  it("keeps the hash-colliding pair `sgrs rj` / `a gtkfr` as two distinct defs", async () => {
+    // These two DIFFERENT bodies hashed to the same fn-16myybs under djb2, which
+    // silently dropped the second body. With text-exact dedup they must survive
+    // as two separate definitions.
+    const d = doc(
+      P(T("x"), ref("fnA"), T(" y"), ref("fnB")),
+      list(def("fnA", P(T("sgrs rj"))), def("fnB", P(T("a gtkfr")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    expect(md).toBe("x^[sgrs rj] y^[a gtkfr]");
+
+    const back = await markdownToProseMirror(md);
+    const defs = findAll(back, "footnoteDefinition");
+    const refs = findAll(back, "footnoteReference");
+    // BOTH bodies survive as DISTINCT definitions.
+    expect(defs.length).toBe(2);
+    const bodies = defs.map(allText).sort();
+    expect(bodies).toEqual(["a gtkfr", "sgrs rj"]);
+    // Two refs, each pointing at a DIFFERENT def id.
+    expect(refs.length).toBe(2);
+    expect(refs[0].attrs.id).not.toBe(refs[1].attrs.id);
+    expect(new Set(defs.map((x: any) => x.attrs.id)).size).toBe(2);
+
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// F2 (CRITICAL): a body ending in `\` (or `\` before `]`) must survive `^[…]`.
+// Each must round-trip BYTE-STABLE across 3 iterations, footnote intact.
+// ---------------------------------------------------------------------------
+describe("inline footnote: raw backslash bodies survive (F2)", () => {
+  const cases: Array<{ name: string; body: string; expectMd: string }> = [
+    {
+      name: "trailing backslash (Windows path)",
+      body: "C:\\dir\\",
+      expectMd: "x^[C:\\\\dir\\\\]",
+    },
+    {
+      name: "backslash before a literal bracket",
+      body: "a \\] b",
+      expectMd: "x^[a \\\\\\] b]",
+    },
+    {
+      name: "regex with trailing backslash",
+      body: "re\\gex\\",
+      expectMd: "x^[re\\\\gex\\\\]",
+    },
+  ];
+  for (const { name, body, expectMd } of cases) {
+    it(`round-trips ${name} byte-stable x3 with the backslash preserved`, async () => {
+      const d = doc(P(T("x"), ref("fn1")), list(def("fn1", P(T(body)))));
+      let md = convertProseMirrorToMarkdown(d);
+      expect(md).toBe(expectMd);
+
+      // Three full iterations must all be byte-identical and keep the footnote.
+      for (let iter = 0; iter < 3; iter++) {
+        const back = await markdownToProseMirror(md);
+        const dfn = findNode(back, "footnoteDefinition");
+        expect(dfn).toBeDefined();
+        // The backslashes are preserved EXACTLY in the note body.
+        expect(allText(dfn)).toBe(body);
+        const md2 = convertProseMirrorToMarkdown(back);
+        expect(md2).toBe(md);
+        md = md2;
+      }
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// F4: assembleFootnotes must not emit a DUPLICATE <section data-footnotes> when
+// the HTML already carries one (a footnote list that landed in a column).
+// ---------------------------------------------------------------------------
+describe("inline footnote: no duplicate footnotes section (F4)", () => {
+  it("produces exactly one footnotesList when a column footnote is present", async () => {
+    const d = doc(
+      {
+        type: "columns",
+        content: [
+          { type: "column", attrs: { width: "50%" }, content: [P(T("c "), ref("fn1"))] },
+        ],
+      },
+      list(def("fn1", P(T("colnote")))),
+    );
+    const md = convertProseMirrorToMarkdown(d);
+    const back = await markdownToProseMirror(md);
+    // Exactly one assembled footnotes list, not two.
+    expect(findAll(back, "footnotesList").length).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// N1 (data-loss): NESTED inline footnotes must round-trip — the assembly pass
+// runs to a FIXED POINT so an inner `^[…]` spawned by parseInline is also
+// assigned an id, built into a def, and stripped (no dangling ref, no lost body).
+// ---------------------------------------------------------------------------
+describe("inline footnote: nested footnotes (N1)", () => {
+  it("keeps `^[outer ^[inner] tail]` as TWO defs, inner preserved, byte-stable", async () => {
+    const md1 = "text ^[outer ^[inner] tail] end";
+    const back = await markdownToProseMirror(md1);
+    const defs = findAll(back, "footnoteDefinition");
+    const refs = findAll(back, "footnoteReference");
+    // Two distinct definitions (outer + inner); two references.
+    expect(defs.length).toBe(2);
+    expect(refs.length).toBe(2);
+    expect(new Set(defs.map((d: any) => d.attrs.id)).size).toBe(2);
+    const bodies = defs.map(allText).sort();
+    expect(bodies).toEqual(["inner", "outer  tail"]);
+    // The OUTER definition body carries a footnoteReference to the inner def.
+    const outer = defs.find((d: any) => allText(d).includes("outer"));
+    const inner = defs.find((d: any) => allText(d) === "inner");
+    const nestedRef = findNode(outer, "footnoteReference");
+    expect(nestedRef).toBeDefined();
+    expect(nestedRef.attrs.id).toBe(inner.attrs.id);
+    // Byte-stable across two further iterations (md1 === md2 === md3).
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md1);
+    const md3 = convertProseMirrorToMarkdown(await markdownToProseMirror(md2));
+    expect(md3).toBe(md2);
+  });
+
+  it("round-trips a 3-level nest `^[a ^[b ^[c] d] e]` (three defs)", async () => {
+    const md1 = "z ^[a ^[b ^[c] d] e] z";
+    const back = await markdownToProseMirror(md1);
+    const defs = findAll(back, "footnoteDefinition");
+    expect(defs.length).toBe(3);
+    expect(new Set(defs.map((d: any) => d.attrs.id)).size).toBe(3);
+    expect(defs.map(allText).sort()).toEqual(["a  e", "b  d", "c"]);
+    const md2 = convertProseMirrorToMarkdown(back);
+    expect(md2).toBe(md1);
+    const md3 = convertProseMirrorToMarkdown(await markdownToProseMirror(md2));
+    expect(md3).toBe(md2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// N2: a generated id must never collide with an id already present in a REUSED
+// footnotes section (the counter is seeded past the max existing `fn-N`).
+// ---------------------------------------------------------------------------
+describe("inline footnote: generated ids never collide with a reused section (N2)", () => {
+  it("seeds the counter past an existing `fn-1` def in a legacy section", async () => {
+    // A legacy `<section data-footnotes>` (existing `fn-1`) reaches the body as
+    // raw HTML; the new inline `^[…]` must NOT be assigned `fn-1` too.
+    const md =
+      "text^[new note]\n\n" +
+      '<section data-footnotes><div data-footnote-def data-id="fn-1">' +
+      "<p>existing note</p></div></section>";
+    const back = await markdownToProseMirror(md);
+    const defs = findAll(back, "footnoteDefinition");
+    // Both notes survive as DISTINCT definitions in a SINGLE list.
+    expect(defs.length).toBe(2);
+    expect(new Set(defs.map((d: any) => d.attrs.id)).size).toBe(2);
+    expect(findAll(back, "footnotesList").length).toBe(1);
+    expect(defs.map(allText).sort()).toEqual(["existing note", "new note"]);
+    // The pre-existing id is preserved; the new one is seeded past it.
+    expect(defs.map((d: any) => d.attrs.id)).toContain("fn-1");
+    expect(defs.map((d: any) => d.attrs.id)).toContain("fn-2");
+  });
+});
-- 
2.52.0


From b7518524258d24c0ea02895d63dbb0e78de86c47 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 10:37:35 +0300
Subject: [PATCH 10/17] =?UTF-8?q?fix(prosemirror-markdown):=20converter=20?=
 =?UTF-8?q?inventory=20bugs=20=E2=80=94=20spoiler/link-title=20in=20raw-HT?=
 =?UTF-8?q?ML,=20contract=20test,=20codeCombined=20dead=20code=20(#293)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The four bugs found during the #293 HTML-emission inventory, fixed in the package:

1. Spoiler mark was silently lost in the raw-HTML path: inlineToHtml (columns /
   spanned cells) had no `case "spoiler"`, so spoilered text there dropped the
   mark on round-trip. Now emits `<span data-spoiler="true">` — the same form the
   top-level serializer uses and exactly what the schema's Spoiler mark parses.

2. Link `title` was dropped in the raw-HTML path: inlineToHtml's link case
   emitted `<a href>` without the title. The schema's link mark carries a
   `title` global attr (DocmostAttributes), so a titled link inside a column now
   round-trips via `<a href … title=…>`.

3. Serializer contract test: emoji/date/toc were flagged as possibly caseless
   inline atoms. Verified they exist in NEITHER the package schema NOR
   editor-ext, so no node handling is needed today. Added
   serializer-contract.test.ts, which derives every node type from the live
   schema (getSchema(docmostExtensions)) and asserts each has an explicit
   serializer `case` — all 45 current node types are covered and present, and a
   future node added without a case will fail this test loudly.

4. codeCombined dead code: `const codeCombined = false` was hardcoded, so every
   `codeCombined ? <html> : <markdown>` ternary always took the markdown branch.
   Removed the variable and the dead HTML-alternative branches (bold/italic/code/
   link/strike). Pure cleanup — output is byte-identical (goldens + full suite
   pass unchanged). The `hasCode` early-return (code excludes other marks) stays.

Tests: spoiler-inside-column and link-title-inside-column round-trips, the
serializer contract test + inline-atom non-empty behavioral checks.

package vitest: 657 passed; tsc clean. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/markdown-converter.ts             |  54 ++---
 .../test/serializer-contract.test.ts          | 194 ++++++++++++++++++
 2 files changed, 221 insertions(+), 27 deletions(-)
 create mode 100644 packages/prosemirror-markdown/test/serializer-contract.test.ts

diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 5a5521b3..dd928e14 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -432,39 +432,24 @@ export function convertProseMirrorToMarkdown(content: any): string {
             textContent = `\`${textContent}\``;
             return textContent;
           }
-          const codeCombined = false;
           for (const mark of node.marks) {
             switch (mark.type) {
               case "bold":
-                textContent = codeCombined
-                  ? `<strong>${textContent}</strong>`
-                  : `**${textContent}**`;
+                textContent = `**${textContent}**`;
                 break;
               case "italic":
-                textContent = codeCombined
-                  ? `<em>${textContent}</em>`
-                  : `*${textContent}*`;
+                textContent = `*${textContent}*`;
                 break;
               case "code":
-                // When combined with another mark, wrap as <code> so the
-                // surrounding HTML marks can nest around it; otherwise use the
-                // plain backtick span.
-                textContent = codeCombined
-                  ? `<code>${textContent}</code>`
-                  : `\`${textContent}\``;
+                // A `code` run already returned above (hasCode early return), so
+                // this branch is only reached for a non-code run that somehow
+                // still lists `code`; emit the plain backtick span.
+                textContent = `\`${textContent}\``;
                 break;
               case "link": {
                 const href = mark.attrs?.href || "";
                 const title = mark.attrs?.title;
-                if (codeCombined) {
-                  // Emit an HTML anchor so it can wrap the nested <code>.
-                  const safeHref = escapeAttr(href);
-                  if (title) {
-                    textContent = `<a href="${safeHref}" title="${escapeAttr(String(title))}">${textContent}</a>`;
-                  } else {
-                    textContent = `<a href="${safeHref}">${textContent}</a>`;
-                  }
-                } else if (title) {
+                if (title) {
                   // Emit the optional markdown link title; escape an embedded
                   // double-quote so it cannot terminate the title string early.
                   const safeTitle = String(title).replace(/"/g, '\\"');
@@ -475,9 +460,7 @@ export function convertProseMirrorToMarkdown(content: any): string {
                 break;
               }
               case "strike":
-                textContent = codeCombined
-                  ? `<s>${textContent}</s>`
-                  : `~~${textContent}~~`;
+                textContent = `~~${textContent}~~`;
                 break;
               case "underline":
                 textContent = `<u>${textContent}</u>`;
@@ -1153,9 +1136,19 @@ export function convertProseMirrorToMarkdown(content: any): string {
             case "superscript":
               t = `<sup>${t}</sup>`;
               break;
-            case "link":
-              t = `<a href="${escapeAttr(mark.attrs?.href || "")}">${t}</a>`;
+            case "link": {
+              // Mirror the top-level link path: emit the optional `title` too
+              // (the schema's link mark carries a `title` attr — see
+              // DocmostAttributes link globals — so <a title> round-trips). A
+              // link with a title inside a column/spanned cell would otherwise
+              // drop it on re-import.
+              const linkTitle = mark.attrs?.title;
+              const titleAttr = linkTitle
+                ? ` title="${escapeAttr(String(linkTitle))}"`
+                : "";
+              t = `<a href="${escapeAttr(mark.attrs?.href || "")}"${titleAttr}>${t}</a>`;
               break;
+            }
             case "highlight":
               t = mark.attrs?.color
                 ? `<mark style="background-color: ${escapeAttr(mark.attrs.color)}">${t}</mark>`
@@ -1165,6 +1158,13 @@ export function convertProseMirrorToMarkdown(content: any): string {
               if (mark.attrs?.color)
                 t = `<span style="color: ${escapeAttr(mark.attrs.color)}">${t}</span>`;
               break;
+            case "spoiler":
+              // Emit the same raw inline HTML the top-level path uses. The
+              // schema's Spoiler mark parses span[data-spoiler] back on import,
+              // so a spoiler inside a column/spanned cell survives the round
+              // trip (without this case the mark was silently lost here).
+              t = `<span data-spoiler="true">${t}</span>`;
+              break;
             case "comment":
               // Inline comment anchor inside a raw-HTML container (columns /
               // spanned table cells), so commented text there also round-trips.
diff --git a/packages/prosemirror-markdown/test/serializer-contract.test.ts b/packages/prosemirror-markdown/test/serializer-contract.test.ts
new file mode 100644
index 00000000..4ec993d7
--- /dev/null
+++ b/packages/prosemirror-markdown/test/serializer-contract.test.ts
@@ -0,0 +1,194 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+import { getSchema } from "@tiptap/core";
+
+import { docmostExtensions } from "../src/lib/docmost-schema.js";
+import { convertProseMirrorToMarkdown } from "../src/lib/markdown-converter.js";
+import { markdownToProseMirror } from "../src/lib/markdown-to-prosemirror.js";
+
+/**
+ * SERIALIZER-CONTRACT GUARD (#293 canon #inventory, bug 3).
+ *
+ * The markdown serializer (`convertProseMirrorToMarkdown`) dispatches on
+ * `node.type` in a big `switch`. Any node type that reaches the `default` arm
+ * is NOT serialized as itself — it silently collapses to its children's text
+ * (or, for an ATOM node with no children, to the empty string). The canon
+ * inventory flagged exactly this class: had the editor schema declared inline
+ * atoms like `emoji`/`date`/`toc`, a document could carry one and the converter
+ * would drop it with no case and no error (a git-sync data-loss on the data
+ * path).
+ *
+ * INVARIANT: every node type declared in the package schema
+ * (`docmostExtensions`) has an EXPLICIT serializer case. This test derives the
+ * node-type set from the live schema and asserts a `case "<name>":` exists in
+ * the serializer source for each. A future node added to the schema WITHOUT a
+ * serializer case (the emoji/date/toc failure mode) fails here loudly.
+ *
+ * We scan the SOURCE (not behavioral output) because it is the only formulation
+ * that reliably catches a missing case for EVERY node kind: a missing case on a
+ * *container* node still emits its children via `default` (non-empty output, so
+ * a behavioral non-empty check would pass while structure was lost), whereas the
+ * source scan catches the drop regardless of whether the node is an atom or a
+ * container. A complementary behavioral check for the atom case follows.
+ */
+
+const SERIALIZER_SOURCE = readFileSync(
+  fileURLToPath(new URL("../src/lib/markdown-converter.ts", import.meta.url)),
+  "utf8",
+);
+
+function schemaNodeNames(): string[] {
+  const schema = getSchema(docmostExtensions as never);
+  return Object.keys(schema.nodes).sort();
+}
+
+describe("serializer contract: every schema node type has a serializer case", () => {
+  const nodeNames = schemaNodeNames();
+
+  it("covers a known, non-trivial set of node types", () => {
+    // Sanity: the schema really does expose the full Docmost node surface, so
+    // this test is not vacuously iterating an empty/tiny list.
+    expect(nodeNames.length).toBeGreaterThanOrEqual(40);
+    // A representative atom that would silently drop without a case.
+    expect(nodeNames).toContain("status");
+    expect(nodeNames).toContain("mention");
+  });
+
+  for (const name of schemaNodeNames()) {
+    it(`serializer has an explicit case for node type "${name}"`, () => {
+      // Node names and mark names never collide, so a `case "<node>"` anywhere
+      // in the serializer is that node's case (marks have distinct names).
+      const pattern = new RegExp(`case "${name}"\\s*:`);
+      expect(
+        pattern.test(SERIALIZER_SOURCE),
+        `Node type "${name}" is declared in the package schema but has no ` +
+          `case "${name}": in convertProseMirrorToMarkdown — it would fall ` +
+          `through to the default arm and be silently dropped on git-sync ` +
+          `export. Add a lossless serializer case (see mention/status).`,
+      ).toBe(true);
+    });
+  }
+});
+
+/**
+ * Behavioral complement: an INLINE ATOM with no serializer case collapses to
+ * "" via the default arm (exactly the emoji/date/toc risk). Prove that the two
+ * inline atoms the schema actually declares (mention, status) do NOT vanish —
+ * i.e. the default-drop path is not reached for them. This is the runtime shape
+ * the source-scan invariant protects.
+ */
+describe("serializer contract: inline atoms are not dropped to empty", () => {
+  const P = (...c: any[]) => ({ type: "paragraph", content: c });
+  const doc = (...c: any[]) => ({ type: "doc", content: c });
+
+  it("mention serializes to non-empty output", () => {
+    const md = convertProseMirrorToMarkdown(
+      doc(P({ type: "mention", attrs: { id: "u1", label: "Bob" } })),
+    );
+    expect(md.trim()).not.toBe("");
+    expect(md).toContain('data-type="mention"');
+  });
+
+  it("status serializes to non-empty output", () => {
+    const md = convertProseMirrorToMarkdown(
+      doc(P({ type: "status", attrs: { text: "Done", color: "green" } })),
+    );
+    expect(md.trim()).not.toBe("");
+    expect(md).toContain('data-type="status"');
+  });
+});
+
+/**
+ * Raw-HTML path (columns) round-trips for the two marks fixed alongside the
+ * contract test. A column renders its inline content via `inlineToHtml`, whose
+ * mark switch previously lacked a `spoiler` case (bug 1) and dropped a link's
+ * `title` (bug 2).
+ */
+
+// Walk a ProseMirror tree and return the first text run whose marks include the
+// given mark type, or undefined.
+function findMarkedText(n: any, markType: string): any {
+  if (!n || typeof n !== "object") return undefined;
+  if (
+    n.type === "text" &&
+    Array.isArray(n.marks) &&
+    n.marks.some((m: any) => m?.type === markType)
+  ) {
+    return n;
+  }
+  if (Array.isArray(n.content)) {
+    for (const c of n.content) {
+      const hit = findMarkedText(c, markType);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+describe("raw-HTML path (columns): spoiler + link title round-trip", () => {
+  const P = (...c: any[]) => ({ type: "paragraph", content: c });
+  const doc = (...c: any[]) => ({ type: "doc", content: c });
+  const column = (...c: any[]) => ({
+    type: "column",
+    attrs: { width: "50%" },
+    content: c,
+  });
+
+  it("bug 1: a spoiler mark inside a column survives the round trip", async () => {
+    const original = doc({
+      type: "columns",
+      content: [
+        column(P({ type: "text", text: "hidden", marks: [{ type: "spoiler" }] })),
+        column(P({ type: "text", text: "plain" })),
+      ],
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    // The raw-HTML path must emit the schema's spoiler span (RED before bug 1
+    // fix: inlineToHtml had no spoiler case, so the mark was dropped and the
+    // text emitted bare).
+    expect(md).toContain('data-spoiler="true"');
+    expect(md).toContain("<span data-spoiler=\"true\">hidden</span>");
+
+    const back = await markdownToProseMirror(md);
+    const spoilered = findMarkedText(back, "spoiler");
+    expect(spoilered).toBeDefined();
+    expect(spoilered.text).toBe("hidden");
+  });
+
+  it("bug 2: a link with a title inside a column keeps its title", async () => {
+    const original = doc({
+      type: "columns",
+      content: [
+        column(
+          P({
+            type: "text",
+            text: "site",
+            marks: [
+              {
+                type: "link",
+                attrs: { href: "https://example.com", title: "Example Title" },
+              },
+            ],
+          }),
+        ),
+        column(P({ type: "text", text: "plain" })),
+      ],
+    });
+    const md = convertProseMirrorToMarkdown(original);
+    // The raw-HTML anchor must carry the title (RED before bug 2 fix:
+    // inlineToHtml emitted <a href> with no title).
+    expect(md).toContain('title="Example Title"');
+    expect(md).toContain('href="https://example.com"');
+
+    const back = await markdownToProseMirror(md);
+    const linked = findMarkedText(back, "link");
+    expect(linked).toBeDefined();
+    const linkMark = linked.marks.find((m: any) => m.type === "link");
+    expect(linkMark.attrs?.href).toBe("https://example.com");
+    // The schema's link mark carries `title`; it must round-trip through the
+    // raw-HTML column path.
+    expect(linkMark.attrs?.title).toBe("Example Title");
+  });
+});
-- 
2.52.0


From 124f5a45a29e36a3d03c4770cb04ad575893848e Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 11:16:09 +0300
Subject: [PATCH 11/17] refactor(mcp): consume @docmost/prosemirror-markdown,
 drop the drifted converter copy (#293/#326 step 5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mcp had its OWN drifted copy of the converter (markdown-converter.ts ~900 lines,
docmost-schema.ts ~1270 lines, markdown-document.ts) — older than the shared
package, missing the git-sync fixes AND the #293 canon. This switches mcp's
converter CORE to @docmost/prosemirror-markdown, so mcp jumps straight to the
canonical format and the drift-generating second copy is gone.

- markdown-converter.ts / markdown-document.ts / docmost-schema.ts become thin
  re-export shims of the package (convertProseMirrorToMarkdown, the docmost:meta
  envelope, docmostExtensions + docmostSchema=getSchema(docmostExtensions)). The
  mcp-only helpers clampCalloutType/sanitizeCssColor are preserved verbatim in
  the schema shim (the package doesn't expose them via its barrel). ~2170 lines
  of the drifted converter/schema bodies deleted.
- collaboration.ts drops its own ~360-line marked pipeline (preprocessCallouts,
  bridgeTaskLists, extractFootnotes, the footnoteRef extension) and re-points to
  the package's markdownToProseMirror, keeping markdownToProseMirrorCanonical and
  all the yjs/collab write glue. footnote-lex/analyze doc comments updated (they
  now describe advisory legacy-syntax diagnostics, not an importer).

Schema parity verified: the package schema is a strict SUPERSET of mcp's old
schema — every node and attr mcp declared is present (the package only adds
status/pageEmbed/transclusion*/subpages.recursive/etc.), so nothing is silently
dropped on the switch. The switch actually FIXES two pre-existing mcp data-loss
bugs its own tests documented: htmlEmbed and pageBreak now round-trip (were
dropped by the old mcp converter).

Footnotes: the package assembles inline ^[body] footnotes on import (sequential
fn-N ids, identical bodies merged), so mcp's canonicalizeFootnotes is now an
idempotent no-op after it (verified). Legacy reference footnotes [^id]/[^id]:
are inert literal text (canon #2 no-backward-compat) — lossless, the text
survives verbatim.

Build hygiene: packages/mcp/build/ is now gitignored and untracked, matching the
git-sync/prosemirror-markdown convention (private package, rebuilt in CI/Docker,
so src and prod can never silently diverge). This also removes a dead untracked
build/_vendored_editor_ext/ artifact that a broad `git add` would otherwise
commit.

Dependency: packages/mcp/package.json gains @docmost/prosemirror-markdown
(workspace:*); pnpm-lock.yaml gets the matching link importer (mirrors git-sync).

mcp tests updated deliberately to the canonical forms (highlight ==, math $…$,
image ![](src)<!--img-->, drawio/media discriminators, subpages/pageBreak
comments, textAlign, inline ^[…] footnotes) with strict assertions; 4 structural
safety-net round-trip tests added.

mcp: node --test 454 passed; tsc clean. package: 657 passed. git-sync: 268 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |    5 +
 packages/mcp/build/client.js                  | 2969 -----------------
 packages/mcp/build/http.js                    |  133 -
 packages/mcp/build/index.js                   |  801 -----
 packages/mcp/build/lib/auth-utils.js          |   92 -
 packages/mcp/build/lib/collaboration.js       |  743 -----
 packages/mcp/build/lib/comment-anchor.js      |  371 --
 packages/mcp/build/lib/diff.js                |  423 ---
 packages/mcp/build/lib/docmost-schema.js      | 1172 -------
 packages/mcp/build/lib/filters.js             |   92 -
 packages/mcp/build/lib/footnote-analyze.js    |  101 -
 packages/mcp/build/lib/footnote-authoring.js  |   88 -
 .../mcp/build/lib/footnote-canonicalize.js    |  215 --
 packages/mcp/build/lib/footnote-lex.js        |   55 -
 packages/mcp/build/lib/internal-file-urls.js  |  110 -
 packages/mcp/build/lib/json-edit.js           |  393 ---
 packages/mcp/build/lib/markdown-converter.js  |  835 -----
 packages/mcp/build/lib/markdown-document.js   |  104 -
 packages/mcp/build/lib/node-ops.js            |  821 -----
 packages/mcp/build/lib/page-lock.js           |   31 -
 packages/mcp/build/lib/parse-node-arg.js      |   15 -
 packages/mcp/build/lib/text-normalize.js      |  108 -
 packages/mcp/build/lib/transforms.js          |  631 ----
 packages/mcp/build/lib/tree.js                |   89 -
 packages/mcp/build/stdio.js                   |   40 -
 packages/mcp/build/tool-specs.js              |  322 --
 packages/mcp/package.json                     |    1 +
 packages/mcp/src/lib/collaboration.ts         |  405 +--
 packages/mcp/src/lib/docmost-schema.ts        | 1262 +------
 packages/mcp/src/lib/footnote-analyze.ts      |   11 +-
 packages/mcp/src/lib/footnote-lex.ts          |   16 +-
 packages/mcp/src/lib/markdown-converter.ts    |  911 +----
 packages/mcp/src/lib/markdown-document.ts     |  145 +-
 packages/mcp/test/unit/collaboration.test.mjs |   58 +-
 .../test/unit/docmost-md-roundtrip.test.mjs   |    8 +-
 .../test/unit/footnote-canonicalize.test.mjs  |   29 +-
 packages/mcp/test/unit/footnotes.test.mjs     |   61 +-
 .../mcp/test/unit/markdown-converter.test.mjs |   37 +-
 .../test/unit/media-roundtrip-attrs.test.mjs  |   22 +-
 .../mcp/test/unit/media-roundtrip.test.mjs    |   49 +-
 packages/mcp/test/unit/roundtrip.test.mjs     |   64 +
 pnpm-lock.yaml                                |    3 +
 42 files changed, 313 insertions(+), 13528 deletions(-)
 delete mode 100644 packages/mcp/build/client.js
 delete mode 100644 packages/mcp/build/http.js
 delete mode 100644 packages/mcp/build/index.js
 delete mode 100644 packages/mcp/build/lib/auth-utils.js
 delete mode 100644 packages/mcp/build/lib/collaboration.js
 delete mode 100644 packages/mcp/build/lib/comment-anchor.js
 delete mode 100644 packages/mcp/build/lib/diff.js
 delete mode 100644 packages/mcp/build/lib/docmost-schema.js
 delete mode 100644 packages/mcp/build/lib/filters.js
 delete mode 100644 packages/mcp/build/lib/footnote-analyze.js
 delete mode 100644 packages/mcp/build/lib/footnote-authoring.js
 delete mode 100644 packages/mcp/build/lib/footnote-canonicalize.js
 delete mode 100644 packages/mcp/build/lib/footnote-lex.js
 delete mode 100644 packages/mcp/build/lib/internal-file-urls.js
 delete mode 100644 packages/mcp/build/lib/json-edit.js
 delete mode 100644 packages/mcp/build/lib/markdown-converter.js
 delete mode 100644 packages/mcp/build/lib/markdown-document.js
 delete mode 100644 packages/mcp/build/lib/node-ops.js
 delete mode 100644 packages/mcp/build/lib/page-lock.js
 delete mode 100644 packages/mcp/build/lib/parse-node-arg.js
 delete mode 100644 packages/mcp/build/lib/text-normalize.js
 delete mode 100644 packages/mcp/build/lib/transforms.js
 delete mode 100644 packages/mcp/build/lib/tree.js
 delete mode 100755 packages/mcp/build/stdio.js
 delete mode 100644 packages/mcp/build/tool-specs.js

diff --git a/.gitignore b/.gitignore
index 6db827eb..0f97bb35 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,11 @@ packages/git-sync/build/
 # never committed, so src/ and prod can never silently diverge).
 packages/prosemirror-markdown/build/
 
+# mcp compiled output (built in CI/Docker via `pnpm build`, never committed, so
+# src/ and prod can never silently diverge). Matches the git-sync/prosemirror-
+# markdown convention; the package is private and rebuilt at deploy.
+packages/mcp/build/
+
 # Logs
 logs
 *.log
diff --git a/packages/mcp/build/client.js b/packages/mcp/build/client.js
deleted file mode 100644
index 1b4b31d5..00000000
--- a/packages/mcp/build/client.js
+++ /dev/null
@@ -1,2969 +0,0 @@
-import FormData from "form-data";
-import axios from "axios";
-import { basename, extname } from "path";
-import { filterWorkspace, filterSpace, filterPage, filterComment, filterSearchResult, } from "./lib/filters.js";
-import { HocuspocusProvider } from "@hocuspocus/provider";
-import { TiptapTransformer } from "@hocuspocus/transformer";
-import * as Y from "yjs";
-import WebSocket from "ws";
-import { convertProseMirrorToMarkdown } from "./lib/markdown-converter.js";
-import { collectInternalFileNodes, normalizeFileUrl, resolveInternalFilePath, } from "./lib/internal-file-urls.js";
-import { updatePageContentRealtime, replacePageContent, markdownToProseMirror, markdownToProseMirrorCanonical, mutatePageContent, buildCollabWsUrl, assertYjsEncodable, applyDocToFragment, } from "./lib/collaboration.js";
-import { footnoteWarningsField } from "./lib/footnote-analyze.js";
-import { buildPageTree } from "./lib/tree.js";
-import { serializeDocmostMarkdown, parseDocmostMarkdown, } from "./lib/markdown-document.js";
-import { replaceNodeById, deleteNodeById, assertUnambiguousMatch, insertNodeRelative, buildOutline, getNodeByRef, readTable, insertTableRow, deleteTableRow, updateTableCell, } from "./lib/node-ops.js";
-import { withPageLock } from "./lib/page-lock.js";
-import { applyTextEdits, } from "./lib/json-edit.js";
-import { getCollabToken, performLogin } from "./lib/auth-utils.js";
-import { diffDocs, summarizeChange } from "./lib/diff.js";
-import { applyAnchorInDoc, canAnchorInDoc, countAnchorMatches, getAnchoredText, } from "./lib/comment-anchor.js";
-import { blockText, walk, getList, insertMarkerAfter, setCalloutRange, noteItem, mdToInlineNodes, commentsToFootnotes, canonicalizeFootnotes, insertInlineFootnote, } from "./lib/transforms.js";
-import vm from "node:vm";
-// Supported image types, kept as two lookup tables so both a local file
-// extension and a remote Content-Type can be mapped to the same canonical set.
-const EXT_TO_MIME = {
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-    ".svg": "image/svg+xml",
-};
-const MIME_TO_EXT = {
-    "image/png": ".png",
-    "image/jpeg": ".jpg",
-    "image/gif": ".gif",
-    "image/webp": ".webp",
-    "image/svg+xml": ".svg",
-};
-// Canonical UUID shape (versions 1–8, matching the `uuid` package's `validate`
-// that the server's isValidUUID uses). page.repo.ts treats any non-UUID pageId
-// as a slugId, so the MCP detects a UUID locally and skips a /pages/info
-// round-trip in resolvePageId. A 10-char nanoid slugId never contains dashes,
-// so it can never be misread as a UUID here.
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-function isUuid(value) {
-    return typeof value === "string" && UUID_RE.test(value);
-}
-export class DocmostClient {
-    client;
-    token = null;
-    apiUrl;
-    // email/password are only set on the service-account (credentials) variant;
-    // null on the getToken variant (where there are no credentials to log in with).
-    email = null;
-    password = null;
-    // Per-user token provider. When set, login() calls it to obtain a BARE access
-    // JWT instead of performLogin, and the 401/403 re-auth path re-calls it.
-    getTokenFn = null;
-    // Optional collab-token provider. When set, getCollabTokenWithReauth() returns
-    // its token instead of calling POST /auth/collab-token; on a 401/403 it is
-    // re-invoked once. Used by the internal agent to carry signed provenance.
-    getCollabTokenFn = null;
-    // Optional blob-sandbox sink for the stash tool. Null when not configured.
-    sandboxPut = null;
-    // Optional probes paired with the sink. `has` lets stashPage detect a blob
-    // FIFO-evicted by a LATER put in the same stash; `evict` lets it free this
-    // op's image blobs if the final doc put throws. Null when the sink omits them.
-    sandboxHas = null;
-    sandboxEvict = null;
-    // In-flight login dedup: when the token expires, the 401 interceptor,
-    // ensureAuthenticated, getCollabTokenWithReauth and the two multipart retries
-    // can all call login() at once. Memoizing a single promise collapses that
-    // thundering herd into ONE /auth/login request that everyone awaits.
-    loginPromise = null;
-    // Canonical-UUID cache for resolvePageId: maps an agent-supplied slugId to the
-    // page's canonical UUID, so repeated collab edits on the same page do not
-    // re-fetch /pages/info. A UUID input short-circuits before this cache (see
-    // resolvePageId), so only slugId->uuid entries are stored/read here.
-    pageIdCache = new Map();
-    constructor(configOrBaseURL, email, password) {
-        // Normalize the legacy positional form into the object union.
-        const config = typeof configOrBaseURL === "string"
-            ? { apiUrl: configOrBaseURL, email: email, password: password }
-            : configOrBaseURL;
-        this.apiUrl = config.apiUrl;
-        if ("getToken" in config) {
-            // Token variant: carry the user's JWT via getToken; no credentials, so
-            // login() must never call performLogin (there is nothing to log in with).
-            this.getTokenFn = config.getToken;
-        }
-        else {
-            // Service-account variant: behaves exactly as before (performLogin).
-            this.email = config.email;
-            this.password = config.password;
-        }
-        // Optional, available to both variants. When present, content mutations get
-        // their collab token from here instead of POST /auth/collab-token.
-        if (config.getCollabToken) {
-            this.getCollabTokenFn = config.getCollabToken;
-        }
-        if (config.sandbox) {
-            this.sandboxPut = config.sandbox.put;
-            this.sandboxHas = config.sandbox.has ?? null;
-            this.sandboxEvict = config.sandbox.evict ?? null;
-        }
-        this.client = axios.create({
-            baseURL: this.apiUrl,
-            // Default request timeout so a hung connection cannot wedge a per-page
-            // lock or block the server indefinitely. Multipart uploads override this
-            // with a longer per-request timeout.
-            timeout: 30000,
-            headers: {
-                "Content-Type": "application/json",
-            },
-        });
-        // Re-authenticate transparently on a 401/403 once: the JWT authToken can
-        // expire while the server is long-running, after which every cached-token
-        // request would otherwise fail until a manual restart. On such a response,
-        // clear the stale token, perform a fresh login, and replay the original
-        // request exactly once (guarded by config._retry to avoid infinite loops;
-        // the login request itself is never retried).
-        this.client.interceptors.response.use((response) => response, async (error) => {
-            const config = error.config;
-            const status = error.response?.status;
-            const isAuthError = status === 401 || status === 403;
-            const isLoginRequest = typeof config?.url === "string" && config.url.includes("/auth/login");
-            if (config && isAuthError && !config._retry && !isLoginRequest) {
-                config._retry = true;
-                // Drop the stale token + Authorization header before re-login.
-                this.token = null;
-                delete this.client.defaults.headers.common["Authorization"];
-                try {
-                    await this.login();
-                }
-                catch (loginError) {
-                    // Re-login failed: surface the original error to the caller.
-                    return Promise.reject(error);
-                }
-                // Re-issue the original request with the freshly minted Bearer token.
-                // Read it from the default header that login() just set, not from
-                // this.token, to avoid a theoretical "Bearer null" if this.token was
-                // cleared between login() resolving and this point.
-                config.headers = config.headers || {};
-                config.headers["Authorization"] =
-                    this.client.defaults.headers.common["Authorization"];
-                return this.client.request(config);
-            }
-            return Promise.reject(error);
-        });
-    }
-    /** Application base URL (API URL without the /api suffix). */
-    get appUrl() {
-        return this.apiUrl.replace(/\/api\/?$/, "");
-    }
-    async login() {
-        // Reuse an in-flight login if one is already running so concurrent callers
-        // share a single token fetch instead of each issuing their own.
-        if (!this.loginPromise) {
-            // Token variant: re-fetch a BARE JWT via getToken() (there are no
-            // credentials to log in with — on a 401/403 the interceptor below calls
-            // login() again, which re-invokes getToken()). Credentials variant:
-            // performLogin against /auth/login exactly as before.
-            const fetchToken = this.getTokenFn
-                ? this.getTokenFn()
-                : performLogin(this.apiUrl, this.email, this.password);
-            this.loginPromise = fetchToken
-                .then((token) => {
-                // Guard against an empty/invalid token (e.g. a getToken provider that
-                // resolves to "" or null): without this an empty token would set a
-                // literal "Authorization: Bearer null"/"Bearer " header and every
-                // request would 401 with a confusing error. Fail loudly instead.
-                if (typeof token !== "string" || token.length === 0) {
-                    throw new Error("getToken returned an empty token");
-                }
-                this.token = token;
-                this.client.defaults.headers.common["Authorization"] =
-                    `Bearer ${token}`;
-            })
-                .finally(() => {
-                this.loginPromise = null;
-            });
-        }
-        return this.loginPromise;
-    }
-    async ensureAuthenticated() {
-        if (!this.token) {
-            await this.login();
-        }
-    }
-    /**
-     * Fetch a collaboration token, transparently re-authenticating once on a
-     * 401/403. getCollabToken() uses bare axios internally, so it is NOT covered
-     * by this.client's response interceptor; this helper replicates that
-     * behaviour for collab-token requests: ensure a token, try once, and on an
-     * expired-token auth error perform a fresh login and retry exactly once.
-     */
-    async getCollabTokenWithReauth() {
-        // Collab-token PROVIDER path: when a getCollabToken provider was supplied
-        // (the internal agent's provenance collab token), use it instead of the
-        // REST /auth/collab-token endpoint. Re-invoke it once on a 401/403 (e.g. the
-        // signed token expired between content mutations in a long agent turn).
-        if (this.getCollabTokenFn) {
-            try {
-                const token = await this.getCollabTokenFn();
-                if (typeof token !== "string" || token.length === 0) {
-                    throw new Error("getCollabToken returned an empty token");
-                }
-                return token;
-            }
-            catch (e) {
-                const axiosStatus = axios.isAxiosError(e)
-                    ? e.response?.status
-                    : undefined;
-                const attachedStatus = e?.status;
-                const isAuthError = axiosStatus === 401 ||
-                    axiosStatus === 403 ||
-                    attachedStatus === 401 ||
-                    attachedStatus === 403;
-                if (isAuthError) {
-                    const token = await this.getCollabTokenFn();
-                    if (typeof token !== "string" || token.length === 0) {
-                        throw new Error("getCollabToken returned an empty token");
-                    }
-                    return token;
-                }
-                throw e;
-            }
-        }
-        await this.ensureAuthenticated();
-        try {
-            return await getCollabToken(this.apiUrl, this.token);
-        }
-        catch (e) {
-            // getCollabToken wraps the AxiosError in a plain Error but attaches the
-            // HTTP status as `.status`, so detect an auth failure via either the raw
-            // AxiosError shape OR the attached status.
-            const axiosStatus = axios.isAxiosError(e)
-                ? e.response?.status
-                : undefined;
-            const attachedStatus = e?.status;
-            const isAuthError = axiosStatus === 401 ||
-                axiosStatus === 403 ||
-                attachedStatus === 401 ||
-                attachedStatus === 403;
-            if (isAuthError) {
-                await this.login();
-                return await getCollabToken(this.apiUrl, this.token);
-            }
-            throw e;
-        }
-    }
-    /**
-     * Connect to the collaboration websocket, read the live doc, apply
-     * `transform`, write the result, and wait for the server to persist it —
-     * WITHOUT acquiring the per-page lock.
-     *
-     * This mirrors collaboration.mutatePageContent EXCEPT that it does not call
-     * withPageLock. It exists solely so replaceImage can hold ONE withPageLock
-     * across its scan -> upload -> write sequence: the per-page mutex is NOT
-     * reentrant, so calling the normal (self-locking) mutatePageContent inside an
-     * outer withPageLock for the same pageId would deadlock. The caller MUST hold
-     * the page lock for the whole operation; this helper assumes that invariant.
-     *
-     * `transform` receives the live ProseMirror doc and returns the NEW full doc
-     * to write, or `null` to abort with no write. Errors thrown by `transform`
-     * propagate to the caller.
-     *
-     * Resolves a `MutationResult { doc, verify }` mirroring mutatePageContent, so
-     * every content mutator (including replaceImage) can return a verifiable
-     * change report. The report is computed AFTER the atomic read->write and
-     * never throws.
-     */
-    mutateLiveContentUnlocked(pageId, collabToken, transform) {
-        const CONNECT_TIMEOUT_MS = 25000;
-        const PERSIST_TIMEOUT_MS = 20000;
-        const ydoc = new Y.Doc();
-        const wsUrl = buildCollabWsUrl(this.apiUrl);
-        return new Promise((resolve, reject) => {
-            let provider;
-            let applied = false; // onSynced may fire again on reconnect — apply once.
-            let settled = false;
-            let connectionLost = false;
-            let connectTimer;
-            let persistTimer;
-            let unsyncedHandler;
-            // The verifiable result resolved on every success/abort path. Set on abort
-            // (no-op report) and after a real write (computed change report).
-            let mutationResult;
-            const cleanup = () => {
-                if (connectTimer)
-                    clearTimeout(connectTimer);
-                if (persistTimer)
-                    clearTimeout(persistTimer);
-                if (provider) {
-                    if (unsyncedHandler) {
-                        try {
-                            provider.off("unsyncedChanges", unsyncedHandler);
-                        }
-                        catch (err) { }
-                    }
-                    try {
-                        provider.destroy();
-                    }
-                    catch (err) { }
-                }
-            };
-            const finish = (err, value) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                if (err)
-                    reject(err);
-                else
-                    resolve(value);
-            };
-            connectTimer = setTimeout(() => {
-                finish(new Error("Connection timeout to collaboration server"));
-            }, CONNECT_TIMEOUT_MS);
-            const waitForPersistence = () => {
-                if (settled)
-                    return;
-                if (!provider) {
-                    finish(new Error("collab provider gone before persistence"));
-                    return;
-                }
-                if (provider.unsyncedChanges === 0) {
-                    finish(null, mutationResult);
-                    return;
-                }
-                persistTimer = setTimeout(() => {
-                    finish(new Error("Timeout waiting for collaboration server to persist the update"));
-                }, PERSIST_TIMEOUT_MS);
-                unsyncedHandler = (data) => {
-                    if (data.number === 0 && !connectionLost) {
-                        finish(null, mutationResult);
-                    }
-                };
-                provider.on("unsyncedChanges", unsyncedHandler);
-            };
-            provider = new HocuspocusProvider({
-                url: wsUrl,
-                name: `page.${pageId}`,
-                document: ydoc,
-                token: collabToken,
-                // @ts-ignore - Required for Node.js environment
-                WebSocketPolyfill: WebSocket,
-                onDisconnect: () => {
-                    connectionLost = true;
-                    finish(new Error("Collaboration connection closed before the update was persisted/synced"));
-                },
-                onClose: () => {
-                    connectionLost = true;
-                    finish(new Error("Collaboration connection closed before the update was persisted/synced"));
-                },
-                onSynced: () => {
-                    if (applied || settled)
-                        return;
-                    applied = true;
-                    // CRITICAL: keep everything between reading and writing the live doc
-                    // synchronous (no await) so no remote update can interleave.
-                    let newDoc;
-                    let beforeDoc;
-                    try {
-                        let liveDoc = TiptapTransformer.fromYdoc(ydoc, "default");
-                        if (!liveDoc ||
-                            typeof liveDoc !== "object" ||
-                            !Array.isArray(liveDoc.content)) {
-                            liveDoc = { type: "doc", content: [] };
-                        }
-                        // Snapshot the before-doc for the change report (safe deep clone).
-                        beforeDoc = JSON.parse(JSON.stringify(liveDoc));
-                        newDoc = transform(liveDoc);
-                        if (newDoc == null) {
-                            // Transform aborted — write nothing, return the live doc with a
-                            // no-op change report.
-                            mutationResult = {
-                                doc: liveDoc,
-                                verify: {
-                                    changed: false,
-                                    textInserted: 0,
-                                    textDeleted: 0,
-                                    blocksChanged: 0,
-                                    marks: {},
-                                    summary: "no changes (transform aborted)",
-                                },
-                            };
-                            finish(null, mutationResult);
-                            return;
-                        }
-                        // Structural diff into the live fragment (issue #152), mirroring
-                        // the main write path: preserves the Yjs ids of unchanged nodes so
-                        // an open editor's cursor is not yanked to the end of the document.
-                        // The previous destructive rewrite (delete-all + applyUpdate of a
-                        // fresh Y.Doc) discarded every node id, so replaceImage — the only
-                        // caller of this method — still reproduced the #152 cursor jump
-                        // (#164). applyDocToFragment runs its own atomic `transact`.
-                        applyDocToFragment(ydoc, newDoc);
-                    }
-                    catch (e) {
-                        finish(e instanceof Error ? e : new Error(String(e)));
-                        return;
-                    }
-                    // Compute the verifiable change report AFTER the transact write: it
-                    // only needs the JSON before/after, so it cannot affect the atomic
-                    // read->write window, and summarizeChange never throws.
-                    mutationResult = {
-                        doc: newDoc,
-                        verify: summarizeChange(beforeDoc, newDoc),
-                    };
-                    waitForPersistence();
-                },
-                onAuthenticationFailed: () => {
-                    finish(new Error("Authentication failed for collaboration connection"));
-                },
-            });
-        });
-    }
-    /**
-     * Generic pagination handler for Docmost API endpoints
-     */
-    async paginateAll(endpoint, basePayload = {}, limit = 100) {
-        await this.ensureAuthenticated();
-        const clampedLimit = Math.max(1, Math.min(100, limit));
-        // Hard ceiling on the number of pages to fetch: guards against a server
-        // that returns a perpetually-true hasNextPage (which would otherwise loop
-        // forever and accumulate duplicates).
-        const MAX_PAGES = 50;
-        let page = 1;
-        let allItems = [];
-        let hasNextPage = true;
-        while (hasNextPage && page <= MAX_PAGES) {
-            const response = await this.client.post(endpoint, {
-                ...basePayload,
-                limit: clampedLimit,
-                page,
-            });
-            const data = response.data;
-            const items = data.data?.items || data.items || [];
-            const meta = data.data?.meta || data.meta;
-            allItems = allItems.concat(items);
-            // Stop if the page is empty or shorter than the requested size: a full
-            // page worth of items is the only situation where another page can exist,
-            // so this defends against a stuck hasNextPage flag in addition to it.
-            if (items.length === 0 || items.length < clampedLimit) {
-                break;
-            }
-            hasNextPage = meta?.hasNextPage || false;
-            page++;
-        }
-        // If the loop stopped because it hit the MAX_PAGES ceiling while the server
-        // still reported more results (hasNextPage true and the last page was
-        // full), the result set is truncated — warn so the caller is not silently
-        // handed an incomplete list.
-        if (hasNextPage && page > MAX_PAGES) {
-            console.warn(`paginateAll: results from "${endpoint}" truncated at the ${MAX_PAGES}-page cap; more pages exist on the server`);
-        }
-        return allItems;
-    }
-    async getWorkspace() {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/workspace/info", {});
-        return {
-            data: filterWorkspace(response.data?.data ?? response.data),
-            success: response.data.success,
-        };
-    }
-    async getSpaces() {
-        const spaces = await this.paginateAll("/spaces", {});
-        return spaces.map((space) => filterSpace(space));
-    }
-    /**
-     * List pages in one of two modes.
-     *
-     * Default (`tree` false): most recent pages by updatedAt (descending),
-     * bounded. Fetching the whole space can exceed MCP response/time limits on
-     * large instances, so a single bounded page of results is returned (default
-     * 50, max 100) via the `/pages/recent` feed.
-     *
-     * Tree (`tree` true): the space's FULL page hierarchy as a nested tree (each
-     * node has a `children` array). This mode REQUIRES `spaceId` (a page tree is
-     * scoped to one space) and IGNORES `limit` — the whole hierarchy is returned.
-     * It walks the sidebar tree via `enumerateSpacePages`, which performs N
-     * sidebar requests and is bounded by that method's 10000-node cap (and skips
-     * soft-deleted pages server-side).
-     */
-    async listPages(spaceId, limit = 50, tree = false) {
-        await this.ensureAuthenticated();
-        if (tree) {
-            if (!spaceId) {
-                throw new Error("list_pages: tree mode requires a spaceId (a page tree is scoped to one space). Pass spaceId, or omit tree to get the recent-pages list.");
-            }
-            const nodes = await this.enumerateSpacePages(spaceId);
-            return buildPageTree(nodes);
-        }
-        const clampedLimit = Math.max(1, Math.min(100, limit));
-        const payload = { limit: clampedLimit, page: 1 };
-        if (spaceId)
-            payload.spaceId = spaceId;
-        const response = await this.client.post("/pages/recent", payload);
-        const data = response.data;
-        const items = data.data?.items || data.items || [];
-        return items.map((page) => filterPage(page));
-    }
-    /**
-     * List sidebar pages for a space. With no pageId the request returns the
-     * space ROOT pages; with a pageId it returns the direct CHILDREN of that
-     * page. pageId is therefore optional and is only included in the POST body
-     * when provided (an empty/undefined pageId would otherwise change the
-     * semantics on the server).
-     */
-    async listSidebarPages(spaceId, pageId) {
-        await this.ensureAuthenticated();
-        // Paginate: the endpoint returns server-paged children, so posting only
-        // { page: 1 } silently dropped every child beyond the first page. Loop on
-        // meta.hasNextPage (with a MAX_PAGES ceiling like paginateAll, guarding
-        // against a stuck hasNextPage flag) and accumulate all children.
-        const MAX_PAGES = 50;
-        let page = 1;
-        let allItems = [];
-        let hasNextPage = true;
-        while (hasNextPage && page <= MAX_PAGES) {
-            // Only send pageId when scoping to a page's children; omit it for roots.
-            const payload = { spaceId, page };
-            if (pageId)
-                payload.pageId = pageId;
-            const response = await this.client.post("/pages/sidebar-pages", payload);
-            const data = response.data?.data ?? response.data;
-            const items = data?.items || [];
-            allItems = allItems.concat(items);
-            hasNextPage = data?.meta?.hasNextPage || false;
-            page++;
-        }
-        return allItems;
-    }
-    /**
-     * Enumerate EVERY page in a space (or in a subtree, when rootPageId is given)
-     * by walking the sidebar-pages tree.
-     *
-     * Starting set: the children of rootPageId when provided, otherwise the
-     * space root pages. From there it does an iterative breadth-first walk: each
-     * node is collected, and when node.hasChildren is true its direct children
-     * are fetched via listSidebarPages(spaceId, node.id) and enqueued.
-     *
-     * This replaces the old "/pages/recent" enumeration, which is a bounded
-     * recent-activity feed (~5000 cap) and therefore misses comments on older
-     * pages that were never recently touched.
-     *
-     * Safeguards: a `visited` Set of page ids prevents re-processing a node
-     * (cycles / duplicate references), and a hard node cap bounds pathological
-     * trees so the walk always terminates.
-     */
-    async enumerateSpacePages(spaceId, rootPageId) {
-        const MAX_NODES = 10000;
-        const result = [];
-        const visited = new Set();
-        // Seed the queue with the starting level (subtree children or roots).
-        const queue = await this.listSidebarPages(spaceId, rootPageId);
-        while (queue.length > 0 && result.length < MAX_NODES) {
-            const node = queue.shift();
-            if (!node || typeof node !== "object" || !node.id)
-                continue;
-            // Skip already-seen ids to guard against cycles / duplicate references.
-            if (visited.has(node.id))
-                continue;
-            visited.add(node.id);
-            result.push(node);
-            if (node.hasChildren) {
-                try {
-                    const children = await this.listSidebarPages(spaceId, node.id);
-                    for (const child of children)
-                        queue.push(child);
-                }
-                catch (e) {
-                    // A failure fetching one node's children must not abort the whole
-                    // walk: skip this branch and keep enumerating the rest.
-                }
-            }
-        }
-        return result;
-    }
-    /** Raw page info including the ProseMirror JSON content and slugId. */
-    async getPageRaw(pageId) {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/pages/info", { pageId });
-        return response.data?.data ?? response.data;
-    }
-    /**
-     * Resolve an agent-supplied pageId to the page's CANONICAL UUID (`page.id`),
-     * so every collaboration document the MCP opens is named `page.<uuid>` — the
-     * SAME name the web editor always uses (`page.${page.id}`).
-     *
-     * The agent commonly passes a 10-char public slugId (from URLs/listings) as
-     * the pageId. The web editor opens the collab doc by UUID, but the MCP used to
-     * pass that slugId straight into the collab doc name (`page.<slugId>`). For one
-     * DB row that produced TWO independent Yjs documents whose debounced stores
-     * clobbered each other — the agent's edit was silently lost (#260).
-     *
-     * A UUID input short-circuits with no network round-trip. A slugId is resolved
-     * once via getPageRaw and cached (both slugId->uuid and uuid->uuid), so
-     * repeated edits on the same page add no extra request.
-     */
-    async resolvePageId(pageId) {
-        if (isUuid(pageId))
-            return pageId;
-        const cached = this.pageIdCache.get(pageId);
-        if (cached)
-            return cached;
-        const data = await this.getPageRaw(pageId);
-        const uuid = data?.id;
-        if (typeof uuid !== "string" || !uuid) {
-            throw new Error(`Could not resolve a canonical page id for "${pageId}"`);
-        }
-        this.pageIdCache.set(pageId, uuid);
-        return uuid;
-    }
-    async getPage(pageId) {
-        await this.ensureAuthenticated();
-        const resultData = await this.getPageRaw(pageId);
-        let content = resultData.content
-            ? convertProseMirrorToMarkdown(resultData.content)
-            : "";
-        // Always fetch subpages to provide context to the agent
-        let subpages = [];
-        try {
-            // `pageId` may be a slugId, but the sidebar-pages endpoint requires the
-            // UUID; `resultData.id` holds the resolved UUID returned by getPageRaw.
-            subpages = await this.listSidebarPages(resultData.spaceId, resultData.id);
-        }
-        catch (e) {
-            console.warn("Failed to fetch subpages:", e);
-        }
-        // Resolve subpages if the placeholder exists
-        if (content && content.includes("{{SUBPAGES}}")) {
-            if (subpages && subpages.length > 0) {
-                const list = subpages
-                    .map((p) => `- [${p.title}](page:${p.id})`)
-                    .join("\n");
-                content = content.replace("{{SUBPAGES}}", `### Subpages\n${list}`);
-            }
-            else {
-                content = content.replace("{{SUBPAGES}}", "");
-            }
-        }
-        return {
-            data: filterPage(resultData, content, subpages),
-            success: true,
-        };
-    }
-    /** Page info + raw ProseMirror JSON content (lossless representation). */
-    async getPageJson(pageId) {
-        const data = await this.getPageRaw(pageId);
-        return {
-            id: data.id,
-            slugId: data.slugId,
-            title: data.title,
-            parentPageId: data.parentPageId,
-            spaceId: data.spaceId,
-            updatedAt: data.updatedAt,
-            content: data.content || { type: "doc", content: [] },
-        };
-    }
-    /**
-     * Fetch an INTERNAL Docmost file (authed loopback) for sandbox mirroring.
-     * `src` is normalized to `/api/files/<id>/<file>`; `this.client.baseURL`
-     * already ends in `/api`, so we strip the leading `/api` and request the
-     * relative path with the client's Authorization header. Returns the raw bytes
-     * and the response Content-Type (mime), defaulting to octet-stream.
-     *
-     * The fetch is size-bounded (hard 64 MiB ceiling) purely to protect memory;
-     * the authoritative per-blob cap is enforced by the sandbox `put`. The path is
-     * resolved via resolveInternalFilePath, which REJECTS (throws) any traversal
-     * or percent-encoded src that would let an attacker-controlled `attrs.src`
-     * escape `/api/files/` and reach another internal endpoint (SSRF). That throw
-     * happens before this.client.get, so a malicious src is counted as a failed
-     * mirror — it never reaches the network.
-     */
-    async fetchInternalFile(src) {
-        const HARD_CEILING = 64 * 1024 * 1024; // 64 MiB memory guard
-        const relPath = resolveInternalFilePath(src);
-        const response = await this.client.get(relPath, {
-            responseType: "arraybuffer",
-            timeout: 30000,
-            maxContentLength: HARD_CEILING,
-            maxBodyLength: HARD_CEILING,
-        });
-        const buffer = Buffer.from(response.data);
-        if (buffer.length === 0) {
-            throw new Error(`Empty file response from "${src}"`);
-        }
-        const rawCt = response.headers?.["content-type"];
-        const mime = typeof rawCt === "string" && rawCt.length > 0
-            ? rawCt.split(";")[0].trim().toLowerCase()
-            : "application/octet-stream";
-        return { buffer, mime };
-    }
-    /**
-     * Stash a page's full content into the in-RAM blob sandbox and return ONLY a
-     * short anonymous URL — the body never enters the model context (this is the
-     * whole point: ~30KB+ ProseMirror docs blow the model context if passed as a
-     * tool argument). Every INTERNAL file/image src (the type-agnostic criterion,
-     * so drawio/excalidraw/video/file nodes are covered too) is mirrored into the
-     * sandbox and its `src` rewritten to the sandbox URL, so an external consumer
-     * can fetch the images anonymously. External http(s) srcs are left untouched.
-     *
-     * Blobs live in RAM with a short TTL and are cleared on restart — consume the
-     * URLs within the TTL and one uptime. A failed image fetch never aborts the
-     * doc: the original src is kept and the failure counted.
-     *
-     * Returns { uri, sha256, size, images:{mirrored, failed} }. `uri` and `sha256`
-     * are for the document blob; `sha256` is also the blob's ETag (integrity).
-     */
-    async stashPage(pageId) {
-        if (!this.sandboxPut) {
-            throw new Error("stash_page is unavailable: the blob sandbox is not configured on this server");
-        }
-        await this.ensureAuthenticated();
-        // Stash the SAME shape get_page_json returns (id/title/.../content), with a
-        // deep clone so the rewrite never mutates anything shared.
-        const pageJson = await this.getPageJson(pageId);
-        const cloned = structuredClone(pageJson);
-        // Group internal-file nodes by normalized src so each unique resource is
-        // fetched + stored ONCE (dedup), and every node sharing that src points at
-        // the one sandbox blob. Capture each node's ORIGINAL raw src per-node:
-        // dedup groups nodes whose normalized src is equal even when their raw srcs
-        // differ (e.g. `/api/files/...` vs the bare `/files/...`), so on a revert we
-        // must restore each node's own original value, not the group key.
-        const bySrc = new Map();
-        for (const node of collectInternalFileNodes(cloned.content)) {
-            const origSrc = String(node.attrs.src);
-            const src = normalizeFileUrl(origSrc);
-            const entry = { node, origSrc };
-            const group = bySrc.get(src);
-            if (group)
-                group.push(entry);
-            else
-                bySrc.set(src, [entry]);
-        }
-        let mirrored = 0;
-        let failed = 0;
-        // Record every successful mirror so it can be (a) reverted if its blob gets
-        // FIFO-evicted by a LATER put in this same stash, and (b) freed if the final
-        // doc put throws.
-        const mirrors = [];
-        const MAX_CONCURRENCY = 5;
-        const groups = [...bySrc.entries()];
-        for (let i = 0; i < groups.length; i += MAX_CONCURRENCY) {
-            const batch = groups.slice(i, i + MAX_CONCURRENCY);
-            await Promise.all(batch.map(async ([src, entries]) => {
-                try {
-                    const { buffer, mime } = await this.fetchInternalFile(src);
-                    // put may throw if the blob exceeds the per-blob/total caps.
-                    const stored = this.sandboxPut(buffer, mime);
-                    for (const entry of entries)
-                        entry.node.attrs.src = stored.uri;
-                    mirrors.push({ uri: stored.uri, entries });
-                    mirrored++;
-                }
-                catch (err) {
-                    // One bad/oversized image (or a rejected traversal src) must not
-                    // abort the document. Logged unconditionally (never the blob body),
-                    // matching the package's ungated console.warn convention.
-                    failed++;
-                    console.warn(`stash_page: failed to mirror "${src}": ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }));
-        }
-        // Revert one mirror's nodes to their original internal srcs and re-count it
-        // as failed (its blob was FIFO-evicted before the doc could reference it
-        // safely).
-        const revertMirror = (mirror) => {
-            for (const entry of mirror.entries)
-                entry.node.attrs.src = entry.origSrc;
-            mirrored--;
-            failed++;
-            console.warn(`stash_page: mirrored blob ${mirror.uri} was evicted before the doc ` +
-                `could safely reference it; reverted its src and counted it as failed`);
-        };
-        // Pre-put reconciliation: an image put earlier in THIS stash can FIFO-evict
-        // an even-earlier image of the same stash. Drop those from the live set
-        // first so the first serialized doc is already mostly correct.
-        let liveMirrors = mirrors;
-        if (this.sandboxHas) {
-            liveMirrors = [];
-            for (const mirror of mirrors) {
-                if (this.sandboxHas(mirror.uri))
-                    liveMirrors.push(mirror);
-                else
-                    revertMirror(mirror);
-            }
-        }
-        // Put the document, then reconcile against eviction caused by the doc put
-        // ITSELF (the doc is newest, FIFO drops oldest = this stash's images). Each
-        // iteration reverts >=1 mirror, so the loop terminates (worst case: all
-        // images reverted and the doc references no sandbox image URLs).
-        let stored;
-        for (;;) {
-            const docBuf = Buffer.from(JSON.stringify(cloned), "utf8");
-            let docStored;
-            try {
-                docStored = this.sandboxPut(docBuf, "application/json");
-            }
-            catch (err) {
-                // The doc put failed (e.g. doc exceeds the cap). Free this op's image
-                // blobs instead of leaking them in RAM for the whole TTL, then
-                // re-throw.
-                if (this.sandboxEvict) {
-                    for (const mirror of liveMirrors)
-                        this.sandboxEvict(mirror.uri);
-                }
-                throw err;
-            }
-            if (!this.sandboxHas) {
-                stored = docStored;
-                break;
-            }
-            const evictedNow = liveMirrors.filter((m) => !this.sandboxHas(m.uri));
-            if (evictedNow.length === 0) {
-                stored = docStored;
-                break;
-            }
-            // The doc we just stored references now-dead blobs. Revert those nodes,
-            // drop the stale doc blob, and loop to re-serialize + re-put the
-            // corrected doc.
-            for (const mirror of evictedNow)
-                revertMirror(mirror);
-            liveMirrors = liveMirrors.filter((m) => this.sandboxHas(m.uri));
-            if (this.sandboxEvict)
-                this.sandboxEvict(docStored.uri);
-        }
-        return {
-            uri: stored.uri,
-            sha256: stored.sha256,
-            size: stored.size,
-            images: { mirrored, failed },
-        };
-    }
-    /**
-     * Compact outline of a page's top-level blocks (no full document body).
-     * Cheap way to locate sections/tables and grab block ids before drilling in
-     * with get_node / patch_node / insert_node.
-     */
-    async getOutline(pageId) {
-        await this.ensureAuthenticated();
-        const data = await this.getPageRaw(pageId);
-        return {
-            pageId,
-            slugId: data.slugId,
-            title: data.title,
-            outline: buildOutline(data.content ?? { type: "doc", content: [] }),
-        };
-    }
-    /**
-     * Fetch a single node's full ProseMirror subtree (lossless) by reference:
-     * a block id (headings/paragraphs/callouts/images), or `#<index>` to select
-     * a top-level block by its outline index (the only way to reach tables/rows/
-     * cells, which carry no id).
-     */
-    async getNode(pageId, nodeId) {
-        await this.ensureAuthenticated();
-        const data = await this.getPageRaw(pageId);
-        const hit = getNodeByRef(data.content ?? { type: "doc", content: [] }, nodeId);
-        if (!hit) {
-            throw new Error(`get_node: no node found for "${nodeId}" on page ${pageId} (use a block id from get_outline, or "#<index>" for a top-level block such as a table)`);
-        }
-        return {
-            pageId,
-            ref: nodeId,
-            path: hit.path,
-            type: hit.type,
-            node: hit.node,
-        };
-    }
-    /**
-     * Read a table as a matrix. `tableRef` is `#<index>` (from get_outline) or a
-     * block id of any node inside the table. Returns the cell texts plus a
-     * parallel cellIds matrix (each cell's first paragraph id, or null) so a
-     * caller can patch_node a cell for rich-formatted edits. Throws when no table
-     * resolves for the reference.
-     */
-    async getTable(pageId, tableRef) {
-        await this.ensureAuthenticated();
-        const data = await this.getPageRaw(pageId);
-        const t = readTable(data.content ?? { type: "doc", content: [] }, tableRef);
-        if (!t) {
-            throw new Error(`table_get: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
-        }
-        return {
-            pageId,
-            table: tableRef,
-            rows: t.rows,
-            cols: t.cols,
-            path: t.path,
-            cells: t.cells,
-            cellIds: t.cellIds,
-        };
-    }
-    /**
-     * Insert a row of plain-text cells into a table on the LIVE collab document.
-     * `tableRef` is `#<index>` or a block id inside the target table. `cells` is
-     * padded to the table's column count (more cells than columns throws); `index`
-     * is a 0-based insert position (omit/out-of-range to append). Throws when no
-     * table resolves for the reference.
-     */
-    async tableInsertRow(pageId, tableRef, cells, index) {
-        await this.ensureAuthenticated();
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Track insertion in an outer var, reset per-transform, so a collab retry
-        // recomputes it cleanly (mirrors insertNode's pattern).
-        let inserted = false;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            inserted = false;
-            const { doc: nd, inserted: ins } = insertTableRow(liveDoc, tableRef, cells, index);
-            inserted = ins;
-            if (!inserted)
-                return null; // table not found -> skip the write entirely
-            return nd;
-        });
-        if (!inserted) {
-            throw new Error(`table_insert_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
-        }
-        return {
-            success: true,
-            table: tableRef,
-            inserted: true,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Delete the row at 0-based `index` from a table on the LIVE collab document.
-     * `tableRef` is `#<index>` or a block id inside the target table. The helper's
-     * out-of-range and last-row errors propagate; a missing table throws here.
-     */
-    async tableDeleteRow(pageId, tableRef, index) {
-        await this.ensureAuthenticated();
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        let deleted = false;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            deleted = false;
-            const { doc: nd, deleted: del } = deleteTableRow(liveDoc, tableRef, index);
-            deleted = del;
-            if (!deleted)
-                return null; // table not found -> skip the write entirely
-            return nd;
-        });
-        if (!deleted) {
-            throw new Error(`table_delete_row: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
-        }
-        return {
-            success: true,
-            table: tableRef,
-            deleted: true,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Set the plain-text content of cell `[row, col]` (0-based) in a table on the
-     * LIVE collab document, replacing the cell's content with a single text
-     * paragraph (the cell's first-paragraph id is preserved). `tableRef` is
-     * `#<index>` or a block id inside the target table. The helper's out-of-range
-     * error propagates; a missing table throws here.
-     */
-    async tableUpdateCell(pageId, tableRef, row, col, text) {
-        await this.ensureAuthenticated();
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        let updated = false;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            updated = false;
-            const { doc: nd, updated: upd } = updateTableCell(liveDoc, tableRef, row, col, text);
-            updated = upd;
-            if (!updated)
-                return null; // table not found -> skip the write entirely
-            return nd;
-        });
-        if (!updated) {
-            throw new Error(`table_update_cell: no table found for "${tableRef}" on page ${pageId} (use "#<index>" from get_outline, or a block id inside the table)`);
-        }
-        return {
-            success: true,
-            table: tableRef,
-            row,
-            col,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Create a new page with title and content.
-     * Uses the /pages/import workaround (the only endpoint accepting content),
-     * then moves the page and restores the exact title: the import endpoint
-     * derives the title from the FILENAME and replaces spaces with
-     * underscores, so we explicitly re-set it via /pages/update afterwards.
-     */
-    async createPage(title, content, spaceId, parentPageId) {
-        await this.ensureAuthenticated();
-        if (parentPageId) {
-            try {
-                await this.getPage(parentPageId);
-            }
-            catch (e) {
-                throw new Error(`Parent page with ID ${parentPageId} not found.`);
-            }
-        }
-        // 1. Create content via Import (using multipart/form-data).
-        // Build a FRESH FormData per send attempt: a FormData body is a single-use
-        // stream consumed on the first send, so it cannot be replayed by
-        // this.client's response interceptor (replay fails with 'socket hang up').
-        // Multipart re-auth is therefore done here with bare axios and an explicit
-        // one-shot 401/403 retry that rebuilds the body.
-        const fileContent = Buffer.from(content, "utf-8");
-        const buildForm = () => {
-            const form = new FormData();
-            form.append("spaceId", spaceId);
-            form.append("file", fileContent, {
-                filename: `${title || "import"}.md`,
-                contentType: "text/markdown",
-            });
-            return form;
-        };
-        const importUrl = `${this.apiUrl}/pages/import`;
-        let response;
-        try {
-            // Call buildForm() ONCE per attempt and reuse the instance for both
-            // getHeaders() and the body so the Content-Type boundary matches the body.
-            const form = buildForm();
-            // Read the Authorization header from this.client's defaults (set by
-            // login(), only ever deleted — never set to null) instead of building
-            // `Bearer ${this.token}`: a concurrent JSON 401 can null this.token
-            // mid-flight, which would otherwise produce a literal "Bearer null".
-            // ensureAuthenticated() above guarantees login() ran, so the default
-            // header exists here.
-            response = await axios.post(importUrl, form, {
-                headers: {
-                    ...form.getHeaders(),
-                    Authorization: this.client.defaults.headers.common["Authorization"],
-                },
-                timeout: 60000,
-            });
-        }
-        catch (error) {
-            // On an expired-token auth error, re-login and retry exactly once with a
-            // freshly-rebuilt FormData (the previous one was already consumed).
-            if (axios.isAxiosError(error) &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                await this.login();
-                const form2 = buildForm();
-                response = await axios.post(importUrl, form2, {
-                    headers: {
-                        ...form2.getHeaders(),
-                        Authorization: this.client.defaults.headers.common["Authorization"],
-                    },
-                    timeout: 60000,
-                });
-            }
-            else {
-                throw error;
-            }
-        }
-        const newPageId = (response.data?.data ?? response.data).id;
-        // 2. Move to parent if needed
-        if (parentPageId) {
-            await this.movePage(newPageId, parentPageId);
-        }
-        // 3. Restore the exact title (import mangles spaces into underscores)
-        if (title) {
-            await this.client.post("/pages/update", { pageId: newPageId, title });
-        }
-        const page = await this.getPage(newPageId);
-        // Surface non-fatal footnote problems (dangling refs, empty/duplicate
-        // definitions, markers in tables) so the agent can fix its markup (#166).
-        return { ...page, ...footnoteWarningsField(content) };
-    }
-    /**
-     * Update a page's content from markdown and optionally its title.
-     * NOTE: full re-import — block ids regenerate. For surgical changes
-     * use editPageText / updatePageJson instead.
-     */
-    async updatePage(pageId, content, title) {
-        await this.ensureAuthenticated();
-        // Open the collab doc by the canonical UUID, never the slugId (#260). The
-        // REST /pages/update title write below keeps the agent-supplied id (the
-        // server resolves a slugId there).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Write the BODY first, then the title (#159 split-brain). If the collab
-        // body write fails (e.g. a persist timeout), the title must be left
-        // UNTOUCHED so the page never ends up with a new title over its old body.
-        // A title write failing AFTER a successful body is rarer (REST is fast) and
-        // leaves correct content under a stale title — the lesser inconsistency.
-        let collabToken = "";
-        let mutation;
-        try {
-            collabToken = await this.getCollabTokenWithReauth();
-            mutation = await updatePageContentRealtime(pageUuid, content, collabToken, this.apiUrl);
-        }
-        catch (error) {
-            // Verbose diagnostics (incl. anything that could expose a token prefix)
-            // are gated behind DEBUG; the thrown Error below carries no token data.
-            if (process.env.DEBUG) {
-                console.error("Failed to update page content via realtime collaboration:", error);
-                const tokenPreview = collabToken
-                    ? collabToken.substring(0, 15) + "..."
-                    : "null";
-                console.error(`Collab token preview: ${tokenPreview}`);
-            }
-            throw new Error(`Failed to update page content: ${error.message}`);
-        }
-        // Body persisted successfully — now it is safe to set the title.
-        if (title) {
-            await this.client.post("/pages/update", { pageId, title });
-        }
-        return {
-            success: true,
-            modified: true,
-            message: "Page updated successfully.",
-            pageId: pageId,
-            verify: mutation.verify,
-            // Non-fatal footnote diagnostics (#166); omitted when there are none.
-            ...footnoteWarningsField(content),
-        };
-    }
-    /**
-     * Validate a URL string against a scheme allowlist for a given context.
-     *
-     * The markdown link path enforces safe schemes via TipTap, but the raw
-     * JSON path (updatePageJson) bypasses that — so this is the sanitization
-     * choke point for ProseMirror JSON written directly by the caller.
-     *
-     * - "link":  reject javascript:, vbscript:, data: (any scheme that can
-     *            execute or smuggle script when the href is clicked).
-     * - "src":   allow only http(s):, mailto:, /api/files paths, or a
-     *            scheme-less relative/absolute path; reject
-     *            javascript:/vbscript:/data:/file:.
-     */
-    isSafeUrl(url, context) {
-        if (typeof url !== "string")
-            return false;
-        const trimmed = url.trim();
-        if (trimmed === "")
-            return true; // empty href/src is harmless
-        // Extract a leading "scheme:" if present. A scheme must start with a
-        // letter and contain only letters/digits/+/-/. before the colon. Strip
-        // whitespace and ASCII control chars first so a tab/newline embedded in
-        // the scheme cannot smuggle a dangerous scheme past the check.
-        const cleaned = trimmed.replace(/[\s\x00-\x1f]+/g, "");
-        const schemeMatch = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(cleaned);
-        const scheme = schemeMatch ? schemeMatch[1].toLowerCase() : null;
-        const dangerous = new Set(["javascript", "vbscript", "data", "file"]);
-        if (context === "link") {
-            if (scheme === null)
-                return true; // relative/anchor link is fine
-            // For links, data: is also blocked (can carry script payloads).
-            return !new Set(["javascript", "vbscript", "data"]).has(scheme);
-        }
-        // context === "src"
-        if (scheme === null)
-            return true; // relative/absolute path (incl. /api/files)
-        if (dangerous.has(scheme))
-            return false;
-        return scheme === "http" || scheme === "https" || scheme === "mailto";
-    }
-    /**
-     * Recursively walk a ProseMirror doc and reject any unsafe URL on a link
-     * mark href or on a media node's src/url. Media nodes covered: image,
-     * attachment, video, plus embed (rendered as an iframe), youtube, drawio
-     * and excalidraw — all of which carry a user-controlled URL that Docmost
-     * renders. Throws a clear error on the first violation. A max-depth guard
-     * turns an over-deep document into a clean error instead of a RangeError
-     * stack overflow.
-     */
-    validateDocUrls(node, depth = 0) {
-        const MAX_DEPTH = 200;
-        if (depth > MAX_DEPTH) {
-            throw new Error(`document nesting exceeds the maximum depth of ${MAX_DEPTH}`);
-        }
-        if (!node || typeof node !== "object")
-            return;
-        // Link marks on text nodes: validate the href.
-        if (Array.isArray(node.marks)) {
-            for (const mark of node.marks) {
-                if (mark && mark.type === "link" && mark.attrs) {
-                    if (!this.isSafeUrl(mark.attrs.href, "link")) {
-                        throw new Error(`unsafe link href rejected: "${mark.attrs.href}"`);
-                    }
-                }
-            }
-        }
-        // Media nodes: validate src/url against the stricter src allowlist.
-        // embed renders as an iframe (highest risk); youtube/drawio/excalidraw
-        // likewise carry a user-controlled URL Docmost renders, so they get the
-        // same scheme check as image/attachment/video.
-        if (node.type === "image" ||
-            node.type === "attachment" ||
-            node.type === "video" ||
-            node.type === "embed" ||
-            node.type === "youtube" ||
-            node.type === "drawio" ||
-            node.type === "excalidraw" ||
-            node.type === "audio" ||
-            node.type === "pdf") {
-            const attrs = node.attrs || {};
-            for (const key of ["src", "url"]) {
-                if (attrs[key] != null && !this.isSafeUrl(attrs[key], "src")) {
-                    throw new Error(`unsafe ${node.type} ${key} rejected: "${attrs[key]}"`);
-                }
-            }
-        }
-        if (Array.isArray(node.content)) {
-            for (const child of node.content) {
-                this.validateDocUrls(child, depth + 1);
-            }
-        }
-    }
-    /**
-     * Recursively validate the STRUCTURE of a ProseMirror node (reuses the
-     * recursion shape of validateDocUrls). Every node must be an object with a
-     * string `type`; when present, `content` must be an array, `marks` must be
-     * an array of objects each with a string `type`, and a text node's `text`
-     * must be a string. Throws a clear "invalid ProseMirror document" error on
-     * the first violation. A max-depth guard turns an over-deep document into a
-     * clean error instead of a RangeError stack overflow.
-     */
-    validateDocStructure(node, depth = 0) {
-        const MAX_DEPTH = 200;
-        if (depth > MAX_DEPTH) {
-            throw new Error(`invalid ProseMirror document: nesting exceeds the maximum depth of ${MAX_DEPTH}`);
-        }
-        if (!node || typeof node !== "object" || typeof node.type !== "string") {
-            throw new Error("invalid ProseMirror document: every node must be an object with a string `type`");
-        }
-        if ("text" in node &&
-            node.type === "text" &&
-            typeof node.text !== "string") {
-            throw new Error("invalid ProseMirror document: a text node must have a string `text`");
-        }
-        if (node.marks !== undefined) {
-            if (!Array.isArray(node.marks)) {
-                throw new Error("invalid ProseMirror document: `marks` must be an array");
-            }
-            for (const mark of node.marks) {
-                if (!mark ||
-                    typeof mark !== "object" ||
-                    typeof mark.type !== "string") {
-                    throw new Error("invalid ProseMirror document: every mark must be an object with a string `type`");
-                }
-            }
-        }
-        if (node.content !== undefined) {
-            if (!Array.isArray(node.content)) {
-                throw new Error("invalid ProseMirror document: `content` must be an array when present");
-            }
-            for (const child of node.content) {
-                this.validateDocStructure(child, depth + 1);
-            }
-        }
-    }
-    /**
-     * Replace page content with a raw ProseMirror JSON document (lossless) and/or
-     * update its title. Both `doc` and `title` are optional, but at least one must
-     * be supplied:
-     *  - `doc` provided   -> validate + full-overwrite the body (and update the
-     *                        title too when `title` is also given).
-     *  - `doc` omitted, `title` given -> title-only update; the body is NOT
-     *                        touched/resent (no collab write happens).
-     *  - neither given    -> throws (nothing to update).
-     */
-    async updatePageJson(pageId, doc, title) {
-        await this.ensureAuthenticated();
-        // Title-only / no-op handling: when no document is supplied, do NOT write
-        // the body. Update the title if one was given; otherwise there is nothing
-        // to do, so fail loudly rather than silently no-op.
-        if (doc == null) {
-            if (!title) {
-                throw new Error("update_page_json: nothing to update (provide content and/or title)");
-            }
-            await this.client.post("/pages/update", { pageId, title });
-            return {
-                success: true,
-                modified: true,
-                message: "Page title updated (content left unchanged).",
-                pageId,
-            };
-        }
-        // Validate the document shape before a full overwrite: a malformed doc
-        // would otherwise silently corrupt the page (full-overwrite is the
-        // documented behaviour; no optimistic-concurrency is applied here).
-        if (typeof doc !== "object" ||
-            doc.type !== "doc" ||
-            !Array.isArray(doc.content)) {
-            throw new Error('content must be a ProseMirror document ({"type":"doc","content":[...]}) ' +
-                "where content is an array of nodes each having a string `type`");
-        }
-        // Recurse the WHOLE document so a malformed nested node (e.g. a node with a
-        // non-string type, a non-array content/marks, or a text node missing its
-        // string text) is rejected up front rather than silently corrupting the
-        // page on overwrite.
-        this.validateDocStructure(doc);
-        // Sanitize URLs before writing. This closes the JSON-path bypass: unlike
-        // the markdown link path (which TipTap sanitizes), raw JSON could otherwise
-        // inject javascript:/data: link hrefs or media srcs straight into the doc.
-        this.validateDocUrls(doc);
-        // Canonicalize footnotes (idempotent): an agent-authored JSON doc cannot
-        // leave footnotes out of order, orphaned, or in multiple lists — the bottom
-        // list + numbering are always derived from reference order. No-op when the
-        // footnotes are already canonical.
-        doc = canonicalizeFootnotes(doc);
-        // Write the BODY first, then the title (#159 split-brain): a failed body
-        // write (e.g. persist timeout) must not leave a new title over the old body.
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        const mutation = await this.replacePage(pageUuid, doc, collabToken, this.apiUrl);
-        // Body persisted successfully — now it is safe to set the title.
-        if (title) {
-            await this.client.post("/pages/update", { pageId, title });
-        }
-        return {
-            success: true,
-            modified: true,
-            message: "Page content replaced from ProseMirror JSON.",
-            pageId,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * AUTHOR-INLINE footnote insertion. The agent supplies only WHERE
-     * (`anchorText`, a snippet of body text to attach the marker after) and WHAT
-     * (`text`, the footnote content as markdown). Numbering and the bottom
-     * `footnotesList` are derived deterministically server-side
-     * (`insertInlineFootnote` -> `canonicalizeFootnotes`): the agent never sees,
-     * assigns, or edits a footnote number or the list, so it CANNOT desync.
-     *
-     * Content DEDUP: when an existing definition has the same content, its id is
-     * reused (one number, one definition, several references). The write is atomic
-     * via `mutatePageContent` (single-writer, page-locked); if the anchor text is
-     * not found the transform aborts with a clear error and no write happens.
-     */
-    async insertFootnote(pageId, anchorText, text) {
-        await this.ensureAuthenticated();
-        if (!anchorText || !anchorText.trim()) {
-            throw new Error("insert_footnote: anchorText is required");
-        }
-        if (text == null || `${text}`.trim() === "") {
-            throw new Error("insert_footnote: text is required");
-        }
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        let result = null;
-        const mutation = await this.mutatePage(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            const r = insertInlineFootnote(liveDoc, { anchorText, text });
-            if (!r.inserted) {
-                // Abort the page-locked write by throwing: mutatePageContent does not
-                // persist when the transform throws, so a missing anchor leaves the
-                // page untouched (no partial write).
-                throw new Error(`insert_footnote: anchor text not found: ${JSON.stringify(anchorText.slice(0, 80))}`);
-            }
-            result = { footnoteId: r.footnoteId, reused: r.reused };
-            return r.doc;
-        });
-        // The not-found path throws inside the transform (aborting mutatePage), so by
-        // here `result` is always set.
-        const r = result;
-        return {
-            success: true,
-            modified: true,
-            pageId,
-            footnoteId: r.footnoteId,
-            reused: r.reused,
-            message: r.reused
-                ? "Footnote inserted (reused an existing same-content definition)."
-                : "Footnote inserted.",
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Page-locked write seam over collaboration.mutatePageContent. Production just
-     * delegates; it exists as an overridable method so the insert_footnote wrapper
-     * (transform abort-on-not-found + response shaping) can be unit-tested without
-     * standing up a live Hocuspocus collab socket.
-     */
-    mutatePage(pageId, collabToken, apiUrl, transform) {
-        return mutatePageContent(pageId, collabToken, apiUrl, transform);
-    }
-    /**
-     * Full-document write seam over collaboration.replacePageContent. Production
-     * just delegates; it exists as an overridable method so the full-doc write
-     * tools (update_page_json, copy_page_content) can have their footnote-
-     * canonicalization binding unit-tested without a live Hocuspocus collab socket.
-     */
-    replacePage(pageId, doc, collabToken, apiUrl) {
-        return replacePageContent(pageId, doc, collabToken, apiUrl);
-    }
-    /**
-     * Export a page to a single self-contained Docmost-flavoured markdown file:
-     * meta block + body (with inline comment anchors + diagrams) + comment
-     * threads. Lossless round-trip target; see importPageMarkdown for the inverse.
-     */
-    async exportPageMarkdown(pageId) {
-        await this.ensureAuthenticated();
-        const page = await this.getPageRaw(pageId);
-        const body = page.content ? convertProseMirrorToMarkdown(page.content) : "";
-        let comments = [];
-        try {
-            comments = await this.listComments(pageId);
-        }
-        catch (e) {
-            // A comments fetch failure must not lose the body; export with [] and let
-            // the caller see the (empty) comments block. Log under DEBUG only.
-            if (process.env.DEBUG)
-                console.error("export: listComments failed", e);
-        }
-        const meta = {
-            version: 1,
-            pageId: page.id,
-            slugId: page.slugId,
-            title: page.title,
-            spaceId: page.spaceId,
-            parentPageId: page.parentPageId ?? null,
-        };
-        return serializeDocmostMarkdown(meta, body, comments);
-    }
-    /**
-     * Import a self-contained Docmost markdown file back into a page. Parses out
-     * the meta + comments metadata blocks, converts the body to ProseMirror
-     * (restoring comment marks + diagrams from their inline HTML), and replaces
-     * the page content. Comment THREAD records are NOT written to the server in
-     * this version — they are preserved in the file and the inline marks are
-     * re-applied so the highlights survive; managing comment records stays with
-     * the comment tools/UI.
-     */
-    async importPageMarkdown(pageId, fullMarkdown) {
-        await this.ensureAuthenticated();
-        const { meta, body, comments } = parseDocmostMarkdown(fullMarkdown);
-        // PAGE import: canonicalize footnotes (see markdownToProseMirrorCanonical).
-        const doc = await markdownToProseMirrorCanonical(body);
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        const mutation = await replacePageContent(pageUuid, doc, collabToken, this.apiUrl);
-        // Collect distinct comment ids that actually became comment marks in the doc.
-        const collectCommentIds = (node, acc) => {
-            if (!node || typeof node !== "object")
-                return acc;
-            if (Array.isArray(node.marks)) {
-                for (const mk of node.marks) {
-                    if (mk && mk.type === "comment" && mk.attrs?.commentId) {
-                        acc.add(mk.attrs.commentId);
-                    }
-                }
-            }
-            if (Array.isArray(node.content)) {
-                for (const child of node.content)
-                    collectCommentIds(child, acc);
-            }
-            return acc;
-        };
-        // Count reflects the comment marks present in the written document, so an id
-        // that only appears as inert text (e.g. inside a fenced code block) is not
-        // counted because it never becomes a comment mark.
-        const anchoredIds = collectCommentIds(doc, new Set());
-        const result = {
-            success: true,
-            pageId,
-            anchoredCommentCount: anchoredIds.size,
-            commentsInFile: Array.isArray(comments) ? comments.length : 0,
-            verify: mutation.verify,
-        };
-        // Warn (non-fatal) if the file was exported from a DIFFERENT page.
-        if (meta?.pageId && meta.pageId !== pageId) {
-            result.warning = `File was exported from page ${meta.pageId} but is being imported into ${pageId}.`;
-        }
-        // Non-fatal footnote diagnostics (#166), analyzed on the BODY (the part after
-        // the docmost:meta / docmost:comments blocks) — so a `[^x]`-like token inside
-        // those JSON blocks never produces a false warning, while real markers in the
-        // body do. `body` comes from parseDocmostMarkdown(fullMarkdown) above.
-        Object.assign(result, footnoteWarningsField(body));
-        return result;
-    }
-    /**
-     * Rename a page (change its title only) without touching or resending its
-     * content. The slug is derived from the page record, not the body, so it is
-     * left intact too.
-     */
-    async renamePage(pageId, title) {
-        await this.ensureAuthenticated();
-        await this.client.post("/pages/update", { pageId, title });
-        return { success: true, pageId, title };
-    }
-    /**
-     * Copy the WHOLE content of one page onto another, entirely server-side: the
-     * source's ProseMirror document is read and written verbatim onto the target
-     * via the live collab path, so the document never passes through the model.
-     *
-     * Only the target's BODY is replaced — its title and slug live on the page
-     * record (not in the content), so they are untouched. The source page is not
-     * modified at all.
-     */
-    async copyPageContent(sourcePageId, targetPageId) {
-        await this.ensureAuthenticated();
-        // A self-copy would be a no-op overwrite; reject it explicitly so a caller
-        // mistake surfaces as a clear error rather than a silent round-trip.
-        if (sourcePageId === targetPageId) {
-            throw new Error("copy_page_content: sourcePageId and targetPageId are the same page (no-op copy)");
-        }
-        const source = await this.getPageRaw(sourcePageId);
-        const content = source?.content;
-        if (!content ||
-            typeof content !== "object" ||
-            content.type !== "doc" ||
-            !Array.isArray(content.content)) {
-            throw new Error(`copy_page_content: source page ${sourcePageId} has no usable ProseMirror content to copy`);
-        }
-        // Defense-in-depth: run the same URL-scheme sanitizer the JSON write path
-        // uses, so copying never lands a javascript:/data: href/src on the target
-        // (parity with updatePageJson; harmless for already-stored source content).
-        this.validateDocUrls(content);
-        // Defense-in-depth (#228): this is a FULL-document write, so canonicalize
-        // footnotes before copying — a no-op on already-canonical source content, but
-        // it guarantees a copy can never propagate a non-canonical footnote topology
-        // to the target (parity with the other full-doc write paths).
-        const canonical = canonicalizeFootnotes(content);
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the TARGET collab doc by its canonical UUID, never the slugId (#260).
-        const targetUuid = await this.resolvePageId(targetPageId);
-        const mutation = await this.replacePage(targetUuid, canonical, collabToken, this.apiUrl);
-        return {
-            success: true,
-            sourcePageId,
-            targetPageId,
-            copiedNodes: canonical.content.length,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Surgical text edits: find/replace inside text nodes of the live
-     * document. Preserves all block ids, marks, callouts and tables.
-     */
-    async editPageText(pageId, edits) {
-        await this.ensureAuthenticated();
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Apply the edits against the LIVE synced document, not the debounced REST
-        // snapshot, so concurrent human edits/comments are preserved. applyTextEdits
-        // records per-edit match problems in `failed` instead of throwing, and
-        // applies whatever it can; we abort the write only when nothing applied.
-        let results;
-        let failed;
-        // Whether we actually wrote new content. Set inside the transform: a
-        // degenerate edit (e.g. find === replace, or a batch that nets to no change)
-        // can "apply" yet leave the document byte-for-byte identical, in which case
-        // we must NOT write (no spurious history version) and must not claim a write
-        // happened.
-        let wrote = false;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            wrote = false;
-            const r = applyTextEdits(liveDoc, edits);
-            results = r.results;
-            failed = r.failed;
-            // Nothing applied -> abort the write (mutatePageContent treats a null
-            // return from the transform as "write nothing").
-            if (r.results.length === 0)
-                return null;
-            // Edits "applied" but produced an identical document: skip the write so
-            // no new history version is created. Stable structural comparison via
-            // JSON.stringify (both docs come from the same deep-copied source, so
-            // key order is stable).
-            if (JSON.stringify(r.doc) === JSON.stringify(liveDoc))
-                return null;
-            wrote = true;
-            return r.doc;
-        });
-        if ((results?.length ?? 0) === 0 && (failed?.length ?? 0) > 0) {
-            // No edit applied: surface an aggregated, actionable error so the caller
-            // does not mistake a no-op for a partial success.
-            throw new Error("edit_page_text: no edits were applied (nothing written). " +
-                failed.map((f) => `"${f.find}": ${f.reason}`).join("; "));
-        }
-        // Edits matched but produced no content change (identical document): report
-        // a successful no-op — NOT a failure — and do not falsely claim a write.
-        if (!wrote) {
-            return {
-                success: true,
-                pageId,
-                applied: results,
-                failed,
-                message: "No changes written (edits produced identical content).",
-                verify: mutation.verify,
-            };
-        }
-        const result = {
-            success: true,
-            pageId,
-            applied: results,
-            failed,
-            message: (failed?.length ?? 0)
-                ? `Applied ${results?.length ?? 0} edit(s); ${failed.length} failed (see failed[]). Node ids and formatting preserved.`
-                : "Text edits applied (node ids and formatting preserved).",
-            verify: mutation.verify,
-        };
-        // If any applied edit matched only after stripping markdown (the
-        // normalized fallback), warn that edit_page_text preserved existing marks
-        // and did NOT change formatting — so a caller who intended a formatting
-        // change is pointed at patch_node.
-        if (results?.some((r) => r.normalized === true)) {
-            result.warning =
-                "Some edits matched only after stripping markdown from your find string; " +
-                    "edit_page_text preserved existing marks (it did not change bold/strike/etc.). " +
-                    "If you intended a formatting change, use patch_node.";
-        }
-        return result;
-    }
-    /**
-     * Replace EVERY node whose attrs.id === nodeId (recursively, including nodes
-     * nested in callouts/tables) with the supplied node. Operates on the LIVE
-     * collab document so comments and concurrent edits are preserved.
-     *
-     * The replacement node's block id is preserved: if node.attrs is missing it
-     * is created, and if node.attrs.id is missing it is set to nodeId so the
-     * replacement keeps the same id it replaced. Throws if no node matches.
-     */
-    async patchNode(pageId, nodeId, node) {
-        await this.ensureAuthenticated();
-        if (!node || typeof node !== "object" || typeof node.type !== "string") {
-            throw new Error("patch_node: `node` must be an object with a string `type`");
-        }
-        // Preserve the block id WITHOUT mutating the caller's object: build a local
-        // copy whose attrs.id === nodeId (so the swapped-in node keeps the id of the
-        // node it replaces).
-        const target = {
-            ...node,
-            attrs: {
-                ...(node.attrs && typeof node.attrs === "object" ? node.attrs : {}),
-            },
-        };
-        if (target.attrs.id == null) {
-            target.attrs.id = nodeId;
-        }
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Track the replacement count in an outer var, reset per-transform, so a
-        // collab retry recomputes it cleanly (mirrors replaceImage's pattern).
-        let replaced = 0;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            replaced = 0;
-            const { doc: nd, replaced: r } = replaceNodeById(liveDoc, nodeId, target);
-            replaced = r;
-            // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS: Docmost
-            // duplicates block ids on copy/paste (and copyPageContent writes them
-            // verbatim), so replacing "the node with id X" would silently clobber
-            // EVERY duplicate (#159). Refuse: skip the write and throw below so the
-            // model re-targets with a more specific anchor instead of corrupting the
-            // page. Only an unambiguous single match is written.
-            if (replaced !== 1)
-                return null;
-            return nd;
-        });
-        // 0 -> "no node"; >1 -> "ambiguous, refused" (the transform already skipped
-        // the write for any count !== 1). Single shared guard (#159, #185 review).
-        assertUnambiguousMatch("patch_node", "replace", replaced, nodeId, pageId);
-        return { success: true, replaced, nodeId, verify: mutation.verify };
-    }
-    /**
-     * Insert a node relative to an anchor (or append it at the top level).
-     * Operates on the LIVE collab document so comments and concurrent edits are
-     * preserved.
-     *
-     * opts.position:
-     *  - "append": push the node at the end of the top-level content.
-     *  - "before"/"after": insert the node as a sibling of the anchor, just
-     *    before/after it. Exactly one of anchorNodeId / anchorText must be given;
-     *    anchorNodeId locates a node anywhere by attrs.id, anchorText matches the
-     *    first top-level block whose plain text includes it.
-     *
-     * Throws if the anchor cannot be found.
-     */
-    async insertNode(pageId, node, opts) {
-        await this.ensureAuthenticated();
-        if (!node || typeof node !== "object" || typeof node.type !== "string") {
-            throw new Error("insert_node: `node` must be an object with a string `type`");
-        }
-        if (!opts ||
-            (opts.position !== "before" &&
-                opts.position !== "after" &&
-                opts.position !== "append")) {
-            throw new Error('insert_node: `position` must be one of "before", "after", "append"');
-        }
-        if (opts.position === "before" || opts.position === "after") {
-            // before/after require EXACTLY ONE anchor (an id or a text fragment).
-            const hasId = typeof opts.anchorNodeId === "string" && opts.anchorNodeId.length > 0;
-            const hasText = typeof opts.anchorText === "string" && opts.anchorText.length > 0;
-            if (hasId === hasText) {
-                throw new Error(`insert_node: position "${opts.position}" requires exactly one of anchorNodeId or anchorText`);
-            }
-        }
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Track insertion in an outer var, reset per-transform, so a collab retry
-        // recomputes it cleanly (mirrors replaceImage's pattern).
-        let inserted = false;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            inserted = false;
-            const { doc: nd, inserted: ins } = insertNodeRelative(liveDoc, node, opts);
-            inserted = ins;
-            if (!inserted)
-                return null; // anchor not found -> skip the write entirely
-            return nd;
-        });
-        if (!inserted) {
-            const anchorDesc = opts.anchorNodeId
-                ? `anchorNodeId "${opts.anchorNodeId}"`
-                : `anchorText "${opts.anchorText}"`;
-            // anchorText is matched against the block's literal RENDERED plain text;
-            // markdown/emoji are tolerated only as a strip-and-retry fallback, so a
-            // miss usually means the text differs from what's on the page.
-            const hint = opts.anchorText
-                ? " anchorText must be the block's literal rendered plain text (no markdown wrappers or emoji); anchorNodeId from get_page_json is more reliable."
-                : "";
-            throw new Error(`insert_node: anchor not found (${anchorDesc}) on page ${pageId}.${hint}`);
-        }
-        return {
-            success: true,
-            inserted: true,
-            position: opts.position,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Remove EVERY node whose attrs.id === nodeId (recursively, including nodes
-     * nested in callouts/tables) from its parent content array. Operates on the
-     * LIVE collab document so comments and concurrent edits are preserved.
-     * Throws if no node matches.
-     */
-    async deleteNode(pageId, nodeId) {
-        await this.ensureAuthenticated();
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Track the deletion count in an outer var, reset per-transform, so a
-        // collab retry recomputes it cleanly (mirrors replaceImage's pattern).
-        let deleted = 0;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            deleted = 0;
-            const { doc: nd, deleted: d } = deleteNodeById(liveDoc, nodeId);
-            deleted = d;
-            // 0 matches -> skip the write. >1 matches -> the id is AMBIGUOUS (block
-            // ids are duplicated on copy/paste, #159): deleting "the node with id X"
-            // would silently remove EVERY duplicate. Refuse: skip the write and throw
-            // below so the model re-targets. Only an unambiguous single match is
-            // deleted.
-            if (deleted !== 1)
-                return null;
-            return nd;
-        });
-        // 0 -> "no node"; >1 -> "ambiguous, refused" (the transform already skipped
-        // the write for any count !== 1). Single shared guard (#159, #185 review).
-        assertUnambiguousMatch("delete_node", "delete", deleted, nodeId, pageId);
-        return { success: true, deleted, nodeId, verify: mutation.verify };
-    }
-    /** Build the public share URL for a page. */
-    shareUrl(shareKey, slugId) {
-        return `${this.appUrl}/share/${shareKey}/p/${slugId}`;
-    }
-    /** Share a page publicly (idempotent) and return the public URL. */
-    async sharePage(pageId, searchIndexing = true) {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/shares/create", {
-            pageId,
-            includeSubPages: false,
-            searchIndexing,
-        });
-        const share = response.data?.data ?? response.data;
-        const slugId = share.page?.slugId || (await this.getPageRaw(pageId)).slugId;
-        return {
-            shareId: share.id,
-            key: share.key,
-            pageId: share.pageId,
-            publicUrl: this.shareUrl(share.key, slugId),
-            searchIndexing: share.searchIndexing,
-        };
-    }
-    /** List all public shares in the workspace with their URLs. */
-    async listShares() {
-        const shares = await this.paginateAll("/shares", {});
-        return shares.map((s) => ({
-            shareId: s.id,
-            key: s.key,
-            pageId: s.pageId,
-            pageTitle: s.page?.title,
-            publicUrl: s.page?.slugId ? this.shareUrl(s.key, s.page.slugId) : null,
-            searchIndexing: s.searchIndexing,
-            createdAt: s.createdAt,
-        }));
-    }
-    /** Remove the public share of a page. */
-    async unsharePage(pageId) {
-        await this.ensureAuthenticated();
-        const shares = await this.listShares();
-        const share = shares.find((s) => s.pageId === pageId);
-        if (!share) {
-            throw new Error(`Page ${pageId} is not shared.`);
-        }
-        await this.client.post("/shares/delete", { shareId: share.shareId });
-        return { success: true, removedShareId: share.shareId, pageId };
-    }
-    async search(query, spaceId, limit) {
-        await this.ensureAuthenticated();
-        const payload = { query, spaceId };
-        // Clamp an optional caller-supplied limit into a sane 1..100 range before
-        // forwarding it to the server; omit it entirely when not provided so the
-        // server applies its own default.
-        if (limit !== undefined) {
-            payload.limit = Math.max(1, Math.min(100, limit));
-        }
-        const response = await this.client.post("/search", payload);
-        // Normalize both response shapes: bare array and paginated { items: [...] }
-        const data = response.data?.data;
-        const items = Array.isArray(data) ? data : data?.items || [];
-        const filteredItems = items.map((item) => filterSearchResult(item));
-        return {
-            items: filteredItems,
-            success: response.data?.success || false,
-        };
-    }
-    async movePage(pageId, parentPageId, position) {
-        await this.ensureAuthenticated();
-        // Docmost requires position >= 5 chars.
-        const validPosition = position || "a00000";
-        return this.client
-            .post("/pages/move", {
-            pageId,
-            parentPageId,
-            position: validPosition,
-        })
-            .then((res) => res.data);
-    }
-    async deletePage(pageId) {
-        await this.ensureAuthenticated();
-        return this.client
-            .post("/pages/delete", { pageId })
-            .then((res) => res.data);
-    }
-    // --- Comment methods (ported from upstream PR #3 by Max Nikitin) ---
-    /**
-     * Normalize a comment's `content` into a ProseMirror doc object before
-     * markdown conversion. createComment/updateComment send content as a
-     * JSON.stringify(...) STRING, and the server stores it as-is, so on read it
-     * comes back as a string. convertProseMirrorToMarkdown returns "" for a
-     * string, so parse it first (guarded — fall back to the raw value on any
-     * parse failure so a non-JSON legacy value is still handled gracefully).
-     */
-    parseCommentContent(content) {
-        if (typeof content !== "string")
-            return content;
-        try {
-            return JSON.parse(content);
-        }
-        catch {
-            return content;
-        }
-    }
-    /** List all comments on a page (cursor-paginated), content as markdown. */
-    async listComments(pageId) {
-        await this.ensureAuthenticated();
-        let allComments = [];
-        let cursor = null;
-        do {
-            const payload = { pageId, limit: 100 };
-            if (cursor)
-                payload.cursor = cursor;
-            const response = await this.client.post("/comments", payload);
-            const data = response.data.data || response.data;
-            const items = data.items || [];
-            allComments = allComments.concat(items);
-            cursor = data.meta?.nextCursor || null;
-        } while (cursor);
-        return allComments.map((comment) => {
-            const markdown = comment.content
-                ? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
-                : "";
-            return filterComment(comment, markdown);
-        });
-    }
-    async getComment(commentId) {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/comments/info", { commentId });
-        const comment = response.data.data || response.data;
-        const markdown = comment.content
-            ? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
-            : "";
-        return {
-            data: filterComment(comment, markdown),
-            success: true,
-        };
-    }
-    /**
-     * Create an inline comment anchored to its `selection` text, or a reply.
-     *
-     * Top-level comments (no `parentCommentId`) are ALWAYS inline and MUST carry a
-     * `selection`: the `type` argument is kept for interface compatibility but the
-     * effective type is coerced to "inline". The selection has to anchor in the
-     * document; if it cannot, the comment is rolled back and an error is thrown so
-     * the caller is forced to supply a proper inline selection rather than leaving
-     * an orphan, unanchored comment behind. Replies (parentCommentId set) inherit
-     * their parent's anchor: they take NO selection and are not anchored.
-     */
-    async createComment(pageId, content, type = "page", selection, parentCommentId, suggestedText) {
-        await this.ensureAuthenticated();
-        const isReply = !!parentCommentId;
-        const hasSuggestion = suggestedText !== undefined && suggestedText !== null;
-        // Defense in depth mirroring the server DTO/service: a suggested edit rewrites
-        // the exact anchored text, so it is only meaningful on a top-level inline
-        // comment that carries a selection.
-        if (hasSuggestion) {
-            if (isReply) {
-                throw new Error("create_comment: a suggested edit (suggestedText) cannot be attached to a reply; it applies only to a top-level inline comment.");
-            }
-            if (!selection || !selection.trim()) {
-                throw new Error("create_comment: a suggested edit (suggestedText) requires a 'selection' to anchor and rewrite.");
-            }
-        }
-        // Only top-level comments are inline-anchored, so they are stored as
-        // "inline". Replies carry no inline selection, so they keep the historical
-        // general ("page") type — both backward-compatible and semantically correct.
-        // The `type` argument is kept for interface compatibility; createComment
-        // normalizes the effective type internally, so callers may pass "inline".
-        const effectiveType = isReply ? "page" : "inline";
-        if (!isReply && (!selection || !selection.trim())) {
-            throw new Error("create_comment: an inline 'selection' (exact text to anchor on) is required for a top-level comment");
-        }
-        // For a SUGGESTION, the value we store as the comment's `selection` must be
-        // the RAW document substring the mark lands on (typographic quotes/dashes,
-        // nbsp, collapsed whitespace), NOT the agent's ASCII input. The anchor is
-        // placed via normalization, so when the doc was auto-converted to
-        // typographic the raw substring differs from the agent input; apply-time
-        // compares the stored selection to the marked doc text STRICTLY, so storing
-        // the raw substring is what makes "Apply" succeed instead of a spurious 409.
-        // Captured in the pre-check below (which already reads the page) and used as
-        // payload.selection. Ordinary comments keep sending the raw agent selection.
-        let anchoredSelection = null;
-        // For a top-level comment, fail BEFORE creating anything when the selection
-        // is not present in the persisted document — this avoids leaving an orphan
-        // comment + notification behind. A read failure (network) is non-fatal: the
-        // live anchor step below still enforces the anchoring invariant.
-        if (!isReply && selection) {
-            try {
-                const page = await this.getPageJson(pageId);
-                if (hasSuggestion) {
-                    // A suggestion's anchor MUST be unambiguous: applying it rewrites the
-                    // exact anchored text, and ordinary anchoring silently takes the first
-                    // occurrence, so 0 matches -> not found and >=2 -> ambiguous, both
-                    // rejected BEFORE creating the comment.
-                    const matches = countAnchorMatches(page.content, selection);
-                    if (matches === 0) {
-                        throw new Error("create_comment: could not find the selection text in the page to anchor the comment. " +
-                            "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).");
-                    }
-                    if (matches >= 2) {
-                        throw new Error(`create_comment: the suggestion's selection is ambiguous — it occurs ${matches} times in the page. ` +
-                            "A suggested edit must anchor to a UNIQUE location; expand the selection with surrounding context " +
-                            "(still <=250 chars) so it appears exactly once.");
-                    }
-                    // Exactly one match: capture the RAW anchored substring to store as the
-                    // comment selection (so apply-time equality holds). If this returns
-                    // null despite countAnchorMatches===1 (shouldn't happen), fall back to
-                    // the raw agent selection below rather than crash.
-                    anchoredSelection = getAnchoredText(page.content, selection);
-                }
-                else if (!canAnchorInDoc(page.content, selection)) {
-                    throw new Error("create_comment: could not find the selection text in the page to anchor the comment. " +
-                        "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).");
-                }
-            }
-            catch (e) {
-                // Rethrow our own "not found"/"ambiguous" errors; swallow read/network
-                // errors so the live anchor step can still try (and enforce) anchoring.
-                if (e instanceof Error &&
-                    (e.message.startsWith("create_comment: could not find the selection") ||
-                        e.message.startsWith("create_comment: the suggestion's selection is ambiguous"))) {
-                    throw e;
-                }
-                if (process.env.DEBUG) {
-                    console.error("Pre-check getPageJson failed; deferring to live anchor step:", e);
-                }
-            }
-        }
-        // Convert through the full Docmost schema. Deliberately the NON-canonicalizing
-        // variant: a comment body may carry a footnote definition with no matching
-        // reference, and canonicalization would drop it (data loss). See
-        // markdownToProseMirror vs markdownToProseMirrorCanonical.
-        const jsonContent = await markdownToProseMirror(content);
-        const payload = {
-            pageId,
-            content: JSON.stringify(jsonContent),
-            type: effectiveType,
-        };
-        // For a suggestion, store the RAW anchored substring (anchoredSelection) so
-        // the stored selection === the text under the mark === apply-time
-        // expectedText. Ordinary comments (and the null fallback) keep the raw
-        // agent selection — their selection is only display/anchor and never used
-        // by apply, so their behavior is unchanged.
-        if (!isReply && selection)
-            payload.selection = anchoredSelection ?? selection;
-        if (parentCommentId)
-            payload.parentCommentId = parentCommentId;
-        // Only a top-level inline comment (with a selection) may carry a suggestion.
-        if (!isReply && selection && hasSuggestion) {
-            payload.suggestedText = suggestedText;
-        }
-        const response = await this.client.post("/comments/create", payload);
-        const comment = response.data.data || response.data;
-        const markdown = comment.content
-            ? convertProseMirrorToMarkdown(this.parseCommentContent(comment.content))
-            : content;
-        const result = {
-            data: filterComment(comment, markdown),
-            success: true,
-        };
-        // Replies inherit the parent's anchor: no selection, no anchoring.
-        if (isReply) {
-            return result;
-        }
-        // Anchor the comment in the document. The /comments/create API records the
-        // comment + its `selection` text, but it does NOT insert the comment MARK
-        // into the page content, so without this the inline comment has no
-        // highlight/anchor and is not clickable. If anchoring fails the comment is
-        // rolled back (deleted) and an error is thrown — never an orphan comment.
-        const newCommentId = comment.id;
-        // Guard: a create response without an id would mean writing a comment mark
-        // with commentId: undefined and a later delete of a falsy id. We have no id
-        // to roll back here (nothing was created with an id), so just fail loudly.
-        if (!newCommentId) {
-            throw new Error("create_comment: the server returned no comment id, so the comment could not be anchored");
-        }
-        let anchored = false;
-        // Set inside the transform when a suggestion's live anchor is ambiguous
-        // (>=2 occurrences), so the rollback path can surface the right error.
-        let ambiguousInLiveDoc = false;
-        try {
-            const collabToken = await this.getCollabTokenWithReauth();
-            // Open the collab doc by the canonical UUID, never the slugId (#260). The
-            // /comments/create REST call above keeps the agent-supplied id.
-            const pageUuid = await this.resolvePageId(pageId);
-            // Route through the mutatePage seam (not the free function) so this
-            // wrapper's uniqueness gate + rollback can be unit-tested without a live
-            // Hocuspocus collab socket.
-            const mutation = await this.mutatePage(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-                const doc = liveDoc && liveDoc.type === "doc"
-                    ? liveDoc
-                    : { type: "doc", content: [] };
-                if (hasSuggestion) {
-                    // Authoritative uniqueness check against the LIVE document: a
-                    // suggestion must anchor to EXACTLY ONE occurrence, otherwise
-                    // "Apply" would rewrite the wrong/ambiguous text. If the live doc
-                    // no longer has exactly one occurrence (it changed since the
-                    // pre-check), abort so the just-created comment is rolled back
-                    // rather than mis-anchored to the first occurrence.
-                    const liveCount = countAnchorMatches(doc, selection);
-                    if (liveCount !== 1) {
-                        ambiguousInLiveDoc = liveCount >= 2;
-                        return null;
-                    }
-                }
-                if (applyAnchorInDoc(doc, selection, newCommentId)) {
-                    anchored = true;
-                    return doc;
-                }
-                // Selection text not found in the LIVE document: abort the write. The
-                // rollback + throw below turns this into a hard error.
-                return null;
-            });
-            result.verify = mutation.verify;
-        }
-        catch (e) {
-            // The comment record already exists; roll it back so we never leave an
-            // orphan, then rethrow the original anchoring error.
-            await this.safeDeleteComment(newCommentId);
-            throw e;
-        }
-        if (!anchored) {
-            // Mutation aborted because the selection was not found (or, for a
-            // suggestion, was ambiguous) in the live document. Roll back the comment
-            // and surface a hard error.
-            await this.safeDeleteComment(newCommentId);
-            throw new Error(ambiguousInLiveDoc
-                ? "create_comment: the suggestion's selection is ambiguous in the live document (multiple occurrences); the comment was rolled back. Expand the selection with surrounding context so it is unique."
-                : "create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back");
-        }
-        result.anchored = true;
-        return result;
-    }
-    /**
-     * Best-effort rollback of a just-created comment. Swallows any delete failure
-     * (logging under DEBUG) so a failed cleanup never masks the original error.
-     */
-    async safeDeleteComment(commentId) {
-        // Defense in depth: never call the delete API with a falsy id — there is
-        // nothing to roll back, and deleteComment(undefined) would hit a bad route.
-        if (!commentId)
-            return;
-        try {
-            await this.deleteComment(commentId);
-        }
-        catch (delErr) {
-            if (process.env.DEBUG) {
-                console.error("Failed to roll back comment after anchoring error:", delErr);
-            }
-        }
-    }
-    async updateComment(commentId, content) {
-        await this.ensureAuthenticated();
-        // NON-canonicalizing on purpose (comment body — see createComment).
-        const jsonContent = await markdownToProseMirror(content);
-        await this.client.post("/comments/update", {
-            commentId,
-            content: JSON.stringify(jsonContent),
-        });
-        return {
-            success: true,
-            commentId,
-            message: "Comment updated successfully.",
-        };
-    }
-    async deleteComment(commentId) {
-        await this.ensureAuthenticated();
-        return this.client
-            .post("/comments/delete", { commentId })
-            .then((res) => res.data);
-    }
-    /**
-     * Resolve or reopen a top-level comment thread (reversible — `resolved`
-     * toggles the state). Only top-level comments can be resolved; the server
-     * rejects resolving a reply. Hits POST /comments/resolve.
-     */
-    async resolveComment(commentId, resolved) {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/comments/resolve", {
-            commentId,
-            resolved,
-        });
-        const comment = response.data?.data ?? response.data;
-        return {
-            success: true,
-            commentId,
-            resolved,
-            comment,
-        };
-    }
-    /**
-     * Check for new comments across pages in a space (optionally scoped to a
-     * subtree): pages updated after `since` are scanned and their comments
-     * filtered by createdAt > since.
-     */
-    async checkNewComments(spaceId, since, parentPageId) {
-        await this.ensureAuthenticated();
-        const sinceDate = new Date(since);
-        // Reject an unparseable `since`: comparing against an Invalid Date silently
-        // yields zero new comments (every `>` against NaN is false), which would
-        // mask a malformed input as "nothing new" instead of erroring.
-        if (Number.isNaN(sinceDate.getTime())) {
-            throw new Error(`checkNewComments: invalid "since" date "${since}"; expected an ISO-8601 timestamp`);
-        }
-        // 1. Enumerate the FULL set of pages in scope by walking the sidebar-pages
-        // tree (a complete page index), NOT the bounded "/pages/recent" feed which
-        // caps at ~5000 recent items and silently misses comments on older pages.
-        //
-        // Subtree scope: when parentPageId is given, the scope is that page ITSELF
-        // plus every descendant (enumerateSpacePages walks its children). Otherwise
-        // the scope is the whole space (all roots and their descendants).
-        //
-        // NOTE: do NOT pre-filter by page.updatedAt — creating a comment does not
-        // bump it (verified on a live server), so such a filter silently misses
-        // comments on pages that were not otherwise edited. The complete tree walk
-        // already restricts the scope correctly, so no recent-feed allow-list is
-        // needed any more.
-        let pagesInScope;
-        if (parentPageId) {
-            const subtree = await this.enumerateSpacePages(spaceId, parentPageId);
-            // Include the parent page node itself alongside its descendants. Fetch it
-            // so its title/id are available even though it is not returned by its own
-            // children listing.
-            let parentNode = { id: parentPageId };
-            try {
-                parentNode = await this.getPageRaw(parentPageId);
-            }
-            catch (e) {
-                // Fall back to a minimal node if the parent can't be fetched; its
-                // comments are still attempted below (the fetch there is non-fatal).
-            }
-            pagesInScope = [parentNode, ...subtree];
-        }
-        else {
-            pagesInScope = await this.enumerateSpacePages(spaceId);
-        }
-        // 2. Fetch comments for each page, keep ones created after since
-        const results = [];
-        for (const page of pagesInScope) {
-            try {
-                const comments = await this.listComments(page.id);
-                const newComments = comments.filter((c) => new Date(c.createdAt) > sinceDate);
-                if (newComments.length > 0) {
-                    results.push({
-                        pageId: page.id,
-                        pageTitle: page.title,
-                        comments: newComments,
-                    });
-                }
-            }
-            catch (e) {
-                // Skip pages with errors (e.g. deleted between calls)
-            }
-        }
-        const totalNewComments = results.reduce((sum, r) => sum + r.comments.length, 0);
-        // enumerateSpacePages caps traversal at 10000 nodes; flag when that cap was
-        // hit so the caller knows the scan may be incomplete (some pages skipped).
-        const truncated = pagesInScope.length >= 10000;
-        return {
-            since,
-            scope: parentPageId ? `subtree of ${parentPageId}` : `space ${spaceId}`,
-            checkedPages: pagesInScope.length,
-            pagesWithNewComments: results.length,
-            totalNewComments,
-            truncated,
-            comments: results,
-        };
-    }
-    // --- Image upload / embedding ---
-    /** Map a Content-Type string to a supported MIME type, or null if unsupported. */
-    supportedImageMime(ct) {
-        return MIME_TO_EXT[ct] ? ct : null;
-    }
-    /**
-     * Download a remote image from a caller-supplied URL and resolve its bytes,
-     * MIME and a filename.
-     *
-     * SSRF / RESOURCE TRUST BOUNDARY: the URL comes from the MCP caller and is
-     * fetched BY THE SERVER, so it must be guarded before and after the request.
-     * The guards mirror the local-file trust boundary in uploadImage:
-     *   - scheme allowlist (http/https only) — rejects file:, data:, ftp:, etc.,
-     *     so the caller cannot use this path to read local files or other schemes;
-     *   - a size cap enforced both via axios maxContentLength/maxBodyLength AND a
-     *     post-download buffer.length re-check (defends against a missing/lying
-     *     Content-Length), so a huge response cannot exhaust memory;
-     *   - a 30s timeout. The timeout matters because replaceImage holds the
-     *     per-page lock across this upload, so a hung download would wedge the
-     *     lock for that page.
-     * We deliberately do NOT block private IP ranges: the MCP caller is already
-     * trusted to read arbitrary host files via the filePath path, so the marginal
-     * trust granted by fetching internal URLs is comparable, and blocking would
-     * break legitimate internal-image use.
-     */
-    async fetchRemoteImage(url, maxBytes) {
-        // Scheme allowlist first — cheapest guard, and rejects non-http(s) schemes
-        // (file:, data:, ftp:, ...) before any network request is made.
-        let parsed;
-        try {
-            parsed = new URL(url);
-        }
-        catch (e) {
-            throw new Error(`Invalid image URL "${url}": ${e.message}`);
-        }
-        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            throw new Error(`unsupported image URL scheme "${parsed.protocol}"; only http and https are allowed`);
-        }
-        let response;
-        try {
-            response = await axios.get(url, {
-                responseType: "arraybuffer",
-                timeout: 30000,
-                maxContentLength: maxBytes,
-                maxBodyLength: maxBytes,
-                headers: { Accept: "image/*" },
-            });
-        }
-        catch (error) {
-            // Keep the thrown message free of the raw response body (it may echo
-            // server internals); surface only status/statusText. The full body is
-            // logged under DEBUG for diagnostics.
-            if (axios.isAxiosError(error)) {
-                if (process.env.DEBUG) {
-                    console.error("Image download failed; response body:", JSON.stringify(error.response?.data));
-                }
-                throw new Error(`Image download failed for "${url}": ${error.response?.status ?? ""} ${error.response?.statusText ?? error.message}`.trim());
-            }
-            throw error;
-        }
-        // axios returns an ArrayBuffer for responseType: "arraybuffer".
-        const buffer = Buffer.from(response.data);
-        // Re-check the size: maxContentLength relies on Content-Length, which may be
-        // absent or lie, so guard against the actual byte count too.
-        if (buffer.length === 0) {
-            throw new Error(`Empty image response from "${url}"`);
-        }
-        if (buffer.length > maxBytes) {
-            throw new Error(`Image too large: ${buffer.length} bytes exceeds the ${maxBytes}-byte cap`);
-        }
-        // Resolve MIME: prefer the response Content-Type (strip any "; charset=..."
-        // parameter, lowercase, trim) mapped through the supported set; if the
-        // header is generic/missing/unsupported, fall back to the URL path
-        // extension via the existing extension->MIME logic.
-        const rawCt = response.headers?.["content-type"];
-        let mime = null;
-        if (typeof rawCt === "string" && rawCt.length > 0) {
-            const ct = rawCt.split(";")[0].trim().toLowerCase();
-            mime = this.supportedImageMime(ct);
-        }
-        if (!mime) {
-            // Fall back to the URL path extension. Use the pathname so the query
-            // string never contaminates the extension lookup.
-            const ext = extname(parsed.pathname).toLowerCase();
-            mime = EXT_TO_MIME[ext] ?? null;
-        }
-        if (!mime) {
-            throw new Error(`cannot determine supported image type for "${url}"; supported: png, jpg, jpeg, gif, webp, svg`);
-        }
-        // Build a filename from the URL path basename (ignore the query string),
-        // defaulting to "image" when empty, and ensure it ends with the canonical
-        // extension for the resolved MIME (append it when missing/mismatched).
-        const canonicalExt = MIME_TO_EXT[mime];
-        let fileName = basename(parsed.pathname) || "image";
-        if (extname(fileName).toLowerCase() !== canonicalExt) {
-            fileName += canonicalExt;
-        }
-        return { buffer, mime, fileName };
-    }
-    /** Build a Docmost ProseMirror image node from an uploaded attachment. */
-    buildImageNode(att, align, alt) {
-        // Clean file URL, matching Docmost's native behaviour. No cache-busting
-        // query: the server serves the bare URL correctly, and replacement creates
-        // a new attachment id (a new URL) which busts caches naturally.
-        const src = `/api/files/${att.id}/${att.fileName}`;
-        const node = {
-            type: "image",
-            attrs: {
-                src,
-                attachmentId: att.id,
-                // Default to null when the server omits fileSize so the attr is never
-                // undefined (undefined would be dropped on serialization / break the
-                // ProseMirror image schema which expects size present).
-                size: att.fileSize ?? null,
-                align: align || "center",
-                width: null,
-            },
-        };
-        if (alt)
-            node.attrs.alt = alt;
-        return node;
-    }
-    /**
-     * Download a remote image from an http(s) URL and upload it as an attachment
-     * of a page, returning the attachment metadata plus a ready-to-insert
-     * ProseMirror image node. Local file paths are intentionally not supported:
-     * the MCP caller is a remote AI with no access to this server's filesystem.
-     */
-    async uploadImage(pageId, url) {
-        await this.ensureAuthenticated();
-        const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // 20 MiB
-        // Fetch + validate the remote image (scheme allowlist, size cap, timeout).
-        // See fetchRemoteImage for the SSRF / resource trust boundary.
-        const fetched = await this.fetchRemoteImage(url, MAX_IMAGE_BYTES);
-        const fileBuffer = fetched.buffer;
-        const mime = fetched.mime;
-        const fileName = fetched.fileName;
-        // Build a FRESH FormData for every send attempt. A FormData body is a
-        // single-use stream that is CONSUMED on the first send, so it cannot be
-        // replayed by this.client's response interceptor (replaying a consumed
-        // stream fails with 'socket hang up'). Multipart re-auth is therefore done
-        // here with bare axios and an explicit one-shot 401/403 retry that rebuilds
-        // the body. Field order matters: text fields must precede the file part so
-        // the server reads them; the server always generates a fresh attachment id.
-        const buildForm = () => {
-            const form = new FormData();
-            form.append("pageId", pageId);
-            form.append("file", fileBuffer, {
-                filename: fileName,
-                contentType: mime,
-            });
-            return form;
-        };
-        // Local name distinct from the `url` parameter (the source image URL): this
-        // is the /files/upload endpoint we POST the multipart body to.
-        const uploadUrl = `${this.apiUrl}/files/upload`;
-        let response;
-        try {
-            // Call buildForm() ONCE per attempt and reuse the instance for both
-            // getHeaders() and the body so the Content-Type boundary matches the body.
-            const form = buildForm();
-            // Read the Authorization header from this.client's defaults (set by
-            // login(), only ever deleted — never set to null) instead of building
-            // `Bearer ${this.token}`: a concurrent JSON 401 can null this.token
-            // mid-flight, which would otherwise produce a literal "Bearer null".
-            // ensureAuthenticated() above guarantees login() ran, so the default
-            // header exists here. A 60s timeout keeps a hung upload from wedging the
-            // per-page lock (replaceImage holds withPageLock across this call).
-            response = await axios.post(uploadUrl, form, {
-                headers: {
-                    ...form.getHeaders(),
-                    Authorization: this.client.defaults.headers.common["Authorization"],
-                },
-                timeout: 60000,
-            });
-        }
-        catch (error) {
-            // On an expired-token auth error, re-login and retry exactly once with a
-            // freshly-rebuilt FormData (the previous one was already consumed).
-            if (axios.isAxiosError(error) &&
-                (error.response?.status === 401 || error.response?.status === 403)) {
-                await this.login();
-                const form2 = buildForm();
-                response = await axios.post(uploadUrl, form2, {
-                    headers: {
-                        ...form2.getHeaders(),
-                        Authorization: this.client.defaults.headers.common["Authorization"],
-                    },
-                    timeout: 60000,
-                });
-            }
-            else if (axios.isAxiosError(error)) {
-                // Keep the thrown message free of the raw response body (it may echo
-                // request data or server internals); surface only status/statusText.
-                // The full body is logged under DEBUG for diagnostics.
-                if (process.env.DEBUG) {
-                    console.error("Image upload failed; response body:", JSON.stringify(error.response?.data));
-                }
-                throw new Error(`Image upload failed: ${error.response?.status} ${error.response?.statusText}`);
-            }
-            else {
-                throw error;
-            }
-        }
-        // The attachment may arrive bare or wrapped in a { data } envelope.
-        const att = response.data?.data ?? response.data;
-        if (!att?.id || !att?.fileName) {
-            throw new Error("Unexpected /files/upload response: " + JSON.stringify(response.data));
-        }
-        // Some Docmost versions omit fileSize from the upload response. Fall back
-        // to the fetched byte length (the bytes we just uploaded) so callers never
-        // get an undefined size.
-        const resolvedSize = att.fileSize ?? fileBuffer.length;
-        return {
-            attachmentId: att.id,
-            fileName: att.fileName,
-            fileSize: resolvedSize,
-            src: `/api/files/${att.id}/${att.fileName}`,
-            imageNode: this.buildImageNode({ ...att, fileSize: resolvedSize }),
-        };
-    }
-    /**
-     * Upload an image from a web (http/https) URL and insert it into a page in
-     * one step.
-     * By default the image is appended at the end. With replaceText, the first
-     * top-level block whose text contains the string is replaced; with afterText,
-     * the image is inserted right after the first matching block. All other
-     * block ids are preserved (only one top-level block is added or swapped).
-     */
-    async insertImage(pageId, url, opts = {}) {
-        const up = await this.uploadImage(pageId, url);
-        // Reuse the node from uploadImage (clean /api/files/<id>/<file> src), then
-        // apply align/alt onto a shallow attrs copy.
-        const node = { ...up.imageNode, attrs: { ...up.imageNode.attrs } };
-        if (opts.align)
-            node.attrs.align = opts.align;
-        if (opts.alt)
-            node.attrs.alt = opts.alt;
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260). The
-        // uploadImage /files/upload call above keeps the agent-supplied id.
-        const pageUuid = await this.resolvePageId(pageId);
-        // Recursively collect the plain text of a top-level block.
-        const blockText = (n) => {
-            let out = "";
-            if (n.type === "text")
-                out += n.text || "";
-            for (const child of n.content || [])
-                out += blockText(child);
-            return out;
-        };
-        // Insert into the LIVE synced document, not the debounced REST snapshot, so
-        // concurrent edits/comments/images are preserved and parallel insert_image
-        // calls (serialized by the per-page lock) each see the previous insertion.
-        let placement;
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, (liveDoc) => {
-            const doc = liveDoc && liveDoc.type === "doc"
-                ? liveDoc
-                : { type: "doc", content: [] };
-            if (!Array.isArray(doc.content))
-                doc.content = [];
-            if (opts.replaceText) {
-                // Ambiguity guard (mirrors editPageText): count matching top-level
-                // blocks first, so a non-unique fragment cannot silently replace the
-                // wrong block (e.g. text that also appears inside a callout/table).
-                const matches = doc.content.filter((b) => blockText(b).includes(opts.replaceText));
-                if (matches.length === 0) {
-                    throw new Error(`replaceText not found: "${opts.replaceText}"`);
-                }
-                if (matches.length > 1) {
-                    throw new Error(`replaceText "${opts.replaceText}" matches ${matches.length} blocks; use a longer unique fragment`);
-                }
-                const idx = doc.content.findIndex((b) => blockText(b).includes(opts.replaceText));
-                // Data-loss guard: replaceText swaps the WHOLE top-level block, so if
-                // the fragment only appears nested inside a container (table, callout,
-                // list, blockquote) the entire structure would be destroyed. Refuse
-                // when the matched block is a container rather than a leaf
-                // paragraph/heading and point the caller at a safer tool.
-                const CONTAINER_TYPES = new Set([
-                    "table",
-                    "callout",
-                    "bulletList",
-                    "orderedList",
-                    "taskList",
-                    "blockquote",
-                ]);
-                const matchedBlock = doc.content[idx];
-                if (matchedBlock && CONTAINER_TYPES.has(matchedBlock.type)) {
-                    throw new Error(`replaceText matched a ${matchedBlock.type} container block; replacing it would destroy the whole structure. ` +
-                        `Use afterText to insert near it, or update_page_json for surgical edits.`);
-                }
-                doc.content.splice(idx, 1, node);
-                placement = "replaced";
-            }
-            else if (opts.afterText) {
-                // Ambiguity guard (mirrors editPageText): refuse a non-unique fragment.
-                const matches = doc.content.filter((b) => blockText(b).includes(opts.afterText));
-                if (matches.length === 0) {
-                    throw new Error(`afterText not found: "${opts.afterText}"`);
-                }
-                if (matches.length > 1) {
-                    throw new Error(`afterText "${opts.afterText}" matches ${matches.length} blocks; use a longer unique fragment`);
-                }
-                const idx = doc.content.findIndex((b) => blockText(b).includes(opts.afterText));
-                doc.content.splice(idx + 1, 0, node);
-                placement = "after";
-            }
-            else {
-                doc.content.push(node);
-                placement = "appended";
-            }
-            return doc;
-        });
-        return {
-            success: true,
-            pageId,
-            attachmentId: up.attachmentId,
-            src: up.src,
-            placement,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Replace an existing image in a page with a new image fetched from a web
-     * (http/https) URL. Uploads the new file as a brand-new attachment, which
-     * yields a fresh clean URL that both renders correctly and busts browser
-     * caches (the URL changed). Finds every image node
-     * whose attrs.attachmentId === oldAttachmentId (recursively, incl. nodes nested
-     * in callouts/tables) and repoints its src/attachmentId/size, preserving
-     * comments, alignment and alt. Operates on the live collab document so comments
-     * and concurrent edits are preserved. Throws if no matching image is found.
-     *
-     * The OLD attachment is left in place as an unreferenced orphan: Docmost
-     * exposes NO HTTP API to delete a single content attachment (verified against
-     * the attachment controller/service and by probing the live API — deletion
-     * happens only by cascade when the page, space or user is removed). This is the
-     * same outcome as Docmost's own editor when an image is removed/replaced.
-     * In-place byte overwrite is deliberately NOT used because some Docmost
-     * versions corrupt the attachment (HTTP 500) when its bytes are overwritten.
-     */
-    async replaceImage(pageId, oldAttachmentId, url, opts = {}) {
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260). The
-        // page lock must ALSO key on the UUID so this operation serializes against
-        // other writes to the same page (mutatePageContent now locks by the resolved
-        // UUID too); locking by the raw slugId here would desync the mutex key and
-        // reopen the TOCTOU/orphan-attachment window the lock closes. uploadImage
-        // keeps the agent-supplied id (it hits REST, not the collab doc).
-        const pageUuid = await this.resolvePageId(pageId);
-        // Hold ONE per-page lock for the WHOLE operation (scan -> upload -> write).
-        // Previously the scan and the write were two separate mutatePageContent
-        // calls, each acquiring + releasing the lock, with the upload happening in
-        // the UNLOCKED gap between them. A concurrent op could interleave there: it
-        // could remove the target image so the write pass matches nothing, leaving
-        // the freshly-uploaded attachment as an un-deletable orphan (Docmost has no
-        // API to delete a single content attachment). Acquiring the lock once and
-        // using the non-locking collab helper inside (the per-page mutex is NOT
-        // reentrant, so the self-locking mutatePageContent would deadlock here)
-        // closes that TOCTOU window. uploadImage hits /files/upload over plain HTTP
-        // and does not touch the page lock, so it is safe to call while held.
-        return withPageLock(pageUuid, async () => {
-            // STEP 1: read-only live check. Scan the live document for any image node
-            // matching oldAttachmentId BEFORE uploading anything, so a wrong/stale id
-            // throws without ever creating an orphan attachment.
-            let matchFound = false;
-            const scan = (nodes) => {
-                for (const node of nodes) {
-                    if (!node)
-                        continue;
-                    if (node.type === "image" &&
-                        node.attrs &&
-                        node.attrs.attachmentId === oldAttachmentId) {
-                        matchFound = true;
-                    }
-                    if (Array.isArray(node.content))
-                        scan(node.content);
-                }
-            };
-            await this.mutateLiveContentUnlocked(pageUuid, collabToken, (liveDoc) => {
-                matchFound = false; // reset per-transform (collab may retry the read).
-                const doc = liveDoc && liveDoc.type === "doc"
-                    ? liveDoc
-                    : { type: "doc", content: [] };
-                if (Array.isArray(doc.content))
-                    scan(doc.content);
-                return null; // read-only: never write on the check pass.
-            });
-            if (!matchFound) {
-                throw new Error(`replace_image: no image with attachmentId "${oldAttachmentId}" found on page ${pageId}`);
-            }
-            // STEP 2: a match exists — upload the new file as a FRESH attachment (new
-            // id, new clean URL) and repoint every matching node in a second pass.
-            // Still inside the SAME lock, so no other op can have changed the page
-            // since the scan.
-            const up = await this.uploadImage(pageId, url);
-            let replaced = 0;
-            // Swap the source of one image node, preserving align/alt/title/geometry.
-            const repoint = (node) => {
-                node.attrs = {
-                    ...node.attrs,
-                    src: up.src,
-                    attachmentId: up.attachmentId,
-                    // Default to null when fileSize is unknown so the attr is never
-                    // undefined.
-                    size: up.fileSize ?? null,
-                };
-                if (opts.align)
-                    node.attrs.align = opts.align;
-                if (opts.alt !== undefined)
-                    node.attrs.alt = opts.alt;
-                replaced++;
-            };
-            // Recursively repoint every image node (incl. ones nested in callouts/tables).
-            const walk = (nodes) => {
-                for (const node of nodes) {
-                    if (!node)
-                        continue;
-                    if (node.type === "image" &&
-                        node.attrs &&
-                        node.attrs.attachmentId === oldAttachmentId) {
-                        repoint(node);
-                    }
-                    if (Array.isArray(node.content))
-                        walk(node.content);
-                }
-            };
-            const mutation = await this.mutateLiveContentUnlocked(pageUuid, collabToken, (liveDoc) => {
-                // Reset per-transform so collab retries recompute cleanly (no double-count).
-                replaced = 0;
-                const doc = liveDoc && liveDoc.type === "doc"
-                    ? liveDoc
-                    : { type: "doc", content: [] };
-                if (!Array.isArray(doc.content))
-                    doc.content = [];
-                walk(doc.content);
-                if (replaced === 0)
-                    return null; // no match -> skip the write entirely
-                return doc;
-            });
-            // KNOWN LIMITATION: a same-count image SRC swap (image count unchanged, no
-            // text/mark change) may still report verify.changed === false, because the
-            // text+marks+integrity-count model in summarizeChange does not inspect
-            // image `src`/attachmentId attributes. That is acceptable here — the
-            // replace is confirmed by `replaced` below, and verify is supplementary.
-            if (replaced === 0) {
-                // The pass-1 SCAN found the target (matchFound was true) and we already
-                // uploaded the new attachment, but pass-2 matched nothing — a concurrent
-                // editor must have removed the node between the two passes. Do NOT throw
-                // here (that would leak the just-uploaded attachment AND report failure);
-                // instead report success with the upload flagged as an unreferenced
-                // orphan so the caller knows. (The early throw above still covers the
-                // case where pass-1 finds nothing, before any upload happens.)
-                return {
-                    success: true,
-                    replaced: 0,
-                    pageId,
-                    oldAttachmentId,
-                    newAttachmentId: up.attachmentId,
-                    src: up.src,
-                    orphanedAttachmentId: up.attachmentId,
-                    warning: "target image was removed concurrently; uploaded attachment is unreferenced",
-                    verify: mutation.verify,
-                };
-            }
-            return {
-                success: true,
-                pageId,
-                replaced,
-                oldAttachmentId,
-                newAttachmentId: up.attachmentId,
-                src: up.src,
-                verify: mutation.verify,
-            };
-        });
-    }
-    // --- Page history / diff / transform ---
-    /**
-     * List the saved versions (history snapshots) of a page, newest first.
-     * Docmost auto-snapshots on every save. Returns one cursor-paginated page of
-     * results: `{ items, nextCursor }`. The history record's id field is `id`.
-     */
-    async listPageHistory(pageId, cursor) {
-        await this.ensureAuthenticated();
-        const payload = { pageId };
-        if (cursor)
-            payload.cursor = cursor;
-        const response = await this.client.post("/pages/history", payload);
-        const data = response.data?.data ?? response.data;
-        return {
-            items: data?.items ?? [],
-            nextCursor: data?.meta?.nextCursor ?? null,
-        };
-    }
-    /**
-     * Fetch a single page-history version including its lossless ProseMirror
-     * `content`. The version also carries pageId/title/createdAt.
-     */
-    async getPageHistory(historyId) {
-        await this.ensureAuthenticated();
-        const response = await this.client.post("/pages/history/info", {
-            historyId,
-        });
-        return response.data?.data ?? response.data;
-    }
-    /**
-     * "Restore" a version: Docmost has NO restore endpoint, so we take the
-     * version's `content` and write it as the page's current content via the live
-     * collab path (which itself creates a new history snapshot). Returns the
-     * affected pageId and the source historyId.
-     */
-    async restorePageVersion(historyId) {
-        await this.ensureAuthenticated();
-        const version = await this.getPageHistory(historyId);
-        if (!version ||
-            !version.pageId ||
-            !version.content ||
-            typeof version.content !== "object") {
-            throw new Error(`restore_page_version: history ${historyId} has no usable content`);
-        }
-        // Defense-in-depth: sanitize URLs in the restored content (parity with the
-        // JSON write path) before writing it back.
-        this.validateDocUrls(version.content);
-        const collabToken = await this.getCollabTokenWithReauth();
-        // version.pageId is the page entity id (already a UUID); resolvePageId
-        // short-circuits a UUID with no round-trip, so this is defensive only (#260).
-        const pageUuid = await this.resolvePageId(version.pageId);
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, () => version.content);
-        return {
-            pageId: version.pageId,
-            restoredFrom: historyId,
-            verify: mutation.verify,
-        };
-    }
-    /**
-     * Diff two versions of a page and return a Docmost-equivalent change set.
-     * `from`/`to` each resolve to a ProseMirror doc:
-     *   - null / undefined / "current" -> the page's CURRENT content;
-     *   - any other string             -> that historyId's content.
-     * Returns the diff plus the resolved version metadata for each side.
-     */
-    async diffPageVersions(pageId, from, to) {
-        await this.ensureAuthenticated();
-        const isCurrent = (v) => v == null || v === "" || v === "current";
-        const resolveSide = async (v) => {
-            if (isCurrent(v)) {
-                const raw = await this.getPageRaw(pageId);
-                return {
-                    doc: raw.content || { type: "doc", content: [] },
-                    meta: {
-                        kind: "current",
-                        pageId,
-                        title: raw.title,
-                        updatedAt: raw.updatedAt,
-                    },
-                };
-            }
-            const version = await this.getPageHistory(v);
-            return {
-                doc: version.content || { type: "doc", content: [] },
-                meta: {
-                    kind: "history",
-                    historyId: version.id,
-                    pageId: version.pageId,
-                    title: version.title,
-                    createdAt: version.createdAt,
-                },
-            };
-        };
-        const fromSide = await resolveSide(from);
-        const toSide = await resolveSide(to);
-        const diff = diffDocs(fromSide.doc, toSide.doc);
-        return { from: fromSide.meta, to: toSide.meta, diff };
-    }
-    /**
-     * Edit a page by running an arbitrary user-supplied JS transform against the
-     * live document, with a diff preview + page-history safety net.
-     *
-     * The transform string is evaluated as `(doc, ctx) => doc` inside a node:vm
-     * sandbox: it gets ONLY `{ doc, ctx, structuredClone, console }` as globals,
-     * a 5s timeout, and NO access to require/process/fs/network. It must return a
-     * `{ type: "doc" }` node, which is validated structurally before any write.
-     *
-     * `ctx` exposes:
-     *   - comments: the page's comments (fetched before the live read);
-     *   - log: an array the transform can push diagnostics to (via console.log);
-     *   - consume(id): mark a comment id as consumed (for deleteComments);
-     *   - helpers: the transforms.ts primitives + commentsToFootnotes.
-     *
-     * Footnote convention used by the helpers: footnote markers are plain "[N]"
-     * text in the body, and the notes are an orderedList under a heading whose
-     * text is "Примечания переводчика".
-     *
-     * dryRun (default true): read the page's current content, run the transform,
-     * and return `{ pushed:false, diff, log }` WITHOUT opening the collab socket.
-     * Otherwise the transform runs atomically inside mutatePageContent, optionally
-     * deletes consumed comments, and returns the new historyId + diff + log.
-     */
-    async transformPage(pageId, transformJs, opts = {}) {
-        const dryRun = opts.dryRun ?? true;
-        const deleteComments = opts.deleteComments ?? false;
-        await this.ensureAuthenticated();
-        const comments = await this.listComments(pageId);
-        // ctx handed to the sandbox. consume() records ids; helpers are the pure
-        // transform primitives. log is captured from console.log inside the sandbox.
-        const ctx = {
-            comments,
-            log: [],
-            consumed: new Set(),
-            consume(id) {
-                this.consumed.add(id);
-            },
-            helpers: {
-                blockText,
-                walk,
-                getList,
-                insertMarkerAfter,
-                setCalloutRange,
-                noteItem,
-                mdToInlineNodes,
-                commentsToFootnotes,
-                canonicalizeFootnotes,
-                insertInlineFootnote,
-            },
-        };
-        // Captured oldDoc / newDoc for the diff (set inside runTransform).
-        let oldDoc;
-        let newDoc;
-        // SYNCHRONOUS transform runner — safe to call inside mutatePageContent's
-        // onSynced (no await between the live read and the write).
-        const runTransform = (liveDoc) => {
-            oldDoc = structuredClone(liveDoc);
-            const sandbox = {
-                doc: structuredClone(liveDoc),
-                ctx,
-                structuredClone,
-                console: {
-                    log: (...a) => ctx.log.push(a.map((x) => String(x)).join(" ")),
-                },
-            };
-            // Wrap the provided string in parentheses so both an expression-arrow
-            // (`(doc, ctx) => {...}`) and a parenthesized function work. Run it in a
-            // fresh context with no require/process/module so the transform cannot
-            // touch fs/network/process. 5s wall-clock timeout.
-            let fn;
-            try {
-                fn = vm.runInNewContext("(" + transformJs + ")", sandbox, {
-                    timeout: 5000,
-                });
-            }
-            catch (e) {
-                throw new Error(`transform did not compile: ${e?.message ?? e}`);
-            }
-            if (typeof fn !== "function") {
-                throw new Error("transform must evaluate to a function (doc, ctx) => doc");
-            }
-            const raw = vm.runInNewContext("f(d, c)", { f: fn, d: sandbox.doc, c: ctx }, { timeout: 5000 });
-            if (!raw ||
-                typeof raw !== "object" ||
-                raw.type !== "doc" ||
-                !Array.isArray(raw.content)) {
-                throw new Error('transform must return a ProseMirror doc node ({ type:"doc", content:[...] })');
-            }
-            // Validate the RAW transform output FIRST (structure — including the
-            // MAX_DEPTH guard — and URLs), mirroring updatePageJson. The canonicalizer
-            // recurses without a depth limiter, so validating after it would turn a
-            // too-deep doc into an opaque "Maximum call stack size exceeded" instead of
-            // the intended "nesting exceeds the maximum depth" error.
-            this.validateDocStructure(raw);
-            this.validateDocUrls(raw);
-            // Auto-canonicalize footnotes after the transform (idempotent): no write
-            // path can leave footnotes out of order / orphaned / in a raw `[^id]`
-            // block. In a dryRun preview this may surface footnote edits the script
-            // author did not write (the canonicalizer tidied them) — that is expected.
-            const result = canonicalizeFootnotes(raw);
-            newDoc = result;
-            return result;
-        };
-        if (dryRun) {
-            // Preview only: run against the current REST snapshot, never open the
-            // socket. oldDoc/newDoc are captured by runTransform.
-            const raw = await this.getPageRaw(pageId);
-            const current = raw.content || { type: "doc", content: [] };
-            runTransform(current);
-            // Run an independent Yjs-encodability check (same sanitize + schema as the
-            // apply path), so the preview fails with the same descriptive error when
-            // the doc is not encodable instead of returning a misleadingly-green diff.
-            assertYjsEncodable(newDoc);
-            return {
-                pushed: false,
-                diff: diffDocs(oldDoc, newDoc),
-                log: ctx.log,
-            };
-        }
-        // Apply atomically against the live doc.
-        const collabToken = await this.getCollabTokenWithReauth();
-        // Open the collab doc by the canonical UUID, never the slugId (#260).
-        const pageUuid = await this.resolvePageId(pageId);
-        const mutation = await mutatePageContent(pageUuid, collabToken, this.apiUrl, runTransform);
-        // Optionally delete consumed comments (best-effort; a delete failure must
-        // not undo the successful write).
-        const deletedComments = [];
-        if (deleteComments) {
-            for (const id of ctx.consumed) {
-                try {
-                    await this.deleteComment(id);
-                    deletedComments.push(id);
-                }
-                catch (e) {
-                    if (process.env.DEBUG) {
-                        console.error(`transform: failed to delete comment ${id}:`, e);
-                    }
-                }
-            }
-        }
-        // Fetch the newest historyId (Docmost snapshots on the write above).
-        let historyId = null;
-        try {
-            const hist = await this.listPageHistory(pageId);
-            historyId = hist.items?.[0]?.id ?? null;
-        }
-        catch (e) {
-            if (process.env.DEBUG) {
-                console.error("transform: failed to fetch history id:", e);
-            }
-        }
-        return {
-            pushed: true,
-            historyId,
-            diff: diffDocs(oldDoc, newDoc),
-            deletedComments,
-            log: ctx.log,
-            verify: mutation.verify,
-        };
-    }
-}
diff --git a/packages/mcp/build/http.js b/packages/mcp/build/http.js
deleted file mode 100644
index 45c422b0..00000000
--- a/packages/mcp/build/http.js
+++ /dev/null
@@ -1,133 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { createDocmostMcpServer } from "./index.js";
-/**
- * Build a stateful Streamable-HTTP handler for the Docmost MCP server. The
- * embedding host (the gitmost NestJS server) bridges its raw Node req/res into
- * `handleRequest`. One McpServer + transport is created per MCP session and
- * kept alive between requests, keyed by the `mcp-session-id` header.
- *
- * `config` is EITHER a static `DocmostMcpConfig` (back-compat: stdio + the env
- * service account, unchanged) OR a `McpConfigResolver` run once per session at
- * `initialize` to bind that session to the request's identity.
- */
-export function createMcpHttpHandler(config, options = {}) {
-    // One transport (and one McpServer) per MCP session, keyed by session id.
-    const transports = {};
-    // Last activity timestamp per session id, used for idle eviction.
-    const lastSeen = {};
-    // Anti-session-fixation: the opaque identity key bound to each session at
-    // initialize. A later request for that session whose key differs is rejected.
-    const sessionIdentity = {};
-    // Write a JSON-RPC error and end the response. Used for the 400/401 paths so
-    // every early rejection is a well-formed JSON-RPC error, not a torn response.
-    const sendJsonRpcError = (res, statusCode, code, message) => {
-        res.statusCode = statusCode;
-        res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify({
-            jsonrpc: "2.0",
-            error: { code, message },
-            id: null,
-        }));
-    };
-    // Idle session TTL (ms): a session with no activity for this long is evicted.
-    // Defaults to 30 min; overridable via MCP_SESSION_IDLE_MS.
-    const idleTtlMs = (() => {
-        const parsed = parseInt(process.env.MCP_SESSION_IDLE_MS ?? "", 10);
-        return Number.isFinite(parsed) && parsed > 0 ? parsed : 30 * 60 * 1000;
-    })();
-    // Periodically close transports idle longer than the TTL. transport.close()
-    // triggers its onclose, which removes it from `transports`; we also drop the
-    // lastSeen entry. unref() so this timer never keeps the process alive.
-    const sweepIntervalMs = 5 * 60 * 1000;
-    const sweepTimer = setInterval(() => {
-        const now = Date.now();
-        for (const sid of Object.keys(transports)) {
-            if (now - (lastSeen[sid] ?? 0) > idleTtlMs) {
-                void transports[sid].close();
-                delete lastSeen[sid];
-                delete sessionIdentity[sid];
-            }
-        }
-    }, sweepIntervalMs);
-    sweepTimer.unref();
-    async function handleRequest(req, res, parsedBody) {
-        const sessionId = req.headers["mcp-session-id"];
-        const method = (req.method || "GET").toUpperCase();
-        let transport = sessionId ? transports[sessionId] : undefined;
-        if (method === "POST" && !transport) {
-            // A new session may only be created by an initialize request without a
-            // session id.
-            if (sessionId || !isInitializeRequest(parsedBody)) {
-                sendJsonRpcError(res, 400, -32000, "Bad Request: no valid session ID provided");
-                return;
-            }
-            // Resolve the per-session config from the request (per-user identity) when
-            // a resolver was supplied; otherwise use the static config unchanged. The
-            // resolver may throw (e.g. bad credentials) — surface a clean 401, never
-            // a created session.
-            let sessionConfig;
-            let identity;
-            try {
-                sessionConfig =
-                    typeof config === "function" ? await config(req) : config;
-                if (options.identify)
-                    identity = await options.identify(req);
-            }
-            catch (err) {
-                sendJsonRpcError(res, 401, -32001, err instanceof Error ? err.message : "Unauthorized");
-                return;
-            }
-            transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-                onsessioninitialized: (sid) => {
-                    transports[sid] = transport;
-                    lastSeen[sid] = Date.now();
-                    // Bind the resolved identity to the new session id for anti-fixation.
-                    if (identity !== undefined)
-                        sessionIdentity[sid] = identity;
-                },
-            });
-            transport.onclose = () => {
-                const sid = transport.sessionId;
-                if (sid && transports[sid])
-                    delete transports[sid];
-                if (sid)
-                    delete sessionIdentity[sid];
-            };
-            const server = createDocmostMcpServer(sessionConfig);
-            await server.connect(transport);
-            await transport.handleRequest(req, res, parsedBody);
-            return;
-        }
-        if (!transport) {
-            sendJsonRpcError(res, 400, -32000, "Bad Request: no valid session ID provided");
-            return;
-        }
-        // Anti-session-fixation: a request reusing an existing session id must
-        // present credentials/token that resolve to the SAME identity bound at
-        // initialize, otherwise reject with 401. This prevents hijacking another
-        // user's established session by replaying its session id with different
-        // credentials.
-        if (options.identify && sessionId && sessionId in sessionIdentity) {
-            let presented;
-            try {
-                presented = await options.identify(req);
-            }
-            catch (err) {
-                sendJsonRpcError(res, 401, -32001, err instanceof Error ? err.message : "Unauthorized");
-                return;
-            }
-            if (presented !== sessionIdentity[sessionId]) {
-                sendJsonRpcError(res, 401, -32001, "Credentials do not match the user that owns this MCP session.");
-                return;
-            }
-        }
-        // Routing to an existing transport: refresh its idle timestamp.
-        if (sessionId)
-            lastSeen[sessionId] = Date.now();
-        await transport.handleRequest(req, res, parsedBody);
-    }
-    return { handleRequest };
-}
diff --git a/packages/mcp/build/index.js b/packages/mcp/build/index.js
deleted file mode 100644
index a573231a..00000000
--- a/packages/mcp/build/index.js
+++ /dev/null
@@ -1,801 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-import { DocmostClient } from "./client.js";
-import { parseNodeArg } from "./lib/parse-node-arg.js";
-import { SHARED_TOOL_SPECS } from "./tool-specs.js";
-// Re-export the client and its config type so embedding hosts (e.g. the gitmost
-// NestJS server) can `import('@docmost/mcp')` and construct a DocmostClient
-// directly — for the credentials variant OR the per-user getToken variant.
-export { DocmostClient } from "./client.js";
-// Re-export the zod-agnostic shared tool-spec registry so the in-app AI-SDK
-// service can read it off the loaded module (it cannot import the ESM package's
-// internals directly; it goes through loadDocmostMcp()).
-export { SHARED_TOOL_SPECS } from "./tool-specs.js";
-// Read version from package.json
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf-8"));
-const VERSION = packageJson.version;
-// Configuration for an MCP server instance is the DocmostMcpConfig union
-// (credentials OR getToken) defined and re-exported above. The factory below is
-// fully side-effect-free on import: it reads no environment variables and opens
-// no transport. The standalone stdio entrypoint (stdio.ts) and the HTTP handler
-// (http.ts) supply this config and own the process/transport lifecycle.
-// --- Modern McpServer Implementation ---
-// Editing guide surfaced to MCP clients in the initialize result so they can
-// pick the right tool by intent and avoid resending whole documents.
-//
-// MAINTENANCE RULE: when you ADD, RENAME, or REMOVE a tool (either an inline
-// server.registerTool(...) here or a spec in tool-specs.ts), you MUST update
-// this guide so the new tool is routed by intent. This is enforced by
-// test/unit/server-instructions.test.mjs, which fails when a registered tool
-// name is not mentioned below (see its EXCEPTIONS list for the rare opt-outs).
-// Exported for that test.
-export const SERVER_INSTRUCTIONS = "Docmost editing guide — choose the tool by intent.\n" +
-    "READ: find a page -> search (workspace-wide full-text); list -> list_pages / list_spaces. Locate blocks and their ids CHEAPLY -> get_outline (compact top-level map; start here, not get_page_json). One block's subtree -> get_node (by attrs.id, or \"#<index>\" for tables, which carry no id). Whole page -> get_page (Markdown, lossy; inline <span data-comment-id> tags are comment anchors — markup, not text) or get_page_json (lossless ProseMirror with block ids). Hand a huge page (with images) to an external consumer without pulling it through the model context -> stash_page (returns a short-lived anonymous URL).\n" +
-    "EDIT: fix wording/typos/numbers -> edit_page_text (find/replace inside blocks, no node id needed). Change ONE block (paragraph/heading/callout/etc.) structurally -> patch_node (by attrs.id from get_outline). Add a block -> insert_node (before/after a block by attrs.id or by anchor text, or append). Remove a block -> delete_node (by attrs.id). Tables -> table_get / table_update_cell / table_insert_row / table_delete_row (address by \"#<index>\" from get_outline; table nodes have no attrs.id). Images -> insert_image (add from a web URL) / replace_image (swap an existing image). Footnotes -> insert_footnote. Bulk/structural rewrite -> update_page_json (full ProseMirror replace; prefer the granular tools above to avoid resending the whole ~100KB+ document). Complex/scripted rewrite (multiple coordinated edits, renumbering) -> docmost_transform: write a JS `(doc, ctx) => doc` transform, preview the diff with dryRun (default), then apply with dryRun:false; ctx.helpers includes commentsToFootnotes for turning inline comments into numbered footnotes.\n" +
-    "PAGES: new -> create_page (Markdown). Rename (title only) -> rename_page. Move -> move_page. Delete -> delete_page (SOFT delete — the page goes to trash and is restorable; nothing is permanent). Copy/replace a page's whole content from another page (server-side, no document through the model) -> copy_page_content. Sharing -> share_page / unshare_page / list_shares; share_page makes the page PUBLICLY accessible — do it only when explicitly asked.\n" +
-    "COMMENTS: create_comment is always inline and requires an EXACT selection — contiguous text from a single block, <=250 chars (fails rather than leaving an unanchored comment); reply to a thread via parentCommentId. Propose a concrete text fix for one-click human approval -> create_comment with suggestedText (the exact plain-text replacement for the selection; the selection must then be UNIQUE in the page — extend it with context if needed); prefer this over editing directly when the change is subjective or needs the author's sign-off. Manage -> list_comments, update_comment, resolve_comment (resolve/reopen, reversible — prefer over delete to close), delete_comment, check_new_comments.\n" +
-    "HISTORY: review what changed -> diff_page_versions (a historyId vs current, or two versions). List saved versions -> list_page_history. Undo a bad edit -> restore_page_version (writes a past version back as current; itself revertible). Lossless markdown round-trip (download, edit, re-upload, incl. comment anchors) -> export_page_markdown / import_page_markdown.";
-// Helper to format JSON responses
-const jsonContent = (data) => ({
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-});
-/**
- * Create a fully configured Docmost MCP server. Side-effect-free: it does not
- * read environment variables and does not connect any transport — the caller
- * decides how to expose it (stdio or HTTP). The client talks to Docmost over
- * REST + the collaboration WebSocket using the provided service-account
- * credentials and auto-re-authenticates.
- */
-export function createDocmostMcpServer(config) {
-    // Pass the whole config union through: the client branches internally on
-    // credentials vs. getToken, so both the external /mcp (creds) and the
-    // internal per-user (getToken) paths are wired here unchanged.
-    const docmostClient = new DocmostClient(config);
-    const server = new McpServer({
-        name: "docmost-mcp",
-        version: VERSION,
-    }, { instructions: SERVER_INSTRUCTIONS });
-    // Register a tool from the shared, zod-agnostic spec registry. The spec owns
-    // the canonical name + model-facing description + (optional) schema builder;
-    // only the execute body is supplied per call. buildShape is invoked with THIS
-    // package's zod (v3); the in-app layer passes its own zod (v4).
-    //
-    // The spec's schema builder returns a plain ZodRawShape (Record<string,
-    // unknown> in the shared module since it must stay zod-agnostic), so the
-    // McpServer.registerTool overloads cannot infer the execute arg's shape from
-    // it. We type `execute` loosely and cast the call through `any`; runtime
-    // behaviour is unchanged — each execute body destructures the same fields the
-    // builder declares.
-    const registerShared = (spec, execute) => server.registerTool(spec.mcpName, spec.buildShape
-        ? { description: spec.description, inputSchema: spec.buildShape(z) }
-        : { description: spec.description }, execute);
-    // Tool: get_workspace
-    registerShared(SHARED_TOOL_SPECS.getWorkspace, async () => {
-        const workspace = await docmostClient.getWorkspace();
-        return jsonContent(workspace);
-    });
-    // Tool: list_spaces
-    registerShared(SHARED_TOOL_SPECS.listSpaces, async () => {
-        const spaces = await docmostClient.getSpaces();
-        return jsonContent(spaces);
-    });
-    // Tool: list_pages
-    // INTENTIONAL per-transport divergence (not in the shared registry): this
-    // transport exposes a `tree:true` mode that returns the full nested hierarchy;
-    // the in-app copy keeps the same tree option but is worded for the in-app agent.
-    // Kept per-layer so each side can tune its own guidance.
-    server.registerTool("list_pages", {
-        description: "List most recent pages in a space ordered by updatedAt (descending). " +
-            "Returns a bounded list (default 50, max 100) — use search for lookups " +
-            "in large spaces. Pass tree:true (with spaceId) to instead get the " +
-            "space's full page hierarchy as a nested tree.",
-        inputSchema: {
-            spaceId: z.string().optional(),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .describe("Max pages to return (default 50, max 100)"),
-            tree: z
-                .boolean()
-                .optional()
-                .describe("When true, return the space's full page hierarchy as a nested tree (each node has a children array) instead of the recent-by-updatedAt flat list. Requires spaceId; ignores limit."),
-        },
-    }, async ({ spaceId, limit, tree }) => {
-        const result = await docmostClient.listPages(spaceId, limit ?? 50, tree ?? false);
-        return jsonContent(result);
-    });
-    // Tool: get_page
-    server.registerTool("get_page", {
-        description: "Get page details with content converted to Markdown. The conversion is " +
-            "LOSSY (block ids, exact table/callout structure are approximated); for a " +
-            "lossless representation use get_page_json. Inline <span data-comment-id> " +
-            "tags in the markdown are comment highlight anchors (also present for " +
-            "RESOLVED threads) — treat them as markup, not page text.",
-        inputSchema: {
-            pageId: z.string().min(1),
-        },
-    }, async ({ pageId }) => {
-        const page = await docmostClient.getPage(pageId);
-        return jsonContent(page);
-    });
-    // Tool: get_page_json
-    registerShared(SHARED_TOOL_SPECS.getPageJson, async ({ pageId }) => {
-        const page = await docmostClient.getPageJson(pageId);
-        return jsonContent(page);
-    });
-    // Tool: get_outline
-    registerShared(SHARED_TOOL_SPECS.getOutline, async ({ pageId }) => {
-        const result = await docmostClient.getOutline(pageId);
-        return jsonContent(result);
-    });
-    // Tool: get_node
-    registerShared(SHARED_TOOL_SPECS.getNode, async ({ pageId, nodeId }) => {
-        const result = await docmostClient.getNode(pageId, nodeId);
-        return jsonContent(result);
-    });
-    // Tool: table_get
-    server.registerTool("table_get", {
-        description: "Read a table as a matrix. Returns {rows, cols, cells (text[][]), " +
-            "cellIds (paragraph id per cell, or null)}. `table` = `#<index>` from " +
-            "get_outline, or any block id inside the table. Use cellIds with " +
-            "patch_node for rich-formatted cell edits. `cols` is the FIRST row's " +
-            "width; ragged tables may vary per row, so use the per-row length of " +
-            "`cells` for each row.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            table: z.string().min(1),
-        },
-    }, async ({ pageId, table }) => {
-        const result = await docmostClient.getTable(pageId, table);
-        return jsonContent(result);
-    });
-    // Tool: table_insert_row
-    // NOT in the shared registry: this transport names the table argument `table`,
-    // while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
-    // one buildShape would rename a public MCP parameter, so the table row/cell
-    // tools stay per-transport by design.
-    server.registerTool("table_insert_row", {
-        description: "Insert a row of plain-text cells into a table. `table` = `#<index>` or " +
-            "a block id inside it. `cells` = text per column (padded to the table's " +
-            "column count; error if more cells than columns). `index` = 0-based " +
-            "insert position (0 inserts before the header); omit to append at the end.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            table: z.string().min(1),
-            cells: z.array(z.string()),
-            index: z.number().int().optional(),
-        },
-    }, async ({ pageId, table, cells, index }) => {
-        const result = await docmostClient.tableInsertRow(pageId, table, cells, index);
-        return jsonContent(result);
-    });
-    // Tool: table_delete_row
-    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
-    // divergence as table_insert_row.
-    server.registerTool("table_delete_row", {
-        description: "Delete the row at 0-based `index` from a table (`table` = `#<index>` or " +
-            "a block id inside it). Refuses to delete the table's only row. An " +
-            "out-of-range `index` throws. Deleting `index` 0 removes the header row, " +
-            "and the next row becomes the new header.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            table: z.string().min(1),
-            index: z.number().int(),
-        },
-    }, async ({ pageId, table, index }) => {
-        const result = await docmostClient.tableDeleteRow(pageId, table, index);
-        return jsonContent(result);
-    });
-    // Tool: table_update_cell
-    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
-    // divergence as table_insert_row.
-    server.registerTool("table_update_cell", {
-        description: "Set the plain-text content of cell [row,col] (0-based) in a table " +
-            "(`table` = `#<index>` or a block id inside it). Replaces the cell's " +
-            "content with a single text paragraph; for rich formatting use patch_node " +
-            "on the cell's paragraph id from table_get.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            table: z.string().min(1),
-            row: z.number().int(),
-            col: z.number().int(),
-            text: z.string(),
-        },
-    }, async ({ pageId, table, row, col, text }) => {
-        const result = await docmostClient.tableUpdateCell(pageId, table, row, col, text);
-        return jsonContent(result);
-    });
-    // Tool: create_page
-    server.registerTool("create_page", {
-        description: "Create a new page from Markdown in a space. Pass parentPageId to nest " +
-            "it under a parent; omit it to create at the space root.",
-        inputSchema: {
-            title: z.string().min(1).describe("Title of the page"),
-            content: z.string().min(1).describe("Markdown content"),
-            spaceId: z.string().min(1),
-            parentPageId: z
-                .string()
-                .optional()
-                .describe("Optional parent page ID to nest under"),
-        },
-    }, async ({ title, content, spaceId, parentPageId }) => {
-        const result = await docmostClient.createPage(title, content, spaceId, parentPageId);
-        return jsonContent(result);
-    });
-    // Tool: update_page_json
-    server.registerTool("update_page_json", {
-        description: "Replace a page's content with a raw ProseMirror JSON document " +
-            "(lossless write: preserves the block ids, callouts, tables and " +
-            "attributes you pass in). Typical flow: get_page_json -> modify the " +
-            "JSON -> update_page_json. Keep existing node ids intact so heading " +
-            "anchors and history stay stable. Minimal full-doc example: " +
-            '{"type":"doc","content":[{"type":"paragraph","content":' +
-            '[{"type":"text","text":"Hi"}]}]}. `content` may be a JSON object or a ' +
-            "JSON string (both accepted), and is OPTIONAL: omit it to update only " +
-            "the title (though prefer rename_page for a title-only change). " +
-            "Supplying neither content nor title is an error.",
-        inputSchema: {
-            pageId: z.string().min(1).describe("ID of the page to update"),
-            content: z
-                .any()
-                .optional()
-                .describe('ProseMirror document {"type":"doc","content":[...]} (JSON object or ' +
-                "JSON string). Omit to rename only."),
-            title: z.string().optional().describe("Optional new title"),
-        },
-    }, async ({ pageId, content, title }) => {
-        // Only parse/validate the document when it was actually supplied; when it
-        // is omitted, pass it straight through so the client performs a title-only
-        // (or no-op) update.
-        let doc;
-        if (content === undefined || content === null) {
-            doc = undefined;
-        }
-        else {
-            // String -> JSON.parse (throwing on invalid); object passes through.
-            doc = parseNodeArg(content, "content was a string but not valid JSON");
-        }
-        const result = await docmostClient.updatePageJson(pageId, doc, title);
-        return jsonContent(result);
-    });
-    // Tool: export_page_markdown
-    server.registerTool("export_page_markdown", {
-        description: "Export a page to a single self-contained, lossless Docmost-flavoured " +
-            "Markdown file (custom extensions): YAML-free meta header, body with " +
-            "inline comment anchors and diagrams, and a trailing comments-thread " +
-            "block. Designed for a download -> edit body -> import_page_markdown " +
-            "round-trip that preserves everything, including comment highlights. " +
-            "Comment THREADS are preserved in the file but are not re-pushed to the " +
-            "server on import.",
-        inputSchema: {
-            pageId: z.string().min(1),
-        },
-    }, async ({ pageId }) => {
-        const md = await docmostClient.exportPageMarkdown(pageId);
-        return { content: [{ type: "text", text: md }] };
-    });
-    // Tool: import_page_markdown
-    registerShared(SHARED_TOOL_SPECS.importPageMarkdown, async ({ pageId, markdown }) => {
-        const res = await docmostClient.importPageMarkdown(pageId, markdown);
-        return jsonContent(res);
-    });
-    // Tool: copy_page_content
-    registerShared(SHARED_TOOL_SPECS.copyPageContent, async ({ sourcePageId, targetPageId }) => {
-        const result = await docmostClient.copyPageContent(sourcePageId, targetPageId);
-        return jsonContent(result);
-    });
-    // Tool: rename_page
-    server.registerTool("rename_page", {
-        description: "Rename a page (change its title only) without touching or resending " +
-            "its content.",
-        inputSchema: {
-            pageId: z.string().min(1).describe("ID of the page to rename"),
-            title: z.string().min(1).describe("New title"),
-        },
-    }, async ({ pageId, title }) => {
-        const result = await docmostClient.renamePage(pageId, title);
-        return jsonContent(result);
-    });
-    // Tool: edit_page_text
-    registerShared(SHARED_TOOL_SPECS.editPageText, async ({ pageId, edits }) => {
-        const result = await docmostClient.editPageText(pageId, edits);
-        return jsonContent(result);
-    });
-    // Tool: stash_page — returns a resource_link (NOT embedded text) so the doc
-    // body never enters the model context. Registered directly (not via
-    // registerShared) because that helper only emits text content. Also returns
-    // `structuredContent` carrying the full documented `{uri, sha256, size, images}`
-    // shape alongside the resource_link, so MCP clients receive the blob's sha256
-    // (its ETag, for integrity) and mirror counts, not just the link.
-    server.registerTool(SHARED_TOOL_SPECS.stashPage.mcpName, {
-        description: SHARED_TOOL_SPECS.stashPage.description,
-        inputSchema: SHARED_TOOL_SPECS.stashPage.buildShape(z),
-    }, async ({ pageId }) => {
-        const result = await docmostClient.stashPage(pageId);
-        return {
-            content: [
-                {
-                    type: "resource_link",
-                    uri: result.uri,
-                    name: "page.json",
-                    mimeType: "application/json",
-                    size: result.size,
-                },
-            ],
-            // Mirror the full documented result shape ({ uri, size, sha256, images })
-            // as structuredContent so MCP clients get the blob's sha256 (its ETag, for
-            // integrity) and the mirror counts, not just the resource_link.
-            structuredContent: {
-                uri: result.uri,
-                sha256: result.sha256,
-                size: result.size,
-                images: result.images,
-            },
-        };
-    });
-    // Tool: patch_node — schema + description from the shared registry (identical
-    // across both transports). The execute body keeps its own parseNodeArg
-    // normalization (the model sometimes serializes `node` as a JSON string).
-    registerShared(SHARED_TOOL_SPECS.patchNode, async ({ pageId, nodeId, node }) => {
-        const parsedNode = parseNodeArg(node);
-        const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
-        return jsonContent(result);
-    });
-    // Tool: insert_node — schema + description from the shared registry. As with
-    // patch_node, the execute body retains parseNodeArg on the incoming node.
-    registerShared(SHARED_TOOL_SPECS.insertNode, async ({ pageId, node, position, anchorNodeId, anchorText }) => {
-        const parsedNode = parseNodeArg(node);
-        const result = await docmostClient.insertNode(pageId, parsedNode, {
-            position,
-            anchorNodeId,
-            anchorText,
-        });
-        return jsonContent(result);
-    });
-    // Tool: delete_node
-    registerShared(SHARED_TOOL_SPECS.deleteNode, async ({ pageId, nodeId }) => {
-        const result = await docmostClient.deleteNode(pageId, nodeId);
-        return jsonContent(result);
-    });
-    // Tool: insert_image
-    server.registerTool("insert_image", {
-        description: "Download an image from a web (http/https) URL and insert it into " +
-            "a page in one step. By default " +
-            "appends the image at the end of the page. With replaceText, replaces the " +
-            "first top-level block whose text contains that string (handy for " +
-            'swapping a text placeholder like "[image: foo.png]" for the real image). ' +
-            "With afterText, inserts the image right after the first block containing " +
-            "that string. Preserves all other block ids.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            imageUrl: z
-                .string()
-                .min(1)
-                .describe("http(s) URL of the image to download and upload"),
-            align: z.enum(["left", "center", "right"]).optional(),
-            alt: z.string().optional(),
-            replaceText: z
-                .string()
-                .optional()
-                .describe("Replace the first top-level block whose text contains this string with the image"),
-            afterText: z
-                .string()
-                .optional()
-                .describe("Insert the image right after the first top-level block whose text contains this string"),
-        },
-    }, async ({ pageId, imageUrl, align, alt, replaceText, afterText }) => {
-        const result = await docmostClient.insertImage(pageId, imageUrl, {
-            align,
-            alt,
-            replaceText,
-            afterText,
-        });
-        return jsonContent(result);
-    });
-    // Tool: replace_image
-    server.registerTool("replace_image", {
-        description: "Replace an existing image on a page with a new image fetched from a web " +
-            "(http/https) URL: uploads the new file as a NEW " +
-            "attachment (fresh clean URL that renders and busts browser caches), then " +
-            "repoints every image node referencing the old attachmentId (recursively, " +
-            "incl. callouts/tables) via the live document, preserving comments, " +
-            "alignment and alt. The old attachment is left as an unreferenced orphan " +
-            "(Docmost has no API to delete a single attachment; it is removed only when " +
-            "the page/space is deleted). In-place byte overwrite is avoided because some " +
-            "Docmost versions corrupt the attachment (HTTP 500) on overwrite.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            attachmentId: z
-                .string()
-                .min(1)
-                .describe("attachmentId of the image currently in the page to replace"),
-            imageUrl: z
-                .string()
-                .min(1)
-                .describe("http(s) URL of the new image to download"),
-            align: z.enum(["left", "center", "right"]).optional(),
-            alt: z.string().optional(),
-        },
-    }, async ({ pageId, attachmentId, imageUrl, align, alt }) => {
-        const result = await docmostClient.replaceImage(pageId, attachmentId, imageUrl, {
-            align,
-            alt,
-        });
-        return jsonContent(result);
-    });
-    // Tool: share_page
-    // INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
-    // security-confirmation framing ("only share when the user explicitly asked,
-    // since this exposes the page to anyone with the link") tuned for the in-app
-    // agent; this transport keeps the plain public-URL wording.
-    server.registerTool("share_page", {
-        description: "Make a page publicly accessible (idempotent) and return its public " +
-            "URL. The URL format is <app>/share/<key>/p/<slugId>. This exposes the " +
-            "page content to ANYONE with the URL — do it only when explicitly asked.",
-        inputSchema: {
-            pageId: z.string().min(1).describe("ID of the page to share"),
-            searchIndexing: z
-                .boolean()
-                .optional()
-                .describe("Allow search engines to index the page (default true)"),
-        },
-    }, async ({ pageId, searchIndexing }) => {
-        const result = await docmostClient.sharePage(pageId, searchIndexing ?? true);
-        return jsonContent(result);
-    });
-    // Tool: unshare_page
-    registerShared(SHARED_TOOL_SPECS.unsharePage, async ({ pageId }) => {
-        const result = await docmostClient.unsharePage(pageId);
-        return jsonContent(result);
-    });
-    // Tool: list_shares
-    registerShared(SHARED_TOOL_SPECS.listShares, async () => {
-        const result = await docmostClient.listShares();
-        return jsonContent(result);
-    });
-    // Tool: move_page
-    server.registerTool("move_page", {
-        description: "Move a page under a new parent (nesting) or to the space root.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            parentPageId: z
-                .string()
-                .nullable()
-                .optional()
-                .describe("Target parent page ID. Pass 'null' or empty string to move to root."),
-            position: z
-                .string()
-                .min(5)
-                .optional()
-                .describe("fractional-index position key; min 5 chars; omit to append at the end."),
-        },
-    }, async ({ pageId, parentPageId, position }) => {
-        const finalParentId = parentPageId === "" || parentPageId === "null" ? null : parentPageId;
-        // Cheap cycle guard: a page cannot be moved directly under itself.
-        // (Deeper descendant-cycle detection is intentionally out of scope.)
-        if (finalParentId !== null && finalParentId === pageId) {
-            throw new Error("cannot move a page under itself");
-        }
-        const result = await docmostClient.movePage(pageId, finalParentId || null, position);
-        // Require POSITIVE confirmation: the live /pages/move success shape is
-        // exactly { success: true, status: 200 }. An empty body, a 204, or any odd
-        // shape lacking success === true must NOT be reported as a successful move,
-        // so we surface the raw API result instead of declaring success.
-        if (!(result && typeof result === "object" && result.success === true)) {
-            throw new Error(`Failed to move page ${pageId}: ${JSON.stringify(result)}`);
-        }
-        return jsonContent({
-            message: `Successfully moved page ${pageId} to parent ${finalParentId || "root"}`,
-            result,
-        });
-    });
-    // Tool: delete_page
-    server.registerTool("delete_page", {
-        description: "Delete a single page by ID. SOFT delete only: the page is moved to " +
-            "trash and can be restored; nothing is permanently deleted.",
-        inputSchema: {
-            pageId: z.string().min(1),
-        },
-    }, async ({ pageId }) => {
-        await docmostClient.deletePage(pageId);
-        return {
-            content: [
-                { type: "text", text: `Successfully deleted page ${pageId}` },
-            ],
-        };
-    });
-    // --- Comment tools (ported from upstream PR #3 by Max Nikitin) ---
-    // Tool: list_comments
-    server.registerTool("list_comments", {
-        description: "List ALL comments on a page in one call (pagination is handled " +
-            "internally), including RESOLVED threads — filter by resolvedAt when you " +
-            "need only open ones. Content is returned as Markdown.",
-        inputSchema: {
-            pageId: z.string().describe("ID of the page"),
-        },
-    }, async ({ pageId }) => {
-        const comments = await docmostClient.listComments(pageId);
-        return jsonContent(comments);
-    });
-    // Tool: create_comment
-    // INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
-    // guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
-    // and "Reversible via the comment UI"); this transport keeps its own wording.
-    server.registerTool("create_comment", {
-        description: "Create a new comment on a page. The comment is ALWAYS inline and is " +
-            "anchored to (highlights) its `selection` text — there are no page-level " +
-            "comments. Content is provided as Markdown and automatically converted. " +
-            "A top-level comment REQUIRES an exact `selection`; if the selection " +
-            "cannot be found in the page the call fails (no orphan comment is left). " +
-            "Replies (parentCommentId set) inherit the parent's anchor and take no " +
-            "selection. You may also attach a `suggestedText` proposing a replacement " +
-            "for the `selection`; a human applies (or rejects) it from the UI. When " +
-            "`suggestedText` is set the `selection` MUST occur exactly once in the " +
-            "page — expand it with surrounding context if it is ambiguous.",
-        inputSchema: {
-            pageId: z.string().describe("ID of the page to comment on"),
-            content: z.string().min(1).describe("Comment content in Markdown format"),
-            selection: z
-                .string()
-                .min(1)
-                // Enforce the documented 250-char cap to match the description above.
-                .max(250)
-                .optional()
-                .describe("EXACT contiguous text from a single paragraph/block to anchor the " +
-                "comment on (<=250 chars). Required for a top-level comment; omit " +
-                "only when replying via parentCommentId."),
-            parentCommentId: z
-                .string()
-                .optional()
-                .describe("Parent comment ID to create a reply (max 2 nesting levels)"),
-            suggestedText: z
-                .string()
-                .min(1)
-                .max(2000)
-                .optional()
-                .describe("Optional proposed replacement (PLAIN TEXT) for the `selection`, " +
-                "applied by a human via the UI (never auto-applied). REQUIRES a " +
-                "`selection`; NOT allowed on a reply. When set, the `selection` must " +
-                "be UNIQUE in the page — expand it with surrounding context (still " +
-                "<=250 chars) if it occurs more than once, or the call is refused."),
-        },
-    }, async ({ pageId, content, selection, parentCommentId, suggestedText }) => {
-        if (!parentCommentId && (!selection || !selection.trim())) {
-            throw new Error("create_comment: a 'selection' (exact text to anchor on) is required for a top-level comment; omit it only when replying via parentCommentId.");
-        }
-        if (suggestedText !== undefined) {
-            if (parentCommentId) {
-                throw new Error("create_comment: 'suggestedText' cannot be attached to a reply; it applies only to a top-level inline comment.");
-            }
-            if (!selection || !selection.trim()) {
-                throw new Error("create_comment: 'suggestedText' requires a 'selection' to anchor and rewrite.");
-            }
-        }
-        const result = await docmostClient.createComment(pageId, content, "inline", selection, parentCommentId, suggestedText);
-        return jsonContent(result);
-    });
-    // Tool: update_comment
-    server.registerTool("update_comment", {
-        description: "Update an existing comment's content. Only the comment creator can " +
-            "update it. Content is provided as Markdown.",
-        inputSchema: {
-            commentId: z.string().min(1).describe("ID of the comment to update"),
-            content: z
-                .string()
-                .min(1)
-                .describe("New comment content in Markdown format"),
-        },
-    }, async ({ commentId, content }) => {
-        const result = await docmostClient.updateComment(commentId, content);
-        return jsonContent(result);
-    });
-    // Tool: delete_comment
-    server.registerTool("delete_comment", {
-        description: "Delete a comment. Only the comment creator or space admin can delete it.",
-        inputSchema: {
-            commentId: z.string().min(1).describe("ID of the comment to delete"),
-        },
-    }, async ({ commentId }) => {
-        await docmostClient.deleteComment(commentId);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Successfully deleted comment ${commentId}`,
-                },
-            ],
-        };
-    });
-    // Tool: resolve_comment
-    server.registerTool("resolve_comment", {
-        description: "Resolve (close) or reopen a comment thread. Only top-level comments can " +
-            "be resolved — the server rejects resolving a reply. Reversible: pass " +
-            "resolved=false to reopen. Resolving keeps the thread and its replies " +
-            "(unlike delete_comment, which permanently removes them).",
-        inputSchema: {
-            commentId: z
-                .string()
-                .min(1)
-                .describe("ID of the top-level comment thread to resolve or reopen"),
-            resolved: z
-                .boolean()
-                .optional()
-                .default(true)
-                .describe("true (default) marks the thread resolved/closed; false reopens it"),
-        },
-    }, async ({ commentId, resolved }) => {
-        const result = await docmostClient.resolveComment(commentId, resolved);
-        return jsonContent(result);
-    });
-    // Tool: check_new_comments
-    server.registerTool("check_new_comments", {
-        description: "Check for new comments across pages in a space since a given timestamp. " +
-            "Optionally scope to a page subtree (folder). Returns only comments " +
-            "created after the specified time.",
-        inputSchema: {
-            spaceId: z.string().describe("Space ID to check for new comments"),
-            since: z
-                .string()
-                .min(1)
-                .describe("ISO 8601 timestamp — only return comments created after this time (e.g. '2026-03-10T00:00:00Z')"),
-            parentPageId: z
-                .string()
-                .optional()
-                .describe("Optional root page ID to scope the check to a subtree (folder). " +
-                "Only pages under this parent will be checked."),
-        },
-    }, async ({ spaceId, since, parentPageId }) => {
-        // Reject an unparseable timestamp up front: otherwise the comparison
-        // against NaN silently treats every comment as "not new" and the tool
-        // returns zero results without signalling the bad input.
-        if (Number.isNaN(Date.parse(since))) {
-            throw new Error(`Invalid 'since' timestamp: ${JSON.stringify(since)} — expected an ISO 8601 date (e.g. '2026-03-10T00:00:00Z')`);
-        }
-        const result = await docmostClient.checkNewComments(spaceId, since, parentPageId);
-        return jsonContent(result);
-    });
-    // Tool: search
-    // INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
-    // runs a semantic + keyword hybrid (RRF) with in-process access control and a
-    // different schema (limit 1-20); this transport is a plain REST full-text search
-    // (limit up to 100). Different behaviour AND schema, so kept per-layer.
-    server.registerTool("search", {
-        description: "Full-text search for pages and content across the whole workspace. " +
-            "Results are bounded by `limit` (1-100; when omitted the server applies " +
-            "its own default).",
-        inputSchema: {
-            query: z.string().min(1).describe("Search query"),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(100)
-                .optional()
-                .describe("Max results to return (max 100)"),
-        },
-    }, async ({ query, limit }) => {
-        // The tool exposes no spaceId filter, so pass undefined for the client's
-        // optional spaceId parameter and forward limit into its correct slot.
-        const result = await docmostClient.search(query, undefined, limit);
-        return jsonContent(result);
-    });
-    // Tool: docmost_transform
-    // INTENTIONAL per-transport divergence (not shared): the in-app `transformPage`
-    // deliberately omits the `deleteComments` schema field (comment-deletion
-    // guardrail) and carries a much shorter description; this transport exposes the
-    // full helper catalogue. Different schema, so kept per-layer.
-    server.registerTool("docmost_transform", {
-        description: "Edit a page by running an arbitrary JS transform `(doc, ctx) => doc` " +
-            "against its LIVE ProseMirror document, with a diff preview and page " +
-            "history as the safety net. By default dryRun=true: returns a diff " +
-            "preview WITHOUT writing. Set dryRun=false to apply (atomic, won't " +
-            "clobber concurrent edits). `doc` is the lossless ProseMirror document " +
-            "({type:'doc',content:[...]}); return a new doc of the same shape. " +
-            "`ctx` gives you: comments (the page's comments, each {id, content " +
-            "(markdown), selection, type}); log (array; console.log pushes to it); " +
-            "consume(id) (mark a comment id as consumed — those are deleted when " +
-            "deleteComments=true after a successful apply); and helpers: " +
-            "blockText(node) (plain text), walk(node, fn) (depth-first over all " +
-            "nodes incl. callouts/tables/lists), getList(doc, predicate) (find a " +
-            "node even without attrs.id), insertMarkerAfter(doc, anchor, marker, " +
-            "{beforeBlock}) (insert a plain unmarked text run after anchor, " +
-            "mark-safe), setCalloutRange(doc, n) (sync a [1]…[K] callout range to " +
-            "[1]…[n]), noteItem(inlineNodes) (wrap inline nodes in a listItem with a " +
-            "fresh id), mdToInlineNodes(markdown) (comment markdown -> inline nodes), " +
-            "commentsToFootnotes(doc, comments, {notesHeading}) (turn inline " +
-            "comments into numbered footnotes), canonicalizeFootnotes(doc) (derive " +
-            "footnote numbering + the single bottom list from reference order, drop " +
-            "orphans/duplicates — runs AUTOMATICALLY on the transform RESULT, so the " +
-            "applied (and dryRun-previewed) doc is always footnote-canonical; a dryRun " +
-            "diff may therefore show footnote tidy-ups your script did not make, and " +
-            "it is idempotent after the first run), and " +
-            "insertInlineFootnote(doc, {anchorText, text}) (author-inline footnote: " +
-            "marker + dedup'd definition, list derived). Footnote convention: markers are " +
-            "plain '[N]' text in the body; the notes are an orderedList under a " +
-            "heading whose text is 'Примечания переводчика' (that is only the DEFAULT " +
-            "notesHeading — pass the notesHeading option to the helpers to use a " +
-            "heading matching the page's language). The transform runs " +
-            "sandboxed (no require/process/fs/network, 5s timeout) and must return a " +
-            "{type:'doc'} node.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            transformJs: z
-                .string()
-                .min(1)
-                .describe("A JS function `(doc, ctx) => doc` (expression-arrow or " +
-                "parenthesized function). It receives a clone of the live doc and " +
-                "ctx (comments, log, consume(id), helpers: blockText/walk/getList/" +
-                "insertMarkerAfter/setCalloutRange/noteItem/mdToInlineNodes/" +
-                "commentsToFootnotes/canonicalizeFootnotes/insertInlineFootnote) " +
-                "and must return a {type:'doc'} node."),
-            dryRun: z
-                .boolean()
-                .optional()
-                .default(true)
-                .describe("Preview only (no write) when true (default)."),
-            deleteComments: z
-                .boolean()
-                .optional()
-                .default(false)
-                .describe("After a successful apply, delete every comment id passed to " +
-                "ctx.consume(id)."),
-        },
-    }, async ({ pageId, transformJs, dryRun, deleteComments }) => {
-        const result = await docmostClient.transformPage(pageId, transformJs, {
-            dryRun,
-            deleteComments,
-        });
-        return jsonContent(result);
-    });
-    // Tool: insert_footnote
-    server.registerTool("insert_footnote", {
-        description: "Insert an AUTHOR-INLINE footnote: you specify only WHERE (anchorText) " +
-            "and WHAT (text). The footnote marker is placed right after anchorText in " +
-            "the body, and the bottom footnotes list + the numbering are derived " +
-            "deterministically server-side. You do NOT assign a number, and you " +
-            "never see or edit the footnotes list — so footnotes cannot end up out " +
-            "of order, orphaned, or as a raw '[^id]' block. If a footnote with the " +
-            "SAME text already exists, its number is REUSED (one definition, several " +
-            "references). The write is atomic and won't clobber concurrent edits; if " +
-            "anchorText is not found, nothing is written and an error is returned.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            anchorText: z
-                .string()
-                .min(1)
-                .describe("A snippet of existing body text; the footnote marker is inserted " +
-                "immediately after its first occurrence (mark-safe)."),
-            text: z
-                .string()
-                .min(1)
-                .describe("The footnote content as markdown (becomes the definition)."),
-        },
-    }, async ({ pageId, anchorText, text }) => {
-        const result = await docmostClient.insertFootnote(pageId, anchorText, text);
-        return jsonContent(result);
-    });
-    // Tool: diff_page_versions
-    registerShared(SHARED_TOOL_SPECS.diffPageVersions, async ({ pageId, from, to }) => {
-        const result = await docmostClient.diffPageVersions(pageId, from, to);
-        return jsonContent(result);
-    });
-    // Tool: list_page_history
-    registerShared(SHARED_TOOL_SPECS.listPageHistory, async ({ pageId, cursor }) => {
-        const result = await docmostClient.listPageHistory(pageId, cursor);
-        return jsonContent(result);
-    });
-    // Tool: restore_page_version
-    registerShared(SHARED_TOOL_SPECS.restorePageVersion, async ({ historyId }) => {
-        const result = await docmostClient.restorePageVersion(historyId);
-        return jsonContent(result);
-    });
-    return server;
-}
diff --git a/packages/mcp/build/lib/auth-utils.js b/packages/mcp/build/lib/auth-utils.js
deleted file mode 100644
index 39b91d9d..00000000
--- a/packages/mcp/build/lib/auth-utils.js
+++ /dev/null
@@ -1,92 +0,0 @@
-import axios from "axios";
-export async function getCollabToken(baseUrl, apiToken) {
-    try {
-        const response = await axios.post(`${baseUrl}/auth/collab-token`, {}, {
-            headers: {
-                Authorization: `Bearer ${apiToken}`,
-                "Content-Type": "application/json",
-            },
-        });
-        // console.error('Collab Token Response:', response.data);
-        // Response is wrapped in { data: { token: ... } }
-        return response.data.data?.token || response.data.token;
-    }
-    catch (error) {
-        if (axios.isAxiosError(error)) {
-            // Attach the HTTP status to the plain Error so callers (e.g.
-            // getCollabTokenWithReauth) can still detect a 401/403 after the
-            // original AxiosError has been wrapped away.
-            // Avoid leaking the full server response body by default; include only
-            // status + statusText. Append the body only when DEBUG is set.
-            let message = `Failed to get collab token: ${error.response?.status} ${error.response?.statusText}`;
-            if (process.env.DEBUG) {
-                message += ` - ${JSON.stringify(error.response?.data)}`;
-            }
-            const err = new Error(message);
-            err.status = error.response?.status;
-            throw err;
-        }
-        throw error;
-    }
-}
-/**
- * Pure cookie-parsing helper extracted from `performLogin` so the parsing logic
- * can be unit-tested without performing the login network request. Given the
- * raw `Set-Cookie` header array from the login response, return the `authToken`
- * cookie's value.
- *
- * Behavior (kept identical to the original inline logic):
- *  - throws if there is no Set-Cookie header at all;
- *  - matches the cookie NAME exactly (`authToken`), so a future
- *    `authTokenRefresh=...` cookie is NOT picked up (a `startsWith` would be);
- *  - returns everything after the FIRST `=` up to the first `;`, so a base64
- *    value containing `=` padding is preserved (a naive `split("=")` would
- *    truncate it);
- *  - cookie attributes after the first `;` (Path, HttpOnly, Expires, …) are
- *    ignored;
- *  - throws if no `authToken` cookie is present.
- */
-export function extractAuthTokenFromSetCookie(cookies) {
-    if (!cookies) {
-        throw new Error("No Set-Cookie header found in login response");
-    }
-    // Match the cookie name exactly to avoid matching a future
-    // authTokenRefresh cookie (startsWith would catch it).
-    const authCookie = cookies.find((c) => {
-        const kv = c.split(";")[0];
-        return kv.slice(0, kv.indexOf("=")) === "authToken";
-    });
-    if (!authCookie) {
-        throw new Error("No authToken cookie found in login response");
-    }
-    // Take everything after the FIRST "=" up to the first ";".
-    // Splitting on "=" would truncate base64 values containing "=" padding.
-    const kv = authCookie.split(";")[0];
-    return kv.slice(kv.indexOf("=") + 1);
-}
-export async function performLogin(baseUrl, email, password) {
-    try {
-        const response = await axios.post(`${baseUrl}/auth/login`, {
-            email,
-            password,
-        });
-        // Extract token from Set-Cookie header
-        return extractAuthTokenFromSetCookie(response.headers["set-cookie"]);
-    }
-    catch (error) {
-        // Avoid leaking the full server response body by default; log only the
-        // HTTP status. Log the verbose body only when DEBUG is set.
-        if (axios.isAxiosError(error)) {
-            if (process.env.DEBUG) {
-                console.error("Login failed:", error.response?.data);
-            }
-            else {
-                console.error("Login failed:", error.response?.status);
-            }
-        }
-        else {
-            console.error("Login failed:", error.message);
-        }
-        throw error;
-    }
-}
diff --git a/packages/mcp/build/lib/collaboration.js b/packages/mcp/build/lib/collaboration.js
deleted file mode 100644
index 4504b8d0..00000000
--- a/packages/mcp/build/lib/collaboration.js
+++ /dev/null
@@ -1,743 +0,0 @@
-import { HocuspocusProvider } from "@hocuspocus/provider";
-import { TiptapTransformer } from "@hocuspocus/transformer";
-import * as Y from "yjs";
-import WebSocket from "ws";
-import { marked } from "marked";
-import { generateJSON } from "@tiptap/html";
-import { Node as PMNode } from "@tiptap/pm/model";
-import { updateYFragment } from "y-prosemirror";
-import { JSDOM } from "jsdom";
-import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
-import { withPageLock } from "./page-lock.js";
-import { sanitizeForYjs, findUnstorableAttr } from "./node-ops.js";
-import { lexFootnoteLines } from "./footnote-lex.js";
-import { canonicalizeFootnotes } from "./footnote-canonicalize.js";
-import { summarizeChange } from "./diff.js";
-/**
- * Build the descriptive error for an opaque Yjs encode failure ("Unexpected
- * content type"), shared by both encode paths (`buildYDoc` -> `toYdoc` and
- * `applyDocToFragment` -> `updateYFragment`) so the message wording stays in one
- * place. `label` names the stage that failed (diagnostic). `sanitizeForYjs`
- * already stripped `undefined` attrs, so a remaining failure is pinpointed via
- * `findUnstorableAttr`.
- */
-function unstorableYjsError(safe, label, e) {
-    const bad = findUnstorableAttr(safe);
-    return new Error(`Failed to encode document to Yjs (${label}): ${e instanceof Error ? e.message : String(e)}.${bad ? ` Offending attribute: ${bad}.` : " A node/mark attribute likely holds a value Yjs cannot store (e.g. undefined)."}`);
-}
-// Setup DOM environment for Tiptap HTML parsing in Node.js
-const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");
-global.window = dom.window;
-global.document = dom.window.document;
-// @ts-ignore
-global.Element = dom.window.Element;
-// @ts-ignore
-global.WebSocket = WebSocket;
-// Navigator is read-only in newer Node versions and already exists
-// global.navigator = dom.window.navigator;
-/**
- * Hard ceiling above which we skip callout preprocessing entirely. The linear
- * scanner below has no quadratic blow-up, but we still cap input defensively so
- * a pathological multi-megabyte payload cannot tie up the event loop; in that
- * case the markdown is passed through verbatim (callouts are simply not
- * detected) rather than risking a slow scan.
- */
-const MAX_CALLOUT_PREPROCESS_BYTES = 4 * 1024 * 1024; // 4 MB
-/** Matches an opening callout fence: `:::type` (type captured, lower-cased). */
-const CALLOUT_OPEN_RE = /^:::\s*(\w+)\s*$/;
-/** Matches a bare closing callout fence: `:::`. */
-const CALLOUT_CLOSE_RE = /^:::\s*$/;
-/** Matches the start/end of a code fence (``` or ~~~), capturing the marker. */
-const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
-/**
- * Pre-process Docmost-flavoured markdown: convert `:::type ... :::`
- * callout blocks (the syntax our markdown export produces) into HTML
- * divs that the callout extension parses. The inner content is rendered
- * through marked as regular markdown.
- *
- * Implemented as a single linear pass over the lines (no quadratic regex
- * rescan). It:
- *   - tracks fenced code regions (```...``` and ~~~...~~~) and never treats a
- *     `:::` line that lives inside a code fence as a callout delimiter, so a
- *     callout body that itself contains a fenced code block with a `:::` line is
- *     no longer corrupted;
- *   - matches an opening `:::type` line with the next CLOSING `:::` at the SAME
- *     nesting level, supporting NESTED callouts via a depth counter (an inner
- *     `:::type` opens a deeper level and consumes a matching `:::`);
- *   - emits the same `<div data-type="callout" data-callout-type="TYPE">` output
- *     (inner rendered through marked) as the previous regex implementation.
- */
-async function preprocessCallouts(markdown) {
-    // Defensive cap: skip preprocessing for pathologically large inputs.
-    if (markdown.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-        return markdown;
-    }
-    // Recursively transform a slice of lines, converting top-level callouts in
-    // that slice into <div> blocks and rendering their inner content (which may
-    // itself contain nested callouts) through this same function.
-    const transform = async (lines) => {
-        const out = [];
-        let inCodeFence = false;
-        let codeFenceMarker = ""; // the exact run of backticks/tildes that opened it
-        let i = 0;
-        while (i < lines.length) {
-            const line = lines[i];
-            // Inside a code fence, only its matching closing fence is significant;
-            // everything else (including `:::` lines) is copied through verbatim.
-            if (inCodeFence) {
-                out.push(line);
-                const fence = line.match(CODE_FENCE_RE);
-                if (fence && fence[2].startsWith(codeFenceMarker[0]) &&
-                    fence[2].length >= codeFenceMarker.length) {
-                    inCodeFence = false;
-                    codeFenceMarker = "";
-                }
-                i++;
-                continue;
-            }
-            // A code fence opening outside any callout body: enter code-fence mode.
-            const fenceOpen = line.match(CODE_FENCE_RE);
-            if (fenceOpen) {
-                inCodeFence = true;
-                codeFenceMarker = fenceOpen[2];
-                out.push(line);
-                i++;
-                continue;
-            }
-            // An opening callout fence: scan forward (with code-fence and nested
-            // callout awareness) for its matching closing `:::` at the same level.
-            const open = line.match(CALLOUT_OPEN_RE);
-            if (open) {
-                const type = open[1].toLowerCase();
-                const bodyLines = [];
-                let depth = 1;
-                let innerInCodeFence = false;
-                let innerCodeFenceMarker = "";
-                let j = i + 1;
-                for (; j < lines.length; j++) {
-                    const bl = lines[j];
-                    if (innerInCodeFence) {
-                        const f = bl.match(CODE_FENCE_RE);
-                        if (f && f[2].startsWith(innerCodeFenceMarker[0]) &&
-                            f[2].length >= innerCodeFenceMarker.length) {
-                            innerInCodeFence = false;
-                            innerCodeFenceMarker = "";
-                        }
-                        bodyLines.push(bl);
-                        continue;
-                    }
-                    const innerFence = bl.match(CODE_FENCE_RE);
-                    if (innerFence) {
-                        innerInCodeFence = true;
-                        innerCodeFenceMarker = innerFence[2];
-                        bodyLines.push(bl);
-                        continue;
-                    }
-                    if (CALLOUT_OPEN_RE.test(bl)) {
-                        depth++;
-                        bodyLines.push(bl);
-                        continue;
-                    }
-                    if (CALLOUT_CLOSE_RE.test(bl)) {
-                        depth--;
-                        if (depth === 0)
-                            break; // matching close for THIS callout
-                        bodyLines.push(bl);
-                        continue;
-                    }
-                    bodyLines.push(bl);
-                }
-                if (j < lines.length) {
-                    // Found the matching closing fence: render the body (recursively, so
-                    // nested callouts are handled) and emit the callout div.
-                    const inner = await transform(bodyLines);
-                    const renderedInner = await marked.parse(inner);
-                    out.push(`\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`);
-                    i = j + 1; // skip past the closing `:::`
-                    continue;
-                }
-                // No matching close (unterminated callout): treat the opener as a
-                // literal line and continue, preserving the original text.
-                out.push(line);
-                i++;
-                continue;
-            }
-            out.push(line);
-            i++;
-        }
-        return out.join("\n");
-    };
-    return transform(markdown.split("\n"));
-}
-/**
- * Bridge marked's checkbox lists to TipTap task lists.
- *
- * marked renders GitHub task list items (`- [x] done`) as a plain
- * `<ul><li><p><input type="checkbox" checked> text</p></li></ul>` WITHOUT the
- * markup TipTap's TaskList/TaskItem extensions parse. This rewrites such lists
- * into the shape those extensions expect:
- *   TaskList parseHTML matches `ul[data-type="taskList"]`,
- *   TaskItem matches `li[data-type="taskItem"]`,
- *   the checked state is read from `data-checked === "true"`.
- *
- * A list is only converted when it has at least one `<li>` and EVERY direct
- * `<li>` contains a checkbox input. Both `<ul>` and `<ol>` are considered: a
- * numbered checklist (`1. [x] a`, which marked renders as an `<ol>` of checkbox
- * `<li>`s) would otherwise lose its task state. TipTap task lists are unordered,
- * so a matching `<ol>` is emitted as `data-type="taskList"` exactly like a
- * `<ul>`. Mixed or ordinary lists (including ordinary `<ol>` lists) are left
- * untouched so they keep rendering as bullet/numbered lists. The marked `<p>`
- * wrapper is kept inside the `<li>` because TaskItem content allows paragraphs.
- */
-function bridgeTaskLists(html) {
-    // Cheap early-out: if the markup contains no checkbox input at all there is
-    // nothing to bridge, so skip the expensive JSDOM parse entirely. This is the
-    // common case (most pages have no task lists).
-    if (!/type=["']?checkbox/i.test(html)) {
-        return html;
-    }
-    // Defensive cap (consistent with preprocessCallouts): skip the bridge for
-    // pathologically large inputs rather than running a second expensive JSDOM
-    // parse on a multi-megabyte payload. The markup is passed through verbatim.
-    if (html.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-        return html;
-    }
-    const dom = new JSDOM(html);
-    const document = dom.window.document;
-    // Collect the checkbox(es) that belong to THIS <li> directly: either direct
-    // child <input type="checkbox"> elements or ones inside the <li>'s direct <p>
-    // child (the shape marked emits: `<li><p><input type="checkbox"> text</p></li>`).
-    // Checkboxes nested deeper (e.g. inside a child <ul>/<ol>) are excluded so a
-    // bullet <li> that merely contains a nested task sublist is not misdetected.
-    // Raw inline HTML can put more than one checkbox in a single <li>; we gather
-    // ALL of them so none survive into the converted item.
-    const directCheckboxes = (li) => {
-        const found = [];
-        for (const child of Array.from(li.children)) {
-            if (child.tagName === "INPUT" &&
-                child.getAttribute("type") === "checkbox") {
-                found.push(child);
-                continue;
-            }
-            if (child.tagName === "P") {
-                for (const inp of Array.from(child.querySelectorAll(":scope > input[type='checkbox']"))) {
-                    found.push(inp);
-                }
-            }
-        }
-        return found;
-    };
-    // Both <ul> and <ol> are candidates: an <ol> whose every direct <li> carries
-    // its own checkbox is a numbered checklist that must also become a taskList.
-    const lists = Array.from(document.querySelectorAll("ul, ol"));
-    for (const list of lists) {
-        // Only consider DIRECT child <li> elements; nested lists are handled by
-        // their own iteration of the outer loop.
-        const items = Array.from(list.children).filter((child) => child.tagName === "LI");
-        if (items.length === 0)
-            continue;
-        const itemCheckboxes = items.map((li) => directCheckboxes(li));
-        // Convert only when every direct <li> carries at least one OWN checkbox.
-        if (!itemCheckboxes.every((boxes) => boxes.length > 0))
-            continue;
-        // A numbered checklist arrives as an <ol>. We must NOT leave the tag as
-        // <ol> while tagging it data-type="taskList": generateJSON would then match
-        // BOTH the orderedList rule (tag ol) and the taskList rule (data-type),
-        // emitting a phantom empty orderedList beside the real taskList. So rename a
-        // qualifying <ol> to a <ul> — move its <li> children over and replace it —
-        // leaving only the taskList rule to match. Already-<ul> lists are unchanged.
-        let target = list;
-        if (list.tagName === "OL") {
-            const ul = document.createElement("ul");
-            // Carry over existing attributes (e.g. class) so nothing is silently lost.
-            for (const attr of Array.from(list.attributes)) {
-                ul.setAttribute(attr.name, attr.value);
-            }
-            // Move every child node (including the <li>s we collected) into the <ul>.
-            while (list.firstChild) {
-                ul.appendChild(list.firstChild);
-            }
-            list.replaceWith(ul);
-            target = ul;
-        }
-        target.setAttribute("data-type", "taskList");
-        items.forEach((li, index) => {
-            const boxes = itemCheckboxes[index];
-            // The first checkbox determines the checked state (matches the previous
-            // single-checkbox behaviour); any extras only need removing.
-            const input = boxes[0] ?? null;
-            li.setAttribute("data-type", "taskItem");
-            const checked = input != null &&
-                (input.hasAttribute("checked") || input.checked);
-            li.setAttribute("data-checked", checked ? "true" : "false");
-            // Remove ALL direct checkbox inputs so none survive into the content
-            // (a raw-inline-HTML <li> may carry more than one).
-            for (const box of boxes) {
-                box.remove();
-            }
-        });
-    }
-    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>.
-// Definition detection + fence handling are shared with analyzeFootnotes via
-// lexFootnoteLines (footnote-lex.js). FOOTNOTE_REF_RE is the inline tokenizer's.
-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 bodyLines = [];
-    const defs = [];
-    // Shared lexer (footnote-lex): a `[^id]: ...` line inside a ``` / ~~~ code
-    // block is inert and stays in the body verbatim; only real definition lines
-    // are pulled out. analyzeFootnotes() consumes the SAME lexer so its diagnostics
-    // match exactly what import keeps/strips (#166).
-    for (const tok of lexFootnoteLines(markdown)) {
-        if (!tok.inFence && tok.definition)
-            defs.push(tok.definition);
-        else
-            bodyLines.push(tok.line);
-    }
-    if (defs.length === 0)
-        return { body: markdown, section: "" };
-    // Duplicate definition ids: FIRST WINS, the rest are DROPPED (mirror of
-    // editor-ext extractFootnoteDefinitions). Reference markers are left untouched
-    // so repeated `[^a]` references reuse the single footnote (Pandoc semantics,
-    // #166). The dropped duplicate is surfaced to the caller via analyzeFootnotes
-    // (`duplicateDefinitions`), not silently lost. MUST stay in sync with the
-    // editor-ext mirror.
-    const firstById = new Map(); // id -> first definition text
-    for (const def of defs) {
-        if (!firstById.has(def.id))
-            firstById.set(def.id, def.text);
-    }
-    const inner = [...firstById.entries()]
-        .map(([id, text]) => `<div data-footnote-def data-id="${escapeFootnoteAttr(id)}"><p>${marked.parseInline(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.
- *
- * This conversion does NOT canonicalize footnotes — it is the shared, content-
- * preserving primitive used by BOTH page write paths and COMMENT bodies
- * (createComment / updateComment). Canonicalization MUST NOT run on a comment
- * body: a comment may legitimately contain a footnote-definition line
- * (`[^1]: text`) with no matching reference, and the canonicalizer drops a
- * reference-less footnotesList — which would silently delete the comment's text.
- *
- * Page write paths that DO need the canonical footnote topology call
- * `markdownToProseMirrorCanonical` instead (markdown import, update_page markdown
- * path). Keep this function reference-loss-free.
- */
-export async function markdownToProseMirror(markdownContent) {
-    const withCallouts = await preprocessCallouts(markdownContent);
-    const { body, section } = extractFootnotes(withCallouts);
-    const html = (await marked.parse(body)) + section;
-    const bridged = bridgeTaskLists(html);
-    return generateJSON(bridged, docmostExtensions);
-}
-/**
- * Page-write variant of `markdownToProseMirror`: converts markdown then enforces
- * the canonical footnote topology. The footnote `section` markdown is emitted in
- * DEFINITION order, but numbering derives from REFERENCE order, so without this
- * the bottom list renders out of order (`1, 4, 2, 3, …`); orphan definitions and
- * duplicate lists are also normalized. Idempotent — a no-op once canonical, and a
- * no-op for footnote-free content.
- *
- * Use this ONLY for full-document PAGE writes (never for comment bodies, where it
- * would drop a reference-less footnote definition — see `markdownToProseMirror`).
- */
-export async function markdownToProseMirrorCanonical(markdownContent) {
-    return canonicalizeFootnotes(await markdownToProseMirror(markdownContent));
-}
-/**
- * Build the collaboration WebSocket URL from an API base URL:
- * switch http(s)->ws(s), strip a trailing /api, mount on /collab.
- * Shared by the live read and the mutate path so both target the same socket.
- */
-export function buildCollabWsUrl(baseUrl) {
-    let wsUrl = baseUrl.replace(/^http/, "ws");
-    try {
-        const urlObj = new URL(wsUrl);
-        if (urlObj.pathname.endsWith("/api") || urlObj.pathname.endsWith("/api/")) {
-            urlObj.pathname = urlObj.pathname.replace(/\/api\/?$/, "");
-        }
-        urlObj.pathname = urlObj.pathname.replace(/\/$/, "") + "/collab";
-        // Drop any query/hash from the base URL so it is not carried into the
-        // collaboration ws URL.
-        urlObj.search = "";
-        urlObj.hash = "";
-        wsUrl = urlObj.toString();
-    }
-    catch (e) {
-        // Fallback if URL parsing fails
-        if (!wsUrl.endsWith("/collab")) {
-            wsUrl = wsUrl.replace(/\/$/, "") + "/collab";
-        }
-    }
-    return wsUrl;
-}
-/**
- * Encode a ProseMirror doc to a Yjs document, sanitizing it first and turning
- * the opaque yjs "Unexpected content type" failure into a descriptive error.
- *
- * `sanitizeForYjs` strips `undefined` node/mark attributes (the common cause of
- * the failure); if `toYdoc` still throws, `findUnstorableAttr` is used to point
- * at the offending attribute path.
- */
-export function buildYDoc(doc) {
-    const safe = sanitizeForYjs(doc);
-    try {
-        return TiptapTransformer.toYdoc(safe, "default", docmostExtensions);
-    }
-    catch (e) {
-        throw unstorableYjsError(safe, "toYdoc", e);
-    }
-}
-/**
- * Write a new ProseMirror doc into the live Yjs fragment by STRUCTURAL DIFF,
- * preserving the Yjs identity of unchanged nodes (issue #152).
- *
- * The previous approach deleted the whole fragment and re-applied a fresh Y.Doc,
- * which discarded every Yjs node id. y-prosemirror anchors the editor selection
- * to those ids, so an open editor's cursor lost its anchor and snapped to the
- * end of the document on every agent write (most visibly on comment anchoring,
- * which changes no text at all). `updateYFragment` is exactly the routine the
- * editor itself uses to sync ProseMirror edits into Yjs: it diffs the new node
- * against the current fragment and touches only the changed children, so
- * unchanged nodes keep their ids and the live cursor stays put.
- *
- * Must run inside a single `transact` so the diff applies atomically (no remote
- * update interleaves). Keeps `buildYDoc`'s `findUnstorableAttr` diagnostic for
- * the opaque "Unexpected content type" encode failure.
- */
-export function applyDocToFragment(ydoc, newDoc) {
-    const safe = sanitizeForYjs(newDoc);
-    const fragment = ydoc.getXmlFragment("default");
-    // Hydrate the ProseMirror node in its OWN try so a failure here (e.g. an
-    // unknown node type) is labelled "fromJSON" — the stage that actually threw —
-    // instead of being misattributed to the Yjs write stage (#154 review).
-    let pmNode;
-    try {
-        pmNode = PMNode.fromJSON(docmostSchema, safe);
-    }
-    catch (e) {
-        throw unstorableYjsError(safe, "fromJSON", e);
-    }
-    try {
-        ydoc.transact(() => {
-            updateYFragment(ydoc, fragment, pmNode, {
-                mapping: new Map(),
-                isOMark: new Map(),
-            });
-        });
-    }
-    catch (e) {
-        throw unstorableYjsError(safe, "updateYFragment", e);
-    }
-}
-/**
- * Run an independent Yjs-encodability check (the same `sanitizeForYjs` + schema
- * the apply path uses) and throw the same descriptive error when the doc cannot
- * be stored. Used by the dry-run preview.
- *
- * Note: it does NOT run `updateYFragment` against the live fragment, so it is an
- * encodability GATE, not a byte-for-byte rehearsal of apply — `buildYDoc`
- * (`toYdoc`) and `applyDocToFragment` (`updateYFragment`) are two different
- * encoders that nonetheless reject the same unstorable attributes. To narrow the
- * preview/apply gap it ALSO rehearses the apply path's `PMNode.fromJSON`
- * hydration, so a doc that would only fail there (e.g. an unknown node type) is
- * rejected at preview time too (#154 review). Still cheap: no live fragment, no
- * `updateYFragment`.
- */
-export function assertYjsEncodable(doc) {
-    buildYDoc(doc);
-    const safe = sanitizeForYjs(doc);
-    try {
-        PMNode.fromJSON(docmostSchema, safe);
-    }
-    catch (e) {
-        throw unstorableYjsError(safe, "fromJSON", e);
-    }
-}
-/** Time we wait for the initial handshake/sync before giving up. */
-const CONNECT_TIMEOUT_MS = 25000;
-/** Time we wait for the server to acknowledge our write before giving up. */
-const PERSIST_TIMEOUT_MS = 20000;
-/**
- * Safely mutate the live content of a page over the collaboration websocket.
- *
- * This is the single safe write path for every MCP content mutation. It:
- *   1. serializes per-page writes through withPageLock (no two MCP writes on
- *      the same page overlap);
- *   2. connects to Hocuspocus and waits for the initial sync so the local ydoc
- *      mirrors the authoritative server doc — INCLUDING edits/comments/images
- *      that are not yet in the debounced REST snapshot;
- *   3. inside onSynced, SYNCHRONOUSLY reads the live doc, runs `transform`, and
- *      writes the result back — with no `await` between read and write so no
- *      remote update can interleave and clobber concurrent human edits;
- *   4. waits for the server to acknowledge the write (unsyncedChanges -> 0)
- *      before resolving, so the next operation observes our change.
- *
- * `transform` receives the live ProseMirror doc and returns the NEW full
- * ProseMirror doc to write, or `null` to abort with no write (a no-op). If
- * `transform` throws, the error is propagated to the caller (not swallowed).
- *
- * Resolves a `MutationResult { doc, verify }`: `doc` is the doc that was
- * written (or the live doc when the transform aborted), and `verify` is a
- * verifiable change report (text/block/mark deltas) of what actually changed.
- * The report is computed AFTER the atomic read->write, so it never widens the
- * read->write window, and it never throws (it can NEVER break a write).
- */
-export async function mutatePageContent(pageId, collabToken, baseUrl, transform) {
-    return withPageLock(pageId, () => {
-        if (process.env.DEBUG) {
-            console.error(`Starting realtime content mutate for page ${pageId}`);
-            // Token prefix is sensitive; only log it under DEBUG.
-            console.error(`Token prefix: ${collabToken ? collabToken.substring(0, 5) : "NONE"}...`);
-        }
-        const ydoc = new Y.Doc();
-        const wsUrl = buildCollabWsUrl(baseUrl);
-        if (process.env.DEBUG)
-            console.error(`Connecting to WebSocket: ${wsUrl}`);
-        return new Promise((resolve, reject) => {
-            let provider;
-            let applied = false; // onSynced may fire again on reconnect — apply once.
-            let settled = false;
-            // Set true on disconnect/close so a reconnect-driven unsyncedChanges->0
-            // cannot be mistaken for a successful persist of our write.
-            let connectionLost = false;
-            let connectTimer;
-            let persistTimer;
-            let unsyncedHandler;
-            const cleanup = () => {
-                if (connectTimer)
-                    clearTimeout(connectTimer);
-                if (persistTimer)
-                    clearTimeout(persistTimer);
-                if (provider) {
-                    if (unsyncedHandler) {
-                        try {
-                            provider.off("unsyncedChanges", unsyncedHandler);
-                        }
-                        catch (err) { }
-                    }
-                    try {
-                        provider.destroy();
-                    }
-                    catch (err) { }
-                }
-            };
-            const finish = (err, value) => {
-                if (settled)
-                    return;
-                settled = true;
-                cleanup();
-                if (err)
-                    reject(err);
-                else
-                    resolve(value);
-            };
-            connectTimer = setTimeout(() => {
-                finish(new Error("Connection timeout to collaboration server"));
-            }, CONNECT_TIMEOUT_MS);
-            // Resolve once the server has acknowledged our update. The provider
-            // increments unsyncedChanges when our local update is sent and
-            // decrements it when the server replies with a SyncStatus(applied=true);
-            // reaching 0 means the authoritative in-memory ydoc on the server now
-            // contains our write.
-            const waitForPersistence = () => {
-                if (settled)
-                    return;
-                // A missing provider is a failure, not a success: without it the write
-                // can never have been acknowledged. Only an actual unsyncedChanges===0
-                // on a live provider counts as persisted.
-                if (!provider) {
-                    finish(new Error("collab provider gone before persistence"));
-                    return;
-                }
-                if (provider.unsyncedChanges === 0) {
-                    finish(null, mutationResult);
-                    return;
-                }
-                persistTimer = setTimeout(() => {
-                    finish(new Error("Timeout waiting for collaboration server to persist the update"));
-                }, PERSIST_TIMEOUT_MS);
-                unsyncedHandler = (data) => {
-                    // Only treat unsyncedChanges->0 as success when the connection is
-                    // still up. A transient disconnect + reconnect handshake can drive
-                    // the counter back to 0 without our write being re-transmitted; in
-                    // that case let the disconnect/close error win instead.
-                    if (data.number === 0 && !connectionLost) {
-                        finish(null, mutationResult);
-                    }
-                };
-                provider.on("unsyncedChanges", unsyncedHandler);
-            };
-            // The verifiable result resolved on every success/abort path. Set on
-            // abort (no-op report) and after a real write (computed change report).
-            let mutationResult;
-            provider = new HocuspocusProvider({
-                url: wsUrl,
-                name: `page.${pageId}`,
-                document: ydoc,
-                token: collabToken,
-                // @ts-ignore - Required for Node.js environment
-                WebSocketPolyfill: WebSocket,
-                onConnect: () => {
-                    if (process.env.DEBUG)
-                        console.error("WS Connect");
-                },
-                // An unexpected disconnect/close while we are still waiting (during the
-                // connect-wait before onSynced, or during the persistence wait after the
-                // write) means the update will never be acknowledged — surface it now
-                // instead of hanging until the connect/persist timeout fires. `finish`
-                // is idempotent via the `settled` flag, so the onClose that our own
-                // cleanup()->provider.destroy() triggers (after settled=true is set) is
-                // a harmless no-op and cannot cause a double-resolve.
-                onDisconnect: () => {
-                    if (process.env.DEBUG)
-                        console.error("WS Disconnect");
-                    // Mark BEFORE finish so the unsyncedChanges handler (if it races)
-                    // sees the connection as lost and won't report a false success.
-                    connectionLost = true;
-                    finish(new Error("Collaboration connection closed before the update was persisted/synced"));
-                },
-                onClose: () => {
-                    if (process.env.DEBUG)
-                        console.error("WS Close");
-                    // Mark BEFORE finish so the unsyncedChanges handler (if it races)
-                    // sees the connection as lost and won't report a false success.
-                    connectionLost = true;
-                    finish(new Error("Collaboration connection closed before the update was persisted/synced"));
-                },
-                onSynced: () => {
-                    if (applied || settled)
-                        return;
-                    applied = true;
-                    if (process.env.DEBUG)
-                        console.error("Connected and synced!");
-                    // CRITICAL: everything between reading the live doc and writing it
-                    // back must stay synchronous (no await). While the JS event loop is
-                    // not yielded, no incoming remote update can interleave, so any
-                    // already-synced concurrent edits are preserved in liveDoc.
-                    let newDoc;
-                    let beforeDoc;
-                    try {
-                        let liveDoc = TiptapTransformer.fromYdoc(ydoc, "default");
-                        if (!liveDoc ||
-                            typeof liveDoc !== "object" ||
-                            !Array.isArray(liveDoc.content)) {
-                            liveDoc = { type: "doc", content: [] };
-                        }
-                        // Snapshot the before-doc for the change report. Docs are
-                        // JSON-serializable, so this is a safe deep clone.
-                        beforeDoc = JSON.parse(JSON.stringify(liveDoc));
-                        newDoc = transform(liveDoc);
-                        if (newDoc == null) {
-                            // Transform aborted — write nothing, return the live doc with a
-                            // no-op change report.
-                            mutationResult = {
-                                doc: liveDoc,
-                                verify: {
-                                    changed: false,
-                                    textInserted: 0,
-                                    textDeleted: 0,
-                                    blocksChanged: 0,
-                                    marks: {},
-                                    summary: "no changes (transform aborted)",
-                                },
-                            };
-                            finish(null, mutationResult);
-                            return;
-                        }
-                        // Structural diff into the live fragment (issue #152): preserves
-                        // the Yjs ids of unchanged nodes, so an open editor's cursor is not
-                        // yanked to the end of the document on every agent write.
-                        applyDocToFragment(ydoc, newDoc);
-                    }
-                    catch (e) {
-                        // Includes errors thrown by transform (e.g. "afterText not found",
-                        // "text not found"): propagate them verbatim to the caller.
-                        finish(e instanceof Error ? e : new Error(String(e)));
-                        return;
-                    }
-                    // Compute the verifiable change report AFTER the transact write: it
-                    // only needs the JSON before/after, so it cannot affect the atomic
-                    // read->write window, and summarizeChange never throws.
-                    mutationResult = {
-                        doc: newDoc,
-                        verify: summarizeChange(beforeDoc, newDoc),
-                    };
-                    if (process.env.DEBUG)
-                        console.error("Content written, waiting for server to persist...");
-                    waitForPersistence();
-                },
-                onAuthenticationFailed: () => {
-                    finish(new Error("Authentication failed for collaboration connection"));
-                },
-            });
-        });
-    });
-}
-/**
- * Replace the live content of a page over the collaboration websocket.
- * Accepts a ready ProseMirror JSON document; the caller controls whether
- * it was produced from markdown (ids regenerate) or edited in place
- * (existing block ids preserved).
- *
- * This is an intentional full replace (used by update_page / update_page_json),
- * but now runs under the per-page lock and waits for server persistence via
- * mutatePageContent.
- */
-export async function replacePageContent(pageId, prosemirrorDoc, collabToken, baseUrl) {
-    // Fail fast on a bad document instead of deferring the failure into the
-    // collaboration write (where TiptapTransformer.toYdoc(undefined) used to
-    // throw). The transform must return a valid ProseMirror doc.
-    if (prosemirrorDoc == null ||
-        typeof prosemirrorDoc !== "object" ||
-        prosemirrorDoc.type !== "doc") {
-        throw new Error("replacePageContent: invalid ProseMirror document");
-    }
-    return await mutatePageContent(pageId, collabToken, baseUrl, () => prosemirrorDoc);
-}
-/**
- * Markdown update path (kept for backwards compatibility).
- * NOTE: this re-imports the whole document — block ids are regenerated.
- * Tables and :::callout::: blocks survive thanks to the full schema.
- */
-export async function updatePageContentRealtime(pageId, markdownContent, collabToken, baseUrl) {
-    // PAGE write: canonicalize footnotes (markdown import builds the bottom list in
-    // definition order; numbering is reference-ordered).
-    const tiptapJson = await markdownToProseMirrorCanonical(markdownContent);
-    return await mutatePageContent(pageId, collabToken, baseUrl, () => tiptapJson);
-}
diff --git a/packages/mcp/build/lib/comment-anchor.js b/packages/mcp/build/lib/comment-anchor.js
deleted file mode 100644
index b5c26dc4..00000000
--- a/packages/mcp/build/lib/comment-anchor.js
+++ /dev/null
@@ -1,371 +0,0 @@
-/**
- * Inline-comment anchoring against a ProseMirror document.
- *
- * Docmost stores an inline comment's highlight as a `comment` MARK on the
- * document text (`{ type: "comment", attrs: { commentId, resolved } }`); the
- * `/comments/create` API only records the comment row + its `selection` text and
- * does NOT insert that mark, so the anchor has to be written into the page
- * content separately. This module finds where a selection lives in the document
- * and splices the comment mark across the matched range.
- *
- * Matching has to be robust because the agent supplies the selection as plain
- * text while the document stores rich inline content: a selection can span
- * several adjacent text nodes (inline code / bold / links each become their own
- * text node), and the document may use smart/typographic quotes, dash variants,
- * non-breaking spaces, or collapsed runs of whitespace that the agent typed as
- * ASCII quotes/hyphens/single spaces. We therefore normalize both sides before
- * comparing and match across maximal runs of consecutive text nodes within a
- * single block, while mapping every normalized character back to its raw index
- * so the mark lands on the exact original characters.
- */
-/** Typographic double-quote variants mapped to ASCII `"`. */
-const DOUBLE_QUOTES = "«»„“”‟〝〞＂";
-/** Typographic single-quote/apostrophe variants mapped to ASCII `'`. */
-const SINGLE_QUOTES = "‘’‚‛";
-/** Dash variants mapped to ASCII `-`. */
-const DASHES = "–—―−‐‑‒";
-/** Guard against pathological/cyclic documents in the depth-first walk. */
-const MAX_DEPTH = 200;
-/** The comment mark Docmost stores on anchored text. */
-function makeCommentMark(commentId) {
-    // The comment mark schema declares both commentId and resolved; include
-    // resolved:false for completeness so the stored mark matches the editor's.
-    return { type: "comment", attrs: { commentId, resolved: false } };
-}
-/** True for any character we collapse/replace with a single normal space. */
-function isWhitespaceChar(ch) {
-    // Regular ASCII whitespace plus the special spaces called out in the spec:
-    // nbsp, narrow nbsp, en/em/thin/hair/figure spaces, etc. \s covers tab and
-    // newline; the explicit code points cover the non-breaking variants \s misses
-    // in some engines, so list them for determinism.
-    return (/\s/.test(ch) ||
-        ch === " " || // no-break space
-        ch === " " || // figure space
-        ch === " " || // narrow no-break space
-        ch === " " || // thin space
-        ch === " " || // hair space
-        ch === " " || // en space
-        ch === " " // em space
-    );
-}
-/**
- * Normalize a string for matching and return both the normalized text and a
- * `map` where `map[i]` is the index into the ORIGINAL `s` of the i-th
- * normalized character.
- *
- * Rules: map smart quotes / dashes / special spaces to their ASCII forms,
- * collapse any run of whitespace to a SINGLE space (whose map entry points at
- * the FIRST raw whitespace char of the run), and DO NOT lowercase (anchoring is
- * case-sensitive to match the exact document text).
- */
-export function normalizeForMatch(s) {
-    let norm = "";
-    const map = [];
-    let i = 0;
-    while (i < s.length) {
-        const ch = s[i];
-        if (isWhitespaceChar(ch)) {
-            // Collapse the whole whitespace run to one space mapped to the run start.
-            const runStart = i;
-            while (i < s.length && isWhitespaceChar(s[i]))
-                i++;
-            norm += " ";
-            map.push(runStart);
-            continue;
-        }
-        let mapped = ch;
-        if (DOUBLE_QUOTES.indexOf(ch) !== -1)
-            mapped = '"';
-        else if (SINGLE_QUOTES.indexOf(ch) !== -1)
-            mapped = "'";
-        else if (DASHES.indexOf(ch) !== -1)
-            mapped = "-";
-        norm += mapped;
-        map.push(i);
-        i++;
-    }
-    return { norm, map };
-}
-/**
- * Find a selection inside a SINGLE block's direct `content` array.
- *
- * Builds maximal runs of consecutive `text` nodes (any non-text inline node,
- * e.g. a mention, breaks the run), normalizes each run and the selection the
- * same way, then searches each run for the normalized selection. Returns the
- * child/offset range of the FIRST matching run, or `null` if none match.
- */
-export function findAnchorInBlock(blockContent, selection) {
-    if (!Array.isArray(blockContent))
-        return null;
-    const normSelObj = normalizeForMatch(selection);
-    // Trim leading/trailing spaces on the NORMALIZED selection only.
-    const normSel = normSelObj.norm.trim();
-    if (normSel.length === 0)
-        return null;
-    let i = 0;
-    while (i < blockContent.length) {
-        const node = blockContent[i];
-        if (!node || typeof node !== "object" || node.type !== "text") {
-            i++;
-            continue;
-        }
-        // Accumulate a maximal run of consecutive text nodes.
-        let rawRun = "";
-        const rawToChild = [];
-        let j = i;
-        while (j < blockContent.length) {
-            const n = blockContent[j];
-            if (!n || typeof n !== "object" || n.type !== "text")
-                break;
-            const text = typeof n.text === "string" ? n.text : "";
-            for (let k = 0; k < text.length; k++) {
-                rawToChild.push({ childIdx: j, offset: k });
-            }
-            rawRun += text;
-            j++;
-        }
-        // Try to match within this run.
-        const { norm, map } = normalizeForMatch(rawRun);
-        const idx = norm.indexOf(normSel);
-        if (idx !== -1) {
-            const rawStart = map[idx];
-            const rawEndExclusive = idx + normSel.length < map.length
-                ? map[idx + normSel.length]
-                : rawRun.length;
-            const startLoc = rawToChild[rawStart];
-            // rawEndExclusive points at the raw char AFTER the match; the last matched
-            // raw char is at rawEndExclusive-1, so endOffset is its offset + 1.
-            const lastLoc = rawToChild[rawEndExclusive - 1];
-            return {
-                startChild: startLoc.childIdx,
-                startOffset: startLoc.offset,
-                endChild: lastLoc.childIdx,
-                endOffset: lastLoc.offset + 1,
-            };
-        }
-        // No match in this run: continue scanning AFTER it.
-        i = j > i ? j : i + 1;
-    }
-    return null;
-}
-/**
- * Reconstruct the RAW text spanned by an AnchorMatch inside one block's
- * `content` array. `startChild..endChild` are all text nodes (guaranteed by
- * findAnchorInBlock, which only builds runs of `text` nodes), so concatenate
- * each node's text slice: from `startOffset` on the first node, up to
- * `endOffset` on the last, and the whole `.text` for any node fully inside the
- * range. Mirrors spliceCommentMark's per-node slicing so the string returned
- * here is EXACTLY the characters the comment mark will cover.
- */
-function reconstructRawText(blockContent, match) {
-    const { startChild, startOffset, endChild, endOffset } = match;
-    let out = "";
-    for (let k = startChild; k <= endChild; k++) {
-        const n = blockContent[k];
-        const text = typeof n.text === "string" ? n.text : "";
-        const sliceStart = k === startChild ? startOffset : 0;
-        const sliceEnd = k === endChild ? endOffset : text.length;
-        out += text.slice(sliceStart, sliceEnd);
-    }
-    return out;
-}
-/**
- * Return the RAW document substring that `selection` would anchor to — the exact
- * characters the comment mark will cover — or `null` when the selection cannot
- * be anchored anywhere in `doc`.
- *
- * This mirrors canAnchorInDoc / applyAnchorInDoc EXACTLY (same depth-first,
- * document-order traversal and the same findAnchorInBlock match on the FIRST
- * matching block), but instead of a boolean / an in-place mutation it
- * reconstructs the raw text spanned by the matched range. Because
- * findAnchorInBlock maps the normalized selection back to raw text-node
- * positions, the returned string is the document's ORIGINAL characters (smart
- * quotes, em-dashes, nbsp, collapsed whitespace) — NOT the normalized ASCII
- * agent input.
- *
- * Callers store THIS as the comment's `selection` so the stored value equals the
- * text actually under the mark, which is what the apply-suggestion equality
- * check (replaceYjsMarkedText's `joinedText !== expectedText`) compares against.
- * Without it a suggestion whose anchor only matched via normalization would be
- * un-appliable (spurious 409).
- */
-export function getAnchoredText(doc, selection) {
-    const visit = (node, depth) => {
-        if (depth > MAX_DEPTH || !node || typeof node !== "object")
-            return null;
-        if (!Array.isArray(node.content))
-            return null;
-        const match = findAnchorInBlock(node.content, selection);
-        if (match)
-            return reconstructRawText(node.content, match);
-        for (const child of node.content) {
-            if (child && typeof child === "object" && Array.isArray(child.content)) {
-                const found = visit(child, depth + 1);
-                if (found !== null)
-                    return found;
-            }
-        }
-        return null;
-    };
-    return visit(doc, 0);
-}
-/**
- * Depth-first, document-order check for whether `selection` can be anchored
- * anywhere in `doc`. At each node with an array `content`, first try to match
- * within that node's own content, then recurse into children that themselves
- * have a `content` array.
- */
-export function canAnchorInDoc(doc, selection) {
-    const visit = (node, depth) => {
-        if (depth > MAX_DEPTH || !node || typeof node !== "object")
-            return false;
-        if (!Array.isArray(node.content))
-            return false;
-        if (findAnchorInBlock(node.content, selection))
-            return true;
-        for (const child of node.content) {
-            if (child && typeof child === "object" && Array.isArray(child.content)) {
-                if (visit(child, depth + 1))
-                    return true;
-            }
-        }
-        return false;
-    };
-    return visit(doc, 0);
-}
-/**
- * Split the matched text nodes and splice the comment mark across the range.
- * `blockContent` is mutated IN PLACE. `match.startChild..endChild` are all text
- * nodes (guaranteed by findAnchorInBlock building runs of text nodes).
- */
-function spliceCommentMark(blockContent, match, commentId) {
-    const { startChild, startOffset, endChild, endOffset } = match;
-    const commentMark = makeCommentMark(commentId);
-    const fragments = [];
-    for (let k = startChild; k <= endChild; k++) {
-        const n = blockContent[k];
-        const text = typeof n.text === "string" ? n.text : "";
-        const sliceStart = k === startChild ? startOffset : 0;
-        const sliceEnd = k === endChild ? endOffset : text.length;
-        const before = k === startChild ? text.slice(0, startOffset) : "";
-        const marked = text.slice(sliceStart, sliceEnd);
-        const after = k === endChild ? text.slice(endOffset) : "";
-        // Process per-node so each node's OWN marks/attrs are preserved.
-        const ownMarks = Array.isArray(n.marks) ? n.marks : [];
-        // Drop any pre-existing comment mark from the marked fragment so it ends up
-        // with exactly one comment mark (the new one) rather than two.
-        const markedBaseMarks = ownMarks.filter((m) => !(m && m.type === "comment"));
-        if (before.length > 0) {
-            fragments.push({ ...n, text: before, marks: [...ownMarks] });
-        }
-        if (marked.length > 0) {
-            fragments.push({
-                ...n,
-                text: marked,
-                marks: [...markedBaseMarks, commentMark],
-            });
-        }
-        if (after.length > 0) {
-            fragments.push({ ...n, text: after, marks: [...ownMarks] });
-        }
-    }
-    blockContent.splice(startChild, endChild - startChild + 1, ...fragments);
-}
-/**
- * Count how many times `selection` occurs across the whole document, using the
- * same normalization and run-matching as findAnchorInBlock but WITHOUT stopping
- * at the first hit: every non-overlapping occurrence within each block's text
- * runs is counted and summed across all blocks (depth-first, the same traversal
- * as canAnchorInDoc).
- *
- * This is the uniqueness gate for SUGGESTIONS: because applying a suggestion
- * rewrites the exact anchored text, an ambiguous anchor (>1 occurrence) would
- * silently edit the wrong place, so a suggestion is only allowed when this
- * returns exactly 1. Ordinary comments keep first-occurrence anchoring and do
- * not use this. (Note: counts OCCURRENCES, not just matching blocks, so two
- * occurrences inside one block are correctly reported as 2.)
- */
-export function countAnchorMatches(doc, selection) {
-    const normSel = normalizeForMatch(selection).norm.trim();
-    if (normSel.length === 0)
-        return 0;
-    // Count non-overlapping occurrences of the normalized selection within a
-    // single block's direct content, matching findAnchorInBlock's run building.
-    const countInBlock = (blockContent) => {
-        if (!Array.isArray(blockContent))
-            return 0;
-        let count = 0;
-        let i = 0;
-        while (i < blockContent.length) {
-            const node = blockContent[i];
-            if (!node || typeof node !== "object" || node.type !== "text") {
-                i++;
-                continue;
-            }
-            // Accumulate a maximal run of consecutive text nodes.
-            let rawRun = "";
-            let j = i;
-            while (j < blockContent.length) {
-                const n = blockContent[j];
-                if (!n || typeof n !== "object" || n.type !== "text")
-                    break;
-                rawRun += typeof n.text === "string" ? n.text : "";
-                j++;
-            }
-            const norm = normalizeForMatch(rawRun).norm;
-            // Count every non-overlapping occurrence in this run.
-            let from = 0;
-            for (;;) {
-                const idx = norm.indexOf(normSel, from);
-                if (idx === -1)
-                    break;
-                count++;
-                from = idx + normSel.length;
-            }
-            i = j > i ? j : i + 1;
-        }
-        return count;
-    };
-    let total = 0;
-    const visit = (node, depth) => {
-        if (depth > MAX_DEPTH || !node || typeof node !== "object")
-            return;
-        if (!Array.isArray(node.content))
-            return;
-        total += countInBlock(node.content);
-        for (const child of node.content) {
-            if (child && typeof child === "object" && Array.isArray(child.content)) {
-                visit(child, depth + 1);
-            }
-        }
-    };
-    visit(doc, 0);
-    return total;
-}
-/**
- * Depth-first (same order as canAnchorInDoc) over `doc`; on the FIRST block
- * whose content matches `selection`, splice the comment mark across the matched
- * range in place and return true. Returns false (and does NOT mutate) when no
- * block matches.
- */
-export function applyAnchorInDoc(doc, selection, commentId) {
-    const visit = (node, depth) => {
-        if (depth > MAX_DEPTH || !node || typeof node !== "object")
-            return false;
-        if (!Array.isArray(node.content))
-            return false;
-        const match = findAnchorInBlock(node.content, selection);
-        if (match) {
-            spliceCommentMark(node.content, match, commentId);
-            return true;
-        }
-        for (const child of node.content) {
-            if (child && typeof child === "object" && Array.isArray(child.content)) {
-                if (visit(child, depth + 1))
-                    return true;
-            }
-        }
-        return false;
-    };
-    return visit(doc, 0);
-}
diff --git a/packages/mcp/build/lib/diff.js b/packages/mcp/build/lib/diff.js
deleted file mode 100644
index c19ff9a9..00000000
--- a/packages/mcp/build/lib/diff.js
+++ /dev/null
@@ -1,423 +0,0 @@
-/**
- * Headless, Docmost-equivalent document diff.
- *
- * Docmost's history editor computes a change set with the exact pipeline below
- * (recreateTransform -> ChangeSet.addSteps -> simplifyChanges) and renders it as
- * editor decorations. This module runs the SAME computation but serializes the
- * result to text + integrity counts instead of decorations, so a diff can be
- * previewed without a browser.
- *
- * recreateTransform here comes from @fellow/prosemirror-recreate-transform, the
- * maintained published fork of the MIT prosemirror-recreate-steps source that
- * Docmost vendors in @docmost/editor-ext; it exposes the identical
- * recreateTransform(fromDoc, toDoc, { complexSteps, wordDiffs, simplifyDiff })
- * signature.
- *
- * If recreateTransform / the changeset throws on a pathological document pair,
- * we fall back to a coarse block-level text diff so the tool never hard-fails.
- */
-import { Node } from "@tiptap/pm/model";
-import { ChangeSet, simplifyChanges } from "@tiptap/pm/changeset";
-import { recreateTransform } from "@fellow/prosemirror-recreate-transform";
-import { docmostSchema } from "./docmost-schema.js";
-/** Recursively concatenate the plain text of a JSON node. */
-function plainText(node) {
-    if (!node || typeof node !== "object")
-        return "";
-    let out = "";
-    if (typeof node.text === "string")
-        out += node.text;
-    if (Array.isArray(node.content)) {
-        for (const child of node.content)
-            out += plainText(child);
-    }
-    return out;
-}
-/** Count nodes in a JSON doc that satisfy `pred` (recursive). */
-function countNodes(doc, pred) {
-    let n = 0;
-    const visit = (node) => {
-        if (!node || typeof node !== "object")
-            return;
-        if (pred(node))
-            n++;
-        if (Array.isArray(node.content))
-            for (const c of node.content)
-                visit(c);
-    };
-    visit(doc);
-    return n;
-}
-/**
- * Count UNIQUE links in a JSON doc by their `href`. A single link can be split
- * across several adjacent text runs (e.g. a "link+bold" run followed by a "link"
- * run); counting link-bearing runs would over-count it. Walking the tree and
- * collecting hrefs into a Set keys each distinct link once. Link marks with a
- * missing/empty href are bucketed under a single "" key so a malformed link is
- * still counted as one.
- */
-function countUniqueLinks(doc) {
-    const hrefs = new Set();
-    const visit = (node) => {
-        if (!node || typeof node !== "object")
-            return;
-        if (node.type === "text" && Array.isArray(node.marks)) {
-            for (const m of node.marks) {
-                if (m && m.type === "link") {
-                    const href = m.attrs && typeof m.attrs.href === "string" ? m.attrs.href : "";
-                    hrefs.add(href);
-                }
-            }
-        }
-        if (Array.isArray(node.content))
-            for (const c of node.content)
-                visit(c);
-    };
-    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;
-}
-/**
- * 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 : [];
-    const notesIdx = top.findIndex((n) => n &&
-        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) {
-        const text = plainText(block);
-        let m;
-        re.lastIndex = 0;
-        while ((m = re.exec(text)) !== null) {
-            markers.push(Number(m[1]));
-        }
-    }
-    return markers;
-}
-/** Compute the [old,new] integrity tuples for two JSON docs. */
-function computeIntegrity(oldDoc, newDoc, notesHeading) {
-    const images = [
-        countNodes(oldDoc, (n) => n.type === "image"),
-        countNodes(newDoc, (n) => n.type === "image"),
-    ];
-    const links = [
-        countUniqueLinks(oldDoc),
-        countUniqueLinks(newDoc),
-    ];
-    const tables = [
-        countNodes(oldDoc, (n) => n.type === "table"),
-        countNodes(newDoc, (n) => n.type === "table"),
-    ];
-    const callouts = [
-        countNodes(oldDoc, (n) => n.type === "callout"),
-        countNodes(newDoc, (n) => n.type === "callout"),
-    ];
-    const fns = [
-        footnoteMarkers(oldDoc, notesHeading),
-        footnoteMarkers(newDoc, notesHeading),
-    ];
-    return { images, links, tables, callouts, footnoteMarkers: fns };
-}
-/**
- * Resolve the lead text of the top-level block in a ProseMirror Node that
- * contains the given document position. Returns "" when out of range.
- */
-function blockContextAt(node, pos) {
-    try {
-        const clamped = Math.max(0, Math.min(pos, node.content.size));
-        const $pos = node.resolve(clamped);
-        // depth 1 is the top-level block in a doc node.
-        const block = $pos.depth >= 1 ? $pos.node(1) : $pos.node(0);
-        const text = block.textContent || "";
-        return text.length > 80 ? text.slice(0, 77) + "..." : text;
-    }
-    catch {
-        return "";
-    }
-}
-/** Truncate a string for the markdown summary. */
-function truncate(s, n = 120) {
-    return s.length > n ? s.slice(0, n - 3) + "..." : s;
-}
-/**
- * Coarse fallback: a block-by-block plain-text diff. Used only when the precise
- * changeset pipeline throws, so the tool degrades gracefully instead of failing.
- */
-function coarseDiff(oldDoc, newDoc) {
-    const oldBlocks = Array.isArray(oldDoc?.content) ? oldDoc.content : [];
-    const newBlocks = Array.isArray(newDoc?.content) ? newDoc.content : [];
-    const oldTexts = oldBlocks.map(plainText);
-    const newTexts = newBlocks.map(plainText);
-    const oldSet = new Set(oldTexts);
-    const newSet = new Set(newTexts);
-    const changes = [];
-    for (const t of oldTexts) {
-        if (!newSet.has(t) && t.trim() !== "") {
-            changes.push({ op: "delete", block: truncate(t, 80), text: t });
-        }
-    }
-    for (const t of newTexts) {
-        if (!oldSet.has(t) && t.trim() !== "") {
-            changes.push({ op: "insert", block: truncate(t, 80), text: t });
-        }
-    }
-    return changes;
-}
-/** Build the human-readable unified-ish markdown summary. */
-function renderMarkdown(result, fellBack) {
-    const lines = [];
-    const { summary, integrity, changes } = result;
-    lines.push(`# Diff: ${summary.inserted} inserted / ${summary.deleted} deleted (${summary.blocksChanged} blocks changed)`);
-    if (fellBack) {
-        lines.push("");
-        lines.push("> note: precise diff failed; coarse block-level diff shown.");
-    }
-    lines.push("");
-    lines.push("## Integrity (old -> new)");
-    lines.push(`- images: ${integrity.images[0]} -> ${integrity.images[1]}`);
-    lines.push(`- links: ${integrity.links[0]} -> ${integrity.links[1]}`);
-    lines.push(`- tables: ${integrity.tables[0]} -> ${integrity.tables[1]}`);
-    lines.push(`- callouts: ${integrity.callouts[0]} -> ${integrity.callouts[1]}`);
-    lines.push(`- footnoteMarkers: [${integrity.footnoteMarkers[0].join(", ")}] -> [${integrity.footnoteMarkers[1].join(", ")}]`);
-    lines.push("");
-    lines.push("## Changes");
-    if (changes.length === 0) {
-        lines.push("(no textual changes)");
-    }
-    else {
-        for (const c of changes) {
-            const sign = c.op === "insert" ? "+" : "-";
-            const ctx = c.block ? ` @ ${truncate(c.block, 60)}` : "";
-            lines.push(`${sign} ${truncate(c.text)}${ctx}`);
-        }
-    }
-    return lines.join("\n");
-}
-/**
- * Diff two ProseMirror JSON documents the way Docmost's history editor does and
- * serialize the result to text + integrity counts.
- *
- * @param oldDocJson the earlier document
- * @param newDocJson the later document
- * @param notesHeading heading delimiting body from notes for footnote counting
- */
-export function diffDocs(oldDocJson, newDocJson, notesHeading = "Примечания переводчика") {
-    const integrity = computeIntegrity(oldDocJson, newDocJson, notesHeading);
-    let changes = [];
-    let inserted = 0;
-    let deleted = 0;
-    let fellBack = false;
-    const changedBlocks = new Set();
-    try {
-        const oldNode = Node.fromJSON(docmostSchema, oldDocJson);
-        const newNode = Node.fromJSON(docmostSchema, newDocJson);
-        const tr = recreateTransform(oldNode, newNode, {
-            complexSteps: false,
-            wordDiffs: true,
-            simplifyDiff: true,
-        });
-        const changeSet = ChangeSet.create(oldNode).addSteps(tr.doc, tr.mapping.maps, []);
-        const simplified = simplifyChanges(changeSet.changes, newNode);
-        for (const change of simplified) {
-            // Deleted text lives in the OLD doc coordinate range [fromA, toA).
-            if (change.toA > change.fromA) {
-                const text = oldNode.textBetween(change.fromA, change.toA, "\n", " ");
-                if (text.length > 0) {
-                    deleted += text.length;
-                    const block = blockContextAt(oldNode, change.fromA);
-                    changes.push({ op: "delete", block, text });
-                    if (block)
-                        changedBlocks.add("d:" + block);
-                }
-            }
-            // Inserted text lives in the NEW doc coordinate range [fromB, toB).
-            if (change.toB > change.fromB) {
-                const text = newNode.textBetween(change.fromB, change.toB, "\n", " ");
-                if (text.length > 0) {
-                    inserted += text.length;
-                    const block = blockContextAt(newNode, change.fromB);
-                    changes.push({ op: "insert", block, text });
-                    if (block)
-                        changedBlocks.add("i:" + block);
-                }
-            }
-        }
-    }
-    catch {
-        // Pathological pair: degrade to a coarse block-level diff so we never throw.
-        fellBack = true;
-        changes = coarseDiff(oldDocJson, newDocJson);
-        for (const c of changes) {
-            if (c.op === "insert")
-                inserted += c.text.length;
-            else
-                deleted += c.text.length;
-            if (c.block)
-                changedBlocks.add(c.op[0] + ":" + c.block);
-        }
-    }
-    const partial = {
-        summary: { inserted, deleted, blocksChanged: changedBlocks.size },
-        integrity,
-        changes,
-    };
-    return { ...partial, markdown: renderMarkdown(partial, fellBack) };
-}
-/**
- * Recursively walk every `text` node and tally the count of each mark by
- * `mark.type` (e.g. `{ bold: 5, strike: 3, link: 2 }`). Pure and never throws.
- */
-function markCounts(doc) {
-    const counts = {};
-    const visit = (node) => {
-        if (!node || typeof node !== "object")
-            return;
-        if (node.type === "text" && Array.isArray(node.marks)) {
-            for (const m of node.marks) {
-                if (m && typeof m.type === "string") {
-                    counts[m.type] = (counts[m.type] || 0) + 1;
-                }
-            }
-        }
-        if (Array.isArray(node.content))
-            for (const c of node.content)
-                visit(c);
-    };
-    visit(doc);
-    return counts;
-}
-/**
- * Build a VerifyReport for a content mutation. Pure and never throws — on any
- * internal error it returns a minimal "changed (diff unavailable)" report so it
- * can NEVER break a write.
- *
- * `changed` is VALUE-based, not JSON-string-based: it is derived from the actual
- * deltas (text chars, blocks, mark counts, structural integrity counts), so two
- * value-equal docs that differ only in JSON key order report cleanly as
- * `changed:false` / "no content change" rather than a misleading +0/-0 change.
- *
- * The structural integrity delta (from diffDocs's `integrity` tuples) is what
- * makes `changed` true for an image/table/callout/link count change that diffs
- * to zero text — closing a verify blind spot for insert_image, delete_node on a
- * table, etc.
- */
-export function summarizeChange(before, after) {
-    try {
-        const diff = diffDocs(before, after);
-        // Per-mark-type delta: include a type only when its count actually changed.
-        const beforeMarks = markCounts(before);
-        const afterMarks = markCounts(after);
-        const marks = {};
-        for (const type of new Set([
-            ...Object.keys(beforeMarks),
-            ...Object.keys(afterMarks),
-        ])) {
-            const b = beforeMarks[type] || 0;
-            const a = afterMarks[type] || 0;
-            if (b !== a)
-                marks[type] = [b, a];
-        }
-        // Structural integrity delta from diffDocs: count-based [old,new] tuples for
-        // images/links/tables/callouts. Include a type only when old != new.
-        const integrity = diff.integrity;
-        const structure = {};
-        const countTypes = [
-            "images",
-            "links",
-            "tables",
-            "callouts",
-        ];
-        for (const type of countTypes) {
-            const [b, a] = integrity[type];
-            if (b !== a)
-                structure[type] = [b, a];
-        }
-        const textInserted = diff.summary.inserted;
-        const textDeleted = diff.summary.deleted;
-        const blocksChanged = diff.summary.blocksChanged;
-        const hasMarkDelta = Object.keys(marks).length > 0;
-        const hasStructureDelta = Object.keys(structure).length > 0;
-        // VALUE-based change decision: ignore JSON key-order no-ops entirely.
-        const changed = textInserted > 0 ||
-            textDeleted > 0 ||
-            blocksChanged > 0 ||
-            hasMarkDelta ||
-            hasStructureDelta;
-        if (!changed) {
-            return {
-                changed: false,
-                textInserted: 0,
-                textDeleted: 0,
-                blocksChanged: 0,
-                marks: {},
-                summary: "no content change",
-            };
-        }
-        const parts = [];
-        // Only mention text/blocks when they actually changed (avoid a misleading
-        // "+0/-0 chars, 0 block(s)" prefix on a pure mark/structure change).
-        if (textInserted > 0 || textDeleted > 0 || blocksChanged > 0) {
-            parts.push(`+${textInserted}/-${textDeleted} chars, ${blocksChanged} block(s)`);
-        }
-        const markParts = Object.entries(marks).map(([type, [b, a]]) => `${type} ${b}→${a}`);
-        if (markParts.length > 0)
-            parts.push(`marks: ${markParts.join(", ")}`);
-        const structureParts = Object.entries(structure).map(([type, [b, a]]) => `${type} ${b}→${a}`);
-        if (structureParts.length > 0)
-            parts.push(structureParts.join(", "));
-        // `changed` is true here, so at least one group is present and parts is non-empty.
-        const summary = `changed: ${parts.join("; ")}`;
-        const report = {
-            changed: true,
-            textInserted,
-            textDeleted,
-            blocksChanged,
-            marks,
-            summary,
-        };
-        if (hasStructureDelta)
-            report.structure = structure;
-        return report;
-    }
-    catch {
-        // A pathological pair must never break a write: degrade to a minimal report.
-        return {
-            changed: true,
-            textInserted: 0,
-            textDeleted: 0,
-            blocksChanged: 0,
-            marks: {},
-            summary: "changed (diff unavailable)",
-        };
-    }
-}
diff --git a/packages/mcp/build/lib/docmost-schema.js b/packages/mcp/build/lib/docmost-schema.js
deleted file mode 100644
index 2c7b576a..00000000
--- a/packages/mcp/build/lib/docmost-schema.js
+++ /dev/null
@@ -1,1172 +0,0 @@
-/**
- * Full TipTap extension set matching the real Docmost document schema.
- *
- * The default StarterKit-only schema silently destroys Docmost-specific
- * nodes (callout, table) and drops attributes it does not know about
- * (node ids, image sizing, link targets). Every code path that converts
- * to or from ProseMirror JSON must use THIS set, otherwise a round-trip
- * loses content.
- */
-import StarterKit from "@tiptap/starter-kit";
-import Image from "@tiptap/extension-image";
-import TaskList from "@tiptap/extension-task-list";
-import TaskItem from "@tiptap/extension-task-item";
-import Highlight from "@tiptap/extension-highlight";
-import Subscript from "@tiptap/extension-subscript";
-import Superscript from "@tiptap/extension-superscript";
-import { Node, Extension, Mark, getSchema } from "@tiptap/core";
-// Inlined from @tiptap/core's getStyleProperty (added after 3.20.x) so this
-// package can stay on the same @tiptap/core version as the editor and avoid a
-// duplicate-tiptap version split in the monorepo. Reads a single declaration
-// from an element's inline `style` attribute, last-wins, case-insensitive.
-function getStyleProperty(element, propertyName) {
-    const styleAttr = element.getAttribute("style");
-    if (!styleAttr) {
-        return null;
-    }
-    const decls = styleAttr.split(";").map((decl) => decl.trim()).filter(Boolean);
-    const target = propertyName.toLowerCase();
-    for (let i = decls.length - 1; i >= 0; i -= 1) {
-        const decl = decls[i];
-        const colonIndex = decl.indexOf(":");
-        if (colonIndex === -1) {
-            continue;
-        }
-        const prop = decl.slice(0, colonIndex).trim().toLowerCase();
-        if (prop === target) {
-            return decl.slice(colonIndex + 1).trim();
-        }
-    }
-    return null;
-}
-/** Allowed Docmost callout types; anything else falls back to "info". */
-const CALLOUT_TYPES = ["info", "warning", "danger", "success"];
-export const clampCalloutType = (value) => value && CALLOUT_TYPES.includes(value.toLowerCase())
-    ? value.toLowerCase()
-    : "info";
-/**
- * Allowlist guard for CSS color values imported from HTML.
- *
- * Docmost interpolates stored mark colors straight into an inline style
- * attribute (e.g. style="background-color: ${color}" / "color: ${color}").
- * An unsanitized value such as `red; --x: url(...)` or `red"><script>` would
- * let a crafted document break out of the style attribute. We therefore only
- * accept a narrow, well-formed subset of CSS <color> syntax and reject (-> null)
- * anything else.
- *
- * Accepted forms:
- *   - named colors:           letters only, e.g. "red", "rebeccapurple"
- *   - hex:                    #rgb, #rgba, #rrggbb, #rrggbbaa
- *   - functional notation:    rgb()/rgba()/hsl()/hsla() containing only
- *                             digits, %, ., commas, spaces and slashes
- */
-const SAFE_COLOR_RE = /^(?:[a-zA-Z]+|#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgb|rgba|hsl|hsla)\([0-9.,%/\s]+\))$/;
-export const sanitizeCssColor = (value) => {
-    if (typeof value !== "string")
-        return null;
-    const color = value.trim();
-    return color && SAFE_COLOR_RE.test(color) ? color : null;
-};
-/** Docmost callout (info/warning/danger/success banner). */
-const Callout = Node.create({
-    name: "callout",
-    group: "block",
-    content: "block+",
-    defining: true,
-    addAttributes() {
-        return {
-            // Read the type from data-callout-type so generateJSON(html) preserves
-            // it; without an explicit parseHTML every imported callout became "info".
-            type: {
-                default: "info",
-                parseHTML: (el) => clampCalloutType(el.getAttribute("data-callout-type")),
-                renderHTML: (attrs) => ({
-                    "data-callout-type": clampCalloutType(attrs.type),
-                }),
-            },
-            icon: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-icon"),
-                renderHTML: (attrs) => attrs.icon ? { "data-icon": attrs.icon } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="callout"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "callout", ...HTMLAttributes }, 0];
-    },
-});
-/** Minimal table family: enough for schema round-trips and HTML parsing. */
-const Table = Node.create({
-    name: "table",
-    group: "block",
-    content: "tableRow+",
-    isolating: true,
-    parseHTML() {
-        return [{ tag: "table" }];
-    },
-    renderHTML() {
-        return ["table", ["tbody", 0]];
-    },
-});
-const TableRow = Node.create({
-    name: "tableRow",
-    content: "(tableCell | tableHeader)*",
-    parseHTML() {
-        return [{ tag: "tr" }];
-    },
-    renderHTML() {
-        return ["tr", 0];
-    },
-});
-const cellAttributes = () => ({
-    colspan: { default: 1 },
-    rowspan: { default: 1 },
-    colwidth: { default: null },
-    backgroundColor: { default: null },
-    backgroundColorName: { default: null },
-    // Column alignment so GFM aligned tables (|:--|:-:|--:|) round-trip.
-    align: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("align") || el.style.textAlign || null,
-        renderHTML: (attrs) => attrs.align ? { align: attrs.align } : {},
-    },
-});
-const TableCell = Node.create({
-    name: "tableCell",
-    content: "block+",
-    isolating: true,
-    addAttributes: cellAttributes,
-    parseHTML() {
-        return [{ tag: "td" }];
-    },
-    renderHTML() {
-        return ["td", 0];
-    },
-});
-const TableHeader = Node.create({
-    name: "tableHeader",
-    content: "block+",
-    isolating: true,
-    addAttributes: cellAttributes,
-    parseHTML() {
-        return [{ tag: "th" }];
-    },
-    renderHTML() {
-        return ["th", 0];
-    },
-});
-/**
- * Attributes Docmost stores on standard nodes that the stock extensions
- * do not declare. Without these, Node.fromJSON silently drops them —
- * including the block ids that heading anchors rely on.
- */
-const DocmostAttributes = Extension.create({
-    name: "docmostAttributes",
-    addGlobalAttributes() {
-        return [
-            {
-                types: ["heading", "paragraph"],
-                attributes: {
-                    id: { default: null },
-                    indent: { default: null },
-                    textAlign: { default: null },
-                },
-            },
-            {
-                types: ["image"],
-                attributes: {
-                    align: { default: null },
-                    attachmentId: { default: null },
-                    aspectRatio: { default: null },
-                    height: { default: null },
-                    placeholder: { default: null },
-                    size: { default: null },
-                    width: { default: null },
-                },
-            },
-            {
-                types: ["orderedList"],
-                attributes: { type: { default: null } },
-            },
-            {
-                types: ["link"],
-                attributes: { internal: { default: null }, title: { default: null } },
-            },
-        ];
-    },
-});
-/**
- * Docmost inline comment mark. Anchors a comment thread to a text range via
- * `commentId`. Without it, any document containing comment highlights fails to
- * round-trip through the schema ("There is no mark type comment in this schema"),
- * which breaks update_page_json and edit_page_text on every commented page.
- * Mirrors Docmost's @docmost/editor-ext comment mark (commentId / resolved).
- */
-const Comment = Mark.create({
-    name: "comment",
-    exitable: true,
-    inclusive: false,
-    addAttributes() {
-        return {
-            commentId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-comment-id"),
-                renderHTML: (attrs) => attrs.commentId ? { "data-comment-id": attrs.commentId } : {},
-            },
-            resolved: {
-                default: false,
-                parseHTML: (el) => el.getAttribute("data-resolved") === "true",
-                renderHTML: (attrs) => attrs.resolved ? { "data-resolved": "true" } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: "span[data-comment-id]" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["span", { class: "comment-mark", ...HTMLAttributes }, 0];
-    },
-});
-/**
- * Text color mark. The markdown-converter emits colored text as
- * <span style="color: ...">, but with no mark parsing it back the color was
- * silently dropped on import. This mirrors TipTap's @tiptap/extension-text-style
- * `textStyle` mark (the name Docmost expects) and carries a single `color`
- * attribute. The parsed color is passed through the allowlist guard so a crafted
- * style cannot break out of the attribute when Docmost re-renders it.
- */
-const TextStyle = Mark.create({
-    name: "textStyle",
-    addAttributes() {
-        return {
-            color: {
-                default: null,
-                parseHTML: (el) => sanitizeCssColor(el.style.color || el.getAttribute("data-color")),
-                renderHTML: (attrs) => {
-                    const color = sanitizeCssColor(attrs.color);
-                    return color ? { style: `color: ${color}` } : {};
-                },
-            },
-        };
-    },
-    parseHTML() {
-        return [
-            {
-                tag: "span",
-                // Only claim a plain colored span. Do NOT match spans that are already a
-                // comment mark (data-comment-id) or a mention node (data-type=mention),
-                // otherwise importing such HTML would silently drop the comment/mention.
-                getAttrs: (el) => el.style.color &&
-                    !el.getAttribute("data-comment-id") &&
-                    el.getAttribute("data-type") !== "mention"
-                    ? {}
-                    : false,
-            },
-        ];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["span", HTMLAttributes, 0];
-    },
-});
-/**
- * Inline spoiler mark. Mirrors the @docmost/editor-ext `spoiler` mark so a
- * document carrying a spoiler survives the MCP read -> transform -> write path
- * (and markdown export) instead of silently dropping the unrecognized mark.
- * packages/mcp does NOT depend on editor-ext, so the definition is kept local;
- * it parses span[data-spoiler] and renders the same span[data-spoiler][class]
- * the editor-ext mark emits.
- */
-const Spoiler = Mark.create({
-    name: "spoiler",
-    // Don't bleed onto text typed at the boundary (mirrors editor-ext).
-    inclusive: false,
-    parseHTML() {
-        return [{ tag: "span[data-spoiler]" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["span", { "data-spoiler": "true", class: "spoiler", ...HTMLAttributes }, 0];
-    },
-});
-/**
- * Passthrough definitions for the remaining Docmost-specific nodes.
- *
- * TiptapTransformer.toYdoc (the write path every mutation uses) throws
- * "Unknown node type: X" for any node not registered here, so editing ANY
- * page that contains one of these nodes used to fail outright. The read path
- * (fromYdoc) accepts them, which is why they appear in real documents.
- *
- * Each node below mirrors the real @docmost/editor-ext definition's name,
- * group, content, inline/atom flags and attribute keys (with the same data-*
- * HTML mapping) so that a fromYdoc -> transform -> toYdoc round-trip both
- * validates and preserves attributes faithfully. Interactive concerns
- * (node views, commands, keyboard shortcuts, input rules, suggestion plugins)
- * are intentionally omitted: the MCP server never renders these nodes, it only
- * needs the schema to accept and carry them. The Callout node above is the
- * pattern these follow.
- */
-/** Docmost @mention (user/page reference). Inline atom. */
-const Mention = Node.create({
-    name: "mention",
-    group: "inline",
-    inline: true,
-    selectable: true,
-    atom: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            id: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-id"),
-                renderHTML: (attrs) => attrs.id ? { "data-id": attrs.id } : {},
-            },
-            label: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-label"),
-                renderHTML: (attrs) => attrs.label ? { "data-label": attrs.label } : {},
-            },
-            entityType: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-entity-type"),
-                renderHTML: (attrs) => attrs.entityType ? { "data-entity-type": attrs.entityType } : {},
-            },
-            entityId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-entity-id"),
-                renderHTML: (attrs) => attrs.entityId ? { "data-entity-id": attrs.entityId } : {},
-            },
-            slugId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-slug-id"),
-                renderHTML: (attrs) => attrs.slugId ? { "data-slug-id": attrs.slugId } : {},
-            },
-            creatorId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-creator-id"),
-                renderHTML: (attrs) => attrs.creatorId ? { "data-creator-id": attrs.creatorId } : {},
-            },
-            anchorId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-anchor-id"),
-                renderHTML: (attrs) => attrs.anchorId ? { "data-anchor-id": attrs.anchorId } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'span[data-type="mention"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        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",
-    group: "inline",
-    inline: true,
-    atom: true,
-    addAttributes() {
-        return {
-            text: { default: "" },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'span[data-type="mathInline"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return [
-            "span",
-            { "data-type": "mathInline", "data-katex": "true" },
-            `${HTMLAttributes.text ?? ""}`,
-        ];
-    },
-});
-/** Block KaTeX expression. Carries the LaTeX source in `text`. */
-const MathBlock = Node.create({
-    name: "mathBlock",
-    group: "block",
-    atom: true,
-    isolating: true,
-    addAttributes() {
-        return {
-            text: { default: "" },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="mathBlock"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return [
-            "div",
-            { "data-type": "mathBlock", "data-katex": "true" },
-            `${HTMLAttributes.text ?? ""}`,
-        ];
-    },
-});
-/** Collapsible <details> wrapper: summary + content children. */
-const Details = Node.create({
-    name: "details",
-    group: "block",
-    content: "detailsSummary detailsContent",
-    defining: true,
-    isolating: true,
-    addAttributes() {
-        return {
-            open: {
-                default: false,
-                parseHTML: (el) => el.getAttribute("open"),
-                renderHTML: (attrs) => attrs.open ? { open: "" } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: "details" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["details", { ...HTMLAttributes }, 0];
-    },
-});
-/** Clickable summary line of a <details> block. */
-const DetailsSummary = Node.create({
-    name: "detailsSummary",
-    group: "block",
-    content: "inline*",
-    defining: true,
-    isolating: true,
-    selectable: false,
-    parseHTML() {
-        return [{ tag: "summary" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["summary", { "data-type": "detailsSummary", ...HTMLAttributes }, 0];
-    },
-});
-/** Body of a <details> block. Permissive content so fromYdoc output validates. */
-const DetailsContent = Node.create({
-    name: "detailsContent",
-    group: "block",
-    // Docmost declares block* (an empty details body is valid); block+ would
-    // reject a collapsed/empty details on round-trip.
-    content: "block*",
-    defining: true,
-    selectable: false,
-    parseHTML() {
-        return [{ tag: 'div[data-type="detailsContent"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "detailsContent", ...HTMLAttributes }, 0];
-    },
-});
-/** File attachment card (non-image upload). Block atom. */
-const Attachment = Node.create({
-    name: "attachment",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            url: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("data-attachment-url"),
-                renderHTML: (attrs) => ({
-                    "data-attachment-url": attrs.url ?? "",
-                }),
-            },
-            name: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-name"),
-                renderHTML: (attrs) => attrs.name ? { "data-attachment-name": attrs.name } : {},
-            },
-            mime: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-mime"),
-                renderHTML: (attrs) => attrs.mime ? { "data-attachment-mime": attrs.mime } : {},
-            },
-            size: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-size"),
-                renderHTML: (attrs) => attrs.size != null ? { "data-attachment-size": attrs.size } : {},
-            },
-            attachmentId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-id"),
-                renderHTML: (attrs) => attrs.attachmentId
-                    ? { "data-attachment-id": attrs.attachmentId }
-                    : {},
-            },
-            // Docmost declares `placeholder` (a transient upload key, not rendered
-            // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-            placeholder: { default: null },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="attachment"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "attachment", ...HTMLAttributes }, 0];
-    },
-});
-/** Uploaded <video> player. Block atom. */
-const Video = Node.create({
-    name: "video",
-    group: "block",
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            src: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("src"),
-                renderHTML: (attrs) => ({ src: attrs.src ?? "" }),
-            },
-            alt: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("aria-label"),
-                renderHTML: (attrs) => attrs.alt ? { "aria-label": attrs.alt } : {},
-            },
-            attachmentId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-id"),
-                renderHTML: (attrs) => attrs.attachmentId
-                    ? { "data-attachment-id": attrs.attachmentId }
-                    : {},
-            },
-            width: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("width"),
-                renderHTML: (attrs) => attrs.width != null ? { width: attrs.width } : {},
-            },
-            height: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("height"),
-                renderHTML: (attrs) => attrs.height != null ? { height: attrs.height } : {},
-            },
-            size: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-size"),
-                renderHTML: (attrs) => attrs.size != null ? { "data-size": attrs.size } : {},
-            },
-            align: {
-                default: "center",
-                parseHTML: (el) => el.getAttribute("data-align"),
-                renderHTML: (attrs) => attrs.align ? { "data-align": attrs.align } : {},
-            },
-            aspectRatio: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-aspect-ratio"),
-                renderHTML: (attrs) => attrs.aspectRatio != null
-                    ? { "data-aspect-ratio": attrs.aspectRatio }
-                    : {},
-            },
-            // Docmost declares `placeholder` (a transient upload key, not rendered
-            // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-            placeholder: { default: null },
-        };
-    },
-    parseHTML() {
-        return [{ tag: "video" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["video", { controls: "true", ...HTMLAttributes }];
-    },
-});
-/**
- * Defensive passthrough for a `youtube` node. Docmost itself has no dedicated
- * youtube node (YouTube is handled via `embed`), but the converter read path
- * references this type, so accept it as a generic block atom that preserves
- * its src so legacy/external documents survive a round-trip.
- */
-const Youtube = Node.create({
-    name: "youtube",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            src: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("data-src"),
-                renderHTML: (attrs) => ({
-                    "data-src": attrs.src ?? "",
-                }),
-            },
-            width: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-width"),
-                renderHTML: (attrs) => attrs.width != null ? { "data-width": attrs.width } : {},
-            },
-            height: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-height"),
-                renderHTML: (attrs) => attrs.height != null ? { "data-height": attrs.height } : {},
-            },
-            align: {
-                default: "center",
-                parseHTML: (el) => el.getAttribute("data-align"),
-                renderHTML: (attrs) => attrs.align ? { "data-align": attrs.align } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="youtube"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "youtube", ...HTMLAttributes }, 0];
-    },
-});
-/** Generic embed (provider iframe). Block atom. */
-const Embed = Node.create({
-    name: "embed",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            src: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("data-src"),
-                renderHTML: (attrs) => ({
-                    "data-src": attrs.src ?? "",
-                }),
-            },
-            provider: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("data-provider"),
-                renderHTML: (attrs) => ({
-                    "data-provider": attrs.provider ?? "",
-                }),
-            },
-            align: {
-                default: "center",
-                parseHTML: (el) => el.getAttribute("data-align"),
-                renderHTML: (attrs) => ({
-                    "data-align": attrs.align ?? "center",
-                }),
-            },
-            width: {
-                default: 800,
-                parseHTML: (el) => el.getAttribute("data-width"),
-                renderHTML: (attrs) => ({
-                    "data-width": attrs.width,
-                }),
-            },
-            height: {
-                default: 600,
-                parseHTML: (el) => el.getAttribute("data-height"),
-                renderHTML: (attrs) => ({
-                    "data-height": attrs.height,
-                }),
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="embed"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "embed", ...HTMLAttributes }, 0];
-    },
-});
-/**
- * Docmost raw HTML embed. Block atom; the client renders `source` inside a
- * sandboxed iframe. The MCP server never renders it — it only needs the
- * schema to accept and carry the node so a fromYdoc -> transform -> toYdoc
- * round-trip does not throw "Unknown node type: htmlEmbed". Mirrors the
- * @docmost/editor-ext node name, attribute keys and flags; keep in sync when
- * the editor-ext htmlEmbed schema changes.
- *
- * NOTE: unlike the canonical editor-ext node, `data-source` here is mapped as
- * plain text rather than base64-encoded. That is intentional: the MCP write
- * path carries the node through Yjs (fromYdoc -> toYdoc) on its JSON `source`
- * attribute and never invokes parseHTML/renderHTML, and htmlEmbed is not
- * produced from the markdown/HTML (generateJSON) path. If a future HTML path
- * for htmlEmbed is added here, this mapping must adopt editor-ext's base64
- * encode/decode to avoid double-encoding `source`.
- */
-const HtmlEmbed = Node.create({
-    name: "htmlEmbed",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            source: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("data-source") ?? "",
-                renderHTML: (attrs) => ({
-                    "data-source": attrs.source ?? "",
-                }),
-            },
-            height: {
-                default: null,
-                parseHTML: (el) => {
-                    const v = el.getAttribute("data-height");
-                    if (!v)
-                        return null;
-                    const n = parseInt(v, 10);
-                    return Number.isFinite(n) ? n : null;
-                },
-                renderHTML: (attrs) => attrs.height != null ? { "data-height": String(attrs.height) } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="htmlEmbed"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "htmlEmbed", ...HTMLAttributes }, 0];
-    },
-});
-/** Shared attribute set for drawio/excalidraw diagram nodes. */
-const diagramAttributes = () => ({
-    src: {
-        default: "",
-        parseHTML: (el) => el.getAttribute("data-src"),
-        renderHTML: (attrs) => ({
-            "data-src": attrs.src ?? "",
-        }),
-    },
-    title: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-title"),
-        renderHTML: (attrs) => attrs.title ? { "data-title": attrs.title } : {},
-    },
-    alt: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-alt"),
-        renderHTML: (attrs) => attrs.alt ? { "data-alt": attrs.alt } : {},
-    },
-    width: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-width"),
-        renderHTML: (attrs) => attrs.width != null ? { "data-width": attrs.width } : {},
-    },
-    height: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-height"),
-        renderHTML: (attrs) => attrs.height != null ? { "data-height": attrs.height } : {},
-    },
-    size: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-size"),
-        renderHTML: (attrs) => attrs.size != null ? { "data-size": attrs.size } : {},
-    },
-    aspectRatio: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-aspect-ratio"),
-        renderHTML: (attrs) => attrs.aspectRatio != null
-            ? { "data-aspect-ratio": attrs.aspectRatio }
-            : {},
-    },
-    align: {
-        default: "center",
-        parseHTML: (el) => el.getAttribute("data-align"),
-        renderHTML: (attrs) => attrs.align ? { "data-align": attrs.align } : {},
-    },
-    attachmentId: {
-        default: null,
-        parseHTML: (el) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs) => attrs.attachmentId ? { "data-attachment-id": attrs.attachmentId } : {},
-    },
-});
-/** draw.io diagram. Block atom (image-backed). */
-const Drawio = Node.create({
-    name: "drawio",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes: diagramAttributes,
-    parseHTML() {
-        return [{ tag: 'div[data-type="drawio"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "drawio", ...HTMLAttributes }, 0];
-    },
-});
-/** Excalidraw diagram. Block atom (image-backed). */
-const Excalidraw = Node.create({
-    name: "excalidraw",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes: diagramAttributes,
-    parseHTML() {
-        return [{ tag: 'div[data-type="excalidraw"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "excalidraw", ...HTMLAttributes }, 0];
-    },
-});
-/** Multi-column layout container holding one or more `column` children. */
-const Columns = Node.create({
-    name: "columns",
-    group: "block",
-    content: "column+",
-    defining: true,
-    isolating: true,
-    addAttributes() {
-        return {
-            layout: {
-                default: "two_equal",
-                parseHTML: (el) => el.getAttribute("data-layout"),
-                renderHTML: (attrs) => attrs.layout ? { "data-layout": attrs.layout } : {},
-            },
-            widthMode: {
-                default: "normal",
-                parseHTML: (el) => el.getAttribute("data-width-mode") || "normal",
-                renderHTML: (attrs) => attrs.widthMode && attrs.widthMode !== "normal"
-                    ? { "data-width-mode": attrs.widthMode }
-                    : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="columns"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "columns", ...HTMLAttributes }, 0];
-    },
-});
-/** Single column within a `columns` layout. */
-const Column = Node.create({
-    name: "column",
-    group: "block",
-    content: "block+",
-    defining: true,
-    isolating: true,
-    selectable: false,
-    addAttributes() {
-        return {
-            width: {
-                default: null,
-                parseHTML: (el) => {
-                    const value = el.getAttribute("data-width");
-                    return value ? parseFloat(value) : null;
-                },
-                renderHTML: (attrs) => attrs.width ? { "data-width": attrs.width } : {},
-            },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="column"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "column", ...HTMLAttributes }, 0];
-    },
-});
-/**
- * Subpages listing block (auto-generated index of child pages). Docmost
- * declares no attributes; the markdown-converter has a `case "subpages"`, so
- * the read path can emit it and toYdoc must accept it. Block atom.
- */
-const Subpages = Node.create({
-    name: "subpages",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    parseHTML() {
-        return [{ tag: 'div[data-type="subpages"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "subpages", ...HTMLAttributes }, 0];
-    },
-});
-/** Uploaded <audio> player. Block atom. Mirrors Docmost audio attrs. */
-const Audio = Node.create({
-    name: "audio",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            src: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("src"),
-                renderHTML: (attrs) => ({ src: attrs.src ?? "" }),
-            },
-            attachmentId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-id"),
-                renderHTML: (attrs) => attrs.attachmentId
-                    ? { "data-attachment-id": attrs.attachmentId }
-                    : {},
-            },
-            size: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-size"),
-                renderHTML: (attrs) => attrs.size != null ? { "data-size": attrs.size } : {},
-            },
-            // Transient upload key Docmost declares with rendered:false; carried so
-            // a round-trip never hits "Unsupported attribute".
-            placeholder: { default: null },
-        };
-    },
-    parseHTML() {
-        return [{ tag: "audio" }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["audio", { controls: "true", ...HTMLAttributes }];
-    },
-});
-/** Embedded PDF viewer. Block atom. Mirrors Docmost pdf attrs. */
-const Pdf = Node.create({
-    name: "pdf",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    addAttributes() {
-        return {
-            src: {
-                default: "",
-                parseHTML: (el) => el.getAttribute("src"),
-                renderHTML: (attrs) => ({ src: attrs.src ?? "" }),
-            },
-            name: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-name"),
-                renderHTML: (attrs) => attrs.name ? { "data-name": attrs.name } : {},
-            },
-            attachmentId: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-attachment-id"),
-                renderHTML: (attrs) => attrs.attachmentId
-                    ? { "data-attachment-id": attrs.attachmentId }
-                    : {},
-            },
-            size: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("data-size"),
-                renderHTML: (attrs) => attrs.size != null ? { "data-size": attrs.size } : {},
-            },
-            width: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("width"),
-                renderHTML: (attrs) => attrs.width != null ? { width: attrs.width } : {},
-            },
-            height: {
-                default: null,
-                parseHTML: (el) => el.getAttribute("height"),
-                renderHTML: (attrs) => attrs.height != null ? { height: attrs.height } : {},
-            },
-            // Transient upload key Docmost declares with rendered:false; carried so
-            // a round-trip never hits "Unsupported attribute".
-            placeholder: { default: null },
-        };
-    },
-    parseHTML() {
-        return [{ tag: 'div[data-type="pdf"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "pdf", ...HTMLAttributes }, 0];
-    },
-});
-/** Page break (print/export divider). Block atom; Docmost declares no attrs. */
-const PageBreak = Node.create({
-    name: "pageBreak",
-    group: "block",
-    inline: false,
-    isolating: true,
-    atom: true,
-    defining: true,
-    draggable: true,
-    parseHTML() {
-        return [{ tag: 'div[data-type="pageBreak"]' }];
-    },
-    renderHTML({ HTMLAttributes }) {
-        return ["div", { "data-type": "pageBreak", ...HTMLAttributes }];
-    },
-});
-/**
- * Full extension list. Image is block-level (matches Docmost); the
- * ProseMirror DOM parser hoists <img> found inside <p> automatically.
- * StarterKit v3 already bundles the link extension, configured here.
- */
-export const docmostExtensions = [
-    StarterKit.configure({
-        codeBlock: {},
-        heading: {},
-        link: { openOnClick: false },
-    }),
-    // Stock @tiptap/extension-image has no caption attribute, so a round-trip
-    // through this schema would drop the data-caption the client TiptapImage
-    // emits. Mirror editor-ext image.ts: add a caption attribute that parses
-    // data-caption and re-renders it only when set (caption-less images stay
-    // clean), keeping the MCP markdown round-trip lossless.
-    Image.extend({
-        addAttributes() {
-            const parent = this.parent?.() ?? {};
-            return {
-                ...parent,
-                caption: {
-                    default: undefined,
-                    parseHTML: (el) => el.getAttribute("data-caption") || undefined,
-                    renderHTML: (attrs) => attrs.caption ? { "data-caption": attrs.caption } : {},
-                },
-            };
-        },
-    }).configure({ inline: false }),
-    TaskList,
-    TaskItem.configure({ nested: true }),
-    // Highlight stores its color unescaped and Docmost interpolates it into
-    // style="background-color: ${color}". Wrap the color attribute's parseHTML
-    // with the same allowlist guard used by textStyle so a crafted import color
-    // cannot break out of the style attribute. Multicolor behavior is preserved.
-    Highlight.extend({
-        addAttributes() {
-            const parent = this.parent?.() ?? {};
-            return {
-                ...parent,
-                color: {
-                    ...parent.color,
-                    parseHTML: (el) => sanitizeCssColor(el.getAttribute("data-color") ||
-                        getStyleProperty(el, "background-color") ||
-                        el.style.backgroundColor),
-                },
-            };
-        },
-    }).configure({ multicolor: true }),
-    Subscript,
-    Superscript,
-    // StarterKit does not provide a textStyle mark, so register ours; without it
-    // generateJSON drops <span style="color: ...">, defeating the color import.
-    TextStyle,
-    Comment,
-    Spoiler,
-    Callout,
-    Table,
-    TableRow,
-    TableCell,
-    TableHeader,
-    Mention,
-    FootnoteReference,
-    FootnotesList,
-    FootnoteDefinition,
-    MathInline,
-    MathBlock,
-    Details,
-    DetailsSummary,
-    DetailsContent,
-    Attachment,
-    Video,
-    Youtube,
-    Embed,
-    HtmlEmbed,
-    Drawio,
-    Excalidraw,
-    Columns,
-    Column,
-    Subpages,
-    Audio,
-    Pdf,
-    PageBreak,
-    DocmostAttributes,
-];
-/**
- * The ProseMirror schema for the docmost editor, built ONCE from
- * `docmostExtensions`. Pure and reused by every consumer (diff, collaboration
- * write-back) so the schema can never drift between call sites — it lives next
- * to the extension list it is derived from.
- */
-export const docmostSchema = getSchema(docmostExtensions);
diff --git a/packages/mcp/build/lib/filters.js b/packages/mcp/build/lib/filters.js
deleted file mode 100644
index eb056968..00000000
--- a/packages/mcp/build/lib/filters.js
+++ /dev/null
@@ -1,92 +0,0 @@
-/**
- * Filter functions to extract only relevant information from API responses
- * for better agent consumption
- */
-export function filterWorkspace(data) {
-    return {
-        id: data.id,
-        name: data.name,
-        description: data.description,
-        defaultSpaceId: data.defaultSpaceId,
-        createdAt: data.createdAt,
-        updatedAt: data.updatedAt,
-        deletedAt: data.deletedAt,
-    };
-}
-export function filterSpace(space) {
-    return {
-        id: space.id,
-        name: space.name,
-        description: space.description,
-        slug: space.slug,
-        visibility: space.visibility,
-        createdAt: space.createdAt,
-        updatedAt: space.updatedAt,
-        deletedAt: space.deletedAt,
-    };
-}
-export function filterGroup(group) {
-    return {
-        id: group.id,
-        name: group.name,
-        description: group.description,
-        workspaceId: group.workspaceId,
-        createdAt: group.createdAt,
-        updatedAt: group.updatedAt,
-        deletedAt: group.deletedAt,
-    };
-}
-export function filterPage(page, content, subpages) {
-    return {
-        id: page.id,
-        slugId: page.slugId,
-        title: page.title,
-        parentPageId: page.parentPageId,
-        spaceId: page.spaceId,
-        isLocked: page.isLocked,
-        createdAt: page.createdAt,
-        updatedAt: page.updatedAt,
-        deletedAt: page.deletedAt,
-        // Include converted markdown content if valid string (even empty)
-        ...(typeof content === "string" && { content }),
-        // Include subpages if provided
-        ...(subpages &&
-            subpages.length > 0 && {
-            subpages: subpages.map((p) => ({ id: p.id, title: p.title })),
-        }),
-    };
-}
-export function filterComment(comment, markdownContent) {
-    return {
-        id: comment.id,
-        pageId: comment.pageId,
-        content: markdownContent ?? comment.content,
-        selection: comment.selection || null,
-        type: comment.type || "page",
-        parentCommentId: comment.parentCommentId || null,
-        creatorId: comment.creatorId,
-        creatorName: comment.creator?.name || null,
-        createdAt: comment.createdAt,
-        editedAt: comment.editedAt || null,
-        resolvedAt: comment.resolvedAt || null,
-        resolvedById: comment.resolvedById || null,
-        // Suggestion state: the proposed replacement text (if any) and, once a human
-        // applies it via the UI, when and by whom.
-        suggestedText: comment.suggestedText || null,
-        suggestionAppliedAt: comment.suggestionAppliedAt || null,
-        suggestionAppliedById: comment.suggestionAppliedById || null,
-    };
-}
-export function filterSearchResult(result) {
-    return {
-        id: result.id,
-        title: result.title,
-        parentPageId: result.parentPageId,
-        createdAt: result.createdAt,
-        updatedAt: result.updatedAt,
-        rank: result.rank,
-        highlight: result.highlight,
-        spaceId: result.space?.id,
-        spaceName: result.space?.name,
-    };
-}
diff --git a/packages/mcp/build/lib/footnote-analyze.js b/packages/mcp/build/lib/footnote-analyze.js
deleted file mode 100644
index 0bae93c7..00000000
--- a/packages/mcp/build/lib/footnote-analyze.js
+++ /dev/null
@@ -1,101 +0,0 @@
-/**
- * Footnote diagnostics for imported Markdown (issue #166).
- *
- * A PURE, fence-aware text scan (independent of the Markdown->ProseMirror
- * conversion path, so it reports the same problems for `create_page`,
- * `update_page` and `import_page_markdown`). It never changes the document — the
- * importer still creates the page; this only surfaces footnote problems to the
- * caller so an agent can fix its own markup instead of shipping broken footnotes.
- *
- * Detected problems:
- *  - danglingReferences: a `[^id]` reference with no `[^id]:` definition.
- *  - emptyDefinitions:   a `[^id]:` whose (kept) text is empty/whitespace.
- *  - duplicateDefinitions: an id defined by two or more `[^id]:` lines (only the
- *    first is kept on import — first-wins; see extractFootnotes).
- *  - referencesInTables: a `[^id]` marker found in a GFM table row (heuristic:
- *    the line, trimmed, starts with `|`) — footnotes in table cells often do not
- *    render as expected.
- */
-import { lexFootnoteLines, forEachFootnoteReference, } from "./footnote-lex.js";
-/**
- * Analyze the footnotes in a Markdown string. Pure; safe to call on any body.
- */
-export function analyzeFootnotes(markdown) {
-    // Distinct reference ids in first-appearance order, plus the set of ids seen
-    // inside a table row.
-    const refIds = [];
-    const refIdSet = new Set();
-    const referencesInTables = new Set();
-    const addRef = (id, inTable) => {
-        if (!refIdSet.has(id)) {
-            refIdSet.add(id);
-            refIds.push(id);
-        }
-        if (inTable)
-            referencesInTables.add(id);
-    };
-    // Definition texts per id, in first-appearance order of the id.
-    const defTextsById = new Map();
-    // Same lexer the importer uses, so the analysis matches exactly what import
-    // keeps/strips (#166): fenced lines are inert, definition lines are pulled.
-    for (const tok of lexFootnoteLines(markdown)) {
-        if (tok.inFence)
-            continue;
-        if (tok.definition) {
-            const { id, text } = tok.definition;
-            const arr = defTextsById.get(id);
-            if (arr)
-                arr.push(text);
-            else
-                defTextsById.set(id, [text]);
-            // A definition's TEXT can itself reference another footnote (`[^a]: see
-            // [^b]`); count those so such a `[^b]` is not falsely reported dangling.
-            forEachFootnoteReference(text, (rid) => addRef(rid, false));
-            continue;
-        }
-        const inTable = tok.line.trimStart().startsWith("|");
-        forEachFootnoteReference(tok.line, (id) => addRef(id, inTable));
-    }
-    const danglingReferences = refIds.filter((id) => !defTextsById.has(id));
-    const duplicateDefinitions = [];
-    const emptyDefinitions = [];
-    for (const [id, texts] of defTextsById) {
-        if (texts.length >= 2)
-            duplicateDefinitions.push(id);
-        // First-wins: the kept definition is the first one; flag it if it is blank.
-        if ((texts[0] ?? "").trim().length === 0)
-            emptyDefinitions.push(id);
-    }
-    const tableRefs = [...referencesInTables];
-    const warnings = [];
-    const list = (ids) => ids.map((id) => `[^${id}]`).join(", ");
-    if (danglingReferences.length > 0) {
-        warnings.push(`Footnote reference(s) with no matching definition: ${list(danglingReferences)} (each will render as an empty footnote in the editor).`);
-    }
-    if (emptyDefinitions.length > 0) {
-        warnings.push(`Footnote definition(s) with empty text: ${list(emptyDefinitions)}.`);
-    }
-    if (duplicateDefinitions.length > 0) {
-        warnings.push(`Footnote id(s) defined more than once (only the first definition was kept): ${list(duplicateDefinitions)}.`);
-    }
-    if (tableRefs.length > 0) {
-        warnings.push(`Footnote marker(s) inside a table row (footnotes in table cells may not render as expected): ${list(tableRefs)}.`);
-    }
-    return {
-        danglingReferences,
-        emptyDefinitions,
-        duplicateDefinitions,
-        referencesInTables: tableRefs,
-        warnings,
-    };
-}
-/**
- * The optional `footnoteWarnings` field for a page-write tool result: present
- * (with the warning lines) only when `markdown` has footnote problems, omitted
- * otherwise. One helper so all three call sites (create/update/import) attach the
- * field identically. Spread into the result: `{ ...result, ...footnoteWarningsField(text) }`.
- */
-export function footnoteWarningsField(markdown) {
-    const { warnings } = analyzeFootnotes(markdown);
-    return warnings.length > 0 ? { footnoteWarnings: warnings } : {};
-}
diff --git a/packages/mcp/build/lib/footnote-authoring.js b/packages/mcp/build/lib/footnote-authoring.js
deleted file mode 100644
index ab8d7eb2..00000000
--- a/packages/mcp/build/lib/footnote-authoring.js
+++ /dev/null
@@ -1,88 +0,0 @@
-/**
- * Inline-authoring helpers for footnotes (MCP).
- *
- * These build/identify footnote DEFINITION nodes for the author-inline tool
- * (`insertInlineFootnote` in transforms.ts): a content key to de-duplicate notes
- * by text, a definition-node factory, and a fresh uuidv7-style id generator.
- *
- * Split out of `footnote-canonicalize.ts` so that module stays a pure MIRROR of
- * the editor-ext canonicalizer (compositionally symmetric to the editor-ext
- * copy, which keeps its authoring helpers in `footnote-util.ts`). The pure
- * canonicalizer has no dependency on these.
- */
-const FOOTNOTE_DEFINITION_NAME = "footnoteDefinition";
-function cloneJson(v) {
-    if (typeof structuredClone === "function")
-        return structuredClone(v);
-    return JSON.parse(JSON.stringify(v));
-}
-/**
- * Normalized content key for de-duplicating footnote DEFINITIONS by their text.
- *
- * Two definitions with the same key are the SAME footnote — so the inline
- * authoring tool reuses one id (one number, one definition, several references)
- * instead of minting a second definition. Key = plaintext (whitespace-collapsed,
- * trimmed) PLUS a signature of the inline mark types in order, so two notes that
- * read the same but differ in formatting (one bold, one plain) are NOT merged.
- * Conservative: only an exact match merges.
- */
-export function footnoteContentKey(defNode) {
-    const parts = [];
-    const visit = (n) => {
-        if (!n || typeof n !== "object")
-            return;
-        if (n.type === "text" && typeof n.text === "string") {
-            const marks = Array.isArray(n.marks)
-                ? n.marks.map((m) => m?.type).filter(Boolean).sort().join(",")
-                : "";
-            parts.push(`${n.text}${marks}`);
-        }
-        if (Array.isArray(n.content))
-            for (const c of n.content)
-                visit(c);
-    };
-    visit(defNode);
-    // Collapse the assembled text's whitespace and trim, keeping the mark
-    // signature attached so formatting differences still distinguish notes.
-    return parts
-        .join("")
-        .replace(/[ \t\r\n]+/g, " ")
-        .trim();
-}
-/**
- * Build a footnoteDefinition node from inline ProseMirror nodes, keyed by id.
- */
-export function makeFootnoteDefinition(id, inlineNodes) {
-    const content = Array.isArray(inlineNodes) ? cloneJson(inlineNodes) : [];
-    return {
-        type: FOOTNOTE_DEFINITION_NAME,
-        attrs: { id },
-        content: [{ type: "paragraph", content }],
-    };
-}
-/**
- * Generate a uuidv7-style id (time-ordered), matching editor-ext's
- * `generateFootnoteId`. Used for a genuinely-new inline footnote id.
- */
-export function generateFootnoteId() {
-    const now = Date.now();
-    const timeHex = now.toString(16).padStart(12, "0");
-    const rand = (length) => {
-        let s = "";
-        for (let i = 0; i < length; i++)
-            s += Math.floor(Math.random() * 16).toString(16);
-        return s;
-    };
-    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));
-}
diff --git a/packages/mcp/build/lib/footnote-canonicalize.js b/packages/mcp/build/lib/footnote-canonicalize.js
deleted file mode 100644
index d2d91400..00000000
--- a/packages/mcp/build/lib/footnote-canonicalize.js
+++ /dev/null
@@ -1,215 +0,0 @@
-/**
- * Server-side footnote canonicalizer (MCP mirror — PURE).
- *
- * `canonicalizeFootnotes(doc)` is a pure ProseMirror-JSON port of the editor's
- * `footnoteSyncPlugin` end-state, identical in behaviour to
- * `@docmost/editor-ext`'s `canonicalizeFootnotes`. It is mirrored here — rather
- * than imported from editor-ext — for the SAME reason `footnote-lex.ts` and the
- * `docmost-schema.ts` nodes are mirrored: the MCP package is deliberately
- * decoupled from the browser/React-heavy editor barrel and operates on plain
- * JSON. The editor-ext copy owns the golden test against the live plugin; this
- * copy must stay behaviourally identical (a SHARED golden corpus, exercised by
- * both test suites, pins that — see `test/unit/footnote-corpus.mjs`).
- *
- * This module is the pure MIRROR only. The inline-authoring helpers
- * (`footnoteContentKey`, `makeFootnoteDefinition`, `generateFootnoteId`) used by
- * `insertInlineFootnote` live in the sibling `footnote-authoring.ts`, so this
- * file is compositionally symmetric to the editor-ext copy.
- *
- * Why it exists: every NON-editor write path (markdown import, update_page_json,
- * docmost_transform, insert_footnote) builds ProseMirror JSON directly, so the
- * editor's footnote plugins never run and the canonical topology (sequential
- * numbering by first reference, one trailing list, no orphans, no raw `[^id]`)
- * was never enforced. Running this at the end of every write path closes that
- * gap; because it is idempotent, it is a no-op when the footnotes are already
- * canonical (no spurious mutations / git-sync churn).
- *
- * ENFORCEMENT RULE (#228): any NEW FULL-document persist path MUST call
- * `canonicalizeFootnotes(doc)` before writing — the current callers are
- * `markdownToProseMirrorCanonical` (page markdown import/update; the plain
- * `markdownToProseMirror` used for COMMENT bodies must NOT, or it would drop a
- * reference-less definition), `update_page_json`, `docmost_transform`,
- * `insert_footnote`, and `copy_page_content`. Append/prepend FRAGMENT writes MUST
- * NOT canonicalize. This is deliberately per-call-site (the replace-vs-fragment
- * and comment-vs-page nuances make a single naive wrapper unsafe).
- */
-const FOOTNOTE_REFERENCE_NAME = "footnoteReference";
-const FOOTNOTES_LIST_NAME = "footnotesList";
-const FOOTNOTE_DEFINITION_NAME = "footnoteDefinition";
-function cloneJson(v) {
-    if (typeof structuredClone === "function")
-        return structuredClone(v);
-    return JSON.parse(JSON.stringify(v));
-}
-function isEmptyParagraph(node) {
-    return (!!node &&
-        node.type === "paragraph" &&
-        (!Array.isArray(node.content) || node.content.length === 0));
-}
-function collectReferenceIds(node, out, seen) {
-    if (!node || typeof node !== "object")
-        return;
-    if (node.type === FOOTNOTE_REFERENCE_NAME) {
-        const id = node?.attrs?.id;
-        if (id && !seen.has(id)) {
-            seen.add(id);
-            out.push(id);
-        }
-    }
-    if (Array.isArray(node.content)) {
-        for (const child of node.content)
-            collectReferenceIds(child, out, seen);
-    }
-}
-function collectDefinitions(node, out) {
-    if (!node || typeof node !== "object")
-        return;
-    if (node.type === FOOTNOTE_DEFINITION_NAME)
-        out.push(node);
-    if (Array.isArray(node.content)) {
-        for (const child of node.content)
-            collectDefinitions(child, out);
-    }
-}
-function emptyDefinition(id) {
-    return {
-        type: FOOTNOTE_DEFINITION_NAME,
-        attrs: { id },
-        content: [{ type: "paragraph" }],
-    };
-}
-/**
- * Deep equality over plain JSON: arrays are compared POSITIONALLY
- * (order-SENSITIVE), object keys order-insensitively. The array order-sensitivity
- * is required for correctness here — a reordered `footnotesList.content` must
- * compare UNEQUAL so the canonical rebuild fires instead of leaving it in place.
- */
-function deepEqualJson(a, b) {
-    if (a === b)
-        return true;
-    if (a == null || b == null || typeof a !== typeof b)
-        return false;
-    if (Array.isArray(a) || Array.isArray(b)) {
-        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
-            return false;
-        }
-        for (let i = 0; i < a.length; i++) {
-            if (!deepEqualJson(a[i], b[i]))
-                return false;
-        }
-        return true;
-    }
-    if (typeof a === "object") {
-        const ka = Object.keys(a);
-        const kb = Object.keys(b);
-        if (ka.length !== kb.length)
-            return false;
-        for (const k of ka) {
-            if (!Object.prototype.hasOwnProperty.call(b, k))
-                return false;
-            if (!deepEqualJson(a[k], b[k]))
-                return false;
-        }
-        return true;
-    }
-    return false;
-}
-/**
- * Canonicalize footnotes in a ProseMirror-JSON document. See the file header and
- * the editor-ext twin for the full contract. Pure (deep-clones input,
- * deterministic, idempotent).
- */
-export function canonicalizeFootnotes(doc) {
-    if (doc == null ||
-        typeof doc !== "object" ||
-        !Array.isArray(doc.content)) {
-        return doc;
-    }
-    const out = cloneJson(doc);
-    // 1) Distinct reference ids in document order (deep — refs can live in
-    //    callouts, tables, list items, ...). The ordering/numbering truth.
-    const referenceIds = [];
-    collectReferenceIds(out, referenceIds, new Set());
-    // 2) Every definition node in document order (deep).
-    const defNodes = [];
-    collectDefinitions(out, defNodes);
-    // 3) First definition per id wins; later duplicates carry the SAME id, so they
-    //    cannot be referenced separately and would be orphans — they are dropped.
-    const defById = new Map();
-    for (const d of defNodes) {
-        const id = d?.attrs?.id;
-        if (id && !defById.has(id))
-            defById.set(id, d);
-    }
-    // 4) Build the ordered definition list: one per referenced id, in REFERENCE
-    //    order, reusing the existing node (shallow-copied, id normalized — `out` is
-    //    already deep-cloned and the old lists are cut) or synthesizing an empty
-    //    one. Definitions whose id is not referenced are orphans and never added.
-    const orderedDefs = [];
-    for (const id of referenceIds) {
-        const existing = defById.get(id);
-        if (existing) {
-            orderedDefs.push({
-                ...existing,
-                attrs: { ...(existing.attrs ?? {}), id },
-            });
-        }
-        else {
-            orderedDefs.push(emptyDefinition(id));
-        }
-    }
-    // 5) No references -> there must be NO list at all (at any depth).
-    if (referenceIds.length === 0) {
-        stripFootnotesListsDeep(out);
-        return out;
-    }
-    // 6) Placement parity with the live plugin: when the document is ALREADY in the
-    //    canonical single-list state, leave that list exactly where it sits rather
-    //    than cutting and re-inserting it at the end (the plugin never repositions a
-    //    sole correct list, so moving it would silently reorder any content that
-    //    follows the list on the first write).
-    const topLevelLists = out.content.filter((n) => n && n.type === FOOTNOTES_LIST_NAME);
-    if (topLevelLists.length === 1 &&
-        defNodes.length === orderedDefs.length &&
-        deepEqualJson(topLevelLists[0].content, orderedDefs)) {
-        return out;
-    }
-    // 7) Otherwise rebuild: strip every footnotesList AND every bare
-    //    footnoteDefinition at ANY depth (collectDefinitions gathers defs
-    //    recursively, so a list nested in a callout/blockquote — or a bare
-    //    definition outside any list — would otherwise have its defs copied into the
-    //    rebuilt list while the original survives in place → duplicates) and
-    //    re-insert exactly one list after the last meaningful (non-empty paragraph)
-    //    top-level block.
-    stripFootnotesListsDeep(out);
-    stripFootnoteDefinitionsDeep(out);
-    const top = out.content;
-    let insertAt = top.length;
-    while (insertAt > 0 && isEmptyParagraph(top[insertAt - 1]))
-        insertAt--;
-    top.splice(insertAt, 0, { type: FOOTNOTES_LIST_NAME, content: orderedDefs });
-    out.content = top;
-    return out;
-}
-/** Remove every `footnotesList` node at ANY depth (mutates the given clone). */
-function stripFootnotesListsDeep(node) {
-    if (!node || typeof node !== "object" || !Array.isArray(node.content))
-        return;
-    node.content = node.content.filter((c) => !(c && c.type === FOOTNOTES_LIST_NAME));
-    for (const child of node.content)
-        stripFootnotesListsDeep(child);
-}
-/**
- * Remove every BARE `footnoteDefinition` node at ANY depth (mutates the given
- * clone). Runs only in the rebuild path AFTER the lists are stripped, so it
- * targets definitions that were sitting outside a list (e.g. hand-authored via a
- * raw-JSON write path and nested in a callout); their content was already copied
- * into the rebuilt list, so leaving the originals would duplicate them.
- */
-function stripFootnoteDefinitionsDeep(node) {
-    if (!node || typeof node !== "object" || !Array.isArray(node.content))
-        return;
-    node.content = node.content.filter((c) => !(c && c.type === FOOTNOTE_DEFINITION_NAME));
-    for (const child of node.content)
-        stripFootnoteDefinitionsDeep(child);
-}
diff --git a/packages/mcp/build/lib/footnote-lex.js b/packages/mcp/build/lib/footnote-lex.js
deleted file mode 100644
index 3c22d149..00000000
--- a/packages/mcp/build/lib/footnote-lex.js
+++ /dev/null
@@ -1,55 +0,0 @@
-/**
- * Shared, fence-aware line lexer for footnote markdown (MCP-internal).
- *
- * Both the importer (`extractFootnotes` in collaboration.ts, which strips
- * definition lines and rebuilds a footnotes section) and the diagnostics
- * (`analyzeFootnotes` in footnote-analyze.ts) must agree EXACTLY on which lines
- * are definitions and which lines are inert (inside a code fence). Sharing one
- * lexer makes "the analyzer sees what the importer leaves" a structural property
- * instead of two hand-kept copies that can drift (#166 review).
- *
- * NOTE: this is deliberately NOT shared with editor-ext's
- * `extractFootnoteDefinitions` — that lives in a different package and the
- * decoupling between the editor and the MCP mirror is intentional.
- */
-/** A footnote DEFINITION line: `[^id]: text` (id + text captured). */
-export const FOOTNOTE_DEF_RE = /^\[\^([^\]\s]+)\]:[ \t]*(.*)$/;
-/** Every footnote REFERENCE `[^id]` in a line (global; id captured). */
-export const FOOTNOTE_REF_RE_G = /\[\^([^\]\s]+)\]/g;
-/** Opening/closing code fence marker (``` or ~~~). */
-const FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
-/** Classify every line of `markdown`, tracking fenced-code state. Pure. */
-export function lexFootnoteLines(markdown) {
-    const out = [];
-    let fence = null;
-    for (const line of markdown.split("\n")) {
-        const fenceMatch = FENCE_RE.exec(line);
-        if (fenceMatch) {
-            const marker = fenceMatch[2][0];
-            if (fence === null)
-                fence = marker; // opening fence
-            else if (marker === fence)
-                fence = null; // matching closing fence
-            out.push({ line, inFence: true, definition: null });
-            continue;
-        }
-        if (fence !== null) {
-            out.push({ line, inFence: true, definition: null });
-            continue;
-        }
-        const m = FOOTNOTE_DEF_RE.exec(line);
-        out.push({
-            line,
-            inFence: false,
-            definition: m ? { id: m[1], text: m[2] } : null,
-        });
-    }
-    return out;
-}
-/** Scan a line for every `[^id]` reference, invoking `onRef(id)` for each. */
-export function forEachFootnoteReference(line, onRef) {
-    FOOTNOTE_REF_RE_G.lastIndex = 0;
-    let m;
-    while ((m = FOOTNOTE_REF_RE_G.exec(line)) !== null)
-        onRef(m[1]);
-}
diff --git a/packages/mcp/build/lib/internal-file-urls.js b/packages/mcp/build/lib/internal-file-urls.js
deleted file mode 100644
index 3fc89bbe..00000000
--- a/packages/mcp/build/lib/internal-file-urls.js
+++ /dev/null
@@ -1,110 +0,0 @@
-// Detection + collection of INTERNAL Docmost file URLs inside a ProseMirror doc.
-//
-// An internal file URL is a relative path served by Docmost's authenticated
-// attachment route (`GET /api/files/:fileId/:fileName`). It is useless to an
-// external consumer (relative + needs a Docmost session), so the stash tool
-// mirrors every such resource into the blob sandbox and rewrites its `src`.
-//
-// The criterion is "internal file URL", NOT the node TYPE: image, drawio,
-// excalidraw, video and file nodes all carry such a `src`, so a type-agnostic
-// walker covers them all. External http(s) srcs (CDNs) are left untouched.
-//
-// Mirrors editor-ext's isInternalFileUrl / normalizeFileUrl (kept as a local
-// dup so the ESM mcp package does not depend on the editor-ext build).
-function isInternalFileUrl(url) {
-    if (typeof url !== "string")
-        return false;
-    const normalized = url.trim();
-    return (normalized.startsWith("/api/files/") || normalized.startsWith("/files/"));
-}
-/** Normalize a bare `/files/...` src to the canonical `/api/files/...` form. */
-export function normalizeFileUrl(src) {
-    const trimmed = src.trim();
-    if (trimmed.startsWith("/files/"))
-        return "/api" + trimmed;
-    return trimmed;
-}
-/**
- * Resolve a page-content `src` into the safe, `/api`-relative path the stash
- * tool may fetch over the authenticated loopback client — or THROW.
- *
- * SECURITY (SSRF / path-traversal): `src` comes from page content and is fully
- * attacker-controllable. The mirroring fetch runs through the AUTHENTICATED
- * loopback axios client whose baseURL ends in `/api`, so a naive
- * `src.replace(/^\/api/, "")` lets a crafted value like
- * `/api/files/../auth/whoami` collapse (via axios/WHATWG URL `..` resolution)
- * into an ARBITRARY internal GET endpoint, whose authed response would then be
- * stored in the anonymous sandbox (SSRF + data exfiltration). A prefix-only
- * `startsWith("/api/files/")` check does NOT defend against this because the
- * `..` segments are still present in the raw string and resolved later.
- *
- * This function defeats that by resolving the canonical pathname FIRST and only
- * then asserting it still lives under `/api/files/`:
- *  - it rejects any percent-encoded dot/slash (`%2e` / `%2f`): the WHATWG URL
- *    parser collapses LITERAL `../` but does NOT decode `%2f` separators, so a
- *    content-controlled src must never be allowed to smuggle those past the
- *    canonicalization;
- *  - it resolves `new URL(trimmed, "http://internal.invalid").pathname`, which
- *    normalizes `..`/`.` segments (e.g. `/api/files/../auth/whoami` →
- *    `/api/auth/whoami`);
- *  - it then requires the canonical pathname to start with `/api/files/`, so a
- *    traversal that escaped that subtree is rejected.
- *
- * Returns the path RELATIVE to the `/api` base (e.g. `/files/<id>/<name>`),
- * ready to hand to the loopback client. The throw happens BEFORE any network
- * call, so a rejected src is counted as a failed mirror and its original src is
- * kept (the per-image try/catch in stashPage never aborts the whole document).
- */
-export function resolveInternalFilePath(src) {
-    const trimmed = src.trim();
-    // Percent-encoded dot/slash must never reach the URL canonicalizer: the
-    // WHATWG parser does NOT decode `%2f` into a path separator, so an encoded
-    // `..%2fauth` would survive canonicalization and still escape /api/files/.
-    if (/%2e|%2f/i.test(trimmed)) {
-        throw new Error(`Refusing internal file src with percent-encoded path segment: "${src}"`);
-    }
-    let pathname;
-    try {
-        // The base host is irrelevant (never contacted); it only lets the parser
-        // resolve a relative `src` and normalize `..`/`.` segments.
-        pathname = new URL(trimmed, "http://internal.invalid").pathname;
-    }
-    catch {
-        throw new Error(`Invalid internal file src: "${src}"`);
-    }
-    if (!pathname.startsWith("/api/files/")) {
-        throw new Error(`Refusing internal file src that escapes /api/files/: "${src}"`);
-    }
-    // Strip the `/api` base prefix; the loopback client's baseURL already ends
-    // in `/api`, so it expects the path relative to that (e.g. /files/<id>/<f>).
-    return pathname.replace(/^\/api/, "");
-}
-/**
- * Recursively collect every node whose `attrs.src` is an internal file URL.
- * Returns references to the live nodes (so the caller can rewrite `attrs.src`
- * in place on its clone). Descends `content` arrays, covering callouts, tables,
- * details and any other nested container.
- */
-export function collectInternalFileNodes(doc) {
-    const out = [];
-    const visit = (node) => {
-        if (!node)
-            return;
-        if (Array.isArray(node)) {
-            for (const child of node)
-                visit(child);
-            return;
-        }
-        if (typeof node !== "object")
-            return;
-        if (node.attrs && isInternalFileUrl(node.attrs.src)) {
-            out.push(node);
-        }
-        if (Array.isArray(node.content)) {
-            for (const child of node.content)
-                visit(child);
-        }
-    };
-    visit(doc);
-    return out;
-}
diff --git a/packages/mcp/build/lib/json-edit.js b/packages/mcp/build/lib/json-edit.js
deleted file mode 100644
index 4a98a4c5..00000000
--- a/packages/mcp/build/lib/json-edit.js
+++ /dev/null
@@ -1,393 +0,0 @@
-/**
- * Surgical text edits on a ProseMirror document without re-importing it.
- *
- * Each edit replaces an exact substring of a block's inline text, preserving
- * every node id, mark and attribute around it. Matching works at the
- * INLINE-CONTAINER (block) level: a block's text nodes are flattened into a
- * per-character array, so a `find` may freely cross bold/italic/link
- * boundaries (separate text nodes). The replacement inherits marks from the
- * unchanged common prefix/suffix of the match, so editing plain text next to a
- * bold word keeps the bold word bold, and editing the inside of a bold word
- * keeps the inserted text bold. This is the safe alternative to a full markdown
- * re-import for small wording fixes.
- */
-import { stripInlineMarkdown, stripBalancedWrappers } from "./text-normalize.js";
-/** Placeholder code unit standing in for one opaque (non-text) inline node. */
-const ATOM_PLACEHOLDER = ""; // OBJECT REPLACEMENT CHARACTER
-/**
- * Find every VALID occurrence of `needle` in a block's flattened slots.
- *
- * A candidate occurrence at slot range [start, start+needle.length) is valid
- * ONLY IF none of the slots in that range are atoms (non-text inline nodes).
- * This makes atom matching collision-safe against the U+FFFC placeholder: an
- * atom slot can never be part of a match, while a real text node containing a
- * literal U+FFFC code unit still matches normally (its slot has no `.atom`).
- *
- * Overlapping candidates that touch an atom are skipped (not counted, not
- * spliced); the scan resumes one code unit past the rejected start so a valid
- * match that begins just after an atom is not missed.
- */
-function findValidMatches(chars, plain, needle) {
-    if (!needle)
-        return [];
-    const positions = [];
-    let idx = plain.indexOf(needle);
-    while (idx !== -1) {
-        const end = idx + needle.length;
-        let hasAtom = false;
-        for (let i = idx; i < end; i++) {
-            if (chars[i] && chars[i].atom) {
-                hasAtom = true;
-                break;
-            }
-        }
-        if (!hasAtom) {
-            positions.push(idx);
-            // Non-overlapping: skip past this match.
-            idx = plain.indexOf(needle, end);
-        }
-        else {
-            // This candidate crosses an atom: reject it and resume one unit later so
-            // an overlapping valid match starting after the atom is still found.
-            idx = plain.indexOf(needle, idx + 1);
-        }
-    }
-    return positions;
-}
-/** Order-sensitive deep-equality of two marks arrays. */
-function marksEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a.length !== b.length)
-        return false;
-    for (let i = 0; i < a.length; i++) {
-        if (JSON.stringify(a[i]) !== JSON.stringify(b[i]))
-            return false;
-    }
-    return true;
-}
-/** A block is any node that DIRECTLY contains at least one inline text child. */
-function isInlineBlock(node) {
-    return (Array.isArray(node?.content) &&
-        node.content.some((child) => child && child.type === "text"));
-}
-/** Flatten a block's inline content into a per-code-unit slot array. */
-function flattenBlock(node) {
-    const chars = [];
-    for (const child of node.content || []) {
-        if (child && child.type === "text" && typeof child.text === "string") {
-            const marks = child.marks || [];
-            // Iterate by UTF-16 code unit so indices align with String.indexOf.
-            for (let i = 0; i < child.text.length; i++) {
-                chars.push({ ch: child.text[i], marks });
-            }
-        }
-        else {
-            // Any non-text inline node becomes one opaque slot.
-            chars.push({
-                ch: ATOM_PLACEHOLDER,
-                marks: (child && child.marks) || [],
-                atom: child,
-            });
-        }
-    }
-    return chars;
-}
-/** Re-tokenize a slot array back into ProseMirror inline nodes. */
-function tokenizeChars(chars) {
-    const out = [];
-    let buffer = "";
-    let bufferMarks = null;
-    const flush = () => {
-        if (buffer.length === 0)
-            return;
-        const textNode = { type: "text", text: buffer };
-        if (bufferMarks && bufferMarks.length > 0)
-            textNode.marks = bufferMarks;
-        out.push(textNode);
-        buffer = "";
-        bufferMarks = null;
-    };
-    for (const slot of chars) {
-        if (slot.atom) {
-            flush();
-            out.push(slot.atom);
-            continue;
-        }
-        if (bufferMarks !== null && !marksEqual(bufferMarks, slot.marks)) {
-            flush();
-        }
-        if (bufferMarks === null)
-            bufferMarks = slot.marks;
-        buffer += slot.ch;
-    }
-    flush();
-    return out;
-}
-/** Longest common prefix length of two strings. */
-function commonPrefixLen(a, b) {
-    const max = Math.min(a.length, b.length);
-    let i = 0;
-    while (i < max && a[i] === b[i])
-        i++;
-    return i;
-}
-/** Longest common suffix length of two strings, capped so it can't overlap. */
-function commonSuffixLen(a, b, cap) {
-    const max = Math.min(a.length, b.length, cap);
-    let i = 0;
-    while (i < max && a[a.length - 1 - i] === b[b.length - 1 - i])
-        i++;
-    return i;
-}
-/**
- * Apply one edit to one block's flattened slot array.
- *
- * The caller passes only VALID (atom-free) match positions (see
- * findValidMatches), so no match range can overlap an atom slot here.
- */
-function applyEditToChars(chars, edit, matchPositions) {
-    // Pre-compute the diff slices once (find/replace are constant per edit).
-    const p = commonPrefixLen(edit.find, edit.replace);
-    const s = commonSuffixLen(edit.find, edit.replace, Math.min(edit.find.length, edit.replace.length) - p);
-    const insertText = edit.replace.slice(p, edit.replace.length - s);
-    // Rebuild the slot array in a single left-to-right pass, splicing at each
-    // match start. Offsets into `chars` stay valid because we copy through.
-    const newChars = [];
-    let cursor = 0;
-    let spliced = 0;
-    for (const mStart of matchPositions) {
-        const mEnd = mStart + edit.find.length;
-        const changedStart = mStart + p;
-        const changedEnd = mEnd - s;
-        // Copy through everything up to the changed region (incl. the prefix).
-        for (; cursor < changedStart; cursor++)
-            newChars.push(chars[cursor]);
-        const removed = chars.slice(changedStart, changedEnd);
-        // Choose the marks for the inserted characters.
-        let chosenMarks = [];
-        if (removed.length > 0 &&
-            removed.every((r) => marksEqual(r.marks, removed[0].marks))) {
-            // Uniform removed region: inherit its marks directly.
-            chosenMarks = removed[0].marks;
-        }
-        else {
-            // Empty or non-uniform removed region: inherit from the nearest TEXT
-            // neighbour, skipping atom slots (an atom carries marks that do not
-            // belong on inserted text). Scan left first, then right; fall back to [].
-            let inherited = null;
-            for (let i = changedStart - 1; i >= 0; i--) {
-                if (!chars[i].atom) {
-                    inherited = chars[i].marks;
-                    break;
-                }
-            }
-            if (inherited === null) {
-                for (let i = changedEnd; i < chars.length; i++) {
-                    if (!chars[i].atom) {
-                        inherited = chars[i].marks;
-                        break;
-                    }
-                }
-            }
-            chosenMarks = inherited === null ? [] : inherited;
-        }
-        // Emit the inserted text (one slot per code unit).
-        for (let i = 0; i < insertText.length; i++) {
-            newChars.push({ ch: insertText[i], marks: chosenMarks });
-        }
-        // Skip the removed region.
-        cursor = changedEnd;
-        spliced++;
-    }
-    // Copy through the tail.
-    for (; cursor < chars.length; cursor++)
-        newChars.push(chars[cursor]);
-    return { newChars, spliced };
-}
-/**
- * Apply text edits to a ProseMirror doc (operates on a deep copy, returns it).
- *
- * Returns { doc, results, failed }:
- *  - results: edits that applied (replacements >= 1).
- *  - failed:  edits that matched zero times, were ambiguous (multi-match
- *    without replaceAll), or whose changed region crosses a non-text inline
- *    node. These do NOT throw — they are recorded so the caller can surface an
- *    actionable message and still keep the edits that did apply.
- *
- * Edits apply IN ORDER to the same working copy, so a later edit can target
- * text produced by an earlier one. The input doc is never mutated. The only
- * thrown error is for invalid input (an empty `edit.find`).
- */
-export function applyTextEdits(doc, edits) {
-    const copy = JSON.parse(JSON.stringify(doc));
-    const results = [];
-    const failed = [];
-    for (const edit of edits) {
-        if (!edit.find)
-            throw new Error("edit.find must be a non-empty string");
-        // HARD-REFUSE formatting changes. edit_page_text edits PLAIN TEXT only and
-        // writes the replacement verbatim, so it cannot add/remove marks. We refuse
-        // only a pure formatting TOGGLE: find and replace differ ONLY by balanced
-        // markdown markers (e.g. find:"~~$69~~" / replace:"$69", or find:"M5Stack" /
-        // replace:"**M5Stack**" which would write literal `**`).
-        //
-        // The detector is the STRICT stripBalancedWrappers, NOT the lenient locator
-        // stripInlineMarkdown: the lenient one also trims whitespace/emoji and
-        // collapses lone `*`/`_` runs, which gives false positives on ordinary
-        // plain-text edits (trailing-space trim, snake_case, `2 * 3 * 4`, URLs with
-        // underscores) and wrongly refuses them. Comparing the strict strip of both
-        // sides symmetrically catches every real formatting toggle while leaving
-        // plain text alone; a typo fix wrapped in markdown still applies because its
-        // stripped find != stripped replace.
-        const formattingOnly = edit.find !== edit.replace &&
-            stripBalancedWrappers(edit.find) === stripBalancedWrappers(edit.replace);
-        if (formattingOnly) {
-            failed.push({
-                find: edit.find,
-                reason: "edit_page_text edits plain text only and cannot add or remove formatting marks (bold/italic/strike/code/link); it writes the replacement as LITERAL text. This edit looks like a formatting change (markdown markers in find/replace). To change marks, read the block with get_page_json and use patch_node (or update_page_json) to set the node's marks array.",
-            });
-            continue;
-        }
-        // Gather every inline block in document order (recurse the whole tree so
-        // nested containers — callouts, list items, table cells, blockquotes — are
-        // all covered).
-        const blocks = [];
-        (function collect(node) {
-            if (isInlineBlock(node))
-                blocks.push(node);
-            for (const child of node.content || [])
-                collect(child);
-        })(copy);
-        // Find every VALID (atom-free) occurrence per block. A candidate whose slot
-        // range overlaps a non-text inline atom is never a match (collision-safe vs
-        // the U+FFFC placeholder), so it is excluded from both the uniqueness count
-        // and the splicing.
-        const blockChars = blocks.map((b) => flattenBlock(b));
-        const blockPlain = blockChars.map((chars) => chars.map((c) => c.ch).join(""));
-        // EXACT MATCH WINS: try the verbatim locator first.
-        let effectiveFind = edit.find;
-        let normalized = false;
-        let validPerBlock = blockChars.map((chars, b) => findValidMatches(chars, blockPlain[b], edit.find));
-        let total = 0;
-        for (const positions of validPerBlock)
-            total += positions.length;
-        // FALLBACK: only if the verbatim locator matched nothing, retry with the
-        // markdown-stripped form. `edit.replace` is never touched — this only
-        // changes what we LOCATE, not what we insert.
-        const stripped = stripInlineMarkdown(edit.find);
-        if (total === 0 && stripped !== edit.find && stripped.length > 0) {
-            const strippedPerBlock = blockChars.map((chars, b) => findValidMatches(chars, blockPlain[b], stripped));
-            let strippedTotal = 0;
-            for (const positions of strippedPerBlock)
-                strippedTotal += positions.length;
-            if (strippedTotal >= 1) {
-                validPerBlock = strippedPerBlock;
-                total = strippedTotal;
-                effectiveFind = stripped;
-                normalized = true;
-            }
-        }
-        if (total === 0) {
-            // Distinguish "the text exists but only across an atom" from a plain
-            // not-found: if a raw substring scan (atoms included) WOULD have hit —
-            // for EITHER the verbatim or the stripped locator — the only thing
-            // blocking the edit is the atom, so report that.
-            const existsAcrossAtom = blockPlain.some((plain) => plain.indexOf(edit.find) !== -1 ||
-                (stripped !== edit.find && plain.indexOf(stripped) !== -1));
-            let reason;
-            if (existsAcrossAtom) {
-                reason =
-                    "match crosses a non-text inline node (image/break/mention); use update_page_json for structural changes.";
-            }
-            else {
-                // Append a bounded "closest text" hint: find the FIRST block that
-                // contains the longest whitespace-delimited token (>= 3 chars) of the
-                // (stripped, then raw) locator, and quote that block's plain text.
-                reason = "text not found in the document.";
-                const tokenSource = stripped.length > 0 ? stripped : edit.find;
-                const longestToken = tokenSource
-                    .split(/\s+/)
-                    .filter((t) => t.length >= 3)
-                    .sort((a, b) => b.length - a.length)[0];
-                if (longestToken) {
-                    const hitBlock = blockPlain.find((plain) => plain.includes(longestToken));
-                    if (hitBlock) {
-                        // Truncate by code point (spread iterates by code point) so a
-                        // surrogate pair is never split; append the ellipsis only when the
-                        // text was actually longer than the limit.
-                        const points = [...hitBlock];
-                        const snippet = points.length > 120
-                            ? points.slice(0, 120).join("") + "…"
-                            : hitBlock;
-                        reason += ` Closest block text: "${snippet}".`;
-                    }
-                }
-            }
-            failed.push({ find: edit.find, reason });
-            continue;
-        }
-        if (total > 1 && !edit.replaceAll) {
-            failed.push({
-                find: edit.find,
-                reason: `matches ${total} times. Provide a longer, unique fragment or set replaceAll: true.`,
-            });
-            continue;
-        }
-        // Plan the splices from the valid positions. For a non-replaceAll edit we
-        // splice only the first valid match (left-to-right across blocks); for
-        // replaceAll we splice every valid match.
-        const plannedPerBlock = blockChars.map(() => []);
-        let takenFirst = false;
-        for (let b = 0; b < validPerBlock.length; b++) {
-            for (const idx of validPerBlock[b]) {
-                if (edit.replaceAll) {
-                    plannedPerBlock[b].push(idx);
-                }
-                else if (!takenFirst) {
-                    plannedPerBlock[b].push(idx);
-                    takenFirst = true;
-                    break;
-                }
-                else {
-                    break;
-                }
-            }
-            if (!edit.replaceAll && takenFirst)
-                break;
-        }
-        // Apply the splices block-by-block and re-tokenize changed blocks. The
-        // local edit uses `effectiveFind` (verbatim or normalized) so the
-        // prefix/suffix diff is computed against the ACTUALLY matched text, while
-        // `edit.replace` stays literal — never stripped.
-        const effectiveEdit = {
-            find: effectiveFind,
-            replace: edit.replace,
-            replaceAll: edit.replaceAll,
-        };
-        let spliced = 0;
-        for (let b = 0; b < blocks.length; b++) {
-            if (plannedPerBlock[b].length === 0)
-                continue;
-            const { newChars, spliced: n } = applyEditToChars(blockChars[b], effectiveEdit, plannedPerBlock[b]);
-            spliced += n;
-            blocks[b].content = tokenizeChars(newChars);
-        }
-        // Keep `find: edit.find` (the original) so the caller can correlate.
-        const result = { find: edit.find, replacements: spliced };
-        if (normalized)
-            result.normalized = true;
-        results.push(result);
-    }
-    // Safety net: drop any empty text nodes (ProseMirror forbids them). The
-    // re-tokenizer never emits empty text nodes, but untouched blocks could in
-    // principle carry one in from upstream.
-    (function prune(node) {
-        if (Array.isArray(node.content)) {
-            node.content = node.content.filter((child) => !(child.type === "text" && child.text === ""));
-            for (const child of node.content)
-                prune(child);
-        }
-    })(copy);
-    return { doc: copy, results, failed };
-}
diff --git a/packages/mcp/build/lib/markdown-converter.js b/packages/mcp/build/lib/markdown-converter.js
deleted file mode 100644
index 96536036..00000000
--- a/packages/mcp/build/lib/markdown-converter.js
+++ /dev/null
@@ -1,835 +0,0 @@
-/**
- * Convert ProseMirror/TipTap JSON content to Markdown
- * Supports all Docmost-specific node types and extensions
- */
-export function convertProseMirrorToMarkdown(content) {
-    if (!content || !content.content)
-        return "";
-    // Escape a value interpolated into an HTML double-quoted attribute value
-    // (textAlign, colors, image src, math `text`, all data-* attrs, etc.). In the
-    // ATTRIBUTE context only the quote that delimits the value and the ampersand
-    // that starts an entity are special, so we escape ONLY & " (and ' for safety
-    // when single-quoted delimiters are used). We deliberately do NOT escape < or
-    // >: the HTML re-parser (parse5/jsdom via @tiptap/html) does NOT decode
-    // &lt;/&gt; back inside attribute values, so escaping them would corrupt the
-    // stored data (e.g. a math node's LaTeX `a < b`) and ACCUMULATE escapes on
-    // every round-trip (`a < b` -> `a &lt; b` -> `a &amp;lt; b`). Escaping & "
-    // keeps the value inert against attribute-injection while staying idempotent.
-    // NOTE: escape ONLY & and " here. The value is always wrapped in double
-    // quotes, so " is the only delimiter; ' is NOT special in a double-quoted
-    // value, and parse5 does not decode &#39; back inside attribute values, so
-    // escaping ' would (like < >) corrupt the value and accumulate &amp; on every
-    // round-trip. Escaping & and " is idempotent (parse5 decodes them back).
-    const escapeAttr = (value) => String(value)
-        .replace(/&/g, "&amp;")
-        .replace(/"/g, "&quot;");
-    // Escape a value placed as HTML element TEXT content (between tags), where
-    // <, >, and & are all significant. Used for text rendered inside raw-HTML
-    // blocks (table cells / columns) so stored characters cannot inject markup.
-    const escapeHtmlText = (value) => String(value)
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
-    // Percent-encode characters that would break out of a markdown URL target
-    // (...) — whitespace/newlines and parentheses — so a stored src stays a
-    // single inert token (used for image/video/youtube srcs).
-    const encodeMdUrl = (value) => String(value || "")
-        .replace(/\s/g, (c) => (c === " " ? "%20" : encodeURIComponent(c)))
-        .replace(/\(/g, "%28")
-        .replace(/\)/g, "%29");
-    const processNode = (node) => {
-        const type = node.type;
-        const nodeContent = node.content || [];
-        switch (type) {
-            case "doc":
-                return nodeContent.map(processNode).join("\n\n");
-            case "paragraph":
-                const text = nodeContent.map(processNode).join("");
-                const align = node.attrs?.textAlign;
-                if (align && align !== "left") {
-                    return `<div align="${escapeAttr(align)}">${text}</div>`;
-                }
-                return text || "";
-            case "heading":
-                const level = node.attrs?.level || 1;
-                const headingText = nodeContent.map(processNode).join("");
-                return "#".repeat(level) + " " + headingText;
-            case "text":
-                let textContent = node.text || "";
-                // Apply marks (bold, italic, code, etc.)
-                if (node.marks) {
-                    // Markdown code spans (`...`) cannot carry inner formatting, so when a
-                    // run has the `code` mark alongside ANY other mark, backtick syntax
-                    // would leak literal ** / []() into the code text. In that case emit
-                    // nested HTML (<code> innermost, the other marks wrapping it as HTML)
-                    // so the output is at least well-formed and re-parseable.
-                    //
-                    // NOTE: this does NOT round-trip both marks. The schema's `code` mark
-                    // has `excludes: "_"` (it excludes every other mark), so on import the
-                    // co-occurring mark is always dropped — the run comes back as `code`
-                    // only. We keep the emission simple and accept that the other mark is
-                    // lost; preserving both is impossible while `code` excludes them.
-                    // Only use the backtick form when `code` is the sole mark.
-                    const markTypes = node.marks.map((m) => m.type);
-                    const hasCode = markTypes.includes("code");
-                    const codeCombined = hasCode && markTypes.length > 1;
-                    for (const mark of node.marks) {
-                        switch (mark.type) {
-                            case "bold":
-                                textContent = codeCombined
-                                    ? `<strong>${textContent}</strong>`
-                                    : `**${textContent}**`;
-                                break;
-                            case "italic":
-                                textContent = codeCombined
-                                    ? `<em>${textContent}</em>`
-                                    : `*${textContent}*`;
-                                break;
-                            case "code":
-                                // When combined with another mark, wrap as <code> so the
-                                // surrounding HTML marks can nest around it; otherwise use the
-                                // plain backtick span.
-                                textContent = codeCombined
-                                    ? `<code>${textContent}</code>`
-                                    : `\`${textContent}\``;
-                                break;
-                            case "link": {
-                                const href = mark.attrs?.href || "";
-                                const title = mark.attrs?.title;
-                                if (codeCombined) {
-                                    // Emit an HTML anchor so it can wrap the nested <code>.
-                                    const safeHref = escapeAttr(href);
-                                    if (title) {
-                                        textContent = `<a href="${safeHref}" title="${escapeAttr(String(title))}">${textContent}</a>`;
-                                    }
-                                    else {
-                                        textContent = `<a href="${safeHref}">${textContent}</a>`;
-                                    }
-                                }
-                                else if (title) {
-                                    // Emit the optional markdown link title; escape an embedded
-                                    // double-quote so it cannot terminate the title string early.
-                                    const safeTitle = String(title).replace(/"/g, '\\"');
-                                    textContent = `[${textContent}](${href} "${safeTitle}")`;
-                                }
-                                else {
-                                    textContent = `[${textContent}](${href})`;
-                                }
-                                break;
-                            }
-                            case "strike":
-                                textContent = codeCombined
-                                    ? `<s>${textContent}</s>`
-                                    : `~~${textContent}~~`;
-                                break;
-                            case "underline":
-                                textContent = `<u>${textContent}</u>`;
-                                break;
-                            case "subscript":
-                                textContent = `<sub>${textContent}</sub>`;
-                                break;
-                            case "superscript":
-                                textContent = `<sup>${textContent}</sup>`;
-                                break;
-                            case "highlight": {
-                                // Preserve a null/empty color as a plain highlight (a bare
-                                // <mark> with no background-color); only emit the style when a
-                                // color is actually set, so a plain highlight is not forced to
-                                // yellow on export.
-                                const color = mark.attrs?.color;
-                                textContent = color
-                                    ? `<mark style="background-color: ${escapeAttr(color)}">${textContent}</mark>`
-                                    : `<mark>${textContent}</mark>`;
-                                break;
-                            }
-                            case "textStyle":
-                                if (mark.attrs?.color) {
-                                    textContent = `<span style="color: ${escapeAttr(mark.attrs.color)}">${textContent}</span>`;
-                                }
-                                break;
-                            case "comment": {
-                                // Emit the inline comment anchor so highlights round-trip. The
-                                // schema's Comment mark parses span[data-comment-id] (attrs
-                                // commentId/resolved).
-                                const cid = mark.attrs?.commentId;
-                                if (cid) {
-                                    const resolvedAttr = mark.attrs?.resolved
-                                        ? ` data-resolved="true"`
-                                        : "";
-                                    textContent = `<span data-comment-id="${escapeAttr(cid)}"${resolvedAttr}>${textContent}</span>`;
-                                }
-                                break;
-                            }
-                            case "spoiler":
-                                // Markdown has no native spoiler syntax, so emit the same
-                                // lossless raw HTML the editor-ext turndown rule produces; the
-                                // schema's Spoiler mark parses span[data-spoiler] back on import.
-                                textContent = `<span data-spoiler="true">${textContent}</span>`;
-                                break;
-                        }
-                    }
-                }
-                return textContent;
-            case "codeBlock":
-                const language = node.attrs?.language || "";
-                // Strip ALL trailing newlines so the export is idempotent: marked
-                // re-adds exactly one trailing "\n" on import, so trimming only one
-                // here would let the text grow by "\n" on each round-trip. Removing
-                // every trailing newline makes repeated cycles stable.
-                const code = nodeContent
-                    .map(processNode)
-                    .join("")
-                    .replace(/\n+$/, "");
-                return "```" + language + "\n" + code + "\n```";
-            case "bulletList":
-                return nodeContent
-                    .map((item) => processListItem(item, "-"))
-                    .join("\n");
-            case "orderedList":
-                return nodeContent
-                    .map((item, index) => processListItem(item, `${index + 1}.`))
-                    .join("\n");
-            case "taskList":
-                return nodeContent.map((item) => processTaskItem(item)).join("\n");
-            case "taskItem":
-                // Delegate to the same helper used by taskList so multi-block and
-                // nested task items render and indent consistently.
-                return processTaskItem(node);
-            case "listItem":
-                return nodeContent.map(processNode).join("\n");
-            case "blockquote":
-                // Prefix EVERY line of EVERY child with "> " and separate block-level
-                // children with a blank ">" line so code blocks / multi-paragraph
-                // quotes round-trip correctly.
-                return nodeContent
-                    .map((n) => processNode(n)
-                    .split("\n")
-                    .map((line) => (line.length ? `> ${line}` : ">"))
-                    .join("\n"))
-                    .join("\n>\n");
-            case "horizontalRule":
-                return "---";
-            case "hardBreak":
-                // Two trailing spaces before the newline encode a markdown hard break;
-                // a bare "\n" would be reimported as a soft break and lost.
-                return "  \n";
-            case "image": {
-                const imgAlt = node.attrs?.alt || "";
-                const imgCaption = node.attrs?.caption || "";
-                if (imgCaption) {
-                    // ![]() can't carry a caption, so (symmetric to video) emit a raw
-                    // <img> wrapped in a block <div>. On import marked.parse keeps the raw
-                    // HTML and generateJSON runs the image extension's parseHTML, which
-                    // restores the caption from data-caption.
-                    const parts = [`src="${escapeAttr(node.attrs?.src ?? "")}"`];
-                    if (imgAlt)
-                        parts.push(`alt="${escapeAttr(imgAlt)}"`);
-                    parts.push(`data-caption="${escapeAttr(imgCaption)}"`);
-                    return `<div><img ${parts.join(" ")}></div>`;
-                }
-                // Neutralize characters that could break out of the markdown image
-                // URL: spaces/newlines and parentheses would terminate the (...) target
-                // and let a stored src inject following markdown/HTML. Percent-encode
-                // them so the URL stays a single inert token.
-                const imgSrc = encodeMdUrl(node.attrs?.src);
-                return `![${imgAlt}](${imgSrc})`;
-            }
-            case "video": {
-                // Emit the schema-matching <video> element so generateJSON rebuilds the
-                // node with its attrs intact. The schema's parseHTML reads src/aria-label
-                // from the standard attributes and the remaining attrs from data-*.
-                const attrs = node.attrs || {};
-                const parts = [`src="${escapeAttr(attrs.src ?? "")}"`];
-                if (attrs.alt)
-                    parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
-                if (attrs.attachmentId)
-                    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-                if (attrs.width != null)
-                    parts.push(`width="${escapeAttr(attrs.width)}"`);
-                if (attrs.height != null)
-                    parts.push(`height="${escapeAttr(attrs.height)}"`);
-                if (attrs.size != null)
-                    parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-                if (attrs.align)
-                    parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-                if (attrs.aspectRatio != null)
-                    parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-                // Wrap in a block <div> so marked treats it as a block (a bare <video>
-                // is inline-level HTML and marked wraps it in <p>, leaving a spurious
-                // empty paragraph beside the hoisted block atom). The wrapper has no
-                // data-type, so the schema parser ignores it and just hoists the video.
-                return `<div><video ${parts.join(" ")}></video></div>`;
-            }
-            case "youtube": {
-                // Emit the schema-matching div[data-type="youtube"]; the schema reads
-                // src from data-src and width/height/align from data-* attributes.
-                const attrs = node.attrs || {};
-                const parts = [
-                    `data-type="youtube"`,
-                    `data-src="${escapeAttr(attrs.src ?? "")}"`,
-                ];
-                if (attrs.width != null)
-                    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-                if (attrs.height != null)
-                    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-                if (attrs.align)
-                    parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-                return `<div ${parts.join(" ")}></div>`;
-            }
-            case "table": {
-                // A GFM pipe table cannot represent merged cells. If ANY cell carries
-                // colspan>1 or rowspan>1, a pipe table would corrupt the grid on
-                // re-import, so emit the WHOLE table as raw HTML <table> instead: the
-                // schema's table family parseHTML (tag table/tr/td/th, with colspan/
-                // rowspan read from the same-named HTML attrs and align via parseHTML)
-                // round-trips it faithfully. Otherwise keep the lighter GFM pipe table.
-                const tableRows = nodeContent;
-                if (tableRows.length === 0)
-                    return "";
-                const hasSpan = tableRows.some((row) => (row.content || []).some((cell) => (cell.attrs?.colspan ?? 1) > 1 || (cell.attrs?.rowspan ?? 1) > 1));
-                if (hasSpan) {
-                    // Render each cell's block children to HTML (marked does NOT parse
-                    // markdown inside a raw HTML block, so emitting markdown here would
-                    // leak literal ** / `` into the cell). blockToHtml mirrors the schema
-                    // HTML so inner formatting re-parses into the right marks/nodes.
-                    const renderHtmlCell = (cell) => {
-                        const tag = cell.type === "tableHeader" ? "th" : "td";
-                        const a = cell.attrs || {};
-                        const cellParts = [];
-                        if ((a.colspan ?? 1) > 1)
-                            cellParts.push(`colspan="${escapeAttr(a.colspan)}"`);
-                        if ((a.rowspan ?? 1) > 1)
-                            cellParts.push(`rowspan="${escapeAttr(a.rowspan)}"`);
-                        if (a.align)
-                            cellParts.push(`align="${escapeAttr(a.align)}"`);
-                        const open = cellParts.length
-                            ? `<${tag} ${cellParts.join(" ")}>`
-                            : `<${tag}>`;
-                        const inner = (cell.content || [])
-                            .map((block) => blockToHtml(block))
-                            .join("");
-                        return `${open}${inner}</${tag}>`;
-                    };
-                    const htmlRows = tableRows
-                        .map((row) => `<tr>${(row.content || []).map(renderHtmlCell).join("")}</tr>`)
-                        .join("");
-                    return `<table><tbody>${htmlRows}</tbody></table>`;
-                }
-                // No merged cells: emit a GFM table (header row + separator) so the
-                // markdown can be parsed back into a table on re-import.
-                const rows = tableRows.map(processNode);
-                const headerCells = tableRows[0]?.content || [];
-                const columns = headerCells.length || 1;
-                // Derive alignment markers (:--, :-:, --:) from each header cell.
-                const markers = Array.from({ length: columns }, (_, i) => {
-                    const align = headerCells[i]?.attrs?.align;
-                    switch (align) {
-                        case "left":
-                            return ":--";
-                        case "center":
-                            return ":-:";
-                        case "right":
-                            return "--:";
-                        default:
-                            return "---";
-                    }
-                });
-                const separator = "| " + markers.join(" | ") + " |";
-                return [rows[0], separator, ...rows.slice(1)].join("\n");
-            }
-            case "tableRow":
-                return "| " + nodeContent.map(processNode).join(" | ") + " |";
-            case "tableCell":
-            case "tableHeader": {
-                // Join multiple block children with a space (not "") so adjacent blocks
-                // like a paragraph followed by a list don't collide into "line1- a".
-                // Then collapse newlines and escape pipes so a cell containing "|" or a
-                // line break cannot corrupt the surrounding GFM row.
-                return nodeContent
-                    .map(processNode)
-                    .join(" ")
-                    .replace(/\r?\n/g, " ")
-                    .replace(/\|/g, "\\|");
-            }
-            case "callout":
-                const calloutType = node.attrs?.type || "info";
-                const calloutContent = nodeContent.map(processNode).join("\n");
-                return `:::${calloutType.toLowerCase()}\n${calloutContent}\n:::`;
-            case "details":
-                return nodeContent.map(processNode).join("\n");
-            case "detailsSummary":
-                const summaryText = nodeContent.map(processNode).join("");
-                return `<details>\n<summary>${summaryText}</summary>\n`;
-            case "detailsContent":
-                const detailsText = nodeContent.map(processNode).join("\n");
-                return `${detailsText}\n</details>`;
-            case "mathInline": {
-                // The schema's `text` attribute has no parseHTML, so TipTap's default
-                // parser reads it from the `text` HTML attribute (NOT the element's text
-                // content). Emit span[data-type="mathInline"] carrying the LaTeX in a
-                // `text="..."` attribute so it round-trips. marked cannot parse $...$
-                // back, so the previous form was lossy.
-                const inlineMath = node.attrs?.text || "";
-                return `<span data-type="mathInline" data-katex="true" text="${escapeAttr(inlineMath)}"></span>`;
-            }
-            case "mathBlock": {
-                // Same as mathInline: the LaTeX must ride in the `text` HTML attribute
-                // for the schema's default parser to recover it.
-                const blockMath = node.attrs?.text || "";
-                return `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(blockMath)}"></div>`;
-            }
-            case "mention": {
-                // Emit span[data-type="mention"] with the schema's data-* attributes so
-                // generateJSON rebuilds the mention node instead of leaving "@label"
-                // plain text that cannot re-parse.
-                const attrs = node.attrs || {};
-                const parts = [`data-type="mention"`];
-                if (attrs.id)
-                    parts.push(`data-id="${escapeAttr(attrs.id)}"`);
-                if (attrs.label)
-                    parts.push(`data-label="${escapeAttr(attrs.label)}"`);
-                if (attrs.entityType)
-                    parts.push(`data-entity-type="${escapeAttr(attrs.entityType)}"`);
-                if (attrs.entityId)
-                    parts.push(`data-entity-id="${escapeAttr(attrs.entityId)}"`);
-                if (attrs.slugId)
-                    parts.push(`data-slug-id="${escapeAttr(attrs.slugId)}"`);
-                if (attrs.creatorId)
-                    parts.push(`data-creator-id="${escapeAttr(attrs.creatorId)}"`);
-                if (attrs.anchorId)
-                    parts.push(`data-anchor-id="${escapeAttr(attrs.anchorId)}"`);
-                // Keep the label as visible text content too; the schema reads attrs
-                // from data-*, so the inner text is purely cosmetic and harmless.
-                const mentionLabel = attrs.label || attrs.id || "";
-                // The label is visible element TEXT content here (the data-* attrs above
-                // 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
-                // schema-matching div[data-type="attachment"] with data-attachment-*
-                // attrs so the node round-trips instead of degrading to a markdown link.
-                const attrs = node.attrs || {};
-                const parts = [
-                    `data-type="attachment"`,
-                    `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
-                ];
-                if (attrs.name)
-                    parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
-                if (attrs.mime)
-                    parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
-                if (attrs.size != null)
-                    parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
-                if (attrs.attachmentId)
-                    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-                return `<div ${parts.join(" ")}></div>`;
-            }
-            case "drawio":
-            case "excalidraw": {
-                // Emit the schema-matching div[data-type=...] carrying the diagram's
-                // attrs as data-* (the schema's diagramAttributes reads src/title/alt/
-                // width/height/size/aspectRatio/align/attachmentId from data-*), so the
-                // diagram round-trips instead of degrading to a lossy placeholder.
-                const attrs = node.attrs || {};
-                const parts = [
-                    `data-type="${type}"`,
-                    `data-src="${escapeAttr(attrs.src ?? "")}"`,
-                ];
-                if (attrs.title != null)
-                    parts.push(`data-title="${escapeAttr(attrs.title)}"`);
-                if (attrs.alt != null)
-                    parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
-                if (attrs.width != null)
-                    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-                if (attrs.height != null)
-                    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-                if (attrs.size != null)
-                    parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-                if (attrs.aspectRatio != null)
-                    parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-                if (attrs.align)
-                    parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-                if (attrs.attachmentId)
-                    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-                return `<div ${parts.join(" ")}></div>`;
-            }
-            case "embed": {
-                // Emit the schema-matching div[data-type="embed"]; the schema reads
-                // src/provider/align/width/height from data-* attributes so the node
-                // (and its provider iframe info) survives the round-trip.
-                const attrs = node.attrs || {};
-                const parts = [
-                    `data-type="embed"`,
-                    `data-src="${escapeAttr(attrs.src ?? "")}"`,
-                    `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
-                ];
-                if (attrs.align)
-                    parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-                if (attrs.width != null)
-                    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-                if (attrs.height != null)
-                    parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-                return `<div ${parts.join(" ")}></div>`;
-            }
-            case "audio": {
-                // Emit the schema-matching <audio> element (was emitting nothing). The
-                // schema reads src from src and attachmentId/size from data-*.
-                const attrs = node.attrs || {};
-                const parts = [`src="${escapeAttr(attrs.src ?? "")}"`];
-                if (attrs.attachmentId)
-                    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-                if (attrs.size != null)
-                    parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-                // Wrap in a block <div> for the same reason as video: a bare <audio> is
-                // inline-level HTML that marked would wrap in <p>.
-                return `<div><audio ${parts.join(" ")}></audio></div>`;
-            }
-            case "pdf": {
-                // Emit the schema-matching div[data-type="pdf"] (was emitting nothing).
-                // The schema reads src/width/height from standard attrs and name/
-                // attachmentId/size from data-*.
-                const attrs = node.attrs || {};
-                const parts = [
-                    `data-type="pdf"`,
-                    `src="${escapeAttr(attrs.src ?? "")}"`,
-                ];
-                if (attrs.name)
-                    parts.push(`data-name="${escapeAttr(attrs.name)}"`);
-                if (attrs.attachmentId)
-                    parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-                if (attrs.size != null)
-                    parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-                if (attrs.width != null)
-                    parts.push(`width="${escapeAttr(attrs.width)}"`);
-                if (attrs.height != null)
-                    parts.push(`height="${escapeAttr(attrs.height)}"`);
-                return `<div ${parts.join(" ")}></div>`;
-            }
-            case "columns": {
-                // Emit the schema-matching div[data-type="columns"] wrapper so the
-                // multi-column layout survives. Without a case the children were
-                // concatenated with no separator and the text merged. The schema reads
-                // layout from data-layout and widthMode from data-width-mode. The whole
-                // block is raw HTML, so render children via blockToHtml (NOT markdown,
-                // which marked would not re-parse inside a raw HTML block).
-                const attrs = node.attrs || {};
-                const parts = [`data-type="columns"`];
-                if (attrs.layout)
-                    parts.push(`data-layout="${escapeAttr(attrs.layout)}"`);
-                if (attrs.widthMode && attrs.widthMode !== "normal")
-                    parts.push(`data-width-mode="${escapeAttr(attrs.widthMode)}"`);
-                const inner = nodeContent.map((n) => blockToHtml(n)).join("");
-                return `<div ${parts.join(" ")}>${inner}</div>`;
-            }
-            case "column": {
-                // Emit the schema-matching div[data-type="column"]; the schema reads the
-                // column width from data-width. Children are rendered as HTML so their
-                // formatting survives inside this raw HTML block.
-                const attrs = node.attrs || {};
-                const parts = [`data-type="column"`];
-                if (attrs.width)
-                    parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-                const inner = nodeContent.map((n) => blockToHtml(n)).join("");
-                return `<div ${parts.join(" ")}>${inner}</div>`;
-            }
-            case "subpages":
-                return "{{SUBPAGES}}";
-            default:
-                // Fallback: process children
-                return nodeContent.map(processNode).join("");
-        }
-    };
-    // Render inline content (text runs + their marks) to HTML. Used by the raw
-    // HTML fallbacks (spanned tables, columns) where marked will NOT re-parse
-    // markdown, so backtick/asterisk/bracket syntax would otherwise leak as
-    // literal characters. Each mark is mirrored to the HTML the schema's parseHTML
-    // accepts so it re-imports as the matching ProseMirror mark.
-    const inlineToHtml = (inlineNodes) => (inlineNodes || [])
-        .map((n) => {
-        if (n.type === "hardBreak")
-            return "<br>";
-        if (n.type !== "text") {
-            // Inline atoms (mention, mathInline) already emit schema HTML.
-            return processNode(n);
-        }
-        let t = escapeHtmlText(n.text || "");
-        for (const mark of n.marks || []) {
-            switch (mark.type) {
-                case "bold":
-                    t = `<strong>${t}</strong>`;
-                    break;
-                case "italic":
-                    t = `<em>${t}</em>`;
-                    break;
-                case "code":
-                    t = `<code>${t}</code>`;
-                    break;
-                case "strike":
-                    t = `<s>${t}</s>`;
-                    break;
-                case "underline":
-                    t = `<u>${t}</u>`;
-                    break;
-                case "subscript":
-                    t = `<sub>${t}</sub>`;
-                    break;
-                case "superscript":
-                    t = `<sup>${t}</sup>`;
-                    break;
-                case "link":
-                    t = `<a href="${escapeAttr(mark.attrs?.href || "")}">${t}</a>`;
-                    break;
-                case "highlight":
-                    t = mark.attrs?.color
-                        ? `<mark style="background-color: ${escapeAttr(mark.attrs.color)}">${t}</mark>`
-                        : `<mark>${t}</mark>`;
-                    break;
-                case "textStyle":
-                    if (mark.attrs?.color)
-                        t = `<span style="color: ${escapeAttr(mark.attrs.color)}">${t}</span>`;
-                    break;
-                case "comment":
-                    // Inline comment anchor inside a raw-HTML container (columns /
-                    // spanned table cells), so commented text there also round-trips.
-                    if (mark.attrs?.commentId) {
-                        const r = mark.attrs?.resolved ? ` data-resolved="true"` : "";
-                        t = `<span data-comment-id="${escapeAttr(mark.attrs.commentId)}"${r}>${t}</span>`;
-                    }
-                    break;
-            }
-        }
-        return t;
-    })
-        .join("");
-    // Emit the schema-matching <img> for an image node. Shared so the image is
-    // emitted as real HTML wherever a raw-HTML container needs it (inside a column
-    // or a spanned table cell), where markdown `![](...)` would NOT be re-parsed
-    // and would survive as literal text. The Image extension reads src/alt from
-    // the standard attributes; the Docmost extra attrs (width/height/align/size/
-    // attachmentId/aspectRatio) are global attributes read from same-named DOM
-    // attributes, so emit them by name.
-    const imageToHtml = (node) => {
-        const attrs = node.attrs || {};
-        const parts = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.alt)
-            parts.push(`alt="${escapeAttr(attrs.alt)}"`);
-        if (attrs.caption)
-            parts.push(`data-caption="${escapeAttr(attrs.caption)}"`);
-        if (attrs.title)
-            parts.push(`title="${escapeAttr(attrs.title)}"`);
-        if (attrs.width != null)
-            parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-            parts.push(`height="${escapeAttr(attrs.height)}"`);
-        if (attrs.align)
-            parts.push(`align="${escapeAttr(attrs.align)}"`);
-        if (attrs.size != null)
-            parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.attachmentId)
-            parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-        if (attrs.aspectRatio != null)
-            parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        return `<img ${parts.join(" ")}>`;
-    };
-    // Emit the schema-matching div[data-type="callout"] for a callout node. The
-    // schema reads the banner type from data-callout-type. Children are rendered
-    // as HTML so they survive inside a raw-HTML container.
-    const calloutToHtml = (node) => {
-        const type = (node.attrs?.type || "info").toLowerCase();
-        const inner = (node.content || []).map(blockToHtml).join("");
-        return `<div data-type="callout" data-callout-type="${escapeAttr(type)}">${inner}</div>`;
-    };
-    // Emit a schema-matching <details> tree. The schema parses <details>,
-    // summary[data-type="detailsSummary"], and div[data-type="detailsContent"].
-    const detailsToHtml = (node) => {
-        const inner = (node.content || []).map(blockToHtml).join("");
-        return `<details>${inner}</details>`;
-    };
-    const detailsSummaryToHtml = (node) => `<summary data-type="detailsSummary">${inlineToHtml(node.content || [])}</summary>`;
-    const detailsContentToHtml = (node) => {
-        const inner = (node.content || []).map(blockToHtml).join("");
-        return `<div data-type="detailsContent">${inner}</div>`;
-    };
-    // Emit the schema-matching taskList/taskItem HTML. bridgeTaskLists (in
-    // collaboration.ts) recognizes ul[data-type="taskList"] with
-    // li[data-type="taskItem"][data-checked]; emitting that directly here keeps
-    // task lists inside columns/cells from degrading to literal "- [ ]" text.
-    const taskListToHtml = (node) => {
-        const items = (node.content || [])
-            .map((it) => {
-            const checked = it.attrs?.checked ? "true" : "false";
-            return `<li data-type="taskItem" data-checked="${checked}">${blockChildrenToHtml(it)}</li>`;
-        })
-            .join("");
-        return `<ul data-type="taskList">${items}</ul>`;
-    };
-    // Render a block node to HTML for the raw-HTML containers (spanned tables,
-    // columns). marked does NOT re-parse markdown inside a raw-HTML block, so
-    // EVERY block type that can appear inside a column or a spanned cell must be
-    // emitted as schema-matching HTML here — never as markdown, or it would land
-    // as literal text on re-import. Nodes whose processNode case already produces
-    // schema-matching HTML (math/media/embed/attachment/nested columns/spanned
-    // table) are delegated to processNode; the markdown-emitting cases
-    // (image/blockquote/callout/details/hr/taskList) get explicit HTML here.
-    const blockToHtml = (block) => {
-        const children = block.content || [];
-        switch (block.type) {
-            case "paragraph":
-                return `<p>${inlineToHtml(children)}</p>`;
-            case "heading": {
-                const level = block.attrs?.level || 1;
-                return `<h${level}>${inlineToHtml(children)}</h${level}>`;
-            }
-            case "bulletList":
-                return `<ul>${children
-                    .map((li) => `<li>${blockChildrenToHtml(li)}</li>`)
-                    .join("")}</ul>`;
-            case "orderedList":
-                return `<ol>${children
-                    .map((li) => `<li>${blockChildrenToHtml(li)}</li>`)
-                    .join("")}</ol>`;
-            case "codeBlock": {
-                const lang = block.attrs?.language || "";
-                // The code itself is element TEXT content (between <code> tags), so it
-                // must escape < > & — NOT the attribute escaper. The language rides in
-                // a class ATTRIBUTE, so it uses escapeAttr.
-                const code = escapeHtmlText(children
-                    .map(processNode)
-                    .join("")
-                    .replace(/\n+$/, ""));
-                const cls = lang ? ` class="language-${escapeAttr(lang)}"` : "";
-                return `<pre><code${cls}>${code}</code></pre>`;
-            }
-            case "image":
-                return imageToHtml(block);
-            case "blockquote":
-                return `<blockquote>${children.map(blockToHtml).join("")}</blockquote>`;
-            case "horizontalRule":
-                return "<hr>";
-            case "callout":
-                return calloutToHtml(block);
-            case "details":
-                return detailsToHtml(block);
-            case "detailsSummary":
-                return detailsSummaryToHtml(block);
-            case "detailsContent":
-                return detailsContentToHtml(block);
-            case "taskList":
-                return taskListToHtml(block);
-            case "taskItem":
-                // A bare taskItem (outside a taskList) still needs a wrapping list so
-                // the schema parses it; wrap it in a single-item taskList.
-                return taskListToHtml({ content: [block] });
-            // table (incl. spanned), columns/column, math, media, embed, attachment,
-            // mention, etc. already emit schema-matching HTML from processNode.
-            case "table":
-            case "columns":
-            case "column":
-            case "mathBlock":
-            case "video":
-            case "audio":
-            case "pdf":
-            case "youtube":
-            case "embed":
-            case "attachment":
-            case "drawio":
-            case "excalidraw":
-                return processNode(block);
-            default:
-                // Any still-unhandled block type: NEVER fall back to markdown inside a
-                // raw-HTML block (it would become literal text). Wrap its rendered
-                // children in a <div> so their content is preserved; if it has no block
-                // children, render its inline content instead.
-                if (children.length && children.some((c) => c.type !== "text")) {
-                    return `<div>${children.map(blockToHtml).join("")}</div>`;
-                }
-                return `<div>${inlineToHtml(children)}</div>`;
-        }
-    };
-    // Render the block children of a list item to HTML (a listItem holds block+
-    // content). Mirrors processListItem but for the HTML fallback path.
-    const blockChildrenToHtml = (item) => (item.content || []).map((b) => blockToHtml(b)).join("");
-    // Indent the rendered children of a list item under a marker prefix.
-    // Each child block is a (possibly multi-line) string. The very first physical
-    // line of the first child carries the marker (e.g. "- " or "1. "); EVERY
-    // other line — the remaining lines of the first child AND all lines of every
-    // subsequent child (nested lists, code blocks, extra paragraphs) — is indented
-    // to align under the marker. Without indenting these continuation lines, the
-    // 2nd/3rd line of a nested child collapses to column 0 and escapes the list.
-    //
-    // The continuation indent MUST equal the LIST marker width, which is not the
-    // same as the visible prefix width:
-    //   - bullet "- "          -> 2 columns
-    //   - task   "- [ ] "      -> marker is still "- " (the "[ ] " is content), 2
-    //   - ordered "1. "/"10. " -> 3/4 columns, scaling with the number's digits
-    // CommonMark anchors nested content to the marker column, so an ordered item
-    // indented to only 2 columns would be re-parsed as a sibling/loose content on
-    // re-import. Callers therefore pass the exact indent width to use.
-    const indentItemChildren = (childStrings, prefix, indentWidth) => {
-        const indent = " ".repeat(indentWidth);
-        const lines = [];
-        childStrings.forEach((child, childIndex) => {
-            child.split("\n").forEach((line, lineIndex) => {
-                if (childIndex === 0 && lineIndex === 0) {
-                    // First physical line of the first block gets the marker.
-                    lines.push(`${prefix} ${line}`);
-                }
-                else {
-                    // Indent every continuation line by the marker width; keep blank
-                    // lines blank rather than emitting trailing whitespace.
-                    lines.push(line.length ? `${indent}${line}` : "");
-                }
-            });
-        });
-        return lines.join("\n");
-    };
-    const processListItem = (item, prefix) => {
-        const itemContent = item.content || [];
-        const childStrings = itemContent.map(processNode);
-        if (childStrings.length === 0)
-            return prefix;
-        // The rendered marker is `${prefix} ` (prefix + one space), so its width —
-        // and thus the continuation indent — is prefix.length + 1. This is correct
-        // for both bullet ("-" -> 2) and ordered ("1." -> 3, "10." -> 4) markers,
-        // since for those the visible prefix IS the list marker.
-        return indentItemChildren(childStrings, prefix, prefix.length + 1);
-    };
-    const processTaskItem = (item) => {
-        const checked = item.attrs?.checked || false;
-        const checkbox = checked ? "[x]" : "[ ]";
-        const prefix = `- ${checkbox}`;
-        const itemContent = item.content || [];
-        const childStrings = itemContent.map(processNode);
-        // An empty task item still needs its checkbox marker; without this guard
-        // the indent below produces "" and the "- [ ]"/"- [x]" row disappears.
-        if (childStrings.length === 0)
-            return prefix;
-        // The list marker for a task item is just "- " (2 columns); the "[ ] "/"[x] "
-        // checkbox is item content, NOT part of the marker. So the continuation
-        // indent is a fixed 2 — do NOT derive it from the wider prefix.length.
-        return indentItemChildren(childStrings, prefix, 2);
-    };
-    return processNode(content).trim();
-}
diff --git a/packages/mcp/build/lib/markdown-document.js b/packages/mcp/build/lib/markdown-document.js
deleted file mode 100644
index d21d9686..00000000
--- a/packages/mcp/build/lib/markdown-document.js
+++ /dev/null
@@ -1,104 +0,0 @@
-/**
- * Self-contained Docmost-flavoured Markdown document (custom extensions).
- *
- * A single `.md` file that packages everything needed to losslessly round-trip
- * a page through "download -> edit body -> re-upload":
- *   - a leading `docmost:meta` block: a one-line JSON object with page identity;
- *   - the Markdown body (carrying inline comment anchors and diagrams as HTML);
- *   - a trailing `docmost:comments` block: a one-line JSON array of comment
- *     threads.
- *
- * Both metadata blocks are HTML comments on purpose: `marked`/`generateJSON`
- * drop HTML comments, so even if the WHOLE file were ever fed straight to the
- * importer without first stripping the blocks, the metadata cannot leak into the
- * document. (A fenced ```docmost-comments``` block would WRONGLY become a
- * codeBlock node, so a fenced block is deliberately NOT used.)
- *
- * The delimiter literals may legitimately appear in the BODY too (e.g. a user
- * re-pastes an exported `.md` into a page, or a page documents this very
- * format). To stay robust, parsing treats only the FINAL, document-ending
- * `docmost:comments` block as metadata: it is the last `<!-- docmost:comments`
- * opener whose closing `-->` sits at the very end of the file. Any earlier
- * literal occurrence is left in the body untouched.
- *
- * NOTE on comments: in this version the comment THREAD records are preserved in
- * the file but are NOT pushed back to the server on import — only the inline
- * comment marks (anchors) embedded in the body are restored. Managing comment
- * records stays with the comment tools/UI.
- */
-// Match the leading meta block (allow leading whitespace). Capture group 1 is
-// the JSON text between the markers.
-const META_RE = /^\s*<!--\s*docmost:meta\s*\n([\s\S]*?)\n-->/;
-// Match a `docmost:comments` opener. Used globally to scan for the LAST opener
-// rather than end-anchoring a single regex (which would mis-capture across a
-// literal opener that appears earlier in the body).
-const COMMENTS_OPEN_RE = /<!--[ \t]*docmost:comments[ \t]*\r?\n/g;
-/**
- * Assemble the full self-contained markdown file: meta block, body, and the
- * comments block. The meta block is always emitted; the comments block is always
- * emitted too (with `[]` when there are no comments) so the format stays uniform
- * and parsing stays simple.
- */
-export function serializeDocmostMarkdown(meta, body, comments) {
-    const metaJson = JSON.stringify(meta);
-    const commentsJson = JSON.stringify(Array.isArray(comments) ? comments : []);
-    const trimmedBody = (body ?? "").trim();
-    return (`<!-- docmost:meta\n${metaJson}\n-->\n\n` +
-        `${trimmedBody}\n\n` +
-        `<!-- docmost:comments\n${commentsJson}\n-->\n`);
-}
-/**
- * Split a self-contained file back into its parts. Tolerant: if the meta or
- * comments block is missing (e.g. a hand-written plain-markdown file), the
- * corresponding value is returned as `null` and the whole input is treated as
- * the body. This never throws on a MISSING block; only a `JSON.parse` failure
- * inside a block that IS present is surfaced as a thrown Error with a clear
- * message. Robust to `\r\n` line endings.
- */
-export function parseDocmostMarkdown(full) {
-    // Normalize line endings so the anchored regexes work regardless of CRLF.
-    const normalized = (full ?? "").replace(/\r\n/g, "\n");
-    // Extract the leading meta block (start-anchored — already unambiguous).
-    let meta = null;
-    let metaEnd = 0;
-    const metaMatch = normalized.match(META_RE);
-    if (metaMatch) {
-        try {
-            meta = JSON.parse(metaMatch[1]);
-        }
-        catch (e) {
-            throw new Error(`Invalid docmost:meta JSON block: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // Body starts right after the matched meta block.
-        metaEnd = (metaMatch.index ?? 0) + metaMatch[0].length;
-    }
-    // Find the LAST `<!-- docmost:comments` opener; the real file-level block is
-    // the final one whose closing `-->` ends the document. Any earlier literal
-    // occurrence inside the body (e.g. a re-pasted export) is left in the body.
-    let lastOpenStart = -1;
-    let lastOpenEnd = -1;
-    let m;
-    COMMENTS_OPEN_RE.lastIndex = 0;
-    while ((m = COMMENTS_OPEN_RE.exec(normalized)) !== null) {
-        lastOpenStart = m.index;
-        lastOpenEnd = m.index + m[0].length;
-    }
-    let comments = null;
-    let bodyEnd = normalized.length;
-    if (lastOpenStart !== -1) {
-        const rest = normalized.slice(lastOpenEnd);
-        const close = rest.match(/\r?\n-->[ \t]*\r?\n?\s*$/); // closer must end the doc
-        if (close) {
-            const jsonText = rest.slice(0, close.index);
-            try {
-                comments = JSON.parse(jsonText);
-            }
-            catch (e) {
-                throw new Error(`Invalid docmost:comments JSON block: ${e instanceof Error ? e.message : String(e)}`);
-            }
-            bodyEnd = lastOpenStart; // strip from the opener to end of document
-        }
-    }
-    const body = normalized.slice(metaEnd, bodyEnd).trim();
-    return { meta, body, comments };
-}
diff --git a/packages/mcp/build/lib/node-ops.js b/packages/mcp/build/lib/node-ops.js
deleted file mode 100644
index 7f8490ca..00000000
--- a/packages/mcp/build/lib/node-ops.js
+++ /dev/null
@@ -1,821 +0,0 @@
-/**
- * Pure, network-free helpers for manipulating a ProseMirror/TipTap document
- * tree by node id.
- *
- * A ProseMirror node here is a plain JSON object of the shape produced by
- * Docmost: `{ type, attrs?, content?, text?, marks? }`. Children live in the
- * `content` array; a node carries a stable id in `attrs.id`. Callouts and
- * table cells hold their children in `content` just like any other block, so a
- * single recursive walk reaches them all.
- *
- * Every exported function operates on a DEEP CLONE of the input document and
- * returns the new document. The input doc and any `newNode`/`node` argument are
- * never mutated. All functions are defensively null-safe: missing/!Array
- * `content`, non-object nodes, and absent `attrs` are tolerated.
- */
-import { stripInlineMarkdown } from "./text-normalize.js";
-/** Deep-clone a JSON-serializable value without mutating the original. */
-function clone(value) {
-    if (typeof structuredClone === "function") {
-        return structuredClone(value);
-    }
-    // Fallback for environments without structuredClone.
-    return JSON.parse(JSON.stringify(value));
-}
-/** True if `value` is a non-null object (and not an array). */
-function isObject(value) {
-    return value != null && typeof value === "object" && !Array.isArray(value);
-}
-/** True if `node` carries the given id in `node.attrs.id`. */
-function matchesId(node, nodeId) {
-    return isObject(node) && isObject(node.attrs) && node.attrs.id === nodeId;
-}
-/**
- * Recursively concatenate all text contained in a node.
- *
- * Text nodes contribute their `text` string; container nodes contribute the
- * joined `blockPlainText` of their `content` children. Returns "" for nullish
- * or non-object inputs.
- */
-export function blockPlainText(node) {
-    if (!isObject(node))
-        return "";
-    let out = "";
-    if (typeof node.text === "string") {
-        out += node.text;
-    }
-    if (Array.isArray(node.content)) {
-        for (const child of node.content) {
-            out += blockPlainText(child);
-        }
-    }
-    return out;
-}
-/** Truncate `text` to at most `n` chars, appending an ellipsis when cut. */
-function truncate(text, n) {
-    return text.length > n ? text.slice(0, n) + "…" : text;
-}
-/**
- * Build a COMPACT outline of the TOP-LEVEL blocks of `doc` (the entries in
- * `doc.content`). Deliberately does NOT recurse into paragraphs, list items, or
- * table cells — compactness is the point; use `getNodeByRef` to drill into a
- * specific block.
- *
- * Each entry carries `{ index, type, id, firstText }`, plus type-specific
- * extras: headings add `level`; tables add `rows`/`cols` and the first row's
- * cell texts as `header`; list blocks (types ending in "List") add `items`.
- * `firstText` is the block's plain text truncated to 100 chars. Null-safe:
- * a missing or non-object doc/content yields `[]`.
- */
-export function buildOutline(doc) {
-    if (!isObject(doc) || !Array.isArray(doc.content))
-        return [];
-    const out = [];
-    for (let i = 0; i < doc.content.length; i++) {
-        const block = doc.content[i];
-        const type = isObject(block) ? block.type : undefined;
-        const entry = {
-            index: i,
-            type,
-            id: isObject(block) && isObject(block.attrs)
-                ? (block.attrs.id ?? null)
-                : null,
-            firstText: truncate(blockPlainText(block), 100),
-        };
-        if (type === "heading") {
-            entry.level = isObject(block.attrs) ? (block.attrs.level ?? null) : null;
-        }
-        else if (type === "table") {
-            const headerRow = block.content?.[0]?.content ?? [];
-            entry.rows = block.content?.length ?? 0;
-            entry.cols = block.content?.[0]?.content?.length ?? 0;
-            entry.header = headerRow.map((cell) => truncate(blockPlainText(cell), 40));
-        }
-        else if (typeof type === "string" && type.endsWith("List")) {
-            entry.items = block.content?.length ?? 0;
-        }
-        out.push(entry);
-    }
-    return out;
-}
-/**
- * Resolve a single node by reference and return `{ node, path, type }`, or
- * `null` when nothing matches.
- *
- * - `ref` of the form `#<n>` (e.g. `#2`) selects the TOP-LEVEL block at index
- *   `n` in `doc.content`. This is the only way to address table/tableRow/
- *   tableCell nodes, which carry no `attrs.id`.
- * - Otherwise `ref` is treated as a block id: the FIRST node anywhere in the
- *   tree with `attrs.id === ref` is returned.
- *
- * `path` is the array of child indices from the doc root down to the node
- * (so a top-level block is `[index]`). The returned `node` is a DEEP CLONE,
- * so callers can mutate it without touching the input doc. Null-safe.
- */
-export function getNodeByRef(doc, ref) {
-    if (!isObject(doc))
-        return null;
-    // "#<n>": index into the top-level content array.
-    const indexMatch = typeof ref === "string" ? ref.match(/^#(\d+)$/) : null;
-    if (indexMatch) {
-        const index = Number(indexMatch[1]);
-        const block = Array.isArray(doc.content) ? doc.content[index] : undefined;
-        if (!isObject(block))
-            return null;
-        return { node: clone(block), path: [index], type: block.type };
-    }
-    // Otherwise: depth-first search for the first node with attrs.id === ref.
-    const search = (node, trail) => {
-        if (!isObject(node))
-            return null;
-        if (Array.isArray(node.content)) {
-            for (let i = 0; i < node.content.length; i++) {
-                const child = node.content[i];
-                const path = [...trail, i];
-                if (matchesId(child, ref)) {
-                    return { node: clone(child), path, type: child.type };
-                }
-                const hit = search(child, path);
-                if (hit != null)
-                    return hit;
-            }
-        }
-        return null;
-    };
-    return search(doc, []);
-}
-/**
- * Replace EVERY node whose `attrs.id === nodeId` with a deep clone of
- * `newNode`, anywhere in the tree (including inside callouts and table cells).
- *
- * Operates on a clone of `doc`; returns `{ doc, replaced }` where `replaced`
- * is the number of nodes substituted. A fresh clone of `newNode` is used for
- * each match so they do not share references.
- */
-export function replaceNodeById(doc, nodeId, newNode) {
-    const out = clone(doc);
-    let replaced = 0;
-    // Walk a content array, replacing direct matches and recursing into the
-    // (possibly new) children of non-matching nodes.
-    const walkContent = (content) => {
-        for (let i = 0; i < content.length; i++) {
-            const child = content[i];
-            if (matchesId(child, nodeId)) {
-                content[i] = clone(newNode);
-                replaced++;
-                // Do not recurse into a freshly substituted node.
-                continue;
-            }
-            if (isObject(child) && Array.isArray(child.content)) {
-                walkContent(child.content);
-            }
-        }
-    };
-    if (isObject(out) && Array.isArray(out.content)) {
-        walkContent(out.content);
-    }
-    return { doc: out, replaced };
-}
-/**
- * Remove EVERY node whose `attrs.id === nodeId` from its parent `content`
- * array, anywhere in the tree (recursive, including callouts and tables).
- *
- * Operates on a clone of `doc`; returns `{ doc, deleted }` where `deleted` is
- * the number of nodes removed.
- */
-export function deleteNodeById(doc, nodeId) {
-    const out = clone(doc);
-    let deleted = 0;
-    // Filter a content array in place, dropping matches and recursing into the
-    // surviving children.
-    const walkContent = (content) => {
-        const kept = [];
-        for (const child of content) {
-            if (matchesId(child, nodeId)) {
-                deleted++;
-                continue;
-            }
-            if (isObject(child) && Array.isArray(child.content)) {
-                child.content = walkContent(child.content);
-            }
-            kept.push(child);
-        }
-        return kept;
-    };
-    if (isObject(out) && Array.isArray(out.content)) {
-        out.content = walkContent(out.content);
-    }
-    return { doc: out, deleted };
-}
-/**
- * Throw a clear, model-actionable error when a node-id write op did NOT match
- * exactly one node (#159). `count === 0` -> "no node found"; `count > 1` ->
- * "ambiguous, refused" — Docmost duplicates block ids on copy/paste, so a write
- * by id could clobber/remove EVERY duplicate. The caller skips the write for any
- * `count !== 1` (the transform returns null), so this only REPORTS; nothing was
- * changed. No-op for the unambiguous single-match case.
- */
-export function assertUnambiguousMatch(op, verb, count, nodeId, pageId) {
-    if (count === 0) {
-        throw new Error(`${op}: no node with id "${nodeId}" found on page ${pageId}`);
-    }
-    if (count > 1) {
-        throw new Error(`${op}: id "${nodeId}" is ambiguous — ${count} nodes on page ${pageId} share it (block ids are duplicated on copy/paste). Refusing to ${verb} all of them; nothing was changed. Re-target with a more specific anchor.`);
-    }
-}
-/**
- * Deep-clone `doc` and strip every node/mark attribute whose value is strictly
- * `undefined`, so the result is safe to hand to Yjs (which throws an opaque
- * "Unexpected content type" when asked to store an `undefined` attribute value).
- *
- * Only `undefined` keys are removed; `null`, `false`, `0`, and `""` are all
- * legitimate JSON-storable values and are preserved. Operates on a clone and
- * returns it; the input is never mutated. Defensively null-safe like the rest
- * of the file.
- */
-export function sanitizeForYjs(doc) {
-    const out = clone(doc);
-    // Drop every key whose value is strictly `undefined` from an attrs object.
-    const stripUndefined = (attrs) => {
-        if (!isObject(attrs))
-            return;
-        for (const key of Object.keys(attrs)) {
-            if (attrs[key] === undefined) {
-                delete attrs[key];
-            }
-        }
-    };
-    const walk = (node) => {
-        if (!isObject(node))
-            return;
-        stripUndefined(node.attrs);
-        if (Array.isArray(node.marks)) {
-            for (const mark of node.marks) {
-                if (isObject(mark))
-                    stripUndefined(mark.attrs);
-            }
-        }
-        if (Array.isArray(node.content)) {
-            for (const child of node.content) {
-                walk(child);
-            }
-        }
-    };
-    walk(out);
-    return out;
-}
-/**
- * Diagnostics helper: walk the tree and return a human-readable path string for
- * the FIRST attribute value (in any `node.attrs` or `mark.attrs`) that Yjs
- * cannot store — i.e. `undefined`, a `function`, a `symbol`, or a `bigint`
- * (e.g. `content[3].content[0].attrs.indent (undefined)`). Returns `null` when
- * every attribute is storable. Null-safe.
- */
-export function findUnstorableAttr(doc) {
-    const isUnstorable = (value) => {
-        if (value === undefined)
-            return "undefined";
-        const t = typeof value;
-        if (t === "function")
-            return "function";
-        if (t === "symbol")
-            return "symbol";
-        if (t === "bigint")
-            return "bigint";
-        return null;
-    };
-    // Check an attrs object; return the offending sub-path or null.
-    const checkAttrs = (attrs, basePath) => {
-        if (!isObject(attrs))
-            return null;
-        for (const key of Object.keys(attrs)) {
-            const kind = isUnstorable(attrs[key]);
-            if (kind != null)
-                return `${basePath}.${key} (${kind})`;
-        }
-        return null;
-    };
-    const walk = (node, path) => {
-        if (!isObject(node))
-            return null;
-        const attrHit = checkAttrs(node.attrs, `${path}.attrs`);
-        if (attrHit != null)
-            return attrHit;
-        if (Array.isArray(node.marks)) {
-            for (let i = 0; i < node.marks.length; i++) {
-                const markHit = checkAttrs(node.marks[i]?.attrs, `${path}.marks[${i}].attrs`);
-                if (markHit != null)
-                    return markHit;
-            }
-        }
-        if (Array.isArray(node.content)) {
-            for (let i = 0; i < node.content.length; i++) {
-                const childHit = walk(node.content[i], `${path}.content[${i}]`);
-                if (childHit != null)
-                    return childHit;
-            }
-        }
-        return null;
-    };
-    // The root doc node carries no useful index, so start the path at "doc".
-    if (!isObject(doc))
-        return null;
-    const attrHit = checkAttrs(doc.attrs, "attrs");
-    if (attrHit != null)
-        return attrHit;
-    if (Array.isArray(doc.content)) {
-        for (let i = 0; i < doc.content.length; i++) {
-            const childHit = walk(doc.content[i], `content[${i}]`);
-            if (childHit != null)
-                return childHit;
-        }
-    }
-    return null;
-}
-/**
- * Table structural node types and the container each must live directly inside.
- * Used by `insertNodeRelative` to splice rows/cells into the correct ancestor
- * rather than blindly into the anchor's direct parent (which would corrupt the
- * table's nesting).
- */
-const STRUCTURAL_TYPES = new Set(["tableRow", "tableCell", "tableHeader"]);
-const REQUIRED_CONTAINER = {
-    tableRow: "table",
-    tableCell: "tableRow",
-    tableHeader: "tableRow",
-};
-/**
- * Find the index of the first TOP-LEVEL block whose plain text includes the
- * anchor, with a markdown-stripping FALLBACK. Returns -1 when none matches.
- *
- * Two passes preserve "exact wins globally":
- *  - Pass 1: first block containing the verbatim `anchorText`.
- *  - Pass 2 (only if pass 1 found nothing): first block containing the
- *    markdown-stripped anchor, when stripping actually changed it.
- */
-function findAnchorTextIndex(content, anchorText) {
-    if (!Array.isArray(content))
-        return -1;
-    // Pass 1: exact.
-    for (let i = 0; i < content.length; i++) {
-        if (blockPlainText(content[i]).includes(anchorText))
-            return i;
-    }
-    // Pass 2: markdown-stripped fallback.
-    const a = stripInlineMarkdown(anchorText);
-    if (a !== anchorText && a.length > 0) {
-        for (let i = 0; i < content.length; i++) {
-            if (blockPlainText(content[i]).includes(a))
-                return i;
-        }
-    }
-    return -1;
-}
-/**
- * Locate an anchor and return its ancestor chain (from `doc` down to and
- * including the matched node). Each chain entry is `{ node, index }` where
- * `index` is the node's position inside its parent's `content` array (the root
- * doc has index -1). Returns `null` when the anchor cannot be resolved.
- */
-function findAnchorChain(doc, opts) {
-    if (!isObject(doc))
-        return null;
-    // DFS by id anywhere in the tree, accumulating the path.
-    if (opts.anchorNodeId != null) {
-        const targetId = opts.anchorNodeId;
-        const search = (node, index, trail) => {
-            if (!isObject(node))
-                return null;
-            const here = [...trail, { node, index }];
-            if (matchesId(node, targetId))
-                return here;
-            if (Array.isArray(node.content)) {
-                for (let i = 0; i < node.content.length; i++) {
-                    const hit = search(node.content[i], i, here);
-                    if (hit != null)
-                        return hit;
-                }
-            }
-            return null;
-        };
-        return search(doc, -1, []);
-    }
-    // By text: only top-level blocks are scanned (same rule as the JSON path).
-    // Exact match wins; a markdown-stripped fallback is tried only on a miss.
-    if (opts.anchorText != null && Array.isArray(doc.content)) {
-        const i = findAnchorTextIndex(doc.content, opts.anchorText);
-        if (i !== -1) {
-            return [
-                { node: doc, index: -1 },
-                { node: doc.content[i], index: i },
-            ];
-        }
-    }
-    return null;
-}
-/**
- * Insert a deep clone of `node` relative to an anchor.
- *
- * - position "append": push the node onto the top-level `doc.content`.
- * - position "before"/"after": locate the anchor and splice the node into the
- *   anchor's parent `content` array immediately before / after it.
- *
- * Anchor resolution for before/after:
- *   - if `anchorNodeId` is given, find the node with `attrs.id === anchorNodeId`
- *     anywhere in the tree (recursive);
- *   - otherwise, if `anchorText` is given, scan only TOP-LEVEL `doc.content`
- *     blocks and pick the first whose `blockPlainText` includes `anchorText`.
- *
- * Operates on a clone of `doc`; returns `{ doc, inserted }`. `inserted` is
- * false when the anchor could not be resolved (the doc is returned unchanged
- * apart from being cloned).
- */
-export function insertNodeRelative(doc, node, opts) {
-    const out = clone(doc);
-    const fresh = clone(node);
-    // Defensive: stay null-safe like the other exports — a missing opts means
-    // there is nothing actionable to do.
-    if (!isObject(opts))
-        return { doc: out, inserted: false };
-    const isStructural = isObject(node) && STRUCTURAL_TYPES.has(node.type);
-    // "append": top-level push.
-    if (opts.position === "append") {
-        // Structural table nodes (tableRow/tableCell/tableHeader) cannot live at the
-        // top level — appending one would produce invalid nesting.
-        if (isStructural) {
-            throw new Error(`insert_node: cannot append a ${node.type} at the top level; use ` +
-                `position before/after with an anchor inside the target table`);
-        }
-        if (isObject(out)) {
-            if (!Array.isArray(out.content))
-                out.content = [];
-            out.content.push(fresh);
-            return { doc: out, inserted: true };
-        }
-        return { doc: out, inserted: false };
-    }
-    const offset = opts.position === "after" ? 1 : 0;
-    // Structural insert (before/after a tableRow/tableCell/tableHeader): splice
-    // into the nearest enclosing table/tableRow rather than the anchor's direct
-    // parent, so the row/cell lands at the correct level of the table.
-    if (isStructural) {
-        const containerType = REQUIRED_CONTAINER[node.type];
-        const chain = findAnchorChain(out, opts);
-        // Anchor not resolved at all — keep the existing "anchor not found" path.
-        if (chain == null)
-            return { doc: out, inserted: false };
-        // Find the DEEPEST ancestor (including the anchor itself) of the required
-        // container type.
-        let containerIdx = -1;
-        for (let i = chain.length - 1; i >= 0; i--) {
-            if (isObject(chain[i].node) && chain[i].node.type === containerType) {
-                containerIdx = i;
-                break;
-            }
-        }
-        if (containerIdx === -1) {
-            throw new Error(`insert_node: cannot insert a ${node.type} here — the anchor is not ` +
-                `inside a ${containerType}. Anchor on a cell's text or a block id ` +
-                `that lives inside the target table.`);
-        }
-        const container = chain[containerIdx].node;
-        if (!Array.isArray(container.content))
-            container.content = [];
-        if (containerIdx === chain.length - 1) {
-            // The matched container IS the anchor node itself (e.g. anchorText
-            // resolved to the table block): append/prepend within it.
-            const at = opts.position === "after" ? container.content.length : 0;
-            container.content.splice(at, 0, fresh);
-        }
-        else {
-            // The immediate child on the path leading to the anchor is the row/cell
-            // to splice next to.
-            const enclosingChildIndex = chain[containerIdx + 1].index;
-            container.content.splice(enclosingChildIndex + offset, 0, fresh);
-        }
-        return { doc: out, inserted: true };
-    }
-    // Resolve by id anywhere in the tree: splice into the parent content array.
-    if (opts.anchorNodeId != null) {
-        let inserted = false;
-        const walkContent = (content) => {
-            for (let i = 0; i < content.length; i++) {
-                const child = content[i];
-                if (matchesId(child, opts.anchorNodeId)) {
-                    content.splice(i + offset, 0, fresh);
-                    inserted = true;
-                    return;
-                }
-                if (isObject(child) && Array.isArray(child.content)) {
-                    walkContent(child.content);
-                    if (inserted)
-                        return;
-                }
-            }
-        };
-        if (isObject(out) && Array.isArray(out.content)) {
-            walkContent(out.content);
-        }
-        return { doc: out, inserted };
-    }
-    // Resolve by text: only top-level doc.content blocks are scanned. Exact
-    // match wins; a markdown-stripped fallback is tried only on a miss.
-    if (opts.anchorText != null && isObject(out) && Array.isArray(out.content)) {
-        const i = findAnchorTextIndex(out.content, opts.anchorText);
-        if (i !== -1) {
-            out.content.splice(i + offset, 0, fresh);
-            return { doc: out, inserted: true };
-        }
-    }
-    return { doc: out, inserted: false };
-}
-// ===========================================================================
-// Table editing helpers
-//
-// A Docmost table is a ProseMirror subtree with NO ids on the structural nodes:
-//   table   -> { type:"table",     content:[tableRow...] }
-//   row     -> { type:"tableRow",  content:[tableCell|tableHeader...] }
-//   cell    -> { type:"tableCell"|"tableHeader", attrs:{colspan,rowspan,colwidth},
-//                content:[paragraph...] }
-//   para    -> { type:"paragraph", attrs:{id,indent}, content:[textNode...] }
-// Only paragraphs/headings carry an `attrs.id`, so a cell is addressed via the
-// id of the paragraph inside it. The helpers below all operate on a DEEP CLONE
-// of the input doc (via `clone`) and never mutate their inputs.
-// ===========================================================================
-/**
- * Collect EVERY `attrs.id` present anywhere in `node` into `used`. Used to seed
- * `makeFreshId` so generated paragraph ids never collide with existing ones.
- */
-function collectIds(node, used) {
-    if (!isObject(node))
-        return;
-    if (isObject(node.attrs) && typeof node.attrs.id === "string") {
-        used.add(node.attrs.id);
-    }
-    if (Array.isArray(node.content)) {
-        for (const child of node.content)
-            collectIds(child, used);
-    }
-}
-/**
- * Fresh-id generator: returns a random Docmost-style id (12 chars from
- * lowercase `a-z0-9`) that is not already in `used`, and records it. On the
- * rare collision the id is regenerated. Callers rely on uniqueness, not on the
- * exact string, so randomness is fine — and unlike a module-local counter it
- * needs no reset and cannot become predictable across calls.
- */
-function makeFreshId(used) {
-    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
-    let id;
-    do {
-        id = "";
-        for (let i = 0; i < 12; i++) {
-            id += alphabet[Math.floor(Math.random() * alphabet.length)];
-        }
-    } while (used.has(id) || id === "");
-    used.add(id);
-    return id;
-}
-/**
- * Resolve a table reference against an ALREADY-CLONED doc and return the LIVE
- * table node (a reference inside `rootClone`, so the caller may mutate it) plus
- * its index path. Returns null when no table matches.
- *
- * - `#<n>`: the top-level block at index `n`, only if its `type === "table"`.
- * - otherwise: DFS for the node with `attrs.id === tableRef`, then walk UP its
- *   ancestor chain to the nearest `type === "table"` ancestor.
- */
-function locateTable(rootClone, tableRef) {
-    if (!isObject(rootClone))
-        return null;
-    // "#<n>": index into the top-level content array; must be a table.
-    const indexMatch = typeof tableRef === "string" ? tableRef.match(/^#(\d+)$/) : null;
-    if (indexMatch) {
-        const index = Number(indexMatch[1]);
-        const block = Array.isArray(rootClone.content)
-            ? rootClone.content[index]
-            : undefined;
-        if (isObject(block) && block.type === "table") {
-            return { table: block, path: [index] };
-        }
-        return null;
-    }
-    // Otherwise: DFS for attrs.id === tableRef, tracking the ancestor chain, then
-    // climb to the nearest enclosing table.
-    const search = (node, trail) => {
-        if (!isObject(node))
-            return null;
-        if (Array.isArray(node.content)) {
-            for (let i = 0; i < node.content.length; i++) {
-                const child = node.content[i];
-                const here = [...trail, { node: child, index: i }];
-                if (matchesId(child, tableRef)) {
-                    // Walk UP to the nearest table ancestor (including the match itself).
-                    for (let j = here.length - 1; j >= 0; j--) {
-                        if (isObject(here[j].node) && here[j].node.type === "table") {
-                            return {
-                                table: here[j].node,
-                                path: here.slice(0, j + 1).map((e) => e.index),
-                            };
-                        }
-                    }
-                    return null; // id found but no enclosing table
-                }
-                const hit = search(child, here);
-                if (hit != null)
-                    return hit;
-            }
-        }
-        return null;
-    };
-    return search(rootClone, []);
-}
-/** Build the plain-text → single-paragraph cell content used by all writers. */
-function makeCellParagraph(id, text) {
-    return {
-        type: "paragraph",
-        attrs: { id, indent: 0 },
-        // Empty string → a paragraph with an empty content array.
-        content: text ? [{ type: "text", text }] : [],
-    };
-}
-/**
- * Read a table as a matrix. Returns null when `tableRef` resolves to no table.
- *
- * - `rows`/`cols`: the table's row count and the column count of its FIRST row.
- *   Tables may be ragged (rows of differing length), so `cols` reflects only
- *   row 0; use the per-row length of `cells`/`cellIds` for each row's actual
- *   width.
- * - `cells`: `string[][]` of each cell's `blockPlainText`.
- * - `cellIds`: `(string|null)[][]` of each cell's FIRST paragraph id (or null),
- *   so callers can `patch_node` a cell for rich-formatted edits.
- * - `path`: index path of the table within the doc.
- */
-export function readTable(doc, tableRef) {
-    const root = clone(doc);
-    const located = locateTable(root, tableRef);
-    if (located == null)
-        return null;
-    const { table, path } = located;
-    const rowNodes = Array.isArray(table.content) ? table.content : [];
-    const rows = rowNodes.length;
-    const cols = rowNodes[0]?.content?.length ?? 0;
-    const cells = [];
-    const cellIds = [];
-    for (const rowNode of rowNodes) {
-        const cellNodes = Array.isArray(rowNode?.content) ? rowNode.content : [];
-        const rowText = [];
-        const rowIds = [];
-        for (const cellNode of cellNodes) {
-            rowText.push(blockPlainText(cellNode));
-            // The cell's first paragraph carries the id used for patch_node.
-            const firstPara = Array.isArray(cellNode?.content)
-                ? cellNode.content[0]
-                : undefined;
-            const id = isObject(firstPara) && isObject(firstPara.attrs)
-                ? (firstPara.attrs.id ?? null)
-                : null;
-            rowIds.push(id);
-        }
-        cells.push(rowText);
-        cellIds.push(rowIds);
-    }
-    return { rows, cols, cells, cellIds, path };
-}
-/**
- * Insert a row of plain-text cells into a table. Returns `{ doc, inserted }`.
- *
- * The row is padded to the table's column count (`cells[i] ?? ""`); supplying
- * MORE cells than columns throws. Each new cell copies `colwidth` for its
- * column from the header row when present, gets a fresh-id paragraph, and a
- * `colspan:1, rowspan:1` attrs. `index` (when an integer in `[0, rows]`) splices
- * the row there; otherwise the row is appended at the end.
- */
-export function insertTableRow(doc, tableRef, cells, index) {
-    const out = clone(doc);
-    const located = locateTable(out, tableRef);
-    if (located == null)
-        return { doc: out, inserted: false };
-    const { table } = located;
-    if (!Array.isArray(table.content))
-        table.content = [];
-    const rows = table.content.length;
-    const headerRow = table.content[0];
-    const headerCells = Array.isArray(headerRow?.content)
-        ? headerRow.content
-        : [];
-    // Column count is the WIDEST existing row, so the guard below stays
-    // meaningful for ragged tables and the new row matches the table's width.
-    // Fall back to the supplied cell count only when the table has no rows.
-    let colCount = 0;
-    for (const r of table.content) {
-        if (isObject(r) && Array.isArray(r.content))
-            colCount = Math.max(colCount, r.content.length);
-    }
-    if (colCount === 0)
-        colCount = Array.isArray(cells) ? cells.length : 0;
-    if (Array.isArray(cells) && cells.length > colCount) {
-        throw new Error(`table_insert_row: got ${cells.length} cell(s) but the table has ${colCount} column(s)`);
-    }
-    // Resolve the landing index up front so the cell-type decision and the splice
-    // below agree: a valid integer in [0, rows] splices there, else we append.
-    const landingIndex = typeof index === "number" &&
-        Number.isInteger(index) &&
-        index >= 0 &&
-        index <= rows
-        ? index
-        : rows;
-    // Seed the id generator with every id already in the doc so the new cell
-    // paragraph ids are unique within the whole document.
-    const used = new Set();
-    collectIds(out, used);
-    const newCells = [];
-    for (let i = 0; i < colCount; i++) {
-        const text = (Array.isArray(cells) ? cells[i] : undefined) ?? "";
-        const attrs = { colspan: 1, rowspan: 1 };
-        // Copy this column's colwidth from the header row's cell when present.
-        const colwidth = headerCells[i]?.attrs?.colwidth;
-        if (colwidth !== undefined)
-            attrs.colwidth = colwidth;
-        // A row landing at index 0 becomes the new header row, so inherit the
-        // current header cell's type per column (Docmost uses "tableHeader" there);
-        // every other position is a plain data cell.
-        const cellType = landingIndex === 0 ? (headerCells[i]?.type ?? "tableCell") : "tableCell";
-        newCells.push({
-            type: cellType,
-            attrs,
-            content: [makeCellParagraph(makeFreshId(used), text)],
-        });
-    }
-    const newRow = { type: "tableRow", content: newCells };
-    // Splice at the resolved landing index (append when index was omitted/invalid).
-    table.content.splice(landingIndex, 0, newRow);
-    return { doc: out, inserted: true };
-}
-/**
- * Delete the row at 0-based `index` from a table. Returns `{ doc, deleted }`.
- * `deleted` is false only when the table cannot be located. Throws on an
- * out-of-range index, and refuses to delete the table's only row.
- */
-export function deleteTableRow(doc, tableRef, index) {
-    const out = clone(doc);
-    const located = locateTable(out, tableRef);
-    if (located == null)
-        return { doc: out, deleted: false };
-    const { table } = located;
-    if (!Array.isArray(table.content))
-        table.content = [];
-    const rows = table.content.length;
-    if (!Number.isInteger(index) || index < 0 || index >= rows) {
-        throw new Error(`table_delete_row: row index ${index} out of range (table has ${rows} row(s))`);
-    }
-    if (rows <= 1) {
-        throw new Error("table_delete_row: refusing to delete the only row of the table");
-    }
-    table.content.splice(index, 1);
-    return { doc: out, deleted: true };
-}
-/**
- * Set the plain-text content of cell `[row, col]` (0-based) to `text`. Returns
- * `{ doc, updated }`; `updated` is false only when the table cannot be located.
- * Throws when `row`/`col` is out of range. The cell's own attrs (colspan/
- * rowspan/colwidth) are preserved; its content becomes a single text paragraph
- * that reuses the cell's existing first-paragraph id when present, else a fresh
- * one.
- */
-export function updateTableCell(doc, tableRef, row, col, text) {
-    const out = clone(doc);
-    const located = locateTable(out, tableRef);
-    if (located == null)
-        return { doc: out, updated: false };
-    const { table } = located;
-    const rowNodes = Array.isArray(table.content) ? table.content : [];
-    const rows = rowNodes.length;
-    const rowNode = rowNodes[row];
-    const cols = isObject(rowNode) && Array.isArray(rowNode.content)
-        ? rowNode.content.length
-        : 0;
-    if (!Number.isInteger(row) ||
-        row < 0 ||
-        row >= rows ||
-        !Number.isInteger(col) ||
-        col < 0 ||
-        col >= cols) {
-        throw new Error(`table_update_cell: cell [${row},${col}] out of range`);
-    }
-    const cellNode = rowNode.content[col];
-    // Reuse the cell's existing first-paragraph id, or mint a fresh unique one.
-    const existingPara = Array.isArray(cellNode?.content)
-        ? cellNode.content[0]
-        : undefined;
-    let id = isObject(existingPara) && isObject(existingPara.attrs)
-        ? existingPara.attrs.id
-        : undefined;
-    if (typeof id !== "string" || id.length === 0) {
-        const used = new Set();
-        collectIds(out, used);
-        id = makeFreshId(used);
-    }
-    cellNode.content = [makeCellParagraph(id, text)];
-    return { doc: out, updated: true };
-}
diff --git a/packages/mcp/build/lib/page-lock.js b/packages/mcp/build/lib/page-lock.js
deleted file mode 100644
index ddba2663..00000000
--- a/packages/mcp/build/lib/page-lock.js
+++ /dev/null
@@ -1,31 +0,0 @@
-/**
- * Per-page async mutex.
- *
- * Content writes over the collaboration websocket must never overlap for the
- * same page: two concurrent full-document replaces would race on the live Yjs
- * fragment. We serialize them with a per-pageId promise chain — each new
- * operation waits for the previous one on that page to settle (success or
- * failure) before it runs. Different pages never block each other.
- */
-const chains = new Map();
-// The returned promise carries the real result/rejection of `fn` and MUST be
-// awaited/handled by the caller; only the internal chaining tail swallows
-// errors (purely to gate ordering).
-export function withPageLock(pageId, fn) {
-    // Wait for the previous op on this page; swallow its error so a failure does
-    // not poison the queue for the next caller.
-    const prev = (chains.get(pageId) ?? Promise.resolve()).catch(() => { });
-    const run = prev.then(fn);
-    // The tail used for chaining must also swallow errors (it only gates order).
-    const tail = run.catch(() => { });
-    chains.set(pageId, tail);
-    // Drop the map entry once this op is the tail and has settled, to avoid an
-    // unbounded map of resolved promises.
-    tail.then(() => {
-        if (chains.get(pageId) === tail) {
-            chains.delete(pageId);
-        }
-    });
-    // Callers get the real result/rejection of fn.
-    return run;
-}
diff --git a/packages/mcp/build/lib/parse-node-arg.js b/packages/mcp/build/lib/parse-node-arg.js
deleted file mode 100644
index 4598b136..00000000
--- a/packages/mcp/build/lib/parse-node-arg.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// The model sometimes serializes a ProseMirror node arg as a JSON string
-// instead of an object. Normalize: parse a string to an object (throwing on
-// invalid JSON), pass an object through unchanged. Shared by patch_node /
-// insert_node (and the analogous update_page_json content parsing).
-export function parseNodeArg(node, errMsg = "node was a string but not valid JSON") {
-    if (typeof node === "string") {
-        try {
-            return JSON.parse(node);
-        }
-        catch {
-            throw new Error(errMsg);
-        }
-    }
-    return node;
-}
diff --git a/packages/mcp/build/lib/text-normalize.js b/packages/mcp/build/lib/text-normalize.js
deleted file mode 100644
index 4db72e4b..00000000
--- a/packages/mcp/build/lib/text-normalize.js
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * Locator normalization: strip inline markdown wrappers and trailing
- * decoration from a LOCATOR string so a find/anchor that the model wrote with
- * markdown (or a stray emoji) can still match the document's plain text.
- *
- * This is used ONLY as a fallback for LOCATING (after an exact match fails);
- * it is never applied to replacement text or inserted node content, so no
- * formatting is ever lost.
- */
-/** Maximum unwrap passes, so pathological/nested input cannot loop forever. */
-const MAX_PASSES = 8;
-/**
- * Inline emphasis/code/strikethrough wrappers, strong BEFORE emphasis so
- * `**x**` collapses to `x` rather than leaving a stray `*x*`. Each pattern is
- * non-greedy and capture group 1 is the inner text. Applied repeatedly until
- * the string stops changing (nested wrappers like `**_x_**`).
- */
-const WRAPPER_PATTERNS = [
-    /\*\*([^*]+?)\*\*/g, // **x**
-    /__([^_]+?)__/g, // __x__
-    /~~([^~]+?)~~/g, // ~~x~~
-    /\*([^*]+?)\*/g, // *x*
-    /_([^_]+?)_/g, // _x_
-    /``([^`]+?)``/g, // ``x``
-    /`([^`]+?)`/g, // `x`
-];
-/** Links/images -> their visible text. `!?` covers both `[t](u)` and `![a](s)`. */
-const LINK_IMAGE_RE = /!?\[([^\]]*)\]\([^)]*\)/g;
-/**
- * Apply ONLY the two balanced/link passes shared by both normalizers: first
- * collapse links/images to their visible text, then collapse balanced inline
- * wrappers repeatedly until stable. Does NOT trim decoration, does NOT guard
- * against an empty result — it returns exactly the transformed string.
- */
-function stripWrappersAndLinks(s) {
-    // 1. Links/images -> their visible text.
-    let out = s.replace(LINK_IMAGE_RE, "$1");
-    // 2. Strip balanced wrappers, repeating until the string is stable so nested
-    //    wrappers (`**_x_**`) and adjacent runs both collapse.
-    for (let pass = 0; pass < MAX_PASSES; pass++) {
-        const before = out;
-        for (const re of WRAPPER_PATTERNS) {
-            out = out.replace(re, "$1");
-        }
-        if (out === before)
-            break;
-    }
-    return out;
-}
-/**
- * STRICT formatting detector — distinct from the lenient locator
- * normalization below. It strips ONLY what unambiguously is markdown markup:
- *  1. links/images `[text](url)` -> `text`, `![alt](src)` -> `alt`, and
- *  2. balanced inline `**`/`__`/`~~`/`*`/`_`/`` ` `` wrappers (repeat-until-stable),
- * and DELIBERATELY does NOT trim leading/trailing whitespace, emoji, or lone
- * marker chars (the lenient extras `stripInlineMarkdown` does in its step 3).
- *
- * It exists ONLY to recognize formatting-vs-plain INTENT in `applyTextEdits`
- * (deciding whether find/replace differ purely by markdown markers). Because it
- * skips the lenient trimming, ordinary plain-text edits are NOT misread as
- * formatting: a trailing-space trim, snake_case (`my_var_name`), math (`2 * 3`),
- * and identifiers/URLs with underscores all stay untouched here (their `_x_` /
- * `*x*` runs are only collapsed when actually balanced, and even then they are
- * compared symmetrically, so plain text never collapses to a different string).
- *
- * Do NOT use this for LOCATING — the locator fallback must keep using the
- * lenient `stripInlineMarkdown` (it trims stray decoration so a find still
- * matches the document's plain text).
- */
-export function stripBalancedWrappers(s) {
-    if (typeof s !== "string" || s.length === 0)
-        return s;
-    return stripWrappersAndLinks(s);
-}
-/**
- * Conservatively strip inline markdown from a locator string.
- *
- * Deterministic, order-fixed steps:
- *  1. Links/images: `[text](url)` -> `text`, `![alt](src)` -> `alt`.
- *  2. Balanced inline wrappers (strong before emphasis, code, strikethrough),
- *     applied repeatedly until stable for nested cases.
- *  3. Trim leading/trailing decoration only: whitespace, leftover marker chars
- *     (`* _ ~ \``) and emoji. Letters/digits and sentence punctuation (`.`/`,`
- *     etc.) are NEVER trimmed.
- *
- * If the result is empty (e.g. the input was only markers like `***`), the
- * ORIGINAL string is returned so a locator can never normalize down to "" and
- * match everything.
- */
-export function stripInlineMarkdown(s) {
-    if (typeof s !== "string" || s.length === 0)
-        return s;
-    // 1 + 2. Shared link/image and balanced-wrapper passes.
-    let out = stripWrappersAndLinks(s);
-    // 3. Trim leading/trailing decoration: whitespace, leftover markdown markers,
-    //    and emoji (Extended_Pictographic plus the VS16 / ZWJ joiners, plus the
-    //    regional-indicator range U+1F1E6–U+1F1FF for flag emoji, which are NOT
-    //    Extended_Pictographic). The `u` flag enables the Unicode property escape.
-    //    Anchored runs only — interior text and sentence punctuation are untouched.
-    const DECORATION = "[\\s*_~\\x60\\p{Extended_Pictographic}\\u{1F1E6}-\\u{1F1FF}\\u{FE0F}\\u{200D}]+";
-    out = out
-        .replace(new RegExp("^" + DECORATION, "u"), "")
-        .replace(new RegExp(DECORATION + "$", "u"), "");
-    // 4. Never normalize a locator down to nothing.
-    if (out.length === 0)
-        return s;
-    return out;
-}
diff --git a/packages/mcp/build/lib/transforms.js b/packages/mcp/build/lib/transforms.js
deleted file mode 100644
index c1b822ba..00000000
--- a/packages/mcp/build/lib/transforms.js
+++ /dev/null
@@ -1,631 +0,0 @@
-/**
- * Pure, network-free transform primitives for a ProseMirror/TipTap document
- * tree, plus one higher-level orchestration (commentsToFootnotes).
- *
- * A ProseMirror node here is a plain JSON object of the shape produced by
- * Docmost: `{ type, attrs?, content?, text?, marks? }`. Children live in the
- * `content` array; callouts, tables, lists all hold their children in
- * `content`, so a single recursive walk reaches them all.
- *
- * Conventions (matching node-ops.ts):
- *  - functions that produce a new document deep-clone their input and return a
- *    `{ doc, ... }` object; the caller's objects are never mutated.
- *  - functions are defensively null-safe.
- *  - `marks` arrays are preserved verbatim when fragments are split/reordered.
- */
-import { blockPlainText } from "./node-ops.js";
-import { canonicalizeFootnotes } from "./footnote-canonicalize.js";
-import { footnoteContentKey, makeFootnoteDefinition, generateFootnoteId, } from "./footnote-authoring.js";
-export { canonicalizeFootnotes } from "./footnote-canonicalize.js";
-/** Deep-clone a JSON-serializable value without mutating the original. */
-function clone(value) {
-    if (typeof structuredClone === "function") {
-        return structuredClone(value);
-    }
-    // Fallback for environments without structuredClone.
-    return JSON.parse(JSON.stringify(value));
-}
-/** True if `value` is a non-null object (and not an array). */
-function isObject(value) {
-    return value != null && typeof value === "object" && !Array.isArray(value);
-}
-/**
- * Plain text of a node (re-export of node-ops' blockPlainText so transform
- * authors have a single import surface). Recurses through nested content.
- */
-export function blockText(node) {
-    return blockPlainText(node);
-}
-/**
- * Depth-first visit of every node in the tree, including the root and the
- * nested content of callouts, tables, lists, etc. `fn` is called once per node.
- * Null-safe: a nullish or non-object node is ignored.
- */
-export function walk(node, fn) {
-    if (!isObject(node))
-        return;
-    fn(node);
-    if (Array.isArray(node.content)) {
-        for (const child of node.content) {
-            walk(child, fn);
-        }
-    }
-}
-/**
- * Find the FIRST node (depth-first) matching `predicate`, anywhere in the tree.
- * Works even when the node carries no `attrs.id` (it searches the raw tree, not
- * an id index). Returns the live node reference inside `doc` (NOT a clone), or
- * null when nothing matches. Typical use: `getList(doc, n => n.type ===
- * "orderedList")`.
- */
-export function getList(doc, predicate) {
-    let found = null;
-    walk(doc, (node) => {
-        if (found == null && predicate(node)) {
-            found = node;
-        }
-    });
-    return found;
-}
-/**
- * Textblocks that hold raw text but do NOT accept inline atom nodes. A
- * `footnoteReference` is `group:"inline", atom:true`; `codeBlock` is
- * `content:"text*"` (text only), so splicing a footnoteReference into it yields
- * an invalid document. (paragraph/heading/detailsSummary are `inline*` and DO
- * accept it; footnote definitions live inside a footnotesList which the
- * footnote inserter excludes via `beforeBlock`.)
- */
-const INLINE_ATOM_FORBIDDEN_BLOCKS = new Set(["codeBlock"]);
-/**
- * Footnote-notes subtrees the inline footnote inserter must never split into (at
- * any depth): a `footnotesList` and the `footnoteDefinition`s it holds. Anchoring
- * a reference inside one of these would later be dropped as an orphan by the
- * canonicalizer, taking the existing definition's text with it.
- */
-const FOOTNOTE_NOTES_SUBTREES = new Set([
-    "footnotesList",
-    "footnoteDefinition",
-]);
-/** True if `node` IS, or contains at any depth, a footnotesList/footnoteDefinition. */
-function containsFootnoteNotes(node) {
-    if (!isObject(node))
-        return false;
-    if (FOOTNOTE_NOTES_SUBTREES.has(node.type))
-        return true;
-    if (Array.isArray(node.content)) {
-        return node.content.some((c) => containsFootnoteNotes(c));
-    }
-    return false;
-}
-/**
- * Insert `marker` as a PLAIN (unmarked) text run right after the first
- * occurrence of `anchor`.
- *
- * The text run that contains the END of the anchor is SPLIT at the anchor end,
- * so all existing marks (links, bold, ...) on the surrounding text are
- * preserved, while the inserted marker run carries NO marks. The marker is
- * inserted as a leading-space-padded run (`" " + marker`) so it visually
- * separates from the preceding word.
- *
- * The anchor is matched against the concatenated plain text of each top-level
- * block (so an anchor that spans several text/mark runs still matches). The
- * insertion happens inside the inline content array that holds the anchor's
- * final character.
- *
- * Operates on a clone of `doc`; returns `{ doc, inserted }`. `inserted` is
- * false when the anchor text was not found in any in-scope block.
- */
-export function insertMarkerAfter(doc, anchor, marker, opts = {}) {
-    // A plain marker is a leading-space-padded unmarked text run.
-    return insertNodesAfterAnchor(doc, anchor, () => [{ type: "text", text: " " + marker }], opts);
-}
-/**
- * Mark-safe insertion CORE: split the inline text run that holds the END of
- * `anchor` (preserving the surrounding marks) and splice the nodes produced by
- * `makeMiddle()` in at the split point. `insertMarkerAfter` (plain text marker)
- * and `insertInlineFootnote` (a `footnoteReference` node) are both thin callers —
- * the only difference is WHAT is inserted (a space-padded text run vs. a node
- * that should hug the preceding word), which is exactly what `makeMiddle`
- * decides. Operates on a clone; returns `{ doc, inserted }`.
- */
-function insertNodesAfterAnchor(doc, anchor, makeMiddle, opts = {}) {
-    const out = clone(doc);
-    if (!isObject(out) || !Array.isArray(out.content) || !anchor) {
-        return { doc: out, inserted: false };
-    }
-    const limit = typeof opts.beforeBlock === "number"
-        ? Math.min(opts.beforeBlock, out.content.length)
-        : out.content.length;
-    for (let b = 0; b < limit; b++) {
-        const block = out.content[b];
-        if (!isObject(block))
-            continue;
-        // Quick reject: skip blocks whose plain text cannot contain the anchor.
-        if (!blockPlainText(block).includes(anchor))
-            continue;
-        // Walk the inline content arrays inside this block, tracking a running
-        // character offset so we can locate the inline array + text run that holds
-        // the END of the anchor's first occurrence.
-        let inserted = false;
-        let offset = 0; // characters of plain text seen so far in this block
-        const anchorEnd = (() => blockPlainText(block).indexOf(anchor) + anchor.length)();
-        // Recurse into inline-bearing containers (paragraph, heading, table cell,
-        // callout child paragraphs, ...). We only split inside an array of inline
-        // nodes (text/inline atoms); the FIRST array whose cumulative range covers
-        // anchorEnd receives the split + marker.
-        const visit = (container) => {
-            if (inserted || !isObject(container) || !Array.isArray(container.content)) {
-                return;
-            }
-            // Skip a forbidden subtree entirely (e.g. footnotesList/footnoteDefinition):
-            // never split into it, but keep `offset` aligned for any sibling text after
-            // it within this block.
-            if (opts.skipSubtreeTypes && opts.skipSubtreeTypes.has(container.type)) {
-                offset += blockPlainText(container).length;
-                return;
-            }
-            const inline = container.content;
-            // Detect whether this array is an inline array (contains text nodes).
-            const hasText = inline.some((n) => isObject(n) && n.type === "text");
-            if (hasText) {
-                // Refuse a textblock whose content spec cannot hold the inserted nodes
-                // (e.g. a codeBlock for an inline atom). Keep `offset` aligned for any
-                // sibling textblocks in this same block, then bail so the search falls
-                // through to the next candidate block.
-                if (opts.forbidBlockTypes && opts.forbidBlockTypes.has(container.type)) {
-                    offset += blockPlainText(container).length;
-                    return;
-                }
-                for (let i = 0; i < inline.length; i++) {
-                    const n = inline[i];
-                    const len = isObject(n) ? blockPlainText(n).length : 0;
-                    const runStart = offset;
-                    const runEnd = offset + len;
-                    // The run that contains the anchor end (anchorEnd lands inside this
-                    // run, i.e. runStart < anchorEnd <= runEnd) is the split point.
-                    if (!inserted &&
-                        isObject(n) &&
-                        n.type === "text" &&
-                        typeof n.text === "string" &&
-                        anchorEnd > runStart &&
-                        anchorEnd <= runEnd) {
-                        const cut = anchorEnd - runStart; // split index within this text run
-                        const before = n.text.slice(0, cut);
-                        const after = n.text.slice(cut);
-                        const marks = Array.isArray(n.marks) ? n.marks : [];
-                        const parts = [];
-                        if (before.length > 0) {
-                            parts.push({ ...n, text: before, marks: [...marks] });
-                        }
-                        // The inserted nodes are caller-decided (a space-padded marker run,
-                        // or a node that hugs the word). They carry no copied marks.
-                        parts.push(...makeMiddle());
-                        if (after.length > 0) {
-                            parts.push({ ...n, text: after, marks: [...marks] });
-                        }
-                        inline.splice(i, 1, ...parts);
-                        inserted = true;
-                        return;
-                    }
-                    offset = runEnd;
-                }
-            }
-            else {
-                // Not an inline array: recurse into children (e.g. callout -> paragraph).
-                for (const child of inline) {
-                    visit(child);
-                    if (inserted)
-                        return;
-                }
-            }
-        };
-        visit(block);
-        if (inserted) {
-            return { doc: out, inserted: true };
-        }
-        // If the block matched in plain text but we could not split (e.g. anchor
-        // lands inside an atom), fall through to the next block rather than failing.
-    }
-    return { doc: out, inserted: false };
-}
-/**
- * In the disclaimer callout, replace a `[1]…[K]` range marker with `[1]…[n]`.
- *
- * Docmost translations use a callout that states the footnote range, e.g.
- * "[1]…[5]". When the number of notes changes, this rewrites the trailing
- * number of any `[1]…[K]` (or `[1]...[K]`, ASCII ellipsis) occurrence found in a
- * callout's text nodes to `[1]…[n]`. Operates on a clone; returns
- * `{ doc, changed }` where `changed` is the number of text nodes rewritten.
- */
-export function setCalloutRange(doc, n) {
-    const out = clone(doc);
-    let changed = 0;
-    // Match "[1]" + (… or ...) + "[<digits>]"; rewrite the last number to n.
-    const rangeRe = /(\[1\]\s*(?:…|\.\.\.)\s*\[)\d+(\])/g;
-    walk(out, (node) => {
-        if (node.type === "callout") {
-            walk(node, (inner) => {
-                if (inner.type === "text" &&
-                    typeof inner.text === "string" &&
-                    rangeRe.test(inner.text)) {
-                    rangeRe.lastIndex = 0;
-                    inner.text = inner.text.replace(rangeRe, `$1${n}$2`);
-                    changed++;
-                }
-                rangeRe.lastIndex = 0;
-            });
-        }
-    });
-    return { doc: out, changed };
-}
-/**
- * Generate a short random id for a new block's `attrs.id`. Docmost uses nanoid;
- * a base36 random string is sufficient here (uniqueness within one document).
- */
-function freshId() {
-    return (Math.random().toString(36).slice(2, 12) +
-        Math.random().toString(36).slice(2, 6));
-}
-/**
- * Wrap inline ProseMirror nodes in a list item:
- *   { type:"listItem", content:[{ type:"paragraph", attrs:{id}, content: inlineNodes }] }
- * with a fresh random block id on the paragraph. The inline nodes are cloned so
- * the result shares no references with the caller's input.
- */
-export function noteItem(inlineNodes) {
-    const content = Array.isArray(inlineNodes) ? clone(inlineNodes) : [];
-    return {
-        type: "listItem",
-        content: [
-            {
-                type: "paragraph",
-                attrs: { id: freshId() },
-                content,
-            },
-        ],
-    };
-}
-/**
- * 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).
- *
- * Built on the shared `makeFootnoteDefinition` factory (footnote-authoring.ts);
- * the only extra is a fresh block id on the inner paragraph (Docmost stamps one,
- * and the canonicalizer preserves attrs as-is). Single factory, one place to
- * change the definition shape.
- */
-export function footnoteDefinition(id, inlineNodes) {
-    const node = makeFootnoteDefinition(id, inlineNodes);
-    node.content[0].attrs = { id: freshId() };
-    return node;
-}
-/**
- * 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.
- *
- * A leading `комментарий: ` (case-insensitive) or `N. ` numeric prefix is
- * stripped first. Then a minimal bold-split is applied: a leading
- * `**bold lead**` run becomes a text node with a bold mark, and the remainder
- * becomes a plain text node. This keeps the conversion synchronous (the
- * transform sandbox runs synchronously) and dependency-free; the existing
- * async markdownToProseMirror is intentionally NOT used here.
- */
-export function mdToInlineNodes(markdown) {
-    let md = typeof markdown === "string" ? markdown : "";
-    // Strip a leading "комментарий: " prefix (case-insensitive) or a "N. " prefix.
-    md = md.replace(/^\s*комментарий\s*:\s*/i, "");
-    md = md.replace(/^\s*\d+\.\s+/, "");
-    md = md.trim();
-    if (md === "")
-        return [];
-    const nodes = [];
-    // Leading bold lead: **...** at the very start.
-    const leadMatch = /^\*\*([^*]+)\*\*\s*/.exec(md);
-    if (leadMatch) {
-        const leadText = leadMatch[1];
-        nodes.push({
-            type: "text",
-            text: leadText,
-            marks: [{ type: "bold" }],
-        });
-        const rest = md.slice(leadMatch[0].length);
-        if (rest.length > 0) {
-            // Preserve the separating space that followed the bold lead.
-            const sep = /^\*\*[^*]+\*\*(\s*)/.exec(md);
-            const spacing = sep ? sep[1] : "";
-            nodes.push({ type: "text", text: spacing + rest });
-        }
-        return nodes;
-    }
-    // No bold lead: emit the whole thing as a single plain text node, with any
-    // remaining **bold** spans split out inline.
-    return splitInlineBold(md);
-}
-/**
- * Split a string with inline `**bold**` spans into text nodes, bolding the
- * spans. Used as the no-lead fallback in mdToInlineNodes.
- */
-function splitInlineBold(text) {
-    const nodes = [];
-    const re = /\*\*([^*]+)\*\*/g;
-    let last = 0;
-    let m;
-    while ((m = re.exec(text)) !== null) {
-        if (m.index > last) {
-            nodes.push({ type: "text", text: text.slice(last, m.index) });
-        }
-        nodes.push({ type: "text", text: m[1], marks: [{ type: "bold" }] });
-        last = m.index + m[0].length;
-    }
-    if (last < text.length) {
-        nodes.push({ type: "text", text: text.slice(last) });
-    }
-    return nodes.length > 0 ? nodes : [{ type: "text", text }];
-}
-/**
- * Turn inline comments into numbered footnotes.
- *
- * For each inline comment that carries a `selection`:
- *   1. insert a placeholder marker (a NUL-delimited "\u0000FN<i>\u0000"
- *      sentinel) right after the selection text in the BODY (before the
- *      notes heading);
- *   2. build a note list item from the comment's markdown content.
- *
- * Then RENUMBER every footnote marker in the body by reading order: existing
- * `[N]` markers and the new "\u0000FN<i>\u0000" placeholders are both replaced by a
- * sequential `[seq]`, and the notes orderedList is reordered so each note lines
- * up with its marker's reading-order position. Finally the disclaimer callout
- * range is synced to the new note count.
- *
- * Returns `{ doc, consumed }` where `consumed` lists the ids of comments that
- * were successfully anchored (their selection was found and a placeholder
- * inserted). Operates on a clone of `doc`.
- */
-export function commentsToFootnotes(doc, comments, opts = {}) {
-    let working = clone(doc);
-    const notesHeading = opts.notesHeading ?? "Примечания переводчика";
-    const top = Array.isArray(working.content) ? working.content : [];
-    const notesIdx = top.findIndex((n) => isObject(n) && n.type === "heading" && blockText(n).trim() === notesHeading);
-    if (notesIdx < 0) {
-        throw new Error(`heading "${notesHeading}" not found`);
-    }
-    // The notes orderedList lives at or after the heading.
-    const notesList = top
-        .slice(notesIdx)
-        .find((n) => isObject(n) && n.type === "orderedList");
-    if (!notesList) {
-        throw new Error("notes orderedList not found");
-    }
-    const consumed = [];
-    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 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`.
-        const r = insertMarkerAfter(working, c.selection.trimEnd(), ph, {
-            beforeBlock: notesIdx,
-        });
-        if (!r.inserted)
-            return;
-        working = r.doc;
-        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 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");
-    }
-    // Inline content of each existing note (listItem -> paragraph -> inline).
-    const oldNoteInline = (Array.isArray(notesList2.content)
-        ? notesList2.content
-        : []).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+(\])/;
-    // 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;
-        }
-        visitInlineArrays(top2[i]);
-    }
-    // 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 };
-}
-/**
- * AUTHOR-INLINE footnote insertion. The caller supplies WHERE (anchorText) and
- * WHAT (markdown text); numbering and the bottom list are derived server-side by
- * `canonicalizeFootnotes`. The caller never sees or edits `footnotesList`, never
- * assigns a number, and cannot desync — orphans / out-of-order lists / raw
- * `[^id]` markdown are structurally impossible.
- *
- * Content DEDUP (#3 in the issue): if an existing definition has the SAME
- * normalized content key, its id is REUSED (the new reference points at it: one
- * number, one definition, several references). Otherwise a fresh uuid id is
- * minted and a new definition added. Conservative — only an exact content match
- * merges.
- *
- * Mechanics: the `footnoteReference` node is inserted DIRECTLY at the anchor via
- * the same mark-safe split as `insertMarkerAfter` (the shared
- * `insertNodesAfterAnchor` core), so it hugs the preceding word with no text
- * sentinel round-trip. The whole document is then canonicalized.
- *
- * Operates on a clone of `doc`. When the anchor is not found, returns the input
- * unchanged with `inserted:false`.
- */
-export function insertInlineFootnote(doc, opts) {
-    const inline = mdToInlineNodes(opts.text ?? "");
-    // footnoteContentKey only reads `.content`, so key off the inline array
-    // directly instead of building a throwaway definition node.
-    const key = footnoteContentKey({ content: inline });
-    // Content dedup: reuse an existing definition's id when its key matches.
-    let footnoteId = null;
-    let reused = false;
-    if (key !== "") {
-        walk(doc, (n) => {
-            if (footnoteId == null &&
-                isObject(n) &&
-                n.type === "footnoteDefinition" &&
-                n.attrs &&
-                typeof n.attrs.id === "string" &&
-                n.attrs.id !== "" &&
-                footnoteContentKey(n) === key) {
-                footnoteId = n.attrs.id;
-                reused = true;
-            }
-        });
-    }
-    if (footnoteId == null)
-        footnoteId = generateFootnoteId();
-    // Insert the footnoteReference node directly after the anchor (mark-safe
-    // split); it hugs the preceding word with no leading space. Two guards keep the
-    // inline atom out of the notes section and out of blocks that cannot hold it:
-    //  - beforeBlock bounds the search to the BODY, before the first top-level block
-    //    that IS or CONTAINS (at any depth) a footnotesList/footnoteDefinition — so
-    //    a NESTED list or a bare definition also bounds the search, not just a
-    //    top-level list;
-    //  - skipSubtreeTypes refuses to descend into any footnotesList/footnoteDefinition
-    //    subtree, so a reference is never glued inside an existing definition (which
-    //    the canonicalizer would then drop as an orphan, losing that definition's
-    //    prose); and forbidBlockTypes refuses codeBlocks (an inline atom there is a
-    //    schema-invalid doc; insert_footnote skips validateDocStructure).
-    // When the only anchor match is in such a place, the insert is refused and the
-    // write aborts cleanly (inserted:false) instead of destroying content.
-    const boundaryIdx = Array.isArray(doc?.content)
-        ? doc.content.findIndex((n) => containsFootnoteNotes(n))
-        : -1;
-    const r = insertNodesAfterAnchor(doc, (opts.anchorText ?? "").trimEnd(), () => [{ type: "footnoteReference", attrs: { id: footnoteId } }], {
-        ...(boundaryIdx >= 0 ? { beforeBlock: boundaryIdx } : {}),
-        forbidBlockTypes: INLINE_ATOM_FORBIDDEN_BLOCKS,
-        skipSubtreeTypes: FOOTNOTE_NOTES_SUBTREES,
-    });
-    if (!r.inserted) {
-        return { doc: clone(doc), inserted: false, footnoteId, reused };
-    }
-    let working = r.doc;
-    // Add a NEW definition (canonicalize will order/place it); a reused id needs
-    // no new definition (the existing one is shared).
-    if (!reused) {
-        appendDefinition(working, makeFootnoteDefinition(footnoteId, inline));
-    }
-    // Derive numbering + the single bottom list deterministically.
-    working = canonicalizeFootnotes(working);
-    return { doc: working, inserted: true, footnoteId, reused };
-}
-/**
- * Append a definition node so the canonicalizer can order/place it: into the
- * first existing footnotesList, or a new trailing list when none exists.
- */
-function appendDefinition(doc, defNode) {
-    const existingList = getList(doc, (n) => isObject(n) && n.type === "footnotesList");
-    if (existingList && Array.isArray(existingList.content)) {
-        existingList.content.push(defNode);
-        return;
-    }
-    if (Array.isArray(doc.content)) {
-        doc.content.push({ type: "footnotesList", content: [defNode] });
-    }
-}
diff --git a/packages/mcp/build/lib/tree.js b/packages/mcp/build/lib/tree.js
deleted file mode 100644
index dd8cb39e..00000000
--- a/packages/mcp/build/lib/tree.js
+++ /dev/null
@@ -1,89 +0,0 @@
-/**
- * Pure tree-builder: turn a flat array of sidebar-style page nodes (as produced
- * by `enumerateSpacePages`) into a nested tree.
- *
- * Input: a flat array of nodes. Each node is expected to carry at least
- *   { id, slugId, title, position, parentPageId } (extra fields are ignored).
- *
- * Output: an array of ROOT nodes, each shaped as
- *   { id, slugId, title, children? }
- * where `children` is the array of child nodes (same shape, recursively). The
- * `children` key is OMITTED entirely when a node has no children — consistent
- * with how `filterPage` omits an empty `subpages` array — to keep the payload
- * lean (nesting alone conveys the structure; parentPageId/position/hasChildren
- * are intentionally dropped from the output).
- *
- * Linking rule: a node is attached as a child of `parentPageId` only when that
- * parent id is actually present in the input. Otherwise — including a null /
- * undefined `parentPageId`, or a parent that was capped out of the bounded walk
- * — the node is promoted to a ROOT. So "orphan whose parent is missing" is the
- * defined behavior: it surfaces at the top level rather than disappearing.
- *
- * Ordering rule: the roots array and every `children` array are sorted ascending
- * by the node's `position` string. The comparator is a plain code-unit (byte)
- * comparison — NOT localeCompare — because the server orders sidebar pages by
- * `collate "C"` (byte order), which a raw `<`/`>` compare approximates for the
- * fractional-index ASCII keys (e.g. "a0", "a1"). Nodes with a missing/undefined
- * `position` sort last.
- *
- * Pure: no I/O, no network, deterministic.
- */
-export function buildPageTree(nodes) {
-    // Map id -> output node. Build the lean output shape up front.
-    const byId = new Map();
-    // Preserve the original position string for sorting (kept off the output).
-    const positionById = new Map();
-    for (const node of nodes) {
-        if (!node || typeof node !== "object" || !node.id)
-            continue;
-        // Defensive against duplicate ids: last one wins (overwrites the earlier
-        // entry). `enumerateSpacePages` already dedups, so this is belt-and-braces.
-        byId.set(node.id, {
-            id: node.id,
-            slugId: node.slugId,
-            title: node.title,
-        });
-        positionById.set(node.id, node.position);
-    }
-    // Stable comparator on the position string: code-unit order, missing last.
-    const byPosition = (aId, bId) => {
-        const a = positionById.get(aId);
-        const b = positionById.get(bId);
-        if (a === undefined || a === null)
-            return b === undefined || b === null ? 0 : 1;
-        if (b === undefined || b === null)
-            return -1;
-        if (a < b)
-            return -1;
-        if (a > b)
-            return 1;
-        return 0;
-    };
-    const roots = [];
-    const childrenIdsByParent = new Map();
-    for (const node of nodes) {
-        if (!node || typeof node !== "object" || !node.id)
-            continue;
-        const parentId = node.parentPageId;
-        // Child only when the parent is actually present in the input; otherwise
-        // (null/undefined parent, or parent capped out of the walk) -> root.
-        if (parentId && byId.has(parentId)) {
-            const list = childrenIdsByParent.get(parentId) ?? [];
-            list.push(node.id);
-            childrenIdsByParent.set(parentId, list);
-        }
-        else {
-            roots.push(node.id);
-        }
-    }
-    // Attach sorted children arrays to each parent, omitting empty ones.
-    for (const [parentId, childIds] of childrenIdsByParent) {
-        const parent = byId.get(parentId);
-        if (!parent)
-            continue;
-        childIds.sort(byPosition);
-        parent.children = childIds.map((id) => byId.get(id));
-    }
-    roots.sort(byPosition);
-    return roots.map((id) => byId.get(id));
-}
diff --git a/packages/mcp/build/stdio.js b/packages/mcp/build/stdio.js
deleted file mode 100755
index 55f9eccb..00000000
--- a/packages/mcp/build/stdio.js
+++ /dev/null
@@ -1,40 +0,0 @@
-#!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createDocmostMcpServer } from "./index.js";
-// Standalone stdio entrypoint. This restores the original behavior of the
-// package when run as a CLI (`docmost-mcp`): it reads credentials from the
-// environment and serves the MCP protocol over stdin/stdout. The factory in
-// index.ts stays side-effect-free; all the process/transport lifecycle lives
-// here.
-const API_URL = process.env.DOCMOST_API_URL;
-const EMAIL = process.env.DOCMOST_EMAIL;
-const PASSWORD = process.env.DOCMOST_PASSWORD;
-if (!API_URL || !EMAIL || !PASSWORD) {
-    console.error("Error: DOCMOST_API_URL, DOCMOST_EMAIL, and DOCMOST_PASSWORD environment variables are required.");
-    process.exit(1);
-}
-async function run() {
-    // Global safety nets so a stray rejection/exception cannot silently kill
-    // the stdio server. Per-tool errors still flow through the SDK and are not
-    // affected by these handlers; these only catch errors raised OUTSIDE a tool
-    // call (e.g. a transient ws/collab socket "error" event). Such errors must
-    // NOT tear down the whole stdio server, so we log only and keep running.
-    // Genuine startup failures are still fatal via run().catch(...) below.
-    process.on("unhandledRejection", (reason) => {
-        console.error("Unhandled promise rejection:", reason);
-    });
-    process.on("uncaughtException", (error) => {
-        console.error("Uncaught exception:", error);
-    });
-    const server = createDocmostMcpServer({
-        apiUrl: API_URL,
-        email: EMAIL,
-        password: PASSWORD,
-    });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-run().catch((error) => {
-    console.error("Fatal error running server:", error);
-    process.exit(1);
-});
diff --git a/packages/mcp/build/tool-specs.js b/packages/mcp/build/tool-specs.js
deleted file mode 100644
index f73d1d15..00000000
--- a/packages/mcp/build/tool-specs.js
+++ /dev/null
@@ -1,322 +0,0 @@
-// Zod-agnostic shared tool-spec registry consumed by BOTH the zod-v3 MCP server
-// (packages/mcp/src/index.ts) and the zod-v4 in-app AI-SDK service
-// (apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts). Intentionally
-// imports NO zod: each consumer passes its OWN zod namespace into buildShape,
-// because the two packages are on different zod majors (v3 here, v4 in the
-// server) and a zod schema object built with one major cannot be reused by the
-// other. The builders below only touch z.string()/.min()/.optional()/.describe(),
-// z.array() and z.object() — API identical across v3 and v4 — so a single
-// builder works with either namespace.
-//
-// Only tools whose snake_case/camelCase name, input schema AND model-facing
-// description are genuinely identical across both layers live here. Tools that
-// diverge on purpose (security guardrails, tuned UX, "Reversible" framing on
-// some write tools, different limits, hybrid-RRF search, etc.) stay defined
-// per-layer and are NOT represented here.
-//
-// MAINTENANCE RULE: adding, renaming, or removing a spec here (or an inline
-// registerTool in index.ts) REQUIRES updating SERVER_INSTRUCTIONS in
-// packages/mcp/src/index.ts — the intent-routing guide MCP clients receive on
-// initialize. Enforced by test/unit/server-instructions.test.mjs.
-export const SHARED_TOOL_SPECS = {
-    // --- no-argument read tools ---
-    getWorkspace: {
-        mcpName: 'get_workspace',
-        inAppKey: 'getWorkspace',
-        description: 'Fetch metadata about the current workspace (name, settings).',
-    },
-    listSpaces: {
-        mcpName: 'list_spaces',
-        inAppKey: 'listSpaces',
-        description: 'List the spaces the current user can access. Returns the array of ' +
-            'spaces (id, name, slug, ...).',
-    },
-    listShares: {
-        mcpName: 'list_shares',
-        inAppKey: 'listShares',
-        description: 'List all public shares in the workspace with page titles and public URLs.',
-    },
-    // --- single-pageId read tools ---
-    getPageJson: {
-        mcpName: 'get_page_json',
-        inAppKey: 'getPageJson',
-        description: 'Get page details with the raw ProseMirror JSON content (lossless: ' +
-            'includes block ids, callouts, tables, link/image attributes) plus the ' +
-            'slugId used in URLs. Use the block ids it returns to make precise ' +
-            'structural edits or surgical text edits without resending the page.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-        }),
-    },
-    getOutline: {
-        mcpName: 'get_outline',
-        inAppKey: 'getOutline',
-        description: "Return a COMPACT outline of a page's top-level blocks ({index, type, " +
-            'id, level, firstText}; tables add rows/cols/header; lists add item ' +
-            'count) WITHOUT the full document body. Use it to locate sections/tables ' +
-            'and grab block ids cheaply before fetching, patching or inserting ' +
-            'individual blocks.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-        }),
-    },
-    // --- two-id read tool ---
-    getNode: {
-        mcpName: 'get_node',
-        inAppKey: 'getNode',
-        description: "Fetch a single node's full ProseMirror subtree (lossless) without " +
-            'pulling the whole document. `nodeId` is a block id from the page ' +
-            'outline or page-JSON view (works for headings/paragraphs/callouts/images), OR ' +
-            '`#<index>` to fetch a top-level block by its outline index — use the ' +
-            '`#<index>` form for tables/rows/cells, which carry no id.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            nodeId: z.string().min(1),
-        }),
-    },
-    // --- node delete ---
-    deleteNode: {
-        mcpName: 'delete_node',
-        inAppKey: 'deleteNode',
-        description: 'Remove a single block by its attrs.id (from the page outline or ' +
-            'page-JSON view) WITHOUT resending the whole document.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            nodeId: z.string().min(1),
-        }),
-    },
-    // --- single-block structural write (patch / insert) ---
-    //
-    // CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
-    // the whole document" + "cheaper/safer than a full-document replace" guidance
-    // AND the in-app copy's "keeps the same node id" + "Reversible via page
-    // history" framing — nothing either side conveyed is dropped. Sibling tools are
-    // named in transport-neutral prose ("the page-JSON view", "a full-document
-    // replace") to match the rest of the registry, since the two layers expose
-    // those siblings under different (snake_case vs camelCase) identifiers.
-    patchNode: {
-        mcpName: 'patch_node',
-        inAppKey: 'patchNode',
-        description: 'Replace a single content block identified by its attrs.id with a new ' +
-            'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
-            'keeps the same node id. Get the block id from the page outline (cheap) ' +
-            'or the page-JSON view, then ' +
-            'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
-            'replacing the whole document for one-block structural edits. Reversible: ' +
-            'the previous version is kept in page history.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1).describe('ID of the page containing the block'),
-            nodeId: z
-                .string()
-                .min(1)
-                .describe('attrs.id of the block to replace (from the page outline or ' +
-                'page-JSON view)'),
-            node: z
-                .any()
-                .describe('ProseMirror node to put in place of the node with this id, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.'),
-        }),
-    },
-    insertNode: {
-        mcpName: 'insert_node',
-        inAppKey: 'insertNode',
-        description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
-            'or append it at the end (top level). For before/after you MUST provide ' +
-            'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
-            'page outline or the page-JSON view. Avoids resending the whole document. ' +
-            'Can also insert ' +
-            'table structure: to add a tableRow, pass a tableRow node with position ' +
-            'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
-            'block/cell in it, or anchorText matching the table; to add a ' +
-            'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
-            '(anchorText only resolves top-level blocks, so it cannot target a row). ' +
-            "`anchorText` is matched against the block's literal rendered plain text " +
-            '(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
-            'text or anchorNodeId. Note: append is top-level only and rejects ' +
-            'structural table nodes. Example node: a paragraph ' +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            'JSON object or a JSON string (both accepted). Reversible via page history.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            node: z
-                .any()
-                .describe('ProseMirror node to insert, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.'),
-            position: z
-                .enum(['before', 'after', 'append'])
-                .describe('Where to insert relative to the anchor.'),
-            anchorNodeId: z
-                .string()
-                .optional()
-                .describe('Anchor block id (for before/after).'),
-            anchorText: z
-                .string()
-                .optional()
-                .describe("Anchor text fragment (for before/after), matched against the " +
-                "block's literal rendered plain text (no markdown). Markdown/emoji " +
-                'are tolerated as a fallback; prefer plain text or anchorNodeId.'),
-        }),
-    },
-    // --- share management ---
-    unsharePage: {
-        mcpName: 'unshare_page',
-        inAppKey: 'unsharePage',
-        description: 'Remove the public share of a page (revokes the public URL).',
-        buildShape: (z) => ({
-            pageId: z.string().min(1).describe('ID of the page to unshare'),
-        }),
-    },
-    // --- version history ---
-    diffPageVersions: {
-        mcpName: 'diff_page_versions',
-        inAppKey: 'diffPageVersions',
-        description: 'Diff two versions of a page and return a Docmost-equivalent change set ' +
-            '(inserted/deleted text, integrity counts for images/links/tables/' +
-            'callouts/footnote markers, and a human-readable markdown summary). ' +
-            "`from`/`to` each accept a historyId, or null/'current' for the page's " +
-            'current content (defaults: from=current, to=current — pass a historyId ' +
-            'from the page-history list to compare against the live page).',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            from: z
-                .string()
-                .optional()
-                .describe("historyId, or 'current'/omit for current content"),
-            to: z
-                .string()
-                .optional()
-                .describe("historyId, or 'current'/omit for current content"),
-        }),
-    },
-    listPageHistory: {
-        mcpName: 'list_page_history',
-        inAppKey: 'listPageHistory',
-        description: "List a page's saved versions (Docmost auto-snapshots on every save), " +
-            'newest first, cursor-paginated. Returns { items, nextCursor }; each ' +
-            "item's id is the historyId to pass to the page diff or restore tools.",
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            cursor: z
-                .string()
-                .optional()
-                .describe('Pagination cursor from a previous nextCursor'),
-        }),
-    },
-    restorePageVersion: {
-        mcpName: 'restore_page_version',
-        inAppKey: 'restorePageVersion',
-        description: 'Restore a page to a saved version: writes that version\'s content back ' +
-            'as the page\'s current content (Docmost has no restore endpoint, so ' +
-            'this creates a NEW history snapshot — the restore is itself revertible). ' +
-            'Get the historyId from the page-history list.',
-        buildShape: (z) => ({
-            historyId: z.string().min(1),
-        }),
-    },
-    // --- markdown round-trip ---
-    importPageMarkdown: {
-        mcpName: 'import_page_markdown',
-        inAppKey: 'importPageMarkdown',
-        description: "Replace a page's content from a self-contained Docmost-flavoured " +
-            'Markdown file produced by the page-Markdown export tool. Restores comment ' +
-            'highlight anchors and diagrams from their inline HTML. NOTE: comment ' +
-            'thread records are NOT created/updated/deleted on the server by this ' +
-            'tool — only the page body + inline comment marks are written; manage ' +
-            'comment threads via the comment tools/UI.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-            markdown: z.string().min(1),
-        }),
-    },
-    // --- server-side content copy ---
-    copyPageContent: {
-        mcpName: 'copy_page_content',
-        inAppKey: 'copyPageContent',
-        description: "Replace targetPageId's content with a copy of sourcePageId's content, " +
-            'entirely server-side — the document is NOT sent through the model. The ' +
-            'target keeps its own title and slug; only its body is replaced. Ideal ' +
-            "for 'make page A's content equal to B' or 'replace A with B but keep A's URL'.",
-        buildShape: (z) => ({
-            sourcePageId: z.string().min(1).describe('Page to copy content FROM'),
-            targetPageId: z
-                .string()
-                .min(1)
-                .describe('Page whose content is REPLACED (title/slug kept)'),
-        }),
-    },
-    // --- surgical text edit (folds in the documented drift-bug fix) ---
-    //
-    // CANONICAL description is the CORRECTED in-app wording: a formatting-only
-    // change is REFUSED into failed[] (not silently stripped-and-retried). The
-    // stale MCP claim that "Markdown wrappers are tolerated via a strip-and-retry
-    // fallback" is intentionally absent here.
-    editPageText: {
-        mcpName: 'edit_page_text',
-        inAppKey: 'editPageText',
-        description: "Surgical find/replace inside a page's text, preserving all block " +
-            'ids and marks. A find MAY cross bold/italic/link boundaries; the ' +
-            'replacement inherits marks from the unchanged common prefix/suffix ' +
-            '(so editing plain text next to a bold word keeps it bold, and ' +
-            'editing inside a bold word keeps the new text bold). Each find must ' +
-            'match exactly once unless replaceAll is set. The batch applies what ' +
-            'it can and returns applied[] + failed[] plus a verify change-report ' +
-            '(the text/marks/structure that ACTUALLY changed — read it to confirm ' +
-            'your edit landed; do not assume success); a fully-unmatched batch ' +
-            'writes nothing and errors. find and replace are LITERAL text, not ' +
-            'markdown. This tool edits plain text ONLY and CANNOT add or remove ' +
-            'formatting marks: a formatting change — find/replace that differ only ' +
-            'in markdown markers (e.g. find:"~~x~~", replace:"x"), or a replace ' +
-            'containing **bold**/~~strike~~/`code` wrappers — is REFUSED into ' +
-            'failed[]. To change bold/italic/strike/code/link, read the block as ' +
-            'page JSON and use a structural node patch/update to set its marks. ' +
-            'Examples: edits:[{find:"teh",replace:"the"}]; edits:[{find:"Hello ' +
-            'world",replace:"Hello there"}] (crosses a bold boundary).',
-        buildShape: (z) => ({
-            pageId: z.string().describe('ID of the page to edit'),
-            edits: z
-                .array(z.object({
-                find: z.string().describe('Exact text to find'),
-                replace: z.string().describe('Replacement text (may be empty)'),
-                replaceAll: z
-                    .boolean()
-                    .optional()
-                    .describe('Replace every occurrence (default: must match once)'),
-            }))
-                .min(1)
-                .describe('List of find/replace operations, applied in order'),
-        }),
-    },
-    // --- hand a large page to an external consumer without bloating context ---
-    stashPage: {
-        mcpName: 'stash_page',
-        inAppKey: 'stashPage',
-        description: 'Serialize a whole page (the full ProseMirror JSON, as get_page_json ' +
-            'returns) into an ephemeral in-memory blob and return ONLY a short ' +
-            'anonymous URL to it — the body NEVER enters the model context, so this ' +
-            'is the way to hand a large page (or its images) to an external consumer ' +
-            'without truncation. Every internal file/image attachment is mirrored ' +
-            'into the same sandbox and its src rewritten to a sandbox URL, so the ' +
-            'consumer can fetch the images anonymously too; external http(s) images ' +
-            'are left untouched. Returns { uri, size, sha256, images:{mirrored, ' +
-            'failed} }. Integrity: the blob is served with ETag = its sha256, so a ' +
-            'truncated/corrupted fetch is detectable. Blobs are RAM-only: they expire ' +
-            'after a short TTL (~1h) and are cleared on restart — consume the URL ' +
-            'within the TTL and one uptime, or re-stash. A blob is bound to the ' +
-            'server instance that created it: in a multi-replica deployment without ' +
-            'sticky sessions a blob stored on one instance is not retrievable via the ' +
-            'sandbox URL on another (it 404s like an expired one).',
-        buildShape: (z) => ({
-            pageId: z.string().min(1),
-        }),
-    },
-};
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index 3edc1902..83b0f002 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -32,6 +32,7 @@
   "author": "Moritz Krause",
   "license": "MIT",
   "dependencies": {
+    "@docmost/prosemirror-markdown": "workspace:*",
     "@fellow/prosemirror-recreate-transform": "^1.2.3",
     "@hocuspocus/provider": "^3.4.4",
     "@hocuspocus/transformer": "^3.4.4",
diff --git a/packages/mcp/src/lib/collaboration.ts b/packages/mcp/src/lib/collaboration.ts
index c8b1cf40..c14afbf8 100644
--- a/packages/mcp/src/lib/collaboration.ts
+++ b/packages/mcp/src/lib/collaboration.ts
@@ -2,18 +2,24 @@ import { HocuspocusProvider } from "@hocuspocus/provider";
 import { TiptapTransformer } from "@hocuspocus/transformer";
 import * as Y from "yjs";
 import WebSocket from "ws";
-import { marked } from "marked";
-import { generateJSON } from "@tiptap/html";
 import { Node as PMNode } from "@tiptap/pm/model";
 import { updateYFragment } from "y-prosemirror";
 import { JSDOM } from "jsdom";
+// #293 STEP 5: the pure markdown -> ProseMirror import path is now owned by the
+// shared package (canonical `^[…]` footnotes, `$…$` math, `==` highlight, the
+// media-family md forms, comment-directive attrs, callouts and task lists all
+// handled there). MCP consumes it directly instead of maintaining its own
+// drifted marked pipeline; only the collab/yjs write glue and the footnote
+// canonicalization wrapper stay mcp-side.
+import { markdownToProseMirror } from "@docmost/prosemirror-markdown";
 import { docmostExtensions, docmostSchema } from "./docmost-schema.js";
 import { withPageLock } from "./page-lock.js";
 import { sanitizeForYjs, findUnstorableAttr } from "./node-ops.js";
-import { lexFootnoteLines } from "./footnote-lex.js";
 import { canonicalizeFootnotes } from "./footnote-canonicalize.js";
 import { summarizeChange, VerifyReport } from "./diff.js";
 
+export { markdownToProseMirror };
+
 /**
  * Build the descriptive error for an opaque Yjs encode failure ("Unexpected
  * content type"), shared by both encode paths (`buildYDoc` -> `toYdoc` and
@@ -51,382 +57,27 @@ global.WebSocket = WebSocket;
 // global.navigator = dom.window.navigator;
 
 /**
- * Hard ceiling above which we skip callout preprocessing entirely. The linear
- * scanner below has no quadratic blow-up, but we still cap input defensively so
- * a pathological multi-megabyte payload cannot tie up the event loop; in that
- * case the markdown is passed through verbatim (callouts are simply not
- * detected) rather than risking a slow scan.
- */
-const MAX_CALLOUT_PREPROCESS_BYTES = 4 * 1024 * 1024; // 4 MB
-
-/** Matches an opening callout fence: `:::type` (type captured, lower-cased). */
-const CALLOUT_OPEN_RE = /^:::\s*(\w+)\s*$/;
-/** Matches a bare closing callout fence: `:::`. */
-const CALLOUT_CLOSE_RE = /^:::\s*$/;
-/** Matches the start/end of a code fence (``` or ~~~), capturing the marker. */
-const CODE_FENCE_RE = /^(\s*)(`{3,}|~{3,})/;
-
-/**
- * Pre-process Docmost-flavoured markdown: convert `:::type ... :::`
- * callout blocks (the syntax our markdown export produces) into HTML
- * divs that the callout extension parses. The inner content is rendered
- * through marked as regular markdown.
+ * Page-write variant of the package's `markdownToProseMirror`: imports markdown
+ * then re-runs mcp's footnote canonicalizer over the result.
  *
- * Implemented as a single linear pass over the lines (no quadratic regex
- * rescan). It:
- *   - tracks fenced code regions (```...``` and ~~~...~~~) and never treats a
- *     `:::` line that lives inside a code fence as a callout delimiter, so a
- *     callout body that itself contains a fenced code block with a `:::` line is
- *     no longer corrupted;
- *   - matches an opening `:::type` line with the next CLOSING `:::` at the SAME
- *     nesting level, supporting NESTED callouts via a depth counter (an inner
- *     `:::type` opens a deeper level and consumes a matching `:::`);
- *   - emits the same `<div data-type="callout" data-callout-type="TYPE">` output
- *     (inner rendered through marked) as the previous regex implementation.
- */
-async function preprocessCallouts(markdown: string): Promise<string> {
-  // Defensive cap: skip preprocessing for pathologically large inputs.
-  if (markdown.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-    return markdown;
-  }
-
-  // Recursively transform a slice of lines, converting top-level callouts in
-  // that slice into <div> blocks and rendering their inner content (which may
-  // itself contain nested callouts) through this same function.
-  const transform = async (lines: string[]): Promise<string> => {
-    const out: string[] = [];
-    let inCodeFence = false;
-    let codeFenceMarker = ""; // the exact run of backticks/tildes that opened it
-    let i = 0;
-
-    while (i < lines.length) {
-      const line = lines[i];
-
-      // Inside a code fence, only its matching closing fence is significant;
-      // everything else (including `:::` lines) is copied through verbatim.
-      if (inCodeFence) {
-        out.push(line);
-        const fence = line.match(CODE_FENCE_RE);
-        if (fence && fence[2].startsWith(codeFenceMarker[0]) &&
-            fence[2].length >= codeFenceMarker.length) {
-          inCodeFence = false;
-          codeFenceMarker = "";
-        }
-        i++;
-        continue;
-      }
-
-      // A code fence opening outside any callout body: enter code-fence mode.
-      const fenceOpen = line.match(CODE_FENCE_RE);
-      if (fenceOpen) {
-        inCodeFence = true;
-        codeFenceMarker = fenceOpen[2];
-        out.push(line);
-        i++;
-        continue;
-      }
-
-      // An opening callout fence: scan forward (with code-fence and nested
-      // callout awareness) for its matching closing `:::` at the same level.
-      const open = line.match(CALLOUT_OPEN_RE);
-      if (open) {
-        const type = open[1].toLowerCase();
-        const bodyLines: string[] = [];
-        let depth = 1;
-        let innerInCodeFence = false;
-        let innerCodeFenceMarker = "";
-        let j = i + 1;
-        for (; j < lines.length; j++) {
-          const bl = lines[j];
-          if (innerInCodeFence) {
-            const f = bl.match(CODE_FENCE_RE);
-            if (f && f[2].startsWith(innerCodeFenceMarker[0]) &&
-                f[2].length >= innerCodeFenceMarker.length) {
-              innerInCodeFence = false;
-              innerCodeFenceMarker = "";
-            }
-            bodyLines.push(bl);
-            continue;
-          }
-          const innerFence = bl.match(CODE_FENCE_RE);
-          if (innerFence) {
-            innerInCodeFence = true;
-            innerCodeFenceMarker = innerFence[2];
-            bodyLines.push(bl);
-            continue;
-          }
-          if (CALLOUT_OPEN_RE.test(bl)) {
-            depth++;
-            bodyLines.push(bl);
-            continue;
-          }
-          if (CALLOUT_CLOSE_RE.test(bl)) {
-            depth--;
-            if (depth === 0) break; // matching close for THIS callout
-            bodyLines.push(bl);
-            continue;
-          }
-          bodyLines.push(bl);
-        }
-
-        if (j < lines.length) {
-          // Found the matching closing fence: render the body (recursively, so
-          // nested callouts are handled) and emit the callout div.
-          const inner = await transform(bodyLines);
-          const renderedInner = await marked.parse(inner);
-          out.push(
-            `\n<div data-type="callout" data-callout-type="${type}">${renderedInner}</div>\n`,
-          );
-          i = j + 1; // skip past the closing `:::`
-          continue;
-        }
-        // No matching close (unterminated callout): treat the opener as a
-        // literal line and continue, preserving the original text.
-        out.push(line);
-        i++;
-        continue;
-      }
-
-      out.push(line);
-      i++;
-    }
-
-    return out.join("\n");
-  };
-
-  return transform(markdown.split("\n"));
-}
-
-/**
- * Bridge marked's checkbox lists to TipTap task lists.
+ * Footnote layering after #293 STEP 5:
+ *   - The package's `markdownToProseMirror` already ASSEMBLES footnotes on import
+ *     (canon #2): inline `^[body]` markers become the schema's
+ *     `footnoteReference` + a single doc-level `footnotesList`, with ids assigned
+ *     sequentially (`fn-1`, `fn-2`, …) in first-reference order and identical
+ *     bodies merged. So the import output is ALREADY in canonical footnote
+ *     topology.
+ *   - `canonicalizeFootnotes` runs AFTER as the mcp write-path invariant shared
+ *     with every other full-document persist path (`update_page_json`,
+ *     `docmost_transform`, `insert_footnote`, …). Because the package output is
+ *     already canonical, this layer is a no-op here (idempotent) — it exists so
+ *     the page-write contract is enforced uniformly regardless of how the PM doc
+ *     was produced, not because the import needs fixing.
  *
- * marked renders GitHub task list items (`- [x] done`) as a plain
- * `<ul><li><p><input type="checkbox" checked> text</p></li></ul>` WITHOUT the
- * markup TipTap's TaskList/TaskItem extensions parse. This rewrites such lists
- * into the shape those extensions expect:
- *   TaskList parseHTML matches `ul[data-type="taskList"]`,
- *   TaskItem matches `li[data-type="taskItem"]`,
- *   the checked state is read from `data-checked === "true"`.
- *
- * A list is only converted when it has at least one `<li>` and EVERY direct
- * `<li>` contains a checkbox input. Both `<ul>` and `<ol>` are considered: a
- * numbered checklist (`1. [x] a`, which marked renders as an `<ol>` of checkbox
- * `<li>`s) would otherwise lose its task state. TipTap task lists are unordered,
- * so a matching `<ol>` is emitted as `data-type="taskList"` exactly like a
- * `<ul>`. Mixed or ordinary lists (including ordinary `<ol>` lists) are left
- * untouched so they keep rendering as bullet/numbered lists. The marked `<p>`
- * wrapper is kept inside the `<li>` because TaskItem content allows paragraphs.
- */
-function bridgeTaskLists(html: string): string {
-  // Cheap early-out: if the markup contains no checkbox input at all there is
-  // nothing to bridge, so skip the expensive JSDOM parse entirely. This is the
-  // common case (most pages have no task lists).
-  if (!/type=["']?checkbox/i.test(html)) {
-    return html;
-  }
-  // Defensive cap (consistent with preprocessCallouts): skip the bridge for
-  // pathologically large inputs rather than running a second expensive JSDOM
-  // parse on a multi-megabyte payload. The markup is passed through verbatim.
-  if (html.length > MAX_CALLOUT_PREPROCESS_BYTES) {
-    return html;
-  }
-  const dom = new JSDOM(html);
-  const document = dom.window.document;
-  // Collect the checkbox(es) that belong to THIS <li> directly: either direct
-  // child <input type="checkbox"> elements or ones inside the <li>'s direct <p>
-  // child (the shape marked emits: `<li><p><input type="checkbox"> text</p></li>`).
-  // Checkboxes nested deeper (e.g. inside a child <ul>/<ol>) are excluded so a
-  // bullet <li> that merely contains a nested task sublist is not misdetected.
-  // Raw inline HTML can put more than one checkbox in a single <li>; we gather
-  // ALL of them so none survive into the converted item.
-  const directCheckboxes = (li: Element): Element[] => {
-    const found: Element[] = [];
-    for (const child of Array.from(li.children)) {
-      if (
-        child.tagName === "INPUT" &&
-        child.getAttribute("type") === "checkbox"
-      ) {
-        found.push(child);
-        continue;
-      }
-      if (child.tagName === "P") {
-        for (const inp of Array.from(
-          child.querySelectorAll(":scope > input[type='checkbox']"),
-        )) {
-          found.push(inp);
-        }
-      }
-    }
-    return found;
-  };
-  // Both <ul> and <ol> are candidates: an <ol> whose every direct <li> carries
-  // its own checkbox is a numbered checklist that must also become a taskList.
-  const lists = Array.from(document.querySelectorAll("ul, ol"));
-  for (const list of lists) {
-    // Only consider DIRECT child <li> elements; nested lists are handled by
-    // their own iteration of the outer loop.
-    const items = Array.from(list.children).filter(
-      (child) => child.tagName === "LI",
-    );
-    if (items.length === 0) continue;
-    const itemCheckboxes = items.map((li) => directCheckboxes(li));
-    // Convert only when every direct <li> carries at least one OWN checkbox.
-    if (!itemCheckboxes.every((boxes) => boxes.length > 0)) continue;
-
-    // A numbered checklist arrives as an <ol>. We must NOT leave the tag as
-    // <ol> while tagging it data-type="taskList": generateJSON would then match
-    // BOTH the orderedList rule (tag ol) and the taskList rule (data-type),
-    // emitting a phantom empty orderedList beside the real taskList. So rename a
-    // qualifying <ol> to a <ul> — move its <li> children over and replace it —
-    // leaving only the taskList rule to match. Already-<ul> lists are unchanged.
-    let target: Element = list;
-    if (list.tagName === "OL") {
-      const ul = document.createElement("ul");
-      // Carry over existing attributes (e.g. class) so nothing is silently lost.
-      for (const attr of Array.from(list.attributes)) {
-        ul.setAttribute(attr.name, attr.value);
-      }
-      // Move every child node (including the <li>s we collected) into the <ul>.
-      while (list.firstChild) {
-        ul.appendChild(list.firstChild);
-      }
-      list.replaceWith(ul);
-      target = ul;
-    }
-
-    target.setAttribute("data-type", "taskList");
-    items.forEach((li, index) => {
-      const boxes = itemCheckboxes[index];
-      // The first checkbox determines the checked state (matches the previous
-      // single-checkbox behaviour); any extras only need removing.
-      const input = boxes[0] ?? null;
-      li.setAttribute("data-type", "taskItem");
-      const checked =
-        input != null &&
-        (input.hasAttribute("checked") || (input as any).checked);
-      li.setAttribute("data-checked", checked ? "true" : "false");
-      // Remove ALL direct checkbox inputs so none survive into the content
-      // (a raw-inline-HTML <li> may carry more than one).
-      for (const box of boxes) {
-        box.remove();
-      }
-    });
-  }
-  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>.
-// Definition detection + fence handling are shared with analyzeFootnotes via
-// lexFootnoteLines (footnote-lex.js). FOOTNOTE_REF_RE is the inline tokenizer's.
-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 bodyLines: string[] = [];
-  const defs: Array<{ id: string; text: string }> = [];
-  // Shared lexer (footnote-lex): a `[^id]: ...` line inside a ``` / ~~~ code
-  // block is inert and stays in the body verbatim; only real definition lines
-  // are pulled out. analyzeFootnotes() consumes the SAME lexer so its diagnostics
-  // match exactly what import keeps/strips (#166).
-  for (const tok of lexFootnoteLines(markdown)) {
-    if (!tok.inFence && tok.definition) defs.push(tok.definition);
-    else bodyLines.push(tok.line);
-  }
-  if (defs.length === 0) return { body: markdown, section: "" };
-
-  // Duplicate definition ids: FIRST WINS, the rest are DROPPED (mirror of
-  // editor-ext extractFootnoteDefinitions). Reference markers are left untouched
-  // so repeated `[^a]` references reuse the single footnote (Pandoc semantics,
-  // #166). The dropped duplicate is surfaced to the caller via analyzeFootnotes
-  // (`duplicateDefinitions`), not silently lost. MUST stay in sync with the
-  // editor-ext mirror.
-  const firstById = new Map<string, string>(); // id -> first definition text
-  for (const def of defs) {
-    if (!firstById.has(def.id)) firstById.set(def.id, def.text);
-  }
-
-  const inner = [...firstById.entries()]
-    .map(
-      ([id, text]) =>
-        `<div data-footnote-def data-id="${escapeFootnoteAttr(
-          id,
-        )}"><p>${marked.parseInline(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.
- *
- * This conversion does NOT canonicalize footnotes — it is the shared, content-
- * preserving primitive used by BOTH page write paths and COMMENT bodies
- * (createComment / updateComment). Canonicalization MUST NOT run on a comment
- * body: a comment may legitimately contain a footnote-definition line
- * (`[^1]: text`) with no matching reference, and the canonicalizer drops a
- * reference-less footnotesList — which would silently delete the comment's text.
- *
- * Page write paths that DO need the canonical footnote topology call
- * `markdownToProseMirrorCanonical` instead (markdown import, update_page markdown
- * path). Keep this function reference-loss-free.
- */
-export async function markdownToProseMirror(
-  markdownContent: string,
-): Promise<any> {
-  const withCallouts = await preprocessCallouts(markdownContent);
-  const { body, section } = extractFootnotes(withCallouts);
-  const html = (await marked.parse(body)) + section;
-  const bridged = bridgeTaskLists(html);
-  return generateJSON(bridged, docmostExtensions);
-}
-
-/**
- * Page-write variant of `markdownToProseMirror`: converts markdown then enforces
- * the canonical footnote topology. The footnote `section` markdown is emitted in
- * DEFINITION order, but numbering derives from REFERENCE order, so without this
- * the bottom list renders out of order (`1, 4, 2, 3, …`); orphan definitions and
- * duplicate lists are also normalized. Idempotent — a no-op once canonical, and a
- * no-op for footnote-free content.
- *
- * Use this ONLY for full-document PAGE writes (never for comment bodies, where it
- * would drop a reference-less footnote definition — see `markdownToProseMirror`).
+ * Use this ONLY for full-document PAGE writes. Comment bodies call the package's
+ * plain `markdownToProseMirror` (no canonicalization) — safe now because inline
+ * `^[body]` footnotes carry their body at the reference point, so a comment can
+ * no longer produce a reference-less footnote definition to be dropped.
  */
 export async function markdownToProseMirrorCanonical(
   markdownContent: string,
diff --git a/packages/mcp/src/lib/docmost-schema.ts b/packages/mcp/src/lib/docmost-schema.ts
index 6478952b..1438f8d7 100644
--- a/packages/mcp/src/lib/docmost-schema.ts
+++ b/packages/mcp/src/lib/docmost-schema.ts
@@ -1,45 +1,33 @@
 /**
- * Full TipTap extension set matching the real Docmost document schema.
+ * Docmost TipTap schema mirror.
  *
- * The default StarterKit-only schema silently destroys Docmost-specific
- * nodes (callout, table) and drops attributes it does not know about
- * (node ids, image sizing, link targets). Every code path that converts
- * to or from ProseMirror JSON must use THIS set, otherwise a round-trip
- * loses content.
+ * #293 STEP 5: the extension set (and its parseHTML/renderHTML behaviour) is now
+ * owned by the shared `@docmost/prosemirror-markdown` package — the single
+ * canonical schema every converter path targets. MCP re-exports it here instead
+ * of maintaining its own drifted ~1200-line copy, so the schema can never drift
+ * between mcp and the package/git-sync again.
+ *
+ * `docmostExtensions` comes from the package; `docmostSchema` is derived from it
+ * exactly as before (`getSchema(docmostExtensions)`), built ONCE and reused by
+ * every consumer (diff, collaboration write-back) so the schema is identical at
+ * every call site.
+ *
+ * The package does NOT re-export the two small mcp-only sanitizer helpers
+ * (`clampCalloutType`, `sanitizeCssColor`) through its public barrel, so they
+ * are preserved verbatim here (they are pure and used by mcp code/tests). The
+ * package's schema uses its own internally-identical copies for parsing.
  */
-import StarterKit from "@tiptap/starter-kit";
-import Image from "@tiptap/extension-image";
-import TaskList from "@tiptap/extension-task-list";
-import TaskItem from "@tiptap/extension-task-item";
-import Highlight from "@tiptap/extension-highlight";
-import Subscript from "@tiptap/extension-subscript";
-import Superscript from "@tiptap/extension-superscript";
-import { Node, Extension, Mark, getSchema } from "@tiptap/core";
+import { getSchema } from "@tiptap/core";
+import { docmostExtensions } from "@docmost/prosemirror-markdown";
 
-// Inlined from @tiptap/core's getStyleProperty (added after 3.20.x) so this
-// package can stay on the same @tiptap/core version as the editor and avoid a
-// duplicate-tiptap version split in the monorepo. Reads a single declaration
-// from an element's inline `style` attribute, last-wins, case-insensitive.
-function getStyleProperty(element: HTMLElement, propertyName: string): string | null {
-  const styleAttr = element.getAttribute("style");
-  if (!styleAttr) {
-    return null;
-  }
-  const decls = styleAttr.split(";").map((decl) => decl.trim()).filter(Boolean);
-  const target = propertyName.toLowerCase();
-  for (let i = decls.length - 1; i >= 0; i -= 1) {
-    const decl = decls[i];
-    const colonIndex = decl.indexOf(":");
-    if (colonIndex === -1) {
-      continue;
-    }
-    const prop = decl.slice(0, colonIndex).trim().toLowerCase();
-    if (prop === target) {
-      return decl.slice(colonIndex + 1).trim();
-    }
-  }
-  return null;
-}
+export { docmostExtensions };
+
+/**
+ * The ProseMirror schema for the docmost editor, built ONCE from
+ * `docmostExtensions`. Pure and reused by every consumer (diff, collaboration
+ * write-back) so the schema can never drift between call sites.
+ */
+export const docmostSchema = getSchema(docmostExtensions);
 
 /** Allowed Docmost callout types; anything else falls back to "info". */
 const CALLOUT_TYPES = ["info", "warning", "danger", "success"];
@@ -73,1201 +61,3 @@ export const sanitizeCssColor = (
   const color = value.trim();
   return color && SAFE_COLOR_RE.test(color) ? color : null;
 };
-
-/** Docmost callout (info/warning/danger/success banner). */
-const Callout = Node.create({
-  name: "callout",
-  group: "block",
-  content: "block+",
-  defining: true,
-  addAttributes() {
-    return {
-      // Read the type from data-callout-type so generateJSON(html) preserves
-      // it; without an explicit parseHTML every imported callout became "info".
-      type: {
-        default: "info",
-        parseHTML: (el: HTMLElement) =>
-          clampCalloutType(el.getAttribute("data-callout-type")),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-callout-type": clampCalloutType(attrs.type),
-        }),
-      },
-      icon: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-icon"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.icon ? { "data-icon": attrs.icon } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="callout"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "callout", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Minimal table family: enough for schema round-trips and HTML parsing. */
-const Table = Node.create({
-  name: "table",
-  group: "block",
-  content: "tableRow+",
-  isolating: true,
-  parseHTML() {
-    return [{ tag: "table" }];
-  },
-  renderHTML() {
-    return ["table", ["tbody", 0]];
-  },
-});
-
-const TableRow = Node.create({
-  name: "tableRow",
-  content: "(tableCell | tableHeader)*",
-  parseHTML() {
-    return [{ tag: "tr" }];
-  },
-  renderHTML() {
-    return ["tr", 0];
-  },
-});
-
-const cellAttributes = () => ({
-  colspan: { default: 1 },
-  rowspan: { default: 1 },
-  colwidth: { default: null },
-  backgroundColor: { default: null },
-  backgroundColorName: { default: null },
-  // Column alignment so GFM aligned tables (|:--|:-:|--:|) round-trip.
-  align: {
-    default: null,
-    parseHTML: (el: HTMLElement) =>
-      el.getAttribute("align") || el.style.textAlign || null,
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.align ? { align: attrs.align } : {},
-  },
-});
-
-const TableCell = Node.create({
-  name: "tableCell",
-  content: "block+",
-  isolating: true,
-  addAttributes: cellAttributes,
-  parseHTML() {
-    return [{ tag: "td" }];
-  },
-  renderHTML() {
-    return ["td", 0];
-  },
-});
-
-const TableHeader = Node.create({
-  name: "tableHeader",
-  content: "block+",
-  isolating: true,
-  addAttributes: cellAttributes,
-  parseHTML() {
-    return [{ tag: "th" }];
-  },
-  renderHTML() {
-    return ["th", 0];
-  },
-});
-
-/**
- * Attributes Docmost stores on standard nodes that the stock extensions
- * do not declare. Without these, Node.fromJSON silently drops them —
- * including the block ids that heading anchors rely on.
- */
-const DocmostAttributes = Extension.create({
-  name: "docmostAttributes",
-  addGlobalAttributes() {
-    return [
-      {
-        types: ["heading", "paragraph"],
-        attributes: {
-          id: { default: null },
-          indent: { default: null },
-          textAlign: { default: null },
-        },
-      },
-      {
-        types: ["image"],
-        attributes: {
-          align: { default: null },
-          attachmentId: { default: null },
-          aspectRatio: { default: null },
-          height: { default: null },
-          placeholder: { default: null },
-          size: { default: null },
-          width: { default: null },
-        },
-      },
-      {
-        types: ["orderedList"],
-        attributes: { type: { default: null } },
-      },
-      {
-        types: ["link"],
-        attributes: { internal: { default: null }, title: { default: null } },
-      },
-    ];
-  },
-});
-
-/**
- * Docmost inline comment mark. Anchors a comment thread to a text range via
- * `commentId`. Without it, any document containing comment highlights fails to
- * round-trip through the schema ("There is no mark type comment in this schema"),
- * which breaks update_page_json and edit_page_text on every commented page.
- * Mirrors Docmost's @docmost/editor-ext comment mark (commentId / resolved).
- */
-const Comment = Mark.create({
-  name: "comment",
-  exitable: true,
-  inclusive: false,
-  addAttributes() {
-    return {
-      commentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-comment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.commentId ? { "data-comment-id": attrs.commentId } : {},
-      },
-      resolved: {
-        default: false,
-        parseHTML: (el: HTMLElement) =>
-          el.getAttribute("data-resolved") === "true",
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.resolved ? { "data-resolved": "true" } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "span[data-comment-id]" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", { class: "comment-mark", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Text color mark. The markdown-converter emits colored text as
- * <span style="color: ...">, but with no mark parsing it back the color was
- * silently dropped on import. This mirrors TipTap's @tiptap/extension-text-style
- * `textStyle` mark (the name Docmost expects) and carries a single `color`
- * attribute. The parsed color is passed through the allowlist guard so a crafted
- * style cannot break out of the attribute when Docmost re-renders it.
- */
-const TextStyle = Mark.create({
-  name: "textStyle",
-  addAttributes() {
-    return {
-      color: {
-        default: null,
-        parseHTML: (el: HTMLElement) =>
-          sanitizeCssColor(
-            el.style.color || el.getAttribute("data-color"),
-          ),
-        renderHTML: (attrs: Record<string, any>) => {
-          const color = sanitizeCssColor(attrs.color);
-          return color ? { style: `color: ${color}` } : {};
-        },
-      },
-    };
-  },
-  parseHTML() {
-    return [
-      {
-        tag: "span",
-        // Only claim a plain colored span. Do NOT match spans that are already a
-        // comment mark (data-comment-id) or a mention node (data-type=mention),
-        // otherwise importing such HTML would silently drop the comment/mention.
-        getAttrs: (el: HTMLElement) =>
-          el.style.color &&
-          !el.getAttribute("data-comment-id") &&
-          el.getAttribute("data-type") !== "mention"
-            ? {}
-            : false,
-      },
-    ];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", HTMLAttributes, 0];
-  },
-});
-
-/**
- * Inline spoiler mark. Mirrors the @docmost/editor-ext `spoiler` mark so a
- * document carrying a spoiler survives the MCP read -> transform -> write path
- * (and markdown export) instead of silently dropping the unrecognized mark.
- * packages/mcp does NOT depend on editor-ext, so the definition is kept local;
- * it parses span[data-spoiler] and renders the same span[data-spoiler][class]
- * the editor-ext mark emits.
- */
-const Spoiler = Mark.create({
-  name: "spoiler",
-  // Don't bleed onto text typed at the boundary (mirrors editor-ext).
-  inclusive: false,
-  parseHTML() {
-    return [{ tag: "span[data-spoiler]" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["span", { "data-spoiler": "true", class: "spoiler", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Passthrough definitions for the remaining Docmost-specific nodes.
- *
- * TiptapTransformer.toYdoc (the write path every mutation uses) throws
- * "Unknown node type: X" for any node not registered here, so editing ANY
- * page that contains one of these nodes used to fail outright. The read path
- * (fromYdoc) accepts them, which is why they appear in real documents.
- *
- * Each node below mirrors the real @docmost/editor-ext definition's name,
- * group, content, inline/atom flags and attribute keys (with the same data-*
- * HTML mapping) so that a fromYdoc -> transform -> toYdoc round-trip both
- * validates and preserves attributes faithfully. Interactive concerns
- * (node views, commands, keyboard shortcuts, input rules, suggestion plugins)
- * are intentionally omitted: the MCP server never renders these nodes, it only
- * needs the schema to accept and carry them. The Callout node above is the
- * pattern these follow.
- */
-
-/** Docmost @mention (user/page reference). Inline atom. */
-const Mention = Node.create({
-  name: "mention",
-  group: "inline",
-  inline: true,
-  selectable: true,
-  atom: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      id: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.id ? { "data-id": attrs.id } : {},
-      },
-      label: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-label"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.label ? { "data-label": attrs.label } : {},
-      },
-      entityType: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-type"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.entityType ? { "data-entity-type": attrs.entityType } : {},
-      },
-      entityId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-entity-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.entityId ? { "data-entity-id": attrs.entityId } : {},
-      },
-      slugId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-slug-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.slugId ? { "data-slug-id": attrs.slugId } : {},
-      },
-      creatorId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-creator-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.creatorId ? { "data-creator-id": attrs.creatorId } : {},
-      },
-      anchorId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-anchor-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.anchorId ? { "data-anchor-id": attrs.anchorId } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'span[data-type="mention"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    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: 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",
-  group: "inline",
-  inline: true,
-  atom: true,
-  addAttributes() {
-    return {
-      text: { default: "" },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'span[data-type="mathInline"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "span",
-      { "data-type": "mathInline", "data-katex": "true" },
-      `${HTMLAttributes.text ?? ""}`,
-    ];
-  },
-});
-
-/** Block KaTeX expression. Carries the LaTeX source in `text`. */
-const MathBlock = Node.create({
-  name: "mathBlock",
-  group: "block",
-  atom: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      text: { default: "" },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="mathBlock"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return [
-      "div",
-      { "data-type": "mathBlock", "data-katex": "true" },
-      `${HTMLAttributes.text ?? ""}`,
-    ];
-  },
-});
-
-/** Collapsible <details> wrapper: summary + content children. */
-const Details = Node.create({
-  name: "details",
-  group: "block",
-  content: "detailsSummary detailsContent",
-  defining: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      open: {
-        default: false,
-        parseHTML: (el: HTMLElement) => el.getAttribute("open"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.open ? { open: "" } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "details" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["details", { ...HTMLAttributes }, 0];
-  },
-});
-
-/** Clickable summary line of a <details> block. */
-const DetailsSummary = Node.create({
-  name: "detailsSummary",
-  group: "block",
-  content: "inline*",
-  defining: true,
-  isolating: true,
-  selectable: false,
-  parseHTML() {
-    return [{ tag: "summary" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["summary", { "data-type": "detailsSummary", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Body of a <details> block. Permissive content so fromYdoc output validates. */
-const DetailsContent = Node.create({
-  name: "detailsContent",
-  group: "block",
-  // Docmost declares block* (an empty details body is valid); block+ would
-  // reject a collapsed/empty details on round-trip.
-  content: "block*",
-  defining: true,
-  selectable: false,
-  parseHTML() {
-    return [{ tag: 'div[data-type="detailsContent"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "detailsContent", ...HTMLAttributes }, 0];
-  },
-});
-
-/** File attachment card (non-image upload). Block atom. */
-const Attachment = Node.create({
-  name: "attachment",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      url: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-url"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-attachment-url": attrs.url ?? "",
-        }),
-      },
-      name: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-name"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.name ? { "data-attachment-name": attrs.name } : {},
-      },
-      mime: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-mime"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.mime ? { "data-attachment-mime": attrs.mime } : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-attachment-size": attrs.size } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      // Docmost declares `placeholder` (a transient upload key, not rendered
-      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="attachment"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "attachment", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Uploaded <video> player. Block atom. */
-const Video = Node.create({
-  name: "video",
-  group: "block",
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      alt: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("aria-label"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.alt ? { "aria-label": attrs.alt } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { width: attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { height: attrs.height } : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.align ? { "data-align": attrs.align } : {},
-      },
-      aspectRatio: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.aspectRatio != null
-            ? { "data-aspect-ratio": attrs.aspectRatio }
-            : {},
-      },
-      // Docmost declares `placeholder` (a transient upload key, not rendered
-      // to HTML). Carry it so a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "video" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["video", { controls: "true", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Defensive passthrough for a `youtube` node. Docmost itself has no dedicated
- * youtube node (YouTube is handled via `embed`), but the converter read path
- * references this type, so accept it as a generic block atom that preserves
- * its src so legacy/external documents survive a round-trip.
- */
-const Youtube = Node.create({
-  name: "youtube",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-src": attrs.src ?? "",
-        }),
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { "data-width": attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { "data-height": attrs.height } : {},
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.align ? { "data-align": attrs.align } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="youtube"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "youtube", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Generic embed (provider iframe). Block atom. */
-const Embed = Node.create({
-  name: "embed",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-src": attrs.src ?? "",
-        }),
-      },
-      provider: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-provider"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-provider": attrs.provider ?? "",
-        }),
-      },
-      align: {
-        default: "center",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-align": attrs.align ?? "center",
-        }),
-      },
-      width: {
-        default: 800,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-width": attrs.width,
-        }),
-      },
-      height: {
-        default: 600,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-height": attrs.height,
-        }),
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="embed"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "embed", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Docmost raw HTML embed. Block atom; the client renders `source` inside a
- * sandboxed iframe. The MCP server never renders it — it only needs the
- * schema to accept and carry the node so a fromYdoc -> transform -> toYdoc
- * round-trip does not throw "Unknown node type: htmlEmbed". Mirrors the
- * @docmost/editor-ext node name, attribute keys and flags; keep in sync when
- * the editor-ext htmlEmbed schema changes.
- *
- * NOTE: unlike the canonical editor-ext node, `data-source` here is mapped as
- * plain text rather than base64-encoded. That is intentional: the MCP write
- * path carries the node through Yjs (fromYdoc -> toYdoc) on its JSON `source`
- * attribute and never invokes parseHTML/renderHTML, and htmlEmbed is not
- * produced from the markdown/HTML (generateJSON) path. If a future HTML path
- * for htmlEmbed is added here, this mapping must adopt editor-ext's base64
- * encode/decode to avoid double-encoding `source`.
- */
-const HtmlEmbed = Node.create({
-  name: "htmlEmbed",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      source: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-source") ?? "",
-        renderHTML: (attrs: Record<string, any>) => ({
-          "data-source": attrs.source ?? "",
-        }),
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => {
-          const v = el.getAttribute("data-height");
-          if (!v) return null;
-          const n = parseInt(v, 10);
-          return Number.isFinite(n) ? n : null;
-        },
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { "data-height": String(attrs.height) } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="htmlEmbed"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "htmlEmbed", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Shared attribute set for drawio/excalidraw diagram nodes. */
-const diagramAttributes = () => ({
-  src: {
-    default: "",
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-src"),
-    renderHTML: (attrs: Record<string, any>) => ({
-      "data-src": attrs.src ?? "",
-    }),
-  },
-  title: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-title"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.title ? { "data-title": attrs.title } : {},
-  },
-  alt: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-alt"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.alt ? { "data-alt": attrs.alt } : {},
-  },
-  width: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-width"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.width != null ? { "data-width": attrs.width } : {},
-  },
-  height: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-height"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.height != null ? { "data-height": attrs.height } : {},
-  },
-  size: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.size != null ? { "data-size": attrs.size } : {},
-  },
-  aspectRatio: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-aspect-ratio"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.aspectRatio != null
-        ? { "data-aspect-ratio": attrs.aspectRatio }
-        : {},
-  },
-  align: {
-    default: "center",
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-align"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.align ? { "data-align": attrs.align } : {},
-  },
-  attachmentId: {
-    default: null,
-    parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-    renderHTML: (attrs: Record<string, any>) =>
-      attrs.attachmentId ? { "data-attachment-id": attrs.attachmentId } : {},
-  },
-});
-
-/** draw.io diagram. Block atom (image-backed). */
-const Drawio = Node.create({
-  name: "drawio",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes: diagramAttributes,
-  parseHTML() {
-    return [{ tag: 'div[data-type="drawio"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "drawio", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Excalidraw diagram. Block atom (image-backed). */
-const Excalidraw = Node.create({
-  name: "excalidraw",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes: diagramAttributes,
-  parseHTML() {
-    return [{ tag: 'div[data-type="excalidraw"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "excalidraw", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Multi-column layout container holding one or more `column` children. */
-const Columns = Node.create({
-  name: "columns",
-  group: "block",
-  content: "column+",
-  defining: true,
-  isolating: true,
-  addAttributes() {
-    return {
-      layout: {
-        default: "two_equal",
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-layout"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.layout ? { "data-layout": attrs.layout } : {},
-      },
-      widthMode: {
-        default: "normal",
-        parseHTML: (el: HTMLElement) =>
-          el.getAttribute("data-width-mode") || "normal",
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.widthMode && attrs.widthMode !== "normal"
-            ? { "data-width-mode": attrs.widthMode }
-            : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="columns"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "columns", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Single column within a `columns` layout. */
-const Column = Node.create({
-  name: "column",
-  group: "block",
-  content: "block+",
-  defining: true,
-  isolating: true,
-  selectable: false,
-  addAttributes() {
-    return {
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => {
-          const value = el.getAttribute("data-width");
-          return value ? parseFloat(value) : null;
-        },
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width ? { "data-width": attrs.width } : {},
-      },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="column"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "column", ...HTMLAttributes }, 0];
-  },
-});
-
-/**
- * Subpages listing block (auto-generated index of child pages). Docmost
- * declares no attributes; the markdown-converter has a `case "subpages"`, so
- * the read path can emit it and toYdoc must accept it. Block atom.
- */
-const Subpages = Node.create({
-  name: "subpages",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  parseHTML() {
-    return [{ tag: 'div[data-type="subpages"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "subpages", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Uploaded <audio> player. Block atom. Mirrors Docmost audio attrs. */
-const Audio = Node.create({
-  name: "audio",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      // Transient upload key Docmost declares with rendered:false; carried so
-      // a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: "audio" }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["audio", { controls: "true", ...HTMLAttributes }];
-  },
-});
-
-/** Embedded PDF viewer. Block atom. Mirrors Docmost pdf attrs. */
-const Pdf = Node.create({
-  name: "pdf",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  addAttributes() {
-    return {
-      src: {
-        default: "",
-        parseHTML: (el: HTMLElement) => el.getAttribute("src"),
-        renderHTML: (attrs: Record<string, any>) => ({ src: attrs.src ?? "" }),
-      },
-      name: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-name"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.name ? { "data-name": attrs.name } : {},
-      },
-      attachmentId: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-attachment-id"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.attachmentId
-            ? { "data-attachment-id": attrs.attachmentId }
-            : {},
-      },
-      size: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("data-size"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.size != null ? { "data-size": attrs.size } : {},
-      },
-      width: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("width"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.width != null ? { width: attrs.width } : {},
-      },
-      height: {
-        default: null,
-        parseHTML: (el: HTMLElement) => el.getAttribute("height"),
-        renderHTML: (attrs: Record<string, any>) =>
-          attrs.height != null ? { height: attrs.height } : {},
-      },
-      // Transient upload key Docmost declares with rendered:false; carried so
-      // a round-trip never hits "Unsupported attribute".
-      placeholder: { default: null },
-    };
-  },
-  parseHTML() {
-    return [{ tag: 'div[data-type="pdf"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "pdf", ...HTMLAttributes }, 0];
-  },
-});
-
-/** Page break (print/export divider). Block atom; Docmost declares no attrs. */
-const PageBreak = Node.create({
-  name: "pageBreak",
-  group: "block",
-  inline: false,
-  isolating: true,
-  atom: true,
-  defining: true,
-  draggable: true,
-  parseHTML() {
-    return [{ tag: 'div[data-type="pageBreak"]' }];
-  },
-  renderHTML({ HTMLAttributes }) {
-    return ["div", { "data-type": "pageBreak", ...HTMLAttributes }];
-  },
-});
-
-/**
- * Full extension list. Image is block-level (matches Docmost); the
- * ProseMirror DOM parser hoists <img> found inside <p> automatically.
- * StarterKit v3 already bundles the link extension, configured here.
- */
-export const docmostExtensions = [
-  StarterKit.configure({
-    codeBlock: {},
-    heading: {},
-    link: { openOnClick: false },
-  }),
-  // Stock @tiptap/extension-image has no caption attribute, so a round-trip
-  // through this schema would drop the data-caption the client TiptapImage
-  // emits. Mirror editor-ext image.ts: add a caption attribute that parses
-  // data-caption and re-renders it only when set (caption-less images stay
-  // clean), keeping the MCP markdown round-trip lossless.
-  Image.extend({
-    addAttributes() {
-      const parent = this.parent?.() ?? {};
-      return {
-        ...parent,
-        caption: {
-          default: undefined,
-          parseHTML: (el: HTMLElement) =>
-            el.getAttribute("data-caption") || undefined,
-          renderHTML: (attrs: Record<string, any>) =>
-            attrs.caption ? { "data-caption": attrs.caption } : {},
-        },
-      };
-    },
-  }).configure({ inline: false }),
-  TaskList,
-  TaskItem.configure({ nested: true }),
-  // Highlight stores its color unescaped and Docmost interpolates it into
-  // style="background-color: ${color}". Wrap the color attribute's parseHTML
-  // with the same allowlist guard used by textStyle so a crafted import color
-  // cannot break out of the style attribute. Multicolor behavior is preserved.
-  Highlight.extend({
-    addAttributes() {
-      const parent = this.parent?.() ?? {};
-      return {
-        ...parent,
-        color: {
-          ...(parent as Record<string, any>).color,
-          parseHTML: (el: HTMLElement) =>
-            sanitizeCssColor(
-              el.getAttribute("data-color") ||
-                getStyleProperty(el, "background-color") ||
-                el.style.backgroundColor,
-            ),
-        },
-      };
-    },
-  }).configure({ multicolor: true }),
-  Subscript,
-  Superscript,
-  // StarterKit does not provide a textStyle mark, so register ours; without it
-  // generateJSON drops <span style="color: ...">, defeating the color import.
-  TextStyle,
-  Comment,
-  Spoiler,
-  Callout,
-  Table,
-  TableRow,
-  TableCell,
-  TableHeader,
-  Mention,
-  FootnoteReference,
-  FootnotesList,
-  FootnoteDefinition,
-  MathInline,
-  MathBlock,
-  Details,
-  DetailsSummary,
-  DetailsContent,
-  Attachment,
-  Video,
-  Youtube,
-  Embed,
-  HtmlEmbed,
-  Drawio,
-  Excalidraw,
-  Columns,
-  Column,
-  Subpages,
-  Audio,
-  Pdf,
-  PageBreak,
-  DocmostAttributes,
-];
-
-/**
- * The ProseMirror schema for the docmost editor, built ONCE from
- * `docmostExtensions`. Pure and reused by every consumer (diff, collaboration
- * write-back) so the schema can never drift between call sites — it lives next
- * to the extension list it is derived from.
- */
-export const docmostSchema = getSchema(docmostExtensions);
diff --git a/packages/mcp/src/lib/footnote-analyze.ts b/packages/mcp/src/lib/footnote-analyze.ts
index b259ea00..11178d25 100644
--- a/packages/mcp/src/lib/footnote-analyze.ts
+++ b/packages/mcp/src/lib/footnote-analyze.ts
@@ -1,5 +1,5 @@
 /**
- * Footnote diagnostics for imported Markdown (issue #166).
+ * Legacy footnote diagnostics for imported Markdown (issue #166).
  *
  * A PURE, fence-aware text scan (independent of the Markdown->ProseMirror
  * conversion path, so it reports the same problems for `create_page`,
@@ -7,11 +7,18 @@
  * importer still creates the page; this only surfaces footnote problems to the
  * caller so an agent can fix its own markup instead of shipping broken footnotes.
  *
+ * SCOPE after #293 STEP 5: the canonical import form is now inline `^[body]`
+ * footnotes (handled by `@docmost/prosemirror-markdown`), where these problems
+ * cannot arise. This scan therefore targets the LEGACY reference-style
+ * (`[^id]` / `[^id]:`) markup, which is now inert on import (left as literal
+ * text). The warnings remain useful as an advisory nudge when an agent still
+ * authors the old syntax, but they no longer describe what the importer builds.
+ *
  * Detected problems:
  *  - danglingReferences: a `[^id]` reference with no `[^id]:` definition.
  *  - emptyDefinitions:   a `[^id]:` whose (kept) text is empty/whitespace.
  *  - duplicateDefinitions: an id defined by two or more `[^id]:` lines (only the
- *    first is kept on import — first-wins; see extractFootnotes).
+ *    first would have been kept under the old first-wins import).
  *  - referencesInTables: a `[^id]` marker found in a GFM table row (heuristic:
  *    the line, trimmed, starts with `|`) — footnotes in table cells often do not
  *    render as expected.
diff --git a/packages/mcp/src/lib/footnote-lex.ts b/packages/mcp/src/lib/footnote-lex.ts
index 30da676b..4a684e86 100644
--- a/packages/mcp/src/lib/footnote-lex.ts
+++ b/packages/mcp/src/lib/footnote-lex.ts
@@ -1,12 +1,14 @@
 /**
- * Shared, fence-aware line lexer for footnote markdown (MCP-internal).
+ * Shared, fence-aware line lexer for legacy footnote markdown (MCP-internal).
  *
- * Both the importer (`extractFootnotes` in collaboration.ts, which strips
- * definition lines and rebuilds a footnotes section) and the diagnostics
- * (`analyzeFootnotes` in footnote-analyze.ts) must agree EXACTLY on which lines
- * are definitions and which lines are inert (inside a code fence). Sharing one
- * lexer makes "the analyzer sees what the importer leaves" a structural property
- * instead of two hand-kept copies that can drift (#166 review).
+ * Since #293 STEP 5 the markdown -> ProseMirror IMPORT path lives in the shared
+ * `@docmost/prosemirror-markdown` package (inline `^[body]` footnotes), so this
+ * lexer no longer backs an mcp importer. It now backs ONLY the import-time
+ * diagnostics (`analyzeFootnotes` in footnote-analyze.ts), which still scan the
+ * raw markdown for legacy reference-style `[^id]:` definition lines and surface
+ * advisory warnings (duplicate/orphan definitions) about content that is now
+ * inert on import. Fence-awareness (a `[^id]:` line inside a ``` / ~~~ block is
+ * NOT a definition) is the property the analyzer relies on.
  *
  * NOTE: this is deliberately NOT shared with editor-ext's
  * `extractFootnoteDefinitions` — that lives in a different package and the
diff --git a/packages/mcp/src/lib/markdown-converter.ts b/packages/mcp/src/lib/markdown-converter.ts
index f9758ace..10a9f775 100644
--- a/packages/mcp/src/lib/markdown-converter.ts
+++ b/packages/mcp/src/lib/markdown-converter.ts
@@ -1,903 +1,12 @@
 /**
- * Convert ProseMirror/TipTap JSON content to Markdown
- * Supports all Docmost-specific node types and extensions
+ * ProseMirror -> Docmost-flavoured Markdown converter.
+ *
+ * #293 STEP 5: the converter CORE now lives in the shared
+ * `@docmost/prosemirror-markdown` package (the canonical, lossless
+ * implementation carrying every git-sync fix and the #293 canon decisions).
+ * MCP consumes it directly instead of keeping its own drifted copy, so the two
+ * can never diverge again. This file is a thin re-export shim kept only so the
+ * many existing `./markdown-converter.js` importers (client.ts, tests) do not
+ * have to move.
  */
-export function convertProseMirrorToMarkdown(content: any): string {
-  if (!content || !content.content) return "";
-
-  // Escape a value interpolated into an HTML double-quoted attribute value
-  // (textAlign, colors, image src, math `text`, all data-* attrs, etc.). In the
-  // ATTRIBUTE context only the quote that delimits the value and the ampersand
-  // that starts an entity are special, so we escape ONLY & " (and ' for safety
-  // when single-quoted delimiters are used). We deliberately do NOT escape < or
-  // >: the HTML re-parser (parse5/jsdom via @tiptap/html) does NOT decode
-  // &lt;/&gt; back inside attribute values, so escaping them would corrupt the
-  // stored data (e.g. a math node's LaTeX `a < b`) and ACCUMULATE escapes on
-  // every round-trip (`a < b` -> `a &lt; b` -> `a &amp;lt; b`). Escaping & "
-  // keeps the value inert against attribute-injection while staying idempotent.
-  // NOTE: escape ONLY & and " here. The value is always wrapped in double
-  // quotes, so " is the only delimiter; ' is NOT special in a double-quoted
-  // value, and parse5 does not decode &#39; back inside attribute values, so
-  // escaping ' would (like < >) corrupt the value and accumulate &amp; on every
-  // round-trip. Escaping & and " is idempotent (parse5 decodes them back).
-  const escapeAttr = (value: unknown): string =>
-    String(value)
-      .replace(/&/g, "&amp;")
-      .replace(/"/g, "&quot;");
-
-  // Escape a value placed as HTML element TEXT content (between tags), where
-  // <, >, and & are all significant. Used for text rendered inside raw-HTML
-  // blocks (table cells / columns) so stored characters cannot inject markup.
-  const escapeHtmlText = (value: unknown): string =>
-    String(value)
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;");
-
-  // Percent-encode characters that would break out of a markdown URL target
-  // (...) — whitespace/newlines and parentheses — so a stored src stays a
-  // single inert token (used for image/video/youtube srcs).
-  const encodeMdUrl = (value: unknown): string =>
-    String(value || "")
-      .replace(/\s/g, (c: string) => (c === " " ? "%20" : encodeURIComponent(c)))
-      .replace(/\(/g, "%28")
-      .replace(/\)/g, "%29");
-
-  const processNode = (node: any): string => {
-    const type = node.type;
-    const nodeContent = node.content || [];
-
-    switch (type) {
-      case "doc":
-        return nodeContent.map(processNode).join("\n\n");
-
-      case "paragraph":
-        const text = nodeContent.map(processNode).join("");
-        const align = node.attrs?.textAlign;
-        if (align && align !== "left") {
-          return `<div align="${escapeAttr(align)}">${text}</div>`;
-        }
-        return text || "";
-
-      case "heading":
-        const level = node.attrs?.level || 1;
-        const headingText = nodeContent.map(processNode).join("");
-        return "#".repeat(level) + " " + headingText;
-
-      case "text":
-        let textContent = node.text || "";
-        // Apply marks (bold, italic, code, etc.)
-        if (node.marks) {
-          // Markdown code spans (`...`) cannot carry inner formatting, so when a
-          // run has the `code` mark alongside ANY other mark, backtick syntax
-          // would leak literal ** / []() into the code text. In that case emit
-          // nested HTML (<code> innermost, the other marks wrapping it as HTML)
-          // so the output is at least well-formed and re-parseable.
-          //
-          // NOTE: this does NOT round-trip both marks. The schema's `code` mark
-          // has `excludes: "_"` (it excludes every other mark), so on import the
-          // co-occurring mark is always dropped — the run comes back as `code`
-          // only. We keep the emission simple and accept that the other mark is
-          // lost; preserving both is impossible while `code` excludes them.
-          // Only use the backtick form when `code` is the sole mark.
-          const markTypes = node.marks.map((m: any) => m.type);
-          const hasCode = markTypes.includes("code");
-          const codeCombined = hasCode && markTypes.length > 1;
-          for (const mark of node.marks) {
-            switch (mark.type) {
-              case "bold":
-                textContent = codeCombined
-                  ? `<strong>${textContent}</strong>`
-                  : `**${textContent}**`;
-                break;
-              case "italic":
-                textContent = codeCombined
-                  ? `<em>${textContent}</em>`
-                  : `*${textContent}*`;
-                break;
-              case "code":
-                // When combined with another mark, wrap as <code> so the
-                // surrounding HTML marks can nest around it; otherwise use the
-                // plain backtick span.
-                textContent = codeCombined
-                  ? `<code>${textContent}</code>`
-                  : `\`${textContent}\``;
-                break;
-              case "link": {
-                const href = mark.attrs?.href || "";
-                const title = mark.attrs?.title;
-                if (codeCombined) {
-                  // Emit an HTML anchor so it can wrap the nested <code>.
-                  const safeHref = escapeAttr(href);
-                  if (title) {
-                    textContent = `<a href="${safeHref}" title="${escapeAttr(String(title))}">${textContent}</a>`;
-                  } else {
-                    textContent = `<a href="${safeHref}">${textContent}</a>`;
-                  }
-                } else if (title) {
-                  // Emit the optional markdown link title; escape an embedded
-                  // double-quote so it cannot terminate the title string early.
-                  const safeTitle = String(title).replace(/"/g, '\\"');
-                  textContent = `[${textContent}](${href} "${safeTitle}")`;
-                } else {
-                  textContent = `[${textContent}](${href})`;
-                }
-                break;
-              }
-              case "strike":
-                textContent = codeCombined
-                  ? `<s>${textContent}</s>`
-                  : `~~${textContent}~~`;
-                break;
-              case "underline":
-                textContent = `<u>${textContent}</u>`;
-                break;
-              case "subscript":
-                textContent = `<sub>${textContent}</sub>`;
-                break;
-              case "superscript":
-                textContent = `<sup>${textContent}</sup>`;
-                break;
-              case "highlight": {
-                // Preserve a null/empty color as a plain highlight (a bare
-                // <mark> with no background-color); only emit the style when a
-                // color is actually set, so a plain highlight is not forced to
-                // yellow on export.
-                const color = mark.attrs?.color;
-                textContent = color
-                  ? `<mark style="background-color: ${escapeAttr(color)}">${textContent}</mark>`
-                  : `<mark>${textContent}</mark>`;
-                break;
-              }
-              case "textStyle":
-                if (mark.attrs?.color) {
-                  textContent = `<span style="color: ${escapeAttr(mark.attrs.color)}">${textContent}</span>`;
-                }
-                break;
-              case "comment": {
-                // Emit the inline comment anchor so highlights round-trip. The
-                // schema's Comment mark parses span[data-comment-id] (attrs
-                // commentId/resolved).
-                const cid = mark.attrs?.commentId;
-                if (cid) {
-                  const resolvedAttr = mark.attrs?.resolved
-                    ? ` data-resolved="true"`
-                    : "";
-                  textContent = `<span data-comment-id="${escapeAttr(cid)}"${resolvedAttr}>${textContent}</span>`;
-                }
-                break;
-              }
-              case "spoiler":
-                // Markdown has no native spoiler syntax, so emit the same
-                // lossless raw HTML the editor-ext turndown rule produces; the
-                // schema's Spoiler mark parses span[data-spoiler] back on import.
-                textContent = `<span data-spoiler="true">${textContent}</span>`;
-                break;
-            }
-          }
-        }
-        return textContent;
-
-      case "codeBlock":
-        const language = node.attrs?.language || "";
-        // Strip ALL trailing newlines so the export is idempotent: marked
-        // re-adds exactly one trailing "\n" on import, so trimming only one
-        // here would let the text grow by "\n" on each round-trip. Removing
-        // every trailing newline makes repeated cycles stable.
-        const code = nodeContent
-          .map(processNode)
-          .join("")
-          .replace(/\n+$/, "");
-        return "```" + language + "\n" + code + "\n```";
-
-      case "bulletList":
-        return nodeContent
-          .map((item: any) => processListItem(item, "-"))
-          .join("\n");
-
-      case "orderedList":
-        return nodeContent
-          .map((item: any, index: number) =>
-            processListItem(item, `${index + 1}.`),
-          )
-          .join("\n");
-
-      case "taskList":
-        return nodeContent.map((item: any) => processTaskItem(item)).join("\n");
-
-      case "taskItem":
-        // Delegate to the same helper used by taskList so multi-block and
-        // nested task items render and indent consistently.
-        return processTaskItem(node);
-
-      case "listItem":
-        return nodeContent.map(processNode).join("\n");
-
-      case "blockquote":
-        // Prefix EVERY line of EVERY child with "> " and separate block-level
-        // children with a blank ">" line so code blocks / multi-paragraph
-        // quotes round-trip correctly.
-        return nodeContent
-          .map((n: any) =>
-            processNode(n)
-              .split("\n")
-              .map((line: string) => (line.length ? `> ${line}` : ">"))
-              .join("\n"),
-          )
-          .join("\n>\n");
-
-      case "horizontalRule":
-        return "---";
-
-      case "hardBreak":
-        // Two trailing spaces before the newline encode a markdown hard break;
-        // a bare "\n" would be reimported as a soft break and lost.
-        return "  \n";
-
-      case "image": {
-        const imgAlt = node.attrs?.alt || "";
-        const imgCaption = node.attrs?.caption || "";
-        if (imgCaption) {
-          // ![]() can't carry a caption, so (symmetric to video) emit a raw
-          // <img> wrapped in a block <div>. On import marked.parse keeps the raw
-          // HTML and generateJSON runs the image extension's parseHTML, which
-          // restores the caption from data-caption.
-          const parts: string[] = [`src="${escapeAttr(node.attrs?.src ?? "")}"`];
-          if (imgAlt) parts.push(`alt="${escapeAttr(imgAlt)}"`);
-          parts.push(`data-caption="${escapeAttr(imgCaption)}"`);
-          return `<div><img ${parts.join(" ")}></div>`;
-        }
-        // Neutralize characters that could break out of the markdown image
-        // URL: spaces/newlines and parentheses would terminate the (...) target
-        // and let a stored src inject following markdown/HTML. Percent-encode
-        // them so the URL stays a single inert token.
-        const imgSrc = encodeMdUrl(node.attrs?.src);
-        return `![${imgAlt}](${imgSrc})`;
-      }
-
-      case "video": {
-        // Emit the schema-matching <video> element so generateJSON rebuilds the
-        // node with its attrs intact. The schema's parseHTML reads src/aria-label
-        // from the standard attributes and the remaining attrs from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.alt) parts.push(`aria-label="${escapeAttr(attrs.alt)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        // Wrap in a block <div> so marked treats it as a block (a bare <video>
-        // is inline-level HTML and marked wraps it in <p>, leaving a spurious
-        // empty paragraph beside the hoisted block atom). The wrapper has no
-        // data-type, so the schema parser ignores it and just hoists the video.
-        return `<div><video ${parts.join(" ")}></video></div>`;
-      }
-
-      case "youtube": {
-        // Emit the schema-matching div[data-type="youtube"]; the schema reads
-        // src from data-src and width/height/align from data-* attributes.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="youtube"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "table": {
-        // A GFM pipe table cannot represent merged cells. If ANY cell carries
-        // colspan>1 or rowspan>1, a pipe table would corrupt the grid on
-        // re-import, so emit the WHOLE table as raw HTML <table> instead: the
-        // schema's table family parseHTML (tag table/tr/td/th, with colspan/
-        // rowspan read from the same-named HTML attrs and align via parseHTML)
-        // round-trips it faithfully. Otherwise keep the lighter GFM pipe table.
-        const tableRows: any[] = nodeContent;
-        if (tableRows.length === 0) return "";
-        const hasSpan = tableRows.some((row: any) =>
-          (row.content || []).some(
-            (cell: any) =>
-              (cell.attrs?.colspan ?? 1) > 1 || (cell.attrs?.rowspan ?? 1) > 1,
-          ),
-        );
-
-        if (hasSpan) {
-          // Render each cell's block children to HTML (marked does NOT parse
-          // markdown inside a raw HTML block, so emitting markdown here would
-          // leak literal ** / `` into the cell). blockToHtml mirrors the schema
-          // HTML so inner formatting re-parses into the right marks/nodes.
-          const renderHtmlCell = (cell: any): string => {
-            const tag = cell.type === "tableHeader" ? "th" : "td";
-            const a = cell.attrs || {};
-            const cellParts: string[] = [];
-            if ((a.colspan ?? 1) > 1)
-              cellParts.push(`colspan="${escapeAttr(a.colspan)}"`);
-            if ((a.rowspan ?? 1) > 1)
-              cellParts.push(`rowspan="${escapeAttr(a.rowspan)}"`);
-            if (a.align) cellParts.push(`align="${escapeAttr(a.align)}"`);
-            const open = cellParts.length
-              ? `<${tag} ${cellParts.join(" ")}>`
-              : `<${tag}>`;
-            const inner = (cell.content || [])
-              .map((block: any) => blockToHtml(block))
-              .join("");
-            return `${open}${inner}</${tag}>`;
-          };
-          const htmlRows = tableRows
-            .map(
-              (row: any) =>
-                `<tr>${(row.content || []).map(renderHtmlCell).join("")}</tr>`,
-            )
-            .join("");
-          return `<table><tbody>${htmlRows}</tbody></table>`;
-        }
-
-        // No merged cells: emit a GFM table (header row + separator) so the
-        // markdown can be parsed back into a table on re-import.
-        const rows = tableRows.map(processNode);
-        const headerCells = tableRows[0]?.content || [];
-        const columns = headerCells.length || 1;
-        // Derive alignment markers (:--, :-:, --:) from each header cell.
-        const markers = Array.from({ length: columns }, (_, i) => {
-          const align = headerCells[i]?.attrs?.align;
-          switch (align) {
-            case "left":
-              return ":--";
-            case "center":
-              return ":-:";
-            case "right":
-              return "--:";
-            default:
-              return "---";
-          }
-        });
-        const separator = "| " + markers.join(" | ") + " |";
-        return [rows[0], separator, ...rows.slice(1)].join("\n");
-      }
-
-      case "tableRow":
-        return "| " + nodeContent.map(processNode).join(" | ") + " |";
-
-      case "tableCell":
-      case "tableHeader": {
-        // Join multiple block children with a space (not "") so adjacent blocks
-        // like a paragraph followed by a list don't collide into "line1- a".
-        // Then collapse newlines and escape pipes so a cell containing "|" or a
-        // line break cannot corrupt the surrounding GFM row.
-        return nodeContent
-          .map(processNode)
-          .join(" ")
-          .replace(/\r?\n/g, " ")
-          .replace(/\|/g, "\\|");
-      }
-
-      case "callout":
-        const calloutType = node.attrs?.type || "info";
-        const calloutContent = nodeContent.map(processNode).join("\n");
-        return `:::${calloutType.toLowerCase()}\n${calloutContent}\n:::`;
-
-      case "details":
-        return nodeContent.map(processNode).join("\n");
-
-      case "detailsSummary":
-        const summaryText = nodeContent.map(processNode).join("");
-        return `<details>\n<summary>${summaryText}</summary>\n`;
-
-      case "detailsContent":
-        const detailsText = nodeContent.map(processNode).join("\n");
-        return `${detailsText}\n</details>`;
-
-      case "mathInline": {
-        // The schema's `text` attribute has no parseHTML, so TipTap's default
-        // parser reads it from the `text` HTML attribute (NOT the element's text
-        // content). Emit span[data-type="mathInline"] carrying the LaTeX in a
-        // `text="..."` attribute so it round-trips. marked cannot parse $...$
-        // back, so the previous form was lossy.
-        const inlineMath = node.attrs?.text || "";
-        return `<span data-type="mathInline" data-katex="true" text="${escapeAttr(inlineMath)}"></span>`;
-      }
-
-      case "mathBlock": {
-        // Same as mathInline: the LaTeX must ride in the `text` HTML attribute
-        // for the schema's default parser to recover it.
-        const blockMath = node.attrs?.text || "";
-        return `<div data-type="mathBlock" data-katex="true" text="${escapeAttr(blockMath)}"></div>`;
-      }
-
-      case "mention": {
-        // Emit span[data-type="mention"] with the schema's data-* attributes so
-        // generateJSON rebuilds the mention node instead of leaving "@label"
-        // plain text that cannot re-parse.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="mention"`];
-        if (attrs.id) parts.push(`data-id="${escapeAttr(attrs.id)}"`);
-        if (attrs.label)
-          parts.push(`data-label="${escapeAttr(attrs.label)}"`);
-        if (attrs.entityType)
-          parts.push(`data-entity-type="${escapeAttr(attrs.entityType)}"`);
-        if (attrs.entityId)
-          parts.push(`data-entity-id="${escapeAttr(attrs.entityId)}"`);
-        if (attrs.slugId)
-          parts.push(`data-slug-id="${escapeAttr(attrs.slugId)}"`);
-        if (attrs.creatorId)
-          parts.push(`data-creator-id="${escapeAttr(attrs.creatorId)}"`);
-        if (attrs.anchorId)
-          parts.push(`data-anchor-id="${escapeAttr(attrs.anchorId)}"`);
-        // Keep the label as visible text content too; the schema reads attrs
-        // from data-*, so the inner text is purely cosmetic and harmless.
-        const mentionLabel = attrs.label || attrs.id || "";
-        // The label is visible element TEXT content here (the data-* attrs above
-        // 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
-        // schema-matching div[data-type="attachment"] with data-attachment-*
-        // attrs so the node round-trips instead of degrading to a markdown link.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="attachment"`,
-          `data-attachment-url="${escapeAttr(attrs.url ?? "")}"`,
-        ];
-        if (attrs.name)
-          parts.push(`data-attachment-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.mime)
-          parts.push(`data-attachment-mime="${escapeAttr(attrs.mime)}"`);
-        if (attrs.size != null)
-          parts.push(`data-attachment-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "drawio":
-      case "excalidraw": {
-        // Emit the schema-matching div[data-type=...] carrying the diagram's
-        // attrs as data-* (the schema's diagramAttributes reads src/title/alt/
-        // width/height/size/aspectRatio/align/attachmentId from data-*), so the
-        // diagram round-trips instead of degrading to a lossy placeholder.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="${type}"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.title != null)
-          parts.push(`data-title="${escapeAttr(attrs.title)}"`);
-        if (attrs.alt != null) parts.push(`data-alt="${escapeAttr(attrs.alt)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.aspectRatio != null)
-          parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "embed": {
-        // Emit the schema-matching div[data-type="embed"]; the schema reads
-        // src/provider/align/width/height from data-* attributes so the node
-        // (and its provider iframe info) survives the round-trip.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="embed"`,
-          `data-src="${escapeAttr(attrs.src ?? "")}"`,
-          `data-provider="${escapeAttr(attrs.provider ?? "")}"`,
-        ];
-        if (attrs.align)
-          parts.push(`data-align="${escapeAttr(attrs.align)}"`);
-        if (attrs.width != null)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`data-height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "audio": {
-        // Emit the schema-matching <audio> element (was emitting nothing). The
-        // schema reads src from src and attachmentId/size from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        // Wrap in a block <div> for the same reason as video: a bare <audio> is
-        // inline-level HTML that marked would wrap in <p>.
-        return `<div><audio ${parts.join(" ")}></audio></div>`;
-      }
-
-      case "pdf": {
-        // Emit the schema-matching div[data-type="pdf"] (was emitting nothing).
-        // The schema reads src/width/height from standard attrs and name/
-        // attachmentId/size from data-*.
-        const attrs = node.attrs || {};
-        const parts: string[] = [
-          `data-type="pdf"`,
-          `src="${escapeAttr(attrs.src ?? "")}"`,
-        ];
-        if (attrs.name) parts.push(`data-name="${escapeAttr(attrs.name)}"`);
-        if (attrs.attachmentId)
-          parts.push(
-            `data-attachment-id="${escapeAttr(attrs.attachmentId)}"`,
-          );
-        if (attrs.size != null)
-          parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-        if (attrs.width != null)
-          parts.push(`width="${escapeAttr(attrs.width)}"`);
-        if (attrs.height != null)
-          parts.push(`height="${escapeAttr(attrs.height)}"`);
-        return `<div ${parts.join(" ")}></div>`;
-      }
-
-      case "columns": {
-        // Emit the schema-matching div[data-type="columns"] wrapper so the
-        // multi-column layout survives. Without a case the children were
-        // concatenated with no separator and the text merged. The schema reads
-        // layout from data-layout and widthMode from data-width-mode. The whole
-        // block is raw HTML, so render children via blockToHtml (NOT markdown,
-        // which marked would not re-parse inside a raw HTML block).
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="columns"`];
-        if (attrs.layout)
-          parts.push(`data-layout="${escapeAttr(attrs.layout)}"`);
-        if (attrs.widthMode && attrs.widthMode !== "normal")
-          parts.push(`data-width-mode="${escapeAttr(attrs.widthMode)}"`);
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div ${parts.join(" ")}>${inner}</div>`;
-      }
-
-      case "column": {
-        // Emit the schema-matching div[data-type="column"]; the schema reads the
-        // column width from data-width. Children are rendered as HTML so their
-        // formatting survives inside this raw HTML block.
-        const attrs = node.attrs || {};
-        const parts: string[] = [`data-type="column"`];
-        if (attrs.width)
-          parts.push(`data-width="${escapeAttr(attrs.width)}"`);
-        const inner = nodeContent.map((n: any) => blockToHtml(n)).join("");
-        return `<div ${parts.join(" ")}>${inner}</div>`;
-      }
-
-      case "subpages":
-        return "{{SUBPAGES}}";
-
-      default:
-        // Fallback: process children
-        return nodeContent.map(processNode).join("");
-    }
-  };
-
-  // Render inline content (text runs + their marks) to HTML. Used by the raw
-  // HTML fallbacks (spanned tables, columns) where marked will NOT re-parse
-  // markdown, so backtick/asterisk/bracket syntax would otherwise leak as
-  // literal characters. Each mark is mirrored to the HTML the schema's parseHTML
-  // accepts so it re-imports as the matching ProseMirror mark.
-  const inlineToHtml = (inlineNodes: any[]): string =>
-    (inlineNodes || [])
-      .map((n: any) => {
-        if (n.type === "hardBreak") return "<br>";
-        if (n.type !== "text") {
-          // Inline atoms (mention, mathInline) already emit schema HTML.
-          return processNode(n);
-        }
-        let t = escapeHtmlText(n.text || "");
-        for (const mark of n.marks || []) {
-          switch (mark.type) {
-            case "bold":
-              t = `<strong>${t}</strong>`;
-              break;
-            case "italic":
-              t = `<em>${t}</em>`;
-              break;
-            case "code":
-              t = `<code>${t}</code>`;
-              break;
-            case "strike":
-              t = `<s>${t}</s>`;
-              break;
-            case "underline":
-              t = `<u>${t}</u>`;
-              break;
-            case "subscript":
-              t = `<sub>${t}</sub>`;
-              break;
-            case "superscript":
-              t = `<sup>${t}</sup>`;
-              break;
-            case "link":
-              t = `<a href="${escapeAttr(mark.attrs?.href || "")}">${t}</a>`;
-              break;
-            case "highlight":
-              t = mark.attrs?.color
-                ? `<mark style="background-color: ${escapeAttr(mark.attrs.color)}">${t}</mark>`
-                : `<mark>${t}</mark>`;
-              break;
-            case "textStyle":
-              if (mark.attrs?.color)
-                t = `<span style="color: ${escapeAttr(mark.attrs.color)}">${t}</span>`;
-              break;
-            case "comment":
-              // Inline comment anchor inside a raw-HTML container (columns /
-              // spanned table cells), so commented text there also round-trips.
-              if (mark.attrs?.commentId) {
-                const r = mark.attrs?.resolved ? ` data-resolved="true"` : "";
-                t = `<span data-comment-id="${escapeAttr(mark.attrs.commentId)}"${r}>${t}</span>`;
-              }
-              break;
-          }
-        }
-        return t;
-      })
-      .join("");
-
-  // Emit the schema-matching <img> for an image node. Shared so the image is
-  // emitted as real HTML wherever a raw-HTML container needs it (inside a column
-  // or a spanned table cell), where markdown `![](...)` would NOT be re-parsed
-  // and would survive as literal text. The Image extension reads src/alt from
-  // the standard attributes; the Docmost extra attrs (width/height/align/size/
-  // attachmentId/aspectRatio) are global attributes read from same-named DOM
-  // attributes, so emit them by name.
-  const imageToHtml = (node: any): string => {
-    const attrs = node.attrs || {};
-    const parts: string[] = [`src="${escapeAttr(attrs.src ?? "")}"`];
-    if (attrs.alt) parts.push(`alt="${escapeAttr(attrs.alt)}"`);
-    if (attrs.caption)
-      parts.push(`data-caption="${escapeAttr(attrs.caption)}"`);
-    if (attrs.title) parts.push(`title="${escapeAttr(attrs.title)}"`);
-    if (attrs.width != null) parts.push(`width="${escapeAttr(attrs.width)}"`);
-    if (attrs.height != null) parts.push(`height="${escapeAttr(attrs.height)}"`);
-    if (attrs.align) parts.push(`align="${escapeAttr(attrs.align)}"`);
-    if (attrs.size != null) parts.push(`data-size="${escapeAttr(attrs.size)}"`);
-    if (attrs.attachmentId)
-      parts.push(`data-attachment-id="${escapeAttr(attrs.attachmentId)}"`);
-    if (attrs.aspectRatio != null)
-      parts.push(`data-aspect-ratio="${escapeAttr(attrs.aspectRatio)}"`);
-    return `<img ${parts.join(" ")}>`;
-  };
-
-  // Emit the schema-matching div[data-type="callout"] for a callout node. The
-  // schema reads the banner type from data-callout-type. Children are rendered
-  // as HTML so they survive inside a raw-HTML container.
-  const calloutToHtml = (node: any): string => {
-    const type = (node.attrs?.type || "info").toLowerCase();
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<div data-type="callout" data-callout-type="${escapeAttr(type)}">${inner}</div>`;
-  };
-
-  // Emit a schema-matching <details> tree. The schema parses <details>,
-  // summary[data-type="detailsSummary"], and div[data-type="detailsContent"].
-  const detailsToHtml = (node: any): string => {
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<details>${inner}</details>`;
-  };
-  const detailsSummaryToHtml = (node: any): string =>
-    `<summary data-type="detailsSummary">${inlineToHtml(node.content || [])}</summary>`;
-  const detailsContentToHtml = (node: any): string => {
-    const inner = (node.content || []).map(blockToHtml).join("");
-    return `<div data-type="detailsContent">${inner}</div>`;
-  };
-
-  // Emit the schema-matching taskList/taskItem HTML. bridgeTaskLists (in
-  // collaboration.ts) recognizes ul[data-type="taskList"] with
-  // li[data-type="taskItem"][data-checked]; emitting that directly here keeps
-  // task lists inside columns/cells from degrading to literal "- [ ]" text.
-  const taskListToHtml = (node: any): string => {
-    const items = (node.content || [])
-      .map((it: any) => {
-        const checked = it.attrs?.checked ? "true" : "false";
-        return `<li data-type="taskItem" data-checked="${checked}">${blockChildrenToHtml(it)}</li>`;
-      })
-      .join("");
-    return `<ul data-type="taskList">${items}</ul>`;
-  };
-
-  // Render a block node to HTML for the raw-HTML containers (spanned tables,
-  // columns). marked does NOT re-parse markdown inside a raw-HTML block, so
-  // EVERY block type that can appear inside a column or a spanned cell must be
-  // emitted as schema-matching HTML here — never as markdown, or it would land
-  // as literal text on re-import. Nodes whose processNode case already produces
-  // schema-matching HTML (math/media/embed/attachment/nested columns/spanned
-  // table) are delegated to processNode; the markdown-emitting cases
-  // (image/blockquote/callout/details/hr/taskList) get explicit HTML here.
-  const blockToHtml = (block: any): string => {
-    const children = block.content || [];
-    switch (block.type) {
-      case "paragraph":
-        return `<p>${inlineToHtml(children)}</p>`;
-      case "heading": {
-        const level = block.attrs?.level || 1;
-        return `<h${level}>${inlineToHtml(children)}</h${level}>`;
-      }
-      case "bulletList":
-        return `<ul>${children
-          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
-          .join("")}</ul>`;
-      case "orderedList":
-        return `<ol>${children
-          .map((li: any) => `<li>${blockChildrenToHtml(li)}</li>`)
-          .join("")}</ol>`;
-      case "codeBlock": {
-        const lang = block.attrs?.language || "";
-        // The code itself is element TEXT content (between <code> tags), so it
-        // must escape < > & — NOT the attribute escaper. The language rides in
-        // a class ATTRIBUTE, so it uses escapeAttr.
-        const code = escapeHtmlText(
-          children
-            .map(processNode)
-            .join("")
-            .replace(/\n+$/, ""),
-        );
-        const cls = lang ? ` class="language-${escapeAttr(lang)}"` : "";
-        return `<pre><code${cls}>${code}</code></pre>`;
-      }
-      case "image":
-        return imageToHtml(block);
-      case "blockquote":
-        return `<blockquote>${children.map(blockToHtml).join("")}</blockquote>`;
-      case "horizontalRule":
-        return "<hr>";
-      case "callout":
-        return calloutToHtml(block);
-      case "details":
-        return detailsToHtml(block);
-      case "detailsSummary":
-        return detailsSummaryToHtml(block);
-      case "detailsContent":
-        return detailsContentToHtml(block);
-      case "taskList":
-        return taskListToHtml(block);
-      case "taskItem":
-        // A bare taskItem (outside a taskList) still needs a wrapping list so
-        // the schema parses it; wrap it in a single-item taskList.
-        return taskListToHtml({ content: [block] });
-      // table (incl. spanned), columns/column, math, media, embed, attachment,
-      // mention, etc. already emit schema-matching HTML from processNode.
-      case "table":
-      case "columns":
-      case "column":
-      case "mathBlock":
-      case "video":
-      case "audio":
-      case "pdf":
-      case "youtube":
-      case "embed":
-      case "attachment":
-      case "drawio":
-      case "excalidraw":
-        return processNode(block);
-      default:
-        // Any still-unhandled block type: NEVER fall back to markdown inside a
-        // raw-HTML block (it would become literal text). Wrap its rendered
-        // children in a <div> so their content is preserved; if it has no block
-        // children, render its inline content instead.
-        if (children.length && children.some((c: any) => c.type !== "text")) {
-          return `<div>${children.map(blockToHtml).join("")}</div>`;
-        }
-        return `<div>${inlineToHtml(children)}</div>`;
-    }
-  };
-
-  // Render the block children of a list item to HTML (a listItem holds block+
-  // content). Mirrors processListItem but for the HTML fallback path.
-  const blockChildrenToHtml = (item: any): string =>
-    (item.content || []).map((b: any) => blockToHtml(b)).join("");
-
-  // Indent the rendered children of a list item under a marker prefix.
-  // Each child block is a (possibly multi-line) string. The very first physical
-  // line of the first child carries the marker (e.g. "- " or "1. "); EVERY
-  // other line — the remaining lines of the first child AND all lines of every
-  // subsequent child (nested lists, code blocks, extra paragraphs) — is indented
-  // to align under the marker. Without indenting these continuation lines, the
-  // 2nd/3rd line of a nested child collapses to column 0 and escapes the list.
-  //
-  // The continuation indent MUST equal the LIST marker width, which is not the
-  // same as the visible prefix width:
-  //   - bullet "- "          -> 2 columns
-  //   - task   "- [ ] "      -> marker is still "- " (the "[ ] " is content), 2
-  //   - ordered "1. "/"10. " -> 3/4 columns, scaling with the number's digits
-  // CommonMark anchors nested content to the marker column, so an ordered item
-  // indented to only 2 columns would be re-parsed as a sibling/loose content on
-  // re-import. Callers therefore pass the exact indent width to use.
-  const indentItemChildren = (
-    childStrings: string[],
-    prefix: string,
-    indentWidth: number,
-  ): string => {
-    const indent = " ".repeat(indentWidth);
-    const lines: string[] = [];
-    childStrings.forEach((child, childIndex) => {
-      child.split("\n").forEach((line, lineIndex) => {
-        if (childIndex === 0 && lineIndex === 0) {
-          // First physical line of the first block gets the marker.
-          lines.push(`${prefix} ${line}`);
-        } else {
-          // Indent every continuation line by the marker width; keep blank
-          // lines blank rather than emitting trailing whitespace.
-          lines.push(line.length ? `${indent}${line}` : "");
-        }
-      });
-    });
-    return lines.join("\n");
-  };
-
-  const processListItem = (item: any, prefix: string): string => {
-    const itemContent = item.content || [];
-    const childStrings = itemContent.map(processNode);
-    if (childStrings.length === 0) return prefix;
-    // The rendered marker is `${prefix} ` (prefix + one space), so its width —
-    // and thus the continuation indent — is prefix.length + 1. This is correct
-    // for both bullet ("-" -> 2) and ordered ("1." -> 3, "10." -> 4) markers,
-    // since for those the visible prefix IS the list marker.
-    return indentItemChildren(childStrings, prefix, prefix.length + 1);
-  };
-
-  const processTaskItem = (item: any): string => {
-    const checked = item.attrs?.checked || false;
-    const checkbox = checked ? "[x]" : "[ ]";
-    const prefix = `- ${checkbox}`;
-    const itemContent = item.content || [];
-    const childStrings = itemContent.map(processNode);
-    // An empty task item still needs its checkbox marker; without this guard
-    // the indent below produces "" and the "- [ ]"/"- [x]" row disappears.
-    if (childStrings.length === 0) return prefix;
-    // The list marker for a task item is just "- " (2 columns); the "[ ] "/"[x] "
-    // checkbox is item content, NOT part of the marker. So the continuation
-    // indent is a fixed 2 — do NOT derive it from the wider prefix.length.
-    return indentItemChildren(childStrings, prefix, 2);
-  };
-
-  return processNode(content).trim();
-}
+export { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown";
diff --git a/packages/mcp/src/lib/markdown-document.ts b/packages/mcp/src/lib/markdown-document.ts
index b6bb004f..c744e117 100644
--- a/packages/mcp/src/lib/markdown-document.ts
+++ b/packages/mcp/src/lib/markdown-document.ts
@@ -1,136 +1,15 @@
 /**
- * Self-contained Docmost-flavoured Markdown document (custom extensions).
+ * Self-contained Docmost-flavoured Markdown document envelope (`docmost:meta` /
+ * `docmost:comments` blocks).
  *
- * A single `.md` file that packages everything needed to losslessly round-trip
- * a page through "download -> edit body -> re-upload":
- *   - a leading `docmost:meta` block: a one-line JSON object with page identity;
- *   - the Markdown body (carrying inline comment anchors and diagrams as HTML);
- *   - a trailing `docmost:comments` block: a one-line JSON array of comment
- *     threads.
- *
- * Both metadata blocks are HTML comments on purpose: `marked`/`generateJSON`
- * drop HTML comments, so even if the WHOLE file were ever fed straight to the
- * importer without first stripping the blocks, the metadata cannot leak into the
- * document. (A fenced ```docmost-comments``` block would WRONGLY become a
- * codeBlock node, so a fenced block is deliberately NOT used.)
- *
- * The delimiter literals may legitimately appear in the BODY too (e.g. a user
- * re-pastes an exported `.md` into a page, or a page documents this very
- * format). To stay robust, parsing treats only the FINAL, document-ending
- * `docmost:comments` block as metadata: it is the last `<!-- docmost:comments`
- * opener whose closing `-->` sits at the very end of the file. Any earlier
- * literal occurrence is left in the body untouched.
- *
- * NOTE on comments: in this version the comment THREAD records are preserved in
- * the file but are NOT pushed back to the server on import — only the inline
- * comment marks (anchors) embedded in the body are restored. Managing comment
- * records stays with the comment tools/UI.
+ * #293 STEP 5: this envelope is now owned by the shared
+ * `@docmost/prosemirror-markdown` package (the mcp copy was byte-identical to
+ * the package's, so re-exporting is lossless). Kept as a thin shim so the
+ * existing `./markdown-document.js` importers (client.ts, tests) do not move.
  */
-
-export interface DocmostMdMeta {
-  version: number;
-  pageId?: string;
-  slugId?: string;
-  title?: string;
-  spaceId?: string;
-  parentPageId?: string | null;
-}
-
-// Match the leading meta block (allow leading whitespace). Capture group 1 is
-// the JSON text between the markers.
-const META_RE = /^\s*<!--\s*docmost:meta\s*\n([\s\S]*?)\n-->/;
-// Match a `docmost:comments` opener. Used globally to scan for the LAST opener
-// rather than end-anchoring a single regex (which would mis-capture across a
-// literal opener that appears earlier in the body).
-const COMMENTS_OPEN_RE = /<!--[ \t]*docmost:comments[ \t]*\r?\n/g;
-
-/**
- * Assemble the full self-contained markdown file: meta block, body, and the
- * comments block. The meta block is always emitted; the comments block is always
- * emitted too (with `[]` when there are no comments) so the format stays uniform
- * and parsing stays simple.
- */
-export function serializeDocmostMarkdown(
-  meta: DocmostMdMeta,
-  body: string,
-  comments: any[],
-): string {
-  const metaJson = JSON.stringify(meta);
-  const commentsJson = JSON.stringify(Array.isArray(comments) ? comments : []);
-  const trimmedBody = (body ?? "").trim();
-  return (
-    `<!-- docmost:meta\n${metaJson}\n-->\n\n` +
-    `${trimmedBody}\n\n` +
-    `<!-- docmost:comments\n${commentsJson}\n-->\n`
-  );
-}
-
-/**
- * Split a self-contained file back into its parts. Tolerant: if the meta or
- * comments block is missing (e.g. a hand-written plain-markdown file), the
- * corresponding value is returned as `null` and the whole input is treated as
- * the body. This never throws on a MISSING block; only a `JSON.parse` failure
- * inside a block that IS present is surfaced as a thrown Error with a clear
- * message. Robust to `\r\n` line endings.
- */
-export function parseDocmostMarkdown(full: string): {
-  meta: DocmostMdMeta | null;
-  body: string;
-  comments: any[] | null;
-} {
-  // Normalize line endings so the anchored regexes work regardless of CRLF.
-  const normalized = (full ?? "").replace(/\r\n/g, "\n");
-
-  // Extract the leading meta block (start-anchored — already unambiguous).
-  let meta: DocmostMdMeta | null = null;
-  let metaEnd = 0;
-  const metaMatch = normalized.match(META_RE);
-  if (metaMatch) {
-    try {
-      meta = JSON.parse(metaMatch[1]);
-    } catch (e) {
-      throw new Error(
-        `Invalid docmost:meta JSON block: ${
-          e instanceof Error ? e.message : String(e)
-        }`,
-      );
-    }
-    // Body starts right after the matched meta block.
-    metaEnd = (metaMatch.index ?? 0) + metaMatch[0].length;
-  }
-
-  // Find the LAST `<!-- docmost:comments` opener; the real file-level block is
-  // the final one whose closing `-->` ends the document. Any earlier literal
-  // occurrence inside the body (e.g. a re-pasted export) is left in the body.
-  let lastOpenStart = -1;
-  let lastOpenEnd = -1;
-  let m: RegExpExecArray | null;
-  COMMENTS_OPEN_RE.lastIndex = 0;
-  while ((m = COMMENTS_OPEN_RE.exec(normalized)) !== null) {
-    lastOpenStart = m.index;
-    lastOpenEnd = m.index + m[0].length;
-  }
-
-  let comments: any[] | null = null;
-  let bodyEnd = normalized.length;
-  if (lastOpenStart !== -1) {
-    const rest = normalized.slice(lastOpenEnd);
-    const close = rest.match(/\r?\n-->[ \t]*\r?\n?\s*$/); // closer must end the doc
-    if (close) {
-      const jsonText = rest.slice(0, close.index);
-      try {
-        comments = JSON.parse(jsonText);
-      } catch (e) {
-        throw new Error(
-          `Invalid docmost:comments JSON block: ${
-            e instanceof Error ? e.message : String(e)
-          }`,
-        );
-      }
-      bodyEnd = lastOpenStart; // strip from the opener to end of document
-    }
-  }
-
-  const body = normalized.slice(metaEnd, bodyEnd).trim();
-  return { meta, body, comments };
-}
+export {
+  serializeDocmostMarkdown,
+  parseDocmostMarkdown,
+  serializeDocmostMarkdownBody,
+} from "@docmost/prosemirror-markdown";
+export type { DocmostMdMeta } from "@docmost/prosemirror-markdown";
diff --git a/packages/mcp/test/unit/collaboration.test.mjs b/packages/mcp/test/unit/collaboration.test.mjs
index 84801840..687e5d6e 100644
--- a/packages/mcp/test/unit/collaboration.test.mjs
+++ b/packages/mcp/test/unit/collaboration.test.mjs
@@ -127,36 +127,54 @@ test("markdownToProseMirror: an aligned GFM table maps header alignment", async
 });
 
 // Comment-body data-loss guard (#228 review #4): markdownToProseMirror is reused
-// for COMMENT bodies (createComment/updateComment), so it must NOT canonicalize —
-// a comment may legitimately carry a standalone footnote definition with no
-// matching reference, and canonicalization would drop the whole list (the text
-// would vanish). The page-write variant DOES canonicalize.
-test("markdownToProseMirror (comment path) PRESERVES a reference-less footnote definition", async () => {
+// for COMMENT bodies (createComment/updateComment), so it must NOT canonicalize.
+// Under the #293 canon, footnotes are INLINE (`^[body]`), so a comment can no
+// longer carry a reference-less definition to be dropped — but the comment path
+// must still (a) leave a legacy reference-style `[^id]:` line as harmless literal
+// TEXT (never silently deleted) and (b) preserve an inline footnote it does
+// contain (no canonicalization stripping it). The page-write variant canonicalizes.
+test("markdownToProseMirror (comment path) keeps a legacy `[^id]:` line as literal text", async () => {
+  // A reference-style `[^1]:` line is not canonical footnote syntax anymore, so it
+  // is not parsed into a footnote node — but its TEXT must survive verbatim (no
+  // data loss on the comment write path).
   const md = "A comment.\n\n[^1]: a standalone footnote definition";
   const doc = await markdownToProseMirror(md);
-  const defs = findAll(doc, "footnoteDefinition");
-  assert.equal(defs.length, 1, "the footnote definition must be preserved");
+  assert.equal(
+    findAll(doc, "footnoteDefinition").length,
+    0,
+    "reference-style line is not a footnote node",
+  );
   assert.match(
     JSON.stringify(doc),
     /a standalone footnote definition/,
-    "the definition text must survive the comment write path",
+    "the text must survive the comment write path",
   );
 });
 
-test("markdownToProseMirrorCanonical (page path) DROPS a reference-less footnote definition", async () => {
-  // Same input through the PAGE variant: with no reference, the canonical doc has
-  // no footnotesList (this is the page-side behavior the comment path must avoid).
-  const md = "A page.\n\n[^1]: a standalone footnote definition";
-  const doc = await markdownToProseMirrorCanonical(md);
-  assert.equal(findAll(doc, "footnotesList").length, 0);
-  assert.equal(findAll(doc, "footnoteDefinition").length, 0);
+test("markdownToProseMirror (comment path) PRESERVES an inline footnote (no canonicalization)", async () => {
+  // An inline `^[body]` footnote in a comment imports to a real footnote node and
+  // is NOT dropped: the comment path must never canonicalize away content.
+  const md = "A comment.\n\n^[an inline footnote]";
+  const doc = await markdownToProseMirror(md);
+  assert.equal(findAll(doc, "footnoteDefinition").length, 1);
+  assert.equal(findAll(doc, "footnotesList").length, 1);
+  assert.match(JSON.stringify(doc), /an inline footnote/);
 });
 
-test("markdownToProseMirrorCanonical still canonicalizes a real page footnote (order)", async () => {
-  // Page path must STILL canonicalize: refs b,a -> definitions reorder to b,a.
-  const md = "See[^b] then[^a].\n\n[^a]: alpha\n[^b]: bravo";
+test("markdownToProseMirrorCanonical (page path) yields a single reference-ordered list", async () => {
+  // Page path produces the canonical footnote topology: one trailing
+  // `footnotesList`, definitions in FIRST-REFERENCE order, ids assigned
+  // sequentially. Inline `^[body]` footnotes carry the body at the reference
+  // point, so the bottom list is inherently reference-ordered.
+  const md = "See^[bravo] then^[alpha].";
   const doc = await markdownToProseMirrorCanonical(md);
-  const defs = findAll(doc, "footnoteDefinition").map((d) => d.attrs.id);
-  assert.deepEqual(defs, ["b", "a"]);
+  const defs = findAll(doc, "footnoteDefinition");
+  assert.deepEqual(
+    defs.map((d) => d.attrs.id),
+    ["fn-1", "fn-2"],
+  );
   assert.equal(findAll(doc, "footnotesList").length, 1);
+  // Bodies stay in reference order (bravo referenced before alpha).
+  assert.match(JSON.stringify(defs[0]), /bravo/);
+  assert.match(JSON.stringify(defs[1]), /alpha/);
 });
diff --git a/packages/mcp/test/unit/docmost-md-roundtrip.test.mjs b/packages/mcp/test/unit/docmost-md-roundtrip.test.mjs
index 798bac10..b8b1293c 100644
--- a/packages/mcp/test/unit/docmost-md-roundtrip.test.mjs
+++ b/packages/mcp/test/unit/docmost-md-roundtrip.test.mjs
@@ -210,13 +210,17 @@ test("drawio round-trips through export and import", () => {
     ],
   };
 
+  // #293 canon #8: the media family (image/video/audio/drawio/excalidraw)
+  // serializes to the markdown image form `![alt](src)` plus a trailing
+  // discriminator comment `<!--drawio {json}-->` carrying the non-src attrs.
   const body = convertProseMirrorToMarkdown(doc);
-  assert.match(body, /data-type="drawio"/);
-  assert.match(body, /data-src="https:\/\/example\/diagram\.xml"/);
+  assert.match(body, /!\[\]\(https:\/\/example\/diagram\.xml\)/);
+  assert.match(body, /<!--drawio \{"attachmentId":"att-7"\}-->/);
 
   return markdownToProseMirror(body).then((rebuilt) => {
     const diagram = find(rebuilt, "drawio");
     assert.ok(diagram, "expected a drawio node after import");
     assert.equal(diagram.attrs.src, "https://example/diagram.xml");
+    assert.equal(diagram.attrs.attachmentId, "att-7");
   });
 });
diff --git a/packages/mcp/test/unit/footnote-canonicalize.test.mjs b/packages/mcp/test/unit/footnote-canonicalize.test.mjs
index e626b316..d7af244e 100644
--- a/packages/mcp/test/unit/footnote-canonicalize.test.mjs
+++ b/packages/mcp/test/unit/footnote-canonicalize.test.mjs
@@ -253,22 +253,23 @@ test("insertInlineFootnote: anchor in body BEFORE a nested list still inserts",
   assert.equal(findAll(r.doc, "footnotesList").length, 1);
 });
 
-test("markdown import (page path): out-of-order definitions render as a reference-ordered list", async () => {
-  // References appear b, a, c in the body; definitions are written in a, b, c
-  // order (the import order). The PAGE import path (markdownToProseMirrorCanonical)
-  // canonicalizes so the bottom list follows REFERENCE order — numbers read 1, 2,
-  // 3 down the list. (The non-canonicalizing markdownToProseMirror, used for
-  // comment bodies, would keep the import order; see collaboration.test.mjs.)
-  const md = [
-    "See[^b] then[^a] then[^c].",
-    "",
-    "[^a]: alpha",
-    "[^b]: bravo",
-    "[^c]: charlie",
-  ].join("\n");
+test("markdown import (page path): inline footnotes render as a reference-ordered list", async () => {
+  // Inline `^[body]` footnotes carry their body at the reference point, so the
+  // PAGE import path (markdownToProseMirrorCanonical) materializes the bottom
+  // list in REFERENCE order — numbers read 1, 2, 3 down the list — with ids
+  // assigned sequentially (fn-1, fn-2, fn-3).
+  const md = "See^[bravo] then^[alpha] then^[charlie].";
   const json = await markdownToProseMirrorCanonical(md);
-  assert.deepEqual(defIds(json), ["b", "a", "c"]);
+  assert.deepEqual(defIds(json), ["fn-1", "fn-2", "fn-3"]);
   assert.equal(findAll(json, "footnotesList").length, 1);
+  // Bodies materialize in reference order (bravo, alpha, charlie).
+  const defsJson = JSON.stringify(findAll(json, "footnoteDefinition"));
+  assert.ok(
+    defsJson.indexOf("bravo") <
+      defsJson.indexOf("alpha") &&
+      defsJson.indexOf("alpha") < defsJson.indexOf("charlie"),
+    "definitions follow reference order",
+  );
 });
 
 test("generateFootnoteId: valid uuidv7 shape (version 7, variant 8..b) and unique", () => {
diff --git a/packages/mcp/test/unit/footnotes.test.mjs b/packages/mcp/test/unit/footnotes.test.mjs
index 67ec9bc5..ab7c2c65 100644
--- a/packages/mcp/test/unit/footnotes.test.mjs
+++ b/packages/mcp/test/unit/footnotes.test.mjs
@@ -49,15 +49,19 @@ const footnoteDoc = {
   ],
 };
 
-test("JSON -> Markdown emits pandoc footnote syntax", () => {
+test("JSON -> Markdown emits canonical inline footnote syntax (#293 canon #2)", () => {
+  // Canonical markdown form is Pandoc/Obsidian INLINE footnotes: the note body is
+  // written at the reference point as `^[body]`. There is NO `[^id]` reference
+  // marker and NO trailing `[^id]: …` definition list; the schema id never
+  // reaches markdown.
   const md = convertProseMirrorToMarkdown(footnoteDoc);
-  assert.match(md, /\[\^fn1\]/);
-  assert.match(md, /\[\^fn2\]/);
-  assert.match(md, /\[\^fn1\]: First note\./);
-  assert.match(md, /\[\^fn2\]: Second note\./);
+  assert.match(md, /\^\[First note\.\]/);
+  assert.match(md, /\^\[Second note\.\]/);
+  assert.doesNotMatch(md, /\[\^/); // no reference-style markers
+  assert.doesNotMatch(md, /^\[\^.+\]:/m); // no bottom definition lines
 });
 
-test("Markdown -> JSON rebuilds footnote nodes", async () => {
+test("Markdown -> JSON rebuilds footnote nodes with sequential fn-N ids", async () => {
   const md = convertProseMirrorToMarkdown(footnoteDoc);
   const json = await markdownToProseMirror(md);
 
@@ -65,42 +69,39 @@ test("Markdown -> JSON rebuilds footnote nodes", async () => {
   const list = findAll(json, "footnotesList");
   const defs = findAll(json, "footnoteDefinition");
 
+  // Structure is preserved; ids are (re)assigned sequentially in first-reference
+  // order by the importer (fn-1, fn-2, …) — the concrete id is never carried in
+  // markdown, so it is derived on import.
   assert.equal(refs.length, 2);
   assert.deepEqual(
     refs.map((r) => r.attrs.id),
-    ["fn1", "fn2"],
+    ["fn-1", "fn-2"],
   );
   assert.equal(list.length, 1);
   assert.equal(defs.length, 2);
   assert.deepEqual(
     defs.map((d) => d.attrs.id),
-    ["fn1", "fn2"],
+    ["fn-1", "fn-2"],
   );
 });
 
-test("JSON -> MD -> JSON preserves footnote ids and text", async () => {
+test("JSON -> MD -> JSON is byte-stable and preserves footnote body 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\./);
+  // The round trip is byte-stable (ids are not written to markdown, so the
+  // concrete import id cannot perturb the output) and the bodies survive.
+  assert.equal(md2, md);
+  assert.match(md2, /\^\[First note\.\]/);
+  assert.match(md2, /\^\[Second note\.\]/);
 });
 
-test("repeated references REUSE one footnote; duplicate definitions are first-wins (#166)", async () => {
-  // Reuse semantics: many `[^d]` references + several `[^d]:` definitions import
-  // as ONE footnote — the references all keep id "d" (reuse), and only the FIRST
-  // definition is kept (first-wins). Deterministic and stable across re-imports.
-  const md = [
-    "See[^d] one[^d] two[^d].",
-    "",
-    "[^d]: first",
-    "[^d]: second",
-    "[^d]: third",
-  ].join("\n");
+test("identical footnote bodies MERGE to one shared definition (#293 canon #2)", async () => {
+  // Two references whose bodies are byte-identical import as ONE definition
+  // shared by both references (dedup on the exact body text). Two DIFFERENT
+  // bodies stay distinct. Deterministic and stable across re-imports.
+  const md = "See^[same] and^[same], but^[other].";
 
   const idsOf = async () => {
     const json = await markdownToProseMirror(md);
@@ -120,11 +121,11 @@ test("repeated references REUSE one footnote; duplicate definitions are first-wi
 
   // Stable across runs.
   assert.deepEqual(a, b);
-  // Reuse: all three reference markers stay "d".
-  assert.deepEqual(a.refs, ["d", "d", "d"]);
-  // First-wins: a single definition "d" with the FIRST text.
-  assert.deepEqual(a.defIds, ["d"]);
-  assert.equal(a.defText, "first");
+  // Merge: the two "same" references share fn-1; the "other" reference is fn-2.
+  assert.deepEqual(a.refs, ["fn-1", "fn-1", "fn-2"]);
+  // One definition per unique body, in first-reference order.
+  assert.deepEqual(a.defIds, ["fn-1", "fn-2"]);
+  assert.equal(a.defText, "same|other");
 });
 
 test("a [^id]: line inside a fenced code block is NOT treated as a definition", async () => {
diff --git a/packages/mcp/test/unit/markdown-converter.test.mjs b/packages/mcp/test/unit/markdown-converter.test.mjs
index 051a7e88..41ec4b00 100644
--- a/packages/mcp/test/unit/markdown-converter.test.mjs
+++ b/packages/mcp/test/unit/markdown-converter.test.mjs
@@ -70,7 +70,7 @@ test("hardBreak -> trailing two-spaces+newline", () => {
   assert.equal(convertProseMirrorToMarkdown(input), "line1  \nline2");
 });
 
-test("table cell with two block children joined by a space (and a pipe escaped)", () => {
+test("table cell with two block children falls back to a raw HTML table", () => {
   const input = doc({
     type: "table",
     content: [
@@ -86,11 +86,12 @@ test("table cell with two block children joined by a space (and a pipe escaped)"
     ],
   });
 
-  // Single-column header row + separator. The cell joins its two paragraphs
-  // with a space ("a|b c") then escapes the pipe -> "a\|b c".
+  // A pipe-table cell cannot represent two block children, so the canonical
+  // converter emits the whole table as raw HTML (lossless) rather than lossily
+  // flattening the paragraphs into one cell.
   assert.equal(
     convertProseMirrorToMarkdown(input),
-    "| a\\|b c |\n| --- |",
+    "<table><tbody><tr><td><p>a|b</p><p>c</p></td></tr></tbody></table>",
   );
 });
 
@@ -108,20 +109,20 @@ test("code block trailing newline trimmed", () => {
   );
 });
 
-test("textAlign value: delimiting double-quote escaped (attribute-safe, idempotent; < > left literal/inert)", () => {
+test("textAlign is carried in a trailing attached-comment directive (JSON-encoded, safe)", () => {
   const input = doc({
     type: "paragraph",
     attrs: { textAlign: 'right"><b' },
     content: [text("body")],
   });
 
-  // Attribute values escape only & and " so the value cannot break out of the
-  // quoted attribute. < and > are left literal: parse5/jsdom does NOT decode
-  // &lt;/&gt; inside attribute values, so escaping them would corrupt the value
-  // and accumulate on every round-trip. The literal < > are inert inside quotes.
+  // #293 canon #9: paragraph textAlign has no native markdown syntax, so it is
+  // attached as a trailing `<!--attrs {json}-->` comment on the block. The value
+  // is JSON-encoded, so a hostile value (`"`, `<`, `>`) is carried verbatim and
+  // inert — it cannot break out of the comment.
   assert.equal(
     convertProseMirrorToMarkdown(input),
-    '<div align="right&quot;><b">body</div>',
+    'body <!--attrs {"textAlign":"right\\"><b"}-->',
   );
 });
 
@@ -150,10 +151,10 @@ test("empty task item still emits its marker", () => {
   assert.equal(convertProseMirrorToMarkdown(input), "- [ ]\n- [x]");
 });
 
-// Image captions (issue #221). An image WITHOUT a caption stays the lossy-free
-// `![alt](src)`; WITH a caption it is emitted as a raw <img data-caption>
-// wrapped in a block <div> (symmetric to video) so the round-trip md -> html ->
-// json restores the caption via the image extension's parseHTML.
+// Image captions (issue #221 / #293 canon #8). An image WITHOUT a caption stays
+// the plain `![alt](src)`; WITH a caption (or any other non-src attr) the extra
+// attrs ride in a trailing `<!--img {json}-->` discriminator comment on the
+// markdown image form, so the round-trip md -> json restores them.
 test("image without a caption emits plain ![alt](src)", () => {
   const input = doc({
     type: "image",
@@ -162,24 +163,24 @@ test("image without a caption emits plain ![alt](src)", () => {
   assert.equal(convertProseMirrorToMarkdown(input), "![cat](/files/a.png)");
 });
 
-test("image with a caption emits a raw <img data-caption> in a block div", () => {
+test("image with a caption emits ![alt](src) plus an <!--img--> directive", () => {
   const input = doc({
     type: "image",
     attrs: { src: "/files/a.png", alt: "cat", caption: "A grey cat" },
   });
   assert.equal(
     convertProseMirrorToMarkdown(input),
-    '<div><img src="/files/a.png" alt="cat" data-caption="A grey cat"></div>',
+    '![cat](/files/a.png) <!--img {"caption":"A grey cat"}-->',
   );
 });
 
-test("image caption escapes & and \" in the data-caption attribute", () => {
+test("image caption is JSON-encoded in the <!--img--> directive (& and \" safe)", () => {
   const input = doc({
     type: "image",
     attrs: { src: "/files/a.png", caption: 'Tom & "Jerry"' },
   });
   assert.equal(
     convertProseMirrorToMarkdown(input),
-    '<div><img src="/files/a.png" data-caption="Tom &amp; &quot;Jerry&quot;"></div>',
+    '![](/files/a.png) <!--img {"caption":"Tom & \\"Jerry\\""}-->',
   );
 });
diff --git a/packages/mcp/test/unit/media-roundtrip-attrs.test.mjs b/packages/mcp/test/unit/media-roundtrip-attrs.test.mjs
index 37668fe0..f2b7ef82 100644
--- a/packages/mcp/test/unit/media-roundtrip-attrs.test.mjs
+++ b/packages/mcp/test/unit/media-roundtrip-attrs.test.mjs
@@ -55,8 +55,10 @@ test("round-trip: drawio diagram survives with src, title, dimensions, align, at
     },
     "drawio",
   );
-  // The converter must emit the schema-matching div[data-type="drawio"].
-  assert.match(md, /data-type="drawio"/);
+  // #293 canon #8: the media family serializes to the markdown image form plus a
+  // trailing discriminator comment carrying the non-src attrs.
+  assert.match(md, /^!\[\]\(\/api\/files\/d\.drawio\)/);
+  assert.match(md, /<!--drawio \{.*"attachmentId":"dz1".*\}-->/);
   assert.equal(found.length, 1, "drawio node must survive the round-trip");
   const a = found[0].attrs;
   assert.equal(a.src, "/api/files/d.drawio");
@@ -123,13 +125,19 @@ test("round-trip: pdf preserves width/height (standard attrs) plus name", async
 });
 
 // ---------------------------------------------------------------------------
-// Escaping: a src containing a double quote must survive the attribute-quoted
-// HTML emission (escapeAttr) and re-parse to the exact original value, with no
-// node loss and no HTML injection.
+// Escaping: a src containing a double quote must survive the markdown image form
+// with no node loss and no injection. In the `![](src)` link the URL is
+// normalized (a raw `"` percent-encodes to `%22`) on import — a semantically
+// equivalent, IDEMPOTENT normalization (it does not drift on further round
+// trips), not data loss.
 // ---------------------------------------------------------------------------
-test("round-trip: a src containing a double quote is escaped and recovered intact", async () => {
+test("round-trip: a src containing a double quote is normalized (idempotent) and survives", async () => {
   const tricky = 'https://e.com/x?a="b"&c=1';
+  const normalized = "https://e.com/x?a=%22b%22&c=1";
   const { found } = await roundtrip({ type: "youtube", attrs: { src: tricky } }, "youtube");
   assert.equal(found.length, 1, "node must survive a quote-bearing src");
-  assert.equal(found[0].attrs.src, tricky, "the exact src is recovered");
+  assert.equal(found[0].attrs.src, normalized, "the quote is percent-encoded in the URL");
+  // Idempotent: a second round trip from the normalized node is byte-stable.
+  const again = await roundtrip({ type: "youtube", attrs: { src: normalized } }, "youtube");
+  assert.equal(again.found[0].attrs.src, normalized);
 });
diff --git a/packages/mcp/test/unit/media-roundtrip.test.mjs b/packages/mcp/test/unit/media-roundtrip.test.mjs
index 9ef99602..9a99a75a 100644
--- a/packages/mcp/test/unit/media-roundtrip.test.mjs
+++ b/packages/mcp/test/unit/media-roundtrip.test.mjs
@@ -25,19 +25,15 @@ const findAll = (node, type, acc = []) => {
 };
 
 // ---------------------------------------------------------------------------
-// DATA-LOSS: atom block nodes with no converter case serialize to "" and the
-// whole block disappears from markdown export.
-//
-// markdown-converter.ts has a `default` branch (~line 601) that renders a node
-// as `nodeContent.map(processNode).join("")`. For a leaf/atom node (no
-// content) that yields "" — so the node (and ALL its attributes) is dropped.
-// `htmlEmbed` and `pageBreak` are both block atoms in docmost-schema.ts with no
-// case in the converter, so they vanish on markdown export.
-//
-// These tests assert the CURRENT (buggy) behavior and name it, so that when a
-// converter case is added the failing assertion flags the test for an update.
+// #293 canon: atom block nodes with no NATIVE markdown syntax are preserved via
+// dedicated converter forms (they used to serialize to "" and vanish — the old
+// mcp converter's data-loss gap, now fixed by consuming the shared package):
+//   - htmlEmbed  -> a raw `<div data-type="htmlEmbed" data-source=… data-height=…>`
+//                   block (source base64-encoded so arbitrary HTML is inert);
+//   - pageBreak  -> a standalone `<!--pagebreak-->` machinery comment (#5).
+// Both survive markdown export AND a full PM -> markdown -> PM round-trip.
 // ---------------------------------------------------------------------------
-test("DATA-LOSS: an htmlEmbed block is silently dropped from markdown export (no converter case)", () => {
+test("htmlEmbed block survives markdown export (source + height preserved)", () => {
   const input = doc(
     para(text("before")),
     { type: "htmlEmbed", attrs: { source: "<b>hi</b>", height: 200 } },
@@ -45,32 +41,31 @@ test("DATA-LOSS: an htmlEmbed block is silently dropped from markdown export (no
   );
   const md = convertProseMirrorToMarkdown(input);
 
-  // BUG: the htmlEmbed block, including its `source` and `height` attrs, is
-  // gone — only the surrounding paragraphs survive. If a future fix adds an
-  // htmlEmbed case, update this test to assert the block (or a placeholder)
-  // survives instead.
-  assert.equal(md, "before\n\n\n\nafter", "htmlEmbed currently disappears");
-  assert.ok(!md.includes("<b>hi</b>"), "the embed source is NOT preserved (data-loss)");
+  assert.match(md, /data-type="htmlEmbed"/);
+  assert.match(md, /data-height="200"/);
+  // The raw source is base64-encoded in data-source (not emitted verbatim), so
+  // the surrounding markdown cannot be corrupted by hostile embed HTML.
+  assert.match(md, /data-source="[^"]+"/);
+  assert.ok(md.includes("before") && md.includes("after"));
 });
 
-test("DATA-LOSS: an htmlEmbed does NOT round-trip (PM -> markdown -> PM loses the node)", async () => {
+test("htmlEmbed round-trips PM -> markdown -> PM (node + source recovered)", async () => {
   const input = doc(
     para(text("x")),
     { type: "htmlEmbed", attrs: { source: "<i>raw</i>", height: 120 } },
   );
   const out = await markdownToProseMirror(convertProseMirrorToMarkdown(input));
-  assert.equal(
-    findAll(out, "htmlEmbed").length,
-    0,
-    "htmlEmbed is lost across a markdown round-trip (known data-loss gap)",
-  );
+  const embeds = findAll(out, "htmlEmbed");
+  assert.equal(embeds.length, 1, "htmlEmbed survives the markdown round-trip");
+  assert.equal(embeds[0].attrs.source, "<i>raw</i>", "source recovered intact");
 });
 
-test("DATA-LOSS: a pageBreak block is silently dropped from markdown export (no converter case)", () => {
+test("pageBreak block survives markdown export and round-trips", async () => {
   const input = doc(para(text("a")), { type: "pageBreak" }, para(text("b")));
   const md = convertProseMirrorToMarkdown(input);
-  // BUG: pageBreak (a block atom with no converter case) disappears.
-  assert.equal(md, "a\n\n\n\nb", "pageBreak currently disappears");
+  assert.match(md, /<!--pagebreak-->/);
+  const out = await markdownToProseMirror(md);
+  assert.equal(findAll(out, "pageBreak").length, 1);
 });
 
 // ---------------------------------------------------------------------------
diff --git a/packages/mcp/test/unit/roundtrip.test.mjs b/packages/mcp/test/unit/roundtrip.test.mjs
index 1b80e554..08ae6219 100644
--- a/packages/mcp/test/unit/roundtrip.test.mjs
+++ b/packages/mcp/test/unit/roundtrip.test.mjs
@@ -165,3 +165,67 @@ test("import: a colored mention span keeps the mention node", async () => {
   const out = await markdownToProseMirror('<span data-type="mention" data-id="u1" data-label="Alice" style="color: blue">@Alice</span>');
   assert.equal(findNodes(out, "mention").length, 1, "mention node must survive a colored span");
 });
+
+// ---------------------------------------------------------------------------
+// #293 STEP 5 canon safety net. These assert STRUCTURE/content preservation
+// (format-agnostic: the node/mark and its value survive PM -> markdown -> PM,
+// and the markdown is idempotent), NOT the exact markdown bytes — so they stay
+// valid regardless of the concrete canonical spelling. They cover the node/mark
+// types whose canonical markdown form changed in #293 (highlight-without-color,
+// textAlign, subpages, inline footnotes) and complement the existing math /
+// media / mention / column round-trips above.
+// ---------------------------------------------------------------------------
+test("round-trip: highlight WITHOUT a color survives as a highlight mark (==)", async () => {
+  const input = doc(para(text("hi", [{ type: "highlight", attrs: { color: null } }])));
+  const md = convertProseMirrorToMarkdown(input);
+  const out = await roundtrip(input);
+  const hit = findNodes(out, "text").find(
+    (n) => n.text === "hi" && (n.marks || []).some((m) => m.type === "highlight"),
+  );
+  assert.ok(hit, "the highlight mark must survive a color-less round-trip");
+  // Idempotent markdown.
+  assert.equal(convertProseMirrorToMarkdown(out), md);
+});
+
+test("round-trip: paragraph textAlign survives via the attached-comment directive", async () => {
+  const input = doc({
+    type: "paragraph",
+    attrs: { textAlign: "center" },
+    content: [text("mid")],
+  });
+  const md = convertProseMirrorToMarkdown(input);
+  const out = await roundtrip(input);
+  const p = findNodes(out, "paragraph").find((n) => n.attrs && n.attrs.textAlign === "center");
+  assert.ok(p, "textAlign must be restored on the paragraph");
+  assert.equal(convertProseMirrorToMarkdown(out), md, "textAlign round-trip is idempotent");
+});
+
+test("round-trip: subpages atom survives", async () => {
+  const input = doc({ type: "subpages" });
+  const out = await roundtrip(input);
+  assert.equal(findNodes(out, "subpages").length, 1, "subpages node must survive");
+});
+
+test("round-trip: inline footnote survives with body text (canonical structure)", async () => {
+  const input = doc(
+    para(text("Claim"), { type: "footnoteReference", attrs: { id: "fnA" } }),
+    {
+      type: "footnotesList",
+      content: [
+        {
+          type: "footnoteDefinition",
+          attrs: { id: "fnA" },
+          content: [para(text("the evidence"))],
+        },
+      ],
+    },
+  );
+  const md = convertProseMirrorToMarkdown(input);
+  const out = await roundtrip(input);
+  assert.equal(findNodes(out, "footnoteReference").length, 1);
+  assert.equal(findNodes(out, "footnotesList").length, 1);
+  assert.equal(findNodes(out, "footnoteDefinition").length, 1);
+  assert.match(JSON.stringify(out), /the evidence/, "footnote body survives");
+  // Byte-stable (the schema id is never written to markdown).
+  assert.equal(convertProseMirrorToMarkdown(out), md);
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1f623946..a861cb0f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -953,6 +953,9 @@ importers:
 
   packages/mcp:
     dependencies:
+      '@docmost/prosemirror-markdown':
+        specifier: workspace:*
+        version: link:../prosemirror-markdown
       '@fellow/prosemirror-recreate-transform':
         specifier: ^1.2.3
         version: 1.2.3
-- 
2.52.0


From 1a7b817250fcb4b5d0e81025592b3d7af5c40462 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 12:17:31 +0300
Subject: [PATCH 12/17] fix(prosemirror-markdown): escape image alt +
 consolidate schema sanitizers + tidy (#333 review F1-F4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

F1 [critical, data-loss] — escape the image alt in `![alt](src)`. Canon #4 moved
the top-level image off the lossless <img> form onto markdown `![alt](src)`, but
the alt was inserted raw; the importer re-parses the `![alt]` label as CommonMark
inline, so a markdown-active char in a realistic description ("Figure [1]", "the
*new* logo", "a]b[c") broke the round-trip — the image node vanished or emphasis
collapsed. Now `escapeLinkText(imgAttrs.alt ?? "")`, exactly as the link-form
media (attachment/pdf/embed) already escape their visible text. Regression test
added: six active-punctuation alts round-trip byte-stable with the node intact.

F2 [drift] — re-export `clampCalloutType` / `sanitizeCssColor` from the package
barrel and drop the verbatim copies in the mcp schema shim. The copies had
already drifted (the mcp `clampCalloutType` lost the callout-type alias mapping
the package applies), which is exactly the schema drift #293 exists to kill. The
sanitizers now live only in the package; mcp `schema.test.mjs` exercises the
single alias-aware implementation.

F3 [docs] — AGENTS.md:296 said `packages/mcp/build/` is committed; this branch
gitignored it (git-sync/prosemirror-markdown convention). Updated the line to say
it is gitignored and rebuilt in CI/Docker via `pnpm build`.

F4 [cleanup] — removed the dead `test.typecheck` block from the package
vitest.config.ts and deleted tsconfig.vitest.json. Both were copied verbatim from
git-sync; this package has zero `*.test-d.ts` files, and the ported comments
referenced git-sync-only entities. Kept the `docmost-client` resolve alias
(22 tests use it) and the runtime include/environment.

package vitest: 658 passed (+1 F1 regression); tsc clean. git-sync: 268 passed.
mcp: node --test 454 passed; tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 AGENTS.md                                     |  2 +-
 packages/mcp/src/lib/docmost-schema.ts        | 50 ++++---------------
 .../prosemirror-markdown/src/lib/index.ts     |  4 ++
 .../src/lib/markdown-converter.ts             |  7 ++-
 .../test/image-comment.test.ts                | 15 ++++++
 .../prosemirror-markdown/tsconfig.vitest.json | 15 ------
 .../prosemirror-markdown/vitest.config.ts     | 17 -------
 7 files changed, 37 insertions(+), 73 deletions(-)
 delete mode 100644 packages/prosemirror-markdown/tsconfig.vitest.json

diff --git a/AGENTS.md b/AGENTS.md
index 1a13dea6..2b91446b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -293,7 +293,7 @@ Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirro
 - The version string shown in the UI comes from `APP_VERSION` (CI/Docker) or `git describe --tags --always` (local), resolved in `vite.config.ts` — not from `package.json`.
 - Server TS config is permissive (`noImplicitAny: false`, `strictNullChecks: false`, `no-explicit-any` lint disabled). Follow the existing relaxed style rather than tightening types broadly.
 - Dependency versions are heavily pinned via `pnpm.overrides` and `pnpm.patchedDependencies` (`scimmy`, `yjs`) in the root `package.json`. Don't bump pinned/patched deps casually; the patches and overrides exist for compatibility/security reasons.
-- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). Remember `packages/mcp/build/` is committed — rebuild after editing.
+- **Adding/renaming/removing an MCP tool requires updating `SERVER_INSTRUCTIONS`** in `packages/mcp/src/index.ts` — the intent-routing guide MCP clients receive on initialize. This applies both to inline `server.registerTool(...)` calls in `index.ts` and to specs in `packages/mcp/src/tool-specs.ts`. Enforced by `packages/mcp/test/unit/server-instructions.test.mjs`, which fails when a registered tool is not mentioned in the guide (deliberate opt-outs go into its `EXCEPTIONS` list). `packages/mcp/build/` is gitignored and rebuilt in CI/Docker via `pnpm build` (same convention as `git-sync`/`prosemirror-markdown`) — never commit it; rebuild locally after editing to run the tests.
 
 ## CI / release
 
diff --git a/packages/mcp/src/lib/docmost-schema.ts b/packages/mcp/src/lib/docmost-schema.ts
index 1438f8d7..200c4649 100644
--- a/packages/mcp/src/lib/docmost-schema.ts
+++ b/packages/mcp/src/lib/docmost-schema.ts
@@ -12,15 +12,20 @@
  * every consumer (diff, collaboration write-back) so the schema is identical at
  * every call site.
  *
- * The package does NOT re-export the two small mcp-only sanitizer helpers
- * (`clampCalloutType`, `sanitizeCssColor`) through its public barrel, so they
- * are preserved verbatim here (they are pure and used by mcp code/tests). The
- * package's schema uses its own internally-identical copies for parsing.
+ * The two schema sanitizers (`clampCalloutType`, `sanitizeCssColor`) are
+ * re-exported from the package's public barrel — they must NOT be re-defined
+ * here, or the mcp copy drifts from the package's (it already had: the local
+ * copy had lost the callout-type alias mapping the package applies). Single
+ * source of truth in the package (#326 invariant #2).
  */
 import { getSchema } from "@tiptap/core";
-import { docmostExtensions } from "@docmost/prosemirror-markdown";
+import {
+  docmostExtensions,
+  clampCalloutType,
+  sanitizeCssColor,
+} from "@docmost/prosemirror-markdown";
 
-export { docmostExtensions };
+export { docmostExtensions, clampCalloutType, sanitizeCssColor };
 
 /**
  * The ProseMirror schema for the docmost editor, built ONCE from
@@ -28,36 +33,3 @@ export { docmostExtensions };
  * write-back) so the schema can never drift between call sites.
  */
 export const docmostSchema = getSchema(docmostExtensions);
-
-/** Allowed Docmost callout types; anything else falls back to "info". */
-const CALLOUT_TYPES = ["info", "warning", "danger", "success"];
-export const clampCalloutType = (value: string | null | undefined): string =>
-  value && CALLOUT_TYPES.includes(value.toLowerCase())
-    ? value.toLowerCase()
-    : "info";
-
-/**
- * Allowlist guard for CSS color values imported from HTML.
- *
- * Docmost interpolates stored mark colors straight into an inline style
- * attribute (e.g. style="background-color: ${color}" / "color: ${color}").
- * An unsanitized value such as `red; --x: url(...)` or `red"><script>` would
- * let a crafted document break out of the style attribute. We therefore only
- * accept a narrow, well-formed subset of CSS <color> syntax and reject (-> null)
- * anything else.
- *
- * Accepted forms:
- *   - named colors:           letters only, e.g. "red", "rebeccapurple"
- *   - hex:                    #rgb, #rgba, #rrggbb, #rrggbbaa
- *   - functional notation:    rgb()/rgba()/hsl()/hsla() containing only
- *                             digits, %, ., commas, spaces and slashes
- */
-const SAFE_COLOR_RE =
-  /^(?:[a-zA-Z]+|#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgb|rgba|hsl|hsla)\([0-9.,%/\s]+\))$/;
-export const sanitizeCssColor = (
-  value: string | null | undefined,
-): string | null => {
-  if (typeof value !== "string") return null;
-  const color = value.trim();
-  return color && SAFE_COLOR_RE.test(color) ? color : null;
-};
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
index 8cdf55cc..10bb757d 100644
--- a/packages/prosemirror-markdown/src/lib/index.ts
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -24,6 +24,10 @@ export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 // schema the converter targets.
 export { docmostExtensions } from "./docmost-schema.js";
 
+// Schema-adjacent sanitizers used by consumers (mcp) so the single canonical,
+// alias-aware / allowlist implementations live ONLY here (no drifting copies).
+export { clampCalloutType, sanitizeCssColor } from "./docmost-schema.js";
+
 // Attached-comment convention (#293 canon #9/#4/#8): the reusable primitives
 // the serializer/parser use to encode attrs that have no native markdown syntax
 // as trailing `<!--name {json}-->` comments.
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index dd928e14..d19dadd4 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -599,7 +599,12 @@ export function convertProseMirrorToMarkdown(content: any): string {
         // title) are carried in an attached `<!--img {…}-->` comment on the SAME
         // line, materialized back onto the <img> by markdown-to-prosemirror's
         // applyCommentDirectives before generateJSON drops the comment.
-        const imgAlt = imgAttrs.alt || "";
+        // Escape the alt text: it sits in the `![alt]` label, which the importer
+        // re-parses as CommonMark inline content, so a markdown-active char in a
+        // realistic description ("Figure [1]", "the *new* logo") would break the
+        // round-trip — the image node vanishes / emphasis collapses. Same reason
+        // the link-form media (attachment/pdf/embed) escape their visible text.
+        const imgAlt = escapeLinkText(imgAttrs.alt ?? "");
         // Neutralize characters that could break out of the markdown image
         // URL: spaces/newlines and parentheses would terminate the (...) target
         // and let a stored src inject following markdown/HTML. Percent-encode
diff --git a/packages/prosemirror-markdown/test/image-comment.test.ts b/packages/prosemirror-markdown/test/image-comment.test.ts
index 77e9cb92..6f4974cb 100644
--- a/packages/prosemirror-markdown/test/image-comment.test.ts
+++ b/packages/prosemirror-markdown/test/image-comment.test.ts
@@ -57,6 +57,21 @@ describe('#293 canon #4 — image serialization + attached img-comment', () => {
     expect(img.attrs.alt).toBe('схема');
   });
 
+  it('alt with markdown-ACTIVE punctuation is escaped and round-trips byte-stable (F1)', async () => {
+    // The alt sits in the `![alt]` label, re-parsed as CommonMark inline on
+    // import; without escaping, a bracket/emphasis in a realistic description
+    // would make the image node VANISH or collapse emphasis. Assert the image
+    // survives with the exact alt AND the markdown is byte-stable on re-export.
+    for (const alt of ['a]b[c', 'Figure [1]', 'the *new* logo', 'x_y_z', 'see ![img', 'a & b']) {
+      const md1 = convertProseMirrorToMarkdown(image({ alt }));
+      const back = await markdownToProseMirror(md1);
+      const img = findImage(back);
+      expect(img).toBeTruthy(); // image node did NOT vanish
+      expect(img.attrs.alt).toBe(alt); // exact alt preserved
+      expect(convertProseMirrorToMarkdown(back)).toBe(md1); // byte-stable
+    }
+  });
+
   it('align "center" (the default) emits a bare image, NO comment, round-trips to center', async () => {
     const { md, img } = await roundTrip(image({ align: 'center' }));
     expect(md).toBe('![](/i.png)');
diff --git a/packages/prosemirror-markdown/tsconfig.vitest.json b/packages/prosemirror-markdown/tsconfig.vitest.json
deleted file mode 100644
index 5a116942..00000000
--- a/packages/prosemirror-markdown/tsconfig.vitest.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  // Test-infra tsconfig used ONLY by vitest's `test.typecheck` pass (Finding #1).
-  // The build tsconfig (`tsconfig.json`) scopes the compiler to `src/**` with
-  // `rootDir: ./src`, so it never type-checks the `test/` tree. This config
-  // inherits the same strict compiler options but widens the file set to the
-  // type-test files so `vitest run` can run `tsc` over them. It is NOT used by
-  // `npm run build` (that still uses `tsconfig.json`), so it has no effect on the
-  // shipped output.
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "rootDir": "."
-  },
-  "include": ["test/**/*.test-d.ts", "src/**/*"]
-}
diff --git a/packages/prosemirror-markdown/vitest.config.ts b/packages/prosemirror-markdown/vitest.config.ts
index 1c63f4e3..33d0fbe4 100644
--- a/packages/prosemirror-markdown/vitest.config.ts
+++ b/packages/prosemirror-markdown/vitest.config.ts
@@ -18,23 +18,6 @@ export default defineConfig({
   },
   test: {
     environment: 'node',
-    // Runtime suites. The `.test.ts` glob deliberately EXCLUDES the type-only
-    // contract file (`*.test-d.ts`), which is enforced by the typecheck pass
-    // below instead — so the 35 runtime suites are never typechecked.
     include: ['test/**/*.test.ts'],
-    // Type-level contract enforcement (Finding #1). Vitest runs `tsc` over the
-    // `.test-d.ts` files so the `expectTypeOf`/`@ts-expect-error` guards in
-    // git-sync-client.contract.test-d.ts become REAL build-time assertions: a
-    // drift in the GitSyncClient result shapes makes `npx vitest run` FAIL with
-    // a type error. Scoped to `*.test-d.ts` so the runtime suites stay
-    // untouched, and pointed at the package tsconfig for the strict options.
-    typecheck: {
-      enabled: true,
-      include: ['test/**/*.test-d.ts'],
-      // A dedicated test-infra tsconfig (NOT the build one) that widens the file
-      // set to include `test/**` — the build tsconfig scopes `tsc` to `src/**`
-      // (rootDir ./src), so without this the type-test file is never checked.
-      tsconfig: './tsconfig.vitest.json',
-    },
   },
 });
-- 
2.52.0


From 08222345ef83bedf331948f934c6a76b074b984f Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 12:46:30 +0300
Subject: [PATCH 13/17] fix(prosemirror-markdown): escape canon
 inline-extension triggers = $ ^ in link/alt text (#333 review F5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

F1 (round 1) wrapped the image alt in escapeLinkText, and that helper also guards
the link-form media captions (attachment/pdf/embed). But its character class
covered only stock CommonMark — NOT the Docmost inline EXTENSIONS this same PR
registers on the marked instance: highlight `==x==` (canon #7), math `$x$`
(canon #6), footnote `^[x]` (canon #2). Their triggers `= $ ^` are not CommonMark
punctuation, so an alt or media filename like `x $A$ y`, `use ==bold==`, `^[fn]`,
or `data $A$.csv` was silently turned into a math/highlight/footnote node on
import — the same class of round-trip data loss F1 closed, reintroduced by this
PR's own canon.

Fix: add `= $ ^` to the escapeLinkText class (`/[\\`*_~[\]<&!()=$^]/g`). `\= \$ \^`
decode back to literals (all ASCII punctuation) AND, being escape tokens, stop
the extension tokenizer from matching — verified lossless byte-stable round-trip.
Updated the helper comment to name the two trigger sets (CommonMark + Docmost
inline extensions). Extended the adversarial round-trip tests: image alt gains
`x $A$ y` / `5$ and 10$` / `use ==bold==` / `^[fn]` / `cost $5 == price`; pdf name
gains `data $A$.csv` / `q3 ==final==.pdf` / `5$ and 10$.pdf` / `note ^[x].pdf` —
all byte-stable with the node intact, so the hole can't reopen.

package vitest: 658 passed; tsc clean. git-sync: 268. mcp: 454.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/lib/markdown-converter.ts             | 35 ++++++++++---------
 .../test/image-comment.test.ts                |  8 ++++-
 .../test/media-comments.test.ts               |  7 ++++
 3 files changed, 33 insertions(+), 17 deletions(-)

diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index d19dadd4..63c39333 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -78,23 +78,26 @@ export function convertProseMirrorToMarkdown(content: any): string {
       .replace(/\(/g, "%28")
       .replace(/\)/g, "%29");
 
-  // Backslash-escape every character a markdown link's `[text]` label would
-  // otherwise INTERPRET, so a link-form media node's visible text (a filename or
-  // provider carried in `attrs.name`/`attrs.provider`) round-trips byte-exact
-  // (#293 canon #8 link-form). Escaping only `[ ] \` is NOT enough: the label is
-  // parsed as inline content, so emphasis (`* _`), code (`` ` ``), strikethrough
-  // (`~`), autolinks/raw-HTML (`<`), HTML entities (`&`), and image markers (`!`)
-  // would all be consumed and lost when the importer reads `a.textContent` back
-  // (e.g. `report *v2*.pdf` -> `report v2.pdf`). CommonMark treats a backslash
-  // before ANY ASCII punctuation as that literal char, so escaping this active
-  // set is always lossless on re-parse; the old `<div data-attachment-name>`
-  // form carried arbitrary strings via escapeAttr, so anything less is a
-  // data-loss regression on the git-sync data path. `( )` are escaped too: even
-  // with `[ ]` escaped, an unescaped `](x)` sequence inside the label (e.g. a
-  // name like `![shot](x).pdf`) forms a false nested-link destination and
-  // fragments the parse — escaping the parens removes that ambiguity entirely.
+  // Backslash-escape every character that would be INTERPRETED inside a markdown
+  // label re-parsed as inline content — used for a link-form media node's visible
+  // text (`attrs.name`/`attrs.provider`, #293 canon #8) AND for an image `![alt]`
+  // (canon #4) — so the value round-trips byte-exact. Two overlapping trigger
+  // sets must be escaped:
+  //   1. Stock CommonMark inline: emphasis (`* _`), code (`` ` ``), strikethrough
+  //      (`~`), autolinks/raw-HTML (`<`), HTML entities (`&`), image markers (`!`),
+  //      brackets (`[ ]`), and `( )` — even with `[ ]` escaped, an unescaped
+  //      `](x)` forms a false nested-link destination and fragments the parse.
+  //   2. The Docmost inline EXTENSIONS this package registers on its marked
+  //      instance: highlight `==x==` (canon #7), math `$x$` (canon #6), and
+  //      footnote `^[x]` (canon #2). Their triggers `= $ ^` are NOT CommonMark
+  //      punctuation the stock lexer would treat specially, but the extension
+  //      tokenizers fire on them — so an alt/name like `x $A$ y`, `use ==b==`, or
+  //      `^[fn]` would be silently turned into a math/highlight/footnote node on
+  //      import unless the trigger is escaped. `\= \$ \^` decode back to literals
+  //      (all ASCII punctuation) and, being escape tokens, stop the extension
+  //      tokenizer from matching — verified lossless round-trip.
   const escapeLinkText = (value: unknown): string =>
-    String(value ?? "").replace(/[\\`*_~[\]<&!()]/g, (c: string) => `\\${c}`);
+    String(value ?? "").replace(/[\\`*_~[\]<&!()=$^]/g, (c: string) => `\\${c}`);
 
   // #293 canon #6: the schema-HTML forms for math. These are the LOSSLESS forms
   // the raw-HTML path (columns/cells) and the mathInline fallback emit, and the
diff --git a/packages/prosemirror-markdown/test/image-comment.test.ts b/packages/prosemirror-markdown/test/image-comment.test.ts
index 6f4974cb..605e3e5b 100644
--- a/packages/prosemirror-markdown/test/image-comment.test.ts
+++ b/packages/prosemirror-markdown/test/image-comment.test.ts
@@ -62,7 +62,13 @@ describe('#293 canon #4 — image serialization + attached img-comment', () => {
     // import; without escaping, a bracket/emphasis in a realistic description
     // would make the image node VANISH or collapse emphasis. Assert the image
     // survives with the exact alt AND the markdown is byte-stable on re-export.
-    for (const alt of ['a]b[c', 'Figure [1]', 'the *new* logo', 'x_y_z', 'see ![img', 'a & b']) {
+    for (const alt of [
+      'a]b[c', 'Figure [1]', 'the *new* logo', 'x_y_z', 'see ![img', 'a & b',
+      // Canon inline-extension triggers this same package introduces (F5): math
+      // `$`, highlight `==`, footnote `^[` — an unescaped one turns the alt into
+      // a math/highlight/footnote node on import.
+      'x $A$ y', '5$ and 10$', 'use ==bold==', '^[fn]', 'cost $5 == price',
+    ]) {
       const md1 = convertProseMirrorToMarkdown(image({ alt }));
       const back = await markdownToProseMirror(md1);
       const img = findImage(back);
diff --git a/packages/prosemirror-markdown/test/media-comments.test.ts b/packages/prosemirror-markdown/test/media-comments.test.ts
index c8f8a2c5..35ccb783 100644
--- a/packages/prosemirror-markdown/test/media-comments.test.ts
+++ b/packages/prosemirror-markdown/test/media-comments.test.ts
@@ -249,6 +249,13 @@ describe('#293 #8 LINK-FORM: pdf', () => {
       'tag <x> & y.pdf',
       'amp &amp; here.pdf',
       '![shot](x).pdf',
+      // Canon inline-extension triggers (F5): math `$`, highlight `==`, footnote
+      // `^[` — a filename carrying these must not become a math/highlight/footnote
+      // node on import.
+      'data $A$.csv',
+      'q3 ==final==.pdf',
+      '5$ and 10$.pdf',
+      'note ^[x].pdf',
     ]) {
       const { md1, md2, doc2 } = await roundTrip(mkDoc([{ type: 'pdf', attrs: { src: '/x', name } }]));
       expect(md2).toBe(md1); // byte-stable, no churn
-- 
2.52.0


From bcd194ee5d8c2b57d17d12ac4dab346f72e6b2cd Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 15:26:43 +0300
Subject: [PATCH 14/17] feat(mcp): hide resolved-comment anchors + feed from
 the agent (#328)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The AI agent (MCP + in-app chat) saw ALL comments incl. resolved via two
channels, cluttering its context and breaking fragment search. Default now:
the agent sees only ACTIVE discussions; resolved is opt-in. Active anchors and
threads are always kept.

Channel 1 — resolved comment anchors on agent reads (converter option):
`convertProseMirrorToMarkdown(content, options?)` gains
`options.dropResolvedCommentAnchors` (default false — zero change for every
existing caller incl. git-sync). Both `case "comment"` emitters (top-level and
the raw-HTML inlineToHtml path) emit BARE text (no `<span data-comment-id>`) when
`resolved && the flag`; active anchors keep their wrapper. mcp `getPage` passes
the flag; `export_page_markdown` does NOT (lossless export must preserve resolved
anchors — that is why it is an opt-in option, not unconditional); `get_page_json`
is untouched (lossless PM JSON). Built on the #293 package converter.

Channel 2 — `list_comments` default active-only: `listComments(pageId,
includeResolved=false)` now returns `{ items, resolvedThreadsHidden }` (was a
bare array). By default a RESOLVED top-level thread is hidden wholesale — the
root AND every reply anchored to it (a thread is gated only by its root's
resolvedAt; a resolved reply under an ACTIVE root stays). `resolvedThreadsHidden`
counts hidden threads so the agent knows to re-query. `includeResolved:true`
returns everything. The `includeResolved` param is added to both tool
registrations (MCP index.ts + in-app ai-chat-tools.service.ts); `DocmostClientLike`
signature updated. Server `findPageComments` is NOT touched — the web UI's tabs
depend on the full feed; filtering is only at the mcp-client level. All internal
call sites (export_page_markdown / checkNewComments / transformPage) updated to
`.items` with `includeResolved:true` to keep their full-feed behavior.

The comment model is assumed FLAT (a reply's parentCommentId points at the
thread root) — documented in the filter; a future reply-of-reply model would
need a root-walk there.

Tests: resolved-comment-anchors.test.ts (6 — anchor dropped with flag / kept
without, for BOTH emitters; active always kept); list-comments-resolved.test.mjs
(4 — resolved thread+reply hidden + counter; includeResolved:true returns all;
an ACTIVE thread with a RESOLVED reply is NOT hidden).

package vitest: 664 passed; tsc clean. mcp: node --test 458 passed; tsc clean.
apps/server + git-sync: tsc clean (converter option default-off).

NOTE: based on feat/293-B (#293/#326 STEP 5) — the converter lives in the
package; this PR is stacked on #333 and its base retargets to develop once #333
merges. mcp/build is gitignored (not committed).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../ai-chat/tools/ai-chat-tools.service.ts    |  16 +-
 .../ai-chat/tools/docmost-client.loader.ts    |   7 +-
 packages/mcp/src/client.ts                    |  65 ++++++-
 packages/mcp/src/index.ts                     |  19 ++-
 packages/mcp/src/lib/markdown-converter.ts    |   5 +-
 .../test/mock/list-comments-resolved.test.mjs | 160 ++++++++++++++++++
 .../prosemirror-markdown/src/lib/index.ts     |   1 +
 .../src/lib/markdown-converter.ts             |  35 +++-
 .../test/resolved-comment-anchors.test.ts     |  95 +++++++++++
 9 files changed, 384 insertions(+), 19 deletions(-)
 create mode 100644 packages/mcp/test/mock/list-comments-resolved.test.mjs
 create mode 100644 packages/prosemirror-markdown/test/resolved-comment-anchors.test.ts

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 9abd1c50..c5a5195a 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
@@ -649,13 +649,21 @@ export class AiChatToolsService {
 
       listComments: tool({
         description:
-          'List ALL comments on a page in one call, including RESOLVED ' +
-          'threads — filter by resolvedAt when you need only open ones. ' +
-          'Content is returned as Markdown.',
+          'List comments on a page in one call. By DEFAULT only ACTIVE ' +
+          'threads are returned; resolved threads (a resolved top-level ' +
+          'comment and all its replies) are hidden and their count reported ' +
+          'as `resolvedThreadsHidden` so you can re-query with ' +
+          '`includeResolved: true` to see everything. Returns ' +
+          '`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.',
         inputSchema: modelFriendlyInput({
           pageId: z.string().describe('The id of the page.'),
+          includeResolved: z
+            .boolean()
+            .optional()
+            .describe('default only active threads; true — include resolved'),
         }),
-        execute: async ({ pageId }) => await client.listComments(pageId),
+        execute: async ({ pageId, includeResolved }) =>
+          await client.listComments(pageId, includeResolved),
       }),
 
       getComment: tool({
diff --git a/apps/server/src/core/ai-chat/tools/docmost-client.loader.ts b/apps/server/src/core/ai-chat/tools/docmost-client.loader.ts
index 7b5a9a4e..5a316ce5 100644
--- a/apps/server/src/core/ai-chat/tools/docmost-client.loader.ts
+++ b/apps/server/src/core/ai-chat/tools/docmost-client.loader.ts
@@ -56,7 +56,12 @@ export interface DocmostClientLike {
   getPageJson(pageId: string): Promise<Record<string, unknown>>;
   getNode(pageId: string, nodeId: string): Promise<Record<string, unknown>>;
   getTable(pageId: string, tableRef: string): Promise<Record<string, unknown>>;
-  listComments(pageId: string): Promise<unknown[]>;
+  // Returns `{ items, resolvedThreadsHidden }`. DEFAULT (includeResolved unset/
+  // false) hides resolved threads wholesale; pass true for the full feed.
+  listComments(
+    pageId: string,
+    includeResolved?: boolean,
+  ): Promise<{ items: unknown[]; resolvedThreadsHidden: number }>;
   getComment(
     commentId: string,
   ): Promise<{ data: Record<string, unknown>; success: boolean }>;
diff --git a/packages/mcp/src/client.ts b/packages/mcp/src/client.ts
index cd29d494..ab96b458 100644
--- a/packages/mcp/src/client.ts
+++ b/packages/mcp/src/client.ts
@@ -807,8 +807,14 @@ export class DocmostClient {
     await this.ensureAuthenticated();
     const resultData = await this.getPageRaw(pageId);
 
+    // Agent read: hide resolved-comment anchors so the agent sees only active
+    // discussions. Active anchors are kept. (The lossless export_page_markdown
+    // round-trip deliberately does NOT pass this flag — resolved anchors there
+    // must be preserved.)
     let content = resultData.content
-      ? convertProseMirrorToMarkdown(resultData.content)
+      ? convertProseMirrorToMarkdown(resultData.content, {
+          dropResolvedCommentAnchors: true,
+        })
       : "";
 
     // Always fetch subpages to provide context to the agent
@@ -1774,7 +1780,10 @@ export class DocmostClient {
     const body = page.content ? convertProseMirrorToMarkdown(page.content) : "";
     let comments: any[] = [];
     try {
-      comments = await this.listComments(pageId);
+      // Lossless export: include RESOLVED threads so the export -> import
+      // round-trip preserves every comment. This is exactly why the active-only
+      // filter is an opt-in (default false) on listComments.
+      comments = (await this.listComments(pageId, true)).items;
     } catch (e) {
       // A comments fetch failure must not lose the body; export with [] and let
       // the caller see the (empty) comments block. Log under DEBUG only.
@@ -2343,8 +2352,21 @@ export class DocmostClient {
     }
   }
 
-  /** List all comments on a page (cursor-paginated), content as markdown. */
-  async listComments(pageId: string) {
+  /**
+   * List comments on a page (cursor-paginated), content as markdown.
+   *
+   * DEFAULT (`includeResolved = false`) hides RESOLVED THREADS WHOLESALE so the
+   * agent sees only active discussions: a top-level comment with `resolvedAt`
+   * set AND every reply under it (a reply of a closed thread is part of the
+   * closed thread) are dropped from `items`. `resolvedThreadsHidden` reports how
+   * many resolved top-level threads were hidden so the agent can re-query with
+   * `includeResolved: true` to see everything. Active threads always stay.
+   *
+   * Returns `{ items, resolvedThreadsHidden }` (NOT a bare array) — callers that
+   * need the full feed (lossless export, transformPage, checkNewComments) pass
+   * `includeResolved: true` and read `.items`.
+   */
+  async listComments(pageId: string, includeResolved = false) {
     await this.ensureAuthenticated();
     let allComments: any[] = [];
     let cursor: string | null = null;
@@ -2360,7 +2382,7 @@ export class DocmostClient {
       cursor = data.meta?.nextCursor || null;
     } while (cursor);
 
-    return allComments.map((comment: any) => {
+    const mapped = allComments.map((comment: any) => {
       const markdown = comment.content
         ? convertProseMirrorToMarkdown(
             this.parseCommentContent(comment.content),
@@ -2368,6 +2390,31 @@ export class DocmostClient {
         : "";
       return filterComment(comment, markdown);
     });
+
+    if (includeResolved) {
+      return { items: mapped, resolvedThreadsHidden: 0 };
+    }
+
+    // Ids of RESOLVED top-level threads (a top-level comment has no
+    // parentCommentId). A whole thread is hidden when its root is resolved.
+    const resolvedRootIds = new Set(
+      mapped
+        .filter((c) => !c.parentCommentId && c.resolvedAt != null)
+        .map((c) => c.id),
+    );
+
+    const items = mapped.filter((c) => {
+      // Hide the resolved root itself and every reply anchored to it. A reply's
+      // own resolvedAt is irrelevant — its membership follows the parent thread.
+      // ASSUMPTION: Docmost's comment model is FLAT — a reply's parentCommentId
+      // always points at the thread ROOT (no reply-of-reply nesting), so a single
+      // level of parent lookup covers a whole thread. If nested replies are ever
+      // introduced, a deep reply of a resolved thread would need a root-walk here.
+      if (!c.parentCommentId) return !resolvedRootIds.has(c.id);
+      return !resolvedRootIds.has(c.parentCommentId);
+    });
+
+    return { items, resolvedThreadsHidden: resolvedRootIds.size };
   }
 
   async getComment(commentId: string) {
@@ -2742,7 +2789,9 @@ export class DocmostClient {
     const results: any[] = [];
     for (const page of pagesInScope) {
       try {
-        const comments = await this.listComments(page.id);
+        // Full feed (incl. resolved): a "new comments since" scan reports all
+        // recent activity; the active-only filter is scoped to list_comments.
+        const comments = (await this.listComments(page.id, true)).items;
         const newComments = comments.filter(
           (c: any) => new Date(c.createdAt) > sinceDate,
         );
@@ -3488,7 +3537,9 @@ export class DocmostClient {
     const deleteComments = opts.deleteComments ?? false;
 
     await this.ensureAuthenticated();
-    const comments = await this.listComments(pageId);
+    // Full feed (incl. resolved): a page transform (e.g. comments -> footnotes)
+    // must operate on every comment, so it opts into the unfiltered feed.
+    const comments = (await this.listComments(pageId, true)).items;
 
     // ctx handed to the sandbox. consume() records ids; helpers are the pure
     // transform primitives. log is captured from console.log inside the sandbox.
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
index 6bbcea7c..51e0f6d9 100644
--- a/packages/mcp/src/index.ts
+++ b/packages/mcp/src/index.ts
@@ -712,15 +712,24 @@ server.registerTool(
   "list_comments",
   {
     description:
-      "List ALL comments on a page in one call (pagination is handled " +
-      "internally), including RESOLVED threads — filter by resolvedAt when you " +
-      "need only open ones. Content is returned as Markdown.",
+      "List comments on a page in one call (pagination is handled " +
+      "internally). By DEFAULT only ACTIVE threads are returned; resolved " +
+      "threads (a resolved top-level comment and all its replies) are hidden " +
+      "and their count reported as `resolvedThreadsHidden` so you can re-query " +
+      "with `includeResolved: true` to see everything. Returns " +
+      "`{ items, resolvedThreadsHidden }`. Content is returned as Markdown.",
     inputSchema: {
       pageId: z.string().describe("ID of the page"),
+      includeResolved: z
+        .boolean()
+        .optional()
+        .describe(
+          "default only active threads; true — include resolved",
+        ),
     },
   },
-  async ({ pageId }) => {
-    const comments = await docmostClient.listComments(pageId);
+  async ({ pageId, includeResolved }) => {
+    const comments = await docmostClient.listComments(pageId, includeResolved);
     return jsonContent(comments);
   },
 );
diff --git a/packages/mcp/src/lib/markdown-converter.ts b/packages/mcp/src/lib/markdown-converter.ts
index 10a9f775..b39f608b 100644
--- a/packages/mcp/src/lib/markdown-converter.ts
+++ b/packages/mcp/src/lib/markdown-converter.ts
@@ -9,4 +9,7 @@
  * many existing `./markdown-converter.js` importers (client.ts, tests) do not
  * have to move.
  */
-export { convertProseMirrorToMarkdown } from "@docmost/prosemirror-markdown";
+export {
+  convertProseMirrorToMarkdown,
+  type ConvertProseMirrorToMarkdownOptions,
+} from "@docmost/prosemirror-markdown";
diff --git a/packages/mcp/test/mock/list-comments-resolved.test.mjs b/packages/mcp/test/mock/list-comments-resolved.test.mjs
new file mode 100644
index 00000000..19188b9e
--- /dev/null
+++ b/packages/mcp/test/mock/list-comments-resolved.test.mjs
@@ -0,0 +1,160 @@
+// gitmost #328 Channel 2: DocmostClient.listComments hides RESOLVED THREADS
+// wholesale by default (a resolved top-level comment AND every reply under it),
+// returning `{ items, resolvedThreadsHidden }`. `includeResolved: true` returns
+// the full feed. These tests stand a local http.createServer in for Docmost and
+// mock the /auth/login + /comments (paginated) routes.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import { DocmostClient } from "../../build/client.js";
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let raw = "";
+    req.on("data", (c) => (raw += c));
+    req.on("end", () => resolve(raw));
+  });
+}
+
+function startServer(handler) {
+  return new Promise((resolve) => {
+    const server = http.createServer(handler);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({ server, baseURL: `http://127.0.0.1:${port}/api` });
+    });
+  });
+}
+
+function closeServer(server) {
+  return new Promise((resolve) => server.close(resolve));
+}
+
+function sendJson(res, status, obj, extraHeaders = {}) {
+  res.writeHead(status, { "Content-Type": "application/json", ...extraHeaders });
+  res.end(JSON.stringify(obj));
+}
+
+const openServers = [];
+async function spawn(handler) {
+  const { server, baseURL } = await startServer(handler);
+  openServers.push(server);
+  return { server, baseURL };
+}
+
+after(async () => {
+  await Promise.all(openServers.map((s) => closeServer(s)));
+});
+
+// A minimal ProseMirror comment body (a paragraph of text).
+const body = (t) => ({
+  type: "doc",
+  content: [{ type: "paragraph", content: [{ type: "text", text: t }] }],
+});
+
+// Feed: an ACTIVE thread whose REPLY is resolved (root active, reply resolved —
+// the thread must STAY, because a thread is gated only by its ROOT's resolvedAt)
+// and a RESOLVED thread (root + reply).
+const FEED = [
+  {
+    id: "a",
+    pageId: "page-1",
+    parentCommentId: null,
+    resolvedAt: null,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    creatorId: "u1",
+    content: body("active root"),
+  },
+  {
+    id: "a1",
+    pageId: "page-1",
+    parentCommentId: "a",
+    // A RESOLVED reply under an ACTIVE root: the thread is NOT hidden (only a
+    // resolved ROOT hides a thread), so this reply survives the default filter.
+    resolvedAt: "2026-02-15T00:00:00.000Z",
+    createdAt: "2026-01-01T01:00:00.000Z",
+    creatorId: "u1",
+    content: body("resolved reply of an active thread"),
+  },
+  {
+    id: "r",
+    pageId: "page-1",
+    parentCommentId: null,
+    resolvedAt: "2026-02-01T00:00:00.000Z",
+    createdAt: "2026-01-02T00:00:00.000Z",
+    creatorId: "u1",
+    content: body("resolved root"),
+  },
+  {
+    id: "r1",
+    pageId: "page-1",
+    parentCommentId: "r",
+    resolvedAt: null,
+    createdAt: "2026-01-02T01:00:00.000Z",
+    creatorId: "u1",
+    content: body("resolved reply"),
+  },
+];
+
+function commentsServer() {
+  return spawn(async (req, res) => {
+    await readBody(req);
+    if (req.url === "/api/auth/login") {
+      sendJson(res, 200, { success: true }, {
+        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
+      });
+      return;
+    }
+    if (req.url === "/api/comments") {
+      // Single page, no cursor.
+      sendJson(res, 200, { data: { items: FEED, meta: { nextCursor: null } } });
+      return;
+    }
+    sendJson(res, 404, { message: "not found" });
+  });
+}
+
+test("default hides the resolved thread (root + its reply) and counts it", async () => {
+  const { baseURL } = await commentsServer();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const result = await client.listComments("page-1");
+  assert.equal(Array.isArray(result.items), true, "returns { items, ... }");
+  const ids = result.items.map((c) => c.id).sort();
+  assert.deepEqual(ids, ["a", "a1"], "only the active thread remains");
+  assert.equal(result.resolvedThreadsHidden, 1, "one resolved thread hidden");
+});
+
+test("includeResolved:true returns EVERYTHING with zero hidden", async () => {
+  const { baseURL } = await commentsServer();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const result = await client.listComments("page-1", true);
+  const ids = result.items.map((c) => c.id).sort();
+  assert.deepEqual(ids, ["a", "a1", "r", "r1"], "all four comments returned");
+  assert.equal(result.resolvedThreadsHidden, 0, "nothing hidden with the flag");
+});
+
+test("the reply of a resolved thread is hidden with the thread", async () => {
+  const { baseURL } = await commentsServer();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const result = await client.listComments("page-1");
+  const ids = result.items.map((c) => c.id);
+  assert.equal(ids.includes("r1"), false, "the resolved thread's reply is gone");
+  assert.equal(ids.includes("r"), false, "the resolved root is gone");
+});
+
+test("an ACTIVE thread whose REPLY is resolved is NOT hidden", async () => {
+  // A thread is gated only by its ROOT's resolvedAt. `a1` is a resolved reply
+  // under the active root `a`, so both must survive the default filter and the
+  // thread must not be counted as hidden.
+  const { baseURL } = await commentsServer();
+  const client = new DocmostClient(baseURL, "user@example.com", "pw");
+
+  const result = await client.listComments("page-1");
+  const ids = result.items.map((c) => c.id).sort();
+  assert.equal(ids.includes("a"), true, "active root stays");
+  assert.equal(ids.includes("a1"), true, "its resolved reply stays with the thread");
+  assert.equal(result.resolvedThreadsHidden, 1, "only the resolved-root thread is hidden");
+});
diff --git a/packages/prosemirror-markdown/src/lib/index.ts b/packages/prosemirror-markdown/src/lib/index.ts
index 10bb757d..f95e6a6d 100644
--- a/packages/prosemirror-markdown/src/lib/index.ts
+++ b/packages/prosemirror-markdown/src/lib/index.ts
@@ -16,6 +16,7 @@ export {
 export type { DocmostMdMeta } from "./markdown-document.js";
 
 export { convertProseMirrorToMarkdown } from "./markdown-converter.js";
+export type { ConvertProseMirrorToMarkdownOptions } from "./markdown-converter.js";
 
 export { markdownToProseMirror } from "./markdown-to-prosemirror.js";
 
diff --git a/packages/prosemirror-markdown/src/lib/markdown-converter.ts b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
index 63c39333..2d173e52 100644
--- a/packages/prosemirror-markdown/src/lib/markdown-converter.ts
+++ b/packages/prosemirror-markdown/src/lib/markdown-converter.ts
@@ -33,13 +33,36 @@ import {
  */
 const MAX_NODE_DEPTH = 400;
 
+/**
+ * Options for {@link convertProseMirrorToMarkdown}.
+ */
+export interface ConvertProseMirrorToMarkdownOptions {
+  /**
+   * When true, an inline comment anchor whose Comment mark is `resolved`
+   * emits its BARE text (no `<span data-comment-id …>` wrapper), so an agent
+   * reading the page never sees resolved-comment anchors. ACTIVE (unresolved)
+   * anchors still emit their wrapper. Defaults to false — a zero-behavior
+   * change for every existing caller, including the lossless git-sync export
+   * path where resolved anchors MUST be preserved for round-tripping.
+   */
+  dropResolvedCommentAnchors?: boolean;
+}
+
 /**
  * Convert ProseMirror/TipTap JSON content to Markdown
  * Supports all Docmost-specific node types and extensions
  */
-export function convertProseMirrorToMarkdown(content: any): string {
+export function convertProseMirrorToMarkdown(
+  content: any,
+  options: ConvertProseMirrorToMarkdownOptions = {},
+): string {
   if (!content || !content.content) return "";
 
+  // Closure flag read by both `case "comment"` emitters (the top-level marks
+  // loop and the raw-HTML inlineToHtml path). Off by default; the agent-read
+  // callers (mcp getPage / in-app AI chat) pass it true.
+  const dropResolvedCommentAnchors = options.dropResolvedCommentAnchors === true;
+
   // Escape a value interpolated into an HTML double-quoted attribute value
   // (textAlign, colors, image src, math `text`, all data-* attrs, etc.). In the
   // ATTRIBUTE context only the quote that delimits the value and the ampersand
@@ -508,6 +531,11 @@ export function convertProseMirrorToMarkdown(content: any): string {
                 // commentId/resolved).
                 const cid = mark.attrs?.commentId;
                 if (cid) {
+                  // Hide resolved anchors from agent reads: drop the wrapper and
+                  // keep only the bare text. Active anchors keep their wrapper.
+                  if (mark.attrs?.resolved && dropResolvedCommentAnchors) {
+                    break;
+                  }
                   const resolvedAttr = mark.attrs?.resolved
                     ? ` data-resolved="true"`
                     : "";
@@ -1177,6 +1205,11 @@ export function convertProseMirrorToMarkdown(content: any): string {
               // Inline comment anchor inside a raw-HTML container (columns /
               // spanned table cells), so commented text there also round-trips.
               if (mark.attrs?.commentId) {
+                // Hide resolved anchors from agent reads: drop the wrapper and
+                // keep only the bare text. Active anchors keep their wrapper.
+                if (mark.attrs?.resolved && dropResolvedCommentAnchors) {
+                  break;
+                }
                 const r = mark.attrs?.resolved ? ` data-resolved="true"` : "";
                 t = `<span data-comment-id="${escapeAttr(mark.attrs.commentId)}"${r}>${t}</span>`;
               }
diff --git a/packages/prosemirror-markdown/test/resolved-comment-anchors.test.ts b/packages/prosemirror-markdown/test/resolved-comment-anchors.test.ts
new file mode 100644
index 00000000..2b83f223
--- /dev/null
+++ b/packages/prosemirror-markdown/test/resolved-comment-anchors.test.ts
@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+// Import the converter DIRECTLY from src (NOT the docmost-client barrel, which
+// pulls in collaboration.ts and mutates the global DOM at import time), matching
+// the other converter unit tests (see markdown-converter-html-marks.test.ts).
+import { convertProseMirrorToMarkdown } from '../src/lib/markdown-converter.js';
+
+// gitmost #328 Channel 1: the `dropResolvedCommentAnchors` converter option
+// hides RESOLVED comment anchors from agent reads while keeping ACTIVE anchors.
+// The option defaults to false (zero behavior change for the lossless git-sync
+// export path). Two emitters read it: the top-level marks loop and the raw-HTML
+// inlineToHtml path (inside columns / spanned table cells).
+
+const text = (t: string, marks?: any[]) =>
+  marks ? { type: 'text', text: t, marks } : { type: 'text', text: t };
+const para = (...inline: any[]) => ({ type: 'paragraph', content: inline });
+const doc = (...nodes: any[]) => ({ type: 'doc', content: nodes });
+
+const commentMark = (commentId: string, resolved: boolean) => ({
+  type: 'comment',
+  attrs: { commentId, resolved },
+});
+
+// A columns node (raw-HTML container) so its children render via the
+// blockToHtml -> inlineToHtml path (the SECOND `case "comment"` emitter).
+const oneColumn = (...blocks: any[]) => ({
+  type: 'columns',
+  attrs: { layout: 'two' },
+  content: [{ type: 'column', content: blocks }],
+});
+
+describe('#328 Channel 1 — top-level emitter: dropResolvedCommentAnchors', () => {
+  const resolvedDoc = doc(
+    para(text('kept '), text('resolved', [commentMark('r1', true)])),
+  );
+  const activeDoc = doc(
+    para(text('kept '), text('active', [commentMark('a1', false)])),
+  );
+
+  it('drops a RESOLVED anchor (bare text) WITH the flag', () => {
+    const out = convertProseMirrorToMarkdown(resolvedDoc, {
+      dropResolvedCommentAnchors: true,
+    });
+    expect(out).toBe('kept resolved');
+    expect(out).not.toContain('data-comment-id');
+  });
+
+  it('PRESERVES a RESOLVED anchor WITHOUT the flag (default off)', () => {
+    const out = convertProseMirrorToMarkdown(resolvedDoc);
+    expect(out).toContain(
+      '<span data-comment-id="r1" data-resolved="true">resolved</span>',
+    );
+  });
+
+  it('KEEPS an ACTIVE anchor in BOTH cases', () => {
+    const withFlag = convertProseMirrorToMarkdown(activeDoc, {
+      dropResolvedCommentAnchors: true,
+    });
+    const withoutFlag = convertProseMirrorToMarkdown(activeDoc);
+    expect(withFlag).toContain('<span data-comment-id="a1">active</span>');
+    expect(withoutFlag).toContain('<span data-comment-id="a1">active</span>');
+  });
+});
+
+describe('#328 Channel 1 — raw-HTML inlineToHtml emitter (columns)', () => {
+  const resolvedCol = doc(
+    oneColumn(para(text('resolved', [commentMark('r1', true)]))),
+  );
+  const activeCol = doc(
+    oneColumn(para(text('active', [commentMark('a1', false)]))),
+  );
+
+  it('drops a RESOLVED anchor (bare text) WITH the flag', () => {
+    const out = convertProseMirrorToMarkdown(resolvedCol, {
+      dropResolvedCommentAnchors: true,
+    });
+    expect(out).toContain('<p>resolved</p>');
+    expect(out).not.toContain('data-comment-id');
+  });
+
+  it('PRESERVES a RESOLVED anchor WITHOUT the flag', () => {
+    const out = convertProseMirrorToMarkdown(resolvedCol);
+    expect(out).toContain(
+      '<span data-comment-id="r1" data-resolved="true">resolved</span>',
+    );
+  });
+
+  it('KEEPS an ACTIVE anchor in BOTH cases', () => {
+    const withFlag = convertProseMirrorToMarkdown(activeCol, {
+      dropResolvedCommentAnchors: true,
+    });
+    const withoutFlag = convertProseMirrorToMarkdown(activeCol);
+    expect(withFlag).toContain('<span data-comment-id="a1">active</span>');
+    expect(withoutFlag).toContain('<span data-comment-id="a1">active</span>');
+  });
+});
-- 
2.52.0


From 832c3cafdfd2ab9d0bf49ac1402c37ee3aa92170 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 16:22:34 +0300
Subject: [PATCH 15/17] test(mcp): update test-e2e.mjs listComments calls to
 the {items} shape (#328 review F1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The listComments Comment[] -> { items, resolvedThreadsHidden } shape change
reached every src/host consumer but not the live-server e2e harness (run via
`node test-e2e.mjs`, not the node --test gate — so the green suite missed it).
The 4 calls now read .items; the post-resolve check passes includeResolved:true
so it still sees the now-resolved root c1 (the default feed hides it).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/mcp/test-e2e.mjs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/mcp/test-e2e.mjs b/packages/mcp/test-e2e.mjs
index 7d3d78bb..6fa6192b 100644
--- a/packages/mcp/test-e2e.mjs
+++ b/packages/mcp/test-e2e.mjs
@@ -462,7 +462,7 @@ async function main() {
     check("create_comment: markdown round-trip", c1.data.content.includes("**комментарий**"), c1.data.content);
     const reply = await client.createComment(pageId, "Ответ на комментарий.", "page", undefined, c1.data.id);
     check("create_comment: reply has parent", reply.data.parentCommentId === c1.data.id);
-    const list = await client.listComments(pageId);
+    const list = (await client.listComments(pageId)).items;
     check("list_comments: both visible", list.length === 2, `count=${list.length}`);
     await client.updateComment(c1.data.id, "Обновлённый текст комментария.");
     const got = await client.getComment(c1.data.id);
@@ -472,17 +472,19 @@ async function main() {
     // resolve_comment: close the top-level thread, verify resolvedAt surfaces, then reopen
     const resolvedRes = await client.resolveComment(c1.data.id, true);
     check("resolve_comment: marks resolved", resolvedRes.success === true && resolvedRes.resolved === true);
-    const listResolved = await client.listComments(pageId);
+    // c1 is now resolved; the default feed hides resolved threads, so pass
+    // includeResolved:true to still see it and assert its resolvedAt (#328).
+    const listResolved = (await client.listComments(pageId, true)).items;
     const c1Resolved = listResolved.find((c) => c.id === c1.data.id);
     check("resolve_comment: resolvedAt set in list", !!c1Resolved?.resolvedAt, `resolvedAt=${c1Resolved?.resolvedAt}`);
     const reopenedRes = await client.resolveComment(c1.data.id, false);
     check("resolve_comment: reopen succeeds", reopenedRes.resolved === false);
-    const listReopened = await client.listComments(pageId);
+    const listReopened = (await client.listComments(pageId)).items;
     const c1Reopened = listReopened.find((c) => c.id === c1.data.id);
     check("resolve_comment: resolvedAt cleared on reopen", !c1Reopened?.resolvedAt, `resolvedAt=${c1Reopened?.resolvedAt}`);
     await client.deleteComment(reply.data.id);
     await client.deleteComment(c1.data.id);
-    const listAfter = await client.listComments(pageId);
+    const listAfter = (await client.listComments(pageId)).items;
     check("delete_comment: comments removed", listAfter.length === 0, `count=${listAfter.length}`);
   } finally {
     if (pageId) {
-- 
2.52.0


From 8e12aa8ebfff198d2a9d640dab82999a30126a72 Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 18:46:33 +0300
Subject: [PATCH 16/17] fix(build): ship + CI-build
 @docmost/prosemirror-markdown; refresh AGENTS.md (#333 conformance)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two infra blockers from the #326-steps-2-5 conformance check — the converter/canon
are correct, but the new shared package wasn't wired into Docker/CI.

BLOCKER 1 (prod): the Docker installer stage copied mcp/build + editor-ext but NOT
packages/prosemirror-markdown. mcp now depends on it (workspace:*) and EAGER-imports
it at runtime — the in-app ai-chat DocmostClient loads build/index.js ->
lib/markdown-converter.js — so the shipped image would resolve a broken workspace
symlink and every ai-chat tool would die with ERR_MODULE_NOT_FOUND. Now the
installer COPYs packages/prosemirror-markdown/build + package.json before the prod
install. (git-sync has no runtime consumer yet — revisit at step 6 with #119.)

BLOCKER 2 (CI red): test.yml/develop.yml build only @docmost/editor-ext before
`pnpm -r test`. That is plain pnpm, which does NOT honour nx `dependsOn: ^build`,
so the package's (gitignored) build/ never appears and its consumers fail:
mcp `pretest: tsc` -> TS2307 Cannot find module '@docmost/prosemirror-markdown',
git-sync vitest typecheck the same. The green local runs only happened because the
coder+reviewer had a full install+build. Added a `pnpm --filter
@docmost/prosemirror-markdown build` step before `pnpm -r test` (mirrors the
editor-ext step); verified the build is clean (tsc exit 0).

Docs (remark 3): AGENTS.md:203 and :285 still told contributors to keep mcp's own
vendored schema mirror "in sync manually" — that copy was deleted by this PR.
Updated both: the converter + schema mirror now live in the SINGLE package
@docmost/prosemirror-markdown (consumed by mcp + git-sync, do NOT reintroduce a
per-package copy); editor-ext is the upstream schema source; the serializer-contract
test guards the boundary. Added the package to the workspace table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .github/workflows/test.yml | 8 ++++++++
 AGENTS.md                  | 5 +++--
 Dockerfile                 | 8 ++++++++
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 1d9ca3ad..7ea47b94 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -72,6 +72,14 @@ jobs:
       - name: Build editor-ext
         run: pnpm --filter @docmost/editor-ext build
 
+      # @docmost/prosemirror-markdown is the shared converter (#293/#326); its
+      # build/ is gitignored, and plain `pnpm -r test` does NOT honour nx
+      # `dependsOn: ^build`, so its consumers (mcp `pretest: tsc`, git-sync vitest
+      # typecheck) fail with TS2307 Cannot find module '@docmost/prosemirror-markdown'
+      # unless it is built first. Build it before the recursive test run.
+      - name: Build prosemirror-markdown
+        run: pnpm --filter @docmost/prosemirror-markdown build
+
       - name: Run unit tests
         run: pnpm -r test
 
diff --git a/AGENTS.md b/AGENTS.md
index 2b91446b..9bedbc39 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -200,7 +200,8 @@ pnpm workspace (`pnpm@10.4.0`) orchestrated by **Nx**. Four workspace packages:
 | `apps/server` | `server` | NestJS 11 + Fastify, Kysely (Postgres), Redis | Backend API, collaboration, AI |
 | `apps/client` | `client` | React 18 + Vite + Mantine 8 + TanStack Query + Jotai | SPA frontend |
 | `packages/editor-ext` | `@docmost/editor-ext` | Tiptap/ProseMirror | Shared Tiptap node/mark extensions, imported by both the client and the server |
-| `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Does **not** import `editor-ext` — it keeps its own vendored mirror of the schema in `packages/mcp/src/lib/` |
+| `packages/mcp` | `@docmost/mcp` | MCP SDK, Tiptap, Yjs | Standalone MCP server, also bundled into the server at `/mcp`. Consumes the shared converter/schema from `@docmost/prosemirror-markdown` (#293) — it no longer carries its own vendored converter/schema copy |
+| `packages/prosemirror-markdown` | `@docmost/prosemirror-markdown` | Tiptap, marked, jsdom | The single, canonical ProseMirror↔Markdown converter + Docmost schema mirror (#293). Consumed by `mcp` and `git-sync`; there is exactly ONE copy of the converter now |
 
 `build` targets are Nx-cached and dependency-ordered (`dependsOn: ["^build"]`), so `editor-ext` builds before the apps. `nx.json` sets `affected.defaultBase: main`.
 
@@ -282,7 +283,7 @@ The API server is a Fastify app with a global `/api` prefix (`main.ts` excludes
 ### Client structure
 Vite SPA. Code is organized by feature under `apps/client/src/features/*` (mirrors the server domains: `page`, `space`, `comment`, `ai-chat`, `editor`, …). Conventions:
 - **TanStack Query** for server state (one `queries/` file per feature), **Jotai** atoms for local/shared UI state, **Mantine 8** + CSS modules (`*.module.css`) + `postcss-preset-mantine` for UI.
-- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. Note `packages/mcp` does *not* depend on `editor-ext`; it carries its own mirrored copy of the schema, so keep the two in sync manually when the document schema changes.
+- The editor is Tiptap; shared node/mark extensions live in `packages/editor-ext` and are imported by **both the client and the server** (collaboration, import/export) — editor schema changes often need to be made in `editor-ext`, not just the client. The ProseMirror↔Markdown converter and its Docmost schema mirror now live in a SINGLE package, `@docmost/prosemirror-markdown` (#293), consumed by both `mcp` and `git-sync` — do NOT reintroduce a per-package copy. `editor-ext` is the upstream source of the Tiptap schema; the package's `docmost-schema.ts` mirrors it and a serializer-contract test (`packages/prosemirror-markdown/test/serializer-contract.test.ts`) guards the boundary (every schema node must have a converter case), so a drift surfaces as a failing test rather than silent divergence.
 - API access goes through `apps/client/src/lib/api-client.ts` (axios). The `@` alias maps to `apps/client/src`.
 - Runtime config is injected at build time by `vite.config.ts` via `define` (`APP_URL`, `COLLAB_URL`, `APP_VERSION`, …) — these come from the root `.env`, not from `import.meta.env`.
 
diff --git a/Dockerfile b/Dockerfile
index e6daeb72..42f5a267 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -38,6 +38,14 @@ COPY --from=builder /app/packages/editor-ext/dist /app/packages/editor-ext/dist
 COPY --from=builder /app/packages/editor-ext/package.json /app/packages/editor-ext/package.json
 COPY --from=builder /app/packages/mcp/build /app/packages/mcp/build
 COPY --from=builder /app/packages/mcp/package.json /app/packages/mcp/package.json
+# mcp now depends on @docmost/prosemirror-markdown (workspace:*) and eager-imports
+# it at runtime (the in-app ai-chat DocmostClient loads build/index.js -> lib/
+# markdown-converter.js). Ship the built package + its manifest, or the prod
+# install resolves a broken workspace symlink and every ai-chat tool dies with
+# ERR_MODULE_NOT_FOUND (#293/#326 step 5). (git-sync has no runtime consumer yet;
+# revisit at step 6 when #119 lands.)
+COPY --from=builder /app/packages/prosemirror-markdown/build /app/packages/prosemirror-markdown/build
+COPY --from=builder /app/packages/prosemirror-markdown/package.json /app/packages/prosemirror-markdown/package.json
 
 # Copy root package files
 COPY --from=builder /app/package.json /app/package.json
-- 
2.52.0


From 8e5ad8070b6adb0a52b739fa03b582b75f8b6f6f Mon Sep 17 00:00:00 2001
From: claude code agent 227 <claude_code@vvzvlad.xyz>
Date: Sat, 4 Jul 2026 19:27:09 +0300
Subject: [PATCH 17/17] fix(lock): repair pnpm-lock.yaml broken by develop
 merge (#333 F-lock)

The develop merge (eacc1c48) left an importer pointing at a vitest@4.1.6
peer-variant WITHOUT @vitest/coverage-v8 that has no snapshot entry, so
`pnpm install --frozen-lockfile` failed with ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY
(CI + Docker red at install). Regenerated with `pnpm install --lockfile-only
--fix-lockfile` (pnpm 10.4.0, matches packageManager pin): the importer now
resolves to the existing coverage-v8 variant; two transitive pointers realigned.
No package.json / source change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 pnpm-lock.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1e325c4b..299f5e51 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1114,7 +1114,7 @@ importers:
         version: 5.9.3
       vitest:
         specifier: 4.1.6
-        version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@20.19.43)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@20.19.43)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
+        version: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@20.19.43)(@vitest/coverage-v8@4.1.6)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@20.19.43)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
 
 packages:
 
@@ -11686,7 +11686,7 @@ snapshots:
 
   '@babel/code-frame@7.29.0':
     dependencies:
-      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/helper-validator-identifier': 7.29.7
       js-tokens: 4.0.0
       picocolors: 1.1.1
 
@@ -16153,7 +16153,7 @@ snapshots:
       obug: 2.1.1
       std-env: 4.1.0
       tinyrainbow: 3.1.0
-      vitest: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@22.19.1)(@vitest/coverage-v8@4.1.6)(happy-dom@20.8.9)(jsdom@25.0.0)(vite@8.0.5(@types/node@22.19.1)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
+      vitest: 4.1.6(@opentelemetry/api@1.9.0)(@types/node@25.5.0)(@vitest/coverage-v8@4.1.6)(happy-dom@20.8.9)(jsdom@27.4.0(@noble/hashes@2.0.1))(vite@8.0.5(@types/node@25.5.0)(esbuild@0.28.0)(jiti@2.4.2)(less@4.2.0)(sugarss@5.0.1(postcss@8.5.14))(terser@5.39.0)(tsx@4.21.0)(yaml@2.8.3))
 
   '@vitest/expect@4.1.6':
     dependencies:
-- 
2.52.0