fix collab module error

fix: scope synced blocks to workspace, gate unsync on edit permission
feat: enforce strict transclusion schema
2026-05-08 15:23:07 +08:00 · 2026-05-08 01:35:50 +01:00 · 2026-05-08 01:15:13 +01:00 · 2026-05-08 00:26:31 +01:00 · 2026-05-07 23:26:16 +01:00 · 2026-05-07 23:16:22 +01:00
92 changed files with 4700 additions and 724 deletions
@@ -54,7 +54,6 @@
    "react-router-dom": "^7.13.1",
    "semver": "^7.7.4",
    "socket.io-client": "^4.8.3",
-    "tiptap-extension-global-drag-handle": "^0.1.18",
    "zod": "^4.3.6"
  },
  "devDependencies": {
@@ -870,6 +870,12 @@
  "Previous 7 days": "Previous 7 days",
  "Previous 30 days": "Previous 30 days",
  "Search chats...": "Search chats...",
+  "Search chats": "Search chats",
+  "Ask anything... Use @ to mention pages": "Ask anything... Use @ to mention pages",
+  "Ask anything or search your workspace": "Ask anything or search your workspace",
+  "Welcome to {{name}}": "Welcome to {{name}}",
+  "Add files": "Add files",
+  "Mention a page": "Mention a page",
  "Start a new chat to see it here.": "Start a new chat to see it here.",
  "Summarize this page": "Summarize this page",
  "Toggle AI Chat": "Toggle AI Chat",
@@ -927,4 +933,18 @@
  "AI navigation": "AI navigation",
  "Breadcrumb": "Breadcrumb",
  "Skip to main content": "Skip to main content"
+  "Synced block": "Synced block",
+  "Create a block that stays in sync across pages.": "Create a block that stays in sync across pages.",
+  "Editing original": "Editing original",
+  "Copy synced block": "Copy synced block",
+  "Unsync": "Unsync",
+  "Delete synced block": "Delete synced block",
+  "Synced to {{count}} other page_one": "Synced to {{count}} other page",
+  "Synced to {{count}} other page_other": "Synced to {{count}} other pages",
+  "ORIGINAL": "ORIGINAL",
+  "THIS PAGE": "THIS PAGE",
+  "No pages": "No pages",
+  "The original synced block no longer exists": "The original synced block no longer exists",
+  "You don't have access to this synced block": "You don't have access to this synced block",
+  "Failed to load this synced block": "Failed to load this synced block"
 }
