fix(docker): install python3/make/g++ toolchain for re2 native build

The develop image build broke at `pnpm install --frozen-lockfile`: the new
native dependency re2@1.25.0 (packages/mcp, search_in_page #330) always
compiles from source under pnpm — its prebuilt-binary downloader
(install-artifact-from-github) cannot identify the GitHub repo because pnpm
does not populate npm_package_repository_*/npm_package_json env vars ("No
github repository was identified. Building locally ..."), and node:22-slim
ships no python3/make/g++ for the node-gyp fallback.

- builder stage: add a cache-friendly apt layer with python3 make g++
  before COPY; the stage is discarded so the toolchain may stay.
- installer stage: install the toolchain, run the prod install as the node
  user via `su node -c`, and purge the toolchain — all in one RUN layer so
  the final image stays slim and node_modules ownership needs no extra
  chown layer; USER node is restored right after.

Fixes the failed run 28715009124 (develop docker build); release.yml uses
the same Dockerfile and is covered too.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.env.example

@@ -202,6 +202,13 @@ MCP_DOCMOST_PASSWORD=
 # Default 900000 (15 min).
 # AI_MCP_CALL_TIMEOUT_MS=900000
 
+# Deferred tool loading for the in-app AI chat (#332). Default ON: the agent sees
+# a compact <tool_catalog> and only CORE tools + a loadTools meta-tool are active
+# each step; deferred tools (the fat/rare ones + all external MCP tools) load on
+# demand. Set AI_CHAT_DEFERRED_TOOLS=false to restore the old "all tools always
+# active" behavior.
+# AI_CHAT_DEFERRED_TOOLS=true
+
 # --- Anonymous public-share AI assistant ---
 # Opt-in per workspace (AI settings -> "public share assistant"; off by default).
 # When enabled, anonymous visitors of a published share can ask an AI about that

.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
 

.gitignore

@@ -4,12 +4,21 @@
 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).
 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/
+
+# 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

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`.
 
@@ -293,7 +294,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
 

Dockerfile

@@ -5,6 +5,13 @@ RUN npm install -g pnpm@10.4.0
 
 FROM base AS builder
 
+# re2 (packages/mcp) always compiles from source under pnpm (the prebuilt-binary
+# download cannot identify the GitHub repo), so node-gyp needs python3/make/g++.
+# This stage is discarded, so the toolchain can stay installed.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 COPY . .
@@ -38,6 +45,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
@@ -49,9 +64,16 @@ COPY --from=builder /app/patches /app/patches
 
 RUN chown -R node:node /app
 
-USER node
+# Toolchain is needed transiently to compile re2 during the prod install; install
+# and purge it in one layer to keep the final image slim. The install itself runs
+# as the node user via su to keep node_modules ownership without a costly chown layer.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends python3 make g++ \
+  && su node -c "pnpm install --frozen-lockfile --prod" \
+  && apt-get purge -y --auto-remove python3 make g++ \
+  && rm -rf /var/lib/apt/lists/*
 
-RUN pnpm install --frozen-lockfile --prod
+USER node
 
 RUN mkdir -p /app/data/storage
 

apps/client/src/features/comment/components/comment-content-view.test.tsx

@@ -0,0 +1,250 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { MemoryRouter } from "react-router-dom";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+// The fallback path renders the full TipTap editor; stub it so we can assert the
+// safety valve fired without pulling in the editor stack.
+vi.mock("@/features/comment/components/comment-editor", () => ({
+  default: () => <div data-testid="comment-editor-fallback" />,
+}));
+
+// Mention rendering hits react-query; stub the page/share queries so the mention
+// case renders in isolation.
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+}));
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useSharePageQuery: () => ({ data: undefined }),
+}));
+
+import { CommentContentView } from "./comment-content-view";
+
+function renderView(content: string | object) {
+  return render(
+    <MantineProvider>
+      <MemoryRouter>
+        <CommentContentView content={content} />
+      </MemoryRouter>
+    </MantineProvider>,
+  );
+}
+
+const doc = (content: any[]) => JSON.stringify({ type: "doc", content });
+const para = (content: any[]) => ({ type: "paragraph", content });
+const text = (t: string, marks?: any[]) => ({ type: "text", text: t, marks });
+
+describe("CommentContentView", () => {
+  it("renders paragraphs as <p> with text", () => {
+    const { container } = renderView(doc([para([text("Hello world")])]));
+    expect(screen.getByText("Hello world")).toBeDefined();
+    expect(container.querySelector("p")).not.toBeNull();
+  });
+
+  it("reproduces the read-only CommentEditor DOM nesting for CSS parity", () => {
+    const { container } = renderView(doc([para([text("x")])]));
+    // outer .commentEditor > .ProseMirror (module) > .ProseMirror (global) > p
+    const globalPm = container.querySelector("div.ProseMirror > p");
+    expect(globalPm).not.toBeNull();
+  });
+
+  it("renders the bold mark as <strong>", () => {
+    const { container } = renderView(
+      doc([para([text("bold", [{ type: "bold" }])])]),
+    );
+    const el = container.querySelector("strong");
+    expect(el?.textContent).toBe("bold");
+  });
+
+  it("renders the italic mark as <em>", () => {
+    const { container } = renderView(
+      doc([para([text("it", [{ type: "italic" }])])]),
+    );
+    expect(container.querySelector("em")?.textContent).toBe("it");
+  });
+
+  it("renders the strike mark as <s>", () => {
+    const { container } = renderView(
+      doc([para([text("st", [{ type: "strike" }])])]),
+    );
+    expect(container.querySelector("s")?.textContent).toBe("st");
+  });
+
+  it("renders the underline mark as <u> (not the editor fallback)", () => {
+    const { container } = renderView(
+      doc([para([text("un", [{ type: "underline" }])])]),
+    );
+    expect(container.querySelector("u")?.textContent).toBe("un");
+    // Underline is a supported mark, so no degrade to the editor fallback.
+    expect(screen.queryByTestId("comment-editor-fallback")).toBeNull();
+  });
+
+  it("renders the code mark as <code>", () => {
+    const { container } = renderView(
+      doc([para([text("co", [{ type: "code" }])])]),
+    );
+    expect(container.querySelector("code")?.textContent).toBe("co");
+  });
+
+  it("renders the link mark as an anchor with safe rel/target", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("click", [
+            { type: "link", attrs: { href: "https://example.com" } },
+          ]),
+        ]),
+      ]),
+    );
+    const a = container.querySelector("a");
+    expect(a?.getAttribute("href")).toBe("https://example.com");
+    expect(a?.getAttribute("target")).toBe("_blank");
+    expect(a?.getAttribute("rel")).toBe("noopener noreferrer nofollow");
+    expect(a?.textContent).toBe("click");
+  });
+
+  it("neutralizes a javascript: link href (stored XSS) while keeping the text", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("click", [
+            { type: "link", attrs: { href: "javascript:alert(1)" } },
+          ]),
+        ]),
+      ]),
+    );
+    const a = container.querySelector("a");
+    expect(a).not.toBeNull();
+    // No navigable javascript: href — attribute is absent (or empty).
+    expect(a?.getAttribute("href")).toBeFalsy();
+    // The link text is still rendered.
+    expect(a?.textContent).toBe("click");
+  });
+
+  it("neutralizes a control-char-obfuscated javascript: href", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("x", [
+            { type: "link", attrs: { href: "java\tscript:alert(1)" } },
+          ]),
+        ]),
+      ]),
+    );
+    expect(container.querySelector("a")?.getAttribute("href")).toBeFalsy();
+  });
+
+  it("neutralizes a data: link href", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("x", [
+            {
+              type: "link",
+              attrs: { href: "data:text/html,<script>alert(1)</script>" },
+            },
+          ]),
+        ]),
+      ]),
+    );
+    expect(container.querySelector("a")?.getAttribute("href")).toBeFalsy();
+  });
+
+  it("preserves a mailto: link href (allowlisted scheme)", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("mail", [
+            { type: "link", attrs: { href: "mailto:a@b.com" } },
+          ]),
+        ]),
+      ]),
+    );
+    expect(container.querySelector("a")?.getAttribute("href")).toBe(
+      "mailto:a@b.com",
+    );
+  });
+
+  it("preserves a relative link href (no scheme, not a script vector)", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          text("rel", [{ type: "link", attrs: { href: "/some/path" } }]),
+        ]),
+      ]),
+    );
+    expect(container.querySelector("a")?.getAttribute("href")).toBe(
+      "/some/path",
+    );
+  });
+
+  it("nests multiple marks on one text node", () => {
+    const { container } = renderView(
+      doc([para([text("x", [{ type: "bold" }, { type: "italic" }])])]),
+    );
+    // bold wraps italic (or vice versa) — both elements exist around the text.
+    expect(container.querySelector("strong")).not.toBeNull();
+    expect(container.querySelector("em")).not.toBeNull();
+    expect(screen.getByText("x")).toBeDefined();
+  });
+
+  it("renders hardBreak as <br/>", () => {
+    const { container } = renderView(
+      doc([para([text("a"), { type: "hardBreak" }, text("b")])]),
+    );
+    expect(container.querySelector("br")).not.toBeNull();
+  });
+
+  it("renders a user mention as a styled span", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          {
+            type: "mention",
+            attrs: { label: "Alice", entityType: "user", entityId: "u1" },
+          },
+        ]),
+      ]),
+    );
+    expect(screen.getByText("@Alice")).toBeDefined();
+    // No fallback to the editor.
+    expect(screen.queryByTestId("comment-editor-fallback")).toBeNull();
+  });
+
+  it("renders a page mention as a link", () => {
+    const { container } = renderView(
+      doc([
+        para([
+          {
+            type: "mention",
+            attrs: {
+              label: "Some Page",
+              entityType: "page",
+              slugId: "pg1",
+            },
+          },
+        ]),
+      ]),
+    );
+    expect(container.querySelector("a")).not.toBeNull();
+    expect(screen.getByText("Some Page")).toBeDefined();
+  });
+
+  it("renders a legacy plain-text (non-JSON) string as plain text", () => {
+    renderView("just a legacy string");
+    expect(screen.getByText("just a legacy string")).toBeDefined();
+    expect(screen.queryByTestId("comment-editor-fallback")).toBeNull();
+  });
+
+  it("falls back to CommentEditor for an unknown node type", () => {
+    renderView(doc([{ type: "codeBlock", content: [text("x")] }]));
+    expect(screen.getByTestId("comment-editor-fallback")).toBeDefined();
+  });
+
+  it("falls back to CommentEditor for malformed JSON", () => {
+    renderView('{"type":"doc","content":[');
+    expect(screen.getByTestId("comment-editor-fallback")).toBeDefined();
+  });
+});

apps/client/src/features/comment/components/comment-content-view.tsx

@@ -0,0 +1,199 @@
+import React from "react";
+import classes from "./comment.module.css";
+import { MentionContent } from "@/features/editor/components/mention/mention-view";
+import CommentEditor from "@/features/comment/components/comment-editor";
+
+// Static, editor-free renderer of a comment body (ProseMirror JSON). It walks the
+// document and emits plain DOM, avoiding the cost of a full TipTap/ProseMirror
+// instance per comment (the panel used to spin up 400+ editors on mount).
+//
+// The supported node/mark set MUST mirror what CommentEditor enables
+// (StarterKit + Mention + LinkExtension). Anything outside that set makes the
+// whole comment degrade to the read-only CommentEditor via the fallback below,
+// so we never show a half-rendered comment.
+
+// Sentinel thrown when we hit a node/mark we don't know how to render statically.
+// Caught at the top level to trigger the CommentEditor fallback for the whole comment.
+class UnknownNodeError extends Error {}
+
+// Protocol allowlist mirroring @tiptap/extension-link's default (the read-only
+// CommentEditor path relies on it to blank javascript:/data: hrefs). The static
+// renderer must apply the SAME sanitization because the backend stores comment
+// content verbatim and React does not neutralize javascript: in an href.
+const ALLOWED_URI_SCHEMES = /^(?:https?|ftps?|mailto|tel|callto|sms|cid|xmpp):/i;
+
+function safeHref(href: unknown): string | undefined {
+  if (typeof href !== "string") return undefined;
+  // Strip control chars/whitespace that could smuggle a scheme past the test
+  // (e.g. "java\tscript:").
+  const cleaned = href.replace(/[\u0000-\u0020]/g, "").trim();
+  // Allow relative/anchor/protocol-relative links (no scheme) — not script vectors.
+  if (!/^[a-z][a-z0-9+.-]*:/i.test(cleaned)) return href;
+  return ALLOWED_URI_SCHEMES.test(cleaned) ? href : undefined;
+}
+
+interface PMMark {
+  type: string;
+  attrs?: Record<string, any>;
+}
+
+interface PMNode {
+  type: string;
+  attrs?: Record<string, any>;
+  content?: PMNode[];
+  text?: string;
+  marks?: PMMark[];
+}
+
+// Wrap a text node's string in its marks (marks nest, e.g. bold + italic).
+function renderMarks(
+  text: React.ReactNode,
+  marks: PMMark[] | undefined,
+  keyPrefix: string,
+): React.ReactNode {
+  if (!marks || marks.length === 0) return text;
+
+  return marks.reduce<React.ReactNode>((acc, mark, i) => {
+    const key = `${keyPrefix}-m${i}`;
+    switch (mark.type) {
+      case "bold":
+        return <strong key={key}>{acc}</strong>;
+      case "italic":
+        return <em key={key}>{acc}</em>;
+      case "strike":
+        return <s key={key}>{acc}</s>;
+      case "underline":
+        // StarterKit enables the Underline extension by default (Mod-u) and
+        // CommentEditor does not disable it, so real comments can carry this
+        // mark. Render it here rather than degrading the whole comment.
+        return <u key={key}>{acc}</u>;
+      case "code":
+        return <code key={key}>{acc}</code>;
+      case "link": {
+        // LinkExtension (TiptapLink) opens links in a new tab; keep the same
+        // safe rel semantics the editor produces. Sanitize the href against the
+        // extension's protocol allowlist — a disallowed scheme (javascript:,
+        // data:) yields undefined so the anchor is non-navigable but still shows
+        // its text, matching how extension-link blanks a bad href.
+        const href = safeHref(mark.attrs?.href);
+        return (
+          <a
+            key={key}
+            href={href}
+            target="_blank"
+            rel="noopener noreferrer nofollow"
+          >
+            {acc}
+          </a>
+        );
+      }
+      default:
+        throw new UnknownNodeError(`Unknown mark type: ${mark.type}`);
+    }
+  }, text);
+}
+
+function renderNode(node: PMNode, key: string): React.ReactNode {
+  switch (node.type) {
+    case "paragraph":
+      return <p key={key}>{renderChildren(node.content, key)}</p>;
+    case "text":
+      return (
+        <React.Fragment key={key}>
+          {renderMarks(node.text ?? "", node.marks, key)}
+        </React.Fragment>
+      );
+    case "hardBreak":
+      return <br key={key} />;
+    case "mention":
+      return (
+        <span key={key} style={{ display: "inline" }}>
+          <MentionContent attrs={node.attrs as any} />
+        </span>
+      );
+    default:
+      throw new UnknownNodeError(`Unknown node type: ${node.type}`);
+  }
+}
+
+function renderChildren(
+  content: PMNode[] | undefined,
+  keyPrefix: string,
+): React.ReactNode {
+  if (!content) return null;
+  return content.map((child, i) => renderNode(child, `${keyPrefix}-${i}`));
+}
+
+// Reproduce the exact DOM nesting the read-only CommentEditor renders so the
+// scoped CSS in comment.module.css (which targets
+// `.commentEditor .ProseMirror :global(.ProseMirror)` and `.ProseMirror p`)
+// applies pixel-for-pixel. Read-only => no data-editable / data-surface attrs.
+function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <div className={classes.commentEditor}>
+      <div className={classes.ProseMirror}>
+        <div className="ProseMirror">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+interface CommentContentViewProps {
+  content: string | object;
+}
+
+export function CommentContentView({ content }: CommentContentViewProps) {
+  // Degrade this single comment to the old editor-based render (safety valve).
+  const fallback = () => {
+    if (import.meta.env.DEV) {
+      console.warn(
+        "CommentContentView: unsupported comment content, falling back to editor",
+      );
+    }
+    return <CommentEditor defaultContent={content} editable={false} />;
+  };
+
+  let doc: unknown = content;
+
+  if (typeof content === "string") {
+    try {
+      doc = JSON.parse(content);
+    } catch {
+      const trimmed = content.trim();
+      // Looks like it was meant to be JSON but is malformed -> safety-valve fallback.
+      if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        return fallback();
+      }
+      // Otherwise it's a legacy plain-text comment: render as a single paragraph.
+      return (
+        <Shell>
+          <p>{content}</p>
+        </Shell>
+      );
+    }
+  }
+
+  // Double-stringified / legacy plain-text stored as a JSON string.
+  if (typeof doc === "string") {
+    return (
+      <Shell>
+        <p>{doc}</p>
+      </Shell>
+    );
+  }
+
+  try {
+    const pmDoc = doc as PMNode;
+    if (!pmDoc || typeof pmDoc !== "object" || pmDoc.type !== "doc") {
+      throw new UnknownNodeError("Not a ProseMirror doc");
+    }
+    return <Shell>{renderChildren(pmDoc.content, "n")}</Shell>;
+  } catch (err) {
+    if (err instanceof UnknownNodeError) {
+      return fallback();
+    }
+    throw err;
+  }
+}
+
+export default CommentContentView;

apps/client/src/features/comment/components/comment-list-item.test.tsx

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import { IComment } from "@/features/comment/types/comment.types";
 
@@ -9,10 +9,11 @@ import { IComment } from "@/features/comment/types/comment.types";
 // component renders in isolation. We only assert the AI-badge rendering branch.
 const applyMutateAsync = vi.fn();
 const dismissMutateAsync = vi.fn();
+const updateMutateAsync = vi.fn();
 vi.mock("@/features/comment/queries/comment-query", () => ({
   useDeleteCommentMutation: () => ({ mutateAsync: vi.fn() }),
   useResolveCommentMutation: () => ({ mutateAsync: vi.fn() }),
-  useUpdateCommentMutation: () => ({ mutateAsync: vi.fn() }),
+  useUpdateCommentMutation: () => ({ mutateAsync: updateMutateAsync }),
   useApplySuggestionMutation: () => ({
     mutateAsync: applyMutateAsync,
     isPending: false,
@@ -23,9 +24,51 @@ vi.mock("@/features/comment/queries/comment-query", () => ({
   }),
 }));
 
+// The document the mocked editor emits via onUpdate when the edit form is open.
+// Duplicated inside the mock factory (below) to keep the factory self-contained.
+const EDITED_DOC = {
+  type: "doc",
+  content: [
+    { type: "paragraph", content: [{ type: "text", text: "edited via editor" }] },
+  ],
+};
+
 // CommentEditor pulls in the full TipTap editor stack; replace it with a stub.
-vi.mock("@/features/comment/components/comment-editor", () => ({
-  default: () => <div data-testid="comment-editor" />,
+// In edit mode the stub exposes buttons that fire the real onUpdate/onSave props
+// so the edit->save/cancel flow can be driven without a live editor.
+vi.mock("@/features/comment/components/comment-editor", () => {
+  const doc = {
+    type: "doc",
+    content: [
+      { type: "paragraph", content: [{ type: "text", text: "edited via editor" }] },
+    ],
+  };
+  return {
+    default: ({ onUpdate, onSave }: any) => (
+      <div data-testid="comment-editor">
+        <button
+          type="button"
+          data-testid="editor-emit-update"
+          onClick={() => onUpdate?.(doc)}
+        />
+        <button
+          type="button"
+          data-testid="editor-emit-save"
+          onClick={() => onSave?.()}
+        />
+      </div>
+    ),
+  };
+});
+
+// CommentContentView (used for the read-only body) imports the mention view,
+// which pulls page-query -> main.tsx (createRoot). Stub the queries so the item
+// renders in isolation without the app entry side-effect.
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+}));
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useSharePageQuery: () => ({ data: undefined }),
 }));
 
 import CommentListItem from "./comment-list-item";
@@ -286,3 +329,132 @@ describe("canShowDismiss predicate", () => {
     expect(canShowDismiss(c({ parentCommentId: "p" }), true, true)).toBe(false);
   });
 });
+
+describe("CommentListItem — edit -> save/cancel flow (#340 F3)", () => {
+  const body = (t: string) =>
+    JSON.stringify({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "text", text: t }] }],
+    });
+
+  // The edit menu item is gated on the viewer owning the comment
+  // (currentUser.id === creatorId). currentUserAtom is atomWithStorage-backed,
+  // so seed localStorage to make the viewer the owner (creatorId "user-1").
+  beforeEach(() => {
+    updateMutateAsync.mockClear();
+    localStorage.setItem(
+      "currentUser",
+      JSON.stringify({ user: { id: "user-1", name: "Owner" } }),
+    );
+  });
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  async function openEditor() {
+    // Open the comment menu, then click "Edit comment" to toggle into edit mode.
+    fireEvent.click(screen.getByLabelText("Comment menu"));
+    fireEvent.click(await screen.findByText("Edit comment"));
+    // Edit form (mocked editor + actions) is now mounted.
+    await screen.findByTestId("comment-editor");
+  }
+
+  it("saves the edited content and, on cache update, shows the new body", async () => {
+    const { rerender } = renderItem(
+      baseComment({ content: body("original body") }),
+    );
+    // Static body first.
+    expect(screen.getByText("original body")).toBeDefined();
+
+    await openEditor();
+
+    // Editor emits an update (populates editContentRef), then Save is clicked.
+    fireEvent.click(screen.getByTestId("editor-emit-update"));
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    // mutateAsync is called with the stringified edited doc.
+    expect(updateMutateAsync).toHaveBeenCalledWith({
+      commentId: "c-1",
+      content: JSON.stringify(EDITED_DOC),
+    });
+
+    // On success the form closes (isEditing -> false); the static body renders
+    // from the comment.content prop again.
+    await waitFor(() =>
+      expect(screen.queryByTestId("comment-editor")).toBeNull(),
+    );
+
+    // Simulate the cache invalidation swapping in a new comment object with the
+    // updated content — the static body reflects it.
+    rerender(
+      <MantineProvider>
+        <CommentListItem
+          comment={baseComment({ content: body("updated body after save") })}
+          pageId="page-1"
+          canComment={true}
+          canEdit={true}
+        />
+      </MantineProvider>,
+    );
+    expect(screen.getByText("updated body after save")).toBeDefined();
+    expect(screen.queryByText("original body")).toBeNull();
+  });
+
+  it("cancel restores the static body and does not call the update mutation", async () => {
+    renderItem(baseComment({ content: body("original body") }));
+    await openEditor();
+
+    // Type something (editContentRef set), then cancel.
+    fireEvent.click(screen.getByTestId("editor-emit-update"));
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+
+    // Editor unmounts, static body restored, no save happened.
+    await waitFor(() =>
+      expect(screen.queryByTestId("comment-editor")).toBeNull(),
+    );
+    expect(screen.getByText("original body")).toBeDefined();
+    expect(updateMutateAsync).not.toHaveBeenCalled();
+  });
+
+  it("saving without editing sends the existing content (editContentRef cleared after cancel)", async () => {
+    renderItem(baseComment({ content: body("original body") }));
+
+    // Cancel path clears editContentRef...
+    await openEditor();
+    fireEvent.click(screen.getByTestId("editor-emit-update"));
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    await waitFor(() =>
+      expect(screen.queryByTestId("comment-editor")).toBeNull(),
+    );
+
+    // ...so re-opening and saving WITHOUT an update falls back to comment.content.
+    await openEditor();
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    expect(updateMutateAsync).toHaveBeenCalledWith({
+      commentId: "c-1",
+      content: JSON.stringify(body("original body")),
+    });
+  });
+});
+
+describe("CommentListItem — read-only body renders statically", () => {
+  it("renders the comment body as static text without a TipTap editor", () => {
+    renderItem(
+      baseComment({
+        content: JSON.stringify({
+          type: "doc",
+          content: [
+            {
+              type: "paragraph",
+              content: [{ type: "text", text: "Hello static world" }],
+            },
+          ],
+        }),
+      }),
+    );
+    // Body text is present...
+    expect(screen.getByText("Hello static world")).toBeDefined();
+    // ...and it did NOT go through the (mocked) CommentEditor instance.
+    expect(screen.queryByTestId("comment-editor")).toBeNull();
+  });
+});

apps/client/src/features/comment/components/comment-list-item.tsx

@@ -1,10 +1,11 @@
 import { Group, Text, Box, Badge, Button } from "@mantine/core";
 import { AgentAvatarStack } from "@/components/ui/agent-avatar-stack.tsx";
-import React, { useEffect, useMemo, useRef, useState } from "react";
+import React, { useMemo, useRef, useState } from "react";
 import classes from "./comment.module.css";
 import { useAtom, useAtomValue } from "jotai";
 import { useTimeAgo } from "@/hooks/use-time-ago";
 import CommentEditor from "@/features/comment/components/comment-editor";
+import CommentContentView from "@/features/comment/components/comment-content-view";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms";
 import CommentActions from "@/features/comment/components/comment-actions";
 import CommentMenu from "@/features/comment/components/comment-menu";
@@ -50,7 +51,6 @@ function CommentListItem({
   const [isEditing, setIsEditing] = useState(false);
   const [isLoading, setIsLoading] = useState(false);
   const editor = useAtomValue(pageEditorAtom);
-  const [content, setContent] = useState<string>(comment.content);
   const editContentRef = useRef<any>(null);
   const updateCommentMutation = useUpdateCommentMutation();
   const deleteCommentMutation = useDeleteCommentMutation(comment.pageId);
@@ -78,22 +78,16 @@ function CommentListItem({
   const isOwnerOrAdmin =
     currentUser?.user?.id === comment.creatorId || userSpaceRole === "admin";
 
-  useEffect(() => {
-    setContent(comment.content);
-  }, [comment]);
 
   async function handleUpdateComment() {
     try {
       setIsLoading(true);
       const commentToUpdate = {
         commentId: comment.id,
-        content: JSON.stringify(editContentRef.current ?? content),
+        content: JSON.stringify(editContentRef.current ?? comment.content),
       };
       await updateCommentMutation.mutateAsync(commentToUpdate);
-      if (editContentRef.current) {
-        setContent(editContentRef.current);
-        editContentRef.current = null;
-      }
+      editContentRef.current = null;
       setIsEditing(false);
     } catch (error) {
       console.error("Failed to update comment:", error);
@@ -350,11 +344,11 @@ function CommentListItem({
         )}
 
         {!isEditing ? (
-          <CommentEditor defaultContent={content} editable={false} />
+          <CommentContentView content={comment.content} />
         ) : (
           <>
             <CommentEditor
-              defaultContent={content}
+              defaultContent={comment.content}
               editable={true}
               onUpdate={(newContent: any) => { editContentRef.current = newContent; }}
               onSave={handleUpdateComment}
@@ -374,4 +368,6 @@ function CommentListItem({
   );
 }
 
-export default CommentListItem;
+// Memoized so a resolve/apply/reply cache update (which only replaces the touched
+// comment's object identity) re-renders that one thread, not all ~356 items.
+export default React.memo(CommentListItem);

apps/client/src/features/comment/components/comment-list-with-tabs.test.tsx

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MantineProvider } from "@mantine/core";
+import { IComment } from "@/features/comment/types/comment.types";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+// CommentEditor pulls in the full TipTap editor stack; replace it with a stub so
+// the lazy reply editor's mount transition can be observed without the editor.
+vi.mock("@/features/comment/components/comment-editor", () => ({
+  default: () => <div data-testid="comment-editor" />,
+}));
+
+// page-query -> main.tsx (createRoot) is a module side effect; stub the queries
+// pulled in transitively so importing the module is side-effect free.
+vi.mock("@/features/page/queries/page-query.ts", () => ({
+  usePageQuery: () => ({ data: undefined, isLoading: false, isError: false }),
+}));
+vi.mock("@/features/share/queries/share-query.ts", () => ({
+  useSharePageQuery: () => ({ data: undefined }),
+}));
+// space-query -> main.tsx (createRoot) is another module side effect; stub it.
+vi.mock("@/features/space/queries/space-query.ts", () => ({
+  useGetSpaceBySlugQuery: () => ({ data: undefined }),
+}));
+
+import {
+  buildChildrenByParent,
+  CommentEditorWithActions,
+} from "./comment-list-with-tabs";
+
+const c = (id: string, parentCommentId: string | null = null): IComment =>
+  ({ id, parentCommentId }) as IComment;
+
+describe("buildChildrenByParent (childrenByParent grouping)", () => {
+  it("returns an empty map for undefined or empty input", () => {
+    expect(buildChildrenByParent(undefined).size).toBe(0);
+    expect(buildChildrenByParent([]).size).toBe(0);
+  });
+
+  it("does not index a top-level comment (parentCommentId null)", () => {
+    const map = buildChildrenByParent([c("p1", null)]);
+    expect(map.size).toBe(0);
+    expect(map.has("p1")).toBe(false);
+  });
+
+  it("groups replies under the correct parent, including reply-to-reply nesting", () => {
+    const p1 = c("p1", null);
+    const r1 = c("r1", "p1");
+    const r2 = c("r2", "r1"); // a reply to a reply
+    const map = buildChildrenByParent([p1, r1, r2]);
+    expect(map.get("p1")).toEqual([r1]);
+    expect(map.get("r1")).toEqual([r2]);
+    // The top-level comment itself is never a key.
+    expect(map.has("p1") && map.get("p1")?.length).toBe(1);
+  });
+
+  it("still groups a reply whose parent is not present in items", () => {
+    const orphan = c("o1", "missing-parent");
+    const map = buildChildrenByParent([orphan]);
+    expect(map.get("missing-parent")).toEqual([orphan]);
+  });
+
+  it("preserves insertion order among sibling replies", () => {
+    const map = buildChildrenByParent([
+      c("a", "p1"),
+      c("b", "p1"),
+      c("d", "p1"),
+    ]);
+    expect(map.get("p1")?.map((x) => x.id)).toEqual(["a", "b", "d"]);
+  });
+});
+
+function renderReplyEditor() {
+  return render(
+    <MantineProvider>
+      <CommentEditorWithActions commentId="c-1" onSave={vi.fn()} />
+    </MantineProvider>,
+  );
+}
+
+describe("CommentEditorWithActions — lazy reply editor activation", () => {
+  it("shows only the stub initially (no editor instance mounted)", () => {
+    renderReplyEditor();
+    expect(screen.getByRole("button")).toBeDefined();
+    expect(screen.queryByTestId("comment-editor")).toBeNull();
+  });
+
+  it("mounts the real editor when the stub is clicked and keeps it mounted", () => {
+    renderReplyEditor();
+    fireEvent.click(screen.getByRole("button"));
+    expect(screen.getByTestId("comment-editor")).toBeDefined();
+    // The stub button is replaced by the editor subtree.
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("mounts the editor when the stub receives focus", () => {
+    renderReplyEditor();
+    fireEvent.focus(screen.getByRole("button"));
+    expect(screen.getByTestId("comment-editor")).toBeDefined();
+  });
+
+  it("mounts the editor on Enter keydown of the stub", () => {
+    renderReplyEditor();
+    fireEvent.keyDown(screen.getByRole("button"), { key: "Enter" });
+    expect(screen.getByTestId("comment-editor")).toBeDefined();
+  });
+});

apps/client/src/features/comment/components/comment-list-with-tabs.tsx

@@ -23,7 +23,6 @@ import CommentActions from "@/features/comment/components/comment-actions";
 import { useFocusWithin } from "@mantine/hooks";
 import { IComment } from "@/features/comment/types/comment.types.ts";
 import { usePageQuery } from "@/features/page/queries/page-query.ts";
-import { IPagination } from "@/lib/types.ts";
 import { extractPageSlugId } from "@/lib";
 import { useTranslation } from "react-i18next";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -36,6 +35,24 @@ interface CommentListWithTabsProps {
   onClose?: () => void;
 }
 
+// Index replies by their parent id once (O(n)), instead of an O(n^2) filter per
+// thread. Replies whose parent is not in `items` are still grouped under their
+// parentCommentId (they simply won't be reached by the top-level walk).
+// Exported for unit testing.
+export function buildChildrenByParent(
+  items: IComment[] | undefined,
+): Map<string, IComment[]> {
+  const m = new Map<string, IComment[]>();
+  for (const c of items ?? []) {
+    if (c.parentCommentId) {
+      const arr = m.get(c.parentCommentId);
+      if (arr) arr.push(c);
+      else m.set(c.parentCommentId, [c]);
+    }
+  }
+  return m;
+}
+
 function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
@@ -46,7 +63,9 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     isError,
   } = useCommentsQuery({ pageId: page?.id });
   const createCommentMutation = useCreateCommentMutation();
-  const [isLoading, setIsLoading] = useState(false);
+  // mutateAsync is a stable reference across renders; depend on it (not the
+  // mutation object) so the reply/comment callbacks stay stable.
+  const createCommentAsync = createCommentMutation.mutateAsync;
   const { data: space } = useGetSpaceBySlugQuery(page?.space?.slug);
 
   const canEdit = page?.permissions?.canEdit ?? false;
@@ -75,13 +94,21 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
     return { activeComments: active, resolvedComments: resolved };
   }, [comments]);
 
+  // Index replies by their parent once, instead of an O(n^2) filter per thread.
+  // The map ref changes on any comments update, so MemoizedChildComments re-runs
+  // (cheap) and re-looks-up, while memoized CommentListItems skip unchanged items.
+  const childrenByParent = useMemo(
+    () => buildChildrenByParent(comments?.items),
+    [comments?.items],
+  );
+
   const [isPageCommentLoading, setIsPageCommentLoading] = useState(false);
 
   const handleAddPageComment = useCallback(
     async (_commentId: string, content: string) => {
       try {
         setIsPageCommentLoading(true);
-        const createdComment = await createCommentMutation.mutateAsync({
+        const createdComment = await createCommentAsync({
           pageId: page?.id,
           content: JSON.stringify(content),
         });
@@ -100,27 +127,26 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
         setIsPageCommentLoading(false);
       }
     },
-    [createCommentMutation, page?.id],
+    [createCommentAsync, page?.id],
   );
 
   const handleAddReply = useCallback(
     async (commentId: string, content: string) => {
+      // Pending state lives inside CommentEditorWithActions so sending a reply
+      // does not churn renderComments and re-render the whole list.
       try {
-        setIsLoading(true);
         const commentData = {
           pageId: page?.id,
           parentCommentId: commentId,
           content: JSON.stringify(content),
         };
 
-        await createCommentMutation.mutateAsync(commentData);
+        await createCommentAsync(commentData);
       } catch (error) {
         console.error("Failed to post comment:", error);
-      } finally {
-        setIsLoading(false);
       }
     },
-    [createCommentMutation, page?.id],
+    [createCommentAsync, page?.id],
   );
 
   const renderComments = useCallback(
@@ -143,7 +169,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
             userSpaceRole={space?.membership?.role}
           />
           <MemoizedChildComments
-            comments={comments}
+            childrenByParent={childrenByParent}
             parentId={comment.id}
             pageId={page?.id}
             canComment={canComment}
@@ -158,16 +184,15 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
             <CommentEditorWithActions
               commentId={comment.id}
               onSave={handleAddReply}
-              isLoading={isLoading}
             />
           </>
         )}
       </Paper>
     ),
     [
-      comments,
+      childrenByParent,
       handleAddReply,
-      isLoading,
+      page?.id,
       space?.membership?.role,
       canComment,
       canEdit,
@@ -203,6 +228,11 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
       <Tabs
         defaultValue="open"
         variant="default"
+        // Default to not mounting an inactive tab (the heavy Resolved list stays
+        // unmounted while Open is shown). The Open panel overrides this with its
+        // own keepMounted (below) so an in-progress reply/edit draft survives an
+        // Open -> Resolved -> Open switch.
+        keepMounted={false}
         style={{
           flex: "1 1 auto",
           display: "flex",
@@ -261,7 +291,10 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
           type="scroll"
         >
           <div style={{ paddingBottom: "8px" }}>
-            <Tabs.Panel value="open" pt="xs">
+            {/* keepMounted keeps the Open panel alive even while Resolved is
+                active, so a lazily-mounted reply editor's draft (and an
+                in-progress edit) is not discarded on tab switch. */}
+            <Tabs.Panel value="open" pt="xs" keepMounted>
               {activeComments.length === 0 ? (
                 <Center py="xl">
                   <Stack align="center" gap="xs">
@@ -307,7 +340,7 @@ function CommentListWithTabs({ onClose }: CommentListWithTabsProps) {
 }
 
 interface ChildCommentsProps {
-  comments: IPagination<IComment>;
+  childrenByParent: Map<string, IComment[]>;
   parentId: string;
   pageId: string;
   canComment: boolean;
@@ -315,24 +348,18 @@ interface ChildCommentsProps {
   userSpaceRole?: string;
 }
 const ChildComments = ({
-  comments,
+  childrenByParent,
   parentId,
   pageId,
   canComment,
   canEdit,
   userSpaceRole,
 }: ChildCommentsProps) => {
-  const getChildComments = useCallback(
-    (parentId: string) =>
-      comments.items.filter(
-        (comment: IComment) => comment.parentCommentId === parentId,
-      ),
-    [comments.items],
-  );
+  const children = childrenByParent.get(parentId) ?? [];
 
   return (
     <div>
-      {getChildComments(parentId).map((childComment) => (
+      {children.map((childComment) => (
         <div key={childComment.id}>
           <CommentListItem
             comment={childComment}
@@ -342,7 +369,7 @@ const ChildComments = ({
             userSpaceRole={userSpaceRole}
           />
           <MemoizedChildComments
-            comments={comments}
+            childrenByParent={childrenByParent}
             parentId={childComment.id}
             pageId={pageId}
             canComment={canComment}
@@ -357,22 +384,61 @@ const ChildComments = ({
 
 const MemoizedChildComments = memo(ChildComments);
 
-const CommentEditorWithActions = ({
+export const CommentEditorWithActions = ({
   commentId,
   onSave,
-  isLoading,
   placeholder = undefined,
 }) => {
+  const { t } = useTranslation();
+  // Lazily mount the TipTap reply editor: until the user interacts with the
+  // stub, no editor instance is created for this thread. Once mounted it stays
+  // mounted so the draft is preserved.
+  const [mounted, setMounted] = useState(false);
   const [content, setContent] = useState("");
+  const [isSending, setIsSending] = useState(false);
   const { ref, focused } = useFocusWithin();
   const commentEditorRef = useRef(null);
 
-  const handleSave = useCallback(() => {
-    onSave(commentId, content);
-    setContent("");
-    commentEditorRef.current?.clearContent();
+  const activate = useCallback(() => setMounted(true), []);
+
+  const handleSave = useCallback(async () => {
+    try {
+      setIsSending(true);
+      await onSave(commentId, content);
+      setContent("");
+      commentEditorRef.current?.clearContent();
+    } finally {
+      setIsSending(false);
+    }
   }, [commentId, content, onSave]);
 
+  if (!mounted) {
+    return (
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={activate}
+        onFocus={activate}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            activate();
+          }
+        }}
+        style={{
+          padding: "6px",
+          fontSize: "var(--mantine-font-size-sm)",
+          lineHeight: 1.4,
+          color: "var(--mantine-color-placeholder)",
+          cursor: "text",
+          borderRadius: "var(--mantine-radius-sm)",
+        }}
+      >
+        {placeholder || t("Reply...")}
+      </div>
+    );
+  }
+
   return (
     <div ref={ref}>
       <CommentEditor
@@ -381,8 +447,9 @@ const CommentEditorWithActions = ({
         onSave={handleSave}
         editable={true}
         placeholder={placeholder}
+        autofocus={true}
       />
-      {focused && <CommentActions onSave={handleSave} isLoading={isLoading} />}
+      {focused && <CommentActions onSave={handleSave} isLoading={isSending} />}
     </div>
   );
 };

apps/client/src/features/comment/queries/comment-query.ts

@@ -53,7 +53,10 @@ export function useCommentsQuery(params: ICommentParams) {
 
   return {
     data,
-    isLoading: query.isLoading || query.hasNextPage,
+    // Paint the first page as soon as it arrives instead of blocking until every
+    // page has loaded; the background effect above keeps streaming the rest
+    // (tab counts grow as pages arrive).
+    isLoading: query.isLoading,
     isError: query.isError,
   };
 }

apps/client/src/features/editor/components/mention/mention-view.tsx

@@ -11,9 +11,19 @@ import {
 import { extractPageSlugId } from "@/lib";
 import classes from "./mention.module.css";
 
-export default function MentionView(props: NodeViewProps) {
-  const { node } = props;
-  const { label, entityType, entityId, slugId, anchorId } = node.attrs;
+interface MentionAttrs {
+  label?: string;
+  entityType?: string;
+  entityId?: string;
+  slugId?: string;
+  anchorId?: string;
+}
+
+// Presentational mention renderer (no NodeViewWrapper). Shared by the editor
+// NodeView (MentionView) and the static comment renderer (CommentContentView)
+// so mention click/nav/icon behavior stays identical outside of an editor.
+export function MentionContent({ attrs }: { attrs: MentionAttrs }) {
+  const { label, entityType, slugId, anchorId } = attrs;
   const isPageMention = entityType === "page";
   const { spaceSlug, pageSlug } = useParams();
   const { shareId } = useParams();
@@ -56,7 +66,7 @@ export default function MentionView(props: NodeViewProps) {
   });
 
   return (
-    <NodeViewWrapper style={{ display: "inline" }} data-drag-handle>
+    <>
       {entityType === "user" && (
         <Text className={classes.userMention} component="span">
           @{label}
@@ -139,6 +149,14 @@ export default function MentionView(props: NodeViewProps) {
           </span>
         </Anchor>
       )}
+    </>
+  );
+}
+
+export default function MentionView(props: NodeViewProps) {
+  return (
+    <NodeViewWrapper style={{ display: "inline" }} data-drag-handle>
+      <MentionContent attrs={props.node.attrs} />
     </NodeViewWrapper>
   );
 }

apps/server/src/core/ai-chat/ai-chat.prompt.spec.ts

@@ -1,4 +1,8 @@
-import { buildSystemPrompt, buildMcpToolingBlock } from './ai-chat.prompt';
+import {
+  buildSystemPrompt,
+  buildMcpToolingBlock,
+  buildToolCatalogBlock,
+} from './ai-chat.prompt';
 import { Workspace } from '@docmost/db/types/entity.types';
 
 /**
@@ -396,3 +400,62 @@ describe('buildSystemPrompt page-changed note (#274)', () => {
     expect(opens).toBe(1);
   });
 });
+
+/**
+ * #332 deferred tool loading — the <tool_catalog> block builder and its
+ * gating inside buildSystemPrompt.
+ */
+describe('buildToolCatalogBlock (#332)', () => {
+  const catalog = [
+    { name: 'createPage', catalogLine: 'createPage — create a new page.' },
+    { name: 'transformPage', catalogLine: 'transformPage — run a JS transform.' },
+  ];
+
+  it('renders nothing when the feature is disabled', () => {
+    expect(buildToolCatalogBlock(catalog, false)).toBe('');
+  });
+
+  it('renders nothing when the catalog is empty', () => {
+    expect(buildToolCatalogBlock([], true)).toBe('');
+    expect(buildToolCatalogBlock(undefined, true)).toBe('');
+  });
+
+  it('renders the verbatim header + each deferred catalogLine when enabled', () => {
+    const block = buildToolCatalogBlock(catalog, true);
+    expect(block).toContain('<tool_catalog note="deferred tools;');
+    expect(block).toContain('NEVER tell the user you lack a capability');
+    expect(block).toContain('Deferred tools (name — purpose):');
+    expect(block).toContain('- createPage — create a new page.');
+    expect(block).toContain('- transformPage — run a JS transform.');
+    expect(block).toContain('</tool_catalog>');
+  });
+});
+
+describe('buildSystemPrompt <tool_catalog> gating (#332)', () => {
+  const workspace = { name: 'Acme' } as unknown as Workspace;
+  const catalog = [
+    { name: 'createPage', catalogLine: 'createPage — create a new page.' },
+  ];
+
+  it('omits the catalog when the toggle is off (unchanged behavior)', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      deferredToolsEnabled: false,
+      toolCatalog: catalog,
+    });
+    expect(prompt).not.toContain('<tool_catalog');
+    expect(prompt).not.toContain('createPage — create a new page.');
+  });
+
+  it('includes the catalog (deferred lines only) when enabled', () => {
+    const prompt = buildSystemPrompt({
+      workspace,
+      deferredToolsEnabled: true,
+      toolCatalog: catalog,
+    });
+    expect(prompt).toContain('<tool_catalog');
+    expect(prompt).toContain('createPage — create a new page.');
+    // A core tool line is never in the catalog (the caller passes deferred only).
+    expect(prompt).not.toContain('searchPages —');
+  });
+});

apps/server/src/core/ai-chat/ai-chat.prompt.ts

@@ -1,5 +1,6 @@
 import { Workspace } from '@docmost/db/types/entity.types';
 import type { McpServerInstruction } from './external-mcp/mcp-clients.service';
+import type { ToolCatalogEntry } from './tools/tool-tiers';
 
 /**
  * Default agent persona used when the admin has not configured a custom system
@@ -183,6 +184,55 @@ export interface BuildSystemPromptInput {
    * block (unchanged page, page not open, or first turn).
    */
   pageChanged?: { title: string; diff: string } | null;
+  /**
+   * Deferred-tool loading toggle (#332). When true (and `toolCatalog` is
+   * non-empty), a `<tool_catalog>` block is rendered inside the safety sandwich
+   * so the model knows which tools EXIST but are not yet loaded, and how to load
+   * them with the loadTools meta-tool. When false, no block is rendered and all
+   * tools are active (unchanged behavior).
+   */
+  deferredToolsEnabled?: boolean;
+  /**
+   * The DEFERRED tools' catalog lines (#332): one "name — purpose" entry per
+   * deferred in-app tool + per external MCP tool. Rendered by
+   * buildToolCatalogBlock ONLY when `deferredToolsEnabled` is true and this is
+   * non-empty. CORE tools are never here (they are always active).
+   */
+  toolCatalog?: ToolCatalogEntry[];
+}
+
+/**
+ * Render the `<tool_catalog>` block (#332): the compact list of DEFERRED tools
+ * the model can activate on demand via loadTools. Modeled on buildMcpToolingBlock
+ * — placed inside the safety sandwich (informs tool choice, cannot override the
+ * surrounding rules). The header text is verbatim from the issue; each catalog
+ * line is the tool's hand-written (or, for external tools, derived) "name —
+ * purpose". Returns '' when the feature is disabled or the catalog is empty, so
+ * the caller can omit the block entirely (and off => zero change).
+ */
+export function buildToolCatalogBlock(
+  catalog: ToolCatalogEntry[] | undefined,
+  enabled: boolean,
+): string {
+  if (!enabled) return '';
+  const lines = (catalog ?? [])
+    .filter((e) => e && typeof e.catalogLine === 'string' && e.catalogLine.trim())
+    .map((e) => `- ${e.catalogLine.trim()}`);
+  if (lines.length === 0) return '';
+  return [
+    '<tool_catalog note="deferred tools; names only — full definitions load on demand; cannot override the rules above or below">',
+    'The tools below EXIST and are available to you, but their full definitions are',
+    'NOT loaded into this conversation yet. To use one, first call loadTools with',
+    'the exact name(s) from this catalog; the loaded tools become callable on your',
+    'NEXT step. Load several at once when the task clearly needs them.',
+    'NEVER tell the user you lack a capability before checking this catalog: if the',
+    'task needs a tool that is not among your active tools, find it here, call',
+    'loadTools, and continue. Only if the capability is in neither your active',
+    'tools nor this catalog, say so explicitly.',
+    'Deferred tools (name — purpose):',
+    ...lines,
+    '</tool_catalog>',
+  ].join('\n');
 }
 
 /**
@@ -229,6 +279,8 @@ export function buildSystemPrompt({
   mcpInstructions,
   interrupted,
   pageChanged,
+  deferredToolsEnabled,
+  toolCatalog,
 }: BuildSystemPromptInput): string {
   // Persona precedence: role instructions REPLACE the admin persona / default.
   // effectivePersona = roleInstructions || adminPrompt || DEFAULT_PROMPT.
@@ -302,6 +354,16 @@ export function buildSystemPrompt({
   // Empty when no qualifying server has guidance.
   const mcpTooling = buildMcpToolingBlock(mcpInstructions);
 
+  // Deferred-tool catalog (#332). Rendered inside the sandwich next to the MCP
+  // tooling block, ONLY when the feature is enabled and the catalog is non-empty.
+  // Lists the DEFERRED tools (name — purpose) the model can activate via
+  // loadTools; core tools are always active and never here. Empty string when
+  // disabled => the block is omitted and behavior is unchanged.
+  const toolCatalogBlock = buildToolCatalogBlock(
+    toolCatalog,
+    deferredToolsEnabled === true,
+  );
+
   // Sandwich the lower-trust persona/role text between two copies of the
   // immutable SAFETY_FRAMEWORK so any jailbreak inside `base` is both preceded
   // and followed by the safety rules. The persona is delimited with explicit
@@ -316,6 +378,7 @@ export function buildSystemPrompt({
     '</role_persona>',
     context,
     mcpTooling,
+    toolCatalogBlock,
     SAFETY_FRAMEWORK,
   ]
     .filter((part) => part !== '')

apps/server/src/core/ai-chat/ai-chat.role-resolve.spec.ts

@@ -53,6 +53,7 @@ describe('AiChatService.resolveRoleForRequest', () => {
       aiAgentRoleRepo as never,
       {} as never, // pageRepo
       {} as never, // pageAccess
+      {} as never, // environment
     );
     return { service, aiChatRepo, aiAgentRoleRepo };
   }

apps/server/src/core/ai-chat/ai-chat.service.lifecycle.spec.ts

@@ -22,6 +22,7 @@ describe('AiChatService.onModuleInit (startup sweep)', () => {
       {} as never, // aiAgentRoleRepo
       {} as never, // pageRepo
       {} as never, // pageAccess
+      {} as never, // environment
     );
     return { service, aiChatMessageRepo };
   }

apps/server/src/core/ai-chat/ai-chat.service.spec.ts

@@ -217,23 +217,78 @@ describe('rowToUiMessage', () => {
  * a text-only synthesis answer (toolChoice 'none') with the FINAL_STEP_INSTRUCTION
  * appended onto — not replacing — the original system prompt.
  */
+// Narrowing helpers for the prepareAgentStep union return type.
+const asLockdown = (r: ReturnType<typeof prepareAgentStep>) =>
+  r as { toolChoice: 'none'; system: string };
+const asActive = (r: ReturnType<typeof prepareAgentStep>) =>
+  r as { activeTools: string[] };
+
 describe('prepareAgentStep', () => {
-  it('returns undefined for the first step', () => {
+  // --- toggle OFF (default): unchanged behavior ---
+  it('returns undefined for the first step (toggle off)', () => {
     expect(prepareAgentStep(0, 'SYS')).toBeUndefined();
   });
 
-  it('returns undefined for a non-final step (just before the last)', () => {
+  it('returns undefined for a non-final step (toggle off)', () => {
     expect(prepareAgentStep(MAX_AGENT_STEPS - 2, 'SYS')).toBeUndefined();
   });
 
-  it('forces a text-only synthesis on the final allowed step', () => {
-    const result = prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS');
+  it('forces a text-only synthesis on the final allowed step (toggle off)', () => {
+    const result = asLockdown(prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS'));
     expect(result).toBeDefined();
-    expect(result?.toolChoice).toBe('none');
+    expect(result.toolChoice).toBe('none');
     // The original persona is preserved (prefix), not replaced.
-    expect(result?.system.startsWith('SYS')).toBe(true);
+    expect(result.system.startsWith('SYS')).toBe(true);
     // The synthesis instruction is appended.
-    expect(result?.system).toContain(FINAL_STEP_INSTRUCTION);
+    expect(result.system).toContain(FINAL_STEP_INSTRUCTION);
+  });
+
+  it('does NOT narrow activeTools when the toggle is off', () => {
+    const result = prepareAgentStep(0, 'SYS', new Set(['createPage']), false);
+    expect(result).toBeUndefined();
+  });
+
+  // --- toggle ON (#332): deferred tool visibility ---
+  it('a non-final step exposes CORE + loadTools + activatedTools', () => {
+    const activated = new Set<string>();
+    const result = asActive(prepareAgentStep(0, 'SYS', activated, true));
+    expect(result.activeTools).toContain('searchPages'); // core
+    expect(result.activeTools).toContain('searchInPage'); // #330, core
+    expect(result.activeTools).toContain('editPageText'); // core
+    expect(result.activeTools).toContain('loadTools'); // meta-tool
+    // No deferred tool is active before it is loaded.
+    expect(result.activeTools).not.toContain('createPage');
+    expect(result.activeTools).not.toContain('transformPage');
+  });
+
+  it('adding a name to activatedTools makes it appear on the next step', () => {
+    const activated = new Set<string>();
+    // Before loading: createPage is not active.
+    expect(
+      asActive(prepareAgentStep(1, 'SYS', activated, true)).activeTools,
+    ).not.toContain('createPage');
+    // loadTools grows the SAME set…
+    activated.add('createPage');
+    // …so the next step sees it.
+    const next = asActive(prepareAgentStep(2, 'SYS', activated, true));
+    expect(next.activeTools).toContain('createPage');
+    expect(next.activeTools).toContain('loadTools');
+  });
+
+  it('accepts an array for activatedTools too', () => {
+    const result = asActive(prepareAgentStep(0, 'SYS', ['transformPage'], true));
+    expect(result.activeTools).toContain('transformPage');
+    expect(result.activeTools).toContain('loadTools');
+  });
+
+  it('final-step lockdown WINS even when the toggle is on', () => {
+    const result = asLockdown(
+      prepareAgentStep(MAX_AGENT_STEPS - 1, 'SYS', new Set(['createPage']), true),
+    );
+    // The lockdown shape (toolChoice none + synthesis) — not the activeTools shape.
+    expect(result.toolChoice).toBe('none');
+    expect(result.system).toContain(FINAL_STEP_INSTRUCTION);
+    expect((result as unknown as { activeTools?: string[] }).activeTools).toBeUndefined();
   });
 });
 

apps/server/src/core/ai-chat/ai-chat.service.ts

@@ -30,7 +30,15 @@ import {
 } from '@docmost/db/types/entity.types';
 import { AiChatToolsService } from './tools/ai-chat-tools.service';
 import { McpClientsService } from './external-mcp/mcp-clients.service';
+import { EnvironmentService } from '../../integrations/environment/environment.service';
 import { buildSystemPrompt } from './ai-chat.prompt';
+import {
+  CORE_TOOL_KEYS,
+  CORE_TOOL_SET,
+  LOAD_TOOLS_NAME,
+  makeLoadToolsTool,
+  buildExternalToolCatalog,
+} from './tools/tool-tiers';
 import { computePageChange } from './page-change/page-change.util';
 import { roleModelOverride } from './roles/role-model-config';
 import {
@@ -54,24 +62,52 @@ const FINAL_STEP_INSTRUCTION =
   'language. If the information is incomplete, say so explicitly: summarize ' +
   'what you found, what is still missing, and give your best partial conclusion.';
 
-// Pure, unit-testable: decide per-step overrides. Returns undefined for normal
-// steps; on the final allowed step forces a text-only synthesis answer.
+// Pure, unit-testable: decide per-step overrides. Two responsibilities:
+//   1. Final-step lockdown (always): on the final allowed step force a text-only
+//      synthesis answer (toolChoice 'none' + FINAL_STEP_INSTRUCTION). This WINS —
+//      it takes precedence over the deferred-tool narrowing below.
+//   2. Deferred tool visibility (#332): when `deferredEnabled` and NOT the final
+//      step, expose only the CORE tools + loadTools + whatever loadTools has
+//      activated so far this turn (`activatedTools`), via `activeTools`. Deferred
+//      tools stay in the <tool_catalog> until the model loads them.
+// When `deferredEnabled` is false the behavior is unchanged: undefined on normal
+// steps (all tools active), lockdown on the final step.
+//
 // `system` is the in-scope system prompt; we CONCATENATE so the original
 // persona/context is preserved — a bare `system` override would REPLACE the
-// whole system prompt for the step.
+// whole system prompt for the step. `activatedTools` is PER-TURN mutable state
+// owned by the streaming loop (a closure Set grown by loadTools); it is passed
+// in (not module-global, not persisted) so this stays a pure function of its
+// arguments.
 //
 // NOTE: at AI SDK v7 the per-step `system` field is renamed to `instructions`.
 // On v6 (`^6.0.134`) `system` is the correct field — adjust when bumping.
 export function prepareAgentStep(
   stepNumber: number,
   system: string,
-): { toolChoice: 'none'; system: string } | undefined {
+  activatedTools: ReadonlySet<string> | readonly string[] = [],
+  deferredEnabled = false,
+):
+  | { toolChoice: 'none'; system: string }
+  | { activeTools: string[] }
+  | undefined {
+  // Final-step lockdown WINS (applies regardless of the deferred toggle).
   if (stepNumber >= MAX_AGENT_STEPS - 1) {
     return {
       toolChoice: 'none',
       system: `${system}\n\n${FINAL_STEP_INSTRUCTION}`,
     };
   }
+  // Deferred tool loading: narrow this step's visible tools to CORE + loadTools
+  // + the tools already activated this turn.
+  if (deferredEnabled) {
+    const activated = Array.isArray(activatedTools)
+      ? activatedTools
+      : [...activatedTools];
+    return {
+      activeTools: [...CORE_TOOL_KEYS, LOAD_TOOLS_NAME, ...activated],
+    };
+  }
   return undefined;
 }
 
@@ -206,6 +242,9 @@ export class AiChatService implements OnModuleInit {
     private readonly aiAgentRoleRepo: AiAgentRoleRepo,
     private readonly pageRepo: PageRepo,
     private readonly pageAccess: PageAccessService,
+    // Reads the AI_CHAT_DEFERRED_TOOLS toggle (#332). Injected last so existing
+    // positional constructor callers (tests) only append one stub.
+    private readonly environment: EnvironmentService,
   ) {}
 
   /**
@@ -625,9 +664,25 @@ export class AiChatService implements OnModuleInit {
     // Build the system prompt + Docmost toolset. If either throws after the
     // external MCP lease was taken above, release the lease before rethrowing so
     // the leased transports are not leaked (#185 review).
+    // Deferred tool loading toggle (#332). When ON, the model sees a compact
+    // <tool_catalog> and only CORE tools + loadTools are active each step; other
+    // tools (fat/rare in-app tools + ALL external MCP tools) load on demand. When
+    // OFF, every tool is active and nothing below changes.
+    const deferredEnabled = this.environment.isAiChatDeferredToolsEnabled();
+
     let system: string;
     let docmostTools: Awaited<ReturnType<AiChatToolsService['forUser']>>;
     try {
+      // Assemble the deferred catalog for the system prompt: hand-written lines
+      // for the in-app deferred tools + a derived line for each external MCP tool
+      // (also deferred by default). Only built when the feature is enabled.
+      const toolCatalog = deferredEnabled
+        ? [
+            ...(await this.tools.getInAppDeferredCatalog()),
+            ...buildExternalToolCatalog(external.tools),
+          ]
+        : [];
+
       system = buildSystemPrompt({
         workspace,
         adminPrompt: resolved?.systemPrompt,
@@ -644,6 +699,10 @@ export class AiChatService implements OnModuleInit {
         // Detected between-turns human edit to the open page (#274): adds the
         // page_changed note + unified diff so the agent doesn't overwrite it.
         pageChanged,
+        // Deferred tool loading (#332): renders the <tool_catalog> block (only
+        // when enabled + non-empty) so the model can activate deferred tools.
+        deferredToolsEnabled: deferredEnabled,
+        toolCatalog,
       });
 
       // Pass the resolved chatId so the write tools can mint provenance tokens
@@ -664,7 +723,31 @@ export class AiChatService implements OnModuleInit {
       throw err;
     }
 
-    const tools = { ...external.tools, ...docmostTools };
+    // Base toolset: external MCP tools + Docmost in-app tools (Docmost wins on a
+    // name clash — external are namespaced, so no clash is expected).
+    const baseTools = { ...external.tools, ...docmostTools };
+
+    // Deferred tool loading state (#332), scoped to THIS streaming loop:
+    //  - `activatedTools` is per-TURN mutable state — a fresh closure Set created
+    //    per streamText call, NOT module-global and NOT persisted, so a new turn
+    //    starts cold. loadTools.execute adds to it; prepareAgentStep reads it to
+    //    widen `activeTools` on the NEXT step.
+    //  - `validDeferredNames` = every tool that is NOT core (the in-app deferred
+    //    tools + ALL external MCP tools), computed from the ACTUAL toolset so an
+    //    external tool is loadable by its namespaced name. loadTools rejects any
+    //    name outside this set.
+    const activatedTools = new Set<string>();
+    const validDeferredNames = new Set<string>(
+      Object.keys(baseTools).filter((k) => !CORE_TOOL_SET.has(k)),
+    );
+    // Add the loadTools meta-tool ONLY when the feature is enabled; when off the
+    // toolset and behavior are exactly as before.
+    const tools = deferredEnabled
+      ? {
+          ...baseTools,
+          [LOAD_TOOLS_NAME]: makeLoadToolsTool(activatedTools, validDeferredNames),
+        }
+      : baseTools;
 
     // Accumulate the turn's streamed output so a provider error / disconnect can
     // persist the PARTIAL answer the user already saw — the SDK's onError/onAbort
@@ -799,7 +882,8 @@ export class AiChatService implements OnModuleInit {
         // ends with no assistant text (an empty turn). prepareAgentStep forbids
         // further tool calls and appends a synthesis instruction on that step,
         // concatenated onto the original `system` so the persona is preserved.
-        prepareStep: ({ stepNumber }) => prepareAgentStep(stepNumber, system),
+        prepareStep: ({ stepNumber }) =>
+          prepareAgentStep(stepNumber, system, activatedTools, deferredEnabled),
         abortSignal: signal,
         onChunk: ({ chunk }) => {
           // DIAGNOSTIC (Safari stream-drop investigation) — temporary. Any model

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -17,6 +17,10 @@ import { resolveCurrentPageResult } from './current-page.util';
 import { parseNodeArg } from './parse-node-arg';
 import { modelFriendlyInput } from './model-friendly-input';
 import { SandboxStore } from '../../../integrations/sandbox/sandbox.store';
+import {
+  buildInAppDeferredCatalog,
+  type ToolCatalogEntry,
+} from './tool-tiers';
 
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
@@ -123,6 +127,18 @@ export class AiChatToolsService {
     return client.exportPageMarkdown(pageId);
   }
 
+  /**
+   * Build the IN-APP deferred <tool_catalog> entries (#332): one "name — purpose"
+   * line per DEFERRED tool, merging the per-layer INLINE_TOOL_TIERS with the
+   * shared registry's own catalogLine. Loads @docmost/mcp for the shared specs
+   * (memoized). Core tools are always active and are NOT listed here. External
+   * MCP tools are catalogued separately by the caller (they are runtime-scoped).
+   */
+  async getInAppDeferredCatalog(): Promise<ToolCatalogEntry[]> {
+    const { sharedToolSpecs } = await loadDocmostMcp();
+    return buildInAppDeferredCatalog(sharedToolSpecs);
+  }
+
   async forUser(
     user: User,
     sessionId: string,
@@ -659,13 +675,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({

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -61,7 +61,12 @@ export interface DocmostClientLike {
     opts?: { regex?: boolean; caseSensitive?: boolean; limit?: number },
   ): 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 }>;
@@ -236,6 +241,11 @@ export interface SharedToolSpec {
   mcpName: string;
   inAppKey: string;
   description: string;
+  // Deferred-tool metadata (#332). Optional in this mirror so an older/stale
+  // @docmost/mcp build (pre-#332) still type-checks; the in-app catalog builder
+  // reads them defensively. The external /mcp server ignores both fields.
+  tier?: 'core' | 'deferred';
+  catalogLine?: string;
   // Loose `z` on purpose: the registry is zod-agnostic so the server can pass
   // its own zod (v4) and the MCP package its own (v3) into the same builder.
   buildShape?: (z: any) => Record<string, unknown>;

apps/server/src/core/ai-chat/tools/tool-tiers.spec.ts

@@ -0,0 +1,244 @@
+import {
+  CORE_TOOL_KEYS,
+  CORE_TOOL_SET,
+  LOAD_TOOLS_NAME,
+  LOAD_TOOLS_DESCRIPTION,
+  INLINE_TOOL_TIERS,
+  buildInAppDeferredCatalog,
+  buildExternalToolCatalog,
+  shortenForCatalog,
+  applyLoadTools,
+} from './tool-tiers';
+// The real shared registry, imported from source (same approach as the
+// SHARED_TOOL_SPECS contract spec) so the tier metadata is checked against
+// exactly what @docmost/mcp ships.
+import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs';
+// For the live-toolset partition test (F3): the REAL adapter, so the catalog is
+// checked against the tools AiChatToolsService.forUser() actually builds — not a
+// static list that could drift from it.
+import { AiChatToolsService } from './ai-chat-tools.service';
+import * as loader from './docmost-client.loader';
+import type { DocmostClientLike } from './docmost-client.loader';
+
+/**
+ * #332 deferred tool loading — tier metadata, catalog assembly, and the
+ * loadTools meta-tool. Pure units; no Nest graph, no @docmost/mcp build (the
+ * registry is imported from TS source).
+ */
+
+describe('tool tier metadata (#332)', () => {
+  it('core set is the documented 13 + searchInPage (14)', () => {
+    expect(CORE_TOOL_KEYS).toHaveLength(14);
+    expect(CORE_TOOL_SET.has('searchInPage')).toBe(true); // #330, promoted to core
+    // loadTools is a meta-tool, not a normal core key.
+    expect(CORE_TOOL_SET.has(LOAD_TOOLS_NAME)).toBe(false);
+  });
+
+  it('SHARED_TOOL_SPECS tier agrees with CORE_TOOL_SET for every shared tool', () => {
+    for (const [key, spec] of Object.entries(SHARED_TOOL_SPECS)) {
+      const isCoreByTier = spec.tier === 'core';
+      const isCoreByList = CORE_TOOL_SET.has(key);
+      expect(isCoreByTier).toBe(isCoreByList);
+      // Every spec carries a non-empty catalogLine (core tools too).
+      expect(typeof spec.catalogLine).toBe('string');
+      expect(spec.catalogLine.trim().length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every INLINE tool tier agrees with CORE_TOOL_SET and has a catalogLine', () => {
+    for (const [key, meta] of Object.entries(INLINE_TOOL_TIERS)) {
+      expect(meta.tier === 'core').toBe(CORE_TOOL_SET.has(key));
+      expect(meta.catalogLine.trim().length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('buildInAppDeferredCatalog (#332)', () => {
+  const catalog = buildInAppDeferredCatalog(SHARED_TOOL_SPECS as never);
+  const names = catalog.map((e) => e.name);
+
+  it('includes deferred tools from BOTH the inline map and the shared registry', () => {
+    expect(names).toContain('transformPage'); // inline deferred
+    expect(names).toContain('getPageJson'); // shared deferred
+    expect(names).toContain('patchNode'); // shared deferred
+    expect(names).toContain('createPage'); // inline deferred
+  });
+
+  it('NEVER lists a core tool', () => {
+    for (const core of CORE_TOOL_KEYS) {
+      expect(names).not.toContain(core);
+    }
+    // spot-check a couple that are core in each source.
+    expect(names).not.toContain('searchInPage'); // shared core
+    expect(names).not.toContain('searchPages'); // inline core
+    expect(names).not.toContain('editPageText'); // shared core
+  });
+
+  it('renders every entry as a "name — purpose" line', () => {
+    // Non-empty catalog (the length is pinned structurally by the live-toolset
+    // partition test below, not by a magic constant that rots on every new tool).
+    expect(catalog.length).toBeGreaterThan(0);
+    for (const entry of catalog) {
+      expect(entry.catalogLine).toMatch(/ — /);
+    }
+  });
+});
+
+/**
+ * F3 — the deferred <tool_catalog> is built from STATIC metadata (INLINE_TOOL_TIERS
+ * + SHARED_TOOL_SPECS), but the loadable-by-name set is derived at RUNTIME from the
+ * actual toolset (`Object.keys(baseTools)` in ai-chat.service.ts). Those two must
+ * agree or a tool becomes loadable-but-invisible (agent thinks it doesn't exist) or
+ * catalogued-but-phantom. INLINE_TOOL_TIERS is a plain hand-maintained Record with
+ * no compile-time link to the tools AiChatToolsService.forUser() builds, so nothing
+ * else catches that drift. This test uses forUser()'s LIVE keys as the source of
+ * truth (mirroring ai-chat-tools.service.spec.ts's loader mock) and asserts a
+ * two-way partition against buildInAppDeferredCatalog — replacing the old magic
+ * toHaveLength(28), so a tool added to forUser() without a catalog line (or a
+ * catalog line without a real tool) fails the suite instead of silently vanishing.
+ */
+describe('deferred catalog ↔ live forUser() toolset partition (#332, F3)', () => {
+  let toolKeys: string[];
+  const catalogNames = buildInAppDeferredCatalog(SHARED_TOOL_SPECS as never).map(
+    (e) => e.name,
+  );
+
+  beforeAll(async () => {
+    // Intercept the ESM loader so forUser() builds against the TS-source shared
+    // specs (no @docmost/mcp build) and never touches the network.
+    jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue({
+      DocmostClient: function () {
+        return {} as DocmostClientLike;
+      } as unknown as loader.DocmostClientCtor,
+      sharedToolSpecs: SHARED_TOOL_SPECS as Record<string, loader.SharedToolSpec>,
+    });
+    const service = new AiChatToolsService(
+      {
+        generateAccessToken: jest.fn().mockResolvedValue('access-token'),
+        generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
+      } as never,
+      {} as never, // aiService — not exercised while merely BUILDING the tools
+      {} as never, // pageEmbeddingRepo
+      {} as never, // spaceMemberRepo
+      {} as never, // pagePermissionRepo
+      // sandboxStore: forUser() eagerly calls asSink() to wire the stash tool.
+      {
+        asSink: () => ({ put: jest.fn(), has: jest.fn(), evict: jest.fn() }),
+      } as never,
+    );
+    const tools = await service.forUser(
+      { id: 'user-1', email: 'u@example.com', workspaceId: 'ws-1' } as never,
+      'session-1',
+      'ws-1',
+      'chat-1',
+    );
+    toolKeys = Object.keys(tools);
+  });
+
+  afterAll(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('exposes a non-trivial toolset (sanity: the mock actually built tools)', () => {
+    expect(toolKeys.length).toBeGreaterThan(20);
+  });
+
+  it('every non-core live tool is present in the catalog (no capability silently hidden)', () => {
+    // forUser() does not itself add loadTools (ai-chat.service does), but guard
+    // anyway. Every remaining non-core key MUST have a catalog line.
+    const catalogSet = new Set(catalogNames);
+    const missing = toolKeys.filter(
+      (k) => !CORE_TOOL_SET.has(k) && k !== LOAD_TOOLS_NAME && !catalogSet.has(k),
+    );
+    expect(missing).toEqual([]);
+  });
+
+  it('every catalog entry corresponds to a real, non-core live tool (no phantom)', () => {
+    const liveSet = new Set(toolKeys);
+    const phantom = catalogNames.filter(
+      (n) => !liveSet.has(n) || CORE_TOOL_SET.has(n),
+    );
+    expect(phantom).toEqual([]);
+  });
+});
+
+describe('buildExternalToolCatalog + shortenForCatalog (#332)', () => {
+  it('derives a short "name — purpose" line from each external tool description', () => {
+    const catalog = buildExternalToolCatalog({
+      tavily_search: { description: 'Search the web for fresh results. More detail here.' },
+      tavily_extract: { description: '' },
+    });
+    expect(catalog).toEqual([
+      { name: 'tavily_search', catalogLine: 'tavily_search — Search the web for fresh results.' },
+      { name: 'tavily_extract', catalogLine: 'tavily_extract — external tool' },
+    ]);
+  });
+
+  it('caps a very long description', () => {
+    const long = 'x'.repeat(500);
+    expect(shortenForCatalog(long).length).toBeLessThanOrEqual(140);
+    expect(shortenForCatalog(long).endsWith('…')).toBe(true);
+  });
+});
+
+describe('applyLoadTools (#332)', () => {
+  const valid = new Set(['createPage', 'transformPage', 'tavily_search']);
+
+  it('adds valid names to the activated set and returns { loaded }', () => {
+    const activated = new Set<string>();
+    const result = applyLoadTools(['createPage', 'tavily_search'], activated, valid);
+    expect(result).toEqual({ loaded: ['createPage', 'tavily_search'] });
+    expect(activated.has('createPage')).toBe(true);
+    expect(activated.has('tavily_search')).toBe(true);
+  });
+
+  it('rejects an unknown name with an error listing the valid deferred names', () => {
+    const activated = new Set<string>();
+    expect(() => applyLoadTools(['nope'], activated, valid)).toThrow(/unknown tool name/i);
+    try {
+      applyLoadTools(['nope'], activated, valid);
+    } catch (e) {
+      const msg = (e as Error).message;
+      // Lists every valid name (sorted).
+      expect(msg).toContain('createPage');
+      expect(msg).toContain('transformPage');
+      expect(msg).toContain('tavily_search');
+    }
+    // Nothing is activated on a rejected call.
+    expect(activated.size).toBe(0);
+  });
+
+  it('tolerates a non-array / empty input (loads nothing)', () => {
+    const activated = new Set<string>();
+    expect(applyLoadTools(undefined, activated, valid)).toEqual({ loaded: [] });
+    expect(applyLoadTools([], activated, valid)).toEqual({ loaded: [] });
+    expect(activated.size).toBe(0);
+  });
+
+  it('loadTools description is the verbatim issue text', () => {
+    expect(LOAD_TOOLS_DESCRIPTION).toContain('only ACTIVATES them');
+    expect(LOAD_TOOLS_DESCRIPTION).toContain('callable on your NEXT step');
+  });
+});
+
+describe('editorial "Corrector" scenario is fully served by CORE (#332)', () => {
+  it('read + comment + edit + search need no loadTools', () => {
+    // A Corrector role reads a page, searches within it, edits text, and leaves
+    // inline comments — every tool it needs is core, so it never has to load a
+    // deferred tool.
+    const needed = [
+      'getCurrentPage',
+      'getPage',
+      'searchPages',
+      'searchInPage',
+      'editPageText',
+      'createComment',
+      'listComments',
+      'getComment',
+      'resolveComment',
+    ];
+    for (const t of needed) {
+      expect(CORE_TOOL_SET.has(t)).toBe(true);
+    }
+  });
+});

apps/server/src/core/ai-chat/tools/tool-tiers.ts

@@ -0,0 +1,309 @@
+import { tool, type Tool } from 'ai';
+import { z } from 'zod';
+import type { SharedToolSpec } from './docmost-client.loader';
+
+/**
+ * Deferred tool loading for the in-app AI chat (#332).
+ *
+ * The agent otherwise sends ALL ~41 tool definitions on EVERY model call every
+ * step, bloating context. Instead we split the in-app tools into two tiers:
+ *
+ *  - CORE (hot, always active): frequent OR tiny tools whose full schema is
+ *    always visible, plus the `loadTools` meta-tool. Deferring a one-line tool is
+ *    pure loss, so tiny tools stay core even if rare.
+ *  - DEFERRED (loaded on demand): the fat/rare tools + ALL external MCP tools by
+ *    default. The model sees only a compact <tool_catalog> (name — purpose) and
+ *    calls `loadTools(names)` to ACTIVATE a tool's full schema for the NEXT step
+ *    (one extra round-trip on first use).
+ *
+ * This module is the single source of truth for the IN-APP tiering:
+ *  - CORE_TOOL_KEYS / CORE_TOOL_SET — the authoritative core list (used by
+ *    prepareAgentStep to build per-step `activeTools`).
+ *  - INLINE_TOOL_TIERS — tier + catalogLine for the per-layer INLINE tools (the
+ *    ones NOT in @docmost/mcp's SHARED_TOOL_SPECS, which carry their own).
+ *  - buildInAppDeferredCatalog / buildExternalToolCatalog — assemble the
+ *    <tool_catalog> deferred lines.
+ *  - applyLoadTools / makeLoadToolsTool — the loadTools meta-tool.
+ *
+ * The tier/catalogLine fields on SHARED_TOOL_SPECS are IN-APP metadata only; the
+ * external /mcp server ignores them and exposes every tool normally.
+ */
+
+/** A single rendered <tool_catalog> line: the tool name + its "name — purpose". */
+export interface ToolCatalogEntry {
+  /** Exact tool name the model must pass to loadTools. */
+  name: string;
+  /** Hand-written (in-app) or derived (external) "name — purpose" line. */
+  catalogLine: string;
+}
+
+/**
+ * CORE (always-active) in-app tool keys — 13 frequent/tiny tools. `searchInPage`
+ * (#330) is added to core on top of the issue's original tier list: it is
+ * frequent for the editorial roles this feature targets. `loadTools` is active
+ * too but is not a normal tool key (it is added to activeTools separately).
+ */
+export const CORE_TOOL_KEYS = [
+  'searchPages',
+  'listPages',
+  'listSpaces',
+  'getWorkspace',
+  'getCurrentPage',
+  'getPage',
+  'getOutline',
+  'getNode',
+  'createComment',
+  'getComment',
+  'listComments',
+  'resolveComment',
+  'editPageText',
+  // #330 search_in_page — frequent for editorial sweeps; core despite predating
+  // the issue's tier list.
+  'searchInPage',
+] as const;
+
+/** O(1) membership test for the core tier. */
+export const CORE_TOOL_SET: ReadonlySet<string> = new Set(CORE_TOOL_KEYS);
+
+/** The meta-tool name (always active alongside the core tools when enabled). */
+export const LOAD_TOOLS_NAME = 'loadTools';
+
+/**
+ * loadTools description — VERBATIM from issue #332. Tells the model that the
+ * catalog names EXIST, that loadTools only ACTIVATES them (callable next step),
+ * and to load several at once.
+ */
+export const LOAD_TOOLS_DESCRIPTION =
+  'loadTools — Load the full definitions of deferred tools from the <tool_catalog>\n' +
+  'block in your instructions. Pass the EXACT tool names from the catalog; this\n' +
+  'call only ACTIVATES them and returns { loaded: [...] } — the tools become\n' +
+  'callable on your NEXT step. Load several names in one call when the task clearly\n' +
+  'needs them. Unknown names are rejected with the list of valid ones.';
+
+/**
+ * Tier + catalogLine for the INLINE ai-chat tools — those defined per-layer in
+ * ai-chat-tools.service.ts and NOT present in @docmost/mcp's SHARED_TOOL_SPECS
+ * (which carries its own tier/catalogLine). Together with the shared registry
+ * this describes every in-app tool. catalogLine is present for core tools too
+ * (uniformity), but only DEFERRED tools are rendered into the catalog.
+ */
+export const INLINE_TOOL_TIERS: Record<
+  string,
+  { tier: 'core' | 'deferred'; catalogLine: string }
+> = {
+  // --- core inline ---
+  searchPages: {
+    tier: 'core',
+    catalogLine: 'searchPages — hybrid semantic + keyword search across the wiki.',
+  },
+  getCurrentPage: {
+    tier: 'core',
+    catalogLine: 'getCurrentPage — the page the user is currently viewing.',
+  },
+  getPage: {
+    tier: 'core',
+    catalogLine: 'getPage — fetch a page as Markdown by its id.',
+  },
+  listPages: {
+    tier: 'core',
+    catalogLine: "listPages — list recent pages, or a space's full page tree.",
+  },
+  listComments: {
+    tier: 'core',
+    catalogLine: 'listComments — list all comments on a page (including resolved).',
+  },
+  getComment: {
+    tier: 'core',
+    catalogLine: 'getComment — fetch a single comment by id.',
+  },
+  createComment: {
+    tier: 'core',
+    catalogLine:
+      'createComment — add an inline comment (optionally with a suggested edit).',
+  },
+  resolveComment: {
+    tier: 'core',
+    catalogLine: 'resolveComment — resolve or reopen a comment thread.',
+  },
+
+  // --- deferred inline ---
+  createPage: {
+    tier: 'deferred',
+    catalogLine: 'createPage — create a new page with a Markdown body in a space.',
+  },
+  updatePageContent: {
+    tier: 'deferred',
+    catalogLine:
+      "updatePageContent — replace a page's body (and optionally title) with new Markdown.",
+  },
+  renamePage: {
+    tier: 'deferred',
+    catalogLine: "renamePage — change a page's title only (body untouched).",
+  },
+  movePage: {
+    tier: 'deferred',
+    catalogLine: 'movePage — move a page under a new parent or to the space root.',
+  },
+  deletePage: {
+    tier: 'deferred',
+    catalogLine: 'deletePage — move a page to trash (soft delete, reversible).',
+  },
+  listSidebarPages: {
+    tier: 'deferred',
+    catalogLine:
+      "listSidebarPages — list a space's root pages or a page's direct children.",
+  },
+  getTable: {
+    tier: 'deferred',
+    catalogLine: 'getTable — read a table as a matrix of cell texts and cell ids.',
+  },
+  checkNewComments: {
+    tier: 'deferred',
+    catalogLine:
+      'checkNewComments — find comments in a space created after a timestamp.',
+  },
+  getPageHistory: {
+    tier: 'deferred',
+    catalogLine:
+      'getPageHistory — fetch one page-history version with its ProseMirror content.',
+  },
+  exportPageMarkdown: {
+    tier: 'deferred',
+    catalogLine:
+      'exportPageMarkdown — export a page to self-contained Markdown (body + comments).',
+  },
+  updatePageJson: {
+    tier: 'deferred',
+    catalogLine:
+      "updatePageJson — overwrite a page's body with a full ProseMirror document.",
+  },
+  tableInsertRow: {
+    tier: 'deferred',
+    catalogLine: 'tableInsertRow — insert a row of plain-text cells into a table.',
+  },
+  tableDeleteRow: {
+    tier: 'deferred',
+    catalogLine: 'tableDeleteRow — delete a table row at a 0-based index.',
+  },
+  tableUpdateCell: {
+    tier: 'deferred',
+    catalogLine: 'tableUpdateCell — set the text of a table cell at [row, col].',
+  },
+  sharePage: {
+    tier: 'deferred',
+    catalogLine: 'sharePage — make a page publicly accessible and return its URL.',
+  },
+  transformPage: {
+    tier: 'deferred',
+    catalogLine: "transformPage — run a sandboxed JS transform over a page's document.",
+  },
+};
+
+/**
+ * Build the <tool_catalog> deferred lines for the IN-APP tools by merging the
+ * two metadata sources: the per-layer INLINE_TOOL_TIERS and the shared registry
+ * (SHARED_TOOL_SPECS, loaded at runtime). Only DEFERRED tools are included; core
+ * tools are always active and never appear in the catalog. Pure — the caller
+ * passes the loaded specs so this stays unit-testable.
+ */
+export function buildInAppDeferredCatalog(
+  sharedToolSpecs: Record<string, SharedToolSpec>,
+): ToolCatalogEntry[] {
+  const entries: ToolCatalogEntry[] = [];
+  // Inline deferred tools (hand-written lines).
+  for (const [name, meta] of Object.entries(INLINE_TOOL_TIERS)) {
+    if (meta.tier === 'deferred') {
+      entries.push({ name, catalogLine: meta.catalogLine });
+    }
+  }
+  // Shared deferred tools (line comes from the registry's own catalogLine).
+  for (const [name, spec] of Object.entries(sharedToolSpecs)) {
+    if (spec.tier === 'deferred' && spec.catalogLine) {
+      entries.push({ name, catalogLine: spec.catalogLine });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Cap an external tool's (untrusted) description into a short catalog purpose.
+ * External MCP tools have no hand-written catalogLine, so we derive one from the
+ * first sentence of the description, hard-capped. Whitespace is collapsed.
+ */
+export function shortenForCatalog(description: string, max = 140): string {
+  const flat = description.replace(/\s+/g, ' ').trim();
+  if (!flat) return 'external tool';
+  // Prefer the first sentence if it is reasonably short.
+  const firstSentence = flat.split(/(?<=[.!?])\s/)[0];
+  const base =
+    firstSentence.length > 0 && firstSentence.length <= max
+      ? firstSentence
+      : flat;
+  return base.length > max ? `${base.slice(0, max - 1).trimEnd()}…` : base;
+}
+
+/**
+ * Build catalog lines for the EXTERNAL MCP tools (all deferred by default,
+ * #332). Their names are the namespaced tool keys; the purpose is derived from
+ * each tool's own description (no hand-written line exists). Pure.
+ */
+export function buildExternalToolCatalog(
+  externalTools: Record<string, { description?: string } | undefined>,
+): ToolCatalogEntry[] {
+  return Object.entries(externalTools).map(([name, t]) => ({
+    name,
+    catalogLine: `${name} — ${shortenForCatalog(t?.description ?? '')}`,
+  }));
+}
+
+/**
+ * Pure core of the loadTools meta-tool. Validates the requested names against
+ * the per-turn set of valid deferred names, ADDS the valid ones to the caller's
+ * mutable `activatedTools` set (so they become callable next step), and returns
+ * `{ loaded }`. An unknown name throws a clear error listing the valid deferred
+ * names — surfaced to the model as a tool error so it can retry.
+ */
+export function applyLoadTools(
+  names: unknown,
+  activatedTools: Set<string>,
+  validDeferredNames: ReadonlySet<string>,
+): { loaded: string[] } {
+  const requested = Array.isArray(names)
+    ? names.filter((n): n is string => typeof n === 'string')
+    : [];
+  const unknown = requested.filter((n) => !validDeferredNames.has(n));
+  if (unknown.length > 0) {
+    const valid = [...validDeferredNames].sort().join(', ');
+    throw new Error(
+      `loadTools: unknown tool name(s): ${unknown.join(', ')}. ` +
+        `Valid deferred tools are: ${valid || '(none)'}.`,
+    );
+  }
+  for (const n of requested) activatedTools.add(n);
+  return { loaded: requested };
+}
+
+/**
+ * Build the loadTools AI-SDK tool bound to THIS turn's mutable state: the
+ * `activatedTools` set (grown by execute, read by prepareAgentStep next step)
+ * and the `validDeferredNames` set (every non-core tool in this turn's toolset,
+ * incl. external MCP). Created per streamText call — never module-global.
+ */
+export function makeLoadToolsTool(
+  activatedTools: Set<string>,
+  validDeferredNames: ReadonlySet<string>,
+): Tool {
+  return tool({
+    description: LOAD_TOOLS_DESCRIPTION,
+    inputSchema: z.object({
+      names: z
+        .array(z.string())
+        .describe(
+          'EXACT deferred tool names from the <tool_catalog> to activate for ' +
+            'your next step.',
+        ),
+    }),
+    execute: async ({ names }) =>
+      applyLoadTools(names, activatedTools, validDeferredNames),
+  });
+}

apps/server/src/integrations/environment/environment.service.ts

@@ -261,6 +261,21 @@ export class EnvironmentService {
     return disable === 'true';
   }
 
+  /**
+   * Deferred tool loading for the in-app AI chat (#332). When enabled, the agent
+   * sees a compact <tool_catalog> and only CORE tools + the loadTools meta-tool
+   * are active each step; deferred tools (the fat/rare ones + all external MCP
+   * tools) load on demand. Defaults to ENABLED — the issue treats deferred
+   * loading as the new behavior; set AI_CHAT_DEFERRED_TOOLS=false to restore the
+   * old "all tools always active" behavior.
+   */
+  isAiChatDeferredToolsEnabled(): boolean {
+    const enabled = this.configService
+      .get<string>('AI_CHAT_DEFERRED_TOOLS', 'true')
+      .toLowerCase();
+    return enabled === 'true';
+  }
+
   getPostHogHost(): string {
     return this.configService.get<string>('POSTHOG_HOST');
   }

apps/server/test/integration/ai-chat-stream.int-spec.ts

@@ -1,5 +1,7 @@
 import * as http from 'node:http';
 import { Kysely } from 'kysely';
+import { tool } from 'ai';
+import { z } from 'zod';
 import { MockLanguageModelV3, convertArrayToReadableStream } from 'ai/test';
 import { AiChatRepo } from '@docmost/db/repos/ai-chat/ai-chat.repo';
 import { AiChatMessageRepo } from '@docmost/db/repos/ai-chat/ai-chat-message.repo';
@@ -146,6 +148,9 @@ describe('AiChatService.stream [integration]', () => {
       {} as any, // aiAgentRoleRepo (role is pre-resolved + passed in)
       {} as any, // pageRepo (only used when body.openPage is set)
       {} as any, // pageAccess (idem)
+      // environment (#332): keep deferred tool loading OFF for this lifecycle
+      // harness so the toolset/behavior is exactly as before.
+      { isAiChatDeferredToolsEnabled: () => false } as any,
     );
   }
 
@@ -315,4 +320,174 @@ describe('AiChatService.stream [integration]', () => {
       true,
     );
   });
+
+  /**
+   * #332 deferred tool loading, the ON path. The riskiest property is that the
+   * per-turn `activatedTools` Set is created FRESH inside each stream() call, so a
+   * tool a previous turn activated via loadTools is NOT still active when the next
+   * turn starts — the new turn begins "cold" (CORE + loadTools only). The unit
+   * tests only exercise pure prepareAgentStep with hand-fed Sets; this pins the
+   * real wiring end-to-end (loadTools.execute -> activatedTools -> prepareStep ->
+   * per-step activeTools) against the real streamText loop, and proves there is no
+   * cross-turn leak. We drive a MockLanguageModelV3 whose step 1 calls
+   * loadTools(['createPage']) and assert, via the model's recorded per-step
+   * CallOptions.tools (the AI SDK filters the provider tool list by activeTools),
+   * that the deferred tool becomes active on the SAME turn's next step but NOT on a
+   * fresh turn's first step.
+   */
+  describe('deferred tool loading ON — per-turn activation, no leak (#332)', () => {
+    // A stub deferred (non-core) tool the agent can activate. Its execute is never
+    // called — the model only needs to SEE it become active — but it must be a
+    // valid AI-SDK tool so the SDK includes it in a step's tool list once active.
+    const createPageStub = tool({
+      description: 'create a new page',
+      inputSchema: z.object({ title: z.string() }),
+      execute: async () => ({ id: 'p-stub' }),
+    });
+
+    // A CORE tool in the toolset, so a cold step shows CORE tools ARE active while
+    // the deferred createPage is not. `searchPages` is in CORE_TOOL_SET.
+    const searchPagesStub = tool({
+      description: 'search the wiki',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async () => [],
+    });
+
+    // Same lifecycle harness as buildService() above, but with deferred loading ON
+    // and a toolset that exposes exactly one deferred tool (createPage) so it is
+    // catalogued + loadable-by-name. Kept separate so the OFF scenarios are
+    // untouched.
+    function buildDeferredService(): AiChatService {
+      return new AiChatService(
+        { getChatModel: async () => null } as any,
+        aiChatRepo,
+        msgRepo,
+        {} as any,
+        { resolve: async () => null } as any,
+        {
+          forUser: async () => ({
+            searchPages: searchPagesStub,
+            createPage: createPageStub,
+          }),
+          getInAppDeferredCatalog: async () => [
+            { name: 'createPage', catalogLine: 'createPage — create a new page.' },
+          ],
+        } as any,
+        mcpClients as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        // #332: deferred tool loading ON — the property under test.
+        { isAiChatDeferredToolsEnabled: () => true } as any,
+      );
+    }
+
+    // Drive ONE stream() turn against `model` and wait for the assistant row to
+    // settle (mirrors runStream, but builds the deferred-ON service).
+    async function runDeferredTurn(
+      model: MockLanguageModelV3,
+      chatId: string,
+      body: any,
+    ): Promise<void> {
+      closeCalls = 0;
+      const service = buildDeferredService();
+      const { res, cleanup } = await makeRealResponse();
+      try {
+        await service.stream({
+          user: { id: userId, workspaceId } as any,
+          workspace: { id: workspaceId, name: 'WS' } as any,
+          sessionId: 'sess-1',
+          body,
+          res: { raw: res } as any,
+          signal: new AbortController().signal,
+          model: model as any,
+          role: null,
+        } as any);
+        await waitFor(async () => {
+          const rows = await msgRepo.findAllByChat(chatId, workspaceId);
+          return rows.some(
+            (r) =>
+              r.role === 'assistant' &&
+              ['completed', 'error', 'aborted'].includes(r.status as string),
+          );
+        });
+        await waitFor(() => closeCalls > 0, { timeoutMs: 5_000 });
+      } finally {
+        await cleanup();
+      }
+    }
+
+    // Tool names the provider actually received for a recorded step (activeTools
+    // filters this list, so it reflects what was active that step).
+    const toolNames = (call: any): string[] =>
+      ((call?.tools ?? []) as any[]).map((t) => t?.name).filter(Boolean);
+
+    // A model that, on step 1, calls loadTools(['createPage']); on step 2, answers.
+    function loadThenAnswerModel(): MockLanguageModelV3 {
+      let step = 0;
+      return new MockLanguageModelV3({
+        doStream: async () => {
+          const n = step++;
+          if (n === 0) {
+            return {
+              stream: convertArrayToReadableStream([
+                { type: 'stream-start', warnings: [] },
+                {
+                  type: 'tool-call',
+                  toolCallId: 'lt1',
+                  toolName: 'loadTools',
+                  input: JSON.stringify({ names: ['createPage'] }),
+                },
+                {
+                  type: 'finish',
+                  finishReason: 'tool-calls',
+                  usage: { inputTokens: 5, outputTokens: 3, totalTokens: 8 },
+                },
+              ] as any),
+            };
+          }
+          return { stream: successStream() };
+        },
+      } as any);
+    }
+
+    it('activates a deferred tool for the SAME turn, and a NEW turn starts cold (no leak)', async () => {
+      const chatId = (await createChat(db, { workspaceId, creatorId: userId })).id;
+
+      // --- Turn 1: loadTools(createPage) on step 1, then answer on step 2. ---
+      const model1 = loadThenAnswerModel();
+      await runDeferredTurn(model1, chatId, {
+        chatId,
+        messages: [userUiMessage('Make me a page')],
+      });
+
+      // The turn ran at least two steps (the load round-trip + the answer).
+      expect(model1.doStreamCalls.length).toBeGreaterThanOrEqual(2);
+      const step1Tools = toolNames(model1.doStreamCalls[0]);
+      const step2Tools = toolNames(model1.doStreamCalls[1]);
+
+      // Step 1 starts cold: CORE tools + the loadTools meta-tool are active, but
+      // the deferred createPage is NOT yet.
+      expect(step1Tools).toContain('loadTools');
+      expect(step1Tools).toContain('searchPages'); // a CORE tool, always active
+      expect(step1Tools).not.toContain('createPage');
+      // Step 2 of the SAME turn sees the just-activated deferred tool.
+      expect(step2Tools).toContain('createPage');
+
+      // --- Turn 2 on the SAME chat: must start cold again. ---
+      const model2 = new MockLanguageModelV3({
+        doStream: async () => ({ stream: successStream() }),
+      } as any);
+      await runDeferredTurn(model2, chatId, {
+        chatId,
+        messages: [userUiMessage('And another thing')],
+      });
+
+      const nextTurnFirstStep = toolNames(model2.doStreamCalls[0]);
+      expect(nextTurnFirstStep).toContain('loadTools');
+      // The activated set is per-turn: the prior turn's createPage did NOT leak,
+      // so the fresh turn's first step sees it deferred again.
+      expect(nextTurnFirstStep).not.toContain('createPage');
+    });
+  });
 });

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",

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 {

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";

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

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";

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

@@ -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);
-}

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.

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

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

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);
 

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

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

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

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.

packages/git-sync/test/roundtrip-corpus.test.ts

@@ -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);
-    },
-  );
-});

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);
 

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 {

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
@@ -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' }] },
       ],
     };

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.
 //

packages/mcp/build/_vendored_editor_ext/copy.js

@@ -1,6 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.copy = copy;
-function copy(value) {
-    return JSON.parse(JSON.stringify(value));
-}

packages/mcp/build/_vendored_editor_ext/getFromPath.js

@@ -1,18 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFromPath = getFromPath;
-/**
- * get target value from json-pointer (e.g. /content/0/content)
- * @param  {AnyObject} obj  object to resolve path into
- * @param  {string}    path json-pointer
- * @return {any} target value
- */
-function getFromPath(obj, path) {
-    const pathParts = path.split("/");
-    pathParts.shift(); // remove root-entry
-    while (pathParts.length) {
-        const property = pathParts.shift();
-        obj = obj[property];
-    }
-    return obj;
-}

packages/mcp/build/_vendored_editor_ext/getReplaceStep.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getReplaceStep = getReplaceStep;
-const transform_1 = require("@tiptap/pm/transform");
-function getReplaceStep(fromDoc, toDoc) {
-    let start = toDoc.content.findDiffStart(fromDoc.content);
-    if (start === null) {
-        return false;
-    }
-    // @ts-ignore property access to content
-    let { a: endA, b: endB } = toDoc.content.findDiffEnd(fromDoc.content);
-    const overlap = start - Math.min(endA, endB);
-    if (overlap > 0) {
-        // If there is an overlap, there is some freedom of choice in how to calculate the
-        // start/end boundary. for an inserted/removed slice. We choose the extreme with
-        // the lowest depth value.
-        if (fromDoc.resolve(start - overlap).depth <
-            toDoc.resolve(endA + overlap).depth) {
-            start -= overlap;
-        }
-        else {
-            endA += overlap;
-            endB += overlap;
-        }
-    }
-    return new transform_1.ReplaceStep(start, endB, toDoc.slice(start, endA));
-}

packages/mcp/build/_vendored_editor_ext/index.js

@@ -1,8 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecreateTransform = exports.recreateTransform = void 0;
-// https://gitlab.com/mpapp-public/prosemirror-recreate-steps - MIT
-// https://github.com/sueddeutsche/prosemirror-recreate-transform - MIT
-var recreateTransform_1 = require("./recreateTransform");
-Object.defineProperty(exports, "recreateTransform", { enumerable: true, get: function () { return recreateTransform_1.recreateTransform; } });
-Object.defineProperty(exports, "RecreateTransform", { enumerable: true, get: function () { return recreateTransform_1.RecreateTransform; } });

packages/mcp/build/_vendored_editor_ext/package.json

@@ -1 +0,0 @@
-{"type":"commonjs"}

packages/mcp/build/_vendored_editor_ext/recreateTransform.js

@@ -1,242 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecreateTransform = void 0;
-exports.recreateTransform = recreateTransform;
-const transform_1 = require("@tiptap/pm/transform");
-const rfc6902_1 = require("rfc6902");
-const diff_1 = require("diff");
-const getReplaceStep_1 = require("./getReplaceStep");
-const simplifyTransform_1 = require("./simplifyTransform");
-const removeMarks_1 = require("./removeMarks");
-const getFromPath_1 = require("./getFromPath");
-const copy_1 = require("./copy");
-class RecreateTransform {
-    constructor(fromDoc, toDoc, options = {}) {
-        const o = {
-            complexSteps: true,
-            wordDiffs: false,
-            simplifyDiff: true,
-            ...options,
-        };
-        this.fromDoc = fromDoc;
-        this.toDoc = toDoc;
-        this.complexSteps = o.complexSteps; // Whether to return steps other than ReplaceSteps
-        this.wordDiffs = o.wordDiffs; // Whether to make text diffs cover entire words
-        this.simplifyDiff = o.simplifyDiff;
-        this.schema = fromDoc.type.schema;
-        this.tr = new transform_1.Transform(fromDoc);
-    }
-    init() {
-        if (this.complexSteps) {
-            // For First steps: we create versions of the documents without marks as
-            // these will only confuse the diffing mechanism and marks won't cause
-            // any mapping changes anyway.
-            this.currentJSON = (0, removeMarks_1.removeMarks)(this.fromDoc).toJSON();
-            this.finalJSON = (0, removeMarks_1.removeMarks)(this.toDoc).toJSON();
-            this.ops = (0, rfc6902_1.createPatch)(this.currentJSON, this.finalJSON);
-            this.recreateChangeContentSteps();
-            this.recreateChangeMarkSteps();
-        }
-        else {
-            // We don't differentiate between mark changes and other changes.
-            this.currentJSON = this.fromDoc.toJSON();
-            this.finalJSON = this.toDoc.toJSON();
-            this.ops = (0, rfc6902_1.createPatch)(this.currentJSON, this.finalJSON);
-            this.recreateChangeContentSteps();
-        }
-        if (this.simplifyDiff) {
-            this.tr = (0, simplifyTransform_1.simplifyTransform)(this.tr) || this.tr;
-        }
-        return this.tr;
-    }
-    /** convert json-diff to prosemirror steps */
-    recreateChangeContentSteps() {
-        // First step: find content changing steps.
-        let ops = [];
-        while (this.ops.length) {
-            // get next
-            let op = this.ops.shift();
-            ops.push(op);
-            let toDoc;
-            const afterStepJSON = (0, copy_1.copy)(this.currentJSON); // working document receiving patches
-            const pathParts = op.path.split("/");
-            // collect operations until we receive a valid document:
-            // apply ops-patches until a valid prosemirror document is retrieved,
-            // then try to create a transformation step or retry with next operation
-            while (toDoc == null) {
-                (0, rfc6902_1.applyPatch)(afterStepJSON, [op]);
-                try {
-                    toDoc = this.schema.nodeFromJSON(afterStepJSON);
-                    toDoc.check();
-                }
-                catch (error) {
-                    toDoc = null;
-                    if (this.ops.length > 0) {
-                        op = this.ops.shift();
-                        ops.push(op);
-                    }
-                    else {
-                        throw new Error(`No valid diff possible applying ${op.path}`);
-                    }
-                }
-            }
-            // apply operation (ignoring afterStepJSON)
-            if (this.complexSteps &&
-                ops.length === 1 &&
-                (pathParts.includes("attrs") || pathParts.includes("type"))) {
-                // Node markup is changing
-                this.addSetNodeMarkup(); // a lost update is ignored
-                ops = [];
-                // console.log("%cop", logStyle, "- update node", ops);
-            }
-            else if (ops.length === 1 &&
-                op.op === "replace" &&
-                pathParts[pathParts.length - 1] === "text") {
-                // Text is being replaced, we apply text diffing to find the smallest possible diffs.
-                this.addReplaceTextSteps(op, afterStepJSON);
-                ops = [];
-                // console.log("%cop", logStyle, "- replace", ops);
-            }
-            else if (this.addReplaceStep(toDoc, afterStepJSON)) {
-                // operations have been applied
-                ops = [];
-                // console.log("%cop", logStyle, "- other", ops);
-            }
-        }
-    }
-    /** update node with attrs and marks, may also change type */
-    addSetNodeMarkup() {
-        // first diff in document is supposed to be a node-change (in type and/or attributes)
-        // thus simply find the first change and apply a node change step, then recalculate the diff
-        // after updating the document
-        const fromDoc = this.schema.nodeFromJSON(this.currentJSON);
-        const toDoc = this.schema.nodeFromJSON(this.finalJSON);
-        const start = toDoc.content.findDiffStart(fromDoc.content);
-        // @note start is the same (first) position for current and target document
-        const fromNode = fromDoc.nodeAt(start);
-        const toNode = toDoc.nodeAt(start);
-        if (start != null) {
-            // @note this completly updates all attributes in one step, by completely replacing node
-            const nodeType = fromNode.type === toNode.type ? null : toNode.type;
-            try {
-                this.tr.setNodeMarkup(start, nodeType, toNode.attrs, toNode.marks);
-            }
-            catch (e) {
-                // if nodetypes differ, the updated node-type and contents might not be compatible
-                // with schema and requires a replace
-                if (nodeType && e.message.includes("Invalid content")) {
-                    // @todo add test-case for this scenario
-                    this.tr.replaceWith(start, start + fromNode.nodeSize, toNode);
-                }
-                else {
-                    throw e;
-                }
-            }
-            this.currentJSON = (0, removeMarks_1.removeMarks)(this.tr.doc).toJSON();
-            // setting the node markup may have invalidated the following ops, so we calculate them again.
-            this.ops = (0, rfc6902_1.createPatch)(this.currentJSON, this.finalJSON);
-            return true;
-        }
-        return false;
-    }
-    recreateChangeMarkSteps() {
-        // Now the documents should be the same, except their marks, so everything should map 1:1.
-        // Second step: Iterate through the toDoc and make sure all marks are the same in tr.doc
-        this.toDoc.descendants((tNode, tPos) => {
-            if (!tNode.isInline) {
-                return true;
-            }
-            this.tr.doc.nodesBetween(tPos, tPos + tNode.nodeSize, (fNode, fPos) => {
-                if (!fNode.isInline) {
-                    return true;
-                }
-                const from = Math.max(tPos, fPos);
-                const to = Math.min(tPos + tNode.nodeSize, fPos + fNode.nodeSize);
-                fNode.marks.forEach((nodeMark) => {
-                    if (!nodeMark.isInSet(tNode.marks)) {
-                        this.tr.removeMark(from, to, nodeMark);
-                    }
-                });
-                tNode.marks.forEach((nodeMark) => {
-                    if (!nodeMark.isInSet(fNode.marks)) {
-                        this.tr.addMark(from, to, nodeMark);
-                    }
-                });
-            });
-        });
-    }
-    /**
-     * retrieve and possibly apply replace-step based from doc changes
-     * From http://prosemirror.net/examples/footnote/
-     */
-    addReplaceStep(toDoc, afterStepJSON) {
-        const fromDoc = this.schema.nodeFromJSON(this.currentJSON);
-        const step = (0, getReplaceStep_1.getReplaceStep)(fromDoc, toDoc);
-        if (!step) {
-            return false;
-        }
-        else if (!this.tr.maybeStep(step).failed) {
-            this.currentJSON = afterStepJSON;
-            return true; // @change previously null
-        }
-        throw new Error("No valid step found.");
-    }
-    /** retrieve and possibly apply text replace-steps based from doc changes */
-    addReplaceTextSteps(op, afterStepJSON) {
-        // We find the position number of the first character in the string
-        const op1 = { ...op, value: "xx" };
-        const op2 = { ...op, value: "yy" };
-        const afterOP1JSON = (0, copy_1.copy)(this.currentJSON);
-        const afterOP2JSON = (0, copy_1.copy)(this.currentJSON);
-        (0, rfc6902_1.applyPatch)(afterOP1JSON, [op1]);
-        (0, rfc6902_1.applyPatch)(afterOP2JSON, [op2]);
-        const op1Doc = this.schema.nodeFromJSON(afterOP1JSON);
-        const op2Doc = this.schema.nodeFromJSON(afterOP2JSON);
-        // get text diffs
-        const finalText = op.value;
-        const currentText = (0, getFromPath_1.getFromPath)(this.currentJSON, op.path);
-        const textDiffs = this.wordDiffs
-            ? (0, diff_1.diffWordsWithSpace)(currentText, finalText)
-            : (0, diff_1.diffChars)(currentText, finalText);
-        let offset = op1Doc.content.findDiffStart(op2Doc.content);
-        const marks = op1Doc.resolve(offset + 1).marks();
-        while (textDiffs.length) {
-            const diff = textDiffs.shift();
-            if (diff.added) {
-                const textNode = this.schema
-                    .nodeFromJSON({ type: "text", text: diff.value })
-                    .mark(marks);
-                if (textDiffs.length && textDiffs[0].removed) {
-                    const nextDiff = textDiffs.shift();
-                    this.tr.replaceWith(offset, offset + nextDiff.value.length, textNode);
-                }
-                else {
-                    this.tr.insert(offset, textNode);
-                }
-                offset += diff.value.length;
-            }
-            else if (diff.removed) {
-                if (textDiffs.length && textDiffs[0].added) {
-                    const nextDiff = textDiffs.shift();
-                    const textNode = this.schema
-                        .nodeFromJSON({ type: "text", text: nextDiff.value })
-                        .mark(marks);
-                    this.tr.replaceWith(offset, offset + diff.value.length, textNode);
-                    offset += nextDiff.value.length;
-                }
-                else {
-                    this.tr.delete(offset, offset + diff.value.length);
-                }
-            }
-            else {
-                offset += diff.value.length;
-            }
-        }
-        this.currentJSON = afterStepJSON;
-    }
-}
-exports.RecreateTransform = RecreateTransform;
-function recreateTransform(fromDoc, toDoc, options = {}) {
-    const recreator = new RecreateTransform(fromDoc, toDoc, options);
-    return recreator.init();
-}

packages/mcp/build/_vendored_editor_ext/recreateTransform.test.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const vitest_1 = require("vitest");
-const schema_basic_1 = require("@tiptap/pm/schema-basic");
-const transform_1 = require("@tiptap/pm/transform");
-const recreateTransform_1 = require("./recreateTransform");
-/**
- * recreateTransform diffs two documents and produces ProseMirror steps that turn
- * `fromDoc` into `toDoc`. It is the backbone of collaborative/version diffing, so
- * THE invariant that matters is: replaying the produced steps on `fromDoc` must
- * reproduce `toDoc` exactly. Every test below re-applies the steps onto a fresh
- * Transform seeded from `fromDoc` (not just trusting `tr.doc`) and asserts node
- * equality with `.eq()`. If a regression makes any step wrong, the round-trip
- * breaks and the test fails.
- */
-// Real ProseMirror schema (the standard basic schema) with paragraph/heading +
-// strong/em marks — the same primitives the editor diffs in production.
-const doc = (...c) => schema_basic_1.schema.node("doc", null, c);
-const p = (...c) => schema_basic_1.schema.node("paragraph", null, c.length ? c : undefined);
-const h = (level, ...c) => schema_basic_1.schema.node("heading", { level }, c);
-const t = (text, ...marks) => schema_basic_1.schema.text(text, marks.length ? marks : undefined);
-const strong = schema_basic_1.schema.marks.strong.create();
-const em = schema_basic_1.schema.marks.em.create();
-// Replay the diff's steps onto a fresh Transform built from `fromDoc`. This is
-// the faithful "apply(diff) == target" check — it exercises the actual Step
-// objects rather than the transform's internal accumulated doc.
-function applyDiff(fromDoc, toDoc, options) {
-    const tr = (0, recreateTransform_1.recreateTransform)(fromDoc, toDoc, options);
-    const replay = new transform_1.Transform(fromDoc);
-    tr.steps.forEach((s) => {
-        const result = replay.maybeStep(s);
-        if (result.failed)
-            throw new Error(`step failed: ${result.failed}`);
-    });
-    return replay.doc;
-}
-(0, vitest_1.describe)("recreateTransform round-trip (apply(diff) == target)", () => {
-    (0, vitest_1.it)("reconstructs the target on plain text insertion", () => {
-        // Inserting " world" must yield exactly the target paragraph.
-        const from = doc(p(t("hello")));
-        const to = doc(p(t("hello world")));
-        (0, vitest_1.expect)(applyDiff(from, to).eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("reconstructs the target on text deletion", () => {
-        // Deleting a trailing word is the inverse of insertion and must round-trip.
-        const from = doc(p(t("hello world")));
-        const to = doc(p(t("hello")));
-        (0, vitest_1.expect)(applyDiff(from, to).eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("reconstructs the target when a word is replaced mid-string", () => {
-        // A char-level replace in the middle must not corrupt the surrounding text.
-        const from = doc(p(t("the quick brown fox")));
-        const to = doc(p(t("the slow brown fox")));
-        (0, vitest_1.expect)(applyDiff(from, to).eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("reconstructs the target when a mark is added (complexSteps path)", () => {
-        // Mark-only changes are diffed in a separate pass; the bolded run must match.
-        const from = doc(p(t("hello")));
-        const to = doc(p(t("hello", strong)));
-        const out = applyDiff(from, to);
-        (0, vitest_1.expect)(out.eq(to)).toBe(true);
-        // Sanity: the produced doc actually carries the strong mark.
-        (0, vitest_1.expect)(out.firstChild.firstChild.marks.length).toBe(1);
-    });
-    (0, vitest_1.it)("reconstructs the target when a mark is removed", () => {
-        // Removing the only mark must leave the same text with no marks.
-        const from = doc(p(t("hello", strong)));
-        const to = doc(p(t("hello")));
-        const out = applyDiff(from, to);
-        (0, vitest_1.expect)(out.eq(to)).toBe(true);
-        (0, vitest_1.expect)(out.firstChild.firstChild.marks.length).toBe(0);
-    });
-    (0, vitest_1.it)("reconstructs the target on a paragraph split into two blocks", () => {
-        // Structural change (one block -> two) must replay as valid replace steps.
-        const from = doc(p(t("hello world")));
-        const to = doc(p(t("hello")), p(t("world")));
-        const out = applyDiff(from, to);
-        (0, vitest_1.expect)(out.eq(to)).toBe(true);
-        (0, vitest_1.expect)(out.childCount).toBe(2);
-    });
-    (0, vitest_1.it)("reconstructs the target on a node-type change (paragraph -> heading)", () => {
-        // Type/attrs changes drive the setNodeMarkup branch; the node must become a
-        // heading while keeping its text.
-        const from = doc(p(t("hello")));
-        const to = doc(h(1, t("hello")));
-        const out = applyDiff(from, to);
-        (0, vitest_1.expect)(out.eq(to)).toBe(true);
-        (0, vitest_1.expect)(out.firstChild.type.name).toBe("heading");
-    });
-    (0, vitest_1.it)("reconstructs a combined structural + mark change", () => {
-        // Several diff kinds at once (new block + italic run) still round-trips.
-        const from = doc(p(t("alpha")));
-        const to = doc(p(t("alpha")), p(t("beta", em)));
-        const out = applyDiff(from, to);
-        (0, vitest_1.expect)(out.eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("produces an empty step list for identical documents", () => {
-        // No diff => no work; spurious steps would mean wasted/incorrect history.
-        const from = doc(p(t("same")));
-        const to = doc(p(t("same")));
-        const tr = (0, recreateTransform_1.recreateTransform)(from, to);
-        (0, vitest_1.expect)(tr.steps.length).toBe(0);
-        (0, vitest_1.expect)(tr.doc.eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("round-trips with complexSteps:false (marks diffed as replaces)", () => {
-        // With complexSteps off, mark changes are folded into replace steps rather
-        // than dedicated mark steps — the result must still equal the target.
-        const from = doc(p(t("hello")));
-        const to = doc(p(t("hello", strong)));
-        (0, vitest_1.expect)(applyDiff(from, to, { complexSteps: false }).eq(to)).toBe(true);
-    });
-    (0, vitest_1.it)("round-trips with wordDiffs:true (whole-word text diffing)", () => {
-        // wordDiffs changes the granularity of the text diff, not the outcome.
-        const from = doc(p(t("the quick brown fox")));
-        const to = doc(p(t("the quick red fox")));
-        (0, vitest_1.expect)(applyDiff(from, to, { wordDiffs: true }).eq(to)).toBe(true);
-    });
-});

packages/mcp/build/_vendored_editor_ext/removeMarks.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeMarks = removeMarks;
-const transform_1 = require("@tiptap/pm/transform");
-function removeMarks(doc) {
-    const tr = new transform_1.Transform(doc);
-    tr.removeMark(0, doc.nodeSize - 2);
-    return tr.doc;
-}

packages/mcp/build/_vendored_editor_ext/simplifyTransform.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.simplifyTransform = simplifyTransform;
-const transform_1 = require("@tiptap/pm/transform");
-const getReplaceStep_1 = require("./getReplaceStep");
-// join adjacent ReplaceSteps
-function simplifyTransform(tr) {
-    if (!tr.steps.length) {
-        return undefined;
-    }
-    const newTr = new transform_1.Transform(tr.docs[0]);
-    const oldSteps = tr.steps.slice();
-    while (oldSteps.length) {
-        let step = oldSteps.shift();
-        while (oldSteps.length && step.merge(oldSteps[0])) {
-            const addedStep = oldSteps.shift();
-            if (step instanceof transform_1.ReplaceStep && addedStep instanceof transform_1.ReplaceStep) {
-                step = (0, getReplaceStep_1.getReplaceStep)(newTr.doc, addedStep.apply(step.apply(newTr.doc).doc).doc);
-            }
-            else {
-                step = step.merge(addedStep);
-            }
-        }
-        newTr.step(step);
-    }
-    return newTr;
-}

packages/mcp/build/_vendored_editor_ext/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

packages/mcp/build/http.js

@@ -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 };
-}

packages/mcp/build/index.js

@@ -1,810 +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). Find every occurrence of a string/regex ON a page (and where each is) -> search_in_page, NOT block-by-block get_node — it returns each hit's node ref + block index + context for a targeted comment. 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: search_in_page
-    registerShared(SHARED_TOOL_SPECS.searchInPage, async ({ pageId, query, regex, caseSensitive, limit }) => {
-        const result = await docmostClient.searchInPage(pageId, query, {
-            regex,
-            caseSensitive,
-            limit,
-        });
-        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;
-}

packages/mcp/build/lib/auth-utils.js

@@ -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;
-    }
-}

packages/mcp/build/lib/collaboration.js

@@ -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);
-}

packages/mcp/build/lib/comment-anchor.js

@@ -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);
-}

packages/mcp/build/lib/diff.js

@@ -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)",
-        };
-    }
-}

packages/mcp/build/lib/filters.js

@@ -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,
-    };
-}

packages/mcp/build/lib/footnote-analyze.js

@@ -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 } : {};
-}

packages/mcp/build/lib/footnote-authoring.js

@@ -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));
-}

packages/mcp/build/lib/footnote-canonicalize.js

@@ -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);
-}

packages/mcp/build/lib/footnote-lex.js

@@ -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]);
-}

packages/mcp/build/lib/internal-file-urls.js

@@ -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;
-}

packages/mcp/build/lib/json-edit.js

@@ -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 };
-}

packages/mcp/build/lib/markdown-converter.js

@@ -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();
-}

packages/mcp/build/lib/markdown-document.js

@@ -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 };
-}

packages/mcp/build/lib/node-ops.js

@@ -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 };
-}

packages/mcp/build/lib/page-lock.js

@@ -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;
-}

packages/mcp/build/lib/page-search.js

@@ -1,186 +0,0 @@
-/**
- * Pure, network-free in-page search over a ProseMirror/TipTap document tree.
- *
- * `searchInDoc(doc, query, opts)` finds every occurrence of a literal substring
- * (default) or a regular expression across the page's TEXT CONTAINERS and
- * reports WHERE each match is — the container's ref (for get_node/patch_node;
- * see the SearchMatch.nodeId note for the `#<index>` caveat), the top-level
- * block index, and a short context window around the hit. It never touches the
- * network, the DB, or the schema mirror; like `comment-anchor.ts` it is
- * isolated-testable.
- *
- * REGEX ENGINE: with `regex:true` the pattern is compiled with RE2 (Google's
- * linear-time engine), NOT the JS `RegExp`. RE2 has no backtracking, so a
- * catastrophic pattern (e.g. `(a+)+$`) can never wedge the shared event loop —
- * it runs in linear time. The trade-off is that RE2 does not support the
- * backtracking-only features lookaround (`(?=…)`, `(?<=…)`) and backreferences
- * (`\1`); such a pattern is rejected up front with a clear tool error (see
- * searchInDoc) rather than being run, which is the desired behaviour — a clear
- * error the agent can fix beats a server hang.
- *
- * WHY plain text (not markdown): each container's inline text is glued into ONE
- * string via `blockPlainText`, so a match survives inline-mark boundaries
- * (bold/italic/link splits that fracture a run like "т.е." into several text
- * nodes) and comment-anchor spans never clutter the haystack.
- *
- * The SEARCH UNIT is a text container: a node whose direct children include
- * text nodes (a paragraph/heading, or the paragraph inside a table cell / list
- * item). ProseMirror keeps block vs. inline content exclusive, so a container
- * never nests another container — the walk reaches each cell/item's own text and
- * the context window is naturally scoped to that specific cell/item, not the
- * whole top-level block's glued text.
- */
-import RE2 from "re2";
-import { blockPlainText } from "./node-ops.js";
-/** True if `value` is a non-null plain object (and not an array). */
-function isObject(value) {
-    return value != null && typeof value === "object" && !Array.isArray(value);
-}
-/**
- * A text container is a node with a `content` array holding at least one text
- * node (a child with a string `text`). These are the paragraphs/headings whose
- * glued inline text we search.
- */
-function isTextContainer(node) {
-    return (isObject(node) &&
-        Array.isArray(node.content) &&
-        node.content.some((c) => isObject(c) && typeof c.text === "string"));
-}
-// Result-size defaults/ceiling.
-const DEFAULT_LIMIT = 50;
-const MAX_LIMIT = 200;
-// Context window on each side of a match.
-const CONTEXT = 40;
-// Cheap sanity cap on the query/pattern length. ReDoS is handled structurally
-// by the RE2 engine (linear-time, no backtracking — see the module doc), so we
-// no longer truncate the per-container text: RE2 scans it in linear time and a
-// cap could silently drop real matches past it. This just rejects an absurdly
-// long pattern early with a clear error.
-const MAX_PATTERN_LENGTH = 1000;
-/** Clamp the requested limit into [1, MAX_LIMIT], defaulting when absent. */
-function resolveLimit(limit) {
-    const n = typeof limit === "number" && Number.isFinite(limit) ? limit : DEFAULT_LIMIT;
-    return Math.min(MAX_LIMIT, Math.max(1, Math.floor(n)));
-}
-/**
- * Yield the [start, length] of every occurrence of the engine in `text`, in
- * order. A literal engine uses indexOf (case-folded when requested); a regex
- * engine uses a global RE2 regex (RE2 extends `RegExp`, so `.exec` advances
- * `lastIndex` exactly like the native engine). Zero-length regex matches (e.g.
- * `\b`, `a*`) are SKIPPED and lastIndex is advanced, so a pattern that can match
- * the empty string cannot flood the results or spin forever.
- */
-function* eachMatch(text, query, re, caseSensitive) {
-    if (re) {
-        re.lastIndex = 0;
-        let m;
-        while ((m = re.exec(text)) != null) {
-            const len = m[0].length;
-            if (len === 0) {
-                // Empty match: advance past this position and do not record it.
-                re.lastIndex = m.index + 1;
-                continue;
-            }
-            yield [m.index, len];
-        }
-        return;
-    }
-    // Literal engine. For case-insensitive search, fold BOTH sides only to locate
-    // the indices; the reported match/context are always sliced from the original
-    // text so the caller gets the real casing (needed to build a unique selection).
-    const haystack = caseSensitive ? text : text.toLowerCase();
-    const needle = caseSensitive ? query : query.toLowerCase();
-    const len = needle.length;
-    let from = 0;
-    for (;;) {
-        const idx = haystack.indexOf(needle, from);
-        if (idx === -1)
-            return;
-        yield [idx, len];
-        from = idx + len;
-    }
-}
-/**
- * Search a ProseMirror document for `query` and return `{ total, truncated,
- * matches }`. `total` counts EVERY occurrence (even beyond the limit) and
- * `truncated` flags when the returned list was capped — nothing is silently
- * dropped.
- *
- * Throws a clear, model-actionable error (never a generic failure) on: an
- * empty/whitespace-only query, an over-long pattern, or — with `regex:true` — a
- * pattern RE2 rejects (invalid syntax, or the unsupported lookaround/
- * backreference features), so the agent can fix its input.
- */
-export function searchInDoc(doc, query, opts = {}) {
-    // --- edge-case guards (fail loudly so the agent can correct the call) ---
-    if (typeof query !== "string" || query.trim().length === 0) {
-        throw new Error("search_in_page: query is empty — pass the text (or regex) to look for.");
-    }
-    if (query.length > MAX_PATTERN_LENGTH) {
-        throw new Error(`search_in_page: query is too long (${query.length} chars; max ${MAX_PATTERN_LENGTH}). Shorten the search text/pattern.`);
-    }
-    const caseSensitive = opts.caseSensitive === true;
-    const limit = resolveLimit(opts.limit);
-    // Compile the pattern up front with RE2 (linear-time, ReDoS-safe) so a bad
-    // pattern is a clean tool error rather than a failure deep in the traversal —
-    // and so a catastrophic-backtracking pattern can never wedge the event loop.
-    // RE2 throws both on syntactically invalid input AND on backtracking-only
-    // features it does not implement (lookaround, backreferences); both map to the
-    // same actionable error so the agent rewrites the pattern.
-    let re = null;
-    if (opts.regex === true) {
-        try {
-            re = new RE2(query, caseSensitive ? "g" : "gi");
-        }
-        catch (e) {
-            throw new Error(`search_in_page: invalid or unsupported regular expression: ${e instanceof Error ? e.message : String(e)} — RE2 does not support lookaround ((?=…)/(?<=…)) or backreferences (\\1); rewrite the pattern without them.`);
-        }
-    }
-    const matches = [];
-    let total = 0;
-    const topLevel = isObject(doc) && Array.isArray(doc.content) ? doc.content : [];
-    // Descend a top-level block, collecting matches from every text container
-    // within it. blockIndex/topRef stay pinned to the enclosing top-level block.
-    const descend = (node, blockIndex, topRef) => {
-        if (!isObject(node))
-            return;
-        if (isTextContainer(node)) {
-            // Glue this container's inline text into one string (mark-safe). No length
-            // cap: RE2 scans it in linear time (no ReDoS) and the whole document is
-            // already in memory, so truncating would only risk dropping real matches
-            // in a very long container.
-            const text = blockPlainText(node);
-            // The container's own id addresses it verbatim in get_node/patch_node; a
-            // container with no id (e.g. a table-cell paragraph) falls back to the
-            // top-level block's #<index> (readable via get_node, but not patchable —
-            // see the SearchMatch.nodeId note).
-            const id = isObject(node.attrs) && typeof node.attrs.id === "string" && node.attrs.id.length > 0
-                ? node.attrs.id
-                : topRef;
-            for (const [idx, len] of eachMatch(text, query, re, caseSensitive)) {
-                total++;
-                if (matches.length < limit) {
-                    matches.push({
-                        nodeId: id,
-                        blockIndex,
-                        type: node.type,
-                        before: text.slice(Math.max(0, idx - CONTEXT), idx),
-                        match: text.slice(idx, idx + len),
-                        after: text.slice(idx + len, idx + len + CONTEXT),
-                    });
-                }
-            }
-            // A text container holds inline content only — no nested containers to
-            // recurse into.
-            return;
-        }
-        if (Array.isArray(node.content)) {
-            for (const child of node.content)
-                descend(child, blockIndex, topRef);
-        }
-    };
-    for (let i = 0; i < topLevel.length; i++) {
-        descend(topLevel[i], i, `#${i}`);
-    }
-    return { total, truncated: total > matches.length, matches };
-}

packages/mcp/build/lib/parse-node-arg.js

@@ -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;
-}

