feat(editor): indentation (#2174)

* switch to default codeblock tab handling

* feat(editor): indentation

apps/client/package.json

@@ -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": {

apps/client/public/locales/en-US/translation.json

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

apps/client/src/components/ui/custom-avatar.tsx

@@ -42,6 +42,11 @@ function pickInitialsColor(name: string) {
   return SAFE_INITIALS_COLORS[hashName(name) % SAFE_INITIALS_COLORS.length];
 }
 
+function sanitizeInitialsSource(name: string) {
+  const sanitized = name.replace(/[^\p{L}\p{N}\s]/gu, " ").trim();
+  return sanitized || name;
+}
+
 export const CustomAvatar = React.forwardRef<
   HTMLInputElement,
   CustomAvatarProps
@@ -49,12 +54,13 @@ export const CustomAvatar = React.forwardRef<
   const avatarLink = getAvatarUrl(avatarUrl, type);
   const resolvedColor =
     !color || color === "initials" ? pickInitialsColor(name ?? "") : color;
+  const initialsSource = sanitizeInitialsSource(name ?? "");
 
   return (
     <Avatar
       ref={ref}
       src={avatarLink}
-      name={name}
+      name={initialsSource}
       alt={name}
       color={resolvedColor}
       {...props}

apps/client/src/ee/ai-chat/components/ai-chat-sidebar.tsx

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

apps/client/src/ee/ai-chat/components/aside-chat-panel.tsx

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

apps/client/src/ee/ai-chat/components/chat-empty-state.tsx

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

apps/client/src/ee/ai-chat/components/chat-input.tsx

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

apps/client/src/ee/ai-chat/components/chat-tool-group.tsx

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

apps/client/src/ee/ai-chat/styles/ai-chat.module.css

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

apps/client/src/ee/ai-chat/styles/chat-input.module.css

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

apps/client/src/ee/ai-chat/styles/chat-sidebar.module.css

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

apps/client/src/features/editor/components/bubble-menu/node-selector.tsx

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

apps/client/src/features/editor/components/emoji-menu/emoji-items.ts

@@ -1,30 +1,26 @@
 import { CommandProps, EmojiMenuItemType } from "./types";
-import { SearchIndex } from "emoji-mart";
+import { buildEmojiIndex, getFrequentlyUsedEmoji, sortFrequentlyUsedEmoji } from "./utils";
-import { getFrequentlyUsedEmoji, sortFrequentlyUsedEmoji } from "./utils";
 
-const searchEmoji = async (value: string): Promise<EmojiMenuItemType[]> => {
+const MAX_RESULTS = 5;
-  if (value === "") {
+
-    const frequentlyUsedEmoji = getFrequentlyUsedEmoji();
+const searchEmoji = async (query: string): Promise<EmojiMenuItemType[]> => {
-    return sortFrequentlyUsedEmoji(frequentlyUsedEmoji);
+  if (query === "") {
+    return sortFrequentlyUsedEmoji(getFrequentlyUsedEmoji());
   }
 
-  const emojis = await SearchIndex.search(value);
+  const q = query.toLowerCase();
-  const results = emojis.map((emoji: any) => {
+  const index = await buildEmojiIndex();
-    return {
-      id: emoji.id,
-      emoji: emoji.skins[0].native,
-      command: ({ editor, range }: CommandProps) => {
-        editor
-          .chain()
-          .focus()
-          .deleteRange(range)
-          .insertContent(emoji.skins[0].native + " ")
-          .run();
-      },
-    };
-  });
 
-  return results;
+  return index
+    .filter((e) => e.name.includes(q) || e.id.includes(q))
+    .slice(0, MAX_RESULTS)
+    .map((entry) => ({
+      id: entry.id,
+      emoji: entry.native,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).insertContent(entry.native + " ").run();
+      },
+    }));
 };
 
 export const getEmojiItems = async ({

apps/client/src/features/editor/components/emoji-menu/emoji-list.tsx

@@ -1,154 +1,208 @@
-import {
+import { Loader, Paper, ScrollArea, Text, UnstyledButton } from "@mantine/core";
-  ActionIcon,
-  Loader,
-  Paper,
-  ScrollArea,
-  SimpleGrid,
-  Text,
-} from "@mantine/core";
-import { EmojiMenuItemType } from "./types";
 import clsx from "clsx";
-import classes from "./emoji-menu.module.css";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { GRID_COLUMNS, incrementEmojiUsage } from "./utils";
+import { useTranslation } from "react-i18next";
+import { EmojiMenuItemType } from "./types";
+import {
+  EmojiCategory,
+  EmojiIndexEntry,
+  getEmojiCategories,
+  incrementEmojiUsage,
+} from "./utils";
+import classes from "./emoji-menu.module.css";
 
-const EmojiList = ({
+const COLS = 8;
+
+const CAT_ICONS: Record<string, string> = {
+  people:   "😀",
+  nature:   "🌿",
+  foods:    "🍕",
+  activity: "🎮",
+  places:   "🗺️",
+  objects:  "🔧",
+  symbols:  "💯",
+  flags:    "🚩",
+};
+
+function EmojiList({
   items,
   isLoading,
   command,
   editor,
   range,
+  query = "",
 }: {
   items: EmojiMenuItemType[];
   isLoading: boolean;
-  command: any;
+  command: (item: EmojiMenuItemType) => void;
   editor: any;
   range: any;
-}) => {
+  query?: string;
-  const [selectedIndex, setSelectedIndex] = useState(0);
+}) {
-  const viewportRef = useRef<HTMLDivElement>(null);
+  const { t } = useTranslation();
+  const [idx, setIdx] = useState(0);
+  const [cats, setCats] = useState<EmojiCategory[]>([]);
+  const [activeCat, setActiveCat] = useState("");
+  const [focusZone, setFocusZone] = useState<"grid" | "tabs">("grid");
+  const listViewport = useRef<HTMLDivElement>(null);
+  const gridViewport = useRef<HTMLDivElement>(null);
+  const catBar = useRef<HTMLDivElement>(null);
 
-  const selectItem = useCallback(
+  const searching = query.length > 0;
-    (index: number) => {
+  const browseLoading = !searching && cats.length === 0;
-      const item = items[index];
+  const gridItems = cats.find((c) => c.id === activeCat)?.emojis ?? [];
-      if (item) {
+
-        command(item);
+  useEffect(() => {
-        incrementEmojiUsage(item.id);
+    getEmojiCategories().then((data) => {
-      }
+      setCats(data);
+      setActiveCat((prev) => prev || data[0]?.id || "");
+    });
+  }, []);
+
+  useEffect(() => { setIdx(0); }, [query, activeCat]);
+
+  useEffect(() => { if (searching) setFocusZone("grid"); }, [searching]);
+
+  useEffect(() => {
+    if (focusZone !== "tabs") return;
+    catBar.current?.querySelector<HTMLElement>(`[data-cat="${activeCat}"]`)?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [activeCat, focusZone]);
+
+  useEffect(() => {
+    if (focusZone === "tabs") return;
+    const vp = searching ? listViewport.current : gridViewport.current;
+    vp?.querySelector<HTMLElement>(`[data-i="${idx}"]`)?.scrollIntoView({ block: "nearest" });
+  }, [idx, searching, focusZone]);
+
+  const pickSearchItem = useCallback(
+    (i: number) => {
+      const item = items[i];
+      if (!item) return;
+      command(item);
+      incrementEmojiUsage(item.id);
     },
-    [command, items]
+    [command, items],
+  );
+
+  const pickGridItem = useCallback(
+    (entry: EmojiIndexEntry) => {
+      editor.chain().focus().deleteRange(range).insertContent(entry.native + " ").run();
+      incrementEmojiUsage(entry.id);
+    },
+    [editor, range],
   );
 
   useEffect(() => {
-    const navigationKeys = [
+    function onKey(e: KeyboardEvent) {
-      "ArrowRight",
+      if (searching) {
-      "ArrowLeft",
+        if      (e.key === "ArrowDown") { e.preventDefault(); setIdx((i) => Math.min(i + 1, items.length - 1)); }
-      "ArrowUp",
+        else if (e.key === "ArrowUp")   { e.preventDefault(); setIdx((i) => Math.max(i - 1, 0)); }
-      "ArrowDown",
+        else if (e.key === "Enter")     { e.preventDefault(); pickSearchItem(idx); }
-      "Enter",
+      } else if (focusZone === "tabs") {
-    ];
+        const catIdx = cats.findIndex((c) => c.id === activeCat);
-    const onKeyDown = (e: KeyboardEvent) => {
+        if      (e.key === "ArrowRight") { e.preventDefault(); const next = cats[Math.min(catIdx + 1, cats.length - 1)]; if (next) setActiveCat(next.id); }
-      if (navigationKeys.includes(e.key)) {
+        else if (e.key === "ArrowLeft")  { e.preventDefault(); const prev = cats[Math.max(catIdx - 1, 0)]; if (prev) setActiveCat(prev.id); }
-        e.preventDefault();
+        else if (e.key === "ArrowDown" || e.key === "Enter") { e.preventDefault(); setFocusZone("grid"); }
-
+        else if (e.key === "ArrowUp")    { e.preventDefault(); }
-        if (e.key === "ArrowRight") {
+      } else {
-          setSelectedIndex(
+        const total = gridItems.length;
-            selectedIndex + 1 < items.length ? selectedIndex + 1 : selectedIndex
+        if      (e.key === "ArrowRight") { e.preventDefault(); setIdx((i) => Math.min(i + 1, total - 1)); }
-          );
+        else if (e.key === "ArrowLeft")  { e.preventDefault(); setIdx((i) => Math.max(i - 1, 0)); }
-          return true;
+        else if (e.key === "ArrowDown")  { e.preventDefault(); setIdx((i) => Math.min(i + COLS, total - 1)); }
+        else if (e.key === "ArrowUp")    {
+          e.preventDefault();
+          if (idx < COLS) setFocusZone("tabs");
+          else            setIdx((i) => Math.max(i - COLS, 0));
         }
-
+        else if (e.key === "Enter")      { e.preventDefault(); if (gridItems[idx]) pickGridItem(gridItems[idx]); }
-        if (e.key === "ArrowLeft") {
-          setSelectedIndex(
-            selectedIndex - 1 >= 0 ? selectedIndex - 1 : selectedIndex
-          );
-          return true;
-        }
-
-        if (e.key === "ArrowUp") {
-          setSelectedIndex(
-            selectedIndex - GRID_COLUMNS >= 0
-              ? selectedIndex - GRID_COLUMNS
-              : selectedIndex
-          );
-          return true;
-        }
-
-        if (e.key === "ArrowDown") {
-          setSelectedIndex(
-            selectedIndex + GRID_COLUMNS < items.length
-              ? selectedIndex + GRID_COLUMNS
-              : selectedIndex
-          );
-          return true;
-        }
-
-        if (e.key === "Enter") {
-          selectItem(selectedIndex);
-          return true;
-        }
-        return false;
       }
-    };
+    }
-    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("keydown", onKey);
-    return () => {
+    return () => document.removeEventListener("keydown", onKey);
-      document.removeEventListener("keydown", onKeyDown);
+  }, [searching, items, idx, gridItems, pickSearchItem, pickGridItem, focusZone, cats, activeCat]);
-    };
-  }, [items, selectedIndex, setSelectedIndex]);
 
-  useEffect(() => {
+  return (
-    setSelectedIndex(0);
-  }, [items]);
-
-  useEffect(() => {
-    viewportRef.current
-      ?.querySelector(`[data-item-index="${selectedIndex}"]`)
-      ?.scrollIntoView({ block: "nearest" });
-  }, [selectedIndex]);
-
-  return items.length > 0 || isLoading ? (
     <Paper
       id="emoji-command"
-      p="0"
+      p={0}
       shadow="md"
       withBorder
+      style={{ width: 280 }}
       role="listbox"
-      aria-label="Emoji results"
+      aria-label={t("Emoji picker")}
-      aria-activedescendant={
-        items.length > 0 ? `emoji-command-option-${selectedIndex}` : undefined
-      }
     >
-      {isLoading && <Loader m="xs" color="blue" type="dots" />}
+      {searching ? (
-      {items.length > 0 && (
+        <>
-        <ScrollArea.Autosize
+          {isLoading && <Loader m="xs" size="xs" color="blue" type="dots" />}
-          viewportRef={viewportRef}
+          <ScrollArea.Autosize mah={260} scrollbarSize={6} viewportRef={listViewport}>
-          mah={250}
+            <div style={{ padding: 4 }}>
-          scrollbarSize={8}
+              {items.length === 0 && !isLoading ? (
-          pr="5"
+                <Text size="sm" c="dimmed" p="xs">{t("No results")}</Text>
-        >
+              ) : items.map((item, i) => (
-          <SimpleGrid cols={GRID_COLUMNS} p="xs" spacing="xs">
+                <UnstyledButton
-            {items.map((item, index: number) => (
+                  key={item.id}
-              <ActionIcon
+                  data-i={i}
-                data-item-index={index}
+                  w="100%"
-                id={`emoji-command-option-${index}`}
+                  className={clsx(classes.row, { [classes.active]: i === idx })}
-                role="option"
+                  onClick={() => pickSearchItem(i)}
-                aria-selected={index === selectedIndex}
+                  onMouseEnter={() => setIdx(i)}
-                aria-label={item.id}
+                  role="option"
-                variant="transparent"
+                  aria-selected={i === idx}
-                key={item.id}
+                >
-                className={clsx(classes.menuBtn, {
+                  <span style={{ fontSize: 20, lineHeight: 1, minWidth: 26 }}>{item.emoji}</span>
-                  [classes.selectedItem]: index === selectedIndex,
+                  <Text size="sm" c="dimmed" ff="monospace" span>:{item.id}:</Text>
-                })}
+                </UnstyledButton>
-                onClick={() => selectItem(index)}
+              ))}
-              >
+            </div>
-                <Text size="xl">{item.emoji}</Text>
+          </ScrollArea.Autosize>
-              </ActionIcon>
+        </>
-            ))}
+      ) : browseLoading ? (
-          </SimpleGrid>
+        <Loader m="xs" size="xs" color="blue" type="dots" />
-        </ScrollArea.Autosize>
+      ) : (
+        <>
+          <div className={classes.catBar} role="tablist" ref={catBar}>
+            {cats.map((c) => {
+              const isActive = c.id === activeCat;
+              const isFocused = isActive && focusZone === "tabs";
+              return (
+                <button
+                  key={c.id}
+                  data-cat={c.id}
+                  title={c.id}
+                  role="tab"
+                  aria-selected={isActive}
+                  className={clsx(classes.catTab, {
+                    [classes.catTabActive]: isActive,
+                    [classes.catTabFocused]: isFocused,
+                  })}
+                  onClick={() => { setActiveCat(c.id); setFocusZone("grid"); }}
+                  onMouseEnter={() => setFocusZone("grid")}
+                >
+                  {CAT_ICONS[c.id] ?? "🔣"}
+                </button>
+              );
+            })}
+          </div>
+          <ScrollArea.Autosize mah={220} scrollbarSize={6} viewportRef={gridViewport}>
+            <div className={classes.grid} style={{ gridTemplateColumns: `repeat(${COLS}, 1fr)` }}>
+              {gridItems.map((entry, i) => (
+                <button
+                  key={entry.id}
+                  data-i={i}
+                  title={`:${entry.id}:`}
+                  className={clsx(classes.emojiBtn, { [classes.active]: i === idx })}
+                  onClick={() => pickGridItem(entry)}
+                  onMouseEnter={() => setIdx(i)}
+                >
+                  {entry.native}
+                </button>
+              ))}
+            </div>
+          </ScrollArea.Autosize>
+        </>
       )}
     </Paper>
-  ) : null;
+  );
-};
+}
 
 export default EmojiList;

apps/client/src/features/editor/components/emoji-menu/emoji-menu.module.css

@@ -1,9 +1,13 @@
-.menuBtn {
+.row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
   border-radius: var(--mantine-radius-sm);
 
   &:hover {
     @mixin light {
-      background: var(--mantine-color-gray-2);
+      background: var(--mantine-color-gray-1);
     }
 
     @mixin dark {
@@ -12,7 +16,7 @@
   }
 }
 
-.selectedItem {
+.active {
   @mixin light {
     background: var(--mantine-color-gray-2);
   }
@@ -21,3 +25,83 @@
     background: var(--mantine-color-gray-light);
   }
 }
+
+.catBar {
+  display: flex;
+  gap: 2px;
+  padding: 4px 6px;
+  overflow-x: auto;
+  scrollbar-width: none;
+
+  @mixin light {
+    border-bottom: 1px solid var(--mantine-color-gray-2);
+  }
+
+  @mixin dark {
+    border-bottom: 1px solid var(--mantine-color-dark-4);
+  }
+}
+
+.catTab {
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  font-size: 16px;
+  line-height: 1;
+  padding: 4px 5px;
+  border-radius: var(--mantine-radius-sm);
+  flex-shrink: 0;
+
+  &:hover {
+    @mixin light {
+      background: var(--mantine-color-gray-1);
+    }
+
+    @mixin dark {
+      background: var(--mantine-color-gray-light);
+    }
+  }
+}
+
+.catTabActive {
+  @mixin light {
+    background: var(--mantine-color-gray-2);
+  }
+
+  @mixin dark {
+    background: var(--mantine-color-gray-light);
+  }
+}
+
+.catTabFocused {
+  outline: 1px solid var(--mantine-color-blue-filled);
+  outline-offset: -1px;
+}
+
+.grid {
+  display: grid;
+  gap: 1px;
+  padding: 6px;
+}
+
+.emojiBtn {
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  font-size: 20px;
+  line-height: 1;
+  padding: 3px;
+  border-radius: var(--mantine-radius-sm);
+  aspect-ratio: 1 / 1;
+
+  &:hover {
+    @mixin light {
+      background: var(--mantine-color-gray-1);
+    }
+
+    @mixin dark {
+      background: var(--mantine-color-gray-light);
+    }
+  }
+}
+

apps/client/src/features/editor/components/emoji-menu/render-emoji-items.ts

@@ -1,6 +1,5 @@
 import { ReactRenderer, useEditor } from "@tiptap/react";
 import EmojiList from "./emoji-list";
-import { init } from "emoji-mart";
 import {
   autoUpdate,
   computePosition,
@@ -37,10 +36,6 @@ const renderEmojiItems = () => {
       editor: ReturnType<typeof useEditor>;
       clientRect: () => DOMRect;
     }) => {
-      init({
-        data: async () => (await import("@emoji-mart/data")).default,
-      });
-
       component = new ReactRenderer(EmojiList, {
         props: { isLoading: true, items: [] },
         editor: props.editor,

apps/client/src/features/editor/components/emoji-menu/utils.ts

@@ -1,8 +1,4 @@
-import { CommandProps } from "./types";
+import { CommandProps, EmojiMartFrequentlyType, EmojiMenuItemType } from "./types";
-import { getEmojiDataFromNative } from "emoji-mart";
-import { EmojiMartFrequentlyType, EmojiMenuItemType } from "./types";
-
-export const GRID_COLUMNS = 10;
 
 export const LOCAL_STORAGE_FREQUENT_KEY = "emoji-mart.frequently";
 
@@ -19,41 +15,76 @@ export const DEFAULT_FREQUENTLY_USED_EMOJI_MART = `{
     "rocket": 1
 }`;
 
+export type EmojiIndexEntry = { id: string; name: string; native: string };
+
+let _emojiIndex: EmojiIndexEntry[] | null = null;
+
+export const buildEmojiIndex = async (): Promise<EmojiIndexEntry[]> => {
+  if (_emojiIndex) return _emojiIndex;
+  const { default: data } = await import("@emoji-mart/data");
+  _emojiIndex = (Object.values((data as any).emojis) as any[])
+    .filter((e) => e.id && e.name && e.skins?.[0]?.native)
+    .map((e) => ({
+      id: e.id as string,
+      name: (e.name as string).toLowerCase(),
+      native: e.skins[0].native as string,
+    }));
+  return _emojiIndex;
+};
+
 export const incrementEmojiUsage = (emojiId: string) => {
-  const frequentlyUsedEmoji =
+  const stored = JSON.parse(
-    JSON.parse(localStorage.getItem(LOCAL_STORAGE_FREQUENT_KEY) || DEFAULT_FREQUENTLY_USED_EMOJI_MART);
+    localStorage.getItem(LOCAL_STORAGE_FREQUENT_KEY) || DEFAULT_FREQUENTLY_USED_EMOJI_MART,
-  frequentlyUsedEmoji[emojiId]
-    ? (frequentlyUsedEmoji[emojiId] += 1)
-    : (frequentlyUsedEmoji[emojiId] = 1);
-  localStorage.setItem(
-    LOCAL_STORAGE_FREQUENT_KEY,
-    JSON.stringify(frequentlyUsedEmoji)
   );
+  stored[emojiId] = (stored[emojiId] ?? 0) + 1;
+  localStorage.setItem(LOCAL_STORAGE_FREQUENT_KEY, JSON.stringify(stored));
 };
 
 export const sortFrequentlyUsedEmoji = async (
-  frequentlyUsedEmoji: EmojiMartFrequentlyType
+  frequentlyUsedEmoji: EmojiMartFrequentlyType,
 ): Promise<EmojiMenuItemType[]> => {
-  const data = await Promise.all(
+  const index = await buildEmojiIndex();
-    Object.entries(frequentlyUsedEmoji).map(
+  const results: EmojiMenuItemType[] = Object.entries(frequentlyUsedEmoji)
-      async ([id, count]): Promise<EmojiMenuItemType> => ({
+    .map(([id, count]): EmojiMenuItemType | null => {
+      const entry = index.find((e) => e.id === id);
+      if (!entry) return null;
+      return {
         id,
         count,
-        emoji: (await getEmojiDataFromNative(id))?.native,
+        emoji: entry.native,
-        command: async ({ editor, range }: CommandProps) => {
+        command: ({ editor, range }: CommandProps) => {
-          editor
+          editor.chain().focus().deleteRange(range).insertContent(entry.native + " ").run();
-            .chain()
-            .focus()
-            .deleteRange(range)
-            .insertContent((await getEmojiDataFromNative(id))?.native + " ")
-            .run();
         },
-      })
+      };
-    )
+    })
-  );
+    .filter((e): e is EmojiMenuItemType => e !== null);
-  return data.sort((a, b) => b.count - a.count);
+  return results.sort((a, b) => (b.count ?? 0) - (a.count ?? 0)).slice(0, 5);
 };
 
-export const getFrequentlyUsedEmoji = () => {
+export const getFrequentlyUsedEmoji = (): EmojiMartFrequentlyType => {
-  return JSON.parse(localStorage.getItem(LOCAL_STORAGE_FREQUENT_KEY) || DEFAULT_FREQUENTLY_USED_EMOJI_MART);
+  return JSON.parse(
-}
+    localStorage.getItem(LOCAL_STORAGE_FREQUENT_KEY) || DEFAULT_FREQUENTLY_USED_EMOJI_MART,
+  );
+};
+
+export type EmojiCategory = { id: string; emojis: EmojiIndexEntry[] };
+
+let _cats: EmojiCategory[] | null = null;
+
+export const getEmojiCategories = async (): Promise<EmojiCategory[]> => {
+  if (_cats) return _cats;
+  const [{ default: data }, index] = await Promise.all([
+    import("@emoji-mart/data"),
+    buildEmojiIndex(),
+  ]);
+  const byId = new Map(index.map((e) => [e.id, e]));
+  _cats = ((data as any).categories as { id: string; emojis: string[] }[])
+    .map((cat) => ({
+      id: cat.id,
+      emojis: cat.emojis
+        .map((id) => byId.get(id))
+        .filter((e): e is EmojiIndexEntry => !!e),
+    }))
+    .filter((c) => c.emojis.length > 0);
+  return _cats;
+};

apps/client/src/features/editor/components/slash-menu/menu-items.ts

@@ -25,6 +25,8 @@ import {
   IconColumns3,
   IconColumns2,
   IconTag,
+  IconMoodSmile,
+  IconRotate2,
 } from "@tabler/icons-react";
 import {
   CommandProps,
@@ -132,7 +134,7 @@ const CommandGroups: SlashMenuGroupedItemsType = {
     {
       title: "Numbered list",
       description: "Create a list with numbering.",
-      searchTerms: ["numbered", "ordered", "list"],
+      searchTerms: ["numbered", "ordered", "list", "ol"],
       icon: IconListNumbers,
       command: ({ editor, range }: CommandProps) => {
         editor.chain().focus().deleteRange(range).toggleOrderedList().run();
@@ -231,7 +233,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();
@@ -468,15 +478,53 @@ const CommandGroups: SlashMenuGroupedItemsType = {
           .run();
       },
     },
+    {
+      title: "Emoji",
+      description: "Insert emoji.",
+      searchTerms: ["emoji", "icon", "smiley", "emoticon", "symbol", "reaction"],
+      icon: IconMoodSmile,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).insertContent(":").run();
+      },
+    },
     {
       title: "Subpages (Child pages)",
       description: "List all subpages of the current page",
-      searchTerms: ["subpages", "child", "children", "nested", "hierarchy"],
+      searchTerms: [
+        "subpages",
+        "child",
+        "children",
+        "nested",
+        "hierarchy",
+        "toc",
+      ],
       icon: IconSitemap,
       command: ({ editor, range }: CommandProps) => {
         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.",

apps/client/src/features/editor/components/transclusion/error-placeholder.tsx

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

apps/client/src/features/editor/components/transclusion/no-access-placeholder.tsx

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

apps/client/src/features/editor/components/transclusion/not-found-placeholder.tsx

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

apps/client/src/features/editor/components/transclusion/transclusion-content.tsx

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

apps/client/src/features/editor/components/transclusion/transclusion-lookup-context.tsx

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

apps/client/src/features/editor/components/transclusion/transclusion-reference-view.tsx

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

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

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

apps/client/src/features/editor/components/transclusion/transclusion.module.css

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

apps/client/src/features/editor/extensions/drag-handle.ts

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

apps/client/src/features/editor/extensions/extensions.ts

@@ -9,9 +9,10 @@ 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 SlashCommand, {
+  SlashCommandExtension as Command,
+} from "@/features/editor/extensions/slash-command";
 import renderItems from "@/features/editor/components/slash-menu/render-items";
 import getSuggestionItems from "@/features/editor/components/slash-menu/menu-items";
 import { Collaboration, isChangeOrigin } from "@tiptap/extension-collaboration";
@@ -47,11 +48,14 @@ import {
   Subpages,
   Heading,
   Highlight,
+  Indent,
   UniqueID,
   SharedStorage,
   Columns,
   Column,
   Status,
+  TransclusionSource,
+  TransclusionReference,
 } from "@docmost/editor-ext";
 import {
   randomElement,
@@ -80,6 +84,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 +106,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 +174,7 @@ export const mainExtensions = [
   SharedStorage,
   Heading,
   UniqueID.configure({
-    types: ["heading", "paragraph"],
+    types: ["heading", "paragraph", "transclusionSource"],
     filterTransaction: (transaction) => !isChangeOrigin(transaction),
   }),
   Placeholder.configure({
@@ -197,6 +204,7 @@ export const mainExtensions = [
     showOnlyWhenEditable: true,
   }),
   TextAlign.configure({ types: ["heading", "paragraph"] }),
+  Indent,
   TaskList,
   TaskItem.configure({
     nested: true,
@@ -215,7 +223,9 @@ export const mainExtensions = [
   }),
   Typography,
   TrailingNode,
-  GlobalDragHandle,
+  GlobalDragHandle.configure({
+    customNodes: ["transclusionSource", "transclusionReference"],
+  }),
   TextStyle,
   Color,
   SlashCommand,
@@ -305,6 +315,8 @@ export const mainExtensions = [
     view: CodeBlockView,
     //@ts-ignore
     lowlight,
+    enableTabIndentation: true,
+    tabSize: 2,
     HTMLAttributes: {
       spellcheck: false,
     },
@@ -351,6 +363,12 @@ export const mainExtensions = [
   Status.configure({
     view: StatusView,
   }),
+  TransclusionSource.configure({
+    view: TransclusionView,
+  }),
+  TransclusionReference.configure({
+    view: TransclusionReferenceView,
+  }),
   MarkdownClipboard.configure({
     transformPastedText: true,
   }),
@@ -393,7 +411,10 @@ const TEMPLATE_EXCLUDED_SLASH_ITEMS = new Set([
 const TemplateSlashCommand = Command.configure({
   suggestion: {
     items: ({ query }: { query: string }) =>
-      getSuggestionItems({ query, excludeItems: TEMPLATE_EXCLUDED_SLASH_ITEMS }),
+      getSuggestionItems({
+        query,
+        excludeItems: TEMPLATE_EXCLUDED_SLASH_ITEMS,
+      }),
     render: renderItems,
   },
 });

apps/client/src/features/editor/page-editor.tsx

@@ -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" }}>
+    <TransclusionLookupProvider>
-      <div ref={menuContainerRef}>
+      {showStatic ? (
-        <EditorContent editor={editor} />
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+        />
+      ) : (
+        <div className="editor-container" style={{ position: "relative" }}>
+          <div ref={menuContainerRef}>
+            <EditorContent editor={editor} />
 
-        {editor && (
+            {editor && (
-          <SearchAndReplaceDialog editor={editor} editable={editable} />
+              <SearchAndReplaceDialog editor={editor} editable={editable} />
-        )}
+            )}
 
-        {editor && editorIsEditable && (
+            {editor && editorIsEditable && (
-          <div>
+              <div>
-            <EditorAiMenu editor={editor} />
+                <EditorAiMenu editor={editor} />
-            <EditorLinkMenu editor={editor} />
+                <EditorLinkMenu editor={editor} />
-            <EditorBubbleMenu editor={editor} />
+                <EditorBubbleMenu editor={editor} />
-            <TableMenu editor={editor} />
+                <TableMenu editor={editor} />
-            <TableCellMenu editor={editor} appendTo={menuContainerRef} />
+                <TableCellMenu editor={editor} appendTo={menuContainerRef} />
-            <ImageMenu editor={editor} />
+                <ImageMenu editor={editor} />
-            <VideoMenu editor={editor} />
+                <VideoMenu editor={editor} />
-            <PdfMenu editor={editor} />
+                <PdfMenu editor={editor} />
-            <CalloutMenu editor={editor} />
+                <CalloutMenu editor={editor} />
-            <SubpagesMenu editor={editor} />
+                <SubpagesMenu editor={editor} />
-            <ExcalidrawMenu editor={editor} />
+                <ExcalidrawMenu editor={editor} />
-            <DrawioMenu editor={editor} />
+                <DrawioMenu editor={editor} />
-            <ColumnsMenu 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>
-        )}
+          <div
-        {editor && !editorIsEditable && (editable || canComment) && providersRef.current && (
+            onClick={() => editor.commands.focus("end")}
-          <ReadonlyBubbleMenu editor={editor} />
+            style={{ paddingBottom: "20vh" }}
-        )}
+          ></div>
-        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
+        </div>
-        {showReadOnlyCommentPopup && (
+      )}
-          <CommentDialog editor={editor} pageId={pageId} readOnly />
+    </TransclusionLookupProvider>
-        )}
-      </div>
-      <div
-        onClick={() => editor.commands.focus("end")}
-        style={{ paddingBottom: "20vh" }}
-      ></div>
-    </div>
   );
 }

apps/client/src/features/editor/readonly-page-editor.tsx

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

apps/client/src/features/editor/styles/indent.css

@@ -0,0 +1,14 @@
+.ProseMirror {
+  --indent-step: 2rem;
+}
+
+.ProseMirror [data-indent="1"] { padding-inline-start: calc(var(--indent-step) * 1); }
+.ProseMirror [data-indent="2"] { padding-inline-start: calc(var(--indent-step) * 2); }
+.ProseMirror [data-indent="3"] { padding-inline-start: calc(var(--indent-step) * 3); }
+.ProseMirror [data-indent="4"] { padding-inline-start: calc(var(--indent-step) * 4); }
+.ProseMirror [data-indent="5"] { padding-inline-start: calc(var(--indent-step) * 5); }
+.ProseMirror [data-indent="6"] { padding-inline-start: calc(var(--indent-step) * 6); }
+.ProseMirror [data-indent="7"] { padding-inline-start: calc(var(--indent-step) * 7); }
+.ProseMirror [data-indent="8"] { padding-inline-start: calc(var(--indent-step) * 8); }
+.ProseMirror [data-indent="9"] { padding-inline-start: calc(var(--indent-step) * 9); }
+.ProseMirror [data-indent="10"] { padding-inline-start: calc(var(--indent-step) * 10); }

apps/client/src/features/editor/styles/index.css

@@ -13,5 +13,6 @@
 @import "./mention.css";
 @import "./ordered-list.css";
 @import "./highlight.css";
+@import "./indent.css";
 @import "./columns.css";
 @import "./status.css";

apps/client/src/features/home/components/home-ai-prompt.module.css

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

apps/client/src/features/transclusion/components/sync-block-references-dropdown.module.css

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

apps/client/src/features/transclusion/components/sync-block-references-dropdown.tsx

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

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

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

apps/client/src/features/transclusion/services/transclusion-api.ts

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

apps/client/src/features/transclusion/types/transclusion.types.ts

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

apps/client/src/features/user/user-provider.tsx

@@ -60,6 +60,10 @@ export function UserProvider({ children }: React.PropsWithChildren) {
     }
   }, [data, isLoading]);
 
+  useEffect(() => {
+    document.documentElement.lang = i18n.resolvedLanguage || i18n.language || "en-US";
+  }, [i18n.language, i18n.resolvedLanguage]);
+
   useEffect(() => {
     if (entitlements) {
       setEntitlements(entitlements);

apps/client/src/pages/share/shared-page.tsx

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

apps/server/package.json

@@ -163,10 +163,11 @@
     "rootDir": "src",
     "testRegex": ".*\\.spec\\.ts$",
     "transform": {
+      "happy-dom.+\\.js$": ["babel-jest", { "presets": [["@babel/preset-env", { "targets": { "node": "current" } }]] }],
       "^.+\\.(t|j)s$": "ts-jest"
     },
     "transformIgnorePatterns": [
-      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked)(@|/))"
+      "/node_modules/(?!(\\.pnpm/)?(nanoid|uuid|image-dimensions|marked|happy-dom)(@|/))"
     ],
     "collectCoverageFrom": [
       "**/*.(t|j)s"

apps/server/src/collaboration/collaboration.module.ts

@@ -1,10 +1,4 @@
-import {
+import { Logger, Module, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-  Global,
-  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);

apps/server/src/collaboration/collaboration.util.ts

@@ -34,12 +34,15 @@ import {
   Mention,
   Subpages,
   Highlight,
+  Indent,
   UniqueID,
   Columns,
   Column,
   Status,
   addUniqueIdsToDoc,
   htmlToMarkdown,
+  TransclusionSource,
+  TransclusionReference,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -60,10 +63,11 @@ export const tiptapExtensions = [
   }),
   Heading,
   UniqueID.configure({
-    types: ['heading', 'paragraph'],
+    types: ['heading', 'paragraph', 'transclusionSource'],
   }),
   Comment,
   TextAlign.configure({ types: ['heading', 'paragraph'] }),
+  Indent,
   TaskList,
   TaskItem.configure({
     nested: true,
@@ -101,6 +105,8 @@ export const tiptapExtensions = [
   Columns,
   Column,
   Status,
+  TransclusionSource,
+  TransclusionReference,
 ] as any;
 
 export function jsonToHtml(tiptapJson: any) {

apps/server/src/collaboration/extensions/persistence.extension.ts

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

apps/server/src/common/helpers/prosemirror/attachment-node-types.ts

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

apps/server/src/common/helpers/prosemirror/html/index.ts

@@ -1,2 +1,2 @@
-export * from './generateHTML.js';
+export * from './generateHTML';
-export * from './generateJSON.js';
+export * from './generateJSON';

apps/server/src/common/helpers/prosemirror/indent-schema.spec.ts

@@ -0,0 +1,63 @@
+import { htmlToJson, jsonToHtml } from '../../../collaboration/collaboration.util';
+
+const findFirstChild = (
+  json: any,
+  type: string,
+): any | undefined => {
+  if (!json || typeof json !== 'object') return undefined;
+  if (json.type === type) return json;
+  if (Array.isArray(json.content)) {
+    for (const child of json.content) {
+      const found = findFirstChild(child, type);
+      if (found) return found;
+    }
+  }
+  return undefined;
+};
+
+describe('indent attribute round-trip', () => {
+  it('parses data-indent on a paragraph into the indent attribute', () => {
+    const html = '<p data-indent="3">Hello</p>';
+    const json = htmlToJson(html);
+    const paragraph = findFirstChild(json, 'paragraph');
+    expect(paragraph).toBeDefined();
+    expect(paragraph.attrs.indent).toBe(3);
+  });
+
+  it('parses data-indent on a heading into the indent attribute', () => {
+    const html = '<h2 data-indent="2">Heading</h2>';
+    const json = htmlToJson(html);
+    const heading = findFirstChild(json, 'heading');
+    expect(heading).toBeDefined();
+    expect(heading.attrs.indent).toBe(2);
+    expect(heading.attrs.level).toBe(2);
+  });
+
+  it('clamps out-of-range data-indent values', () => {
+    const html = '<p data-indent="42">Too deep</p>';
+    const json = htmlToJson(html);
+    const paragraph = findFirstChild(json, 'paragraph');
+    expect(paragraph.attrs.indent).toBe(8);
+  });
+
+  it('renders nonzero indent back to data-indent on HTML serialization', () => {
+    const html = '<p data-indent="4">Round-trip</p>';
+    const json = htmlToJson(html);
+    const out = jsonToHtml(json);
+    expect(out).toContain('data-indent="4"');
+  });
+
+  it('omits data-indent for indent zero', () => {
+    const html = '<p>No indent</p>';
+    const json = htmlToJson(html);
+    const out = jsonToHtml(json);
+    expect(out).not.toContain('data-indent');
+  });
+
+  it('preserves indent through HTML → JSON → HTML', () => {
+    const original = '<p data-indent="5">Five deep</p>';
+    const json = htmlToJson(original);
+    const final = jsonToHtml(json);
+    expect(final).toContain('data-indent="5"');
+  });
+});

apps/server/src/common/helpers/prosemirror/utils.ts

@@ -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) {
+export { isAttachmentNode };
-  const attachmentNodeTypes = [
-    'attachment',
-    'image',
-    'video',
-    'audio',
-    'pdf',
-    'excalidraw',
-    'drawio',
-  ];
-  return attachmentNodeTypes.includes(nodeType);
-}
 
 export function getAttachmentIds(prosemirrorJson: any) {
   const doc = jsonToNode(prosemirrorJson);

apps/server/src/core/page/page.module.ts

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

apps/server/src/core/page/services/page.service.ts

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

apps/server/src/core/page/transclusion/dto/lookup.dto.ts

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

apps/server/src/core/page/transclusion/dto/references.dto.ts

@@ -0,0 +1,9 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class ReferencesDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}

apps/server/src/core/page/transclusion/dto/unsync-reference.dto.ts

@@ -0,0 +1,12 @@
+import { IsString, IsUUID } from 'class-validator';
+
+export class UnsyncReferenceDto {
+  @IsUUID()
+  referencePageId!: string;
+
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  transclusionId!: string;
+}

apps/server/src/core/page/transclusion/spec/transclusion-prosemirror.util.spec.ts

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

apps/server/src/core/page/transclusion/spec/transclusion-unsync.util.spec.ts

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

apps/server/src/core/page/transclusion/spec/transclusion.controller.spec.ts

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

apps/server/src/core/page/transclusion/spec/transclusion.service.spec.ts

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

apps/server/src/core/page/transclusion/transclusion.controller.ts

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

apps/server/src/core/page/transclusion/transclusion.module.ts

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

apps/server/src/core/page/transclusion/transclusion.service.ts

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

apps/server/src/core/page/transclusion/transclusion.types.ts

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

apps/server/src/core/page/transclusion/utils/transclusion-prosemirror.util.ts

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

apps/server/src/core/page/transclusion/utils/transclusion-unsync.util.ts

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

apps/server/src/core/share/dto/share-transclusion-lookup.dto.ts

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

apps/server/src/core/share/share.controller.ts

@@ -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(

apps/server/src/core/share/share.module.ts

@@ -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],

apps/server/src/core/share/share.service.ts

@@ -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 doc = await this.prepareContentForShare(
-    const attachmentIds = getAttachmentIds(prosemirrorJson);
+      page.content,
-    const attachmentMap = new Map<string, string>();
+      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,
+          pageId: attachmentOwnerPageId,
-          workspaceId: page.workspaceId,
+          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 token = tokenMap.get(node.attrs.attachmentId);
-      const attachmentId = node.attrs.attachmentId;
-      const token = attachmentMap.get(attachmentId);
       if (!token) return;
-
       updateAttachmentAttr(node, 'src', token);
       updateAttachmentAttr(node, 'url', token);
     });
 
-    const removeCommentMarks = removeMarkTypeFromDoc(doc, 'comment');
+    return doc ? removeMarkTypeFromDoc(doc, 'comment') : null;
-    return removeCommentMarks.toJSON();
   }
 }

apps/server/src/database/database.module.ts

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

apps/server/src/database/migrations/20260501T202258-page-transclusions.ts

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

apps/server/src/database/repos/attachment/attachment.repo.ts

@@ -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?: {

apps/server/src/database/repos/page-transclusions/page-transclusion-references.repo.ts

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

apps/server/src/database/repos/page-transclusions/page-transclusions.repo.ts

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

apps/server/src/database/repos/page/page.repo.ts

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

apps/server/src/database/types/db.d.ts

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

apps/server/src/database/types/entity.types.ts

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

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

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

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

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

apps/server/src/main.ts

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

packages/editor-ext/src/index.ts

@@ -21,7 +21,9 @@ 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/indent";
 export * from "./lib/heading/heading";
 export * from "./lib/unique-id";
 export * from "./lib/shared-storage";

packages/editor-ext/src/lib/custom-code-block/custom-code-block.ts

@@ -1,8 +1,8 @@
-import type { CodeBlockOptions } from "@tiptap/extension-code-block";
+import type { CodeBlockOptions } from '@tiptap/extension-code-block';
-import CodeBlock from "@tiptap/extension-code-block";
+import CodeBlock from '@tiptap/extension-code-block';
 
-import { LowlightPlugin } from "./lowlight-plugin.js";
+import { LowlightPlugin } from './lowlight-plugin.js';
-import { ReactNodeViewRenderer } from "@tiptap/react";
+import { ReactNodeViewRenderer } from '@tiptap/react';
 
 export interface CodeBlockLowlightOptions extends CodeBlockOptions {
   /**
@@ -12,7 +12,7 @@ export interface CodeBlockLowlightOptions extends CodeBlockOptions {
   view: any;
 }
 
-const TAB_CHAR = "\u00A0\u00A0";
+const TAB_CHAR = '\u00A0\u00A0';
 
 /**
  * This extension allows you to highlight code blocks with lowlight.
@@ -25,7 +25,7 @@ export const CustomCodeBlock = CodeBlock.extend<CodeBlockLowlightOptions>({
     return {
       ...this.parent?.(),
       lowlight: {},
-      languageClassPrefix: "language-",
+      languageClassPrefix: 'language-',
       exitOnTripleEnter: true,
       exitOnArrowDown: true,
       defaultLanguage: null,
@@ -37,20 +37,8 @@ export const CustomCodeBlock = CodeBlock.extend<CodeBlockLowlightOptions>({
   addKeyboardShortcuts() {
     return {
       ...this.parent?.(),
-      Tab: () => {
+      'Mod-a': () => {
-        if (this.editor.isActive("codeBlock")) {
+        if (this.editor.isActive('codeBlock')) {
-          this.editor
-            .chain()
-            .command(({ tr }) => {
-              tr.insertText(TAB_CHAR);
-              return true;
-            })
-            .run();
-          return true;
-        }
-      },
-      "Mod-a": () => {
-        if (this.editor.isActive("codeBlock")) {
           const { state } = this.editor;
           const { $from } = state.selection;
 
@@ -60,7 +48,7 @@ export const CustomCodeBlock = CodeBlock.extend<CodeBlockLowlightOptions>({
 
           for (depth = $from.depth; depth > 0; depth--) {
             const node = $from.node(depth);
-            if (node.type.name === "codeBlock") {
+            if (node.type.name === 'codeBlock') {
               codeBlockNode = node;
               codeBlockPos = $from.start(depth) - 1;
               break;

packages/editor-ext/src/lib/indent.ts

@@ -0,0 +1,223 @@
+import { Extension } from '@tiptap/core';
+import {
+  Plugin,
+  PluginKey,
+  type EditorState,
+  type Transaction,
+} from '@tiptap/pm/state';
+
+export type IndentOptions = {
+  types: string[];
+  min: number;
+  max: number;
+};
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    indent: {
+      indent: () => ReturnType;
+      outdent: () => ReturnType;
+    };
+  }
+}
+
+// Containers whose descendants must never carry an `indent` attribute. These
+// nodes own their own Tab semantics (list nesting, cell navigation, literal
+// tab) and visually conflict with our indent padding, so paragraphs and
+// headings inside them stay flat
+const NON_INDENTABLE_ANCESTORS = new Set([
+  'listItem',
+  'taskItem',
+  'tableCell',
+  'tableHeader',
+  'codeBlock',
+]);
+
+const clampIndent = (value: number, min: number, max: number): number => {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+};
+
+const hasNonIndentableAncestor = (
+  doc: EditorState['doc'],
+  pos: number,
+): boolean => {
+  const $pos = doc.resolve(pos);
+  for (let depth = $pos.depth; depth >= 0; depth--) {
+    if (NON_INDENTABLE_ANCESTORS.has($pos.node(depth).type.name)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+export const Indent = Extension.create<IndentOptions>({
+  name: 'indent',
+
+  priority: 1000,
+
+  addOptions() {
+    return {
+      types: ['paragraph', 'heading'],
+      min: 0,
+      max: 8,
+    };
+  },
+
+  addGlobalAttributes() {
+    return [
+      {
+        types: this.options.types,
+        attributes: {
+          indent: {
+            default: this.options.min,
+            keepOnSplit: true,
+            parseHTML: (element) => {
+              const raw = element.getAttribute('data-indent');
+              if (raw === null) return this.options.min;
+              return clampIndent(
+                parseInt(raw, 10),
+                this.options.min,
+                this.options.max,
+              );
+            },
+            renderHTML: (attributes) => {
+              const value = attributes.indent;
+              if (value <= this.options.min) return {};
+              return { 'data-indent': String(value) };
+            },
+          },
+        },
+      },
+    ];
+  },
+
+  addCommands() {
+    return {
+      indent:
+        () =>
+        ({ state, tr, dispatch }) => {
+          return updateIndent(state, tr, dispatch, this.options, +1);
+        },
+      outdent:
+        () =>
+        ({ state, tr, dispatch }) => {
+          return updateIndent(state, tr, dispatch, this.options, -1);
+        },
+    };
+  },
+
+  addKeyboardShortcuts() {
+    const isInIndentableBlock = (): boolean => {
+      const { $from } = this.editor.state.selection;
+      if (!this.options.types.includes($from.parent.type.name)) return false;
+      for (let depth = $from.depth - 1; depth >= 0; depth--) {
+        if (NON_INDENTABLE_ANCESTORS.has($from.node(depth).type.name)) {
+          return false;
+        }
+      }
+      return true;
+    };
+
+    return {
+      Tab: () => {
+        if (!isInIndentableBlock()) return false;
+        this.editor.commands.indent();
+        return true;
+      },
+      'Shift-Tab': () => {
+        if (!isInIndentableBlock()) return false;
+        this.editor.commands.outdent();
+        return true;
+      },
+      Backspace: () => {
+        const { $from, empty } = this.editor.state.selection;
+        if (!empty) return false;
+        if ($from.parentOffset !== 0) return false;
+        if (!isInIndentableBlock()) return false;
+        if ($from.parent.attrs.indent <= this.options.min) return false;
+        this.editor.commands.outdent();
+        return true;
+      },
+    };
+  },
+
+  addProseMirrorPlugins() {
+    const types = new Set(this.options.types);
+    const min = this.options.min;
+
+    return [
+      new Plugin({
+        key: new PluginKey('indentNormalizer'),
+        appendTransaction: (transactions, _oldState, newState) => {
+          if (!transactions.some((tr) => tr.docChanged)) return null;
+
+          const tr = newState.tr;
+          let modified = false;
+
+          newState.doc.descendants((node, pos) => {
+            // Containers: descend so we can find paragraph/heading children.
+            if (!types.has(node.type.name)) return true;
+
+            if (node.attrs.indent <= min) return false;
+
+            if (hasNonIndentableAncestor(newState.doc, pos)) {
+              tr.setNodeMarkup(
+                pos,
+                undefined,
+                { ...node.attrs, indent: min },
+                node.marks,
+              );
+              modified = true;
+            }
+
+            // paragraph/heading don't contain other paragraphs/headings —
+            // never descend into their inline content.
+            return false;
+          });
+
+          if (!modified) return null;
+          // Normalisation must not show up as a separate undo step;
+          // otherwise undo would re-introduce the illegal indent.
+          return tr.setMeta('addToHistory', false);
+        },
+      }),
+    ];
+  },
+});
+
+function updateIndent(
+  state: EditorState,
+  tr: Transaction,
+  dispatch: ((tr: Transaction) => void) | undefined,
+  options: IndentOptions,
+  delta: number,
+): boolean {
+  const { selection } = state;
+  const { from, to } = selection;
+  const types = new Set(options.types);
+  let updated = false;
+
+  state.doc.nodesBetween(from, to, (node, pos) => {
+    // Skip non-block nodes (text, inline atoms) up front.
+    if (!node.type.isBlock) return false;
+
+    // Don't descend into containers whose children must stay flat — handles
+    // multi-block selections that span across e.g. a list-item or table-cell.
+    if (NON_INDENTABLE_ANCESTORS.has(node.type.name)) return false;
+
+    if (!types.has(node.type.name)) return true;
+
+    const current = node.attrs.indent as number;
+    const next = clampIndent(current + delta, options.min, options.max);
+    if (next === current) return false;
+
+    tr.setNodeMarkup(pos, undefined, { ...node.attrs, indent: next });
+    updated = true;
+    return false;
+  });
+
+  if (!updated) return false;
+  if (dispatch) dispatch(tr);
+  return true;
+}

packages/editor-ext/src/lib/transclusion/constants.ts

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

packages/editor-ext/src/lib/transclusion/index.ts

@@ -0,0 +1,3 @@
+export * from "./constants";
+export * from "./transclusion-source";
+export * from "./transclusion-reference";

packages/editor-ext/src/lib/transclusion/transclusion-reference.ts

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

packages/editor-ext/src/lib/transclusion/transclusion-source.ts

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

pnpm-lock.yaml

@@ -382,9 +382,6 @@ importers:
       socket.io-client:
         specifier: ^4.8.3
         version: 4.8.3
-      tiptap-extension-global-drag-handle:
-        specifier: ^0.1.18
-        version: 0.1.18
       zod:
         specifier: ^4.3.6
         version: 4.3.6
@@ -9691,9 +9688,6 @@ packages:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
 
-  tiptap-extension-global-drag-handle@0.1.18:
-    resolution: {integrity: sha512-jwFuy1K8DP3a4bFy76Hpc63w1Sil0B7uZ3mvhQomVvUFCU787Lg2FowNhn7NFzeyok761qY2VG+PZ/FDthWUdg==}
-
   tlds@1.261.0:
     resolution: {integrity: sha512-QXqwfEl9ddlGBaRFXIvNKK6OhipSiLXuRuLJX5DErz0o0Q0rYxulWLdFryTkV5PkdZct5iMInwYEGe/eR++1AA==}
     hasBin: true
@@ -20882,8 +20876,6 @@ snapshots:
       fdir: 6.5.0(picomatch@4.0.4)
       picomatch: 4.0.4
 
-  tiptap-extension-global-drag-handle@0.1.18: {}
-
   tlds@1.261.0: {}
 
   tldts-core@6.1.72: {}