@@ -137,7 +137,8 @@ export default function AiChatSidebar() {

      <TextInput
        className={classes.searchInput}
-        placeholder="Search chats..."
+        placeholder={t("Search chats...")}
+        aria-label={t("Search chats")}
        leftSection={<IconSearch size={14} />}
        size="xs"
        value={search}
@@ -178,6 +178,7 @@ export default function AsideChatPanel() {
            href="/ai"
            variant="subtle"
            color="dark"
+            aria-label={t("New chat")}
            onClick={handleNewChat}
          >
            <IconPlus size={20} stroke={1.75} />
@@ -185,13 +186,23 @@ export default function AsideChatPanel() {
        </Tooltip>

        <Tooltip label={t("Open full page")} openDelay={250}>
-          <ActionIcon variant="subtle" color="dark" onClick={handleExpand}>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            aria-label={t("Open full page")}
+            onClick={handleExpand}
+          >
            <IconArrowsDiagonal size={18} stroke={1.5} />
          </ActionIcon>
        </Tooltip>

        <Tooltip label={t("Close")} openDelay={250}>
-          <ActionIcon variant="subtle" color="dark" onClick={handleClose}>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            aria-label={t("Close")}
+            onClick={handleClose}
+          >
            <IconX size={20} stroke={1.75} />
          </ActionIcon>
        </Tooltip>
@@ -65,7 +65,7 @@ export default function ChatEmptyState({ isStreaming, onSend, onStop }: Props) {
          isStreaming={isStreaming}
          onSend={onSend}
          onStop={onStop}
-          placeholder="Ask anything... Use @ to mention pages"
+          placeholder={t("Ask anything... Use @ to mention pages")}
          autofocus
        />
      </div>
@@ -200,7 +200,7 @@ export default function ChatInput({
        link: false,
      }),
      Placeholder.configure({
-        placeholder: placeholder || "Ask anything... Use @ to mention pages",
+        placeholder: placeholder || t("Ask anything... Use @ to mention pages"),
      }),
      CharacterCount.configure({
        limit: 50000,
@@ -225,6 +225,10 @@ export default function ChatInput({
      }),
    ],
    editorProps: {
+      attributes: {
+        "aria-label": placeholder || t("Ask anything... Use @ to mention pages"),
+        "aria-multiline": "true",
+      },
      handleDOMEvents: {
        keydown: (_view, event) => {
          if (
@@ -275,6 +279,8 @@ export default function ChatInput({
        type="file"
        accept={ACCEPTED_FILE_TYPES}
        multiple
+        aria-label={t("Add files")}
+        tabIndex={-1}
        style={{ display: "none" }}
        onChange={(e) => handleFileSelect(e.target.files)}
      />
@@ -31,7 +31,16 @@ export default function ChatToolGroup({ toolCalls, isStreaming }: Props) {
    <div className={classes.toolGroup}>
      <div
        className={classes.toolGroupHeader}
+        role="button"
+        tabIndex={0}
+        aria-expanded={expanded}
        onClick={() => setExpanded((prev) => !prev)}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            setExpanded((prev) => !prev);
+          }
+        }}
      >
        {activeLabel ? (
          <IconLoader2 size={12} className={classes.processingSpinner} />
@@ -98,7 +98,7 @@
  font-weight: 600;
  letter-spacing: 0.08em;
  text-transform: uppercase;
-  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  color: var(--mantine-color-dimmed);
  margin-bottom: var(--mantine-spacing-xs);
 }

@@ -125,7 +125,7 @@
 .suggestionsLabel {
  font-size: var(--mantine-font-size-xs);
  font-weight: 500;
-  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+  color: var(--mantine-color-dimmed);
  text-transform: uppercase;
  letter-spacing: 0.5px;
  margin-bottom: var(--mantine-spacing-sm);
@@ -43,7 +43,7 @@
  margin-top: 6px;
  text-align: center;
  font-size: var(--mantine-font-size-xs);
-  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+  color: var(--mantine-color-dimmed);
 }

 .attachmentChips {
@@ -36,7 +36,7 @@
  padding: 4px var(--mantine-spacing-xs);
  font-size: var(--mantine-font-size-xs);
  font-weight: 600;
-  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  color: var(--mantine-color-dimmed);
  user-select: none;
 }

@@ -104,7 +104,7 @@

 .chatItemDate {
  font-size: var(--mantine-font-size-xs);
-  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+  color: var(--mantine-color-dimmed);
  white-space: nowrap;
  transition: opacity 150ms;
 }
@@ -12,6 +12,7 @@ import {
  IconInfoCircle,
  IconList,
  IconListNumbers,
+  IconQuote,
  IconTypography,
 } from "@tabler/icons-react";
 import { Popover, Button, ScrollArea, Tooltip } from "@mantine/core";
@@ -59,6 +60,7 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
        isCodeBlock: ctx.editor.isActive("codeBlock"),
        isCallout: ctx.editor.isActive("callout"),
        isDetails: ctx.editor.isActive("details"),
+        isTransclusionSource: ctx.editor.isActive("transclusionSource"),
      };
    },
  });
@@ -122,6 +124,12 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
          .run(),
      isActive: () => editorState?.isBlockquote,
    },
+    {
+      name: "Synced block",
+      icon: IconQuote,
+      command: () => editor.chain().focus().toggleTransclusionSource().run(),
+      isActive: () => editorState?.isTransclusionSource,
+    },
    {
      name: "Code",
      icon: IconCode,
@@ -149,7 +157,12 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
  return (
    <Popover opened={isOpen} withArrow>
      <Popover.Target>
-        <Tooltip label={t("Turn into")} withArrow withinPortal={false} disabled={isOpen}>
+        <Tooltip
+          label={t("Turn into")}
+          withArrow
+          withinPortal={false}
+          disabled={isOpen}
+        >
          <Button
            className={classes.buttonRoot}
            variant="default"
@@ -25,6 +25,7 @@ import {
  IconColumns3,
  IconColumns2,
  IconTag,
+  IconRotate2,
 } from "@tabler/icons-react";
 import {
  CommandProps,
@@ -231,7 +232,15 @@ const CommandGroups: SlashMenuGroupedItemsType = {
    {
      title: "Audio",
      description: "Upload any audio from your device.",
-      searchTerms: ["audio", "music", "sound", "mp3", "media", "file", "attachment"],
+      searchTerms: [
+        "audio",
+        "music",
+        "sound",
+        "mp3",
+        "media",
+        "file",
+        "attachment",
+      ],
      icon: IconMusic,
      command: ({ editor, range }) => {
        editor.chain().focus().deleteRange(range).run();
@@ -477,6 +486,28 @@ const CommandGroups: SlashMenuGroupedItemsType = {
        editor.chain().focus().deleteRange(range).insertSubpages().run();
      },
    },
+    {
+      title: "Synced block",
+      description: "Create a block that stays in sync across pages.",
+      searchTerms: [
+        "sync",
+        "synced",
+        "synced block",
+        "excerpt",
+        "transclusion",
+        "reusable",
+        "snippet",
+      ],
+      icon: IconRotate2,
+      command: ({ editor, range }: CommandProps) => {
+        editor
+          .chain()
+          .focus()
+          .deleteRange(range)
+          .insertTransclusionSource()
+          .run();
+      },
+    },
    {
      title: "2 Columns",
      description: "Split content into two columns.",
@@ -0,0 +1,17 @@
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function ErrorPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconAlertTriangle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("Failed to load this synced block")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,13 @@
+import { IconEyeOff } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NoAccessPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconEyeOff size={18} stroke={1.6} className={classes.placeholderIcon} />
+      <span>{t("You don't have access to this synced block")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,17 @@
+import { IconInfoCircle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NotFoundPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconInfoCircle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("The original synced block no longer exists")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,48 @@
+import { EditorProvider } from "@tiptap/react";
+import { useMemo } from "react";
+import { mainExtensions } from "@/features/editor/extensions/extensions";
+import { UniqueID } from "@docmost/editor-ext";
+
+type Props = {
+  content: unknown;
+};
+
+export default function TransclusionContent({ content }: Props) {
+  const extensions = useMemo(() => {
+    const filtered = mainExtensions.filter(
+      (e: any) => e.name !== "uniqueID" && e.name !== "globalDragHandle",
+    );
+    return [
+      ...filtered,
+      UniqueID.configure({
+        types: ["heading", "paragraph", "transclusionSource"],
+        updateDocument: false,
+      }),
+    ];
+  }, []);
+
+  // Isolate the nested read-only editor's events from the host editor:
+  // - mousedown/click would otherwise make the host node-select the atom
+  //   wrapper, blocking native text selection inside.
+  // - dragstart/dragover/drop would otherwise let the host treat events
+  //   inside the nested view as drops on the host, duplicating dropped
+  //   files at the transclusion's position.
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation();
+
+  return (
+    <div
+      onMouseDown={stop}
+      onClick={stop}
+      onDragStart={stop}
+      onDragOver={stop}
+      onDrop={stop}
+    >
+      <EditorProvider
+        editable={false}
+        immediatelyRender={true}
+        extensions={extensions}
+        content={content as any}
+      />
+    </div>
+  );
+}
@@ -0,0 +1,213 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  lookupTransclusion,
+  lookupTransclusionForShare,
+} from "@/features/transclusion/services/transclusion-api";
+import type { TransclusionLookup } from "@/features/transclusion/types/transclusion.types";
+
+type LookupKey = string; // `${sourcePageId}::${transclusionId}`
+
+type Subscriber = {
+  key: LookupKey;
+  sourcePageId: string;
+  transclusionId: string;
+  setResult: (r: TransclusionLookup) => void;
+};
+
+type ContextValue = {
+  /** Register a subscriber. Returns an unsubscribe function. */
+  subscribe: (s: Subscriber) => () => void;
+  /**
+   * Force a re-fetch of `key` and resolve when the response arrives (or the
+   * request fails). Bypasses the cache and any in-flight de-dup so the user
+   * always sees a fresh server read.
+   */
+  refresh: (key: LookupKey) => Promise<void>;
+};
+
+const TransclusionLookupContext = createContext<ContextValue | null>(null);
+
+export function TransclusionLookupProvider({
+  children,
+  shareId,
+}: {
+  children: React.ReactNode;
+  /**
+   * When set, lookups go through the share-scoped public endpoint and are
+   * gated by the share graph (source page must have its own share or inherit
+   * one). Used by the public share viewer; left undefined in the authenticated
+   * app, where personal permissions gate access.
+   */
+  shareId?: string;
+}) {
+  const subscribersRef = useRef(new Map<LookupKey, Subscriber[]>());
+  const queueRef = useRef(new Set<LookupKey>());
+  const tickRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Read inside flush() via ref so changing share context doesn't churn the
+  // memoized callbacks (and thus doesn't re-render every consumer).
+  const shareIdRef = useRef<string | undefined>(shareId);
+  shareIdRef.current = shareId;
+  // Last looked-up value for each key. Re-subscribers (e.g. when the editor
+  // remounts after switching from static to live) get this immediately
+  // instead of triggering a duplicate fetch.
+  const resultCacheRef = useRef(new Map<LookupKey, TransclusionLookup>());
+  // Keys that are currently in flight in a batch request. A second subscribe
+  // for the same key while the first request is pending is a no-op; the
+  // subscriber is added to subscribersRef and will be notified when the
+  // pending request completes.
+  const inFlightRef = useRef(new Set<LookupKey>());
+  // Resolvers waiting on the next response for a key. Populated by refresh()
+  // so callers can await the fetch round-trip; resolved on success and on
+  // network error so the UI never hangs in a loading state.
+  const pendingRef = useRef(new Map<LookupKey, Array<() => void>>());
+
+  const flush = useCallback(async () => {
+    tickRef.current = null;
+    const keys = Array.from(queueRef.current);
+    queueRef.current.clear();
+    if (keys.length === 0) return;
+
+    for (const k of keys) inFlightRef.current.add(k);
+
+    const references = keys.map((k) => {
+      const [sourcePageId, transclusionId] = k.split("::");
+      return { sourcePageId, transclusionId };
+    });
+
+    const resolveWaiters = (key: LookupKey) => {
+      const waiters = pendingRef.current.get(key);
+      if (!waiters) return;
+      pendingRef.current.delete(key);
+      for (const w of waiters) w();
+    };
+
+    try {
+      const activeShareId = shareIdRef.current;
+      const { items } = activeShareId
+        ? await lookupTransclusionForShare({
+            shareId: activeShareId,
+            references,
+          })
+        : await lookupTransclusion({ references });
+      for (const r of items) {
+        const key = `${r.sourcePageId}::${r.transclusionId}`;
+        resultCacheRef.current.set(key, r);
+        inFlightRef.current.delete(key);
+        const subs = subscribersRef.current.get(key);
+        if (subs) {
+          for (const s of subs) s.setResult(r);
+        }
+        resolveWaiters(key);
+      }
+    } catch {
+      // Network error — leave subscribers in pending state and clear the
+      // in-flight flag so a future subscribe can retry.
+      for (const k of keys) {
+        inFlightRef.current.delete(k);
+        resolveWaiters(k);
+      }
+    }
+  }, []);
+
+  const enqueue = useCallback(
+    (key: LookupKey) => {
+      queueRef.current.add(key);
+      if (tickRef.current === null) {
+        tickRef.current = setTimeout(flush, 10);
+      }
+    },
+    [flush],
+  );
+
+  const subscribe = useCallback<ContextValue["subscribe"]>(
+    (s) => {
+      const list = subscribersRef.current.get(s.key) ?? [];
+      list.push(s);
+      subscribersRef.current.set(s.key, list);
+
+      const cached = resultCacheRef.current.get(s.key);
+      if (cached) {
+        s.setResult(cached);
+      } else if (!inFlightRef.current.has(s.key)) {
+        enqueue(s.key);
+      }
+
+      return () => {
+        const cur = subscribersRef.current.get(s.key) ?? [];
+        const next = cur.filter((x) => x !== s);
+        if (next.length === 0) subscribersRef.current.delete(s.key);
+        else subscribersRef.current.set(s.key, next);
+      };
+    },
+    [enqueue],
+  );
+
+  const refresh = useCallback<ContextValue["refresh"]>(
+    (key) =>
+      new Promise<void>((resolve) => {
+        resultCacheRef.current.delete(key);
+        inFlightRef.current.delete(key);
+        const waiters = pendingRef.current.get(key) ?? [];
+        waiters.push(resolve);
+        pendingRef.current.set(key, waiters);
+        enqueue(key);
+      }),
+    [enqueue],
+  );
+
+  useEffect(
+    () => () => {
+      if (tickRef.current) clearTimeout(tickRef.current);
+    },
+    [],
+  );
+
+  const value = useMemo<ContextValue>(
+    () => ({ subscribe, refresh }),
+    [subscribe, refresh],
+  );
+
+  return (
+    <TransclusionLookupContext.Provider value={value}>
+      {children}
+    </TransclusionLookupContext.Provider>
+  );
+}
+
+export function useTransclusionLookup(
+  sourcePageId: string | null | undefined,
+  transclusionId: string | null | undefined,
+): {
+  result: TransclusionLookup | null;
+  refresh: () => Promise<void>;
+} {
+  const ctx = useContext(TransclusionLookupContext);
+  const [result, setResult] = useState<TransclusionLookup | null>(null);
+
+  useEffect(() => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    const key = `${sourcePageId}::${transclusionId}`;
+    const unsubscribe = ctx.subscribe({
+      key,
+      sourcePageId,
+      transclusionId,
+      setResult,
+    });
+    return unsubscribe;
+  }, [ctx, sourcePageId, transclusionId]);
+
+  const refresh = useCallback(async () => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    await ctx.refresh(`${sourcePageId}::${transclusionId}`);
+  }, [ctx, sourcePageId, transclusionId]);
+
+  return { result, refresh };
+}
@@ -0,0 +1,212 @@
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconDots,
+  IconLinkOff,
+  IconPencil,
+  IconRefresh,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { ErrorBoundary } from "react-error-boundary";
+import { useTransclusionLookup } from "./transclusion-lookup-context";
+import TransclusionContent from "./transclusion-content";
+import NoAccessPlaceholder from "./no-access-placeholder";
+import NotFoundPlaceholder from "./not-found-placeholder";
+import ErrorPlaceholder from "./error-placeholder";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+import {
+  useReferencesQuery,
+  useUnsyncReferenceMutation,
+} from "@/features/transclusion/queries/transclusion-query";
+import { buildPageUrl } from "@/features/page/page.utils";
+
+export default function TransclusionReferenceView(props: NodeViewProps) {
+  const isEditable = props.editor.isEditable;
+  const sourcePageId: string | null = props.node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = props.node.attrs.transclusionId ?? null;
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  return (
+    <NodeViewWrapper
+      className={classes.includeWrap}
+      data-focused={isEditable && props.selected ? "true" : "false"}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      contentEditable={false}
+    >
+      <ErrorBoundary
+        resetKeys={[sourcePageId, transclusionId]}
+        fallback={<ErrorPlaceholder />}
+      >
+        <TransclusionReferenceBody {...props} trackOpen={trackOpen} />
+      </ErrorBoundary>
+    </NodeViewWrapper>
+  );
+}
+
+function TransclusionReferenceBody({
+  editor,
+  node,
+  deleteNode,
+  getPos,
+  trackOpen,
+}: NodeViewProps & { trackOpen: (open: boolean) => void }) {
+  const { t } = useTranslation();
+  const sourcePageId: string | null = node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = node.attrs.transclusionId ?? null;
+  const isEditable = editor.isEditable;
+
+  const { result, refresh } = useTransclusionLookup(
+    sourcePageId,
+    transclusionId,
+  );
+  const [refreshing, setRefreshing] = useState(false);
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    try {
+      await refresh();
+    } finally {
+      setRefreshing(false);
+    }
+  };
+  // @ts-ignore - editor.storage.pageId is set by the host editor
+  const hostPageId: string | undefined = editor.storage?.pageId;
+  const unsyncMutation = useUnsyncReferenceMutation();
+  // Cached against the dropdown's identical query so the source link target
+  // is ready as soon as the controls fade in on hover, without a second
+  // fetch.
+  const referencesQuery = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    isEditable,
+  );
+  const sourcePageHref = (() => {
+    const source = referencesQuery.data?.source;
+    const base = source?.spaceSlug
+      ? buildPageUrl(source.spaceSlug, source.slugId, source.title)
+      : sourcePageId
+        ? `/p/${sourcePageId}`
+        : null;
+    if (!base) return null;
+    return transclusionId ? `${base}#${transclusionId}` : base;
+  })();
+
+  const handleUnsync = async () => {
+    if (!hostPageId || !sourcePageId || !transclusionId) return;
+    try {
+      const { content } = await unsyncMutation.mutateAsync({
+        referencePageId: hostPageId,
+        sourcePageId,
+        transclusionId,
+      });
+      const pos = getPos();
+      if (typeof pos !== "number") return;
+      const from = pos;
+      const to = pos + node.nodeSize;
+      editor
+        .chain()
+        .focus()
+        .insertContentAt({ from, to }, content as any)
+        .run();
+    } catch {
+      // mutation surfaces errors via React Query; node stays as-is
+    }
+  };
+
+  return (
+    <>
+      {isEditable && (
+        <div
+          className={classes.includeControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && hostPageId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={hostPageId}
+              mode="reference"
+              onOpenChange={trackOpen}
+            />
+          )}
+          <span className={classes.controlsDivider} />
+          <Tooltip label={t("Refresh")}>
+            <ActionIcon
+              variant="subtle"
+              color="gray"
+              size="sm"
+              onClick={handleRefresh}
+              loading={refreshing}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              <IconRefresh size={14} />
+            </ActionIcon>
+          </Tooltip>
+          {sourcePageHref && (
+            <Tooltip label={t("Edit source")}>
+              <ActionIcon
+                component={Link}
+                to={sourcePageHref}
+                variant="subtle"
+                color="gray"
+                size="sm"
+                style={{
+                  textDecoration: "none",
+                  borderBottom: "none",
+                }}
+              >
+                <IconPencil size={14} />
+              </ActionIcon>
+            </Tooltip>
+          )}
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+                disabled={
+                  unsyncMutation.isPending ||
+                  !hostPageId ||
+                  !sourcePageId ||
+                  !transclusionId
+                }
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Remove from page")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      {!sourcePageId || !transclusionId ? (
+        <NotFoundPlaceholder />
+      ) : !result ? (
+        <div style={{ minHeight: 24 }} />
+      ) : !("status" in result) ? (
+        <TransclusionContent content={result.content} />
+      ) : result.status === "no_access" ? (
+        <NoAccessPlaceholder />
+      ) : (
+        <NotFoundPlaceholder />
+      )}
+    </>
+  );
+}
@@ -0,0 +1,126 @@
+import {
+  NodeViewContent,
+  NodeViewProps,
+  NodeViewWrapper,
+} from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import {
+  IconCheck,
+  IconCopy,
+  IconDots,
+  IconLinkOff,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+
+export default function TransclusionView(props: NodeViewProps) {
+  const { editor, node, deleteNode } = props;
+  const { t } = useTranslation();
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  const isEditable = editor.isEditable;
+  // @ts-ignore - editor.storage.pageId is set by the host editor (page-editor.tsx onCreate)
+  const sourcePageId: string | undefined = editor.storage?.pageId;
+  const transclusionId: string | null = node.attrs.id ?? null;
+
+  const [copied, setCopied] = useState(false);
+  const handleCopy = async () => {
+    if (!sourcePageId || !transclusionId) return;
+    const html = `<div data-type="transclusionReference" data-source-page-id="${sourcePageId}" data-transclusion-id="${transclusionId}"></div>`;
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob([html], { type: "text/html" }),
+          "text/plain": new Blob([html], { type: "text/plain" }),
+        }),
+      ]);
+    } catch {
+      // Fallback for browsers without ClipboardItem write support
+      try {
+        await navigator.clipboard.writeText(html);
+      } catch {
+        return;
+      }
+    }
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 2000);
+    notifications.show({
+      message: t("Copied. Paste on any page to embed this synced block."),
+    });
+  };
+
+  const handleUnsync = () => {
+    editor.chain().focus().unsyncTransclusionSource().run();
+  };
+
+  return (
+    <NodeViewWrapper
+      className={classes.transclusionWrap}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      data-id={transclusionId ?? undefined}
+    >
+      {isEditable && (
+        <div
+          className={classes.transclusionControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={sourcePageId}
+              mode="source"
+              onOpenChange={trackOpen}
+            />
+          )}
+
+          <span className={classes.controlsDivider} />
+
+          <Tooltip label={copied ? t("Copied") : t("Copy synced block")}>
+            <ActionIcon
+              variant="subtle"
+              color={copied ? "teal" : "gray"}
+              size="sm"
+              onClick={handleCopy}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              {copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+            </ActionIcon>
+          </Tooltip>
+
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Delete synced block")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}
@@ -0,0 +1,209 @@
+.placeholder {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-radius: var(--mantine-radius-md);
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  font-size: var(--mantine-font-size-sm);
+  user-select: none;
+}
+
+.placeholderIcon {
+  flex: none;
+  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+}
+
+.transclusionBadge {
+  display: inline-block;
+  padding: 2px 8px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 600;
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  border-radius: var(--mantine-radius-sm);
+  margin-bottom: 4px;
+}
+
+.transclusionWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 3rem;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.transclusionWrap:hover,
+.transclusionWrap:focus-within {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.transclusionControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.transclusionControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.transclusionWrap:hover .transclusionControls,
+.transclusionWrap:focus-within .transclusionControls,
+.transclusionWrap[data-menu-open="true"] .transclusionControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.controlsDivider {
+  display: inline-block;
+  width: 1px;
+  height: 16px;
+  background: var(--mantine-color-default-border);
+}
+
+.transclusionControls a[href],
+.includeControls a[href] {
+  color: var(--ai-color);
+  border-bottom: none;
+  font-weight: inherit;
+}
+
+.includeWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 0;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.includeWrap:hover,
+.includeWrap[data-focused="true"],
+.includeWrap[data-menu-open="true"] {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.includeControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.includeControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.includeWrap:hover .includeControls,
+.includeWrap:focus-within .includeControls,
+.includeWrap[data-focused="true"] .includeControls,
+.includeWrap[data-menu-open="true"] .includeControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+:global(.react-renderer.node-transclusionSource.ProseMirror-selectednode),
+:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode) {
+  outline: none;
+}
+
+@media (max-width: 48em) {
+  .transclusionWrap,
+  .includeWrap {
+    margin-left: -1rem;
+    margin-right: -1rem;
+    width: calc(100% + 2rem);
+  }
+
+  .transclusionWrap {
+    padding-left: 1rem;
+    padding-right: 1rem;
+  }
+}
+
+@media print {
+  .transclusionControls,
+  .includeControls {
+    display: none !important;
+  }
+  .transclusionWrap,
+  .includeWrap {
+    border: none !important;
+    margin-left: 0 !important;
+    margin-right: 0 !important;
+    width: 100% !important;
+    padding: 0 !important;
+  }
+}
+
+.editingOriginalTag {
+  display: inline-block;
+  padding: 0 6px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: var(--mantine-color-blue-7);
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  border-radius: var(--mantine-radius-sm);
+}
@@ -0,0 +1,419 @@
+import { Extension } from "@tiptap/core";
+import {
+  NodeSelection,
+  Plugin,
+  PluginKey,
+  TextSelection,
+} from "@tiptap/pm/state";
+import { Fragment, Slice, Node } from "@tiptap/pm/model";
+import { EditorView } from "@tiptap/pm/view";
+
+export interface GlobalDragHandleOptions {
+  /**
+   * The width of the drag handle
+   */
+  dragHandleWidth: number;
+
+  /**
+   * The treshold for scrolling
+   */
+  scrollThreshold: number;
+
+  /*
+   * The css selector to query for the drag handle. (eg: '.custom-handle').
+   * If handle element is found, that element will be used as drag handle. If not, a default handle will be created
+   */
+  dragHandleSelector?: string;
+
+  /**
+   * Tags to be excluded for drag handle
+   */
+  excludedTags: string[];
+
+  /**
+   * Custom nodes to be included for drag handle
+   */
+  customNodes: string[];
+}
+function absoluteRect(node: Element) {
+  const data = node.getBoundingClientRect();
+  const modal = node.closest('[role="dialog"]');
+
+  if (modal && window.getComputedStyle(modal).transform !== "none") {
+    const modalRect = modal.getBoundingClientRect();
+
+    return {
+      top: data.top - modalRect.top,
+      left: data.left - modalRect.left,
+      width: data.width,
+    };
+  }
+  return {
+    top: data.top,
+    left: data.left,
+    width: data.width,
+  };
+}
+
+function nodeDOMAtCoords(
+  coords: { x: number; y: number },
+  options: GlobalDragHandleOptions,
+  view: EditorView,
+) {
+  const selectors = [
+    "li",
+    "p:not(:first-child)",
+    "pre",
+    "blockquote",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    ...options.customNodes.map((node) => `[data-type=${node}]`),
+  ].join(", ");
+  return document
+    .elementsFromPoint(coords.x, coords.y)
+    .find((elem: Element) => {
+      // Skip elements that belong to a nested editor (e.g. transclusion
+      // references render their own ProseMirror instance). Only consider
+      // elements whose closest editor is this host view.
+      if (elem.closest(".ProseMirror") !== view.dom) return false;
+      return (
+        elem.parentElement?.matches?.(".ProseMirror") ||
+        elem.matches(selectors)
+      );
+    });
+}
+function nodePosAtDOM(
+  node: Element,
+  view: EditorView,
+  options: GlobalDragHandleOptions,
+) {
+  const boundingRect = node.getBoundingClientRect();
+
+  return view.posAtCoords({
+    left: boundingRect.left + 50 + options.dragHandleWidth,
+    top: boundingRect.top + 1,
+  })?.inside;
+}
+
+function calcNodePos(pos: number, view: EditorView) {
+  const $pos = view.state.doc.resolve(pos);
+  if ($pos.depth > 1) return $pos.before($pos.depth);
+  return pos;
+}
+
+export function DragHandlePlugin(
+  options: GlobalDragHandleOptions & { pluginKey: string },
+) {
+  let listType = "";
+  function handleDragStart(event: DragEvent, view: EditorView) {
+    view.focus();
+
+    if (!event.dataTransfer) return;
+
+    const node = nodeDOMAtCoords(
+      {
+        x: event.clientX + 50 + options.dragHandleWidth,
+        y: event.clientY,
+      },
+      options,
+      view,
+    );
+
+    if (!(node instanceof Element)) return;
+
+    let draggedNodePos = nodePosAtDOM(node, view, options);
+    if (draggedNodePos == null || draggedNodePos < 0) return;
+    draggedNodePos = calcNodePos(draggedNodePos, view);
+
+    const { from, to } = view.state.selection;
+    const diff = from - to;
+
+    const fromSelectionPos = calcNodePos(from, view);
+    let differentNodeSelected = false;
+
+    const nodePos = view.state.doc.resolve(fromSelectionPos);
+
+    // Check if nodePos points to the top level node
+    if (nodePos.node().type.name === "doc") differentNodeSelected = true;
+    else {
+      const nodeSelection = NodeSelection.create(
+        view.state.doc,
+        nodePos.before(),
+      );
+
+      // Check if the node where the drag event started is part of the current selection
+      differentNodeSelected = !(
+        draggedNodePos + 1 >= nodeSelection.$from.pos &&
+        draggedNodePos <= nodeSelection.$to.pos
+      );
+    }
+    let selection = view.state.selection;
+    if (
+      !differentNodeSelected &&
+      diff !== 0 &&
+      !(view.state.selection instanceof NodeSelection)
+    ) {
+      const endSelection = NodeSelection.create(view.state.doc, to - 1);
+      selection = TextSelection.create(
+        view.state.doc,
+        draggedNodePos,
+        endSelection.$to.pos,
+      );
+    } else {
+      selection = NodeSelection.create(view.state.doc, draggedNodePos);
+
+      // if inline node is selected, e.g mention -> go to the parent node to select the whole node
+      // if table row is selected, go to the parent node to select the whole node
+      if (
+        (selection as NodeSelection).node.type.isInline ||
+        (selection as NodeSelection).node.type.name === "tableRow"
+      ) {
+        let $pos = view.state.doc.resolve(selection.from);
+        selection = NodeSelection.create(view.state.doc, $pos.before());
+      }
+    }
+    view.dispatch(view.state.tr.setSelection(selection));
+
+    // If the selected node is a list item, we need to save the type of the wrapping list e.g. OL or UL
+    if (
+      view.state.selection instanceof NodeSelection &&
+      view.state.selection.node.type.name === "listItem"
+    ) {
+      listType = node.parentElement!.tagName;
+    }
+
+    const slice = view.state.selection.content();
+    const { dom, text } = view.serializeForClipboard(slice);
+
+    event.dataTransfer.clearData();
+    event.dataTransfer.setData("text/html", dom.innerHTML);
+    event.dataTransfer.setData("text/plain", text);
+    event.dataTransfer.effectAllowed = "move";
+
+    event.dataTransfer.setDragImage(node, 0, 0);
+
+    view.dragging = { slice, move: event.ctrlKey };
+  }
+
+  let dragHandleElement: HTMLElement | null = null;
+
+  function hideDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.add("hide");
+    }
+  }
+
+  function showDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.remove("hide");
+    }
+  }
+
+  function hideHandleOnEditorOut(event: MouseEvent) {
+    if (event.target instanceof Element) {
+      // Check if the relatedTarget class is still inside the editor
+      const relatedTarget = event.relatedTarget as HTMLElement;
+      const isInsideEditor =
+        relatedTarget?.classList.contains("tiptap") ||
+        relatedTarget?.classList.contains("drag-handle");
+
+      if (isInsideEditor) return;
+    }
+    hideDragHandle();
+  }
+
+  return new Plugin({
+    key: new PluginKey(options.pluginKey),
+    view: (view) => {
+      const handleBySelector = options.dragHandleSelector
+        ? document.querySelector<HTMLElement>(options.dragHandleSelector)
+        : null;
+      dragHandleElement = handleBySelector ?? document.createElement("div");
+      dragHandleElement.draggable = true;
+      dragHandleElement.dataset.dragHandle = "";
+      dragHandleElement.classList.add("drag-handle");
+
+      function onDragHandleDragStart(e: DragEvent) {
+        handleDragStart(e, view);
+      }
+
+      dragHandleElement.addEventListener("dragstart", onDragHandleDragStart);
+
+      function onDragHandleDrag(e: DragEvent) {
+        hideDragHandle();
+        let scrollY = window.scrollY;
+        if (e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY - 30, behavior: "smooth" });
+        } else if (window.innerHeight - e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY + 30, behavior: "smooth" });
+        }
+      }
+
+      dragHandleElement.addEventListener("drag", onDragHandleDrag);
+
+      hideDragHandle();
+
+      if (!handleBySelector) {
+        view?.dom?.parentElement?.appendChild(dragHandleElement);
+      }
+      view?.dom?.parentElement?.addEventListener(
+        "mouseout",
+        hideHandleOnEditorOut,
+      );
+
+      return {
+        destroy: () => {
+          if (!handleBySelector) {
+            dragHandleElement?.remove?.();
+          }
+          dragHandleElement?.removeEventListener("drag", onDragHandleDrag);
+          dragHandleElement?.removeEventListener(
+            "dragstart",
+            onDragHandleDragStart,
+          );
+          dragHandleElement = null;
+          view?.dom?.parentElement?.removeEventListener(
+            "mouseout",
+            hideHandleOnEditorOut,
+          );
+        },
+      };
+    },
+    props: {
+      handleDOMEvents: {
+        mousemove: (view, event) => {
+          if (!view.editable) {
+            return;
+          }
+
+          const node = nodeDOMAtCoords(
+            {
+              x: event.clientX + 50 + options.dragHandleWidth,
+              y: event.clientY,
+            },
+            options,
+            view,
+          );
+
+          const notDragging = node?.closest(".not-draggable");
+          const excludedTagList = options.excludedTags
+            .concat(["ol", "ul"])
+            .join(", ");
+
+          if (
+            !(node instanceof Element) ||
+            node.matches(excludedTagList) ||
+            notDragging
+          ) {
+            hideDragHandle();
+            return;
+          }
+
+          const compStyle = window.getComputedStyle(node);
+          const parsedLineHeight = parseInt(compStyle.lineHeight, 10);
+          const lineHeight = isNaN(parsedLineHeight)
+            ? parseInt(compStyle.fontSize) * 1.2
+            : parsedLineHeight;
+          const paddingTop = parseInt(compStyle.paddingTop, 10);
+
+          const rect = absoluteRect(node);
+
+          rect.top += (lineHeight - 24) / 2;
+          rect.top += paddingTop;
+          // Li markers
+          if (node.matches("ul:not([data-type=taskList]) li, ol li")) {
+            rect.left -= options.dragHandleWidth;
+          }
+          rect.width = options.dragHandleWidth;
+
+          if (!dragHandleElement) return;
+
+          dragHandleElement.style.left = `${rect.left - rect.width}px`;
+          dragHandleElement.style.top = `${rect.top}px`;
+          showDragHandle();
+        },
+        keydown: () => {
+          hideDragHandle();
+        },
+        mousewheel: () => {
+          hideDragHandle();
+        },
+        // dragging class is used for CSS
+        dragstart: (view) => {
+          view.dom.classList.add("dragging");
+        },
+        drop: (view, event) => {
+          view.dom.classList.remove("dragging");
+          hideDragHandle();
+          let droppedNode: Node | null = null;
+          const dropPos = view.posAtCoords({
+            left: event.clientX,
+            top: event.clientY,
+          });
+
+          if (!dropPos) return;
+
+          if (view.state.selection instanceof NodeSelection) {
+            droppedNode = view.state.selection.node;
+          }
+          if (!droppedNode) return;
+
+          const resolvedPos = view.state.doc.resolve(dropPos.pos);
+
+          const isDroppedInsideList =
+            resolvedPos.parent.type.name === "listItem";
+
+          // If the selected node is a list item and is not dropped inside a list, we need to wrap it inside <ol> tag otherwise ol list items will be transformed into ul list item when dropped
+          if (
+            view.state.selection instanceof NodeSelection &&
+            view.state.selection.node.type.name === "listItem" &&
+            !isDroppedInsideList &&
+            listType == "OL"
+          ) {
+            const newList = view.state.schema.nodes.orderedList?.createAndFill(
+              null,
+              droppedNode,
+            );
+            const slice = new Slice(Fragment.from(newList), 0, 0);
+            view.dragging = { slice, move: event.ctrlKey };
+          }
+        },
+        dragend: (view) => {
+          view.dom.classList.remove("dragging");
+        },
+      },
+    },
+  });
+}
+
+const GlobalDragHandle = Extension.create({
+  name: "globalDragHandle",
+
+  addOptions() {
+    return {
+      dragHandleWidth: 20,
+      scrollThreshold: 100,
+      excludedTags: [],
+      customNodes: [],
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      DragHandlePlugin({
+        pluginKey: "globalDragHandle",
+        dragHandleWidth: this.options.dragHandleWidth,
+        scrollThreshold: this.options.scrollThreshold,
+        dragHandleSelector: this.options.dragHandleSelector,
+        excludedTags: this.options.excludedTags,
+        customNodes: this.options.customNodes,
+      }),
+    ];
+  },
+});
+
+export default GlobalDragHandle;
@@ -9,7 +9,6 @@ import SubScript from "@tiptap/extension-subscript";
 import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