packages/mcp/build/lib/text-normalize.js

@@ -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;
-}

packages/mcp/build/lib/transforms.js

@@ -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] });
-    }
-}

packages/mcp/build/lib/tree.js

@@ -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));
-}

packages/mcp/build/stdio.js

@@ -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);
-});

packages/mcp/build/tool-specs.js

@@ -1,371 +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),
-        }),
-    },
-    // --- in-page occurrence search (client-side, over ProseMirror plain text) ---
-    searchInPage: {
-        mcpName: 'search_in_page',
-        inAppKey: 'searchInPage',
-        description: 'Find every occurrence of a string (or regex) INSIDE one page and get ' +
-            'WHERE each is — instead of pulling blocks one-by-one with get_node. ' +
-            'Searches the plain text of each text block/cell (marks glued, so a match ' +
-            'survives bold/italic/link splits; comment anchors do not interfere). ' +
-            'Returns { total, truncated, matches:[{ nodeId, blockIndex, type, before, ' +
-            'match, after }] }: `nodeId` is the block id (or "#<index>" for ' +
-            'table/cell content) — pass it to get_node/patch_node (the "#<index>" ' +
-            'form resolves with get_node but NOT patch_node, which only accepts a real ' +
-            'block id). To anchor a comment, do NOT pass nodeId to create_comment (it ' +
-            'has no nodeId param); build a UNIQUE text selection from before+match+' +
-            'after and pass it as create_comment\'s `selection`. `blockIndex` is the ' +
-            'get_outline index; `before`/`after` give ~40 chars of context to build ' +
-            'that unique selection. `total` counts all ' +
-            'hits and `truncated` is true when more than `limit` were found (nothing ' +
-            'is silently dropped). Default is a literal, case-INSENSITIVE substring; ' +
-            'set regex:true for an RE2 regular expression (linear-time, ReDoS-safe: ' +
-            'char classes, word boundaries, anchors and quantifiers work; lookaround ' +
-            '(?=…)/(?<=…) and backreferences \\1 are NOT supported) and ' +
-            'caseSensitive:true to match case. Ideal for systematic ' +
-            'editorial sweeps (unquoted "ё", straight quotes, "т.е.", stray units). An ' +
-            'invalid regex or an empty query returns a clear error to fix.',
-        buildShape: (z) => ({
-            pageId: z.string().min(1).describe('ID of the page to search'),
-            query: z
-                .string()
-                .min(1)
-                .describe('The text to find (a literal substring, or a regex when regex:true)'),
-            regex: z
-                .boolean()
-                .optional()
-                .describe('Treat query as an RE2 regular expression — linear-time, ReDoS-safe; ' +
-                'no lookaround or backreferences (default false).'),
-            caseSensitive: z
-                .boolean()
-                .optional()
-                .describe('Case-sensitive matching (default false).'),
-            limit: z
-                .number()
-                .int()
-                .min(1)
-                .max(200)
-                .optional()
-                .describe('Max matches to RETURN (default 50, max 200); total is always reported.'),
-        }),
-    },
-    // --- 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),
-        }),
-    },
-};

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",

