feat: proper DOCX support

feat: footnotes
chore: package updates (#2383 )
2026-08-20 02:54:11 +08:00 · 2026-08-11 01:45:01 +01:00 · 2026-08-11 01:30:26 +01:00 · 2026-08-10 17:56:12 +01:00 · 2026-08-10 17:38:03 +01:00 · 2026-08-10 17:37:12 +01:00
76 changed files with 4095 additions and 3276 deletions
@@ -1,7 +1,7 @@
 FROM node:26-slim AS base
 LABEL org.opencontainers.image.source="https://github.com/docmost/docmost"

-RUN npm install -g pnpm@11.13.0
+RUN npm install -g pnpm@11.15.1

 FROM base AS builder

@@ -36,7 +36,7 @@
    "@tanstack/react-table": "8.21.3",
    "@tanstack/react-virtual": "3.14.3",
    "alfaaz": "1.1.0",
-    "axios": "1.16.0",
+    "axios": "1.18.1",
    "blueimp-load-image": "5.16.0",
    "clsx": "2.1.1",
    "file-saver": "2.0.5",
@@ -50,9 +50,9 @@
    "katex": "0.16.40",
    "lowlight": "3.3.0",
    "mantine-form-zod-resolver": "1.3.0",
-    "mermaid": "11.15.0",
+    "mermaid": "11.16.1",
    "mitt": "3.0.1",
-    "nanoid": "3.3.8",
+    "nanoid": "3.3.17",
    "posthog-js": "1.391.2",
    "react": "19.2.7",
    "react-clear-modal": "^2.0.18",
@@ -61,7 +61,7 @@
    "react-error-boundary": "6.1.1",
    "react-helmet-async": "3.0.0",
    "react-i18next": "16.5.8",
-    "react-router-dom": "7.18.0",
+    "react-router-dom": "7.18.2",
    "semver": "7.7.4",
    "socket.io-client": "4.8.3",
    "zod": "4.3.6"
@@ -86,7 +86,7 @@
    "globals": "15.13.0",
    "jsdom": "25.0.0",
    "optics-ts": "2.4.1",
-    "postcss": "8.5.14",
+    "postcss": "8.5.25",
    "postcss-preset-mantine": "1.18.0",
    "postcss-simple-vars": "7.0.1",
    "prettier": "3.8.1",
@@ -387,6 +387,8 @@
  "Insert horizontal rule divider": "Insert horizontal rule divider",
  "Page break": "Page break",
  "Insert a page break for printing.": "Insert a page break for printing.",
+  "Footnote": "Footnote",
+  "Insert a footnote reference.": "Insert a footnote reference.",
  "Upload any image from your device.": "Upload any image from your device.",
  "Upload any video from your device.": "Upload any video from your device.",
  "Upload any audio from your device.": "Upload any audio from your device.",
@@ -0,0 +1,45 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+import { HelmetProvider } from "react-helmet-async";
+import { DocumentTitle } from "./document-title.tsx";
+
+const renderTitle = (ui: React.ReactNode) =>
+  render(<HelmetProvider>{ui}</HelmetProvider>);
+
+describe("DocumentTitle", () => {
+  beforeEach(() => {
+    document.head.innerHTML = "<title>Docmost</title>";
+  });
+
+  it("appends the app name", () => {
+    renderTitle(<DocumentTitle title="Home" />);
+    expect(document.title).toBe("Home - Docmost");
+  });
+
+  it("omits the app name when asked", () => {
+    renderTitle(<DocumentTitle title="My page" withAppName={false} />);
+    expect(document.title).toBe("My page");
+  });
+
+  it("falls back to the app name without a title", () => {
+    renderTitle(<DocumentTitle />);
+    expect(document.title).toBe("Docmost");
+  });
+
+  it("never renders an empty title", () => {
+    renderTitle(<DocumentTitle title="Spaces" />);
+    const titles = Array.from(document.querySelectorAll("head > title"));
+    expect(titles.every((node) => node.textContent !== "")).toBe(true);
+  });
+
+  it("renders extra head children", () => {
+    renderTitle(
+      <DocumentTitle title="Shared">
+        <meta name="robots" content="noindex" />
+      </DocumentTitle>,
+    );
+    expect(
+      document.querySelector('head > meta[name="robots"]')?.getAttribute("content"),
+    ).toBe("noindex");
+  });
+});
@@ -0,0 +1,29 @@
+import React from "react";
+import { Helmet } from "react-helmet-async";
+import { getAppName } from "@/lib/config.ts";
+
+type DocumentTitleProps = {
+  title?: string;
+  withAppName?: boolean;
+  children?: React.ReactNode;
+};
+
+export function DocumentTitle({
+  title,
+  withAppName = true,
+  children,
+}: DocumentTitleProps) {
+  const appName = getAppName();
+
+  let documentTitle = appName;
+  if (title) {
+    documentTitle = withAppName ? `${title} - ${appName}` : title;
+  }
+
+  return (
+    <Helmet>
+      <title>{documentTitle}</title>
+      {children}
+    </Helmet>
+  );
+}
@@ -1,17 +1,15 @@
 import { Title, Text, Button, Container, Group } from "@mantine/core";
 import classes from "./error-404.module.css";
 import { Link } from "react-router-dom";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export function Error404() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>{t("404 page not found")} - Docmost</title>
-      </Helmet>
+      <DocumentTitle title={t("404 page not found")} />
      <Container className={classes.root}>
        <Title className={classes.title}>{t("404 page not found")}</Title>
        <Text c="dimmed" size="lg" ta="center" className={classes.description}>
@@ -1,5 +1,3 @@
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
 import React from "react";
 import useUserRole from "@/hooks/use-user-role.tsx";
@@ -15,6 +13,7 @@ import { Feature } from "@/ee/features";
 import { useUpgradeLabel } from "@/ee/hooks/use-upgrade-label";
 import { isCloud } from "@/lib/config.ts";
 import { useLocation, useNavigate } from "react-router-dom";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function AiSettings() {
  const { t } = useTranslation();
@@ -40,9 +39,7 @@ export default function AiSettings() {

  return (
    <>
-      <Helmet>
-        <title>AI settings - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="AI settings" />
      <SettingsTitle title={t("AI settings")} />

      <Tabs color="dark" value={activeTab} onChange={handleTabChange}>
@@ -1,10 +1,9 @@
 import React, { useState } from "react";
 import { Anchor, Alert, Button, Group, Space, Text } from "@mantine/core";
 import { IconInfoCircle } from "@tabler/icons-react";
-import { Helmet } from "react-helmet-async";
 import { Trans, useTranslation } from "react-i18next";
 import SettingsTitle from "@/components/settings/settings-title";
-import { getAppName, getAppUrl } from "@/lib/config";
+import { getAppUrl } from "@/lib/config";
 import { ApiKeyTable } from "@/ee/api-key/components/api-key-table";
 import { CreateApiKeyModal } from "@/ee/api-key/components/create-api-key-modal";
 import { ApiKeyCreatedModal } from "@/ee/api-key/components/api-key-created-modal";
@@ -17,6 +16,7 @@ import { IApiKey } from "@/ee/api-key";
 import { useAtom } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import useUserRole from "@/hooks/use-user-role.tsx";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function UserApiKeys() {
  const { t } = useTranslation();
@@ -49,11 +49,7 @@ export default function UserApiKeys() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("API keys")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("API keys")} />

      <SettingsTitle title={t("API keys")} />

@@ -1,9 +1,7 @@
 import React, { useState } from "react";
 import { Anchor, Button, Divider, Group, Space, Text } from "@mantine/core";
-import { Helmet } from "react-helmet-async";
 import { Trans, useTranslation } from "react-i18next";
 import SettingsTitle from "@/components/settings/settings-title";
-import { getAppName } from "@/lib/config";
 import { ApiKeyTable } from "@/ee/api-key/components/api-key-table";
 import { CreateApiKeyModal } from "@/ee/api-key/components/create-api-key-modal";
 import { ApiKeyCreatedModal } from "@/ee/api-key/components/api-key-created-modal";
@@ -15,6 +13,7 @@ import { useGetApiKeysQuery } from "@/ee/api-key/queries/api-key-query.ts";
 import { IApiKey } from "@/ee/api-key";
 import useUserRole from '@/hooks/use-user-role.tsx';
 import RestrictApiToAdmins from "@/ee/api-key/components/restrict-api-to-admins";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function WorkspaceApiKeys() {
  const { t } = useTranslation();
@@ -47,11 +46,7 @@ export default function WorkspaceApiKeys() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("API management")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("API management")} />

      <SettingsTitle title={t("API management")} />

@@ -10,11 +10,9 @@ import {
  Text,
  Tooltip,
 } from "@mantine/core";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { IconSettings } from "@tabler/icons-react";
 import SettingsTitle from "@/components/settings/settings-title";
-import { getAppName } from "@/lib/config";
 import Paginate from "@/components/common/paginate";
 import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import {
@@ -26,6 +24,7 @@ import { IAuditLogParams } from "@/ee/audit/types/audit.types";
 import { eventFilterOptions } from "@/ee/audit/lib/audit-event-labels";
 import AuditLogsTable from "@/ee/audit/components/audit-logs-table";
 import useUserRole from "@/hooks/use-user-role";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 type RetentionUnit = "days" | "months" | "years";

@@ -97,11 +96,7 @@ export default function AuditLogs() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Audit log")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Audit log")} />

      <SettingsTitle title={t("Audit log")} />

@@ -1,5 +1,3 @@
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
 import BillingPlans from "@/ee/billing/components/billing-plans.tsx";
 import BillingTrial from "@/ee/billing/components/billing-trial.tsx";
@@ -9,6 +7,7 @@ import React from "react";
 import BillingDetails from "@/ee/billing/components/billing-details.tsx";
 import { useBillingQuery } from "@/ee/billing/queries/billing-query.ts";
 import useUserRole from "@/hooks/use-user-role.tsx";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Billing() {
  const { data: billing, isError: isBillingError } = useBillingQuery();
@@ -20,9 +19,7 @@ export default function Billing() {

  return (
    <>
-      <Helmet>
-        <title>Billing - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="Billing" />
      <SettingsTitle title="Billing" />

      <BillingTrial />
@@ -1,5 +1,3 @@
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
 import React from "react";
 import useUserRole from "@/hooks/use-user-role.tsx";
@@ -9,6 +7,7 @@ import InstallationDetails from "@/ee/licence/components/installation-details.ts
 import OssDetails from "@/ee/licence/components/oss-details.tsx";
 import { useAtom } from "jotai/index";
 import { entitlementAtom } from "@/ee/entitlement/entitlement-atom";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function License() {
  const [entitlements] = useAtom(entitlementAtom);
@@ -21,9 +20,7 @@ export default function License() {

  return (
    <>
-      <Helmet>
-        <title>License - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="License" />
      <SettingsTitle title="License" />

      <ActivateLicenseForm />
@@ -1,17 +1,16 @@
 import { useState, useMemo } from "react";
 import { Group, MultiSelect, Select, Space, TextInput } from "@mantine/core";
 import { useDebouncedValue } from "@mantine/hooks";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { IconSearch } from "@tabler/icons-react";
 import SettingsTitle from "@/components/settings/settings-title";
-import { getAppName } from "@/lib/config";
 import Paginate from "@/components/common/paginate";
 import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import { useVerificationListQuery } from "@/ee/page-verification/queries/page-verification-query";
 import { IVerificationListParams } from "@/ee/page-verification/types/page-verification.types";
 import VerificationListTable from "@/ee/page-verification/components/verification-list-table";
 import { useGetSpacesQuery } from "@/features/space/queries/space-query";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function VerifiedPages() {
  const { t } = useTranslation();
@@ -68,11 +67,7 @@ export default function VerifiedPages() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Verified pages")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Verified pages")} />

      <SettingsTitle title={t("Verified pages")} />

@@ -1,18 +1,13 @@
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import { CloudLoginForm } from "@/ee/components/cloud-login-form.tsx";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function CloudLogin() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Login")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Login")} />

      <CloudLoginForm />
    </>
@@ -1,14 +1,11 @@
 import { SetupWorkspaceForm } from "@/features/auth/components/setup-workspace-form.tsx";
-import { Helmet } from "react-helmet-async";
 import React from "react";
-import { getAppName } from "@/lib/config.ts";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function CreateWorkspace() {
  return (
    <>
-      <Helmet>
-        <title>Create Workspace - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="Create Workspace" />
      <SetupWorkspaceForm />
    </>
  );
@@ -1,5 +1,4 @@
-import { Helmet } from "react-helmet-async";
-import { getAppName, isCloud } from "@/lib/config.ts";
+import { isCloud } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
 import {
  Alert,
@@ -37,6 +36,7 @@ import EnableScim from "@/ee/scim/components/enable-scim";
 import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import Paginate from "@/components/common/paginate";
 import { IScimToken } from "@/ee/scim/types/scim-token.types";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 const SCIM_TOKEN_LIMIT = 5;

@@ -64,9 +64,7 @@ export default function Security() {

  return (
    <>
-      <Helmet>
-        <title>Security - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="Security" />
      <SettingsTitle title={t("Security")} />

      <EnforceMfa />
@@ -22,8 +22,6 @@ import { useTranslation } from "react-i18next";
 import { useDisclosure, useWindowEvent } from "@mantine/hooks";
 import { notifications } from "@mantine/notifications";
 import { Link, useParams } from "react-router-dom";
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config";
 import { useEditor, EditorContent } from "@tiptap/react";
 import { templateExtensions } from "@/features/editor/extensions/extensions";
 import {
@@ -44,6 +42,7 @@ import CalloutMenu from "@/features/editor/components/callout/callout-menu.tsx";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";

 import classes from "./template-editor.module.css";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function TemplateEditor() {
  const { t } = useTranslation();
@@ -247,11 +246,7 @@ export default function TemplateEditor() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Edit template")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Edit template")} />

      {editorToolbarEnabled && editor && (
        <FixedToolbar editor={editor} templateMode />
@@ -13,11 +13,9 @@ import {
 } from "@mantine/core";
 import { modals } from "@mantine/modals";
 import { IconPlus } from "@tabler/icons-react";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { useNavigate } from "react-router-dom";
 import { useDisclosure } from "@mantine/hooks";
-import { getAppName } from "@/lib/config";
 import {
  useGetTemplatesQuery,
  useDeleteTemplateMutation,
@@ -31,6 +29,7 @@ import useUserRole from "@/hooks/use-user-role";
 import CreateTemplateModal from "@/ee/template/components/create-template-modal";
 import { useAtomValue } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function TemplateList() {
  const { t } = useTranslation();
@@ -102,11 +101,7 @@ export default function TemplateList() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Templates")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Templates")} />

      <Container size="900" pt="xl">
        <Group justify="space-between" mb="xl">
@@ -0,0 +1,46 @@
+import {
+  HocuspocusProviderWebsocket,
+  WebSocketStatus,
+} from "@hocuspocus/provider";
+import { getCollaborationUrl } from "@/lib/config.ts";
+
+const RELEASE_GRACE_MS = 5000;
+
+let socket: HocuspocusProviderWebsocket | null = null;
+let editorCount = 0;
+let releaseTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function getCollabSocket(): HocuspocusProviderWebsocket {
+  if (!socket) {
+    socket = new HocuspocusProviderWebsocket({
+      url: getCollaborationUrl(),
+      autoConnect: false,
+    });
+  }
+  return socket;
+}
+
+export function acquireCollabSocket(): void {
+  editorCount++;
+  if (releaseTimer) {
+    clearTimeout(releaseTimer);
+    releaseTimer = null;
+  }
+  const collabSocket = getCollabSocket();
+  collabSocket.shouldConnect = true;
+  if (collabSocket.status === WebSocketStatus.Disconnected) {
+    collabSocket.connect();
+  }
+}
+
+export function releaseCollabSocket(): void {
+  editorCount--;
+  if (editorCount > 0) return;
+  if (releaseTimer) clearTimeout(releaseTimer);
+  releaseTimer = setTimeout(() => {
+    releaseTimer = null;
+    if (editorCount === 0) {
+      socket?.disconnect();
+    }
+  }, RELEASE_GRACE_MS);
+}
@@ -6,6 +6,7 @@
  z-index: 99;
  display: flex;
  align-items: center;
+  min-height: 45px;
  background: var(--mantine-color-body);
  border-bottom: 1px solid
    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-4));
@@ -31,8 +31,6 @@ export const FixedToolbar: FC<FixedToolbarProps> = ({
  const workspace = useAtomValue(workspaceAtom);
  const isGenerativeAiEnabled = workspace?.settings?.ai?.generative === true;

-  if (!editor || !state) return null;
-
  return (
    <>
      <div
@@ -49,22 +47,26 @@ export const FixedToolbar: FC<FixedToolbarProps> = ({
              <div className={classes.divider} />
            </>
          )} */}
-          <BlockTypeGroup editor={editor} />
-          <div className={classes.divider} />
-          <InlineMarksGroup editor={editor} state={state} />
-          <div className={classes.divider} />
-          <ColorGroup editor={editor} />
-          <div className={classes.divider} />
-          <ListsGroup editor={editor} state={state} />
-          <div className={classes.divider} />
-          <AlignmentGroup editor={editor} />
-          <div className={classes.divider} />
-          <MediaGroup editor={editor} templateMode={templateMode} />
-          <div className={classes.divider} />
-          <QuickInsertsGroup editor={editor} />
-          <MoreInsertsGroup editor={editor} templateMode={templateMode} />
-          <div className={classes.divider} />
-          <HistoryGroup editor={editor} state={state} />
+          {editor && state && (
+            <>
+              <BlockTypeGroup editor={editor} />
+              <div className={classes.divider} />
+              <InlineMarksGroup editor={editor} state={state} />
+              <div className={classes.divider} />
+              <ColorGroup editor={editor} />
+              <div className={classes.divider} />
+              <ListsGroup editor={editor} state={state} />
+              <div className={classes.divider} />
+              <AlignmentGroup editor={editor} />
+              <div className={classes.divider} />
+              <MediaGroup editor={editor} templateMode={templateMode} />
+              <div className={classes.divider} />
+              <QuickInsertsGroup editor={editor} />
+              <MoreInsertsGroup editor={editor} templateMode={templateMode} />
+              <div className={classes.divider} />
+              <HistoryGroup editor={editor} state={state} />
+            </>
+          )}
        </div>
      </div>
      <div className={classes.spacer} aria-hidden />
@@ -12,6 +12,7 @@ import {
  IconMathFunction,
  IconRotate2,
  IconSitemap,
+  IconSuperscript,
  IconTable,
  IconTag,
 } from "@tabler/icons-react";
@@ -270,6 +271,12 @@ export const MoreInsertsGroup: FC<Props> = ({ editor, templateMode }) => {
        >
          {t("Math block")}
        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconSuperscript size={16} />}
+          onClick={() => editor.chain().focus().addFootnote().run()}
+        >
+          {t("Footnote")}
+        </Menu.Item>
      </Menu.Dropdown>
    </Menu>
  );
@@ -30,6 +30,7 @@ import {
  IconTag,
  IconMoodSmile,
  IconRotate2,
+  IconSuperscript,
 } from "@tabler/icons-react";
 import {
  CommandProps,
@@ -177,6 +178,16 @@ const CommandGroups: SlashMenuGroupedItemsType = {
      command: ({ editor, range }: CommandProps) =>
        editor.chain().focus().deleteRange(range).setPageBreak().run(),
    },
+    {
+      title: "Footnote",
+      description: "Insert a footnote reference.",
+      searchTerms: ["footnote", "reference", "citation", "note"],
+      icon: IconSuperscript,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).run();
+        editor.commands.addFootnote();
+      },
+    },
    {
      title: "Image",
      description: "Upload any image from your device.",
@@ -1,9 +1,11 @@
 import { markInputRule } from "@tiptap/core";
 import { StarterKit } from "@tiptap/starter-kit";
+import { Document } from "@tiptap/extension-document";
 import { Code } from "@tiptap/extension-code";
 import { TextAlign } from "@tiptap/extension-text-align";
 import { TaskList, TaskItem } from "@tiptap/extension-list";
-import { Placeholder, CharacterCount, UndoRedo } from "@tiptap/extensions";
+import { CharacterCount, UndoRedo } from "@tiptap/extensions";
+import { Placeholder } from "@/features/editor/extensions/placeholder";
 import { Superscript } from "@tiptap/extension-superscript";
 import SubScript from "@tiptap/extension-subscript";
 import { Typography } from "@tiptap/extension-typography";
@@ -62,6 +64,9 @@ import {
  TransclusionReference,
  TableView,
  BaseEmbed as BaseEmbedNode,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
 } from "@docmost/editor-ext";
 import {
  randomElement,
@@ -131,6 +136,7 @@ lowlight.register("scala", scala);
 // @ts-ignore
 export const mainExtensions = [
  StarterKit.configure({
+    document: false,
    heading: false,
    undoRedo: false,
    link: false,
@@ -142,6 +148,9 @@ export const mainExtensions = [
    codeBlock: false,
    code: false,
  }),
+  Document.extend({
+    content: "block+ footnotes?",
+  }),
  // Override TipTap's Code extension to fix the inline code input rule.
  // The upstream regex /(^|[^`])`([^`]+)`(?!`)$/ captures the character
  // before the opening backtick as part of the match, causing markInputRule
@@ -194,16 +203,19 @@ export const mainExtensions = [
        return i18n.t("Toggle title");
      }
      if (node.type.name === "paragraph") {
-        const $pos = editor.state.doc.resolve(pos);
-        const parentName = $pos.parent.type.name;
-        if (
-          parentName === "column" ||
-          parentName === "tableCell" ||
-          parentName === "tableHeader" ||
-          parentName === "callout" ||
-          parentName === "blockquote"
-        ) {
-          return i18n.t("Write...");
+        const doc = editor.state.doc;
+        if (pos >= 0 && pos <= doc.content.size) {
+          const parentName = doc.resolve(pos).parent.type.name;
+          if (
+            parentName === "column" ||
+            parentName === "tableCell" ||
+            parentName === "tableHeader" ||
+            parentName === "callout" ||
+            parentName === "blockquote" ||
+            parentName === "footnote"
+          ) {
+            return i18n.t("Write...");
+          }
        }
        return i18n.t('Write anything. Enter "/" for commands');
      }
@@ -414,6 +426,9 @@ export const mainExtensions = [
  }).configure(),
  Columns,
  Column,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
  AutoJoiner.configure({
    elementsToJoin: [],
  }),
@@ -0,0 +1,64 @@
+import { isNodeEmpty } from "@tiptap/core";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import { Placeholder as TiptapPlaceholder } from "@tiptap/extensions";
+
+export const Placeholder = TiptapPlaceholder.extend({
+  addProseMirrorPlugins() {
+    const editor = this.editor;
+    const options = this.options;
+    const dataAttribute = `data-${options.dataAttribute || "placeholder"}`;
+
+    return [
+      new Plugin({
+        key: new PluginKey("docmostPlaceholder"),
+        props: {
+          decorations: (state) => {
+            if (options.showOnlyWhenEditable && !editor.isEditable) {
+              return null;
+            }
+
+            const { doc, selection } = state;
+            const { anchor } = selection;
+            const decorations: Decoration[] = [];
+            const isEmptyDoc = editor.isEmpty;
+
+            doc.descendants((node, pos) => {
+              if (!node.type.isTextblock) {
+                return options.includeChildren;
+              }
+
+              const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize;
+              const isEmpty = !node.isLeaf && isNodeEmpty(node);
+
+              if ((hasAnchor || !options.showOnlyCurrent) && isEmpty) {
+                const emptyNodeClass =
+                  typeof options.emptyNodeClass === "function"
+                    ? options.emptyNodeClass({ editor, node, pos, hasAnchor })
+                    : options.emptyNodeClass;
+                const classes = [emptyNodeClass];
+                if (isEmptyDoc) {
+                  classes.push(options.emptyEditorClass);
+                }
+
+                decorations.push(
+                  Decoration.node(pos, pos + node.nodeSize, {
+                    class: classes.join(" "),
+                    [dataAttribute]:
+                      typeof options.placeholder === "function"
+                        ? options.placeholder({ editor, node, pos, hasAnchor })
+                        : options.placeholder,
+                  }),
+                );
+              }
+
+              return options.includeChildren;
+            });
+
+            return DecorationSet.create(doc, decorations);
+          },
+        },
+      }),
+    ];
+  },
+});
@@ -1,7 +0,0 @@
-import { getCollaborationUrl } from "@/lib/config.ts";
-
-const useCollaborationURL = (): string => {
-  return getCollaborationUrl();
-};
-
-export default useCollaborationURL;
@@ -2,20 +2,22 @@ import "@/features/editor/styles/index.css";
 import React, {
  useCallback,
  useEffect,
+  useLayoutEffect,
  useMemo,
  useRef,
  useState,
 } from "react";
 import { IndexeddbPersistence } from "y-indexeddb";
-import * as Y from "yjs";
 import {
-  HocuspocusProvider,
-  onStatusParameters,
  WebSocketStatus,
-  HocuspocusProviderWebsocket,
-  onSyncedParameters,
  onStatelessParameters,
 } from "@hocuspocus/provider";
+import {
+  HocuspocusProviderWebsocketComponent,
+  HocuspocusRoom,
+  useHocuspocusEvent,
+  useHocuspocusProvider,
+} from "@hocuspocus/provider-react";
 import {
  Editor,
  EditorContent,
@@ -28,7 +30,6 @@ import {
  mainExtensions,
 } from "@/features/editor/extensions/extensions";
 import { useAtom, useAtomValue } from "jotai";
-import useCollaborationUrl from "@/features/editor/hooks/use-collaboration-url";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom";
 import {
  currentPageEditModeAtom,
@@ -76,6 +77,11 @@ import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";
 import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";
 import { useTranslation } from "react-i18next";
+import {
+  acquireCollabSocket,
+  getCollabSocket,
+  releaseCollabSocket,
+} from "@/features/editor/collab-socket";

 interface PageEditorProps {
  pageId: string;
@@ -91,7 +97,80 @@ export default function PageEditor({
  canComment,
 }: PageEditorProps) {
  const { t } = useTranslation();
-  const collaborationURL = useCollaborationUrl();
+  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
+  const { pageSlug } = useParams();
+  const slugId = extractPageSlugId(pageSlug);
+  const [socket] = useState(getCollabSocket);
+  const hasCollabToken = !!collabQuery?.token;
+
+  useEffect(() => {
+    if (!hasCollabToken) return;
+    acquireCollabSocket();
+    return () => releaseCollabSocket();
+  }, [hasCollabToken]);
+
+  const handleStateless = ({ payload }: onStatelessParameters) => {
+    try {
+      const message = JSON.parse(payload);
+      if (message?.type !== "page.updated" || !message.updatedAt) return;
+      const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
+      if (pageData) {
+        queryClient.setQueryData(["pages", slugId], {
+          ...pageData,
+          updatedAt: message.updatedAt,
+          ...(message.lastUpdatedBy && {
+            lastUpdatedBy: message.lastUpdatedBy,
+          }),
+        });
+      }
+    } catch {
+      // ignore unrelated stateless messages
+    }
+  };
+
+  const handleAuthenticationFailed = () => {
+    const payload = jwtDecode(collabQuery?.token);
+    const now = Date.now().valueOf() / 1000;
+    const isTokenExpired = now >= payload.exp;
+    if (isTokenExpired) {
+      refetchCollabToken();
+    }
+  };
+
+  return (
+    <TransclusionLookupProvider>
+      {collabQuery?.token ? (
+        <HocuspocusProviderWebsocketComponent websocketProvider={socket}>
+          <HocuspocusRoom
+            name={`page.${pageId}`}
+            token={collabQuery.token}
+            flushDelay={500}
+            onStateless={handleStateless}
+            onAuthenticationFailed={handleAuthenticationFailed}
+          >
+            <CollabPageEditor
+              pageId={pageId}
+              editable={editable}
+              content={content}
+              canComment={canComment}
+            />
+          </HocuspocusRoom>
+        </HocuspocusProviderWebsocketComponent>
+      ) : (
+        <StaticPageEditor content={content} ariaLabel={t("Page content")} />
+      )}
+    </TransclusionLookupProvider>
+  );
+}
+
+function CollabPageEditor({
+  pageId,
+  editable,
+  content,
+  canComment,
+}: PageEditorProps) {
+  const { t } = useTranslation();
+  const provider = useHocuspocusProvider();
  const isComponentMounted = useRef(false);
  const editorRef = useRef<Editor | null>(null);

@@ -112,7 +191,6 @@ export default function PageEditor({
  );
  const [, setYjsSynced] = useAtom(yjsSyncedAtom);
  const menuContainerRef = useRef(null);
-  const { data: collabQuery, refetch: refetchCollabToken } = useCollabToken();
  const { isIdle, resetIdle } = useIdle(FIVE_MINUTES, { initialState: false });
  const documentState = useDocumentVisibility();
  const { pageSlug } = useParams();
@@ -123,95 +201,24 @@ export default function PageEditor({
    [isComponentMounted],
  );
  const { handleScrollTo } = useEditorScroll({ canScroll });
-  // Providers only created once per pageId
-  const providersRef = useRef<{
-    local: IndexeddbPersistence;
-    remote: HocuspocusProvider;
-    socket: HocuspocusProviderWebsocket;
-  } | null>(null);
-  const [providersReady, setProvidersReady] = useState(false);

  useEffect(() => {
-    if (!providersRef.current) {
-      const documentName = `page.${pageId}`;
-      const ydoc = new Y.Doc();
-      const local = new IndexeddbPersistence(documentName, ydoc);
-      const socket = new HocuspocusProviderWebsocket({
-        url: collaborationURL,
-      });
-      const onLocalSyncedHandler = () => {
-        setIsLocalSynced(true);
-      };
-      const onStatusHandler = (event: onStatusParameters) => {
-        setYjsConnectionStatus(event.status);
-      };
-      const onSyncedHandler = (event: onSyncedParameters) => {
-        setIsRemoteSynced(event.state);
-      };
-      const onStatelessHandler = ({ payload }: onStatelessParameters) => {
-        try {
-          const message = JSON.parse(payload);
-          if (message?.type !== "page.updated" || !message.updatedAt) return;
-          const pageData = queryClient.getQueryData<IPage>(["pages", slugId]);
-          if (pageData) {
-            queryClient.setQueryData(["pages", slugId], {
-              ...pageData,
-              updatedAt: message.updatedAt,
-              ...(message.lastUpdatedBy && {
-                lastUpdatedBy: message.lastUpdatedBy,
-              }),
-            });
-          }
-        } catch {
-          // ignore unrelated stateless messages
-        }
-      };
-      const onAuthenticationFailedHandler = () => {
-        const payload = jwtDecode(collabQuery?.token);
-        const now = Date.now().valueOf() / 1000;
-        const isTokenExpired = now >= payload.exp;
-        if (isTokenExpired) {
-          refetchCollabToken().then((result) => {
-            if (result.data?.token) {
-              socket.disconnect();
-              setTimeout(() => {
-                remote.configuration.token = result.data.token;
-                socket.connect();
-              }, 100);
-            }
-          });
-        }
-      };
-      const remote = new HocuspocusProvider({
-        websocketProvider: socket,
-        name: documentName,
-        document: ydoc,
-        token: collabQuery?.token,
-        onAuthenticationFailed: onAuthenticationFailedHandler,
-        onStatus: onStatusHandler,
-        onSynced: onSyncedHandler,
-        onStateless: onStatelessHandler,
-      });
-
-      local.on("synced", onLocalSyncedHandler);
-      providersRef.current = { socket, local, remote };
-      setProvidersReady(true);
-    } else {
-      setProvidersReady(true);
-    }
-    // Only destroy on final unmount
+    const local = new IndexeddbPersistence(
+      provider.configuration.name,
+      provider.document,
+    );
+    local.on("synced", () => setIsLocalSynced(true));
    return () => {
-      providersRef.current?.socket.destroy();
-      providersRef.current?.remote.destroy();
-      providersRef.current?.local.destroy();
-      providersRef.current = null;
+      local.destroy();
    };
-  }, [pageId]);
+  }, [provider]);
+
+  useHocuspocusEvent("synced", ({ state }) => setIsRemoteSynced(state));
+  useHocuspocusEvent("status", ({ status }) => setYjsConnectionStatus(status));

  // Only connect/disconnect on tab/idle, not destroy
  useEffect(() => {
-    if (!providersReady || !providersRef.current) return;
-    const socket = providersRef.current.socket;
+    const socket = provider.configuration.websocketProvider;

    if (
      isIdle &&
@@ -228,23 +235,15 @@ export default function PageEditor({
      resetIdle();
      socket.connect();
    }
-  }, [isIdle, documentState, providersReady, resetIdle]);
-
-  // Attach here, to make sure the connection gets properly established
-  providersRef.current?.remote.attach();
+  }, [isIdle, documentState, provider, resetIdle]);

  const extensions = useMemo(() => {
-    if (!providersReady || !providersRef.current || !currentUser?.user) {
+    if (!currentUser?.user) {
      return mainExtensions;
    }

-    const remoteProvider = providersRef.current.remote;
-
-    return [
-      ...mainExtensions,
-      ...collabExtensions(remoteProvider, currentUser?.user),
-    ];
-  }, [providersReady, currentUser?.user]);
+    return [...mainExtensions, ...collabExtensions(provider, currentUser.user)];
+  }, [provider, currentUser?.user]);

  const editor = useEditor(
    {
@@ -326,6 +325,16 @@ export default function PageEditor({
    [pageId, editable, extensions],
  );

+  useLayoutEffect(() => {
+    if (editor && !editor.isDestroyed) {
+      // @ts-ignore
+      setEditor(editor);
+      // @ts-ignore
+      editor.storage.pageId = pageId;
+      editorRef.current = editor;
+    }
+  }, [editor, pageId, setEditor]);
+
  const editorIsEditable = useEditorState({
    editor,
    selector: (ctx) => {
@@ -416,65 +425,72 @@ export default function PageEditor({
    }
  }, [yjsConnectionStatus, isSynced]);

+  if (showStatic) {
+    return <StaticPageEditor content={content} ariaLabel={t("Page content")} />;
+  }
+
  return (
-    <TransclusionLookupProvider>
-      {showStatic ? (
-        <EditorProvider
-          editable={false}
-          immediatelyRender={true}
-          extensions={mainExtensions}
-          content={content}
-          editorProps={{
-            attributes: {
-              "aria-label": t("Page content"),
-            },
-          }}
-        />
-      ) : (
-        <div className="editor-container" style={{ position: "relative" }}>
-          <div ref={menuContainerRef}>
-            <EditorContent editor={editor} />
+    <div className="editor-container" style={{ position: "relative" }}>
+      <div ref={menuContainerRef}>
+        <EditorContent editor={editor} />

-            {editor && (
-              <SearchAndReplaceDialog editor={editor} editable={editable} />
-            )}
+        {editor && (
+          <SearchAndReplaceDialog editor={editor} editable={editable} />
+        )}

-            {editor && editorIsEditable && (
-              <div>
-                <EditorAiMenu editor={editor} />
-                <EditorLinkMenu editor={editor} />
-                <EditorBubbleMenu editor={editor} />
-                <TableMenu editor={editor} />
-                <TableHandlesLayer editor={editor} />
-                <ImageMenu editor={editor} />
-                <VideoMenu editor={editor} />
-                <PdfMenu editor={editor} />
-                <CalloutMenu editor={editor} />
-                <SubpagesMenu editor={editor} />
-                <ExcalidrawMenu editor={editor} />
-                <DrawioMenu editor={editor} />
-                <ColumnsMenu editor={editor} />
-              </div>
-            )}
-            {editor &&
-              !editorIsEditable &&
-              (editable || canComment) &&
-              providersRef.current && <ReadonlyBubbleMenu editor={editor} />}
-            {showCommentPopup && (
-              <CommentDialog editor={editor} pageId={pageId} />
-            )}
-            {showReadOnlyCommentPopup && (
-              <CommentDialog editor={editor} pageId={pageId} readOnly />
-            )}
+        {editor && editorIsEditable && (
+          <div>
+            <EditorAiMenu editor={editor} />
+            <EditorLinkMenu editor={editor} />
+            <EditorBubbleMenu editor={editor} />
+            <TableMenu editor={editor} />
+            <TableHandlesLayer editor={editor} />
+            <ImageMenu editor={editor} />
+            <VideoMenu editor={editor} />
+            <PdfMenu editor={editor} />
+            <CalloutMenu editor={editor} />
+            <SubpagesMenu editor={editor} />
+            <ExcalidrawMenu editor={editor} />
+            <DrawioMenu editor={editor} />
+            <ColumnsMenu editor={editor} />
          </div>
-          <div
-            onClick={() => {
-              if (editor && !editor.isDestroyed) editor.commands.focus("end");
-            }}
-            style={{ paddingBottom: "20vh" }}
-          ></div>
-        </div>
-      )}
-    </TransclusionLookupProvider>
+        )}
+        {editor && !editorIsEditable && (editable || canComment) && (
+          <ReadonlyBubbleMenu editor={editor} />
+        )}
+        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
+        {showReadOnlyCommentPopup && (
+          <CommentDialog editor={editor} pageId={pageId} readOnly />
+        )}
+      </div>
+      <div
+        onClick={() => {
+          if (editor && !editor.isDestroyed) editor.commands.focus("end");
+        }}
+        style={{ paddingBottom: "20vh" }}
+      ></div>
+    </div>
+  );
+}
+
+function StaticPageEditor({
+  content,
+  ariaLabel,
+}: {
+  content: any;
+  ariaLabel: string;
+}) {
+  return (
+    <EditorProvider
+      editable={false}
+      immediatelyRender={true}
+      extensions={mainExtensions}
+      content={content}
+      editorProps={{
+        attributes: {
+          "aria-label": ariaLabel,
+        },
+      }}
+    />
  );
 }
@@ -0,0 +1,26 @@
+.ProseMirror sup a.footnote-ref {
+  color: var(--mantine-primary-color-filled);
+  text-decoration: none;
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.ProseMirror sup:has(a.footnote-ref) {
+  padding: 0 1px;
+}
+
+.ProseMirror ol.footnotes {
+  margin-top: 2rem;
+  padding-top: 0.75rem;
+  font-size: 0.875rem;
+  color: var(--mantine-color-dimmed);
+  list-style-type: decimal;
+}
+
+.ProseMirror ol.footnotes:has(li) {
+  border-top: 1px solid var(--mantine-color-default-border);
+}
+
+.ProseMirror ol.footnotes li p {
+  margin: 0.15rem 0;
+}
@@ -18,3 +18,4 @@
@import "./columns.css";
@import "./status.css";
@import "./base-embed.css";
+@import "./footnotes.css";
@@ -1,13 +1,10 @@
 import { ForgotPasswordForm } from "@/features/auth/components/forgot-password-form";
-import { getAppName } from "@/lib/config";
-import { Helmet } from "react-helmet-async";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function ForgotPassword() {
    return (
        <>
-            <Helmet>
-                <title>Forgot Password - {getAppName()}</title>
-            </Helmet>
+            <DocumentTitle title="Forgot Password" />
            <ForgotPasswordForm />
        </>
    );
@@ -1,16 +1,13 @@
-import { Helmet } from "react-helmet-async";
 import { InviteSignUpForm } from "@/features/auth/components/invite-sign-up-form.tsx";
-import {getAppName} from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function InviteSignup() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>{t("Invitation Signup")} - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title={t("Invitation Signup")} />
      <InviteSignUpForm />
    </>
  );
@@ -1,18 +1,13 @@
 import { LoginForm } from "@/features/auth/components/login-form";
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function LoginPage() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Login")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Login")} />
      <LoginForm />
    </>
  );
@@ -1,11 +1,10 @@
-import { Helmet } from "react-helmet-async";
 import { PasswordResetForm } from "@/features/auth/components/password-reset-form";
 import { Link, useSearchParams } from "react-router-dom";
 import { useVerifyUserTokenQuery } from "@/features/auth/queries/auth-query";
 import { Button, Container, Group, Text } from "@mantine/core";
 import APP_ROUTE from "@/lib/app-route";
-import { getAppName } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function PasswordReset() {
  const { t } = useTranslation();
@@ -23,11 +22,7 @@ export default function PasswordReset() {
  if (isError || !resetToken) {
    return (
      <>
-        <Helmet>
-          <title>
-            {t("Password Reset")} - {getAppName()}
-          </title>
-        </Helmet>
+        <DocumentTitle title={t("Password Reset")} />
        <Container my={40}>
          <Text size="lg" ta="center">
            {t("Invalid or expired password reset link")}
@@ -49,11 +44,7 @@ export default function PasswordReset() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Password Reset")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Password Reset")} />
      <PasswordResetForm resetToken={resetToken} />
    </>
  );
@@ -1,11 +1,10 @@
 import { useWorkspacePublicDataQuery } from "@/features/workspace/queries/workspace-query.ts";
 import { SetupWorkspaceForm } from "@/features/auth/components/setup-workspace-form.tsx";
-import { Helmet } from "react-helmet-async";
 import React, { useEffect } from "react";
 import { useNavigate } from "react-router-dom";
 import APP_ROUTE from "@/lib/app-route.ts";
-import { getAppName } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function SetupWorkspace() {
  const { t } = useTranslation();
@@ -35,11 +34,7 @@ export default function SetupWorkspace() {
  ) {
    return (
      <>
-        <Helmet>
-          <title>
-            {t("Setup Workspace")} - {getAppName()}
-          </title>
-        </Helmet>
+        <DocumentTitle title={t("Setup Workspace")} />
        <SetupWorkspaceForm />
      </>
    );
@@ -2,20 +2,15 @@ import { Container, Space } from "@mantine/core";
 import HomeTabs from "@/features/home/components/home-tabs";
 import HomeAiPrompt from "@/features/home/components/home-ai-prompt";
 import SpaceCarousel from "@/features/space/components/space-carousel.tsx";
-import { getAppName } from "@/lib/config.ts";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Home() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Home")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Home")} />
      <Container size={"900"} pt="xl">
        <HomeAiPrompt />

@@ -17,9 +17,7 @@ import {
 } from "@tabler/icons-react";
 import { Link, useParams } from "react-router-dom";
 import { useTranslation } from "react-i18next";
-import { Helmet } from "react-helmet-async";
 import { useDebouncedValue } from "@mantine/hooks";
-import { getAppName } from "@/lib/config";
 import { useLabelPagesQuery } from "@/features/label/queries/label-query.ts";
 import { useGetSpacesQuery } from "@/features/space/queries/space-query.ts";
 import { getLabelColor } from "@/features/label/utils/label-colors.ts";
@@ -29,6 +27,7 @@ import { normalizeLabelName } from "@/features/label/utils/normalize-label.ts";
 import { SpaceFilterMenu } from "@/features/space/components/space-filter-menu.tsx";
 import { EmptyState } from "@/components/ui/empty-state";
 import classes from "@/features/label/label.module.css";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function LabelPage() {
  const { t } = useTranslation();
@@ -82,11 +81,7 @@ export default function LabelPage() {

  return (
    <>
-      <Helmet>
-        <title>
-          {labelName} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={labelName} />

      <Container size={820} py="xl">
        <Stack gap="lg">
@@ -3,7 +3,6 @@ import { usePageQuery } from "@/features/page/queries/page-query";
 import { FullEditor } from "@/features/editor/full-editor";
 import { TitleEditor } from "@/features/editor/title-editor";
 import HistoryModal from "@/features/page-history/components/history-modal";
-import { Helmet } from "react-helmet-async";
 import PageHeader from "@/features/page/components/header/page-header.tsx";
 import { extractPageSlugId } from "@/lib";
 import { useGetSpaceBySlugQuery } from "@/features/space/queries/space-query.ts";
@@ -18,6 +17,7 @@ import { BaseView } from "@/ee/base/components/base-view";
 import { useHasFeature } from "@/ee/hooks/use-feature";
 import { Feature } from "@/ee/features";
 import { getPageTitle } from "@/features/page/page.utils";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";
 const MemoizedFullEditor = React.memo(FullEditor);
 const MemoizedTitleEditor = React.memo(TitleEditor);
 const MemoizedPageHeader = React.memo(PageHeader);
@@ -110,9 +110,10 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
          paddingTop: "calc(var(--page-header-height) + 6px)",
        }}
      >
-        <Helmet>
-          <title>{`${page?.icon || ""}  ${getPageTitle(page?.title, page?.isBase, t)}`}</title>
-        </Helmet>
+        <DocumentTitle
+          title={`${page?.icon || ""}  ${getPageTitle(page?.title, page?.isBase, t)}`}
+          withAppName={false}
+        />
        <MemoizedPageHeader readOnly={!canEdit} />
        <div
          style={{
@@ -159,9 +160,10 @@ function PageContent({ pageSlug }: { pageSlug: string | undefined }) {
  return (
    page && (
      <div>
-        <Helmet>
-          <title>{`${page?.icon || ""}  ${getPageTitle(page?.title, page?.isBase, t)}`}</title>
-        </Helmet>
+        <DocumentTitle
+          title={`${page?.icon || ""}  ${getPageTitle(page?.title, page?.isBase, t)}`}
+          withAppName={false}
+        />

        <MemoizedPageHeader readOnly={!canEdit} />

@@ -5,21 +5,16 @@ import PageWidthPref from "@/features/user/components/page-width-pref.tsx";
 import PageEditPref from "@/features/user/components/page-state-pref";
 import FixedToolbarPref from "@/features/user/components/fixed-toolbar-pref";
 import NotificationPref from "@/features/user/components/notification-pref";
-import { getAppName } from "@/lib/config.ts";
 import { Divider } from "@mantine/core";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function AccountPreferences() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Preferences")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Preferences")} />
      <SettingsTitle title={t("Preferences")} />

      <AccountTheme />
@@ -4,22 +4,17 @@ import ChangePassword from "@/features/user/components/change-password";
 import { Divider } from "@mantine/core";
 import AccountAvatar from "@/features/user/components/account-avatar";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
-import { getAppName } from "@/lib/config.ts";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { AccountMfaSection } from "@/features/user/components/account-mfa-section";
 import SessionList from "@/features/session/components/session-list";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function AccountSettings() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("My Profile")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("My Profile")} />
      <SettingsTitle title={t("My Profile")} />

      <AccountAvatar />
@@ -1,20 +1,15 @@
 import SettingsTitle from "@/components/settings/settings-title.tsx";
 import GroupMembersList from "@/features/group/components/group-members";
 import GroupDetails from "@/features/group/components/group-details";
-import { getAppName } from "@/lib/config.ts";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function GroupInfo() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Manage Group")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Manage Group")} />
      <SettingsTitle title={t("Manage Group")} />
      <GroupDetails />
      <GroupMembersList />
@@ -3,9 +3,8 @@ import SettingsTitle from "@/components/settings/settings-title.tsx";
 import { Group } from "@mantine/core";
 import CreateGroupModal from "@/features/group/components/create-group-modal";
 import useUserRole from "@/hooks/use-user-role.tsx";
-import {getAppName} from "@/lib/config.ts";
-import {Helmet} from "react-helmet-async";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Groups() {
  const { t } = useTranslation();
@@ -13,9 +12,7 @@ export default function Groups() {

  return (
    <>
-        <Helmet>
-            <title>{t("Groups")} - {getAppName()}</title>
-        </Helmet>
+      <DocumentTitle title={t("Groups")} />
      <SettingsTitle title={t("Groups")} />

      <Group my="md" justify="flex-end">
@@ -1,22 +1,17 @@
 import SettingsTitle from "@/components/settings/settings-title.tsx";
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
 import ShareList from "@/features/share/components/share-list.tsx";
 import { Alert, Text } from "@mantine/core";
 import { IconInfoCircle } from "@tabler/icons-react";
 import React from "react";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Shares() {
  const { t } = useTranslation();

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Public sharing")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Public sharing")} />
      <SettingsTitle title={t("Public sharing")} />

      <Alert variant="light" color="blue" icon={<IconInfoCircle />}>
@@ -3,9 +3,8 @@ import SpaceList from "@/features/space/components/space-list.tsx";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import { Group } from "@mantine/core";
 import CreateSpaceModal from "@/features/space/components/create-space-modal.tsx";
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config.ts";
 import { useTranslation } from "react-i18next";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Spaces() {
  const { t } = useTranslation();
@@ -13,11 +12,7 @@ export default function Spaces() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Spaces")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Spaces")} />
      <SettingsTitle title={t("Spaces")} />

      <Group my="md" justify="flex-end">
@@ -6,11 +6,10 @@ import { useEffect, useState } from "react";
 import { useNavigate, useSearchParams } from "react-router-dom";
 import WorkspaceInvitesTable from "@/features/workspace/components/members/components/workspace-invites-table.tsx";
 import useUserRole from "@/hooks/use-user-role.tsx";
-import { getAppName } from "@/lib/config.ts";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { useAtom } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function WorkspaceMembers() {
  const { t } = useTranslation();
@@ -38,11 +37,7 @@ export default function WorkspaceMembers() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Members")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Members")} />
      <SettingsTitle title={t("Members")} />

      {/* <WorkspaceInviteSection /> */}
@@ -2,21 +2,19 @@ import SettingsTitle from "@/components/settings/settings-title.tsx";
 import WorkspaceNameForm from "@/features/workspace/components/settings/components/workspace-name-form";
 import WorkspaceIcon from "@/features/workspace/components/settings/components/workspace-icon.tsx";
 import { useTranslation } from "react-i18next";
-import { getAppName, isCloud } from "@/lib/config.ts";
-import { Helmet } from "react-helmet-async";
+import { isCloud } from "@/lib/config.ts";
 import ManageHostname from "@/ee/components/manage-hostname.tsx";
 import { Divider } from "@mantine/core";
 import AllowMemberTemplates from "@/ee/security/components/allow-member-templates.tsx";
 import WorkspaceDefaultPageEditMode from "@/features/workspace/components/settings/components/workspace-default-page-edit-mode.tsx";
 import PersonalSpacesSetting from "@/ee/personal-space/components/personal-spaces-setting.tsx";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function WorkspaceSettings() {
  const { t } = useTranslation();
  return (
    <>
-      <Helmet>
-        <title>Workspace Settings - {getAppName()}</title>
-      </Helmet>
+      <DocumentTitle title="Workspace Settings" />
      <SettingsTitle title={t("General")} />
      <WorkspaceIcon />
      <WorkspaceNameForm />
@@ -1,5 +1,4 @@
 import { useNavigate, useParams } from "react-router-dom";
-import { Helmet } from "react-helmet-async";
 import { useTranslation } from "react-i18next";
 import { useSharePageQuery } from "@/features/share/queries/share-query.ts";
 import { Container } from "@mantine/core";
@@ -14,6 +13,7 @@ import {
  sharedTreeDataAtom,
 } from "@/features/share/atoms/shared-page-atom.ts";
 import { isPageInTree } from "@/features/share/utils.ts";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function SharedPage() {
  const { t } = useTranslation();
@@ -56,12 +56,14 @@ export default function SharedPage() {

  return (
    <div>
-      <Helmet>
-        <title>{`${data?.page?.title || t("untitled")}`}</title>
+      <DocumentTitle
+        title={data?.page?.title || t("untitled")}
+        withAppName={false}
+      >
        {!data?.share.searchIndexing && (
          <meta name="robots" content="noindex" />
        )}
-      </Helmet>
+      </DocumentTitle>

      <Container fluid={fullWidth} size={fullWidth ? undefined : 900} p={0}>
        <ReadonlyPageEditor
@@ -2,8 +2,7 @@ import {Container} from "@mantine/core";
 import SpaceHomeTabs from "@/features/space/components/space-home-tabs.tsx";
 import {useParams} from "react-router-dom";
 import {useGetSpaceBySlugQuery} from "@/features/space/queries/space-query.ts";
-import {getAppName} from "@/lib/config.ts";
-import {Helmet} from "react-helmet-async";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function SpaceHome() {
    const {spaceSlug} = useParams();
@@ -11,9 +10,7 @@ export default function SpaceHome() {

    return (
        <>
-            <Helmet>
-                <title>{space?.name || 'Overview'} - {getAppName()}</title>
-            </Helmet>
+            <DocumentTitle title={space?.name || 'Overview'} />
            <Container size={"900"} pt="xl">
                {space && <SpaceHomeTabs/>}
            </Container>
@@ -1,13 +1,12 @@
 import { Container, Title, Text, Group, Box } from "@mantine/core";
 import { useTranslation } from "react-i18next";
-import { Helmet } from "react-helmet-async";
-import { getAppName } from "@/lib/config";
 import { useGetSpacesQuery } from "@/features/space/queries/space-query";
 import CreateSpaceModal from "@/features/space/components/create-space-modal";
 import { AllSpacesList } from "@/features/space/components/spaces-page";
 import FavoriteSpacesGrid from "@/features/space/components/spaces-page/favorite-spaces-grid";
 import { usePaginateAndSearch } from "@/hooks/use-paginate-and-search";
 import useUserRole from "@/hooks/use-user-role";
+import { DocumentTitle } from "@/components/ui/document-title.tsx";

 export default function Spaces() {
  const { t } = useTranslation();
@@ -22,11 +21,7 @@ export default function Spaces() {

  return (
    <>
-      <Helmet>
-        <title>
-          {t("Spaces")} - {getAppName()}
-        </title>
-      </Helmet>
+      <DocumentTitle title={t("Spaces")} />

      <Container size={"800"} pt="xl">
        <Group justify="space-between" mb="xl">
@@ -40,30 +40,30 @@
    "@clickhouse/client": "1.18.2",
    "@docmost/base-formula": "workspace:*",
    "@docmost/pdf-inspector": "1.9.6",
-    "@fastify/cookie": "^11.0.2",
-    "@fastify/multipart": "^10.0.0",
-    "@fastify/static": "^9.1.3",
-    "@keyv/redis": "^5.1.6",
+    "@fastify/cookie": "11.0.2",
+    "@fastify/multipart": "10.0.0",
+    "@fastify/static": "10.1.2",
+    "@keyv/redis": "5.1.6",
    "@langchain/core": "1.1.46",
    "@langchain/textsplitters": "1.0.1",
-    "@modelcontextprotocol/sdk": "1.29.0",
-    "@nest-lab/throttler-storage-redis": "^1.2.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@nest-lab/throttler-storage-redis": "1.2.0",
    "@nestjs-labs/nestjs-ioredis": "11.0.4",
    "@nestjs/bullmq": "11.0.4",
    "@nestjs/cache-manager": "3.1.3",
-    "@nestjs/common": "11.1.27",
+    "@nestjs/common": "11.1.28",
    "@nestjs/config": "4.0.4",
    "@nestjs/core": "11.1.27",
    "@nestjs/event-emitter": "3.1.0",
    "@nestjs/jwt": "11.0.2",
    "@nestjs/mapped-types": "2.1.1",
    "@nestjs/passport": "11.0.5",
-    "@nestjs/platform-fastify": "11.1.27",
-    "@nestjs/platform-socket.io": "11.1.27",
+    "@nestjs/platform-fastify": "11.1.28",
+    "@nestjs/platform-socket.io": "11.1.28",
    "@nestjs/schedule": "6.1.3",
    "@nestjs/terminus": "11.1.1",
    "@nestjs/throttler": "6.5.0",
-    "@nestjs/websockets": "11.1.27",
+    "@nestjs/websockets": "11.1.28",
    "@node-saml/passport-saml": "5.1.0",
    "@socket.io/redis-adapter": "8.3.0",
    "ai": "6.0.134",
@@ -88,11 +88,10 @@
    "kysely-migration-cli": "0.4.2",
    "kysely-postgres-js": "3.0.0",
    "ldapts": "8.1.7",
-    "lib0": "0.2.117",
    "mammoth": "1.12.0",
    "mime-types": "3.0.2",
-    "msgpackr": "^1.11.9",
-    "nanoid": "5.1.7",
+    "msgpackr": "1.11.9",
+    "nanoid": "5.1.16",
    "nestjs-cls": "6.2.0",
    "nestjs-kysely": "3.1.2",
    "nestjs-pino": "4.6.1",
@@ -103,7 +102,7 @@
    "passport-google-oauth20": "2.0.0",
    "passport-jwt": "4.0.1",
    "pg-tsquery": "8.4.2",
-    "pgvector": "^0.2.1",
+    "pgvector": "0.2.1",
    "pino-http": "11.0.0",
    "pino-pretty": "13.1.3",
    "postgres": "3.4.8",
@@ -118,9 +117,8 @@
    "stripe": "^17.7.0",
    "tlds": "1.261.0",
    "tmp-promise": "3.0.3",
-    "tseep": "1.3.1",
    "typesense": "3.0.5",
-    "undici": "7.28.0",
+    "undici": "7.29.0",
    "ws": "8.21.0",
    "yauzl": "3.4.0",
    "zod": "4.3.6"
@@ -15,6 +15,7 @@ import {
  RedisSyncExtension,
  SerializedHTTPRequest,
 } from './extensions/redis-sync';
+import { toWebRequest } from './extensions/redis-sync/redis-sync.types';
 import { WsSocketWrapper } from './extensions/redis-sync/ws-socket-wrapper';
 import RedisClient from 'ioredis';
 import { pack, unpack } from 'msgpackr';
@@ -98,34 +99,36 @@ export class CollaborationGateway {
      const serializedHTTPRequest = this.serializeRequest(request);
      const socketId = serializedHTTPRequest.headers['sec-websocket-key'];

-      // Create wrapper socket that only receives events via emit()
-      // This prevents double-handling since Hocuspocus won't listen to raw WebSocket events
      const wrappedSocket = new WsSocketWrapper(client);

      // Route through RedisSync extension (this calls handleConnection internally)
-      this.redisSync.onSocketOpen(wrappedSocket as any, serializedHTTPRequest);
+      this.redisSync.onSocketOpen(wrappedSocket, serializedHTTPRequest);

-      // Forward raw WebSocket messages to the extension
      client.on('message', (data: ArrayBuffer) => {
-        this.redisSync!.onSocketMessage(
-          wrappedSocket as any,
-          serializedHTTPRequest,
-          data,
-        );
+        this.redisSync!.onSocketMessage(serializedHTTPRequest, data);
      });

-      // Forward close events
      client.on('close', (code: number, reason: Buffer) => {
-        this.redisSync!.onSocketClose(socketId, code, reason.buffer as ArrayBuffer);
-      });
-
-      // Forward pong events for keepalive
-      client.on('pong', (data: Buffer) => {
-        wrappedSocket.emit('pong', data);
+        this.redisSync!.onSocketClose(
+          socketId,
+          code,
+          new Uint8Array(reason).buffer,
+        );
      });
    } else {
      // Fallback to direct Hocuspocus connection
-      this.hocuspocus.handleConnection(client, request);
+      const clientConnection = this.hocuspocus.handleConnection(
+        client,
+        toWebRequest(this.serializeRequest(request)),
+      );
+
+      client.on('message', (data: Buffer) => {
+        clientConnection.handleMessage(new Uint8Array(data));
+      });
+
+      client.on('close', (code: number, reason: Buffer) => {
+        clientConnection.handleClose({ code, reason: reason.toString() });
+      });
    }
  }

@@ -178,6 +181,7 @@ export class CollaborationGateway {

        if (this.hocuspocus.getDocumentsCount() === 0) resolve('');
        this.hocuspocus.closeConnections();
+        this.hocuspocus.flushPendingStores();
      } catch (error) {
        console.error(error);
      }
@@ -1,4 +1,5 @@
 import { StarterKit } from '@tiptap/starter-kit';
+import { Document } from '@tiptap/extension-document';
 import { TextAlign } from '@tiptap/extension-text-align';
 import { Superscript } from '@tiptap/extension-superscript';
 import SubScript from '@tiptap/extension-subscript';
@@ -45,6 +46,9 @@ import {
  TransclusionSource,
  TransclusionReference,
  BaseEmbed,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -58,11 +62,15 @@ import { Logger } from '@nestjs/common';

 export const tiptapExtensions = [
  StarterKit.configure({
+    document: false,
    codeBlock: false,
    link: false,
    trailingNode: false,
    heading: false,
  }),
+  Document.extend({
+    content: 'block+ footnotes?',
+  }),
  Heading,
  UniqueID.configure({
    types: ['heading', 'paragraph', 'transclusionSource'],
@@ -110,7 +118,10 @@ export const tiptapExtensions = [
  Status,
  TransclusionSource,
  TransclusionReference,
-  BaseEmbed
+  BaseEmbed,
+  Footnotes,
+  Footnote,
+  FootnoteReference,
 ] as any;

 export function jsonToHtml(tiptapJson: any) {
@@ -96,7 +96,7 @@ export class PersistenceExtension implements Extension {
  }

  async onStoreDocument(data: onStoreDocumentPayload) {
-    const { documentName, document, context } = data;
+    const { documentName, document, lastContext } = data;

    const pageId = getPageId(documentName);

@@ -151,7 +151,7 @@ export class PersistenceExtension implements Extension {
            content: tiptapJson,
            textContent: textContent,
            ydoc: ydocState,
-            lastUpdatedById: context.user.id,
+            lastUpdatedById: lastContext.user.id,
            contributorIds: contributorIds,
          },
          pageId,
@@ -169,12 +169,12 @@ export class PersistenceExtension implements Extension {
        JSON.stringify({
          type: 'page.updated',
          updatedAt: new Date().toISOString(),
-          lastUpdatedById: context?.user?.id,
-          lastUpdatedBy: context?.user
+          lastUpdatedById: lastContext?.user?.id,
+          lastUpdatedBy: lastContext?.user
            ? {
-                id: context.user?.id,
-                name: context.user?.name,
-                avatarUrl: context.user?.avatarUrl,
+                id: lastContext.user?.id,
+                name: lastContext.user?.name,
+                avatarUrl: lastContext.user?.avatarUrl,
              }
            : undefined,
        }),
@@ -1,61 +1,37 @@
 import type RedisClient from 'ioredis';
-import { EventEmitter } from 'tseep';
-import type {
-  Pack,
-  RSAMessageClose,
-  RSAMessagePing,
-  RSAMessageSend,
-} from './redis-sync.types';
+import type { WebSocketLike } from '@hocuspocus/server';
+import type { Pack, RSAMessageClose, RSAMessageSend } from './redis-sync.types';

-export class CollabProxySocket extends EventEmitter {
+// Stands in for the client WebSocket on the server that owns the document.
+// Outgoing traffic is relayed over redis to the origin server, which holds the real socket.
+export class CollabProxySocket implements WebSocketLike {
  private readonly replyTo: string;
-  private readonly serverChannel: string;
  private readonly socketId: string;
  private pub: RedisClient;
  private readonly pack: Pack;
  readyState = 1;
+  onClose?: (code?: number, reason?: string) => void;

-  constructor(
-    pub: RedisClient,
-    pack: Pack,
-    replyTo: string,
-    serverChannel: string,
-    socketId: string,
-  ) {
-    super();
+  constructor(pub: RedisClient, pack: Pack, replyTo: string, socketId: string) {
    this.replyTo = replyTo;
    this.socketId = socketId;
-    this.serverChannel = serverChannel;
    this.pub = pub;
    this.pack = pack;
-    this.once('close', () => {
-      this.readyState = 3;
-    });
  }

-  private publish(msg: RSAMessageClose | RSAMessagePing | RSAMessageSend) {
+  private publish(msg: RSAMessageClose | RSAMessageSend) {
    this.pub.publish(this.replyTo, this.pack(msg));
  }

+  // The origin server already closed the real socket; stop relaying without echoing a close back
+  markClosed() {
+    this.readyState = 3;
+  }
+
  close(code?: number, reason?: string) {
    if (this.readyState !== 1) return;
-    const msg: RSAMessageClose = {
-      type: 'close',
-      code,
-      reason,
-      socketId: this.socketId,
-    };
-    this.publish(msg);
-  }
-
-  ping() {
-    if (this.readyState !== 1) return;
-    const msg: RSAMessagePing = {
-      type: 'ping',
-      socketId: this.socketId,
-      replyTo: this.serverChannel,
-    };
-    this.publish(msg);
+    this.readyState = 3;
+    this.onClose?.(code, reason);
  }

  send(message: Uint8Array) {
@@ -3,27 +3,30 @@ import {
  Extension,
  Hocuspocus,
  IncomingMessage,
-  afterUnloadDocumentPayload,
  onConfigurePayload,
  onLoadDocumentPayload,
+  afterUnloadDocumentPayload,
+  WebSocketLike,
 } from '@hocuspocus/server';
+import { ConnectionTimeout, Unauthorized } from '@hocuspocus/common';
 import RedisClient from 'ioredis';
-import { readVarString } from 'lib0/decoding.js';
 import { CollabProxySocket } from './collab-proxy-socket';
 import {
-  BaseWebSocket,
  Configuration,
  CustomEvents,
  Pack,
  RSAMessage,
+  RSAMessageClose,
  RSAMessageCloseProxy,
  RSAMessageCustomEventComplete,
  RSAMessageCustomEventStart,
-  RSAMessagePong,
  RSAMessageProxy,
  RSAMessageUnload,
  SerializedHTTPRequest,
  Unpack,
+  OriginConnection,
+  ProxyConnection,
+  toWebRequest,
 } from './redis-sync.types';

 export type { Pack, SerializedHTTPRequest } from './redis-sync.types';
@@ -38,10 +41,10 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
  private sub: RedisClient;
  private readonly pack: Pack;
  private readonly unpack: Unpack;
-  private originSockets: Record<SocketId, BaseWebSocket> = {};
+  private originConnections: Record<SocketId, OriginConnection> = {};
  private locks: Record<DocumentName, NodeJS.Timeout> = {};
  private lockPromises: Record<DocumentName, Promise<ServerId | null>> = {};
-  private proxySockets: Record<SocketId, CollabProxySocket> = {};
+  private proxyConnections: Record<SocketId, ProxyConnection> = {};
  private readonly prefix: string;
  private readonly lockPrefix: string;
  private readonly msgChannel: string;
@@ -54,6 +57,9 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
  // @ts-ignore
  private pendingReplies: Record<number, PromiseWithResolvers<any>['resolve']> =
    {};
+  private deriveContext: (
+    serializedHTTPRequest: SerializedHTTPRequest,
+  ) => Record<string, any>;

  constructor(configuration: Configuration<TCE>) {
    const {
@@ -65,6 +71,7 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      prefix,
      customEvents,
      customEventTTL,
+      deriveContext,
    } = configuration;
    this.pub = redis.duplicate();
    this.sub = redis.duplicate();
@@ -77,6 +84,7 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
    this.lockPrefix = `${this.prefix}Lock`;
    this.msgChannel = `${this.prefix}Msg`;
    this.customEvents = (customEvents as any) ?? ({} as any as CustomEvents);
+    this.deriveContext = deriveContext ?? (() => ({}));
    this.sub.subscribe(this.msgChannel, `${this.msgChannel}:${this.serverId}`);
    this.sub.on('messageBuffer', this.handleRedisMessage);
    this.pub.on('error', () => {});
@@ -87,44 +95,63 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
  }

  private closeProxy(socketId: string) {
-    const proxySocket = this.proxySockets[socketId];
-    if (proxySocket) {
-      proxySocket.emit(
-        'close',
-        1000,
-        Buffer.from('provider_initiated', 'utf-8'),
-      );
-      delete this.proxySockets[socketId];
+    const entry = this.proxyConnections[socketId];
+    if (entry) {
+      delete this.proxyConnections[socketId];
+      const { socket, clientConnection } = entry;
+      // The origin socket is already gone; don't echo a close message back
+      socket.markClosed();
+      clientConnection.handleClose({
+        code: 1000,
+        reason: 'provider_initiated',
+      });
    }
  }

-  private pongProxy(socketId: string) {
-    this.proxySockets[socketId]?.emit('pong');
-  }
-
  private handleProxyMessage(
    msg: Pick<RSAMessageProxy, 'replyTo' | 'message' | 'serializedHTTPRequest'>,
  ) {
    const { replyTo, message, serializedHTTPRequest } = msg;
    const { headers } = serializedHTTPRequest;
-    const socketId = headers['sec-websocket-key']!;
-    let socket = this.proxySockets[socketId];
-    if (!socket) {
-      socket = new CollabProxySocket(
+    const socketId = headers['sec-websocket-key'];
+    let entry = this.proxyConnections[socketId];
+    if (!entry) {
+      const socket = new CollabProxySocket(
        this.pub,
        this.pack,
        replyTo,
-        `${this.msgChannel}:${this.serverId}`,
        socketId,
      );
-      this.proxySockets[socketId] = socket;
-      this.instance.handleConnection(
-        socket as any,
-        serializedHTTPRequest as any,
-        {},
+      // A proxy connection with no live documents (client left the page, auth
+      // failed, or the origin server crashed) is reaped by hocuspocus' message
+      // timeout. Dispose it silently in that case: relaying the timeout close
+      // to the origin would kill the client's real socket, which may be busy
+      // serving other documents. Genuine protocol closes are still relayed.
+      socket.onClose = (code, reason) => {
+        delete this.proxyConnections[socketId];
+        if (code !== ConnectionTimeout.code) {
+          const msg: RSAMessageClose = {
+            type: 'close',
+            code,
+            reason,
+            socketId,
+          };
+          this.pub.publish(replyTo, this.pack(msg));
+        }
+      };
+      const clientConnection = this.instance.handleConnection(
+        socket,
+        toWebRequest(serializedHTTPRequest),
+        this.deriveContext(serializedHTTPRequest),
      );
+      entry = { clientConnection, socket };
+      this.proxyConnections[socketId] = entry;
    }
-    socket.emit('message', message);
+    entry.clientConnection.handleMessage(message);
+  }
+
+  private getLock(documentName: string) {
+    return this.pub.get(this.getKey(documentName));
  }

  private getOrClaimLock(documentName: string) {
@@ -166,10 +193,6 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      this.closeProxy(msg.socketId);
      return;
    }
-    if (type === 'pong') {
-      this.pongProxy(msg.socketId);
-      return;
-    }
    if (type === 'unload') {
      delete this.lockPromises[msg.documentName];
      return;
@@ -198,22 +221,14 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      return;
    }
    const { socketId } = msg;
-    const socket = this.originSockets[socketId];
-    if (!socket) {
+    const entry = this.originConnections[socketId];
+    if (!entry) {
      // origin socket already cleaned up
      return;
    }
+    const { socket } = entry;
    if (type === 'close') {
      socket.close(msg.code, msg.reason);
-    } else if (type === 'ping') {
-      // Reply instantly to the proxy socket, without forwarding to client
-      // The origin socket handles heartbeat for itself
-      const { replyTo, socketId } = msg;
-      const reply: RSAMessagePong = {
-        type: 'pong',
-        socketId,
-      };
-      this.pub.publish(`${replyTo}`, this.pack(reply));
    } else if (type === 'send') {
      socket.send(msg.message);
    }
@@ -251,6 +266,8 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
    eventName: TName,
    documentName: string,
    payload: any,
+    // if true, don't claim the lock. Useful for targeting pages that are currently open
+    onlyIfOpen = false,
  ) {
    const isDocLoadedOnInstance = this.instance.documents.has(documentName);

@@ -258,7 +275,14 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      return this.handleEventLocally(eventName, documentName, payload);
    }

-    const proxyTo = await this.getOrClaimLockThrottled(documentName);
+    const proxyTo = await (onlyIfOpen
+      ? this.getLock(documentName)
+      : this.getOrClaimLockThrottled(documentName));
+
+    if (!proxyTo && onlyIfOpen) {
+      return;
+    }
+
    if (proxyTo && proxyTo !== this.serverId) {
      ++this.replyIdCounter; // bug in biome thinks this.replyIdCounter is not used if written on the line below
      const replyId = this.replyIdCounter;
@@ -277,7 +301,8 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      const { promise, resolve, reject } = Promise.withResolvers();
      this.pendingReplies[replyId] = resolve;
      setTimeout(() => {
-        reject('TIMEOUT');
+        delete this.pendingReplies[replyId];
+        reject(new Error('TIMEOUT'));
      }, this.customEventTTL);
      return promise as Promise<ReturnType<TCE[TName]>>;
    }
@@ -296,36 +321,59 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {

  /* WebSocket Server Hooks */
  onSocketOpen(
-    ws: BaseWebSocket,
+    ws: WebSocketLike,
    serializedHTTPRequest: SerializedHTTPRequest,
-    context = {},
  ) {
-    const socketId = serializedHTTPRequest.headers['sec-websocket-key']!;
-    this.originSockets[socketId] = ws;
-    this.instance.handleConnection(
-      ws as any,
-      serializedHTTPRequest as any,
-      context,
+    const socketId = serializedHTTPRequest.headers['sec-websocket-key'];
+    const clientConnection = this.instance.handleConnection(
+      ws,
+      toWebRequest(serializedHTTPRequest),
+      this.deriveContext(serializedHTTPRequest),
    );
+    this.originConnections[socketId] = { clientConnection, socket: ws };
  }

  async onSocketMessage(
-    ws: BaseWebSocket,
    serializedHTTPRequest: SerializedHTTPRequest,
    detachableMsg: ArrayBuffer,
  ) {
-    const message = new Uint8Array(detachableMsg.slice());
-    const tmpMsg = new IncomingMessage(detachableMsg);
-    const documentName = readVarString(tmpMsg.decoder);
+    const socketId = serializedHTTPRequest.headers['sec-websocket-key'];
+    const entry = this.originConnections[socketId];
+    if (!entry) return;
+    const { clientConnection } = entry;
+
+    let message: Uint8Array;
+    let documentName: string;
+    try {
+      message = new Uint8Array(detachableMsg.slice());
+      const tmpMsg = new IncomingMessage(detachableMsg);
+      const documentNameAndSessionId = tmpMsg.readVarString();
+      // session-aware providers suffix the documentName with \0sessionId
+      const sepIdx = documentNameAndSessionId.indexOf('\0');
+      documentName =
+        sepIdx === -1
+          ? documentNameAndSessionId
+          : documentNameAndSessionId.slice(0, sepIdx);
+    } catch (error) {
+      entry.socket.close(Unauthorized.code, Unauthorized.reason);
+      return;
+    }
    const isDocLoadedOnInstance = this.instance.documents.has(documentName);

    if (isDocLoadedOnInstance) {
-      ws.emit('message', message);
+      clientConnection.handleMessage(message);
      return;
    }

    const proxyTo = await this.getOrClaimLockThrottled(documentName);
    if (proxyTo && proxyTo !== this.serverId) {
+      // Proxied messages bypass handleMessage, so refresh the connection's
+      // liveness fields manually or hocuspocus' message timeout would reap the
+      // real socket every `timeout` ms. connectionEstablishedAt is the
+      // reference while unauthenticated (auth for remote docs is proxied too)
+      // and is private upstream.
+      clientConnection.lastMessageReceivedAt = Date.now();
+      (clientConnection as any).connectionEstablishedAt = Date.now();
      // another server owns the doc
      const proxyMessage: RSAMessageProxy = {
        serializedHTTPRequest: serializedHTTPRequest,
@@ -338,16 +386,17 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
      return;
    }
    // This server owns the document, but hocuspocus hasn't loaded it yet
-    ws.emit('message', message);
+    clientConnection.handleMessage(message);
  }

  onSocketClose(socketId: string, code?: number, reason?: ArrayBuffer) {
-    const socket = this.originSockets[socketId];
-    if (!socket) return;
-    // at this point the socket is considered GC'd and we cannot call close
-    // The origin socket did not set up any connections for the proxy, so none of the hooks will work if we just emit
-    socket?.emit('close', code, reason);
-    delete this.originSockets[socketId];
+    const entry = this.originConnections[socketId];
+    if (!entry) return;
+    delete this.originConnections[socketId];
+    entry.clientConnection.handleClose({
+      code: code ?? 1000,
+      reason: reason ? Buffer.from(reason).toString() : '',
+    });
    const msg: RSAMessageCloseProxy = { type: 'closeProxy', socketId };
    this.pub.publish(this.msgChannel, this.pack(msg)).catch(() => {});
  }
@@ -372,6 +421,7 @@ export class RedisSyncExtension<TCE extends CustomEvents> implements Extension {
  }

  async onDestroy() {
+    this.pendingReplies = {};
    this.pub.disconnect(false);
    this.sub.disconnect(false);
  }
@@ -1,12 +1,13 @@
-import EventEmitter from 'node:events';
 import { IncomingHttpHeaders } from 'node:http2';
 import RedisClient from 'ioredis';
+import { CollabProxySocket } from './collab-proxy-socket';
+import { type Hocuspocus, type WebSocketLike } from '@hocuspocus/server';

 export type SecondParam<T> = T extends (
-  arg1: unknown,
+  arg1: any,
  arg2: infer A,
-  ...args: unknown[]
-) => unknown
+  ...args: any[]
+) => any
  ? A
  : never;

@@ -41,17 +42,6 @@ export type RSAMessageClose = {
  socketId: string;
 };

-export type RSAMessagePing = {
-  type: 'ping';
-  socketId: string;
-  replyTo: string;
-};
-
-export type RSAMessagePong = {
-  type: 'pong';
-  socketId: string;
-};
-
 export type RSAMessageSend = {
  type: 'send';
  // @ts-ignore
@@ -59,7 +49,7 @@ export type RSAMessageSend = {
  socketId: string;
 };

-export type RSAMessageCustomEventStart<TName = string, TPayload = unknown> = {
+export type RSAMessageCustomEventStart<TName = string, TPayload = any> = {
  type: 'customEventStart';
  documentName: string;
  eventName: TName;
@@ -71,7 +61,7 @@ export type RSAMessageCustomEventStart<TName = string, TPayload = unknown> = {
 export type RSAMessageCustomEventComplete = {
  type: 'customEventComplete';
  replyId: number;
-  payload: unknown;
+  payload: any;
 };

 export type RSAMessage =
@@ -79,8 +69,6 @@ export type RSAMessage =
  | RSAMessageCloseProxy
  | RSAMessageUnload
  | RSAMessageClose
-  | RSAMessagePing
-  | RSAMessagePong
  | RSAMessageSend
  | RSAMessageCustomEventStart
  | RSAMessageCustomEventComplete;
@@ -99,9 +87,20 @@ type CustomEventName = string;

 export type CustomEvents = Record<
  CustomEventName,
-  (documentName: string, payload: unknown) => Promise<unknown>
+  (documentName: string, payload: any) => Promise<any>
 >;

+// Not exported by @hocuspocus/server
+export type ClientConnection = ReturnType<Hocuspocus['handleConnection']>;
+export type OriginConnection = {
+  clientConnection: ClientConnection;
+  socket: WebSocketLike;
+};
+export type ProxyConnection = {
+  clientConnection: ClientConnection;
+  socket: CollabProxySocket;
+};
+
 export interface Configuration<TCE> {
  redis: RedisClient;
  pack: Pack;
@@ -111,11 +110,29 @@ export interface Configuration<TCE> {
  customEventTTL?: number;
  prefix?: string;
  customEvents?: TCE;
+  // Derive the hocuspocus context once per socket instead of re-deriving it in a
+  // per-document hook like onConnect/onAuthenticate. Runs on the origin server when
+  // the socket opens and on the doc owner when the first proxied message arrives.
+  deriveContext?: (
+    serializedHTTPRequest: SerializedHTTPRequest,
+  ) => Record<string, any>;
 }

-export type BaseWebSocket = EventEmitter & {
-  readyState: number;
-  close(code?: number, reason?: string): void;
-  ping(): void;
-  send(message: Uint8Array): void;
+// Hocuspocus expects a web-standard Request, so rehydrate one from what crossed the wire
+export const toWebRequest = (serializedHTTPRequest: SerializedHTTPRequest) => {
+  const { method, url, headers } = serializedHTTPRequest;
+  const webHeaders = new Headers();
+  Object.entries(headers).forEach(([name, value]) => {
+    if (Array.isArray(value)) {
+      value.forEach((v) => {
+        webHeaders.append(name, v);
+      });
+    } else if (value !== undefined) {
+      webHeaders.set(name, value);
+    }
+  });
+  return new Request(new URL(url, 'http://localhost'), {
+    method,
+    headers: webHeaders,
+  });
 };
@@ -1,20 +1,17 @@
-import { EventEmitter } from 'events';
 import type WebSocket from 'ws';
+import type { WebSocketLike } from '@hocuspocus/server';

 /**
- * Wrapper around ws WebSocket that only receives events via emit().
- * This prevents double-handling when used with RedisSyncExtension.
+ * Wrapper around ws WebSocket that Hocuspocus only writes to.
+ * Incoming socket events are forwarded separately by the gateway,
+ * which prevents double-handling with RedisSyncExtension.
 */
-export class WsSocketWrapper extends EventEmitter {
+export class WsSocketWrapper implements WebSocketLike {
  private ws: WebSocket;
  readyState = 1;

  constructor(ws: WebSocket) {
-    super();
    this.ws = ws;
-    this.once('close', () => {
-      this.readyState = 3;
-    });
  }

  close(code?: number, reason?: string) {
@@ -27,15 +24,6 @@ export class WsSocketWrapper extends EventEmitter {
    }
  }

-  ping() {
-    if (this.readyState !== 1) return;
-    try {
-      this.ws.ping();
-    } catch (e) {
-      // Socket already closed
-    }
-  }
-
  send(message: Uint8Array) {
    if (this.readyState !== 1) return;
    try {
@@ -810,6 +810,10 @@ export class PageService {
      throw new BadRequestException('Invalid move position');
    }

+    if (dto.parentPageId && dto.parentPageId === dto.pageId) {
+      throw new BadRequestException('A page cannot be its own parent');
+    }
+
    let parentPageId = null;
    if (movedPage.parentPageId === dto.parentPageId) {
      parentPageId = undefined;
@@ -15,13 +15,21 @@ import { getMimeType } from '../../../common/helpers';
 import { Upload } from '@aws-sdk/lib-storage';
 import { Logger } from '@nestjs/common';

+const S3_MAX_SOCKETS = parseInt(process.env.AWS_S3_MAX_SOCKETS) || 200;
+
 export class S3Driver implements StorageDriver {
  private readonly s3Client: S3Client;
  private readonly config: S3StorageConfig;

  constructor(config: S3StorageConfig) {
-    this.config = config;
-    this.s3Client = new S3Client(config as any);
+    this.config = {
+      ...config,
+      requestHandler: {
+        httpAgent: { maxSockets: S3_MAX_SOCKETS },
+        httpsAgent: { maxSockets: S3_MAX_SOCKETS },
+      },
+    };
+    this.s3Client = new S3Client(this.config as any);
  }

  async upload(filePath: string, file: Buffer | Readable): Promise<void> {
@@ -23,47 +23,49 @@
    "@casl/ability": "6.8.0",
    "@docmost/editor-ext": "workspace:*",
    "@floating-ui/dom": "1.7.3",
-    "@hocuspocus/provider": "3.4.4",
-    "@hocuspocus/server": "3.4.4",
-    "@hocuspocus/transformer": "3.4.4",
+    "@hocuspocus/common": "4.5.0",
+    "@hocuspocus/provider": "4.5.0",
+    "@hocuspocus/provider-react": "4.5.0",
+    "@hocuspocus/server": "4.5.0",
+    "@hocuspocus/transformer": "4.5.0",
    "@joplin/turndown": "4.0.82",
    "@joplin/turndown-plugin-gfm": "1.0.64",
    "@sindresorhus/slugify": "3.0.0",
-    "@tiptap/core": "3.27.1",
-    "@tiptap/extension-audio": "3.27.1",
-    "@tiptap/extension-code-block": "3.27.1",
-    "@tiptap/extension-collaboration": "3.27.1",
-    "@tiptap/extension-collaboration-caret": "3.27.1",
-    "@tiptap/extension-color": "3.27.1",
-    "@tiptap/extension-document": "3.27.1",
-    "@tiptap/extension-heading": "3.27.1",
-    "@tiptap/extension-highlight": "3.27.1",
-    "@tiptap/extension-history": "3.27.1",
-    "@tiptap/extension-image": "3.27.1",
-    "@tiptap/extension-link": "3.27.1",
-    "@tiptap/extension-list": "3.27.1",
-    "@tiptap/extension-placeholder": "3.27.1",
-    "@tiptap/extension-subscript": "3.27.1",
-    "@tiptap/extension-superscript": "3.27.1",
-    "@tiptap/extension-table": "3.27.1",
-    "@tiptap/extension-text": "3.27.1",
-    "@tiptap/extension-text-align": "3.27.1",
-    "@tiptap/extension-text-style": "3.27.1",
-    "@tiptap/extension-typography": "3.27.1",
-    "@tiptap/extension-unique-id": "3.27.1",
-    "@tiptap/extension-youtube": "3.27.1",
-    "@tiptap/html": "3.27.1",
-    "@tiptap/pm": "3.27.1",
-    "@tiptap/react": "3.27.1",
-    "@tiptap/starter-kit": "3.27.1",
-    "@tiptap/suggestion": "3.27.1",
-    "@tiptap/y-tiptap": "3.0.5",
+    "@tiptap/core": "3.29.2",
+    "@tiptap/extension-audio": "3.29.2",
+    "@tiptap/extension-code-block": "3.29.2",
+    "@tiptap/extension-collaboration": "3.29.2",
+    "@tiptap/extension-collaboration-caret": "3.29.2",
+    "@tiptap/extension-color": "3.29.2",
+    "@tiptap/extension-document": "3.29.2",
+    "@tiptap/extension-heading": "3.29.2",
+    "@tiptap/extension-highlight": "3.29.2",
+    "@tiptap/extension-history": "3.29.2",
+    "@tiptap/extension-image": "3.29.2",
+    "@tiptap/extension-link": "3.29.2",
+    "@tiptap/extension-list": "3.29.2",
+    "@tiptap/extension-placeholder": "3.29.2",
+    "@tiptap/extension-subscript": "3.29.2",
+    "@tiptap/extension-superscript": "3.29.2",
+    "@tiptap/extension-table": "3.29.2",
+    "@tiptap/extension-text": "3.29.2",
+    "@tiptap/extension-text-align": "3.29.2",
+    "@tiptap/extension-text-style": "3.29.2",
+    "@tiptap/extension-typography": "3.29.2",
+    "@tiptap/extension-unique-id": "3.29.2",
+    "@tiptap/extension-youtube": "3.29.2",
+    "@tiptap/html": "3.29.2",
+    "@tiptap/pm": "3.29.2",
+    "@tiptap/react": "3.29.2",
+    "@tiptap/starter-kit": "3.29.2",
+    "@tiptap/suggestion": "3.29.2",
+    "@tiptap/y-tiptap": "3.0.7",
    "bytes": "3.1.2",
    "cross-env": "10.1.0",
    "date-fns": "4.1.0",
    "diff": "8.0.3",
    "docx": "9.7.1",
-    "dompurify": "3.4.11",
+    "dompurify": "3.4.13",
    "fractional-indexing-jittered": "1.0.0",
    "highlight.js": "11.11.1",
    "image-dimensions": "2.5.0",
@@ -79,12 +81,12 @@
    "yjs": "^13.6.30"
  },
  "devDependencies": {
-    "@nx/js": "22.6.1",
+    "@nx/js": "23.1.1",
    "@types/bytes": "3.1.5",
    "@types/qrcode": "1.5.6",
    "@types/turndown": "5.0.6",
-    "concurrently": "9.2.3",
-    "nx": "22.6.1",
+    "concurrently": "10.0.4",
+    "nx": "23.1.1",
    "tsx": "^4.21.0"
  },
  "workspaces": {
@@ -93,5 +95,5 @@
      "packages/*"
    ]
  },
-  "packageManager": "pnpm@11.13.0"
+  "packageManager": "pnpm@11.15.1"
 }
@@ -32,6 +32,7 @@ export * from "./lib/columns";
 export * from "./lib/status";
 export * from "./lib/pdf";
 export * from "./lib/page-break";
+export * from "./lib/footnotes";
 export * from "./lib/resizable-nodeview";
 export {
  pageNodeToDocxBuffer,
@@ -0,0 +1,189 @@
+//Source MIT - https://github.com/buttondown/tiptap-footnotes
+import { mergeAttributes } from "@tiptap/core";
+import ListItem, { ListItemOptions } from "@tiptap/extension-list-item";
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    footnote: {
+      /**
+       * scrolls to & sets the text selection at the end of the footnote with the given id
+       * @param id the id of the footote (i.e. the `data-id` attribute value of the footnote)
+       * @example editor.commands.focusFootnote("a43956c1-1ab8-462f-96e4-be3a4b27fd50")
+       */
+      focusFootnote: (id: string) => ReturnType;
+    };
+  }
+}
+
+export interface FootnoteOptions extends ListItemOptions {
+  /**
+   * Content expression for this node
+   * @default "paragraph+"
+   */
+  content: string;
+}
+
+const Footnote = ListItem.extend<FootnoteOptions>({
+  name: "footnote",
+  content() {
+    return this.options.content;
+  },
+  isolating: true,
+  defining: true,
+  draggable: false,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      bulletListTypeName: 'bulletList',
+      orderedListTypeName: 'orderedList',
+      ...this.parent?.(),
+      content: "paragraph+",
+    };
+  },
+
+  addAttributes() {
+    return {
+      id: {
+        isRequired: true,
+      },
+      // the data-id field should match the data-id field of a footnote reference.
+      // it's used to link footnotes and references together.
+      "data-id": {
+        isRequired: true,
+      },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "li",
+        getAttrs(node) {
+          const id = node.getAttribute("data-id");
+          if (id) {
+            return {
+              "data-id": node.getAttribute("data-id"),
+            };
+          }
+          return false;
+        },
+        priority: 1000,
+      },
+    ];
+  },
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "li",
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes),
+      0,
+    ];
+  },
+
+  addCommands() {
+    return {
+      focusFootnote:
+        (id: string) =>
+        ({ editor, chain }) => {
+          const matchedFootnote = editor.$node("footnote", {
+            "data-id": id,
+          });
+          if (matchedFootnote) {
+            // sets the text selection to the end of the footnote definition and scroll to it.
+            chain()
+              .focus()
+              .setTextSelection(
+                matchedFootnote.from + matchedFootnote.content.size
+              )
+              .run();
+
+            matchedFootnote.element.scrollIntoView();
+            return true;
+          }
+          return false;
+        },
+    };
+  },
+  addKeyboardShortcuts() {
+    return {
+      // when inside a footnote, Mod-a should select only the footnote content
+      "Mod-a": ({ editor }) => {
+        try {
+          const { selection } = editor.state;
+          const { $from } = selection;
+
+          for (let depth = $from.depth; depth >= 0; depth--) {
+            const node = $from.node(depth);
+            if (node.type.name === "footnote") {
+              const start = $from.start(depth);
+              const end = $from.end(depth);
+
+              editor.commands.setTextSelection({
+                from: start + 1,
+                to: end - 1,
+              });
+              return true;
+            }
+          }
+
+          return false;
+        } catch (e) {
+          return false;
+        }
+      },
+      // when the user presses tab, adjust the text selection to be at the end of the next footnote
+      Tab: ({ editor }) => {
+        try {
+          const { selection } = editor.state;
+          const pos = editor.$pos(selection.anchor);
+          if (!pos.after) return false;
+          // if the next node  is "footnotes", place the text selection at the end of the first footnote
+          if (pos.after.node.type.name == "footnotes") {
+            const firstChild = pos.after.node.child(0);
+            editor
+              .chain()
+              .setTextSelection(pos.after.from + firstChild.content.size)
+              .scrollIntoView()
+              .run();
+            return true;
+          } else {
+            const startPos = selection.$from.start(2);
+            if (Number.isNaN(startPos)) return false;
+            const parent = editor.$pos(startPos);
+            if (parent.node.type.name != "footnote" || !parent.after) {
+              return false;
+            }
+            // if the next node is a footnote, place the text selection at the end of it
+            editor
+              .chain()
+              .setTextSelection(parent.after.to - 1)
+              .scrollIntoView()
+              .run();
+            return true;
+          }
+        } catch {
+          return false;
+        }
+      },
+      // inverse of the tab command - place the text selection at the end of the previous footnote
+      "Shift-Tab": ({ editor }) => {
+        const { selection } = editor.state;
+        const startPos = selection.$from.start(2);
+        if (Number.isNaN(startPos)) return false;
+        const parent = editor.$pos(startPos);
+        if (parent.node.type.name != "footnote" || !parent.before) {
+          return false;
+        }
+
+        editor
+          .chain()
+          .setTextSelection(parent.before.to - 1)
+          .scrollIntoView()
+          .run();
+        return true;
+      },
+    };
+  },
+
+});
+
+export default Footnote;
@@ -0,0 +1,46 @@
+//Source MIT - https://github.com/buttondown/tiptap-footnotes
+import OrderedList from "@tiptap/extension-ordered-list";
+import FootnoteRules from "./rules";
+
+const Footnotes = OrderedList.extend({
+  name: "footnotes",
+  group: "", // removed the default group of the ordered list extension
+  isolating: true,
+  defining: true,
+  draggable: false,
+
+  content() {
+    return "footnote*";
+  },
+  addAttributes() {
+    return {
+      class: {
+        default: "footnotes",
+      },
+    };
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "ol.footnotes",
+        priority: 1000,
+      },
+    ];
+  },
+
+  addKeyboardShortcuts() {
+    return {};
+  },
+  addCommands() {
+    return {};
+  },
+  addInputRules() {
+    return [];
+  },
+
+  addExtensions() {
+    return [FootnoteRules];
+  },
+});
+
+export default Footnotes;
@@ -0,0 +1,4 @@
+export { default as Footnotes } from "./footnotes";
+export { default as Footnote } from "./footnote";
+export type { FootnoteOptions } from "./footnote";
+export { default as FootnoteReference } from "./reference";
@@ -0,0 +1,221 @@
+//Source MIT - https://github.com/buttondown/tiptap-footnotes
+import { mergeAttributes, Node } from "@tiptap/core";
+import {
+  Fragment as PMFragment,
+  Node as PMNode,
+  Slice,
+} from "@tiptap/pm/model";
+import { NodeSelection, Plugin, PluginKey } from "@tiptap/pm/state";
+import { generateNodeId } from "../utils";
+
+
+const REFNUM_ATTR = "data-reference-number";
+const REF_CLASS = "footnote-ref";
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    footnoteReference: {
+      /**
+       * add a new footnote reference
+       * @example editor.commands.addFootnote()
+       */
+      addFootnote: () => ReturnType;
+    };
+  }
+}
+
+const FootnoteReference = Node.create({
+  name: "footnoteReference",
+  inline: true,
+  content: "text*",
+  group: "inline",
+  atom: true,
+  draggable: true,
+
+  parseHTML() {
+    return [
+      {
+        tag: `sup`,
+        priority: 1000,
+        getAttrs(node) {
+          const anchor = node.querySelector<HTMLAnchorElement>(
+            `a.${REF_CLASS}:first-child`
+          );
+
+          if (!anchor) {
+            return false;
+          }
+
+          const id = anchor.getAttribute("data-id");
+          const ref = anchor.getAttribute(REFNUM_ATTR);
+
+          return {
+            "data-id": id ?? generateNodeId(),
+            referenceNumber: ref ?? anchor.innerText,
+          };
+        },
+        contentElement(node) {
+          return node.firstChild as HTMLElement;
+        },
+      },
+    ];
+  },
+
+  addAttributes() {
+    return {
+      class: {
+        default: REF_CLASS,
+      },
+      "data-id": {
+        renderHTML(attributes) {
+          return {
+            "data-id": attributes["data-id"] || generateNodeId(),
+          };
+        },
+      },
+      referenceNumber: {},
+
+      href: {
+        renderHTML(attributes) {
+          return {
+            href: `#fn:${attributes["referenceNumber"]}`,
+          };
+        },
+      },
+    };
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    const { referenceNumber, ...attributes } = HTMLAttributes;
+    const attrs = mergeAttributes(this.options.HTMLAttributes, attributes);
+    attrs[REFNUM_ATTR] = referenceNumber;
+
+    return [
+      "sup",
+      { id: `fnref:${referenceNumber}` },
+      ["a", attrs, HTMLAttributes.referenceNumber],
+    ];
+  },
+
+  addProseMirrorPlugins() {
+    const { editor } = this;
+
+    // Ensures pasted footnote references get unique IDs.
+    const mapNode = (node: PMNode): PMNode => {
+      if (node.type.name === this.name) {
+        const newAttrs = { ...node.attrs, "data-id": generateNodeId() };
+        return node.type.create(newAttrs, node.content, node.marks);
+      }
+
+      if (node.content && node.content.size > 0) {
+        const newChildren: PMNode[] = [];
+        let changed = false;
+
+        node.content.forEach((child) => {
+          const mapped = mapNode(child);
+          if (mapped !== child) {
+            changed = true;
+          }
+
+          newChildren.push(mapped);
+        });
+
+        if (changed) {
+          return node.copy(PMFragment.from(newChildren));
+        }
+      }
+
+      return node;
+    };
+
+    return [
+      new Plugin({
+        key: new PluginKey("footnotePasteHandler"),
+        props: {
+          transformPasted(slice) {
+            const mappedNodes: PMNode[] = [];
+            let changed = false;
+
+            slice.content.forEach((node) => {
+              const mapped = mapNode(node);
+              if (mapped !== node) {
+                changed = true;
+              }
+              mappedNodes.push(mapped);
+            });
+
+            if (!changed) {
+              return slice;
+            }
+
+            return new Slice(
+              PMFragment.from(mappedNodes),
+              slice.openStart,
+              slice.openEnd
+            );
+          },
+        },
+      }),
+      new Plugin({
+        key: new PluginKey("footnoteRefClick"),
+
+        props: {
+          // on double-click, focus on the footnote
+          handleDoubleClickOn(view, pos, node, nodePos, event) {
+            if (node.type.name != "footnoteReference") return false;
+            event.preventDefault();
+            const id = node.attrs["data-id"];
+            return editor.commands.focusFootnote(id);
+          },
+          // click the footnote reference once to get focus, click twice to scroll to the footnote
+          handleClickOn(view, pos, node, nodePos, event) {
+            if (node.type.name != "footnoteReference") return false;
+            event.preventDefault();
+            const { selection } = editor.state.tr;
+            if (selection instanceof NodeSelection && selection.node.eq(node)) {
+              const id = node.attrs["data-id"];
+              return editor.commands.focusFootnote(id);
+            } else {
+              editor.chain().setNodeSelection(nodePos).run();
+              return true;
+            }
+          },
+        },
+      }),
+    ];
+  },
+
+  addCommands() {
+    return {
+      addFootnote:
+        () =>
+        ({ state, tr }) => {
+          const node = this.type.create({
+            "data-id": generateNodeId(),
+          });
+          tr.insert(state.selection.anchor, node);
+          return true;
+        },
+    };
+  },
+
+  addInputRules() {
+    // when a user types [^text], add a new footnote
+    return [
+      {
+        find: /\[\^(.*?)\]/,
+        type: this.type,
+        undoable: true,
+        handler({ range, match, chain }) {
+          const start = range.from;
+          let end = range.to;
+          if (match[1]) {
+            chain().deleteRange({ from: start, to: end }).addFootnote().run();
+          }
+        },
+      },
+    ];
+  },
+});
+
+export default FootnoteReference;
@@ -0,0 +1,90 @@
+//Source MIT - https://github.com/buttondown/tiptap-footnotes
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { ReplaceStep } from "@tiptap/pm/transform";
+import { Extension } from "@tiptap/core";
+import { updateFootnotesList } from "./utils";
+
+const FootnoteRules = Extension.create({
+  name: "footnoteRules",
+  priority: 1000,
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey("footnoteRules"),
+        filterTransaction(tr) {
+          const { from, to } = tr.selection;
+
+          // Allow full document selections (Mod-a/Ctrl-a)
+          if (from === 0 && to === tr.doc.content.size) return true;
+
+          let selectedFootnotes = false;
+          let selectedContent = false;
+          let footnoteCount = 0;
+          tr.doc.nodesBetween(from, to, (node, _, parent) => {
+            if (parent?.type.name == "doc" && node.type.name != "footnotes") {
+              selectedContent = true;
+            } else if (node.type.name == "footnote") {
+              footnoteCount += 1;
+            } else if (node.type.name == "footnotes") {
+              selectedFootnotes = true;
+            }
+          });
+          const overSelected = selectedContent && selectedFootnotes;
+          /*
+           * Here, we don't allow any transaction that spans between the "content" nodes and the "footnotes" node. This also rejects any transaction that spans between more than 1 footnote.
+           */
+          return !overSelected && footnoteCount <= 1;
+        },
+
+        // if there are some to the footnote references (added/deleted/dragged), append a transaction that updates the footnotes list accordingly
+        appendTransaction(transactions, oldState, newState) {
+          let newTr = newState.tr;
+          let refsChanged = false; // true if the footnote references have been changed, false otherwise
+          for (let tr of transactions) {
+            if (!tr.docChanged) continue;
+            if (refsChanged) break;
+
+            for (let step of tr.steps) {
+              if (!(step instanceof ReplaceStep)) continue;
+              if (refsChanged) break;
+
+              const isDelete = step.from != step.to; // the user deleted items from the document (from != to & the step is a replace step)
+              const isInsert = step.slice.size > 0;
+
+              // check if any footnote references have been inserted
+              if (isInsert) {
+                step.slice.content.descendants((node) => {
+                  if (node?.type.name == "footnoteReference") {
+                    refsChanged = true;
+                    return false;
+                  }
+                });
+              }
+              if (isDelete && !refsChanged) {
+                // check if any footnote references have been deleted
+                tr.before.nodesBetween(
+                  step.from,
+                  Math.min(tr.before.content.size, step.to), // make sure to not go over the old document's limit
+                  (node) => {
+                    if (node.type.name == "footnoteReference") {
+                      refsChanged = true;
+                      return false;
+                    }
+                  },
+                );
+              }
+            }
+          }
+
+          if (refsChanged) {
+            updateFootnotesList(newTr, newState);
+            return newTr;
+          }
+
+          return null;
+        },
+      }),
+    ];
+  },
+});
+export default FootnoteRules;
@@ -0,0 +1,123 @@
+//Source MIT - https://github.com/buttondown/tiptap-footnotes
+import { EditorState, Transaction } from "@tiptap/pm/state";
+import { Fragment, Node } from "@tiptap/pm/model";
+
+// update the reference number of all the footnote references in the document
+export function updateFootnoteReferences(tr: Transaction) {
+  let count = 1;
+
+  const nodes: any[] = [];
+
+  tr.doc.descendants((node, pos) => {
+    if (node.type.name == "footnoteReference") {
+      tr.setNodeAttribute(pos, "referenceNumber", `${count}`);
+
+      nodes.push(node);
+      count += 1;
+    }
+  });
+  // return the updated footnote references (in the order that they appear in the document)
+  return nodes;
+}
+
+function getFootnotes(tr: Transaction) {
+  let footnotesRange: { from: number; to: number } | undefined;
+  const footnotes: Node[] = [];
+  tr.doc.descendants((node, pos) => {
+    if (node.type.name == "footnote") {
+      footnotes.push(node);
+    } else if (node.type.name == "footnotes") {
+      footnotesRange = { from: pos, to: pos + node.nodeSize };
+    } else {
+      return false;
+    }
+  });
+  return { footnotesRange, footnotes };
+}
+
+// update the "footnotes" ordered list based on the footnote references in the document
+export function updateFootnotesList(tr: Transaction, state: EditorState) {
+  const footnoteReferences = updateFootnoteReferences(tr);
+
+  const footnoteType = state.schema.nodes.footnote;
+  const footnotesType = state.schema.nodes.footnotes;
+
+  const emptyParagraph = state.schema.nodeFromJSON({
+    type: "paragraph",
+    content: [],
+  });
+
+  const { footnotesRange, footnotes } = getFootnotes(tr);
+
+  // a mapping of footnote id -> footnote node
+  const footnoteIds: { [key: string]: Node } = footnotes.reduce(
+    (obj, footnote) => {
+      obj[footnote.attrs["data-id"]] = footnote;
+      return obj;
+    },
+    {} as any,
+  );
+
+  const newFootnotes: Node[] = [];
+
+  let footnoteRefIds = new Set(
+    footnoteReferences.map((ref) => ref.attrs["data-id"]),
+  );
+  const deleteFootnoteIds: Set<string> = new Set();
+  for (let footnote of footnotes) {
+    const id = footnote.attrs["data-id"];
+    if (!footnoteRefIds.has(id) || deleteFootnoteIds.has(id)) {
+      deleteFootnoteIds.add(id);
+      // we traverse through this footnote's content because it may contain footnote references.
+      // we want to delete the footnotes associated with these references, so we add them to the delete set.
+      footnote.content.descendants((node) => {
+        if (node.type.name == "footnoteReference")
+          deleteFootnoteIds.add(node.attrs["data-id"]);
+      });
+    }
+  }
+
+  for (let i = 0; i < footnoteReferences.length; i++) {
+    let refId = footnoteReferences[i].attrs["data-id"];
+
+    if (deleteFootnoteIds.has(refId)) continue;
+    // if there is a footnote w/ the same id as this `ref`, we preserve its content and update its id attribute
+    if (refId in footnoteIds) {
+      let footnote = footnoteIds[refId];
+      newFootnotes.push(
+        footnoteType.create(
+          { ...footnote.attrs, id: `fn:${i + 1}` },
+          footnote.content,
+        ),
+      );
+    } else {
+      let newNode = footnoteType.create(
+        {
+          "data-id": refId,
+          id: `fn:${i + 1}`,
+        },
+        [emptyParagraph],
+      );
+      newFootnotes.push(newNode);
+    }
+  }
+
+  if (newFootnotes.length == 0) {
+    // no footnotes in the doc, delete the "footnotes" node
+    if (footnotesRange) {
+      tr.delete(footnotesRange.from, footnotesRange.to);
+    }
+  } else if (!footnotesRange) {
+    // there is no footnotes node present in the doc, add it
+    tr.insert(
+      tr.doc.content.size,
+      footnotesType.create(undefined, Fragment.from(newFootnotes)),
+    );
+  } else {
+    tr.replaceWith(
+      footnotesRange!.from + 1, // add 1 to point at the position after the opening ol tag
+      footnotesRange!.to - 1, // substract 1 to point to the position before the closing ol tag
+      Fragment.from(newFootnotes),
+    );
+  }
+}
@@ -0,0 +1,110 @@
+import { Token, marked } from 'marked';
+import { generateNodeId } from '../../utils';
+
+interface FootnoteRefToken {
+  type: 'footnoteRef';
+  label: string;
+  raw: string;
+}
+
+interface FootnoteDefToken {
+  type: 'footnoteDef';
+  label: string;
+  text: string;
+  raw: string;
+}
+
+// Parse-scoped state: markdownToHtml resets before the top-level parse and
+// appends the collected list after it. Nested marked.parse calls (callout,
+// footnote definitions) share this state, so hooks cannot be used here.
+let footnoteRefs: { label: string; id: string; number: number }[] = [];
+let footnoteDefs = new Map<string, string>();
+
+export function resetFootnotes() {
+  footnoteRefs = [];
+  footnoteDefs = new Map();
+}
+
+export function renderFootnotesList(): string {
+  if (!footnoteRefs.length) return '';
+  const items = footnoteRefs.map(({ label, id, number }) => {
+    const body = footnoteDefs.get(label) || '<p></p>';
+    return `<li id="fn:${number}" data-id="${id}">${body}</li>`;
+  });
+  return `<ol class="footnotes">\n${items.join('\n')}\n</ol>\n`;
+}
+
+export const footnoteRefExtension = {
+  name: 'footnoteRef',
+  level: 'inline',
+  start(src: string) {
+    return src.indexOf('[^');
+  },
+  tokenizer(src: string): FootnoteRefToken | undefined {
+    const match = /^\[\^([^\]\s]+)\]/.exec(src);
+    if (match) {
+      return {
+        type: 'footnoteRef',
+        raw: match[0],
+        label: match[1].toLowerCase(),
+      };
+    }
+  },
+  renderer(token: Token) {
+    const refToken = token as FootnoteRefToken;
+    const number = footnoteRefs.length + 1;
+    const id = generateNodeId();
+    footnoteRefs.push({ label: refToken.label, id, number });
+    return `<sup id="fnref:${number}"><a class="footnote-ref" data-id="${id}" data-reference-number="${number}" href="#fn:${number}">${number}</a></sup>`;
+  },
+};
+
+export const footnoteDefExtension = {
+  name: 'footnoteDef',
+  level: 'block',
+  start(src: string) {
+    return src.match(/^\[\^[^\]\s]+\]:/m)?.index ?? -1;
+  },
+  tokenizer(src: string): FootnoteDefToken | undefined {
+    const firstLine = /^\[\^([^\]\s]+)\]:[ \t]*/.exec(src);
+    if (!firstLine) return undefined;
+
+    const lines = src.split('\n');
+    const contentLines = [lines[0].slice(firstLine[0].length)];
+    let consumed = 1;
+    while (consumed < lines.length) {
+      const line = lines[consumed];
+      if (/^[ \t]{2,}\S/.test(line)) {
+        contentLines.push(line.replace(/^[ \t]{1,4}/, ''));
+        consumed += 1;
+      } else if (
+        /^[ \t]*$/.test(line) &&
+        consumed + 1 < lines.length &&
+        /^[ \t]{2,}\S/.test(lines[consumed + 1])
+      ) {
+        contentLines.push('');
+        consumed += 1;
+      } else {
+        break;
+      }
+    }
+
+    const raw =
+      lines.slice(0, consumed).join('\n') +
+      (consumed < lines.length ? '\n' : '');
+    return {
+      type: 'footnoteDef',
+      raw,
+      label: firstLine[1].toLowerCase(),
+      text: contentLines.join('\n').trim(),
+    };
+  },
+  renderer(token: Token) {
+    const defToken = token as FootnoteDefToken;
+    const body = defToken.text
+      ? marked.parse(defToken.text).toString()
+      : '<p></p>';
+    footnoteDefs.set(defToken.label, body);
+    return '';
+  },
+};
@@ -2,6 +2,12 @@ import { marked } from "marked";
 import { calloutExtension } from "./callout.marked";
 import { mathBlockExtension } from "./math-block.marked";
 import { mathInlineExtension } from "./math-inline.marked";
+import {
+  footnoteDefExtension,
+  footnoteRefExtension,
+  renderFootnotesList,
+  resetFootnotes,
+} from "./footnotes.marked";

 marked.use({
  renderer: {
@@ -34,7 +40,13 @@ marked.use({
 });

 marked.use({
-  extensions: [calloutExtension, mathBlockExtension, mathInlineExtension],
+  extensions: [
+    calloutExtension,
+    mathBlockExtension,
+    mathInlineExtension,
+    footnoteDefExtension,
+    footnoteRefExtension,
+  ],
 });

 marked.setOptions({ breaks: true });
@@ -48,5 +60,7 @@ export function markdownToHtml(
    .replace(YAML_FONT_MATTER_REGEX, "")
    .trimStart();

-  return marked.parse(markdown).toString();
+  resetFootnotes();
+  const html = marked.parse(markdown).toString();
+  return html + renderFootnotesList();
 }
@@ -34,6 +34,8 @@ export function htmlToMarkdown(html: string): string {
    iframeEmbed,
    image,
    video,
+    footnoteRef,
+    footnotesList,
  ]);
  return turndownService.turndown(html).replaceAll('<br>', ' ');
 }
@@ -203,6 +205,56 @@ function image(turndownService: _TurndownService) {
  });
 }

+function getFootnoteAnchor(node: HTMLElement): HTMLElement | null {
+  const child = node.firstElementChild as HTMLElement | null;
+  return child?.nodeName === 'A' && child.classList.contains('footnote-ref')
+    ? child
+    : null;
+}
+
+function footnoteRef(turndownService: _TurndownService) {
+  turndownService.addRule('footnoteRef', {
+    filter: function (node: HTMLInputElement) {
+      return node.nodeName === 'SUP' && !!getFootnoteAnchor(node);
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      const anchor = getFootnoteAnchor(node);
+      const number =
+        anchor.getAttribute('data-reference-number') || anchor.textContent;
+      return `[^${number}]`;
+    },
+  });
+}
+
+function footnotesList(turndownService: _TurndownService) {
+  turndownService.addRule('footnotesList', {
+    filter: function (node: HTMLInputElement) {
+      return node.nodeName === 'OL' && node.classList.contains('footnotes');
+    },
+    replacement: function (_content: string, node: HTMLInputElement) {
+      const items = Array.from(node.children).filter(
+        (child) => child.nodeName === 'LI',
+      );
+      const definitions = items.map((li, index) => {
+        const number =
+          (li.getAttribute('id') || '').replace('fn:', '') ||
+          String(index + 1);
+        const markdown = turndownService
+          .turndown((li as HTMLElement).innerHTML)
+          .trim();
+        // continuation lines need a 4-space indent to stay in the footnote
+        const [first, ...rest] = markdown.split('\n');
+        const body = [
+          first,
+          ...rest.map((line: string) => (line.trim() ? `    ${line}` : line)),
+        ].join('\n');
+        return `[^${number}]: ${body}`;
+      });
+      return `\n\n${definitions.join('\n')}\n\n`;
+    },
+  });
+}
+
 function video(turndownService: _TurndownService) {
  turndownService.addRule('video', {
    filter: function (node: HTMLInputElement) {
@@ -1,4 +1,4 @@
-import { HeadingLevel, ShadingType } from 'docx';
+import { FootnoteReferenceRun, HeadingLevel, Paragraph, ShadingType } from 'docx';
 import { Node } from 'prosemirror-model';
 import {
  DocxSerializerAsync,
@@ -168,6 +168,27 @@ export const defaultAsyncNodes: NodeSerializerAsync = {
  pageBreak(state, node) {
    state.closeBlock(node, { pageBreakBefore: true });
  },
+  footnoteReference(state, node) {
+    const number =
+      Number(node.attrs?.referenceNumber) || state.$footnoteCounter + 1;
+    state.$footnoteCounter = Math.max(state.$footnoteCounter, number);
+    // seed an empty body so the reference stays valid even if the trailing
+    // footnotes list is missing; the footnotes node overwrites it with content
+    if (!state.footnotes[number]) {
+      state.footnotes[number] = { children: [new Paragraph('')] };
+    }
+    state.current.push(new FootnoteReferenceRun(number));
+  },
+  async footnotes(state, node) {
+    for (let i = 0; i < node.childCount; i += 1) {
+      const item = node.child(i);
+      const number =
+        Number(String(item.attrs?.id ?? '').replace('fn:', '')) || i + 1;
+      await state.footnoteDefinition(item, number);
+    }
+  },
+  // items are consumed by the footnotes handler above
+  footnote() {},
  // No usable static export representation: skip without failing.
  subpages() {},
  transclusionReference() {},
@@ -824,6 +824,29 @@ export class DocxSerializerStateAsync {
    this.current.push(new FootnoteReferenceRun(this.$footnoteCounter));
  }

+  // Fills the footnote body for an already-referenced footnote number from a
+  // node holding block content (Docmost keeps footnote text in a trailing
+  // list, separate from the inline reference).
+  async footnoteDefinition(node: Node, number: number) {
+    const { current, children, nextRunOpts, nextParentParagraphOpts } = this;
+    this.current = [];
+    this.children = [];
+    delete this.nextRunOpts;
+    delete this.nextParentParagraphOpts;
+
+    await this.renderContent(node);
+    this.footnotes[number] = {
+      children: this.children.filter(
+        (child): child is Paragraph => child instanceof Paragraph,
+      ),
+    };
+
+    this.current = current;
+    this.children = children;
+    this.nextRunOpts = nextRunOpts;
+    this.nextParentParagraphOpts = nextParentParagraphOpts;
+  }
+
  closeBlock(node: Node, props?: IParagraphOptions) {
    const paragraph = new Paragraph({
      children: this.current,
@@ -422,6 +422,8 @@ export const SearchAndReplace = Extension.create<
        state: {
          init: () => DecorationSet.empty,
          apply({ doc, docChanged }, oldState) {
+            const storage = editor.storage.searchAndReplace;
+            if (!storage) return oldState;
            const {
              searchTerm,
              lastSearchTerm,
@@ -429,7 +431,7 @@ export const SearchAndReplace = Extension.create<
              lastCaseSensitive,
              resultIndex,
              lastResultIndex,
-            } = editor.storage.searchAndReplace;
+            } = storage;

            if (
              !docChanged &&
@@ -7,9 +7,19 @@ export interface TrailingNodeExtensionOptions {
 }

 function nodeEqualsType({ types, node }: { types: any, node: any }) {
+  if (!node) return false
  return (Array.isArray(types) && types.includes(node.type)) || node.type === types
 }

+// footnotes must stay the last doc child, so the trailing node goes before it
+function lastNodeBeforeFootnotes(doc: any) {
+  const lastChild = doc.lastChild
+  if (lastChild?.type.name === 'footnotes') {
+    return doc.childCount > 1 ? doc.child(doc.childCount - 2) : null
+  }
+  return lastChild
+}
+
 // @ts-ignore
 /**
 * Extension based on:
@@ -40,19 +50,23 @@ export const TrailingNode = Extension.create<TrailingNodeExtensionOptions>({
        appendTransaction: (_, __, state) => {
          const { doc, tr, schema } = state;
          const shouldInsertNodeAtEnd = plugin.getState(state);
-          const endPosition = doc.content.size;
          const type = schema.nodes[this.options.node]

          if (!shouldInsertNodeAtEnd) {
            return;
          }

+          const lastChild = doc.lastChild
+          const endPosition = lastChild?.type.name === 'footnotes'
+            ? doc.content.size - lastChild.nodeSize
+            : doc.content.size
+
          return tr.insert(endPosition, type.create());
        },
        state: {
          init: (_, state) => {
            try {
-              const lastNode = state.tr.doc.lastChild
+              const lastNode = lastNodeBeforeFootnotes(state.tr.doc)
              return !nodeEqualsType({ node: lastNode, types: disabledNodes })
            } catch (err){
              console.log(err)
@@ -70,7 +84,7 @@ export const TrailingNode = Extension.create<TrailingNodeExtensionOptions>({
              return value
            }

-            const lastNode = tr.doc.lastChild
+            const lastNode = lastNodeBeforeFootnotes(tr.doc)
            return !nodeEqualsType({ node: lastNode, types: disabledNodes })
          },
        },
@@ -5,56 +5,30 @@ patchedDependencies:
  scimmy@1.3.5: patches/scimmy@1.3.5.patch
 overrides:
  prosemirror-changeset: 2.4.0
-  y-prosemirror: 1.3.7
  glob: 13.0.6
  ws: 8.21.0
-  dompurify: 3.4.11
+  dompurify: 3.4.13
+  mermaid: 11.16.1
+  undici: 7.29.0
  tmp: 0.2.7
-  hono: 4.12.25
-  mermaid: 11.15.0
-  nanoid@^3: 3.3.8
-  socket.io-parser: 4.2.6
-  serialize-javascript: 7.0.3
+  nanoid@^3: 3.3.17
  lodash-es: 4.18.1
-  lodash: 4.18.1
-  '@hono/node-server': 1.19.13
-  undici: 7.28.0
-  ajv@^6: 6.14.0
-  ajv@^8: 8.18.0
-  underscore: 1.13.8
-  immutable: 4.3.8
  express-rate-limit: 8.2.2
-  minimatch@^3: 3.1.5
-  minimatch@^5: 5.1.8
  flatted: 3.4.2
-  picomatch@<2.3.2: 2.3.2
-  picomatch@>=4.0.0 <4.0.4: 4.0.4
-  fastify: 5.8.5
-  yaml@>=1.0.0 <1.10.3: 1.10.3
+  find-my-way: 9.7.0
  yaml@>=2.0.0 <2.8.3: 2.8.3
-  path-to-regexp@^8: 8.4.0
-  brace-expansion@^5: 5.0.6
-  '@xmldom/xmldom': 0.8.13
-  handlebars: 4.7.9
-  axios: 1.16.0
-  langsmith: 0.7.0
-  follow-redirects: 1.16.0
-  protobufjs: 7.5.8
-  ip-address: 10.1.1
-  fast-uri: 3.1.3
+  brace-expansion@^5: 5.0.9
+  axios: 1.18.1
+  ip-address: 10.3.1
+  fast-uri: 3.1.5
  form-data@>=4.0.0 <4.0.6: 4.0.6
-  nanoid@>=4.0.0 <5.0.9: 5.1.16
-  qs: 6.15.3
+  nanoid@>=4.0.0 <5.1.16: 5.1.16
  esbuild@>=0.27.3 <0.28.1: 0.28.1
-  '@babel/core@<=7.29.0': 7.29.7
  '@opentelemetry/core@>=2.0.0 <2.8.0': 2.9.0
-  '@babel/plugin-transform-modules-systemjs@<=7.29.3': 7.29.7
-  brace-expansion@<1.1.13: 1.1.15
-  brace-expansion@>=2.0.0 <2.0.3: 2.0.3
-  js-yaml@>=3.0.0 <3.15.0: 3.15.0
-  js-yaml@>=4.0.0 <=4.1.1: 4.3.0
+  js-yaml@>=3.0.0 <3.15.1: 3.15.1
+  js-yaml@>=4.0.0 <4.3.1: 4.3.1
 shamefullyHoist: true
-minimumReleaseAge: 5760
+minimumReleaseAge: 4320
 allowBuilds:
  '@swc/core': true
  bcrypt: true
Author	SHA1	Message	Date
Philipinho	c17369411d	feat: proper DOCX support	2026-08-11 01:45:01 +01:00
Philipinho	0a5206f19e	feat: footnotes	2026-08-11 01:30:26 +01:00
Philip Okugbe	7439da2f6e	chore: package updates (#2383 ) * update * update versions * package updates	2026-08-10 17:56:12 +01:00
Philip Okugbe	305fd40686	fix: browser tab showing url instead of page title (#2382 )	2026-08-10 17:38:03 +01:00
Philipinho	4bd51d7404	fix: self-reference parent page	2026-08-10 17:37:12 +01:00
Philip Okugbe	89378ee766	chore: package updates (#2378 ) * chore: package updates * remove stale overrides	2026-08-06 23:41:36 +01:00
Philip Okugbe	56ac42767a	fix: stale placeholder decorations on empty paragraphs (#2374 )	2026-08-02 21:07:50 +01:00
Philipinho	38380211a5	fix: dedupe duplicate packages	2026-08-01 11:57:05 +01:00
Philip Okugbe	cd34594b5d	fix: placeholder bug (#2373 ) * fix placeholder check * tiptap v3.29.2 * add s3 max socket env	2026-08-01 11:45:25 +01:00
Philip Okugbe	70d2ff8685	fix: increase s3 client max socket limit (#2355 )	2026-07-21 22:59:25 +01:00
Philipinho	0ba2d78660	chore: update pnpm and axios	2026-07-20 20:46:02 +01:00
Philip Okugbe	3ed505d2be	fix: toolbar flicker on navigation (#2352 )	2026-07-20 20:36:03 +01:00
Philip Okugbe	a55057db37	feat: collab hocuspocus v4 upgrade (#2351 ) * WIP 1 * complete v4 migration * add flushDelay * feat: multiplexing * fix: survive hocuspocus v4 message timeout * fix: searchTerm type error	2026-07-20 20:34:09 +01:00
Philip Okugbe	ce8fbb86ff	chore: upgrade to node 26 and pnpm 11 (#2342 ) * chore: pnpm 11 * chore: set minimum age and allowedBuilds * Node 26; pnpm 11 * prod package overrides * dev package overides * cleanup	2026-07-20 19:44:51 +01:00