-import GlobalDragHandle from "tiptap-extension-global-drag-handle";
 import { Youtube } from "@tiptap/extension-youtube";
 import SlashCommand, { SlashCommandExtension as Command } from "@/features/editor/extensions/slash-command";
 import renderItems from "@/features/editor/components/slash-menu/render-items";
@@ -52,6 +51,8 @@ import {
  Columns,
  Column,
  Status,
+  TransclusionSource,
+  TransclusionReference,
 } from "@docmost/editor-ext";
 import {
  randomElement,
@@ -80,6 +81,8 @@ import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-v
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import PdfView from "@/features/editor/components/pdf/pdf-view.tsx";
 import SubpagesView from "@/features/editor/components/subpages/subpages-view.tsx";
+import TransclusionView from "@/features/editor/components/transclusion/transclusion-view.tsx";
+import TransclusionReferenceView from "@/features/editor/components/transclusion/transclusion-reference-view.tsx";
 import { common, createLowlight } from "lowlight";
 import plaintext from "highlight.js/lib/languages/plaintext";
 import powershell from "highlight.js/lib/languages/powershell";
@@ -100,6 +103,7 @@ import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboa
 import EmojiCommand from "./emoji-command";
 import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
+import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";

 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -167,7 +171,7 @@ export const mainExtensions = [
  SharedStorage,
  Heading,
  UniqueID.configure({
-    types: ["heading", "paragraph"],
+    types: ["heading", "paragraph", "transclusionSource"],
    filterTransaction: (transaction) => !isChangeOrigin(transaction),
  }),
  Placeholder.configure({
@@ -215,7 +219,9 @@ export const mainExtensions = [
  }),
  Typography,
  TrailingNode,
-  GlobalDragHandle,
+  GlobalDragHandle.configure({
+    customNodes: ["transclusionSource", "transclusionReference"],
+  }),
  TextStyle,
  Color,
  SlashCommand,
@@ -351,6 +357,12 @@ export const mainExtensions = [
  Status.configure({
    view: StatusView,
  }),
+  TransclusionSource.configure({
+    view: TransclusionView,
+  }),
+  TransclusionReference.configure({
+    view: TransclusionReferenceView,
+  }),
  MarkdownClipboard.configure({
    transformPastedText: true,
  }),
@@ -71,6 +71,7 @@ import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { EditorAiMenu } from "@/ee/ai/components/editor/ai-menu/ai-menu";
 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";

 interface PageEditorProps {
  pageId: string;
@@ -399,55 +400,60 @@ export default function PageEditor({
    }
  }, [yjsConnectionStatus, isSynced]);

-  if (showStatic) {
-    return (
-      <EditorProvider
-        editable={false}
-        immediatelyRender={true}
-        extensions={mainExtensions}
-        content={content}
-      />
-    );
-  }
-
  return (
-    <div className="editor-container" style={{ position: "relative" }}>
-      <div ref={menuContainerRef}>
-        <EditorContent editor={editor} />
+    <TransclusionLookupProvider>
+      {showStatic ? (
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+        />
+      ) : (
+        <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} />
-            <TableCellMenu editor={editor} appendTo={menuContainerRef} />
-            <ImageMenu editor={editor} />
-            <VideoMenu editor={editor} />
-            <PdfMenu editor={editor} />
-            <CalloutMenu editor={editor} />
-            <SubpagesMenu editor={editor} />
-            <ExcalidrawMenu editor={editor} />
-            <DrawioMenu editor={editor} />
-            <ColumnsMenu editor={editor} />
+            {editor && editorIsEditable && (
+              <div>
+                <EditorAiMenu editor={editor} />
+                <EditorLinkMenu editor={editor} />
+                <EditorBubbleMenu editor={editor} />
+                <TableMenu editor={editor} />
+                <TableCellMenu editor={editor} appendTo={menuContainerRef} />
+                <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 />
+            )}
          </div>
-        )}
-        {editor && !editorIsEditable && (editable || canComment) && providersRef.current && (
-          <ReadonlyBubbleMenu editor={editor} />
-        )}
-        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
-        {showReadOnlyCommentPopup && (
-          <CommentDialog editor={editor} pageId={pageId} readOnly />
-        )}
-      </div>
-      <div
-        onClick={() => editor.commands.focus("end")}
-        style={{ paddingBottom: "20vh" }}
-      ></div>
-    </div>
+          <div
+            onClick={() => editor.commands.focus("end")}
+            style={{ paddingBottom: "20vh" }}
+          ></div>
+        </div>
+      )}
+    </TransclusionLookupProvider>
  );
 }