packages/mcp/src/client.ts

@@ -808,8 +808,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
@@ -1798,7 +1804,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.
@@ -2367,8 +2376,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;
@@ -2384,7 +2406,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),
@@ -2392,6 +2414,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) {
@@ -2766,7 +2813,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,
         );
@@ -3512,7 +3561,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.

packages/mcp/src/index.ts

@@ -725,15 +725,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);
   },
 );

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,

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.

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

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

@@ -1,903 +1,15 @@
 /**
- * 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,
+  type ConvertProseMirrorToMarkdownOptions,
+} from "@docmost/prosemirror-markdown";

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";

packages/mcp/src/tool-specs.ts

@@ -31,6 +31,22 @@ export interface SharedToolSpec {
   inAppKey: string;
   /** Single canonical model-facing description used by both layers. */
   description: string;
+  /**
+   * Deferred-tool tier for the IN-APP agent (#332). 'core' tools are always
+   * active; 'deferred' tools are hidden behind the <tool_catalog> and loaded on
+   * demand via the loadTools meta-tool. This is an IN-APP concern only: the
+   * standalone /mcp server ignores this field and registers every tool normally
+   * (registerShared in index.ts reads mcpName/description/buildShape only).
+   */
+  tier: 'core' | 'deferred';
+  /**
+   * Hand-written one-liner "name — purpose" shown in the in-app agent's
+   * <tool_catalog> for a DEFERRED tool (#332). Deliberately NOT derived from the
+   * description's first sentence — a concise, accurate purpose line. Present on
+   * every spec (core tools too) for uniformity; only deferred ones are rendered.
+   * Inert for the external /mcp server.
+   */
+  catalogLine: string;
   /**
    * Builds the tool's input schema as a plain object of zod fields (a
    * ZodRawShape). Called with the consumer's own zod namespace. Omitted for
@@ -47,6 +63,8 @@ export const SHARED_TOOL_SPECS = {
     mcpName: 'get_workspace',
     inAppKey: 'getWorkspace',
     description: 'Fetch metadata about the current workspace (name, settings).',
+    tier: 'core',
+    catalogLine: 'getWorkspace — fetch current workspace metadata (name, settings).',
   },
 
   listSpaces: {
@@ -55,6 +73,8 @@ export const SHARED_TOOL_SPECS = {
     description:
       'List the spaces the current user can access. Returns the array of ' +
       'spaces (id, name, slug, ...).',
+    tier: 'core',
+    catalogLine: 'listSpaces — list the spaces the user can access (id, name, slug).',
   },
 
   listShares: {
@@ -62,6 +82,8 @@ export const SHARED_TOOL_SPECS = {
     inAppKey: 'listShares',
     description:
       'List all public shares in the workspace with page titles and public URLs.',
+    tier: 'deferred',
+    catalogLine: 'listShares — list all public shares in the workspace with their URLs.',
   },
 
   // --- single-pageId read tools ---
@@ -74,6 +96,9 @@ export const SHARED_TOOL_SPECS = {
       '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.',
+    tier: 'deferred',
+    catalogLine:
+      "getPageJson — get a page's raw ProseMirror JSON (lossless, with block ids).",
     buildShape: (z) => ({
       pageId: z.string().min(1),
     }),
@@ -88,6 +113,9 @@ export const SHARED_TOOL_SPECS = {
       'count) WITHOUT the full document body. Use it to locate sections/tables ' +
       'and grab block ids cheaply before fetching, patching or inserting ' +
       'individual blocks.',
+    tier: 'core',
+    catalogLine:
+      "getOutline — compact outline of a page's top-level blocks with their ids.",
     buildShape: (z) => ({
       pageId: z.string().min(1),
     }),
@@ -104,6 +132,9 @@ export const SHARED_TOOL_SPECS = {
       '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.',
+    tier: 'core',
+    catalogLine:
+      "getNode — fetch one block's ProseMirror subtree by block id or #index.",
     buildShape: (z) => ({
       pageId: z.string().min(1),
       nodeId: z.string().min(1),
@@ -137,6 +168,9 @@ export const SHARED_TOOL_SPECS = {
       'caseSensitive:true to match case. Ideal for systematic ' +
       'editorial sweeps (unquoted "ё", straight quotes, "т.е.", stray units). An ' +
       'invalid regex or an empty query returns a clear error to fix.',
+    tier: 'core',
+    catalogLine:
+      'searchInPage — find every occurrence of a string/regex inside one page, with locations.',
     buildShape: (z) => ({
       pageId: z.string().min(1).describe('ID of the page to search'),
       query: z
@@ -172,6 +206,8 @@ export const SHARED_TOOL_SPECS = {
     description:
       'Remove a single block by its attrs.id (from the page outline or ' +
       'page-JSON view) WITHOUT resending the whole document.',
+    tier: 'deferred',
+    catalogLine: 'deleteNode — remove a single content block by its block id.',
     buildShape: (z) => ({
       pageId: z.string().min(1),
       nodeId: z.string().min(1),
@@ -203,6 +239,9 @@ export const SHARED_TOOL_SPECS = {
       '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.',
+    tier: 'deferred',
+    catalogLine:
+      'patchNode — replace one block with a new ProseMirror node, keeping its id.',
     buildShape: (z) => ({
       pageId: z.string().min(1).describe('ID of the page containing the block'),
       nodeId: z
@@ -245,6 +284,9 @@ export const SHARED_TOOL_SPECS = {
       '[{"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.',
+    tier: 'deferred',
+    catalogLine:
+      'insertNode — insert a block before/after an anchor, or append at the end.',
     buildShape: (z) => ({
       pageId: z.string().min(1),
       node: z
@@ -278,6 +320,8 @@ export const SHARED_TOOL_SPECS = {
     mcpName: 'unshare_page',
     inAppKey: 'unsharePage',
     description: 'Remove the public share of a page (revokes the public URL).',
+    tier: 'deferred',
+    catalogLine: "unsharePage — revoke a page's public share (removes the public URL).",
     buildShape: (z) => ({
       pageId: z.string().min(1).describe('ID of the page to unshare'),
     }),
@@ -295,6 +339,9 @@ export const SHARED_TOOL_SPECS = {
       "`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).',
+    tier: 'deferred',
+    catalogLine:
+      'diffPageVersions — diff two page versions and return the change set + summary.',
     buildShape: (z) => ({
       pageId: z.string().min(1),
       from: z
@@ -315,6 +362,9 @@ export const SHARED_TOOL_SPECS = {
       "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.",
+    tier: 'deferred',
+    catalogLine:
+      "listPageHistory — list a page's saved versions (newest first, paginated).",
     buildShape: (z) => ({
       pageId: z.string().min(1),
       cursor: z
@@ -332,6 +382,9 @@ export const SHARED_TOOL_SPECS = {
       '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.',
+    tier: 'deferred',
+    catalogLine:
+      'restorePageVersion — restore a page to a saved history version (revertible).',
     buildShape: (z) => ({
       historyId: z.string().min(1),
     }),
@@ -349,6 +402,9 @@ export const SHARED_TOOL_SPECS = {
       '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.',
+    tier: 'deferred',
+    catalogLine:
+      "importPageMarkdown — replace a page's content from exported Docmost Markdown.",
     buildShape: (z) => ({
       pageId: z.string().min(1),
       markdown: z.string().min(1),
@@ -365,6 +421,9 @@ export const SHARED_TOOL_SPECS = {
       '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'.",
+    tier: 'deferred',
+    catalogLine:
+      "copyPageContent — replace one page's body with a copy of another page's body.",
     buildShape: (z) => ({
       sourcePageId: z.string().min(1).describe('Page to copy content FROM'),
       targetPageId: z
@@ -402,6 +461,9 @@ export const SHARED_TOOL_SPECS = {
       '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).',
+    tier: 'core',
+    catalogLine:
+      "editPageText — surgical find/replace of plain text in a page, preserving ids/marks.",
     buildShape: (z) => ({
       pageId: z.string().describe('ID of the page to edit'),
       edits: z
@@ -440,6 +502,9 @@ export const SHARED_TOOL_SPECS = {
       '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).',
+    tier: 'deferred',
+    catalogLine:
+      'stashPage — serialize a whole page to a short anonymous URL without loading its body.',
     buildShape: (z) => ({
       pageId: z.string().min(1),
     }),

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) {

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");
+});

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/);
 });

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");
   });
 });

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", () => {

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 () => {

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\\""}-->',
   );
 });

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);
 });

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);
 });
 
 // ---------------------------------------------------------------------------