@@ -9,17 +9,26 @@ import { Placeholder } from "@tiptap/extension-placeholder";
 import { useAtom } from "jotai";
 import { readOnlyEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
+import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";

 interface PageEditorProps {
  title: string;
  content: any;
  pageId?: string;
+  /**
+   * When rendering inside a public share, pass the share's id (or key). Lookups
+   * for transclusion content then resolve against the share graph instead of
+   * the viewer's personal permissions, so a share never leaks source content
+   * that isn't itself shared.
+   */
+  shareId?: string;
 }

 export default function ReadonlyPageEditor({
  title,
  content,
  pageId,
+  shareId,
 }: PageEditorProps) {
  const [, setReadOnlyEditor] = useAtom(readOnlyEditorAtom);
  const isComponentMounted = useRef(false);
@@ -65,7 +74,7 @@ export default function ReadonlyPageEditor({
  ];

  return (
-    <>
+    <TransclusionLookupProvider shareId={shareId}>
      <div className="page-title">
        <EditorProvider
          editable={false}
@@ -95,6 +104,6 @@ export default function ReadonlyPageEditor({
        }}
      ></EditorProvider>
      <div style={{ paddingBottom: "20vh" }}></div>
-    </>
+    </TransclusionLookupProvider>
  );
 }
@@ -16,7 +16,7 @@

 .subtitle {
  font-size: var(--mantine-font-size-sm);
-  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  color: var(--mantine-color-dimmed);
  text-align: center;
  margin-top: 6px;
  margin-bottom: var(--mantine-spacing-lg);
@@ -0,0 +1,205 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 6px 3px 6px;
+  border-radius: 999px;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--mantine-font-size-xs);
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  transition: background 120ms ease;
+  user-select: none;
+}
+
+.trigger:hover {
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+.triggerIcon {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  display: inline-flex;
+}
+
+.triggerChev {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  display: inline-flex;
+  margin-left: 2px;
+}
+
+.dropdown {
+  padding: 0;
+}
+
+.banner {
+  display: flex;
+  gap: 10px;
+  padding: 10px 14px;
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  border-bottom: 1px solid
+    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-4));
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  font-size: var(--mantine-font-size-xs);
+  line-height: 1.5;
+}
+
+.bannerIcon {
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  flex: none;
+  display: inline-flex;
+  margin-top: 1px;
+}
+
+.bannerLink {
+  color: light-dark(
+    var(--mantine-color-gray-9),
+    var(--mantine-color-dark-0)
+  );
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+  font-weight: 500;
+}
+
+.bannerLink:hover {
+  text-decoration-thickness: 2px;
+}
+
+.section {
+  padding: 12px;
+}
+
+.sectionLabel {
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  margin: 0 0 6px;
+  padding: 0 4px;
+}
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 6px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  color: light-dark(
+    var(--mantine-color-gray-9),
+    var(--mantine-color-dark-0)
+  );
+  font-size: var(--mantine-font-size-sm);
+  text-decoration: none;
+  transition: background 100ms ease;
+}
+
+.row:hover {
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+.rowIcon {
+  color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  flex: none;
+  display: inline-flex;
+}
+
+.rowEmoji {
+  font-size: 14px;
+  line-height: 1;
+  flex: none;
+  display: inline-flex;
+  width: 18px;
+  justify-content: center;
+}
+
+.rowTitle {
+  font-weight: 500;
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.badge {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  padding: 2px 7px;
+  border-radius: 999px;
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  color: light-dark(
+    var(--mantine-color-gray-7),
+    var(--mantine-color-dark-1)
+  );
+  text-transform: uppercase;
+  flex: none;
+}
+
+.badgeAccent {
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  color: light-dark(
+    var(--mantine-color-blue-7),
+    var(--mantine-color-blue-2)
+  );
+}
+
+.empty {
+  padding: 18px 14px;
+  text-align: center;
+  color: light-dark(
+    var(--mantine-color-gray-6),
+    var(--mantine-color-dark-2)
+  );
+  font-size: var(--mantine-font-size-xs);
+}
+
+.loading {
+  display: flex;
+  justify-content: center;
+  padding: 18px;
+}
@@ -0,0 +1,184 @@
+import { useState } from "react";
+import { Loader, Popover } from "@mantine/core";
+import {
+  IconChevronDown,
+  IconCornerDownLeft,
+  IconFile,
+  IconInfoCircle,
+} from "@tabler/icons-react";
+import { Link } from "react-router-dom";
+import { Trans, useTranslation } from "react-i18next";
+import { useReferencesQuery } from "@/features/transclusion/queries/transclusion-query";
+import type { ReferencingPage } from "@/features/transclusion/types/transclusion.types";
+import { buildPageUrl } from "@/features/page/page.utils";
+import classes from "./sync-block-references-dropdown.module.css";
+
+type Props = {
+  sourcePageId: string | null;
+  transclusionId: string | null;
+  /** The page currently being viewed - used to mark the "THIS PAGE" badge. */
+  currentPageId: string;
+  /**
+   * Source: trigger reads "Editing original".
+   * Reference: trigger reads "Synced to N other pages".
+   */
+  mode: "source" | "reference";
+  /** Notified whenever the dropdown opens/closes (for keep-chrome-visible). */
+  onOpenChange?: (open: boolean) => void;
+};
+
+export default function SyncBlockReferencesDropdown({
+  sourcePageId,
+  transclusionId,
+  currentPageId,
+  mode,
+  onOpenChange,
+}: Props) {
+  const { t } = useTranslation();
+  const [opened, setOpened] = useState(false);
+
+  const handleOpenChange = (next: boolean) => {
+    setOpened(next);
+    onOpenChange?.(next);
+  };
+
+  // Fetch eagerly so the "Synced to N other pages" count is correct even
+  // before the dropdown is opened. The cache is keyed on (sourcePageId,
+  // transclusionId), so two views (source + reference) share one fetch.
+  const enabled = !!sourcePageId && !!transclusionId;
+  const { data, isLoading } = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    enabled,
+  );
+
+  const allPages: Array<{ page: ReferencingPage; isOriginal: boolean }> = [];
+  if (data?.source) {
+    allPages.push({ page: data.source, isOriginal: true });
+  }
+  for (const ref of data?.references ?? []) {
+    allPages.push({ page: ref, isOriginal: false });
+  }
+
+  const otherCount = allPages.filter((p) => p.page.id !== currentPageId).length;
+  const label =
+    mode === "source"
+      ? t("Editing original")
+      : t("Synced to {{count}} other page", {
+          count: otherCount,
+          defaultValue_one: "Synced to {{count}} other page",
+          defaultValue_other: "Synced to {{count}} other pages",
+        });
+
+  return (
+    <Popover
+      position="bottom-start"
+      shadow="lg"
+      opened={opened}
+      onChange={handleOpenChange}
+      width={340}
+      withinPortal
+    >
+      <Popover.Target>
+        <button
+          type="button"
+          className={classes.trigger}
+          onClick={() => handleOpenChange(!opened)}
+          aria-expanded={opened}
+          aria-haspopup="dialog"
+        >
+          <span className={classes.triggerIcon}>
+            <IconCornerDownLeft size={14} stroke={1.8} />
+          </span>
+          <span>{label}</span>
+          <span className={classes.triggerChev}>
+            <IconChevronDown size={12} stroke={2} />
+          </span>
+        </button>
+      </Popover.Target>
+
+      <Popover.Dropdown className={classes.dropdown}>
+        {mode === "reference" && data?.source && (
+          <div className={classes.banner}>
+            <span className={classes.bannerIcon}>
+              <IconInfoCircle size={16} stroke={1.6} />
+            </span>
+            <div>
+              <Trans
+                i18nKey="sourceReadOnlyHint"
+                defaults="This section is read-only here. Edit it on the <link>original source page</link>."
+                components={{
+                  link: (
+                    <Link
+                      to={
+                        data.source.spaceSlug
+                          ? buildPageUrl(
+                              data.source.spaceSlug,
+                              data.source.slugId,
+                              data.source.title,
+                            )
+                          : `/p/${data.source.id}`
+                      }
+                      className={classes.bannerLink}
+                      onClick={() => handleOpenChange(false)}
+                    />
+                  ),
+                }}
+              />
+            </div>
+          </div>
+        )}
+
+        {isLoading ? (
+          <div className={classes.loading}>
+            <Loader size="xs" />
+          </div>
+        ) : allPages.length === 0 ? (
+          <div className={classes.empty}>{t("No pages")}</div>
+        ) : (
+          <div className={classes.section}>
+            <div className={classes.sectionLabel}>{t("Synced to")}</div>
+            <ul className={classes.list}>
+              {allPages.map(({ page, isOriginal }) => {
+                const isCurrent = page.id === currentPageId;
+                const href = page.spaceSlug
+                  ? buildPageUrl(page.spaceSlug, page.slugId, page.title)
+                  : `/p/${page.id}`;
+                const title = page.title?.length ? page.title : t("Untitled");
+                return (
+                  <li key={page.id}>
+                    <Link
+                      to={href}
+                      className={classes.row}
+                      onClick={() => handleOpenChange(false)}
+                    >
+                      {page.icon ? (
+                        <span className={classes.rowEmoji}>{page.icon}</span>
+                      ) : (
+                        <span className={classes.rowIcon}>
+                          <IconFile size={16} stroke={1.6} />
+                        </span>
+                      )}
+                      <span className={classes.rowTitle} title={title}>
+                        {title}
+                      </span>
+                      {isCurrent ? (
+                        <span
+                          className={`${classes.badge} ${classes.badgeAccent}`}
+                        >
+                          {t("THIS PAGE")}
+                        </span>
+                      ) : isOriginal ? (
+                        <span className={classes.badge}>{t("ORIGINAL")}</span>
+                      ) : null}
+                    </Link>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        )}
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
@@ -0,0 +1,32 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import {
+  listReferences,
+  unsyncReference,
+} from "../services/transclusion-api";
+
+export function useReferencesQuery(
+  sourcePageId: string | null,
+  transclusionId: string | null,
+  enabled: boolean,
+) {
+  return useQuery({
+    queryKey: ["transclusion-references", sourcePageId, transclusionId],
+    queryFn: () =>
+      listReferences({
+        sourcePageId: sourcePageId!,
+        transclusionId: transclusionId!,
+      }),
+    enabled: enabled && !!sourcePageId && !!transclusionId,
+    staleTime: 10 * 1000,
+  });
+}
+
+export function useUnsyncReferenceMutation() {
+  return useMutation({
+    mutationFn: (params: {
+      referencePageId: string;
+      sourcePageId: string;
+      transclusionId: string;
+    }) => unsyncReference(params),
+  });
+}
@@ -0,0 +1,37 @@
+import api from "@/lib/api-client";
+import type {
+  ReferencingPagesResponse,
+  TransclusionLookup,
+} from "../types/transclusion.types";
+
+export async function lookupTransclusion(params: {
+  references: Array<{ sourcePageId: string; transclusionId: string }>;
+}): Promise<{ items: TransclusionLookup[] }> {
+  const r = await api.post("/pages/transclusion/lookup", params);
+  return r.data;
+}
+
+export async function lookupTransclusionForShare(params: {
+  shareId: string;
+  references: Array<{ sourcePageId: string; transclusionId: string }>;
+}): Promise<{ items: TransclusionLookup[] }> {
+  const r = await api.post("/shares/transclusion/lookup", params);
+  return r.data;
+}
+
+export async function listReferences(params: {
+  sourcePageId: string;
+  transclusionId: string;
+}): Promise<ReferencingPagesResponse> {
+  const r = await api.post("/pages/transclusion/references", params);
+  return r.data;
+}
+
+export async function unsyncReference(params: {
+  referencePageId: string;
+  sourcePageId: string;
+  transclusionId: string;
+}): Promise<{ content: unknown }> {
+  const r = await api.post("/pages/transclusion/unsync-reference", params);
+  return r.data;
+}
@@ -0,0 +1,23 @@
+export type TransclusionLookup =
+  | {
+      sourcePageId: string;
+      transclusionId: string;
+      content: unknown;
+      sourceUpdatedAt: string;
+    }
+  | { sourcePageId: string; transclusionId: string; status: "not_found" }
+  | { sourcePageId: string; transclusionId: string; status: "no_access" };
+
+export type ReferencingPage = {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  spaceSlug: string | null;
+};
+
+export type ReferencingPagesResponse = {
+  source: ReferencingPage | null;
+  references: ReferencingPage[];
+};
@@ -65,6 +65,7 @@ export default function SharedPage() {
          title={data.page.title}
          content={data.page.content}
          pageId={data.page.id}
+          shareId={data.share.id}
        />
      </Container>

@@ -63,8 +63,6 @@
    "@nestjs/throttler": "^6.5.0",
    "@nestjs/websockets": "^11.1.19",
    "@node-saml/passport-saml": "^5.1.0",
-    "@react-email/components": "1.0.10",
-    "@react-email/render": "2.0.4",
    "@socket.io/redis-adapter": "^8.3.0",
    "ai": "^6.0.134",
    "ai-sdk-ollama": "^3.8.1",
@@ -108,6 +106,7 @@
    "postgres": "^3.4.8",
    "postmark": "^4.0.7",
    "react": "^18.3.1",
+    "react-email": "6.0.8",
    "reflect-metadata": "^0.2.2",
    "rxjs": "^7.8.2",
    "sanitize-filename": "1.6.3",
@@ -146,7 +145,6 @@
    "jest": "^30.3.0",
    "kysely-codegen": "^0.20.0",
    "prettier": "^3.8.1",
-    "react-email": "5.2.10",
    "source-map-support": "^0.5.21",
    "supertest": "^7.2.2",
    "ts-jest": "^29.4.6",
@@ -1,10 +1,4 @@
-import {
-  Global,
-  Logger,
-  Module,
-  OnModuleDestroy,
-  OnModuleInit,
-} from '@nestjs/common';
+import { Logger, Module, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
 import { AuthenticationExtension } from './extensions/authentication.extension';
 import { PersistenceExtension } from './extensions/persistence.extension';
 import { CollaborationGateway } from './collaboration.gateway';
@@ -18,6 +12,10 @@ import { LoggerExtension } from './extensions/logger.extension';
 import { CollaborationHandler } from './collaboration.handler';
 import { CollabHistoryService } from './services/collab-history.service';
 import { WatcherModule } from '../core/watcher/watcher.module';
+import { TransclusionService } from '../core/page/transclusion/transclusion.service';
+import { TransclusionModule } from '../core/page/transclusion/transclusion.module';
+import { StorageModule } from '../integrations/storage/storage.module';
+import { EnvironmentModule } from '../integrations/environment/environment.module';

@Module({
  providers: [
@@ -28,9 +26,17 @@ import { WatcherModule } from '../core/watcher/watcher.module';
    HistoryProcessor,
    CollabHistoryService,
    CollaborationHandler,
+    TransclusionService,
  ],
  exports: [CollaborationGateway],
-  imports: [TokenModule, WatcherModule],
+  imports: [
+    TokenModule,
+    WatcherModule,
+    StorageModule.forRootAsync({
+      imports: [EnvironmentModule],
+    }),
+    TransclusionModule,
+  ],
 })
 export class CollaborationModule implements OnModuleInit, OnModuleDestroy {
  private readonly logger = new Logger(CollaborationModule.name);
@@ -40,6 +40,8 @@ import {
  Status,
  addUniqueIdsToDoc,
  htmlToMarkdown,
+  TransclusionSource,
+  TransclusionReference,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -101,6 +103,8 @@ export const tiptapExtensions = [
  Columns,
  Column,
  Status,
+  TransclusionSource,
+  TransclusionReference,
 ] as any;

 export function jsonToHtml(tiptapJson: any) {
@@ -32,6 +32,7 @@ import {
  HISTORY_FAST_THRESHOLD,
  HISTORY_INTERVAL,
 } from '../constants';
+import { TransclusionService } from '../../core/page/transclusion/transclusion.service';

@Injectable()
 export class PersistenceExtension implements Extension {
@@ -45,6 +46,7 @@ export class PersistenceExtension implements Extension {
    @InjectQueue(QueueName.HISTORY_QUEUE) private historyQueue: Queue,
    @InjectQueue(QueueName.NOTIFICATION_QUEUE) private notificationQueue: Queue,
    private readonly collabHistory: CollabHistoryService,
+    private readonly transclusionService: TransclusionService,
  ) {}

  async onLoadDocument(data: onLoadDocumentPayload) {
@@ -134,7 +136,11 @@ export class PersistenceExtension implements Extension {
        try {
          const existingContributors = page.contributorIds || [];
          contributorIds = Array.from(
-            new Set([...existingContributors, ...editingUserIds, page.creatorId]),
+            new Set([
+              ...existingContributors,
+              ...editingUserIds,
+              page.creatorId,
+            ]),
          );
        } catch (err) {
          //this.logger.debug('Contributors error:' + err?.['message']);
@@ -158,6 +164,10 @@ export class PersistenceExtension implements Extension {
      this.logger.error(`Failed to update page ${pageId}`, err);
    }

+    if (page) {
+      await this.syncTransclusion(pageId, page.workspaceId, tiptapJson);
+    }
+
    if (page) {
      await this.collabHistory.addContributors(pageId, editingUserIds);

@@ -165,7 +175,9 @@ export class PersistenceExtension implements Extension {

      const userMentions = extractUserMentions(mentions);
      const oldMentions = page.content ? extractMentions(page.content) : [];
-      const oldMentionedUserIds = extractUserMentions(oldMentions).map((m) => m.entityId);
+      const oldMentionedUserIds = extractUserMentions(oldMentions).map(
+        (m) => m.entityId,
+      );

      if (userMentions.length > 0) {
        await this.notificationQueue.add(QueueJob.PAGE_MENTION_NOTIFICATION, {
@@ -229,4 +241,41 @@ export class PersistenceExtension implements Extension {
      { jobId: page.id, delay },
    );
  }
+
+  /**
+   * Refresh `page_transclusions` and `page_transclusion_references` to match
+   * the page's current content. Runs outside the page-write transaction and
+   * isolates each call so a failure here cannot affect the page save itself.
+   * The diff is idempotent — the next save converges if a round drops anything.
+   */
+  private async syncTransclusion(
+    pageId: string,
+    workspaceId: string,
+    tiptapJson: unknown,
+  ): Promise<void> {
+    try {
+      await this.transclusionService.syncPageTransclusions(
+        pageId,
+        workspaceId,
+        tiptapJson,
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, pageId },
+        'Failed to sync transclusions for page',
+      );
+    }
+    try {
+      await this.transclusionService.syncPageReferences(
+        pageId,
+        workspaceId,
+        tiptapJson,
+      );
+    } catch (err) {
+      this.logger.error(
+        { err, pageId },
+        'Failed to sync transclusion references for page',
+      );
+    }
+  }
 }
@@ -62,14 +62,14 @@ function applyMarkToYFragment(
 ) {
  let pos = 0;

-  const processItem = (item: any): boolean => {
+  const processItem = (item: any, parentNodeName?: string): boolean => {
    if (pos >= to) return false;

    if (item instanceof Y.XmlText) {
      const textLength = item.length;
      const itemEnd = pos + textLength;

-      if (itemEnd > from && pos < to) {
+      if (itemEnd > from && pos < to && parentNodeName !== 'codeBlock') {
        const formatFrom = Math.max(0, from - pos);
        const formatTo = Math.min(textLength, to - pos);
        const formatLength = formatTo - formatFrom;
@@ -82,7 +82,7 @@ function applyMarkToYFragment(
    } else if (item instanceof Y.XmlElement) {
      pos++; // Opening tag
      for (let i = 0; i < item.length; i++) {
-        if (!processItem(item.get(i))) return false;
+        if (!processItem(item.get(i), item.nodeName)) return false;
      }
      pos++; // Closing tag
    }
@@ -0,0 +1,13 @@
+const ATTACHMENT_NODE_TYPES = [
+  'attachment',
+  'image',
+  'video',
+  'audio',
+  'pdf',
+  'excalidraw',
+  'drawio',
+];
+
+export function isAttachmentNode(nodeType: string): boolean {
+  return ATTACHMENT_NODE_TYPES.includes(nodeType);
+}
@@ -1,2 +1,2 @@
-export * from './generateHTML.js';
-export * from './generateJSON.js';
+export * from './generateHTML';
+export * from './generateJSON';
@@ -11,6 +11,7 @@ import {
  INTERNAL_LINK_REGEX,
  extractPageSlugId,
 } from '../../../integrations/export/utils';
+import { isAttachmentNode } from './attachment-node-types';

 export interface MentionNode {
  id: string;
@@ -122,18 +123,7 @@ export function getProsemirrorContent(content: any) {
  );
 }

-export function isAttachmentNode(nodeType: string) {
-  const attachmentNodeTypes = [
-    'attachment',
-    'image',
-    'video',
-    'audio',
-    'pdf',
-    'excalidraw',
-    'drawio',
-  ];
-  return attachmentNodeTypes.includes(nodeType);
-}
+export { isAttachmentNode };

 export function getAttachmentIds(prosemirrorJson: any) {
  const doc = jsonToNode(prosemirrorJson);
@@ -6,11 +6,12 @@ import { TrashCleanupService } from './services/trash-cleanup.service';
 import { StorageModule } from '../../integrations/storage/storage.module';
 import { CollaborationModule } from '../../collaboration/collaboration.module';
 import { WatcherModule } from '../watcher/watcher.module';
+import { TransclusionModule } from './transclusion/transclusion.module';

@Module({
  controllers: [PageController],
  providers: [PageService, PageHistoryService, TrashCleanupService],
  exports: [PageService, PageHistoryService],
-  imports: [StorageModule, CollaborationModule, WatcherModule],
+  imports: [StorageModule, CollaborationModule, WatcherModule, TransclusionModule],
 })
 export class PageModule {}
@@ -54,6 +54,7 @@ import {
 import { markdownToHtml } from '@docmost/editor-ext';
 import { WatcherService } from '../../watcher/watcher.service';
 import { sql } from 'kysely';
+import { TransclusionService } from '../transclusion/transclusion.service';

@Injectable()
 export class PageService {
@@ -71,6 +72,7 @@ export class PageService {
    private eventEmitter: EventEmitter2,
    private collaborationGateway: CollaborationGateway,
    private readonly watcherService: WatcherService,
+    private readonly transclusionService: TransclusionService,
  ) {}

  async findById(
@@ -600,6 +602,17 @@ export class PageService {
            }
          }

+          // Remap transclusion-reference source pages to their copies when
+          // the source page is also being duplicated in the same operation.
+          if (node.type.name === 'transclusionReference') {
+            const sourcePageId = node.attrs.sourcePageId;
+            if (sourcePageId && pageMap.has(sourcePageId)) {
+              const mappedPage = pageMap.get(sourcePageId);
+              //@ts-ignore
+              node.attrs.sourcePageId = mappedPage.newPageId;
+            }
+          }
+
          // Update internal page links in link marks
          for (const mark of node.marks) {
            if (
@@ -659,6 +672,39 @@ export class PageService {

    await this.db.insertInto('pages').values(insertablePages).execute();

+    // Extract transclusions from every duplicated page and persist them in
+    // one statement. Duplication bypasses Yjs onStoreDocument; brand-new
+    // pages never have prior rows so we can skip the diff and just bulk-insert.
+    try {
+      await this.transclusionService.insertTransclusionsForPages(
+        insertablePages.map((p) => ({
+          id: p.id,
+          workspaceId: p.workspaceId,
+          content: p.content,
+        })),
+      );
+    } catch (err) {
+      this.logger.error(
+        'Failed to insert transclusions for duplicated pages',
+        err,
+      );
+    }
+
+    try {
+      await this.transclusionService.insertReferencesForPages(
+        insertablePages.map((p) => ({
+          id: p.id,
+          workspaceId: p.workspaceId,
+          content: p.content,
+        })),
+      );
+    } catch (err) {
+      this.logger.error(
+        'Failed to insert transclusion references for duplicated pages',
+        err,
+      );
+    }
+
    const insertedPageIds = insertablePages.map((page) => page.id);
    this.eventEmitter.emit(EventName.PAGE_CREATED, {
      pageIds: insertedPageIds,
@@ -0,0 +1,26 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsString,
+  IsUUID,
+  MaxLength,
+  ValidateNested,
+} from 'class-validator';
+
+export class LookupReferenceDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  @MaxLength(36)
+  transclusionId!: string;
+}
+
+export class LookupDto {
+  @IsArray()
+  @ArrayMaxSize(50)
+  @ValidateNested({ each: true })
+  @Type(() => LookupReferenceDto)
+  references!: LookupReferenceDto[];
+}
@@ -0,0 +1,9 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class ReferencesDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}
@@ -0,0 +1,12 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class UnsyncReferenceDto {
+  @IsUUID()
+  referencePageId!: string;
+
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}
@@ -0,0 +1,240 @@
+import {
+  collectReferencesFromPmJson,
+  collectTransclusionsFromPmJson,
+} from '../utils/transclusion-prosemirror.util';
+
+describe('collectTransclusionsFromPmJson', () => {
+  it('returns [] for null/undefined doc', () => {
+    expect(collectTransclusionsFromPmJson(null)).toEqual([]);
+    expect(collectTransclusionsFromPmJson(undefined)).toEqual([]);
+  });
+
+  it('returns [] for a doc with no transclusion nodes', () => {
+    const doc = {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'hi' }] }],
+    };
+    expect(collectTransclusionsFromPmJson(doc)).toEqual([]);
+  });
+
+  it('extracts a top-level transclusion with id and content', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'abc123' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Body' }] }],
+        },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got).toHaveLength(1);
+    expect(got[0].transclusionId).toBe('abc123');
+    expect(got[0].content).toEqual({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Body' }] }],
+    });
+  });
+
+  it('skips transclusion nodes with no id (transient before UniqueID assigns one)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusionSource', attrs: {}, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    expect(collectTransclusionsFromPmJson(doc)).toEqual([]);
+  });
+
+  it('returns multiple top-level transclusions', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusionSource', attrs: { id: 'a' }, content: [{ type: 'paragraph' }] },
+        { type: 'transclusionSource', attrs: { id: 'b' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got.map((e) => e.transclusionId)).toEqual(['a', 'b']);
+  });
+
+  it('does not recurse into a nested transclusion (transclusion cannot contain transclusion per schema, but be defensive)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'outer' },
+          content: [
+            {
+              type: 'transclusionSource',
+              attrs: { id: 'inner' },
+              content: [{ type: 'paragraph' }],
+            },
+          ],
+        },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got.map((e) => e.transclusionId)).toEqual(['outer']);
+  });
+
+  it('finds transclusions nested inside other block containers (e.g. column)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'column',
+          content: [
+            { type: 'transclusionSource', attrs: { id: 'inCol' }, content: [{ type: 'paragraph' }] },
+          ],
+        },
+      ],
+    };
+    expect(collectTransclusionsFromPmJson(doc).map((e) => e.transclusionId)).toEqual([
+      'inCol',
+    ]);
+  });
+
+  it('uses the last id when duplicate ids appear (later wins, deterministic)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'dup' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'first' }] }],
+        },
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'dup' },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'second' }] }],
+        },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got).toHaveLength(1);
+    expect(got[0].content).toEqual({
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'second' }] }],
+    });
+  });
+});
+
+describe('collectReferencesFromPmJson', () => {
+  it('returns [] for null/undefined doc', () => {
+    expect(collectReferencesFromPmJson(null)).toEqual([]);
+    expect(collectReferencesFromPmJson(undefined)).toEqual([]);
+  });
+
+  it('returns [] for a doc with no transclusionReference nodes', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hi' }] },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([]);
+  });
+
+  it('extracts a top-level reference', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { sourcePageId: 'p1', transclusionId: 'e1' },
+    ]);
+  });
+
+  it('skips references missing sourcePageId or transclusionId', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusionReference', attrs: { transclusionId: 'e1' } },
+        { type: 'transclusionReference', attrs: { sourcePageId: 'p1' } },
+        { type: 'transclusionReference', attrs: {} },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([]);
+  });
+
+  it('finds references nested in other block containers (column, callout, etc.)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'column',
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+            },
+          ],
+        },
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { sourcePageId: 'p1', transclusionId: 'e1' },
+      { sourcePageId: 'p2', transclusionId: 'e2' },
+    ]);
+  });
+
+  it('does not recurse into a transclusion source (schema forbids references inside)', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'src1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([]);
+  });
+
+  it('dedupes identical (sourcePageId, transclusionId) pairs', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { sourcePageId: 'p1', transclusionId: 'e1' },
+      { sourcePageId: 'p2', transclusionId: 'e2' },
+    ]);
+  });
+});
@@ -0,0 +1,161 @@
+import {
+  rewriteAttachmentsForUnsync,
+  type AttachmentRewritePlan,
+} from '../utils/transclusion-unsync.util';
+
+describe('rewriteAttachmentsForUnsync', () => {
+  const fixedIds = (() => {
+    let i = 0;
+    return () => `new-${++i}`;
+  });
+
+  it('returns content unchanged when no attachment nodes are present', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hello' }] },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.content).toEqual(content);
+    expect(r.copies).toEqual([]);
+  });
+
+  it('rewrites attachmentId and src on a single image node', () => {
+    const oldId = '11111111-1111-1111-1111-111111111111';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: oldId,
+            src: `/api/files/${oldId}/cat.png`,
+          },
+        },
+      ],
+    };
+    const gen = fixedIds();
+    const r = rewriteAttachmentsForUnsync(content, gen);
+
+    expect(r.copies).toHaveLength(1);
+    const plan: AttachmentRewritePlan = r.copies[0];
+    expect(plan.oldAttachmentId).toBe(oldId);
+    expect(plan.newAttachmentId).toBe('new-1');
+
+    const img = (r.content as any).content[0];
+    expect(img.attrs.attachmentId).toBe('new-1');
+    expect(img.attrs.src).toBe('/api/files/new-1/cat.png');
+  });
+
+  it('rewrites every attachment node type (image, video, audio, attachment, drawio, excalidraw, pdf)', () => {
+    const types = [
+      'image',
+      'video',
+      'audio',
+      'attachment',
+      'drawio',
+      'excalidraw',
+      'pdf',
+    ] as const;
+    const content = {
+      type: 'doc',
+      content: types.map((t, i) => ({
+        type: t,
+        attrs: {
+          attachmentId: `old-${i}`,
+          src: `/api/files/old-${i}/file`,
+        },
+      })),
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(types.length);
+    expect((r.content as any).content.map((n: any) => n.attrs.attachmentId)).toEqual(
+      Array.from({ length: types.length }, (_, i) => `new-${i + 1}`),
+    );
+  });
+
+  it('reuses one new id per old attachmentId across nodes (dedupe)', () => {
+    const shared = 'shared-old';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: shared,
+            src: `/api/files/${shared}/a.png`,
+          },
+        },
+        {
+          type: 'image',
+          attrs: {
+            attachmentId: shared,
+            src: `/api/files/${shared}/a.png`,
+          },
+        },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(1);
+    expect(r.copies[0].oldAttachmentId).toBe(shared);
+    const newId = r.copies[0].newAttachmentId;
+    expect((r.content as any).content[0].attrs.attachmentId).toBe(newId);
+    expect((r.content as any).content[1].attrs.attachmentId).toBe(newId);
+  });
+
+  it('does not mutate the input content object', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'image',
+          attrs: { attachmentId: 'old-x', src: '/api/files/old-x/x.png' },
+        },
+      ],
+    };
+    const snapshot = JSON.parse(JSON.stringify(content));
+    rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(content).toEqual(snapshot);
+  });
+
+  it('skips nodes whose attachmentId is missing or not a uuid-shaped string', () => {
+    const content = {
+      type: 'doc',
+      content: [
+        { type: 'image', attrs: {} },
+        { type: 'image', attrs: { attachmentId: '' } },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toEqual([]);
+    expect(r.content).toEqual(content);
+  });
+
+  it('recurses into nested containers (column, callout)', () => {
+    const oldId = 'old-nested';
+    const content = {
+      type: 'doc',
+      content: [
+        {
+          type: 'callout',
+          content: [
+            {
+              type: 'image',
+              attrs: {
+                attachmentId: oldId,
+                src: `/api/files/${oldId}/x.png`,
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const r = rewriteAttachmentsForUnsync(content, fixedIds());
+    expect(r.copies).toHaveLength(1);
+    const newId = r.copies[0].newAttachmentId;
+    const inner = (r.content as any).content[0].content[0];
+    expect(inner.attrs.attachmentId).toBe(newId);
+    expect(inner.attrs.src).toBe(`/api/files/${newId}/x.png`);
+  });
+});
@@ -0,0 +1,48 @@
+import { Test } from '@nestjs/testing';
+import { TransclusionController } from '../transclusion.controller';
+import { TransclusionService } from '../transclusion.service';
+import { JwtAuthGuard } from '../../../../common/guards/jwt-auth.guard';
+
+describe('TransclusionController.lookup', () => {
+  let controller: TransclusionController;
+  let service: jest.Mocked<TransclusionService>;
+
+  beforeEach(async () => {
+    service = {
+      lookup: jest.fn(),
+      listReferences: jest.fn(),
+      unsyncReference: jest.fn(),
+    } as any;
+
+    const module = await Test.createTestingModule({
+      controllers: [TransclusionController],
+      providers: [{ provide: TransclusionService, useValue: service }],
+    })
+      .overrideGuard(JwtAuthGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    controller = module.get(TransclusionController);
+  });
+
+  const user = { id: 'u1', workspaceId: 'w1' } as any;
+  const ref = { sourcePageId: 'p1', transclusionId: 'e1' };
+
+  it('passes the references, viewer id and workspace id through to the service and returns its result', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          content: { type: 'doc' },
+          sourceUpdatedAt: new Date(),
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect(out.items[0]).not.toHaveProperty('status');
+    expect((out.items[0] as any).content).toEqual({ type: 'doc' });
+    expect(service.lookup).toHaveBeenCalledWith([ref], 'u1', 'w1');
+  });
+});
@@ -0,0 +1,320 @@
+import { Test } from '@nestjs/testing';
+import { TransclusionService } from '../transclusion.service';
+import { PageTransclusionsRepo } from '@docmost/db/repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from '@docmost/db/repos/page-transclusions/page-transclusion-references.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { StorageService } from '../../../../integrations/storage/storage.service';
+import { PageAccessService } from '../../page-access/page-access.service';
+
+describe('TransclusionService.syncPageTransclusions', () => {
+  let service: TransclusionService;
+  let repo: jest.Mocked<PageTransclusionsRepo>;
+
+  beforeEach(async () => {
+    const mockRepo: jest.Mocked<Partial<PageTransclusionsRepo>> = {
+      findByPageId: jest.fn(),
+      insert: jest.fn(),
+      update: jest.fn(),
+      deleteByPageAndTransclusionIds: jest.fn(),
+    };
+    const module = await Test.createTestingModule({
+      providers: [
+        TransclusionService,
+        { provide: PageTransclusionsRepo, useValue: mockRepo },
+        { provide: PageTransclusionReferencesRepo, useValue: {} },
+        { provide: PageRepo, useValue: {} },
+        { provide: PagePermissionRepo, useValue: {} },
+        { provide: AttachmentRepo, useValue: {} },
+        { provide: StorageService, useValue: {} },
+        { provide: PageAccessService, useValue: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    repo = module.get(PageTransclusionsRepo);
+  });
+
+  const pageId = '00000000-0000-0000-0000-000000000001';
+  const workspaceId = '00000000-0000-0000-0000-000000000099';
+
+  it('inserts new transclusions that did not exist before', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'a' },
+          content: [{ type: 'paragraph' }],
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 1, updated: 0, deleted: 0 });
+    expect(repo.insert).toHaveBeenCalledTimes(1);
+    expect(repo.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pageId,
+        transclusionId: 'a',
+      }),
+      undefined,
+    );
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.deleteByPageAndTransclusionIds).not.toHaveBeenCalled();
+  });
+
+  it('updates transclusions whose content changed', async () => {
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        content: { type: 'doc', content: [{ type: 'paragraph' }] },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const newContent = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'X' }] },
+      ],
+    };
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'a' },
+          content: newContent.content,
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 1, deleted: 0 });
+    expect(repo.update).toHaveBeenCalledWith(
+      pageId,
+      'a',
+      expect.objectContaining({ content: newContent }),
+      undefined,
+    );
+  });
+
+  it('skips update when content is unchanged', async () => {
+    const sameContent = {
+      type: 'doc',
+      content: [{ type: 'paragraph' }],
+    };
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        content: sameContent,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 'a' },
+          content: sameContent.content,
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 0 });
+    expect(repo.update).not.toHaveBeenCalled();
+  });
+
+  it('deletes transclusions that no longer appear in the doc', async () => {
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'r',
+        pageId,
+        transclusionId: 'gone',
+        content: { type: 'doc', content: [] },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    const result = await service.syncPageTransclusions(pageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 1 });
+    expect(repo.deleteByPageAndTransclusionIds).toHaveBeenCalledWith(
+      pageId,
+      ['gone'],
+      undefined,
+    );
+  });
+
+  it('handles empty doc → noop', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const result = await service.syncPageTransclusions(pageId, workspaceId, null);
+    expect(result).toEqual({ inserted: 0, updated: 0, deleted: 0 });
+    expect(repo.insert).not.toHaveBeenCalled();
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.deleteByPageAndTransclusionIds).not.toHaveBeenCalled();
+  });
+});
+
+describe('TransclusionService.syncPageReferences', () => {
+  let service: TransclusionService;
+  let refRepo: jest.Mocked<PageTransclusionReferencesRepo>;
+
+  beforeEach(async () => {
+    const mockTransclusionsRepo: Partial<PageTransclusionsRepo> = {};
+    const mockRefRepo: jest.Mocked<Partial<PageTransclusionReferencesRepo>> = {
+      findByReferencePageId: jest.fn(),
+      insertMany: jest.fn(),
+      deleteByReferenceAndKeys: jest.fn(),
+    };
+    const module = await Test.createTestingModule({
+      providers: [
+        TransclusionService,
+        { provide: PageTransclusionsRepo, useValue: mockTransclusionsRepo },
+        { provide: PageTransclusionReferencesRepo, useValue: mockRefRepo },
+        { provide: PageRepo, useValue: {} },
+        { provide: PagePermissionRepo, useValue: {} },
+        { provide: AttachmentRepo, useValue: {} },
+        { provide: StorageService, useValue: {} },
+        { provide: PageAccessService, useValue: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    refRepo = module.get(PageTransclusionReferencesRepo);
+  });
+
+  const referencePageId = '00000000-0000-0000-0000-000000000001';
+  const workspaceId = '00000000-0000-0000-0000-000000000099';
+
+  it('inserts new loose references, no deletes when none existed', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 2, deleted: 0 });
+    expect(refRepo.insertMany).toHaveBeenCalledWith(
+      [
+        {
+          workspaceId,
+          referencePageId,
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+        },
+        {
+          workspaceId,
+          referencePageId,
+          sourcePageId: 'p2',
+          transclusionId: 'e2',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+  });
+
+  it('ignores references nested inside a source (schema-forbidden)', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionSource',
+          attrs: { id: 's1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+  });
+
+  it('deletes references that no longer appear', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([
+      {
+        id: 'r1',
+        referencePageId,
+        sourcePageId: 'p1',
+        transclusionId: 'e1',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    const result = await service.syncPageReferences(referencePageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 1 });
+    expect(refRepo.deleteByReferenceAndKeys).toHaveBeenCalledWith(
+      referencePageId,
+      [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op when desired matches existing exactly', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([
+      {
+        id: 'r',
+        referencePageId,
+        sourcePageId: 'p1',
+        transclusionId: 'e1',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, workspaceId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,59 @@
+import {
+  Body,
+  Controller,
+  HttpCode,
+  HttpStatus,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../../common/guards/jwt-auth.guard';
+import { AuthUser } from '../../../common/decorators/auth-user.decorator';
+import { User } from '@docmost/db/types/entity.types';
+import { TransclusionService } from './transclusion.service';
+import { LookupDto } from './dto/lookup.dto';
+import { ReferencesDto } from './dto/references.dto';
+import { UnsyncReferenceDto } from './dto/unsync-reference.dto';
+
+@UseGuards(JwtAuthGuard)
+@Controller('pages/transclusion')
+export class TransclusionController {
+  constructor(private readonly transclusionService: TransclusionService) {}
+
+  @HttpCode(HttpStatus.OK)
+  @Post('lookup')
+  async lookup(@Body() dto: LookupDto, @AuthUser() user: User) {
+    return this.transclusionService.lookup(
+      dto.references,
+      user.id,
+      user.workspaceId,
+    );
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('references')
+  async references(
+    @Body() dto: ReferencesDto,
+    @AuthUser() user: User,
+  ) {
+    return this.transclusionService.listReferences({
+      sourcePageId: dto.sourcePageId,
+      transclusionId: dto.transclusionId,
+      viewerUserId: user.id,
+      workspaceId: user.workspaceId,
+    });
+  }
+
+  @HttpCode(HttpStatus.OK)
+  @Post('unsync-reference')
+  async unsyncReference(
+    @Body() dto: UnsyncReferenceDto,
+    @AuthUser() user: User,
+  ) {
+    return this.transclusionService.unsyncReference(
+      dto.referencePageId,
+      dto.sourcePageId,
+      dto.transclusionId,
+      user,
+    );
+  }
+}
@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { TransclusionController } from './transclusion.controller';
+import { TransclusionService } from './transclusion.service';
+
+@Module({
+  controllers: [TransclusionController],
+  providers: [TransclusionService],
+  exports: [TransclusionService],
+})
+export class TransclusionModule {}
@@ -0,0 +1,478 @@
+import {
+  Injectable,
+  Logger,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import { isDeepStrictEqual } from 'node:util';
+import { v7 as uuid7 } from 'uuid';
+import { KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { PageTransclusionsRepo } from '@docmost/db/repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from '@docmost/db/repos/page-transclusions/page-transclusion-references.repo';
+import { PageRepo } from '@docmost/db/repos/page/page.repo';
+import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
+import { AttachmentRepo } from '@docmost/db/repos/attachment/attachment.repo';
+import { StorageService } from '../../../integrations/storage/storage.service';
+import {
+  collectReferencesFromPmJson,
+  collectTransclusionsFromPmJson,
+} from './utils/transclusion-prosemirror.util';
+import { rewriteAttachmentsForUnsync } from './utils/transclusion-unsync.util';
+import { TransclusionLookup } from './transclusion.types';
+import { Page, User } from '@docmost/db/types/entity.types';
+import { PageAccessService } from '../page-access/page-access.service';
+
+type ReferencingPageInfo = {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  spaceSlug: string | null;
+};
+
+@Injectable()
+export class TransclusionService {
+  private readonly logger = new Logger(TransclusionService.name);
+
+  constructor(
+    private readonly pageTransclusionsRepo: PageTransclusionsRepo,
+    private readonly pageTransclusionReferencesRepo: PageTransclusionReferencesRepo,
+    private readonly pageRepo: PageRepo,
+    private readonly pagePermissionRepo: PagePermissionRepo,
+    private readonly attachmentRepo: AttachmentRepo,
+    private readonly storageService: StorageService,
+    private readonly pageAccessService: PageAccessService,
+  ) {}
+
+  async syncPageTransclusions(
+    pageId: string,
+    workspaceId: string,
+    pmJson: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number; updated: number; deleted: number }> {
+    const desired = collectTransclusionsFromPmJson(pmJson);
+    const desiredById = new Map(desired.map((d) => [d.transclusionId, d]));
+
+    const existing = await this.pageTransclusionsRepo.findByPageId(pageId, trx);
+    const existingById = new Map(existing.map((e) => [e.transclusionId, e]));
+
+    let inserted = 0;
+    let updated = 0;
+    let deleted = 0;
+
+    for (const d of desired) {
+      const prev = existingById.get(d.transclusionId);
+      if (!prev) {
+        await this.pageTransclusionsRepo.insert(
+          {
+            workspaceId,
+            pageId,
+            transclusionId: d.transclusionId,
+            content: d.content as any,
+          },
+          trx,
+        );
+        inserted += 1;
+        continue;
+      }
+
+      const contentChanged = !isDeepStrictEqual(prev.content, d.content);
+      if (contentChanged) {
+        await this.pageTransclusionsRepo.update(
+          pageId,
+          d.transclusionId,
+          { content: d.content as any },
+          trx,
+        );
+        updated += 1;
+      }
+    }
+
+    const removedIds = existing
+      .filter((e) => !desiredById.has(e.transclusionId))
+      .map((e) => e.transclusionId);
+    if (removedIds.length > 0) {
+      await this.pageTransclusionsRepo.deleteByPageAndTransclusionIds(
+        pageId,
+        removedIds,
+        trx,
+      );
+      deleted = removedIds.length;
+    }
+
+    return { inserted, updated, deleted };
+  }
+
+  async syncPageReferences(
+    referencePageId: string,
+    workspaceId: string,
+    pmJson: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number; deleted: number }> {
+    const desired = collectReferencesFromPmJson(pmJson);
+    const keyOf = (s: {
+      sourcePageId: string;
+      transclusionId: string;
+    }) => `${s.sourcePageId}::${s.transclusionId}`;
+    const desiredKeys = new Set(desired.map(keyOf));
+
+    const existing = await this.pageTransclusionReferencesRepo.findByReferencePageId(
+      referencePageId,
+      trx,
+    );
+    const existingKeys = new Set(existing.map(keyOf));
+
+    const toInsert = desired
+      .filter((d) => !existingKeys.has(keyOf(d)))
+      .map((d) => ({
+        workspaceId,
+        referencePageId,
+        sourcePageId: d.sourcePageId,
+        transclusionId: d.transclusionId,
+      }));
+
+    const toDelete = existing
+      .filter((e) => !desiredKeys.has(keyOf(e)))
+      .map((e) => ({
+        sourcePageId: e.sourcePageId,
+        transclusionId: e.transclusionId,
+      }));
+
+    if (toInsert.length > 0) {
+      await this.pageTransclusionReferencesRepo.insertMany(toInsert, trx);
+    }
+    if (toDelete.length > 0) {
+      await this.pageTransclusionReferencesRepo.deleteByReferenceAndKeys(
+        referencePageId,
+        toDelete,
+        trx,
+      );
+    }
+
+    return {
+      inserted: toInsert.length,
+      deleted: toDelete.length,
+    };
+  }
+
+  /**
+   * Extract transclusions from each page's PM JSON and bulk-insert into
+   * `page_transclusions` in a single statement. Intended for brand-new pages
+   * (e.g. duplication, import) where there is nothing to diff against.
+   */
+  async insertTransclusionsForPages(
+    pages: Array<{ id: string; workspaceId: string; content: unknown }>,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number }> {
+    const rows: Parameters<PageTransclusionsRepo['insertMany']>[0] = [];
+    for (const page of pages) {
+      const snapshots = collectTransclusionsFromPmJson(page.content);
+      for (const s of snapshots) {
+        rows.push({
+          workspaceId: page.workspaceId,
+          pageId: page.id,
+          transclusionId: s.transclusionId,
+          content: s.content as any,
+        });
+      }
+    }
+    if (rows.length === 0) return { inserted: 0 };
+    await this.pageTransclusionsRepo.insertMany(rows, trx);
+    return { inserted: rows.length };
+  }
+
+  /**
+   * Walk each page's PM JSON for `transclusionReference` nodes and bulk-insert
+   * one row per `(referencePage, source, target)`. For brand-new pages
+   * (duplication, import) where there is nothing to diff against.
+   */
+  async insertReferencesForPages(
+    pages: Array<{ id: string; workspaceId: string; content: unknown }>,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number }> {
+    const rows: Array<{
+      workspaceId: string;
+      referencePageId: string;
+      sourcePageId: string;
+      transclusionId: string;
+    }> = [];
+    for (const page of pages) {
+      const refs = collectReferencesFromPmJson(page.content);
+      for (const r of refs) {
+        rows.push({
+          workspaceId: page.workspaceId,
+          referencePageId: page.id,
+          sourcePageId: r.sourcePageId,
+          transclusionId: r.transclusionId,
+        });
+      }
+    }
+    if (rows.length === 0) return { inserted: 0 };
+    await this.pageTransclusionReferencesRepo.insertMany(rows, trx);
+    return { inserted: rows.length };
+  }
+
+  async lookup(
+    references: Array<{ sourcePageId: string; transclusionId: string }>,
+    viewerUserId: string,
+    workspaceId: string,
+  ): Promise<{ items: TransclusionLookup[] }> {
+    if (references.length === 0) return { items: [] };
+
+    const candidatePageIds = Array.from(
+      new Set(references.map((r) => r.sourcePageId)),
+    );
+    const accessibleSet = new Set(
+      await this.pagePermissionRepo.filterAccessiblePageIds({
+        pageIds: candidatePageIds,
+        userId: viewerUserId,
+      }),
+    );
+
+    return this.lookupWithAccessSet(references, accessibleSet, workspaceId);
+  }
+
+  /**
+   * Resolve transclusion content for the given references using a caller-supplied
+   * `accessibleSet` of source page ids. Source pages absent from the set return
+   * `no_access`. Used by the share-scoped lookup path, where access is gated by
+   * the share graph rather than the viewer's personal permissions.
+   */
+  async lookupWithAccessSet(
+    references: Array<{ sourcePageId: string; transclusionId: string }>,
+    accessibleSet: Set<string>,
+    workspaceId: string,
+  ): Promise<{ items: TransclusionLookup[] }> {
+    if (references.length === 0) return { items: [] };
+
+    const items: TransclusionLookup[] = new Array(references.length).fill(null);
+    const pendingIdx = references.map((_, i) => i);
+
+    const accessiblePending = pendingIdx.filter((i) =>
+      accessibleSet.has(references[i].sourcePageId),
+    );
+    const rows = await this.pageTransclusionsRepo.findManyByPageAndTransclusion(
+      accessiblePending.map((i) => ({
+        pageId: references[i].sourcePageId,
+        transclusionId: references[i].transclusionId,
+      })),
+      workspaceId,
+    );
+    const rowKey = (r: { pageId: string; transclusionId: string }) =>
+      `${r.pageId}::${r.transclusionId}`;
+    const rowMap = new Map(rows.map((r) => [rowKey(r), r]));
+
+    const accessiblePageIds = Array.from(
+      new Set(accessiblePending.map((i) => references[i].sourcePageId)),
+    );
+    const pages = await this.pageRepo.findManyByIds(accessiblePageIds, {
+      workspaceId,
+    });
+    const pageMeta = new Map<string, Date>();
+    for (const p of pages) {
+      pageMeta.set(p.id, p.updatedAt);
+    }
+
+    for (const i of pendingIdx) {
+      const ref = references[i];
+      if (!accessibleSet.has(ref.sourcePageId)) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'no_access',
+        };
+        continue;
+      }
+      const updatedAt = pageMeta.get(ref.sourcePageId);
+      if (!updatedAt) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'not_found',
+        };
+        continue;
+      }
+
+      const row = rowMap.get(`${ref.sourcePageId}::${ref.transclusionId}`);
+      if (!row) {
+        items[i] = {
+          sourcePageId: ref.sourcePageId,
+          transclusionId: ref.transclusionId,
+          status: 'not_found',
+        };
+        continue;
+      }
+      items[i] = {
+        sourcePageId: ref.sourcePageId,
+        transclusionId: ref.transclusionId,
+        content: row.content,
+        sourceUpdatedAt: updatedAt,
+      };
+    }
+
+    return { items };
+  }
+
+  async listReferences(opts: {
+    sourcePageId: string;
+    transclusionId: string;
+    viewerUserId: string;
+    workspaceId: string;
+  }): Promise<{
+    source: ReferencingPageInfo | null;
+    references: ReferencingPageInfo[];
+  }> {
+    const { sourcePageId, transclusionId, viewerUserId, workspaceId } = opts;
+
+    const referencePageIds =
+      await this.pageTransclusionReferencesRepo.findReferencePageIdsByTransclusion(
+        sourcePageId,
+        transclusionId,
+        workspaceId,
+      );
+
+    const candidatePageIds = Array.from(
+      new Set([sourcePageId, ...referencePageIds]),
+    );
+    const accessibleSet = new Set(
+      await this.pagePermissionRepo.filterAccessiblePageIds({
+        pageIds: candidatePageIds,
+        userId: viewerUserId,
+      }),
+    );
+
+    const accessibleIds = candidatePageIds.filter((id) =>
+      accessibleSet.has(id),
+    );
+    if (accessibleIds.length === 0) {
+      return { source: null, references: [] };
+    }
+
+    const rows = await Promise.all(
+      accessibleIds.map((id) =>
+        this.pageRepo.findById(id, { includeSpace: true }),
+      ),
+    );
+    const byId = new Map<string, ReferencingPageInfo>();
+    for (const p of rows) {
+      if (!p || p.deletedAt || p.workspaceId !== workspaceId) continue;
+      const space = (p as Page & { space?: { slug?: string } }).space;
+      byId.set(p.id, {
+        id: p.id,
+        slugId: p.slugId,
+        title: p.title ?? null,
+        icon: p.icon ?? null,
+        spaceId: p.spaceId,
+        spaceSlug: space?.slug ?? null,
+      });
+    }
+
+    const source = byId.get(sourcePageId) ?? null;
+    const references = referencePageIds
+      .map((id) => byId.get(id))
+      .filter((p): p is ReferencingPageInfo => Boolean(p));
+
+    return { source, references };
+  }
+
+  /**
+   * Convert a `transclusionReference` into a self-contained copy on the
+   * reference page: load source content, generate fresh attachment ids, copy storage
+   * files, insert new attachment rows, return rewritten content. The caller
+   * (controller) returns the content blob to the client which then performs
+   * `editor.commands.insertContentAt(range, content)` to replace the
+   * reference node. The next Yjs save naturally cleans up the
+   * page_transclusion_references row, but we also delete it eagerly here so a
+   * crash between server response and client save doesn't leave a stale row.
+   */
+  async unsyncReference(
+    referencePageId: string,
+    sourcePageId: string,
+    transclusionId: string,
+    user: User,
+  ): Promise<{ content: unknown }> {
+    const referencePage = await this.pageRepo.findById(referencePageId);
+    if (!referencePage || referencePage.deletedAt) {
+      throw new NotFoundException('Reference page not found');
+    }
+
+    const sourcePage = await this.pageRepo.findById(sourcePageId);
+    if (!sourcePage || sourcePage.deletedAt) {
+      throw new NotFoundException('Source page not found');
+    }
+
+    if (
+      referencePage.workspaceId !== user.workspaceId ||
+      sourcePage.workspaceId !== user.workspaceId
+    ) {
+      throw new ForbiddenException();
+    }
+
+    await this.pageAccessService.validateCanEdit(referencePage, user);
+    await this.pageAccessService.validateCanView(sourcePage, user);
+
+    const transclusion =
+      await this.pageTransclusionsRepo.findByPageAndTransclusion(
+        sourcePageId,
+        transclusionId,
+      );
+    if (!transclusion) {
+      throw new NotFoundException('Sync block not found');
+    }
+
+    const { content, copies } = rewriteAttachmentsForUnsync(
+      transclusion.content,
+      () => uuid7(),
+    );
+
+    if (copies.length > 0) {
+      const oldIds = copies.map((c) => c.oldAttachmentId);
+      const oldRows = await this.attachmentRepo.findByIds(oldIds);
+      const byOldId = new Map(
+        oldRows
+          .filter((a) => a.pageId === sourcePageId)
+          .map((a) => [a.id, a]),
+      );
+
+      for (const plan of copies) {
+        const old = byOldId.get(plan.oldAttachmentId);
+        if (!old) continue;
+
+        const newFilePath = old.filePath
+          .split(plan.oldAttachmentId)
+          .join(plan.newAttachmentId);
+        try {
+          await this.storageService.copy(old.filePath, newFilePath);
+        } catch (err) {
+          this.logger.error(
+            `unsync: failed to copy attachment ${old.id}`,
+            err as Error,
+          );
+          continue;
+        }
+        await this.attachmentRepo.insertAttachment({
+          id: plan.newAttachmentId,
+          type: old.type,
+          filePath: newFilePath,
+          fileName: old.fileName,
+          fileSize: old.fileSize,
+          mimeType: old.mimeType,
+          fileExt: old.fileExt,
+          creatorId: user.id,
+          workspaceId: referencePage.workspaceId,
+          pageId: referencePageId,
+          spaceId: referencePage.spaceId,
+        });
+      }
+    }
+
+    await this.pageTransclusionReferencesRepo.deleteOne(
+      referencePageId,
+      sourcePageId,
+      transclusionId,
+    );
+
+    return { content };
+  }
+}
@@ -0,0 +1,14 @@
+export type TransclusionLookup =
+  | {
+      sourcePageId: string;
+      transclusionId: string;
+      content: unknown;
+      sourceUpdatedAt: Date;
+    }
+  | { sourcePageId: string; transclusionId: string; status: 'not_found' }
+  | { sourcePageId: string; transclusionId: string; status: 'no_access' };
+
+export type TransclusionNodeSnapshot = {
+  transclusionId: string;
+  content: unknown;
+};
@@ -0,0 +1,95 @@
+import { TransclusionNodeSnapshot } from '../transclusion.types';
+
+const TRANSCLUSION_TYPE = 'transclusionSource';
+const REFERENCE_TYPE = 'transclusionReference';
+
+export type TransclusionReferenceSnapshot = {
+  sourcePageId: string;
+  transclusionId: string;
+};
+
+/**
+ * Walks a ProseMirror JSON document and returns one snapshot per top-level
+ * `transclusion` node. Does not recurse into transclusions (schema disallows
+ * nesting). Skips transclusion nodes without an id (transient state). When
+ * duplicate ids are encountered, the later occurrence wins so the result is
+ * deterministic.
+ */
+export function collectTransclusionsFromPmJson(
+  doc: unknown,
+): TransclusionNodeSnapshot[] {
+  if (!doc || typeof doc !== 'object') return [];
+
+  const byId = new Map<string, TransclusionNodeSnapshot>();
+
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === TRANSCLUSION_TYPE) {
+      const id = node.attrs?.id;
+      if (typeof id === 'string' && id.length > 0) {
+        byId.set(id, {
+          transclusionId: id,
+          content: { type: 'doc', content: node.content ?? [] },
+        });
+      }
+      return; // do not recurse into transclusion children
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(doc);
+  return Array.from(byId.values());
+}
+
+/**
+ * Walks a ProseMirror JSON document and returns one snapshot per unique
+ * `(sourcePageId, transclusionId)` pair found on `transclusionReference`
+ * nodes. The schema forbids references inside a `transclusionSource` so this
+ * walk stops at source boundaries — references can only appear at page level.
+ * Order preserved by first-seen.
+ */
+export function collectReferencesFromPmJson(
+  doc: unknown,
+): TransclusionReferenceSnapshot[] {
+  if (!doc || typeof doc !== 'object') return [];
+
+  const seen = new Set<string>();
+  const out: TransclusionReferenceSnapshot[] = [];
+
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (node.type === REFERENCE_TYPE) {
+      const sourcePageId = node.attrs?.sourcePageId;
+      const transclusionId = node.attrs?.transclusionId;
+      if (
+        typeof sourcePageId === 'string' &&
+        sourcePageId.length > 0 &&
+        typeof transclusionId === 'string' &&
+        transclusionId.length > 0
+      ) {
+        const key = `${sourcePageId}::${transclusionId}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push({ sourcePageId, transclusionId });
+        }
+      }
+      return; // atom node - no children
+    }
+
+    // References cannot live inside a source (schema-enforced); skip recursing
+    // so a malformed inbound doc can't sneak in a nested reference here.
+    if (node.type === TRANSCLUSION_TYPE) return;
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(doc);
+  return out;
+}
@@ -0,0 +1,65 @@
+import { isAttachmentNode } from '../../../../common/helpers/prosemirror/attachment-node-types';
+
+export type AttachmentRewritePlan = {
+  oldAttachmentId: string;
+  newAttachmentId: string;
+};
+
+export type RewriteResult = {
+  content: unknown;
+  copies: AttachmentRewritePlan[];
+};
+
+/**
+ * Walk a ProseMirror JSON tree, rewrite every attachment-like node so its
+ * `attachmentId` (and any `src` substring matching that id) point at a fresh
+ * id. Each unique old id maps to exactly one new id; the caller is responsible
+ * for actually copying the underlying storage file.
+ *
+ * Pure: does not mutate the input. Returns a deep clone.
+ */
+export function rewriteAttachmentsForUnsync(
+  content: unknown,
+  generateId: () => string,
+): RewriteResult {
+  const cloned = content ? JSON.parse(JSON.stringify(content)) : content;
+  const idMap = new Map<string, string>();
+
+  const visit = (node: any): void => {
+    if (!node || typeof node !== 'object') return;
+
+    if (
+      typeof node.type === 'string' &&
+      isAttachmentNode(node.type) &&
+      node.attrs
+    ) {
+      const oldId = node.attrs.attachmentId;
+      if (typeof oldId === 'string' && oldId.length > 0) {
+        let newId = idMap.get(oldId);
+        if (!newId) {
+          newId = generateId();
+          idMap.set(oldId, newId);
+        }
+        node.attrs.attachmentId = newId;
+        if (typeof node.attrs.src === 'string' && node.attrs.src.includes(oldId)) {
+          node.attrs.src = node.attrs.src.split(oldId).join(newId);
+        }
+      }
+    }
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child);
+    }
+  };
+
+  visit(cloned);
+
+  const copies: AttachmentRewritePlan[] = Array.from(idMap.entries()).map(
+    ([oldAttachmentId, newAttachmentId]) => ({
+      oldAttachmentId,
+      newAttachmentId,
+    }),
+  );
+
+  return { content: cloned, copies };
+}
@@ -0,0 +1,8 @@
+import { IsNotEmpty, IsString } from 'class-validator';
+import { LookupDto } from '../../page/transclusion/dto/lookup.dto';
+
+export class ShareTransclusionLookupDto extends LookupDto {
+  @IsString()
+  @IsNotEmpty()
+  shareId!: string;
+}
@@ -21,6 +21,7 @@ import {
  SharePageIdDto,
  UpdateShareDto,
 } from './dto/share.dto';
+import { ShareTransclusionLookupDto } from './dto/share-transclusion-lookup.dto';
 import { PageRepo } from '@docmost/db/repos/page/page.repo';
 import { PagePermissionRepo } from '@docmost/db/repos/page/page-permission.repo';
 import { PageAccessService } from '../page/page-access/page-access.service';
@@ -110,6 +111,20 @@ export class ShareController {
    return share;
  }

+  @Public()
+  @HttpCode(HttpStatus.OK)
+  @Post('/transclusion/lookup')
+  async transclusionLookup(
+    @Body() dto: ShareTransclusionLookupDto,
+    @AuthWorkspace() workspace: Workspace,
+  ) {
+    return this.shareService.lookupTransclusionForShare(
+      dto.shareId,
+      dto.references,
+      workspace.id,
+    );
+  }
+
  @HttpCode(HttpStatus.OK)
  @Post('/for-page')
  async getShareForPage(
@@ -3,9 +3,10 @@ import { ShareController } from './share.controller';
 import { ShareService } from './share.service';
 import { TokenModule } from '../auth/token.module';
 import { ShareSeoController } from './share-seo.controller';
+import { TransclusionModule } from '../page/transclusion/transclusion.module';

@Module({
-  imports: [TokenModule],
+  imports: [TokenModule, TransclusionModule],
  controllers: [ShareController, ShareSeoController],
  providers: [ShareService],
  exports: [ShareService],
@@ -24,6 +24,8 @@ import { updateAttachmentAttr } from './share.util';
 import { Page } from '@docmost/db/types/entity.types';
 import { validate as isValidUUID } from 'uuid';
 import { sql } from 'kysely';
+import { TransclusionService } from '../page/transclusion/transclusion.service';
+import { TransclusionLookup } from '../page/transclusion/transclusion.types';

@Injectable()
 export class ShareService {
@@ -35,6 +37,7 @@ export class ShareService {
    private readonly pagePermissionRepo: PagePermissionRepo,
    @InjectKysely() private readonly db: KyselyDB,
    private readonly tokenService: TokenService,
+    private readonly transclusionService: TransclusionService,
  ) {}

  async getShareTree(shareId: string, workspaceId: string) {
@@ -281,6 +284,113 @@ export class ShareService {
    return ancestor;
  }

+  /**
+   * Resolve transclusion content for a public share viewer. Each requested
+   * source page must itself be reachable via the share graph (its own share
+   * or a shared ancestor with `includeSubPages`), in the same workspace as
+   * the requesting share, with sharing allowed and no restricted ancestors.
+   * Sources that don't qualify come back as `no_access` so the editor renders
+   * the existing placeholder. The viewer's personal permissions are
+   * intentionally ignored — share-served content is gated only by the share
+   * graph.
+   */
+  async lookupTransclusionForShare(
+    shareId: string,
+    references: Array<{ sourcePageId: string; transclusionId: string }>,
+    workspaceId: string,
+  ): Promise<{ items: TransclusionLookup[] }> {
+    const share = await this.shareRepo.findById(shareId);
+    if (!share || share.workspaceId !== workspaceId) {
+      throw new NotFoundException('Share not found');
+    }
+    const sharingAllowed = await this.isSharingAllowed(
+      workspaceId,
+      share.spaceId,
+    );
+    if (!sharingAllowed) {
+      throw new NotFoundException('Share not found');
+    }
+
+    const candidatePageIds = Array.from(
+      new Set(references.map((r) => r.sourcePageId)),
+    );
+
+    // TODO: Reduce DB round trips at scale by replacing the per-page chain
+    // with bulk repo methods that take all candidate pageIds at once:
+    //   - shareRepo.getSharesForPages(pageIds, workspaceId): Map<pageId, share>
+    //   - pagePermissionRepo.filterRestrictedPageIds(pageIds): Set<pageId>
+    //   - isSharingAllowed for the distinct spaceIds in one query
+    // Brings per-request trip count from ~2N+1 (parallel) to 3 (constant)
+    // for N unique candidate pages. Worth doing if profiling ever flags it.
+
+    // Most candidates will share the host share's space, so cache by spaceId
+    // and seed with the host space we just verified. Stores in-flight
+    // promises so concurrent chains de-dupe at the request boundary.
+    const sharingAllowedCache = new Map<string, Promise<boolean>>();
+    sharingAllowedCache.set(share.spaceId, Promise.resolve(true));
+    const isSharingAllowedFor = (spaceId: string) => {
+      const cached = sharingAllowedCache.get(spaceId);
+      if (cached) return cached;
+      const p = this.isSharingAllowed(workspaceId, spaceId);
+      sharingAllowedCache.set(spaceId, p);
+      return p;
+    };
+
+    // Per-page chains run in parallel; wall time is the slowest chain, not
+    // the sum. Each chain still does its 2–3 queries sequentially because
+    // each step gates the next.
+    const accessibleResults = await Promise.all(
+      candidatePageIds.map(async (pageId) => {
+        const sourceShare = await this.getShareForPage(pageId, workspaceId);
+        if (!sourceShare) return null;
+        if (!(await isSharingAllowedFor(sourceShare.spaceId))) return null;
+        const restricted =
+          await this.pagePermissionRepo.hasRestrictedAncestor(pageId);
+        if (restricted) return null;
+        return pageId;
+      }),
+    );
+    const accessibleSet = new Set<string>(
+      accessibleResults.filter((id): id is string => id !== null),
+    );
+
+    const { items } = await this.transclusionService.lookupWithAccessSet(
+      references,
+      accessibleSet,
+      workspaceId,
+    );
+
+    // Sanitize each item's content for public delivery
+    // generate per-attachment tokens scoped to the source page
+    // and strip comment marks.
+    const tokenized = await Promise.all(
+      items.map(async (item) => {
+        if ('status' in item) return item;
+        const doc = await this.prepareContentForShare(
+          item.content,
+          item.sourcePageId,
+          workspaceId,
+        );
+        return { ...item, content: doc?.toJSON() ?? item.content };
+      }),
+    );
+
+    // Collapse `not_found` to `no_access` for share viewers so the response
+    // can't be used to tell "page is shared but transclusion id doesn't
+    // match" from "page isn't shared at all".
+    const sanitized = tokenized.map((item) =>
+      'status' in item && item.status === 'not_found'
+        ? {
+            sourcePageId: item.sourcePageId,
+            transclusionId: item.transclusionId,
+            status: 'no_access' as const,
+          }
+        : item,
+    );
+
+    return { items: sanitized };
+  }
+
  async isSharingAllowed(
    workspaceId: string,
    spaceId: string,
@@ -307,35 +417,64 @@ export class ShareService {
  }

  async updatePublicAttachments(page: Page): Promise<any> {
-    const prosemirrorJson = getProsemirrorContent(page.content);
-    const attachmentIds = getAttachmentIds(prosemirrorJson);
-    const attachmentMap = new Map<string, string>();
+    const doc = await this.prepareContentForShare(
+      page.content,
+      page.id,
+      page.workspaceId,
+    );
+    return doc?.toJSON() ?? page.content;
+  }

+  /**
+   * Prepare a ProseMirror JSON doc for delivery to a public share viewer.
+   * Performs the two transforms required by the share threat model:
+   *
+   * 1. Mint a per-attachment public token scoped to `attachmentOwnerPageId`
+   *    and rewrite each attachment node's `src`/`url` to the public form
+   *    (`/files/public/...?jwt=`). The receiver enforces
+   *    `attachment.pageId === token.pageId`, which is why the owner page id
+   *    has to be passed in explicitly: the host page for direct shared
+   *    content, the source page for transcluded source-block content
+   *    (attachments in a sync block were uploaded onto the source page).
+   *
+   * 2. Strip `comment` marks. Comments are internal-team metadata and must
+   *    not leak structure (existence, location, count, resolved state, or
+   *    comment ids) to public viewers.
+   *
+   * Both share-content paths — the host page (`updatePublicAttachments`) and
+   * the share-scoped transclusion lookup (`lookupTransclusionForShare`) —
+   * call into this single helper so the two paths can never drift on
+   * sanitization rules.
+   */
+  private async prepareContentForShare(
+    content: unknown,
+    attachmentOwnerPageId: string,
+    workspaceId: string,
+  ): Promise<Node | null> {
+    const pmJson = getProsemirrorContent(content);
+    const attachmentIds = getAttachmentIds(pmJson);
+
+    const tokenMap = new Map<string, string>();
    await Promise.all(
      attachmentIds.map(async (attachmentId: string) => {
        const token = await this.tokenService.generateAttachmentToken({
          attachmentId,
-          pageId: page.id,
-          workspaceId: page.workspaceId,
+          pageId: attachmentOwnerPageId,
+          workspaceId,
        });
-        attachmentMap.set(attachmentId, token);
+        tokenMap.set(attachmentId, token);
      }),
    );

-    const doc = jsonToNode(prosemirrorJson);
-
+    const doc = jsonToNode(pmJson);
    doc?.descendants((node: Node) => {
      if (!isAttachmentNode(node.type.name)) return;
-
-      const attachmentId = node.attrs.attachmentId;
-      const token = attachmentMap.get(attachmentId);
+      const token = tokenMap.get(node.attrs.attachmentId);
      if (!token) return;
-
      updateAttachmentAttr(node, 'src', token);
      updateAttachmentAttr(node, 'url', token);
    });

-    const removeCommentMarks = removeMarkTypeFromDoc(doc, 'comment');
-    return removeCommentMarks.toJSON();
+    return doc ? removeMarkTypeFromDoc(doc, 'comment') : null;
  }
 }
@@ -11,6 +11,8 @@ import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
 import { PageRepo } from './repos/page/page.repo';
 import { PagePermissionRepo } from './repos/page/page-permission.repo';
 import { CommentRepo } from './repos/comment/comment.repo';
+import { PageTransclusionsRepo } from './repos/page-transclusions/page-transclusions.repo';
+import { PageTransclusionReferencesRepo } from './repos/page-transclusions/page-transclusion-references.repo';
 import { PageHistoryRepo } from './repos/page/page-history.repo';
 import { AttachmentRepo } from './repos/attachment/attachment.repo';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -75,6 +77,8 @@ import { normalizePostgresUrl } from '../common/helpers';
    SpaceMemberRepo,
    PageRepo,
    PagePermissionRepo,
+    PageTransclusionsRepo,
+    PageTransclusionReferencesRepo,
    PageHistoryRepo,
    CommentRepo,
    FavoriteRepo,
@@ -97,6 +101,8 @@ import { normalizePostgresUrl } from '../common/helpers';
    SpaceMemberRepo,
    PageRepo,
    PagePermissionRepo,
+    PageTransclusionsRepo,
+    PageTransclusionReferencesRepo,
    PageHistoryRepo,
    CommentRepo,
    FavoriteRepo,
@@ -0,0 +1,76 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('page_transclusions')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.notNull().references('workspaces.id').onDelete('cascade'),
+    )
+    .addColumn('page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('transclusion_id', 'varchar', (col) => col.notNull())
+    .addColumn('content', 'jsonb', (col) => col.notNull())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addUniqueConstraint('page_transclusions_page_transclusion_unique', [
+      'page_id',
+      'transclusion_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusions_workspace')
+    .on('page_transclusions')
+    .column('workspace_id')
+    .execute();
+
+  await db.schema
+    .createTable('page_transclusion_references')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.notNull().references('workspaces.id').onDelete('cascade'),
+    )
+    .addColumn('reference_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('source_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('transclusion_id', 'varchar', (col) => col.notNull())
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addUniqueConstraint('page_transclusion_references_unique', [
+      'reference_page_id',
+      'source_page_id',
+      'transclusion_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_source')
+    .on('page_transclusion_references')
+    .columns(['source_page_id', 'transclusion_id'])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_workspace')
+    .on('page_transclusion_references')
+    .column('workspace_id')
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('page_transclusion_references').execute();
+  await db.schema.dropTable('page_transclusions').execute();
+}
@@ -89,6 +89,22 @@ export class AttachmentRepo {
      .execute();
  }

+  async findByIds(
+    ids: string[],
+    opts?: {
+      trx?: KyselyTransaction;
+    },
+  ): Promise<Attachment[]> {
+    if (ids.length === 0) return [];
+    const db = dbOrTx(this.db, opts?.trx);
+
+    return db
+      .selectFrom('attachments')
+      .select(this.baseFields)
+      .where('id', 'in', ids)
+      .execute();
+  }
+
  async findByAiChatId(
    aiChatId: string,
    opts?: {
@@ -0,0 +1,98 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { dbOrTx } from '@docmost/db/utils';
+import {
+  InsertablePageTransclusionReference,
+  PageTransclusionReference,
+} from '@docmost/db/types/entity.types';
+
+export type TransclusionReferenceKey = {
+  sourcePageId: string;
+  transclusionId: string;
+};
+
+@Injectable()
+export class PageTransclusionReferencesRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async findByReferencePageId(
+    referencePageId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusionReference[]> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusionReferences')
+      .selectAll()
+      .where('referencePageId', '=', referencePageId)
+      .execute();
+  }
+
+  async findReferencePageIdsByTransclusion(
+    sourcePageId: string,
+    transclusionId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<string[]> {
+    const rows = await dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusionReferences')
+      .select('referencePageId')
+      .distinct()
+      .where('workspaceId', '=', workspaceId)
+      .where('sourcePageId', '=', sourcePageId)
+      .where('transclusionId', '=', transclusionId)
+      .execute();
+    return rows.map((r) => r.referencePageId);
+  }
+
+  async insertMany(
+    rows: InsertablePageTransclusionReference[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (rows.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .insertInto('pageTransclusionReferences')
+      .values(rows)
+      .onConflict((oc) =>
+        oc
+          .columns(['referencePageId', 'sourcePageId', 'transclusionId'])
+          .doNothing(),
+      )
+      .execute();
+  }
+
+  async deleteByReferenceAndKeys(
+    referencePageId: string,
+    keys: TransclusionReferenceKey[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (keys.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .deleteFrom('pageTransclusionReferences')
+      .where('referencePageId', '=', referencePageId)
+      .where((eb) =>
+        eb.or(
+          keys.map((k) =>
+            eb.and([
+              eb('sourcePageId', '=', k.sourcePageId),
+              eb('transclusionId', '=', k.transclusionId),
+            ]),
+          ),
+        ),
+      )
+      .execute();
+  }
+
+  async deleteOne(
+    referencePageId: string,
+    sourcePageId: string,
+    transclusionId: string,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    await dbOrTx(this.db, trx)
+      .deleteFrom('pageTransclusionReferences')
+      .where('referencePageId', '=', referencePageId)
+      .where('sourcePageId', '=', sourcePageId)
+      .where('transclusionId', '=', transclusionId)
+      .execute();
+  }
+}
@@ -0,0 +1,112 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { dbOrTx } from '@docmost/db/utils';
+import {
+  InsertablePageTransclusion,
+  PageTransclusion,
+  UpdatablePageTransclusion,
+} from '@docmost/db/types/entity.types';
+
+@Injectable()
+export class PageTransclusionsRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async findByPageId(
+    pageId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusion[]> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusions')
+      .selectAll()
+      .where('pageId', '=', pageId)
+      .orderBy('createdAt', 'asc')
+      .execute();
+  }
+
+  async findByPageAndTransclusion(
+    pageId: string,
+    transclusionId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusion | undefined> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusions')
+      .selectAll()
+      .where('pageId', '=', pageId)
+      .where('transclusionId', '=', transclusionId)
+      .executeTakeFirst();
+  }
+
+  async findManyByPageAndTransclusion(
+    keys: Array<{ pageId: string; transclusionId: string }>,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusion[]> {
+    if (keys.length === 0) return [];
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusions')
+      .selectAll()
+      .where('workspaceId', '=', workspaceId)
+      .where((eb) =>
+        eb.or(
+          keys.map((k) =>
+            eb.and([
+              eb('pageId', '=', k.pageId),
+              eb('transclusionId', '=', k.transclusionId),
+            ]),
+          ),
+        ),
+      )
+      .execute();
+  }
+
+  async insert(
+    data: InsertablePageTransclusion,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusion> {
+    return dbOrTx(this.db, trx)
+      .insertInto('pageTransclusions')
+      .values(data)
+      .returningAll()
+      .executeTakeFirstOrThrow();
+  }
+
+  async insertMany(
+    data: InsertablePageTransclusion[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (data.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .insertInto('pageTransclusions')
+      .values(data)
+      .execute();
+  }
+
+  async update(
+    pageId: string,
+    transclusionId: string,
+    data: UpdatablePageTransclusion,
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    await dbOrTx(this.db, trx)
+      .updateTable('pageTransclusions')
+      .set({ ...data, updatedAt: new Date() })
+      .where('pageId', '=', pageId)
+      .where('transclusionId', '=', transclusionId)
+      .execute();
+  }
+
+  async deleteByPageAndTransclusionIds(
+    pageId: string,
+    transclusionIds: string[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (transclusionIds.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .deleteFrom('pageTransclusions')
+      .where('pageId', '=', pageId)
+      .where('transclusionId', 'in', transclusionIds)
+      .execute();
+  }
+
+}
@@ -100,6 +100,30 @@ export class PageRepo {
    return query.executeTakeFirst();
  }

+  async findManyByIds(
+    pageIds: string[],
+    opts?: {
+      trx?: KyselyTransaction;
+      workspaceId?: string;
+    },
+  ): Promise<Page[]> {
+    if (pageIds.length === 0) return [];
+    const db = dbOrTx(this.db, opts?.trx);
+
+    let query = db
+      .selectFrom('pages')
+      .select(this.baseFields)
+      .where('id', 'in', pageIds);
+
+    if (opts?.workspaceId) {
+      query = query
+        .where('workspaceId', '=', opts.workspaceId)
+        .where('deletedAt', 'is', null);
+    }
+
+    return query.execute();
+  }
+
  async updatePage(
    updatablePage: UpdatablePage,
    pageId: string,
@@ -228,6 +228,25 @@ export interface GroupUsers {
  userId: string;
 }

+export interface PageTransclusionReferences {
+  createdAt: Generated<Timestamp>;
+  transclusionId: string;
+  referencePageId: string;
+  id: Generated<string>;
+  sourcePageId: string;
+  workspaceId: string;
+}
+
+export interface PageTransclusions {
+  content: Json;
+  createdAt: Generated<Timestamp>;
+  transclusionId: string;
+  id: Generated<string>;
+  pageId: string;
+  updatedAt: Generated<Timestamp>;
+  workspaceId: string;
+}
+
 export interface PageHistory {
  content: Json | null;
  contributorIds: Generated<string[] | null>;
@@ -571,6 +590,8 @@ export interface DB {
  groupUsers: GroupUsers;
  notifications: Notifications;
  pageAccess: PageAccess;
+  pageTransclusionReferences: PageTransclusionReferences;
+  pageTransclusions: PageTransclusions;
  pagePermissions: PagePermissions;
  pageHistory: PageHistory;
  pageVerifications: PageVerifications;
@@ -7,6 +7,8 @@ import {
  Groups,
  Notifications,
  PageAccess as _PageAccess,
+  PageTransclusions,
+  PageTransclusionReferences,
  PagePermissions as _PagePermissions,
  PageVerifications as _PageVerifications,
  PageVerifiers as _PageVerifiers,
@@ -145,6 +147,18 @@ export type Favorite = Selectable<Favorites>;
 export type InsertableFavorite = Insertable<Favorites>;
 export type UpdatableFavorite = Updateable<Omit<Favorites, 'id'>>;

+// Page Transclusion
+export type PageTransclusion = Selectable<PageTransclusions>;
+export type InsertablePageTransclusion = Insertable<PageTransclusions>;
+export type UpdatablePageTransclusion = Updateable<Omit<PageTransclusions, 'id'>>;
+
+// Page Transclusion Reference
+export type PageTransclusionReference = Selectable<PageTransclusionReferences>;
+export type InsertablePageTransclusionReference = Insertable<PageTransclusionReferences>;
+export type UpdatablePageTransclusionReference = Updateable<
+  Omit<PageTransclusionReferences, 'id'>
+>;
+
 // File Task
 export type FileTask = Selectable<FileTasks>;
 export type InsertableFileTask = Insertable<FileTasks>;
@@ -112,7 +112,10 @@ export class EnvironmentService {
  }

  getAwsS3ForcePathStyle(): boolean {
-    return this.configService.get<boolean>('AWS_S3_FORCE_PATH_STYLE');
+    const forcePathStyle = this.configService
+      .get<string>('AWS_S3_FORCE_PATH_STYLE', 'false')
+      .toLowerCase();
+    return forcePathStyle === 'true';
  }

  getAwsS3Url(): string {
@@ -131,6 +134,17 @@ export class EnvironmentService {
    return this.configService.get<string>('MAIL_FROM_NAME', 'Docmost');
  }

+  getMailBlockedRecipientDomains(): string[] {
+    const raw = this.configService.get<string>(
+      'MAIL_BLOCKED_RECIPIENT_DOMAINS',
+      '',
+    );
+    return raw
+      .split(',')
+      .map((d) => d.trim().toLowerCase())
+      .filter(Boolean);
+  }
+
  getSmtpHost(): string {
    return this.configService.get<string>('SMTP_HOST');
  }
@@ -6,7 +6,7 @@ import { EnvironmentService } from '../environment/environment.service';
 import { InjectQueue } from '@nestjs/bullmq';
 import { QueueName, QueueJob } from '../queue/constants';
 import { Queue } from 'bullmq';
-import { render } from '@react-email/render';
+import { render } from 'react-email';

@Injectable()
 export class MailService {
@@ -17,6 +17,10 @@ export class MailService {
  ) {}

  async sendEmail(message: MailMessage): Promise<void> {
+    if (this.isRecipientBlocked(message.to)) {
+      return;
+    }
+
    if (message.template) {
      // in case this method is used directly. we do not send the tsx template from queue
      message.html = await render(message.template, {
@@ -35,6 +39,10 @@ export class MailService {
  }

  async sendToQueue(message: MailMessage): Promise<void> {
+    if (this.isRecipientBlocked(message.to)) {
+      return;
+    }
+
    if (message.template) {
      // transform the React object because it gets lost when sent via the queue
      message.html = await render(message.template, {
@@ -47,4 +55,11 @@ export class MailService {
    }
    await this.emailQueue.add(QueueJob.SEND_EMAIL, message);
  }
+
+  private isRecipientBlocked(to: string): boolean {
+    const blocked = this.environmentService.getMailBlockedRecipientDomains();
+    if (blocked.length === 0) return false;
+    const domain = to?.split('@')[1]?.toLowerCase();
+    return !!domain && blocked.includes(domain);
+  }
 }
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Button, Link, Section, Text } from '@react-email/components';
+import { Button, Link, Section, Text } from 'react-email';
 import * as React from 'react';
 import { button, content, paragraph } from '../css/styles';
 import { MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Link, Section, Text } from '@react-email/components';
+import { Link, Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, link, paragraph } from '../css/styles';
 import { getGreetingName, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Link, Section, Text } from '@react-email/components';
+import { Link, Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, link, paragraph } from '../css/styles';
 import { EmailButton, getGreetingName, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -1,4 +1,4 @@
-import { Section, Text } from '@react-email/components';
+import { Section, Text } from 'react-email';
 import * as React from 'react';
 import { content, paragraph } from '../css/styles';
 import { EmailButton, MailBody } from '../partials/partials';
@@ -7,7 +7,7 @@ import {
  Row,
  Section,
  Text,
-} from '@react-email/components';
+} from 'react-email';
 import * as React from 'react';

 interface MailBodyProps {
@@ -50,6 +50,14 @@ async function bootstrap() {
  await app.register(fastifyMultipart);
  await app.register(fastifyCookie);

+  app
+    .getHttpAdapter()
+    .getInstance()
+    .addHook('onRequest', (request, _reply, done) => {
+      (request.raw as any).ip = request.ip;
+      done();
+    });
+
  app
    .getHttpAdapter()
    .getInstance()
@@ -21,6 +21,7 @@ export * from "./lib/markdown";
 export * from "./lib/search-and-replace";
 export * from "./lib/embed-provider";
 export * from "./lib/subpages";
+export * from "./lib/transclusion";
 export * from "./lib/highlight";
 export * from "./lib/heading/heading";
 export * from "./lib/unique-id";
@@ -0,0 +1,41 @@
+/**
+ * Top-level block node types allowed inside a `transclusionSource`.
+ * Notably excludes:
+ * - `transclusionSource` — sync blocks cannot wrap other sync blocks (sources are leaves).
+ * - `transclusionReference` — sync blocks cannot transclude other sync blocks,
+ *   which keeps the transclusion graph acyclic and lets the renderer skip
+ *   cycle-aware traversal entirely.
+ *
+ * Also excludes child-only nodes (`listItem`, `tableRow`, `column`, etc.)
+ * — they're already constrained by their parent containers.
+ */
+export const TRANSCLUSION_SOURCE_ALLOWED_NODE_TYPES = [
+  'paragraph',
+  'heading',
+  'blockquote',
+  'codeBlock',
+  'horizontalRule',
+  'bulletList',
+  'orderedList',
+  'taskList',
+  'image',
+  'video',
+  'audio',
+  'attachment',
+  'callout',
+  'details',
+  'embed',
+  'mathBlock',
+  'table',
+  'drawio',
+  'excalidraw',
+  'pdf',
+  'subpages',
+  'columns',
+  'youtube',
+] as const;
+
+export type TransclusionSourceAllowedNodeType =
+  (typeof TRANSCLUSION_SOURCE_ALLOWED_NODE_TYPES)[number];
+
+export const TRANSCLUSION_SOURCE_CONTENT_EXPRESSION = `(${TRANSCLUSION_SOURCE_ALLOWED_NODE_TYPES.join(' | ')})+`;
@@ -0,0 +1,3 @@
+export * from "./constants";
+export * from "./transclusion-source";
+export * from "./transclusion-reference";
@@ -0,0 +1,92 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+
+export interface TransclusionReferenceOptions {
+  HTMLAttributes: Record<string, any>;
+  view: any;
+}
+
+export interface TransclusionReferenceAttributes {
+  sourcePageId?: string | null;
+  transclusionId?: string | null;
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    transclusionReference: {
+      insertTransclusionReference: (
+        attributes: TransclusionReferenceAttributes,
+      ) => ReturnType;
+    };
+  }
+}
+
+export const TransclusionReference = Node.create<TransclusionReferenceOptions>({
+  name: "transclusionReference",
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      view: null,
+    };
+  },
+
+  group: "block",
+  atom: true,
+  selectable: true,
+  draggable: false,
+
+  addAttributes() {
+    return {
+      sourcePageId: {
+        default: null,
+        parseHTML: (el) => el.getAttribute("data-source-page-id"),
+        renderHTML: (attrs) =>
+          attrs.sourcePageId
+            ? { "data-source-page-id": attrs.sourcePageId }
+            : {},
+      },
+      transclusionId: {
+        default: null,
+        parseHTML: (el) => el.getAttribute("data-transclusion-id"),
+        renderHTML: (attrs) =>
+          attrs.transclusionId
+            ? { "data-transclusion-id": attrs.transclusionId }
+            : {},
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: `div[data-type="${this.name}"]` }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      mergeAttributes(
+        { "data-type": this.name },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+    ];
+  },
+
+  addCommands() {
+    return {
+      insertTransclusionReference:
+        (attributes) =>
+        ({ commands }) =>
+          commands.insertContent({
+            type: this.name,
+            attrs: attributes,
+          }),
+    };
+  },
+
+  addNodeView() {
+    if (!this.options.view) return null;
+    this.editor.isInitialized = true;
+    return ReactNodeViewRenderer(this.options.view);
+  },
+});
@@ -0,0 +1,134 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { ReactNodeViewRenderer } from "@tiptap/react";
+import { TRANSCLUSION_SOURCE_CONTENT_EXPRESSION } from "./constants";
+
+export interface TransclusionSourceOptions {
+  HTMLAttributes: Record<string, any>;
+  view: any;
+}
+
+export interface TransclusionSourceAttributes {
+  id?: string | null;
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    transclusionSource: {
+      insertTransclusionSource: (
+        attributes?: TransclusionSourceAttributes,
+      ) => ReturnType;
+      toggleTransclusionSource: () => ReturnType;
+      unsyncTransclusionSource: () => ReturnType;
+    };
+  }
+}
+
+export const TransclusionSource = Node.create<TransclusionSourceOptions>({
+  name: "transclusionSource",
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+      view: null,
+    };
+  },
+
+  group: "block",
+  // Schema-enforced allow-list. Excludes `transclusionSource` (no nesting)
+  content: TRANSCLUSION_SOURCE_CONTENT_EXPRESSION,
+  defining: true,
+  isolating: true,
+
+  addAttributes() {
+    return {
+      id: {
+        default: null,
+        parseHTML: (el) => el.getAttribute("data-id"),
+        renderHTML: (attrs) =>
+          attrs.id ? { "data-id": attrs.id } : {},
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: `div[data-type="${this.name}"]` }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      "div",
+      mergeAttributes(
+        { "data-type": this.name },
+        this.options.HTMLAttributes,
+        HTMLAttributes,
+      ),
+      0,
+    ];
+  },
+
+  addCommands() {
+    return {
+      insertTransclusionSource:
+        (attributes) =>
+        ({ commands, state, chain }) => {
+          const { $from } = state.selection;
+          for (let depth = $from.depth; depth > 0; depth -= 1) {
+            if ($from.node(depth).type.name === this.name) return false;
+          }
+
+          const node = {
+            type: this.name,
+            attrs: attributes ?? {},
+            content: [{ type: "paragraph" }],
+          };
+
+          const parent = $from.parent;
+          const isEmptyParagraph =
+            parent.type.name === "paragraph" && parent.content.size === 0;
+
+          if (isEmptyParagraph) {
+            return chain()
+              .insertContentAt(
+                { from: $from.before(), to: $from.after() },
+                node,
+              )
+              .run();
+          }
+
+          return commands.insertContent(node);
+        },
+      toggleTransclusionSource:
+        () =>
+        ({ commands }) =>
+          commands.toggleWrap(this.name),
+      unsyncTransclusionSource:
+        () =>
+        ({ state, tr, dispatch }) => {
+          const { $from } = state.selection;
+          // Walk up to the nearest source wrapper.
+          let depth = $from.depth;
+          while (depth > 0 && $from.node(depth).type.name !== this.name) {
+            depth -= 1;
+          }
+          if (depth === 0) return false;
+
+          const node = $from.node(depth);
+          const start = $from.before(depth);
+          const end = start + node.nodeSize;
+
+          if (dispatch) {
+            tr.replaceWith(start, end, node.content);
+            dispatch(tr);
+          }
+          return true;
+        },
+    };
+  },
+
+  addNodeView() {
+    if (!this.options.view) return null;
+    // Force the react node view to render immediately using flush sync
+    this.editor.isInitialized = true;
+    return ReactNodeViewRenderer(this.options.view);
+  },
+});
Author	SHA1	Message	Date
Philipinho	b246f3311d	fix collab module error	2026-05-08 01:35:50 +01:00
Philipinho	159920bc84	fix: scope synced blocks to workspace, gate unsync on edit permission	2026-05-08 01:15:13 +01:00
Philipinho	09f2b84988	feat: enforce strict transclusion schema	2026-05-08 00:26:31 +01:00
Philipinho	c5ebc29d6b	translation	2026-05-07 23:26:16 +01:00
Philipinho	b6418a4e74	make placeholders smaller	2026-05-07 23:16:22 +01:00
Philipinho	6c966651b0	fix:remove name	2026-05-07 23:15:40 +01:00
Philipinho	94ecc98617	feat: synced blocks (transclusion)	2026-05-07 22:20:29 +01:00
Philipinho	ec51ca7815	fix request ip	2026-05-07 22:09:32 +01:00
Philipinho	2b63137217	mail	2026-05-07 18:13:24 +01:00
Philipinho	3227bc6059	fix: a11y	2026-05-04 23:04:26 +01:00
Philip Okugbe	73dc62bca3	update react-email (#2149 )	2026-05-04 22:26:53 +01:00
Philipinho	3c74bb3dee	update package	2026-05-04 22:09:19 +01:00
Philip Okugbe	dbe6c2d6ba	feat: A11y fixes (#2148 )	2026-05-04 21:21:37 +01:00
Sarthak Chaturvedi	fe18f22dc6	fix: prevent code block deletion when adding inline comments in read mode (#2146 )	2026-05-04 21:14:21 +01:00
Philipinho	fcef0c6b96	fix: S3	2026-05-04 20:57:35 +01:00