feat: sync blocks - wip

* feat: replace pdfjs-dist with firecrawl-pdf-inspector

* use modified firecrawl-pdf-inspector

* feat: pdf import

* increase single file upload size limit

* use npm package

* sync

* update package

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/de-DE/translation.json

@@ -391,7 +391,7 @@
   "Write anything. Enter \"/\" for commands": "Schreiben Sie etwas. Geben Sie \"/\" für Befehle ein",
   "Write...": "\"Schreiben...\"",
   "Column count": "Spaltenanzahl",
-  "{{count}} Columns": "{count, plural, one {# Spalte} other {# Spalten}}",
+  "{{count}} Columns": "{{count}} Spalten",
   "Equal columns": "Gleich breite Spalten",
   "Left sidebar": "Linke Seitenleiste",
   "Right sidebar": "Rechte Seitenleiste",

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

@@ -608,25 +608,21 @@
   "Image exceeds 10MB limit.": "Image exceeds 10MB limit.",
   "Image removed successfully": "Image removed successfully",
   "API key": "API key",
-  "API key created successfully": "API key created successfully",
   "API keys": "API keys",
   "API management": "API management",
-  "Are you sure you want to revoke this API key": "Are you sure you want to revoke this API key",
-  "Create API Key": "Create API Key",
   "Custom expiration date": "Custom expiration date",
   "Enter a descriptive token name": "Enter a descriptive token name",
   "Expiration": "Expiration",
   "Expired": "Expired",
   "Expires": "Expires",
-  "I've saved my API key": "I've saved my API key",
   "Last use": "Last Used",
   "No API keys found": "No API keys found",
   "No expiration": "No expiration",
-  "Revoke API key": "Revoke API key",
   "Revoked successfully": "Revoked successfully",
   "Select expiration date": "Select expiration date",
   "This action cannot be undone. Any applications using this API key will stop working.": "This action cannot be undone. Any applications using this API key will stop working.",
-  "Update API key": "Update API key",
+  "Update": "Update",
+  "Update {{credential}}": "Update {{credential}}",
   "Manage API keys for all users in the workspace": "Manage API keys for all users in the workspace",
   "Restrict API key creation to admins": "Restrict API key creation to admins",
   "Only admins and owners can create new API keys. Existing member keys will continue to work.": "Only admins and owners can create new API keys. Existing member keys will continue to work.",
@@ -880,5 +876,41 @@
   "Try a different search term.": "Try a different search term.",
   "Try again": "Try again",
   "Untitled chat": "Untitled chat",
-  "What can I help you with?": "What can I help you with?"
+  "What can I help you with?": "What can I help you with?",
+  "Are you sure you want to revoke this {{credential}}": "Are you sure you want to revoke this {{credential}}",
+  "Automatically provision users and groups from your identity provider via SCIM.": "Automatically provision users and groups from your identity provider via SCIM.",
+  "Configure your identity provider with this URL to provision users and groups.": "Configure your identity provider with this URL to provision users and groups.",
+  "Create {{credential}}": "Create {{credential}}",
+  "{{credential}} created": "{{credential}} created",
+  "{{credential}} created successfully": "{{credential}} created successfully",
+  "Created by": "Created by",
+  "Custom": "Custom",
+  "Enable SCIM": "Enable SCIM",
+  "Enter a descriptive name": "Enter a descriptive name",
+  "I've saved my {{credential}}": "I've saved my {{credential}}",
+  "Important": "Important",
+  "Make sure to copy your {{credential}} now. You won't be able to see it again!": "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+  "Never": "Never",
+  "Revoke {{credential}}": "Revoke {{credential}}",
+  "SCIM endpoint URL": "SCIM endpoint URL",
+  "SCIM provisioning": "SCIM provisioning",
+  "SCIM takes precedence over SSO group sync while enabled.": "SCIM takes precedence over SSO group sync while enabled.",
+  "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.": "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.",
+  "SCIM token": "SCIM token",
+  "SCIM tokens": "SCIM tokens",
+  "This action cannot be undone. Your identity provider will stop syncing immediately.": "This action cannot be undone. Your identity provider will stop syncing immediately.",
+  "Toggle SCIM provisioning": "Toggle SCIM provisioning",
+  "Token": "Token",
+  "Sync block": "Sync block",
+  "Create a block that stays in sync across pages.": "Create a block that stays in sync across pages.",
+  "Sync block name": "Sync block name",
+  "Editing original": "Editing original",
+  "Copy synced block": "Copy synced block",
+  "Unsync": "Unsync",
+  "Delete sync block": "Delete sync 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"
 }

apps/client/src/components/layouts/global/global-app-shell.tsx

@@ -116,7 +116,9 @@ export default function GlobalAppShell({
       </AppShell.Navbar>
       <AppShell.Main>
         {isSettingsRoute ? (
-          <Container size={900}>{children}</Container>
+          <Container size={900} pb={80}>
+            {children}
+          </Container>
         ) : (
           children
         )}

apps/client/src/components/settings/settings-queries.tsx

@@ -13,6 +13,7 @@ import { getShares } from "@/features/share/services/share-service.ts";
 import { getApiKeys } from "@/ee/api-key";
 import { getAuditLogs } from "@/ee/audit/services/audit-service";
 import { getVerificationList } from "@/ee/page-verification/services/page-verification-service";
+import { getScimTokens } from "@/ee/scim/services/scim-token-service";
 
 export const prefetchWorkspaceMembers = () => {
   const params: QueryParams = { limit: 100, query: "" };
@@ -98,3 +99,10 @@ export const prefetchVerifiedPages = () => {
     queryFn: () => getVerificationList(params),
   });
 };
+
+export const prefetchScimTokens = () => {
+  queryClient.prefetchQuery({
+    queryKey: ["scim-token-list", { cursor: undefined }],
+    queryFn: () => getScimTokens({}),
+  });
+};

apps/client/src/components/settings/settings-sidebar.tsx

@@ -31,6 +31,7 @@ import {
   prefetchBilling,
   prefetchGroups,
   prefetchLicense,
+  prefetchScimTokens,
   prefetchShares,
   prefetchSpaces,
   prefetchSsoProviders,
@@ -204,7 +205,10 @@ export default function SettingsSidebar() {
               }
               break;
             case "Security & SSO":
-              prefetchHandler = prefetchSsoProviders;
+              prefetchHandler = () => {
+                prefetchSsoProviders();
+                prefetchScimTokens();
+              };
               break;
             case "Public sharing":
               prefetchHandler = prefetchShares;

apps/client/src/ee/api-key/components/api-key-created-modal.tsx

@@ -31,7 +31,7 @@ export function ApiKeyCreatedModal({
     <Modal
       opened={opened}
       onClose={onClose}
-      title={t("API key created")}
+      title={t("{{credential}} created", { credential: t("API key") })}
       size="lg"
     >
       <Stack gap="md">
@@ -41,7 +41,8 @@ export function ApiKeyCreatedModal({
           color="red"
         >
           {t(
-            "Make sure to copy your API key now. You won't be able to see it again!",
+            "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+            { credential: t("API key") },
           )}
         </Alert>
 
@@ -64,7 +65,7 @@ export function ApiKeyCreatedModal({
         </div>
 
         <Button fullWidth onClick={onClose} mt="md">
-          {t("I've saved my API key")}
+          {t("I've saved my {{credential}}", { credential: t("API key") })}
         </Button>
       </Stack>
     </Modal>

apps/client/src/ee/api-key/components/create-api-key-modal.tsx

@@ -105,7 +105,7 @@ export function CreateApiKeyModal({
     <Modal
       opened={opened}
       onClose={handleClose}
-      title={t("Create API Key")}
+      title={t("Create {{credential}}", { credential: t("API key") })}
       size="md"
     >
       <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>

apps/client/src/ee/api-key/components/revoke-api-key-modal.tsx

@@ -30,12 +30,14 @@ export function RevokeApiKeyModal({
     <Modal
       opened={opened}
       onClose={onClose}
-      title={t("Revoke API key")}
+      title={t("Revoke {{credential}}", { credential: t("API key") })}
       size="md"
     >
       <Stack gap="md">
         <Text>
-          {t("Are you sure you want to revoke this API key")}{" "}
+          {t("Are you sure you want to revoke this {{credential}}", {
+            credential: t("API key"),
+          })}{" "}
           <strong>{apiKey?.name}</strong>?
         </Text>
         <Text size="sm" c="dimmed">

apps/client/src/ee/api-key/components/update-api-key-modal.tsx

@@ -53,7 +53,7 @@ export function UpdateApiKeyModal({
     <Modal
       opened={opened}
       onClose={onClose}
-      title={t("Update API key")}
+      title={t("Update {{credential}}", { credential: t("API key") })}
       size="md"
     >
       <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>

apps/client/src/ee/api-key/queries/api-key-query.ts

@@ -63,7 +63,11 @@ export function useCreateApiKeyMutation() {
   return useMutation<IApiKey, Error, ICreateApiKeyRequest>({
     mutationFn: (data) => createApiKey(data),
     onSuccess: () => {
-      notifications.show({ message: t("API key created successfully") });
+      notifications.show({
+        message: t("{{credential}} created successfully", {
+          credential: t("API key"),
+        }),
+      });
       queryClient.invalidateQueries({
         predicate: (item) =>
           ["api-key-list"].includes(item.queryKey[0] as string),

apps/client/src/ee/audit/lib/audit-event-labels.ts

@@ -33,6 +33,10 @@ export const auditEventLabels: Record<string, string> = {
   "api_key.updated": "Updated API key",
   "api_key.deleted": "Deleted API key",
 
+  "scim_token.created": "Created SCIM token",
+  "scim_token.updated": "Updated SCIM token",
+  "scim_token.deleted": "Deleted SCIM token",
+
   "space.created": "Created space",
   "space.updated": "Updated space",
   "space.deleted": "Deleted space",
@@ -174,6 +178,14 @@ export const eventFilterOptions: EventGroup[] = [
       { value: "api_key.deleted", label: "Deleted API key" },
     ],
   },
+  {
+    group: "SCIM token",
+    items: [
+      { value: "scim_token.created", label: "Created SCIM token" },
+      { value: "scim_token.updated", label: "Updated SCIM token" },
+      { value: "scim_token.deleted", label: "Deleted SCIM token" },
+    ],
+  },
   {
     group: "License",
     items: [

apps/client/src/ee/features.ts

@@ -8,6 +8,7 @@ export const Feature = {
   AI: 'ai',
   CONFLUENCE_IMPORT: 'import:confluence',
   DOCX_IMPORT: 'import:docx',
+  PDF_IMPORT: 'import:pdf',
   ATTACHMENT_INDEXING: 'attachment:indexing',
   SECURITY_SETTINGS: 'security:settings',
   MCP: 'mcp',

apps/client/src/ee/page-permission/components/page-permission-list.tsx

@@ -140,7 +140,7 @@ export function PagePermissionList({
         )}
       </Group>
 
-      <ScrollArea mah={250} viewportRef={viewportRef}>
+      <ScrollArea.Autosize mah={400} viewportRef={viewportRef}>
         {sortedMembers.map((member) => (
           <PagePermissionItem
             key={`${member.type}-${member.id}`}
@@ -158,7 +158,7 @@ export function PagePermissionList({
             <Loader size="xs" />
           </Center>
         )}
-      </ScrollArea>
+      </ScrollArea.Autosize>
     </>
   );
 }

apps/client/src/ee/scim/components/create-scim-token-modal.tsx

@@ -0,0 +1,78 @@
+import { Modal, TextInput, Button, Group, Stack } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { zod4Resolver } from "mantine-form-zod-resolver";
+import { z } from "zod/v4";
+import { useTranslation } from "react-i18next";
+import { useCreateScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface CreateScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  onSuccess: (response: IScimToken) => void;
+}
+
+const formSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+});
+type FormValues = z.infer<typeof formSchema>;
+
+export function CreateScimTokenModal({
+  opened,
+  onClose,
+  onSuccess,
+}: CreateScimTokenModalProps) {
+  const { t } = useTranslation();
+  const createMutation = useCreateScimTokenMutation();
+
+  const form = useForm<FormValues>({
+    validate: zod4Resolver(formSchema),
+    initialValues: { name: "" },
+  });
+
+  const handleSubmit = async (data: FormValues) => {
+    try {
+      const created = await createMutation.mutateAsync({ name: data.name });
+      onSuccess(created);
+      form.reset();
+      onClose();
+    } catch (err) {
+      //
+    }
+  };
+
+  const handleClose = () => {
+    form.reset();
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={handleClose}
+      title={t("Create {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
+        <Stack gap="md">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("Enter a descriptive name")}
+            data-autofocus
+            required
+            {...form.getInputProps("name")}
+          />
+
+          <Group justify="flex-end" mt="md">
+            <Button variant="default" onClick={handleClose}>
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={createMutation.isPending}>
+              {t("Create")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}

apps/client/src/ee/scim/components/enable-scim.tsx

@@ -0,0 +1,55 @@
+import { Group, Text, Switch, Tooltip } from "@mantine/core";
+import { useAtom } from "jotai";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
+import React, { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { updateWorkspace } from "@/features/workspace/services/workspace-service.ts";
+import { notifications } from "@mantine/notifications";
+import { useHasFeature } from "@/ee/hooks/use-feature.ts";
+import { Feature } from "@/ee/features.ts";
+import { useUpgradeLabel } from "@/ee/hooks/use-upgrade-label.ts";
+
+export default function EnableScim() {
+  const { t } = useTranslation();
+  const [workspace, setWorkspace] = useAtom(workspaceAtom);
+  const [checked, setChecked] = useState(workspace?.isScimEnabled ?? false);
+  const hasAccess = useHasFeature(Feature.SCIM);
+  const upgradeLabel = useUpgradeLabel();
+
+  const handleChange = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const value = event.currentTarget.checked;
+    try {
+      const updatedWorkspace = await updateWorkspace({ isScimEnabled: value });
+      setChecked(value);
+      setWorkspace(updatedWorkspace);
+    } catch (err) {
+      notifications.show({
+        message: err?.response?.data?.message,
+        color: "red",
+      });
+    }
+  };
+
+  return (
+    <Group justify="space-between" wrap="nowrap" gap="xl">
+      <div>
+        <Text size="md">{t("Enable SCIM")}</Text>
+        <Text size="sm" c="dimmed">
+          {t(
+            "Automatically provision users and groups from your identity provider via SCIM.",
+          )}
+        </Text>
+      </div>
+
+      <Tooltip label={upgradeLabel} disabled={hasAccess} refProp="rootRef">
+        <Switch
+          labelPosition="left"
+          defaultChecked={checked}
+          onChange={handleChange}
+          disabled={!hasAccess}
+          aria-label={t("Toggle SCIM provisioning")}
+        />
+      </Tooltip>
+    </Group>
+  );
+}

apps/client/src/ee/scim/components/revoke-scim-token-modal.tsx

@@ -0,0 +1,61 @@
+import { Modal, Text, Button, Group, Stack } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import { useRevokeScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface RevokeScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function RevokeScimTokenModal({
+  opened,
+  onClose,
+  scimToken,
+}: RevokeScimTokenModalProps) {
+  const { t } = useTranslation();
+  const revokeMutation = useRevokeScimTokenMutation();
+
+  const handleRevoke = async () => {
+    if (!scimToken) return;
+    await revokeMutation.mutateAsync({ tokenId: scimToken.id });
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("Revoke {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <Stack gap="md">
+        <Text>
+          {t("Are you sure you want to revoke this {{credential}}", {
+            credential: t("SCIM token"),
+          })}{" "}
+          <strong>{scimToken?.name}</strong>?
+        </Text>
+        <Text size="sm" c="dimmed">
+          {t(
+            "This action cannot be undone. Your identity provider will stop syncing immediately.",
+          )}
+        </Text>
+
+        <Group justify="flex-end" mt="md">
+          <Button variant="default" onClick={onClose}>
+            {t("Cancel")}
+          </Button>
+          <Button
+            color="red"
+            onClick={handleRevoke}
+            loading={revokeMutation.isPending}
+          >
+            {t("Revoke")}
+          </Button>
+        </Group>
+      </Stack>
+    </Modal>
+  );
+}

apps/client/src/ee/scim/components/scim-token-created-modal.tsx

@@ -0,0 +1,69 @@
+import {
+  Modal,
+  Text,
+  Stack,
+  Alert,
+  Group,
+  Button,
+  TextInput,
+} from "@mantine/core";
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import CopyTextButton from "@/components/common/copy.tsx";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface ScimTokenCreatedModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function ScimTokenCreatedModal({
+  opened,
+  onClose,
+  scimToken,
+}: ScimTokenCreatedModalProps) {
+  const { t } = useTranslation();
+  if (!scimToken) return null;
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("{{credential}} created", { credential: t("SCIM token") })}
+      size="lg"
+    >
+      <Stack gap="md">
+        <Alert
+          icon={<IconAlertTriangle size={16} />}
+          title={t("Important")}
+          color="red"
+        >
+          {t(
+            "Make sure to copy your {{credential}} now. You won't be able to see it again!",
+            { credential: t("SCIM token") },
+          )}
+        </Alert>
+
+        <div>
+          <Text size="sm" fw={500} mb="xs">
+            {t("SCIM token")}
+          </Text>
+          <Group gap="xs" wrap="nowrap">
+            <TextInput
+              variant="filled"
+              style={{ flex: 1 }}
+              value={scimToken.token}
+              readOnly
+            />
+            <CopyTextButton text={scimToken.token} />
+          </Group>
+        </div>
+
+        <Button fullWidth onClick={onClose} mt="md">
+          {t("I've saved my {{credential}}", { credential: t("SCIM token") })}
+        </Button>
+      </Stack>
+    </Modal>
+  );
+}

apps/client/src/ee/scim/components/scim-token-table.tsx

@@ -0,0 +1,130 @@
+import { ActionIcon, Group, Menu, Table, Text } from "@mantine/core";
+import { IconDots, IconEdit, IconTrash } from "@tabler/icons-react";
+import { format } from "date-fns";
+import { useTranslation } from "react-i18next";
+import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import React from "react";
+import NoTableResults from "@/components/common/no-table-results";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+interface ScimTokenTableProps {
+  tokens: IScimToken[];
+  isLoading?: boolean;
+  onUpdate?: (token: IScimToken) => void;
+  onRevoke?: (token: IScimToken) => void;
+}
+
+export function ScimTokenTable({
+  tokens,
+  isLoading,
+  onUpdate,
+  onRevoke,
+}: ScimTokenTableProps) {
+  const { t } = useTranslation();
+
+  const formatDate = (date: Date | string | null) => {
+    if (!date) return t("Never");
+    return format(new Date(date), "MMM dd, yyyy");
+  };
+
+  return (
+    <Table.ScrollContainer minWidth={500}>
+      <Table highlightOnHover verticalSpacing="sm">
+        <Table.Thead>
+          <Table.Tr>
+            <Table.Th>{t("Name")}</Table.Th>
+            <Table.Th>{t("Token")}</Table.Th>
+            <Table.Th>{t("Created by")}</Table.Th>
+            <Table.Th>{t("Last used")}</Table.Th>
+            <Table.Th>{t("Created")}</Table.Th>
+            <Table.Th></Table.Th>
+          </Table.Tr>
+        </Table.Thead>
+
+        <Table.Tbody>
+          {tokens && tokens.length > 0 ? (
+            tokens.map((token) => (
+              <Table.Tr key={token.id}>
+                <Table.Td>
+                  <Text fz="sm" fw={500}>
+                    {token.name}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Text fz="sm" ff="monospace" c="dimmed">
+                    ••••{token.tokenLastFour}
+                  </Text>
+                </Table.Td>
+
+                {token.creator ? (
+                  <Table.Td>
+                    <Group gap="4" wrap="nowrap">
+                      <CustomAvatar
+                        avatarUrl={token.creator?.avatarUrl}
+                        name={token.creator.name}
+                        size="sm"
+                      />
+                      <Text fz="sm" lineClamp={1}>
+                        {token.creator.name}
+                      </Text>
+                    </Group>
+                  </Table.Td>
+                ) : (
+                  <Table.Td>
+                    <Text fz="sm" c="dimmed">
+                      —
+                    </Text>
+                  </Table.Td>
+                )}
+
+                <Table.Td>
+                  <Text fz="sm" style={{ whiteSpace: "nowrap" }}>
+                    {formatDate(token.lastUsedAt)}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Text fz="sm" style={{ whiteSpace: "nowrap" }}>
+                    {formatDate(token.createdAt)}
+                  </Text>
+                </Table.Td>
+
+                <Table.Td>
+                  <Menu position="bottom-end" withinPortal>
+                    <Menu.Target>
+                      <ActionIcon variant="subtle" color="gray">
+                        <IconDots size={16} />
+                      </ActionIcon>
+                    </Menu.Target>
+                    <Menu.Dropdown>
+                      {onUpdate && (
+                        <Menu.Item
+                          leftSection={<IconEdit size={16} />}
+                          onClick={() => onUpdate(token)}
+                        >
+                          {t("Rename")}
+                        </Menu.Item>
+                      )}
+                      {onRevoke && (
+                        <Menu.Item
+                          leftSection={<IconTrash size={16} />}
+                          color="red"
+                          onClick={() => onRevoke(token)}
+                        >
+                          {t("Revoke")}
+                        </Menu.Item>
+                      )}
+                    </Menu.Dropdown>
+                  </Menu>
+                </Table.Td>
+              </Table.Tr>
+            ))
+          ) : (
+            <NoTableResults colSpan={6} />
+          )}
+        </Table.Tbody>
+      </Table>
+    </Table.ScrollContainer>
+  );
+}

apps/client/src/ee/scim/components/scim-url-panel.tsx

@@ -0,0 +1,30 @@
+import { Group, Stack, Text, TextInput } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import CopyTextButton from "@/components/common/copy.tsx";
+
+export function ScimUrlPanel() {
+  const { t } = useTranslation();
+  const scimUrl = `${window.location.origin}/api/scim/v2`;
+
+  return (
+    <Stack gap="xs">
+      <Text size="sm" fw={500}>
+        {t("SCIM endpoint URL")}
+      </Text>
+      <Text size="xs" c="dimmed">
+        {t(
+          "Configure your identity provider with this URL to provision users and groups.",
+        )}
+      </Text>
+      <Group gap="xs" wrap="nowrap">
+        <TextInput
+          variant="filled"
+          style={{ flex: 1 }}
+          value={scimUrl}
+          readOnly
+        />
+        <CopyTextButton text={scimUrl} />
+      </Group>
+    </Stack>
+  );
+}

apps/client/src/ee/scim/components/update-scim-token-modal.tsx

@@ -0,0 +1,77 @@
+import { Modal, TextInput, Button, Group, Stack } from "@mantine/core";
+import { useForm } from "@mantine/form";
+import { zod4Resolver } from "mantine-form-zod-resolver";
+import { z } from "zod/v4";
+import { useTranslation } from "react-i18next";
+import { useEffect } from "react";
+import { useUpdateScimTokenMutation } from "@/ee/scim/queries/scim-token-query";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+const formSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+});
+type FormValues = z.infer<typeof formSchema>;
+
+interface UpdateScimTokenModalProps {
+  opened: boolean;
+  onClose: () => void;
+  scimToken: IScimToken | null;
+}
+
+export function UpdateScimTokenModal({
+  opened,
+  onClose,
+  scimToken,
+}: UpdateScimTokenModalProps) {
+  const { t } = useTranslation();
+  const updateMutation = useUpdateScimTokenMutation();
+
+  const form = useForm<FormValues>({
+    validate: zod4Resolver(formSchema),
+    initialValues: { name: "" },
+  });
+
+  useEffect(() => {
+    if (opened && scimToken) {
+      form.setValues({ name: scimToken.name });
+    }
+  }, [opened, scimToken]);
+
+  const handleSubmit = async (data: FormValues) => {
+    if (!scimToken) return;
+    await updateMutation.mutateAsync({
+      tokenId: scimToken.id,
+      name: data.name,
+    });
+    onClose();
+  };
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      title={t("Update {{credential}}", { credential: t("SCIM token") })}
+      size="md"
+    >
+      <form onSubmit={form.onSubmit((values) => handleSubmit(values))}>
+        <Stack gap="md">
+          <TextInput
+            label={t("Name")}
+            placeholder={t("Enter a descriptive name")}
+            required
+            {...form.getInputProps("name")}
+          />
+
+          <Group justify="flex-end" mt="md">
+            <Button variant="default" onClick={onClose}>
+              {t("Cancel")}
+            </Button>
+            <Button type="submit" loading={updateMutation.isPending}>
+              {t("Update")}
+            </Button>
+          </Group>
+        </Stack>
+      </form>
+    </Modal>
+  );
+}

apps/client/src/ee/scim/index.ts

@@ -0,0 +1,2 @@
+export * from "./types/scim-token.types";
+export * from "./services/scim-token-service";

apps/client/src/ee/scim/queries/scim-token-query.ts

@@ -0,0 +1,96 @@
+import { IPagination, QueryParams } from "@/lib/types.ts";
+import {
+  keepPreviousData,
+  useMutation,
+  useQuery,
+  useQueryClient,
+  UseQueryResult,
+} from "@tanstack/react-query";
+import {
+  createScimToken,
+  getScimTokens,
+  revokeScimToken,
+  updateScimToken,
+} from "@/ee/scim/services/scim-token-service";
+import {
+  IScimToken,
+  ICreateScimTokenRequest,
+  IRevokeScimTokenRequest,
+  IUpdateScimTokenRequest,
+} from "@/ee/scim/types/scim-token.types";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+
+export function useGetScimTokensQuery(
+  params?: QueryParams,
+): UseQueryResult<IPagination<IScimToken>, Error> {
+  return useQuery({
+    queryKey: ["scim-token-list", params],
+    queryFn: () => getScimTokens(params),
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useCreateScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<IScimToken, Error, ICreateScimTokenRequest>({
+    mutationFn: (data) => createScimToken(data),
+    onSuccess: () => {
+      notifications.show({
+        message: t("{{credential}} created successfully", {
+          credential: t("SCIM token"),
+        }),
+      });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}
+
+export function useUpdateScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<void, Error, IUpdateScimTokenRequest>({
+    mutationFn: (data) => updateScimToken(data),
+    onSuccess: () => {
+      notifications.show({ message: t("Updated successfully") });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}
+
+export function useRevokeScimTokenMutation() {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<void, Error, IRevokeScimTokenRequest>({
+    mutationFn: (data) => revokeScimToken(data),
+    onSuccess: () => {
+      notifications.show({ message: t("Revoked successfully") });
+      queryClient.invalidateQueries({
+        predicate: (item) =>
+          ["scim-token-list"].includes(item.queryKey[0] as string),
+      });
+    },
+    onError: (error) => {
+      const errorMessage = error["response"]?.data?.message;
+      notifications.show({ message: errorMessage, color: "red" });
+    },
+  });
+}

apps/client/src/ee/scim/services/scim-token-service.ts

@@ -0,0 +1,34 @@
+import api from "@/lib/api-client";
+import {
+  IScimToken,
+  ICreateScimTokenRequest,
+  IRevokeScimTokenRequest,
+  IUpdateScimTokenRequest,
+} from "@/ee/scim/types/scim-token.types";
+import { IPagination, QueryParams } from "@/lib/types.ts";
+
+export async function getScimTokens(
+  params?: QueryParams,
+): Promise<IPagination<IScimToken>> {
+  const req = await api.post("/scim-tokens", { ...params });
+  return req.data;
+}
+
+export async function createScimToken(
+  data: ICreateScimTokenRequest,
+): Promise<IScimToken> {
+  const req = await api.post<IScimToken>("/scim-tokens/create", data);
+  return req.data;
+}
+
+export async function updateScimToken(
+  data: IUpdateScimTokenRequest,
+): Promise<void> {
+  await api.post("/scim-tokens/update", data);
+}
+
+export async function revokeScimToken(
+  data: IRevokeScimTokenRequest,
+): Promise<void> {
+  await api.post("/scim-tokens/revoke", data);
+}

apps/client/src/ee/scim/types/scim-token.types.ts

@@ -0,0 +1,27 @@
+import { IUser } from "@/features/user/types/user.types.ts";
+
+export interface IScimToken {
+  id: string;
+  name: string;
+  token?: string;
+  tokenLastFour: string;
+  isEnabled: boolean;
+  creatorId: string;
+  workspaceId: string;
+  lastUsedAt: string | null;
+  createdAt: string;
+  creator?: Partial<IUser>;
+}
+
+export interface ICreateScimTokenRequest {
+  name: string;
+}
+
+export interface IUpdateScimTokenRequest {
+  tokenId: string;
+  name: string;
+}
+
+export interface IRevokeScimTokenRequest {
+  tokenId: string;
+}

apps/client/src/ee/security/components/sso-provider-list.tsx

@@ -69,8 +69,8 @@ export default function SsoProviderList() {
   return (
     <>
       <Card shadow="sm" radius="sm">
-        <Table.ScrollContainer minWidth={600}>
-          <Table verticalSpacing="sm">
+        <Table.ScrollContainer minWidth={600} maxHeight={400}>
+          <Table verticalSpacing="sm" stickyHeader>
             <Table.Thead>
               <Table.Tr>
                 <Table.Th>{t("Name")}</Table.Th>

apps/client/src/ee/security/pages/security.tsx

@@ -1,8 +1,18 @@
 import { Helmet } from "react-helmet-async";
 import { getAppName, isCloud } from "@/lib/config.ts";
 import SettingsTitle from "@/components/settings/settings-title.tsx";
-import { Divider, Title } from "@mantine/core";
-import React from "react";
+import {
+  Alert,
+  Button,
+  Card,
+  Divider,
+  Group,
+  Space,
+  Title,
+  Tooltip,
+} from "@mantine/core";
+import { IconInfoCircle } from "@tabler/icons-react";
+import React, { useState } from "react";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import SsoProviderList from "@/ee/security/components/sso-provider-list.tsx";
 import CreateSsoProvider from "@/ee/security/components/create-sso-provider.tsx";
@@ -12,16 +22,41 @@ import { useTranslation } from "react-i18next";
 import EnforceMfa from "@/ee/security/components/enforce-mfa.tsx";
 import DisablePublicSharing from "@/ee/security/components/disable-public-sharing.tsx";
 import TrashRetention from "@/ee/security/components/trash-retention.tsx";
-
+import { useAtom } from "jotai";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { useHasFeature } from "@/ee/hooks/use-feature";
 import { Feature } from "@/ee/features";
+import { useGetScimTokensQuery } from "@/ee/scim/queries/scim-token-query";
+import { ScimUrlPanel } from "@/ee/scim/components/scim-url-panel";
+import { ScimTokenTable } from "@/ee/scim/components/scim-token-table";
+import { CreateScimTokenModal } from "@/ee/scim/components/create-scim-token-modal";
+import { ScimTokenCreatedModal } from "@/ee/scim/components/scim-token-created-modal";
+import { RevokeScimTokenModal } from "@/ee/scim/components/revoke-scim-token-modal";
+import { UpdateScimTokenModal } from "@/ee/scim/components/update-scim-token-modal";
+import EnableScim from "@/ee/scim/components/enable-scim";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
+import Paginate from "@/components/common/paginate";
+import { IScimToken } from "@/ee/scim/types/scim-token.types";
+
+const SCIM_TOKEN_LIMIT = 5;
 
 export default function Security() {
   const { t } = useTranslation();
   const { isAdmin } = useUserRole();
   const hasCustomSso = useHasFeature(Feature.SSO_CUSTOM);
-  const hasRetention = useHasFeature(Feature.RETENTION);
-  const hasSharingControls = useHasFeature(Feature.SHARING_CONTROLS);
+  const hasScim = useHasFeature(Feature.SCIM);
+  const [workspace] = useAtom(workspaceAtom);
+  const isScimEnabled = workspace?.isScimEnabled ?? false;
+
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data: scimData, isLoading: scimLoading } = useGetScimTokensQuery(
+    hasScim && isScimEnabled ? { cursor } : undefined,
+  );
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [createdToken, setCreatedToken] = useState<IScimToken | null>(null);
+  const [updateTarget, setUpdateTarget] = useState<IScimToken | null>(null);
+  const [revokeTarget, setRevokeTarget] = useState<IScimToken | null>(null);
 
   if (!isAdmin) {
     return null;
@@ -45,7 +80,7 @@ export default function Security() {
       <Divider my="lg" />
 
       <Title order={4} my="lg">
-        Single sign-on (SSO)
+        {t("Single sign-on (SSO)")}
       </Title>
 
       <EnforceSso />
@@ -66,6 +101,102 @@ export default function Security() {
       )}
 
       <SsoProviderList />
+
+      {hasScim && (
+        <>
+          <Divider my="xl" />
+
+          <Title order={4} my="lg">
+            {t("SCIM provisioning")}
+          </Title>
+
+          <Alert
+            icon={<IconInfoCircle size={16} />}
+            color="blue"
+            variant="light"
+            mb="md"
+          >
+            {t("SCIM takes precedence over SSO group sync while enabled.")}
+          </Alert>
+
+          <EnableScim />
+
+          <Divider my="lg" />
+
+          <ScimUrlPanel />
+
+          {isScimEnabled && (
+            <>
+              <Divider my="lg" />
+
+              <Group justify="space-between" mb="md">
+                <Title order={5}>{t("SCIM tokens")}</Title>
+                <Tooltip
+                  label={t(
+                    "You have reached the maximum of {{max}} SCIM tokens. Delete an existing token to create a new one.",
+                    { max: SCIM_TOKEN_LIMIT },
+                  )}
+                  disabled={(scimData?.items.length ?? 0) < SCIM_TOKEN_LIMIT}
+                  refProp="rootRef"
+                >
+                  <Button
+                    onClick={() => setCreateOpen(true)}
+                    disabled={(scimData?.items.length ?? 0) >= SCIM_TOKEN_LIMIT}
+                  >
+                    {t("Create {{credential}}", {
+                      credential: t("SCIM token"),
+                    })}
+                  </Button>
+                </Tooltip>
+              </Group>
+
+              <Card shadow="sm" radius="sm">
+                <ScimTokenTable
+                  tokens={scimData?.items}
+                  isLoading={scimLoading}
+                  onUpdate={setUpdateTarget}
+                  onRevoke={setRevokeTarget}
+                />
+              </Card>
+
+              <Space h="md" />
+
+              {scimData?.items.length > 0 && (
+                <Paginate
+                  hasPrevPage={scimData?.meta?.hasPrevPage}
+                  hasNextPage={scimData?.meta?.hasNextPage}
+                  onNext={() => goNext(scimData?.meta?.nextCursor)}
+                  onPrev={goPrev}
+                />
+              )}
+
+              <CreateScimTokenModal
+                opened={createOpen}
+                onClose={() => setCreateOpen(false)}
+                onSuccess={setCreatedToken}
+              />
+
+              <ScimTokenCreatedModal
+                opened={!!createdToken}
+                onClose={() => setCreatedToken(null)}
+                scimToken={createdToken}
+              />
+
+              <UpdateScimTokenModal
+                opened={!!updateTarget}
+                onClose={() => setUpdateTarget(null)}
+                scimToken={updateTarget}
+              />
+
+              <RevokeScimTokenModal
+                opened={!!revokeTarget}
+                onClose={() => setRevokeTarget(null)}
+                scimToken={revokeTarget}
+              />
+            </>
+          )}
+        </>
+      )}
     </>
   );
 }

apps/client/src/features/comment/components/comment-editor.tsx

@@ -10,6 +10,7 @@ import { useTranslation } from "react-i18next";
 import EmojiCommand from "@/features/editor/extensions/emoji-command";
 import mentionRenderItems from "@/features/editor/components/mention/mention-suggestion";
 import MentionView from "@/features/editor/components/mention/mention-view";
+import { platformModifierKey } from "@/lib";
 
 interface CommentEditorProps {
   defaultContent?: any;
@@ -83,7 +84,7 @@ const CommentEditor = forwardRef(
               }
             }
 
-            if ((event.ctrlKey || event.metaKey) && event.key === "Enter") {
+            if (platformModifierKey(event) && event.code === "Enter") {
               event.preventDefault();
               if (onSave) onSave();
 

apps/client/src/features/editor/components/attachment/upload-attachment-action.tsx

@@ -19,7 +19,9 @@ export const uploadAttachmentAction = handleAttachmentUpload({
   },
   validateFn: (file, allowMedia: boolean) => {
     if (
-      (file.type.includes("image/") || file.type.includes("video/")) &&
+      (file.type.includes("image/") ||
+        file.type.includes("video/") ||
+        file.type === "application/pdf") &&
       !allowMedia
     ) {
       return false;

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"),
+        isTransclusion: ctx.editor.isActive("transclusion"),
       };
     },
   });
@@ -140,6 +142,12 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
       command: () => editor.chain().focus().setDetails().run(),
       isActive: () => editorState?.isDetails,
     },
+    {
+      name: "Sync block",
+      icon: IconQuote,
+      command: () => editor.chain().focus().toggleTransclusion().run(),
+      isActive: () => editorState?.isTransclusion,
+    },
   ];
 
   const activeItem = items.filter((item) => item.isActive()).pop() ?? {

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

@@ -25,6 +25,7 @@ import {
   IconColumns3,
   IconColumns2,
   IconTag,
+  IconRotate2,
 } from "@tabler/icons-react";
 import {
   CommandProps,
@@ -477,6 +478,23 @@ const CommandGroups: SlashMenuGroupedItemsType = {
         editor.chain().focus().deleteRange(range).insertSubpages().run();
       },
     },
+    {
+      title: "Sync block",
+      description: "Create a block that stays in sync across pages.",
+      searchTerms: [
+        "sync",
+        "synced",
+        "sync block",
+        "excerpt",
+        "transclusion",
+        "reusable",
+        "snippet",
+      ],
+      icon: IconRotate2,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).insertTransclusion().run();
+      },
+    },
     {
       title: "2 Columns",
       description: "Split content into two columns.",

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

@@ -0,0 +1,22 @@
+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={20}
+        stroke={1.5}
+        className={classes.placeholderIcon}
+      />
+      <div className={classes.placeholderTitle}>
+        {t("Failed to load transclusion")}
+      </div>
+      <div className={classes.placeholderSubtext}>
+        {t("An error occurred while rendering this reference")}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,16 @@
+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={20} stroke={1.5} className={classes.placeholderIcon} />
+      <div className={classes.placeholderTitle}>{t("No access")}</div>
+      <div className={classes.placeholderSubtext}>
+        {t("You don't have access to this content")}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,24 @@
+import { IconQuestionMark } 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}>
+      <IconQuestionMark
+        size={20}
+        stroke={1.5}
+        className={classes.placeholderIcon}
+      />
+      <div className={classes.placeholderTitle}>
+        {t("Synced block unavailable")}
+      </div>
+      <div className={classes.placeholderSubtext}>
+        {t(
+          "The source may have been removed, or embedding it here would create a loop.",
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,52 @@
+import { EditorProvider } from "@tiptap/react";
+import { useMemo } from "react";
+import { mainExtensions } from "@/features/editor/extensions/extensions";
+import { UniqueID } from "@docmost/editor-ext";
+import { TransclusionLookupProvider } from "./transclusion-lookup-context";
+
+type Props = {
+  hostPageId: string;
+  content: unknown;
+};
+
+export default function TransclusionContent({ hostPageId, content }: Props) {
+  const extensions = useMemo(() => {
+    const filtered = mainExtensions.filter(
+      (e: any) => e.name !== "uniqueID" && e.name !== "globalDragHandle",
+    );
+    return [
+      ...filtered,
+      UniqueID.configure({
+        types: ["heading", "paragraph", "transclusion"],
+        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 (
+    <TransclusionLookupProvider hostPageId={hostPageId}>
+      <div
+        onMouseDown={stop}
+        onClick={stop}
+        onDragStart={stop}
+        onDragOver={stop}
+        onDrop={stop}
+      >
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={extensions}
+          content={content as any}
+        />
+      </div>
+    </TransclusionLookupProvider>
+  );
+}

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

@@ -0,0 +1,198 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { lookupTransclusion } 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,
+}: {
+  /**
+   * Retained for API compatibility with previous callers that passed the
+   * host page id; no longer used internally now that cycle prevention lives
+   * on the server side and lookups are stateless.
+   */
+  hostPageId?: string;
+  children: React.ReactNode;
+}) {
+  const subscribersRef = useRef(new Map<LookupKey, Subscriber[]>());
+  const queueRef = useRef(new Set<LookupKey>());
+  const tickRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // 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 { items } = 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,204 @@
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconDots,
+  IconExternalLink,
+  IconLinkOff,
+  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;
+    if (source?.spaceSlug) {
+      return buildPageUrl(source.spaceSlug, source.slugId, source.title);
+    }
+    return sourcePageId ? `/p/${sourcePageId}` : null;
+  })();
+
+  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}>
+          {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("Go to source page")}>
+              <ActionIcon
+                component={Link}
+                to={sourcePageHref}
+                variant="subtle"
+                color="gray"
+                size="sm"
+              >
+                <IconExternalLink 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
+          hostPageId={hostPageId ?? sourcePageId}
+          content={result.content}
+        />
+      ) : result.status === "no_access" ? (
+        <NoAccessPlaceholder />
+      ) : (
+        <NotFoundPlaceholder />
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,122 @@
+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().unsyncTransclusion().run();
+  };
+
+  return (
+    <NodeViewWrapper
+      className={classes.transclusionWrap}
+      data-drag-handle
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+    >
+      {isEditable && (
+        <div className={classes.transclusionControls} contentEditable={false}>
+          {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 sync block")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}

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

@@ -0,0 +1,199 @@
+.placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: var(--mantine-spacing-md);
+  border-radius: var(--mantine-radius-md);
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  border: 1px dashed
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+}
+
+.placeholderIcon {
+  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+}
+
+.placeholderTitle {
+  font-weight: 600;
+  font-size: var(--mantine-font-size-sm);
+}
+
+.placeholderSubtext {
+  font-size: var(--mantine-font-size-xs);
+  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  text-align: center;
+}
+
+.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: 4px;
+  border: 1px solid transparent;
+  transition: border 0.3s;
+}
+
+.transclusionWrap:hover,
+.transclusionWrap:focus-within {
+  border: 1px solid
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-gray-7));
+}
+
+.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);
+}
+
+.includeWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 0;
+  border-radius: 4px;
+  border: 1px solid transparent;
+  transition: border 0.3s;
+}
+
+.includeWrap:hover,
+.includeWrap[data-focused="true"],
+.includeWrap[data-menu-open="true"] {
+  border: 1px solid
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-gray-7));
+}
+
+.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-transclusion.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;
+  }
+}
+
+.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,
+      scrollTreshold: 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,7 +9,6 @@ import SubScript from "@tiptap/extension-subscript";
 import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
-import GlobalDragHandle from "tiptap-extension-global-drag-handle";
 import { Youtube } from "@tiptap/extension-youtube";
 import SlashCommand, { SlashCommandExtension as Command } from "@/features/editor/extensions/slash-command";
 import renderItems from "@/features/editor/components/slash-menu/render-items";
@@ -52,6 +51,8 @@ import {
   Columns,
   Column,
   Status,
+  Transclusion,
+  TransclusionReference,
 } from "@docmost/editor-ext";
 import {
   randomElement,
@@ -80,6 +81,8 @@ import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-v
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import PdfView from "@/features/editor/components/pdf/pdf-view.tsx";
 import SubpagesView from "@/features/editor/components/subpages/subpages-view.tsx";
+import TransclusionView from "@/features/editor/components/transclusion/transclusion-view.tsx";
+import TransclusionReferenceView from "@/features/editor/components/transclusion/transclusion-reference-view.tsx";
 import { common, createLowlight } from "lowlight";
 import plaintext from "highlight.js/lib/languages/plaintext";
 import powershell from "highlight.js/lib/languages/powershell";
@@ -100,6 +103,7 @@ import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboa
 import EmojiCommand from "./emoji-command";
 import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
+import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";
 
 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -167,7 +171,7 @@ export const mainExtensions = [
   SharedStorage,
   Heading,
   UniqueID.configure({
-    types: ["heading", "paragraph"],
+    types: ["heading", "paragraph", "transclusion"],
     filterTransaction: (transaction) => !isChangeOrigin(transaction),
   }),
   Placeholder.configure({
@@ -215,7 +219,9 @@ export const mainExtensions = [
   }),
   Typography,
   TrailingNode,
-  GlobalDragHandle,
+  GlobalDragHandle.configure({
+    customNodes: ["transclusion", "transclusionReference"],
+  }),
   TextStyle,
   Color,
   SlashCommand,
@@ -351,6 +357,12 @@ export const mainExtensions = [
   Status.configure({
     view: StatusView,
   }),
+  Transclusion.configure({
+    view: TransclusionView,
+  }),
+  TransclusionReference.configure({
+    view: TransclusionReferenceView,
+  }),
   MarkdownClipboard.configure({
     transformPastedText: true,
   }),

apps/client/src/features/editor/extensions/markdown-clipboard.ts

@@ -80,10 +80,12 @@ export const MarkdownClipboard = Extension.create({
             const { from, to } = view.state.selection;
 
             const parsed = markdownToHtml(text.replace(/\n+$/, ""));
+            const body = elementFromString(parsed);
+            normalizeTableColumnWidths(body);
 
             const contentNodes = DOMParser.fromSchema(
               this.editor.schema,
-            ).parseSlice(elementFromString(parsed), {
+            ).parseSlice(body, {
               preserveWhitespace: true,
             });
 
@@ -137,3 +139,92 @@ function elementFromString(value) {
 
   return new window.DOMParser().parseFromString(wrappedValue, "text/html").body;
 }
+
+const DEFAULT_PASTE_COL_WIDTH_PX = 150;
+
+function parsePixelWidth(el: Element): number | null {
+  const attr = el.getAttribute("width");
+  if (attr) {
+    const n = parseInt(attr, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  const style = el.getAttribute("style") || "";
+  const m = style.match(/(?:^|;)\s*width\s*:\s*([\d.]+)\s*px/i);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+function getFirstRow(table: Element): Element | null {
+  const tbodyRow = table.querySelector(":scope > tbody > tr");
+  if (tbodyRow) return tbodyRow;
+  const theadRow = table.querySelector(":scope > thead > tr");
+  if (theadRow) return theadRow;
+  return table.querySelector(":scope > tr");
+}
+
+function deriveColumnWidths(table: Element): (number | null)[] | null {
+  const cols = table.querySelectorAll(":scope > colgroup > col");
+  if (cols.length > 0) {
+    const widths: (number | null)[] = [];
+    cols.forEach((col) => widths.push(parsePixelWidth(col)));
+    if (widths.some((w) => w !== null)) return widths;
+  }
+
+  const firstRow = getFirstRow(table);
+  if (!firstRow) return null;
+
+  const widths: (number | null)[] = [];
+  Array.from(firstRow.children)
+    .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+    .forEach((cell) => {
+      const colspan = parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+      const w = parsePixelWidth(cell);
+      for (let i = 0; i < colspan; i++) {
+        widths.push(w !== null ? Math.round(w / colspan) : null);
+      }
+    });
+  if (widths.length === 0 || widths.every((w) => w === null)) return null;
+  return widths;
+}
+
+// Mirror of server normalizeTableColumnWidths (see import/utils/table-utils.ts):
+// markdown source has no widths, so without this every pasted table renders
+// at table-layout:fixed/100% and squashes columns to fit the editor instead of
+// letting .tableWrapper's overflow-x: auto scroll.
+export function normalizeTableColumnWidths(root: Element): void {
+  root.querySelectorAll("table").forEach((table) => {
+    const firstRow = getFirstRow(table);
+    if (!firstRow) return;
+
+    let colWidths = deriveColumnWidths(table);
+    if (!colWidths) {
+      let count = 0;
+      Array.from(firstRow.children)
+        .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+        .forEach((cell) => {
+          count += parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+        });
+      if (count === 0) return;
+      colWidths = new Array(count).fill(DEFAULT_PASTE_COL_WIDTH_PX);
+    }
+
+    let col = 0;
+    Array.from(firstRow.children)
+      .filter((c) => c.tagName === "TD" || c.tagName === "TH")
+      .forEach((cell) => {
+        if (cell.getAttribute("colwidth")) {
+          col += parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+          return;
+        }
+        const colspan = parseInt(cell.getAttribute("colspan") || "1", 10) || 1;
+        const slice = colWidths!.slice(col, col + colspan);
+        col += colspan;
+        if (slice.length === 0 || slice.every((w) => w === null)) return;
+        const values = slice.map((w) => (w == null ? 100 : w));
+        cell.setAttribute("colwidth", values.join(","));
+      });
+  });
+}

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

@@ -62,7 +62,7 @@ import { useIdle } from "@/hooks/use-idle.ts";
 import { queryClient } from "@/main.tsx";
 import { IPage } from "@/features/page/types/page.types.ts";
 import { useParams } from "react-router-dom";
-import { extractPageSlugId } from "@/lib";
+import { extractPageSlugId, platformModifierKey } from "@/lib";
 import { FIVE_MINUTES } from "@/lib/constants.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { jwtDecode } from "jwt-decode";
@@ -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;
@@ -232,11 +233,19 @@ export default function PageEditor({
         scrollMargin: 80,
         handleDOMEvents: {
           keydown: (_view, event) => {
-            if ((event.ctrlKey || event.metaKey) && event.code === "KeyS") {
+            if (platformModifierKey(event) && event.code === "KeyS") {
               event.preventDefault();
               return true;
             }
-            if ((event.ctrlKey || event.metaKey) && event.code === "KeyK") {
+            if (event.key === "Tab") {
+                const editor = editorRef.current;
+                if (!editor) return false;
+                event.preventDefault();
+                return editor.view.someProp("handleKeyDown", (f) =>
+                  f(editor.view, event)
+                );
+            }
+            if (platformModifierKey(event) && event.code === "KeyK") {
               searchSpotlight.open();
               return true;
             }
@@ -391,55 +400,60 @@ export default function PageEditor({
     }
   }, [yjsConnectionStatus, isSynced]);
 
-  if (showStatic) {
-    return (
-      <EditorProvider
-        editable={false}
-        immediatelyRender={true}
-        extensions={mainExtensions}
-        content={content}
-      />
-    );
-  }
-
   return (
-    <div className="editor-container" style={{ position: "relative" }}>
-      <div ref={menuContainerRef}>
-        <EditorContent editor={editor} />
+    <TransclusionLookupProvider hostPageId={pageId}>
+      {showStatic ? (
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+        />
+      ) : (
+        <div className="editor-container" style={{ position: "relative" }}>
+          <div ref={menuContainerRef}>
+            <EditorContent editor={editor} />
 
-        {editor && (
-          <SearchAndReplaceDialog editor={editor} editable={editable} />
-        )}
+            {editor && (
+              <SearchAndReplaceDialog editor={editor} editable={editable} />
+            )}
 
-        {editor && editorIsEditable && (
-          <div>
-            <EditorAiMenu editor={editor} />
-            <EditorLinkMenu editor={editor} />
-            <EditorBubbleMenu editor={editor} />
-            <TableMenu editor={editor} />
-            <TableCellMenu editor={editor} appendTo={menuContainerRef} />
-            <ImageMenu editor={editor} />
-            <VideoMenu editor={editor} />
-            <PdfMenu editor={editor} />
-            <CalloutMenu editor={editor} />
-            <SubpagesMenu editor={editor} />
-            <ExcalidrawMenu editor={editor} />
-            <DrawioMenu editor={editor} />
-            <ColumnsMenu editor={editor} />
+            {editor && editorIsEditable && (
+              <div>
+                <EditorAiMenu editor={editor} />
+                <EditorLinkMenu editor={editor} />
+                <EditorBubbleMenu editor={editor} />
+                <TableMenu editor={editor} />
+                <TableCellMenu editor={editor} appendTo={menuContainerRef} />
+                <ImageMenu editor={editor} />
+                <VideoMenu editor={editor} />
+                <PdfMenu editor={editor} />
+                <CalloutMenu editor={editor} />
+                <SubpagesMenu editor={editor} />
+                <ExcalidrawMenu editor={editor} />
+                <DrawioMenu editor={editor} />
+                <ColumnsMenu editor={editor} />
+              </div>
+            )}
+            {editor &&
+              !editorIsEditable &&
+              (editable || canComment) &&
+              providersRef.current && (
+                <ReadonlyBubbleMenu editor={editor} />
+              )}
+            {showCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} />
+            )}
+            {showReadOnlyCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} readOnly />
+            )}
           </div>
-        )}
-        {editor && !editorIsEditable && (editable || canComment) && providersRef.current && (
-          <ReadonlyBubbleMenu editor={editor} />
-        )}
-        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
-        {showReadOnlyCommentPopup && (
-          <CommentDialog editor={editor} pageId={pageId} readOnly />
-        )}
-      </div>
-      <div
-        onClick={() => editor.commands.focus("end")}
-        style={{ paddingBottom: "20vh" }}
-      ></div>
-    </div>
+          <div
+            onClick={() => editor.commands.focus("end")}
+            style={{ paddingBottom: "20vh" }}
+          ></div>
+        </div>
+      )}
+    </TransclusionLookupProvider>
   );
 }

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

@@ -9,6 +9,7 @@ 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;
@@ -65,7 +66,7 @@ export default function ReadonlyPageEditor({
   ];
 
   return (
-    <>
+    <TransclusionLookupProvider hostPageId={pageId ?? "anonymous"}>
       <div className="page-title">
         <EditorProvider
           editable={false}
@@ -95,6 +96,6 @@ export default function ReadonlyPageEditor({
         }}
       ></EditorProvider>
       <div style={{ paddingBottom: "20vh" }}></div>
-    </>
+    </TransclusionLookupProvider>
   );
 }

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

@@ -27,6 +27,7 @@ import localEmitter from "@/lib/local-emitter.ts";
 import { currentUserAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { PageEditMode } from "@/features/user/types/user.types.ts";
 import { searchSpotlight } from "@/features/search/constants.ts";
+import { platformModifierKey } from "@/lib";
 
 export interface TitleEditorProps {
   pageId: string;
@@ -90,11 +91,11 @@ export function TitleEditor({
     editorProps: {
       handleDOMEvents: {
         keydown: (_view, event) => {
-          if ((event.ctrlKey || event.metaKey) && event.code === "KeyS") {
+          if (platformModifierKey(event) && event.code === "KeyS") {
             event.preventDefault();
             return true;
           }
-          if ((event.ctrlKey || event.metaKey) && event.code === "KeyK") {
+          if (platformModifierKey(event) && event.code === "KeyK") {
             searchSpotlight.open();
             return true;
           }

apps/client/src/features/page/components/page-import-modal.tsx

@@ -12,6 +12,7 @@ import {
   IconCheck,
   IconFileCode,
   IconFileTypeDocx,
+  IconFileTypePdf,
   IconFileTypeZip,
   IconMarkdown,
   IconX,
@@ -90,12 +91,14 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
   const markdownFileRef = useRef<() => void>(null);
   const htmlFileRef = useRef<() => void>(null);
   const docxFileRef = useRef<() => void>(null);
+  const pdfFileRef = useRef<() => void>(null);
   const notionFileRef = useRef<() => void>(null);
   const confluenceFileRef = useRef<() => void>(null);
   const zipFileRef = useRef<() => void>(null);
 
   const canUseConfluence = useHasFeature(Feature.CONFLUENCE_IMPORT);
   const canUseDocx = useHasFeature(Feature.DOCX_IMPORT);
+  const canUsePdf = useHasFeature(Feature.PDF_IMPORT);
   const upgradeLabel = useUpgradeLabel();
 
   const handleZipUpload = async (selectedFile: File, source: string) => {
@@ -244,7 +247,7 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
     }, 3000);
   }, [fileTaskId]);
 
-  const maxSingleFileSize = bytes("20mb");
+  const maxSingleFileSize = bytes("30mb");
 
   const handleFileUpload = async (selectedFiles: File[]) => {
     if (!selectedFiles) {
@@ -298,6 +301,7 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
       if (markdownFileRef.current) markdownFileRef.current();
       if (htmlFileRef.current) htmlFileRef.current();
       if (docxFileRef.current) docxFileRef.current();
+      if (pdfFileRef.current) pdfFileRef.current();
 
       const pageCountText =
         pageCount === 1 ? `1 ${t("page")}` : `${pageCount} ${t("pages")}`;
@@ -378,6 +382,30 @@ function ImportFormatSelection({ spaceId, onClose }: ImportFormatSelection) {
           )}
         </FileButton>
 
+        <FileButton
+          onChange={handleFileUpload}
+          accept=".pdf"
+          multiple
+          resetRef={pdfFileRef}
+        >
+          {(props) => (
+            <Tooltip
+              label={upgradeLabel}
+              disabled={canUsePdf}
+            >
+              <Button
+                disabled={!canUsePdf}
+                justify="start"
+                variant="default"
+                leftSection={<IconFileTypePdf size={18} />}
+                {...props}
+              >
+                PDF
+              </Button>
+            </Tooltip>
+          )}
+        </FileButton>
+
         <FileButton
           onChange={(file) => handleZipUpload(file, "notion")}
           accept="application/zip"

apps/client/src/features/search/components/search-control.tsx

@@ -13,6 +13,7 @@ import {
 import classes from "./search-control.module.css";
 import React from "react";
 import { useTranslation } from "react-i18next";
+import { platformModifierLabel } from "@/lib";
 
 interface SearchControlProps extends BoxProps, ElementProps<"button"> {}
 
@@ -27,7 +28,7 @@ export function SearchControl({ className, ...others }: SearchControlProps) {
           {t("Search")}
         </Text>
         <Text fw={700} className={classes.shortcut}>
-          Ctrl + K
+          {platformModifierLabel} + K
         </Text>
       </Group>
     </UnstyledButton>

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,29 @@
+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 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/workspace/types/workspace.types.ts

@@ -28,6 +28,7 @@ export interface IWorkspace {
   trashRetentionDays?: number;
   restrictApiToAdmins?: boolean;
   allowMemberTemplates?: boolean;
+  isScimEnabled?: boolean;
 }
 
 export interface IWorkspaceSettings {

apps/client/src/lib/utils.tsx

@@ -100,6 +100,15 @@ export const normalizeUrl = (url: string): string => {
   return `https://${url}`;
 };
 
+const _isApple = /mac|iphone|ipad|ipod/i.test(navigator.platform ?? "");
+
+/// Cmd key on Apple devices, Ctrl key everywhere else
+export function platformModifierKey(event: KeyboardEvent): boolean {
+  return _isApple ? event.metaKey : event.ctrlKey;
+}
+
+export const platformModifierLabel = _isApple ? "⌘" : "Ctrl";
+
 export function castToBoolean(value: unknown): boolean {
   if (value == null) {
     return false;

apps/server/package.json

@@ -33,10 +33,11 @@
     "@ai-sdk/google": "^3.0.52",
     "@ai-sdk/openai": "^3.0.47",
     "@ai-sdk/openai-compatible": "^2.0.37",
-    "@aws-sdk/client-s3": "3.1037.0",
-    "@aws-sdk/lib-storage": "3.1037.0",
-    "@aws-sdk/s3-request-presigner": "3.1037.0",
+    "@aws-sdk/client-s3": "3.1040.0",
+    "@aws-sdk/lib-storage": "3.1040.0",
+    "@aws-sdk/s3-request-presigner": "3.1040.0",
     "@clickhouse/client": "^1.18.2",
+    "@docmost/pdf-inspector": "1.9.4",
     "@fastify/cookie": "^11.0.2",
     "@fastify/multipart": "^10.0.0",
     "@fastify/static": "^9.1.3",
@@ -100,7 +101,6 @@
     "p-limit": "^7.3.0",
     "passport-google-oauth20": "^2.0.0",
     "passport-jwt": "^4.0.1",
-    "pdfjs-dist": "^5.5.207",
     "pg-tsquery": "^8.4.2",
     "pgvector": "^0.2.1",
     "pino-http": "^11.0.0",
@@ -111,6 +111,7 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "sanitize-filename": "1.6.3",
+    "scimmy": "1.3.5",
     "socket.io": "^4.8.3",
     "stripe": "^17.7.0",
     "tlds": "^1.261.0",

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

@@ -18,6 +18,7 @@ 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';
 
 @Module({
   providers: [
@@ -28,6 +29,7 @@ import { WatcherModule } from '../core/watcher/watcher.module';
     HistoryProcessor,
     CollabHistoryService,
     CollaborationHandler,
+    TransclusionService,
   ],
   exports: [CollaborationGateway],
   imports: [TokenModule, WatcherModule],

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

@@ -40,6 +40,8 @@ import {
   Status,
   addUniqueIdsToDoc,
   htmlToMarkdown,
+  Transclusion,
+  TransclusionReference,
 } from '@docmost/editor-ext';
 import { generateText, getSchema, JSONContent } from '@tiptap/core';
 import { generateHTML, generateJSON } from '../common/helpers/prosemirror/html';
@@ -101,6 +103,8 @@ export const tiptapExtensions = [
   Columns,
   Column,
   Status,
+  Transclusion,
+  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, 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,29 @@ 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,
+    tiptapJson: unknown,
+  ): Promise<void> {
+    try {
+      await this.transclusionService.syncPageTransclusions(pageId, tiptapJson);
+    } catch (err) {
+      this.logger.error(`Failed to sync transclusions for page ${pageId}`, err);
+    }
+    try {
+      await this.transclusionService.syncPageReferences(pageId, tiptapJson);
+    } catch (err) {
+      this.logger.error(
+        `Failed to sync transclusion references for page ${pageId}`,
+        err,
+      );
+    }
+  }
 }

apps/server/src/common/events/audit-events.ts

@@ -23,6 +23,11 @@ export const AuditEvent = {
   API_KEY_UPDATED: 'api_key.updated',
   API_KEY_DELETED: 'api_key.deleted',
 
+  // SCIM Tokens
+  SCIM_TOKEN_CREATED: 'scim_token.created',
+  SCIM_TOKEN_UPDATED: 'scim_token.updated',
+  SCIM_TOKEN_DELETED: 'scim_token.deleted',
+
   // Space
   SPACE_CREATED: 'space.created',
   SPACE_UPDATED: 'space.updated',
@@ -119,6 +124,7 @@ export const AuditResource = {
   COMMENT: 'comment',
   SHARE: 'share',
   API_KEY: 'api_key',
+  SCIM_TOKEN: 'scim_token',
   SSO_PROVIDER: 'sso_provider',
   WORKSPACE_INVITATION: 'workspace_invitation',
   ATTACHMENT: 'attachment',

apps/server/src/common/features.ts

@@ -8,6 +8,7 @@ export const Feature = {
   AI: 'ai',
   CONFLUENCE_IMPORT: 'import:confluence',
   DOCX_IMPORT: 'import:docx',
+  PDF_IMPORT: 'import:pdf',
   ATTACHMENT_INDEXING: 'attachment:indexing',
   SECURITY_SETTINGS: 'security:settings',
   MCP: 'mcp',

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

@@ -110,7 +110,7 @@ export function extractBearerTokenFromHeader(
   request: FastifyRequest,
 ): string | undefined {
   const [type, token] = request.headers.authorization?.split(' ') ?? [];
-  return type === 'Bearer' ? token : undefined;
+  return type?.toLowerCase() === 'bearer' ? token : undefined;
 }
 
 /**

apps/server/src/core/group/services/group-user.service.ts

@@ -7,7 +7,7 @@ import {
 } from '@nestjs/common';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { GroupService } from './group.service';
-import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
 import { InjectKysely } from 'nestjs-kysely';
 import { GroupUserRepo } from '@docmost/db/repos/group/group-user.repo';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
@@ -20,6 +20,7 @@ import {
   AUDIT_SERVICE,
   IAuditService,
 } from '../../../integrations/audit/audit.service';
+import { dbOrTx } from '@docmost/db/utils';
 
 @Injectable()
 export class GroupUserService {
@@ -54,17 +55,23 @@ export class GroupUserService {
     userIds: string[],
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<void> {
-    await this.groupService.findAndValidateGroup(groupId, workspaceId);
+    const db = dbOrTx(this.db, trx);
+    await this.groupService.findAndValidateGroup(groupId, workspaceId, trx);
+
+    if (userIds.length === 0) return;
 
     // make sure we have valid workspace users
-    const validUsers = await this.db
+    const validUsers = await db
       .selectFrom('users')
       .select(['id', 'name'])
       .where('users.id', 'in', userIds)
       .where('users.workspaceId', '=', workspaceId)
       .execute();
 
+    if (validUsers.length === 0) return;
+
     // prepare users to add to group
     const groupUsersToInsert = [];
     for (const user of validUsers) {
@@ -75,7 +82,7 @@ export class GroupUserService {
     }
 
     // batch insert new group users
-    await this.db
+    await db
       .insertInto('groupUsers')
       .values(groupUsersToInsert)
       .onConflict((oc) => oc.columns(['userId', 'groupId']).doNothing())

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

@@ -216,8 +216,11 @@ export class GroupService {
   async findAndValidateGroup(
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<Group> {
-    const group = await this.groupRepo.findById(groupId, workspaceId);
+    const group = await this.groupRepo.findById(groupId, workspaceId, {
+      trx,
+    });
     if (!group) {
       throw new NotFoundException('Group not found');
     }

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,31 @@ 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, 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, 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,24 @@
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsString,
+  IsUUID,
+  ValidateNested,
+} from 'class-validator';
+
+export class LookupReferenceDto {
+  @IsUUID()
+  sourcePageId!: string;
+
+  @IsString()
+  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,232 @@
+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, name and content', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'abc123', name: 'Pricing' },
+          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].name).toBe('Pricing');
+    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: 'transclusion', attrs: {}, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    expect(collectTransclusionsFromPmJson(doc)).toEqual([]);
+  });
+
+  it('returns multiple top-level transclusions', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: { id: 'a' }, content: [{ type: 'paragraph' }] },
+        { type: 'transclusion', attrs: { id: 'b', name: 'Two' }, 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: 'transclusion',
+          attrs: { id: 'outer' },
+          content: [
+            {
+              type: 'transclusion',
+              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: 'transclusion', 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: 'transclusion', attrs: { id: 'dup', name: 'first' }, content: [{ type: 'paragraph' }] },
+        { type: 'transclusion', attrs: { id: 'dup', name: 'second' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+    const got = collectTransclusionsFromPmJson(doc);
+    expect(got).toHaveLength(1);
+    expect(got[0].name).toBe('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([
+      { containingTransclusionId: null, 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([
+      { containingTransclusionId: null, sourcePageId: 'p1', transclusionId: 'e1' },
+      { containingTransclusionId: null, sourcePageId: 'p2', transclusionId: 'e2' },
+    ]);
+  });
+
+  it('also finds references nested inside a transclusion (source) node', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'src1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+            },
+          ],
+        },
+      ],
+    };
+    expect(collectReferencesFromPmJson(doc)).toEqual([
+      { containingTransclusionId: 'src1', sourcePageId: 'p1', transclusionId: 'e1' },
+    ]);
+  });
+
+  it('dedupes identical (containingTransclusionId, sourcePageId, transclusionId) triples', () => {
+    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([
+      { containingTransclusionId: null, sourcePageId: 'p1', transclusionId: 'e1' },
+      { containingTransclusionId: null, 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,78 @@
+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' } as any;
+  const ref = { sourcePageId: 'p1', transclusionId: 'e1' };
+
+  it('returns content when lookup succeeds', 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');
+  });
+
+  it('returns no_access when service says no_access', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          status: 'no_access',
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect((out.items[0] as { status?: string }).status).toBe('no_access');
+  });
+
+  it('returns not_found when service says not_found', async () => {
+    service.lookup.mockResolvedValue({
+      items: [
+        {
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+          status: 'not_found',
+        },
+      ],
+    } as any);
+
+    const out = await controller.lookup({ references: [ref] } as any, user);
+    expect((out.items[0] as { status?: string }).status).toBe('not_found');
+  });
+});

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

@@ -0,0 +1,412 @@
+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-transclusion-references/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';
+
+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: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    repo = module.get(PageTransclusionsRepo);
+  });
+
+  const pageId = '00000000-0000-0000-0000-000000000001';
+
+  it('inserts new transclusions that did not exist before', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'Hello' },
+          content: [{ type: 'paragraph' }],
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 1, updated: 0, deleted: 0 });
+    expect(repo.insert).toHaveBeenCalledTimes(1);
+    expect(repo.insert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        pageId,
+        transclusionId: 'a',
+        name: 'Hello',
+      }),
+      undefined,
+    );
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.deleteByPageAndTransclusionIds).not.toHaveBeenCalled();
+  });
+
+  it('updates transclusions whose name or content changed', async () => {
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        name: 'Old',
+        content: { type: 'doc', content: [{ type: 'paragraph' }] },
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'New' },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'X' }] },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, pm);
+
+    expect(result).toEqual({ inserted: 0, updated: 1, deleted: 0 });
+    expect(repo.update).toHaveBeenCalledWith(
+      pageId,
+      'a',
+      expect.objectContaining({ name: 'New' }),
+      undefined,
+    );
+  });
+
+  it('skips update when name and content are unchanged', async () => {
+    const sameContent = {
+      type: 'doc',
+      content: [{ type: 'paragraph' }],
+    };
+    repo.findByPageId.mockResolvedValue([
+      {
+        id: 'row1',
+        pageId,
+        transclusionId: 'a',
+        name: 'Same',
+        content: sameContent,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 'a', name: 'Same' },
+          content: sameContent.content,
+        },
+      ],
+    };
+
+    const result = await service.syncPageTransclusions(pageId, 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',
+        name: null,
+        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, 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, 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();
+  });
+
+  it('passes through the trx parameter to repo calls', async () => {
+    repo.findByPageId.mockResolvedValue([]);
+    const trx = { mock: 'trx' } as any;
+    const pm = {
+      type: 'doc',
+      content: [
+        { type: 'transclusion', attrs: { id: 'a' }, content: [{ type: 'paragraph' }] },
+      ],
+    };
+
+    await service.syncPageTransclusions(pageId, pm, trx);
+
+    expect(repo.findByPageId).toHaveBeenCalledWith(pageId, trx);
+    expect(repo.insert).toHaveBeenCalledWith(expect.anything(), trx);
+  });
+});
+
+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(),
+      findCyclicEdgesForSource: jest.fn().mockResolvedValue([]),
+      deleteByIds: 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: {} },
+      ],
+    }).compile();
+    service = module.get(TransclusionService);
+    refRepo = module.get(PageTransclusionReferencesRepo);
+  });
+
+  const referencePageId = '00000000-0000-0000-0000-000000000001';
+
+  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, pm);
+
+    expect(result).toEqual({ inserted: 2, deleted: 0 });
+    expect(refRepo.insertMany).toHaveBeenCalledWith(
+      [
+        {
+          referencePageId,
+          containingTransclusionId: null,
+          sourcePageId: 'p1',
+          transclusionId: 'e1',
+        },
+        {
+          referencePageId,
+          containingTransclusionId: null,
+          sourcePageId: 'p2',
+          transclusionId: 'e2',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+    // Loose references never seed cycle detection.
+    expect(refRepo.findCyclicEdgesForSource).not.toHaveBeenCalled();
+  });
+
+  it('records the containing transclusion when references nest in a source', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 's1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 1, deleted: 0 });
+    expect(refRepo.insertMany).toHaveBeenCalledWith(
+      [
+        {
+          referencePageId,
+          containingTransclusionId: 's1',
+          sourcePageId: 'p2',
+          transclusionId: 'e2',
+        },
+      ],
+      undefined,
+    );
+    expect(refRepo.findCyclicEdgesForSource).toHaveBeenCalledWith(
+      'p2',
+      'e2',
+      undefined,
+    );
+  });
+
+  it('deletes edges that close a cycle and excludes them from the inserted count', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    refRepo.findCyclicEdgesForSource.mockResolvedValue([
+      {
+        id: 'closing-edge-id',
+        referencePageId,
+        containingTransclusionId: 's1',
+        sourcePageId: 'p2',
+        transclusionId: 'e2',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusion',
+          attrs: { id: 's1' },
+          content: [
+            {
+              type: 'transclusionReference',
+              attrs: { sourcePageId: 'p2', transclusionId: 'e2' },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.deleteByIds).toHaveBeenCalledWith(
+      ['closing-edge-id'],
+      undefined,
+    );
+  });
+
+  it('deletes references that no longer appear', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([
+      {
+        id: 'r1',
+        referencePageId,
+        containingTransclusionId: null,
+        sourcePageId: 'p1',
+        transclusionId: 'e1',
+        createdAt: new Date(),
+      } as any,
+    ]);
+    const pm = { type: 'doc', content: [{ type: 'paragraph' }] };
+
+    const result = await service.syncPageReferences(referencePageId, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 1 });
+    expect(refRepo.deleteByReferenceAndKeys).toHaveBeenCalledWith(
+      referencePageId,
+      [
+        {
+          containingTransclusionId: null,
+          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,
+        containingTransclusionId: null,
+        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, pm);
+
+    expect(result).toEqual({ inserted: 0, deleted: 0 });
+    expect(refRepo.insertMany).not.toHaveBeenCalled();
+    expect(refRepo.deleteByReferenceAndKeys).not.toHaveBeenCalled();
+  });
+
+  it('passes through trx parameter to repo calls', async () => {
+    refRepo.findByReferencePageId.mockResolvedValue([]);
+    const trx = { mock: 'trx' } as any;
+    const pm = {
+      type: 'doc',
+      content: [
+        {
+          type: 'transclusionReference',
+          attrs: { sourcePageId: 'p1', transclusionId: 'e1' },
+        },
+      ],
+    };
+
+    await service.syncPageReferences(referencePageId, pm, trx);
+
+    expect(refRepo.findByReferencePageId).toHaveBeenCalledWith(
+      referencePageId,
+      trx,
+    );
+    expect(refRepo.insertMany).toHaveBeenCalledWith(expect.anything(), trx);
+  });
+});

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

@@ -0,0 +1,57 @@
+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 ?? null,
+    );
+  }
+
+  @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,
+    });
+  }
+
+  @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.id,
+    );
+  }
+}

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

@@ -0,0 +1,12 @@
+import { Module } from '@nestjs/common';
+import { TransclusionController } from './transclusion.controller';
+import { TransclusionService } from './transclusion.service';
+import { StorageModule } from '../../../integrations/storage/storage.module';
+
+@Module({
+  imports: [StorageModule],
+  controllers: [TransclusionController],
+  providers: [TransclusionService],
+  exports: [TransclusionService],
+})
+export class TransclusionModule {}

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

@@ -0,0 +1,526 @@
+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-transclusion-references/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 } from '@docmost/db/types/entity.types';
+
+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,
+  ) {}
+
+  async syncPageTransclusions(
+    pageId: 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(
+          {
+            pageId,
+            transclusionId: d.transclusionId,
+            name: d.name,
+            content: d.content as any,
+          },
+          trx,
+        );
+        inserted += 1;
+        continue;
+      }
+
+      const nameChanged = prev.name !== d.name;
+      const contentChanged = !isDeepStrictEqual(prev.content, d.content);
+      if (nameChanged || contentChanged) {
+        await this.pageTransclusionsRepo.update(
+          pageId,
+          d.transclusionId,
+          { name: d.name, 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,
+    pmJson: unknown,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number; deleted: number }> {
+    const desired = collectReferencesFromPmJson(pmJson);
+    const keyOf = (s: {
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }) =>
+      `${s.containingTransclusionId ?? ''}::${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) => ({
+        referencePageId,
+        containingTransclusionId: d.containingTransclusionId,
+        sourcePageId: d.sourcePageId,
+        transclusionId: d.transclusionId,
+      }));
+
+    const toDelete = existing
+      .filter((e) => !desiredKeys.has(keyOf(e)))
+      .map((e) => ({
+        containingTransclusionId: e.containingTransclusionId,
+        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,
+      );
+    }
+
+    const removedCount = await this.removeCyclicEdgesIntroducedBy(
+      toInsert,
+      trx,
+    );
+
+    return {
+      inserted: toInsert.length - removedCount,
+      deleted: toDelete.length,
+    };
+  }
+
+  /**
+   * Run cycle detection rooted at each newly-introduced edge's target and
+   * delete any closing edge that belongs to a cycle. Lookups for those rows
+   * then return `not_found`, which the editor renders as the cycle-aware
+   * placeholder. Returns the count of rows removed.
+   */
+  private async removeCyclicEdgesIntroducedBy(
+    candidates: ReadonlyArray<{
+      referencePageId: string;
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }>,
+    trx?: KyselyTransaction,
+  ): Promise<number> {
+    const seedKeys = new Set<string>();
+    const seeds: Array<{ sourcePageId: string; transclusionId: string }> = [];
+    for (const c of candidates) {
+      if (c.containingTransclusionId === null) continue;
+      const key = `${c.sourcePageId}::${c.transclusionId}`;
+      if (seedKeys.has(key)) continue;
+      seedKeys.add(key);
+      seeds.push({
+        sourcePageId: c.sourcePageId,
+        transclusionId: c.transclusionId,
+      });
+    }
+    if (seeds.length === 0) return 0;
+
+    const offendingIds = new Set<string>();
+    for (const seed of seeds) {
+      const cyclicEdges =
+        await this.pageTransclusionReferencesRepo.findCyclicEdgesForSource(
+          seed.sourcePageId,
+          seed.transclusionId,
+          trx,
+        );
+      for (const edge of cyclicEdges) offendingIds.add(edge.id);
+    }
+
+    if (offendingIds.size === 0) return 0;
+
+    await this.pageTransclusionReferencesRepo.deleteByIds(
+      Array.from(offendingIds),
+      trx,
+    );
+    return offendingIds.size;
+  }
+
+  /**
+   * 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; 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({
+          pageId: page.id,
+          transclusionId: s.transclusionId,
+          name: s.name,
+          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 `(containing, source, target)` triple. For brand-new pages
+   * (duplication, import) where there is nothing to diff against.
+   *
+   * Cycle detection runs once per distinct seed source after the bulk insert;
+   * any closing edges are removed so lookups return `not_found` and the
+   * editor renders the cycle-aware placeholder.
+   */
+  async insertReferencesForPages(
+    pages: Array<{ id: string; content: unknown }>,
+    trx?: KyselyTransaction,
+  ): Promise<{ inserted: number }> {
+    const rows: Array<{
+      referencePageId: string;
+      containingTransclusionId: string | null;
+      sourcePageId: string;
+      transclusionId: string;
+    }> = [];
+    for (const page of pages) {
+      const refs = collectReferencesFromPmJson(page.content);
+      for (const r of refs) {
+        rows.push({
+          referencePageId: page.id,
+          containingTransclusionId: r.containingTransclusionId,
+          sourcePageId: r.sourcePageId,
+          transclusionId: r.transclusionId,
+        });
+      }
+    }
+    if (rows.length === 0) return { inserted: 0 };
+    await this.pageTransclusionReferencesRepo.insertMany(rows, trx);
+
+    const removedCount = await this.removeCyclicEdgesIntroducedBy(rows, trx);
+    return { inserted: rows.length - removedCount };
+  }
+
+  async lookup(
+    references: Array<{ sourcePageId: string; transclusionId: string }>,
+    viewerUserId: string | null,
+  ): Promise<{ items: TransclusionLookup[] }> {
+    if (references.length === 0) return { items: [] };
+
+    const items: TransclusionLookup[] = new Array(references.length).fill(null);
+    const pendingIdx = references.map((_, i) => i);
+
+    // 1) permission filter on the candidate pageIds (auth users only;
+    // unauthenticated share viewers get no_access for any private page).
+    const candidatePageIds = Array.from(
+      new Set(pendingIdx.map((i) => references[i].sourcePageId)),
+    );
+    const accessibleSet = viewerUserId
+      ? new Set(
+          await this.pagePermissionRepo.filterAccessiblePageIds({
+            pageIds: candidatePageIds,
+            userId: viewerUserId,
+          }),
+        )
+      : new Set<string>();
+
+    // 2) one DB hit for all (page_id, transclusion_id) keys still pending and accessible
+    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,
+      })),
+    );
+    const rowKey = (r: { pageId: string; transclusionId: string }) =>
+      `${r.pageId}::${r.transclusionId}`;
+    const rowMap = new Map(rows.map((r) => [rowKey(r), r]));
+
+    // 3) pull updatedAt from each accessible page so we can return
+    //    sourceUpdatedAt on each successful result.
+    const accessiblePageIds = Array.from(
+      new Set(accessiblePending.map((i) => references[i].sourcePageId)),
+    );
+    const pageMeta = new Map<string, Date>();
+    for (const pid of accessiblePageIds) {
+      const p = await this.pageRepo.findById(pid);
+      if (p && !p.deletedAt) pageMeta.set(p.id, p.updatedAt);
+    }
+
+    // 4) stitch the results
+    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;
+  }): Promise<{
+    source: ReferencingPageInfo | null;
+    references: ReferencingPageInfo[];
+  }> {
+    const { sourcePageId, transclusionId, viewerUserId } = opts;
+
+    const referencePageIds =
+      await this.pageTransclusionReferencesRepo.findReferencePageIdsByTransclusion(
+        sourcePageId,
+        transclusionId,
+      );
+
+    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) 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,
+    viewerUserId: string,
+  ): 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');
+    }
+
+    const accessible = new Set(
+      await this.pagePermissionRepo.filterAccessiblePageIds({
+        pageIds: [referencePageId, sourcePageId],
+        userId: viewerUserId,
+      }),
+    );
+    if (!accessible.has(referencePageId) || !accessible.has(sourcePageId)) {
+      throw new ForbiddenException();
+    }
+
+    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.findBySpaceId(sourcePage.spaceId);
+      const byOldId = new Map(
+        oldRows
+          .filter(
+            (a) => oldIds.includes(a.id) && 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: viewerUserId,
+          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,15 @@
+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;
+  name: string | null;
+  content: unknown;
+};

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

@@ -0,0 +1,111 @@
+import { TransclusionNodeSnapshot } from '../transclusion.types';
+
+const TRANSCLUSION_TYPE = 'transclusion';
+const REFERENCE_TYPE = 'transclusionReference';
+
+export type TransclusionReferenceSnapshot = {
+  /**
+   * Id of the `transclusion` (source) node whose content holds this reference,
+   * or `null` if the reference is loose on the page (not nested inside a source).
+   * Used by the cycle-detection CTE to walk source-to-source edges.
+   */
+  containingTransclusionId: string | null;
+  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) {
+        const name =
+          typeof node.attrs?.name === 'string' && node.attrs.name.length > 0
+            ? node.attrs.name
+            : null;
+        byId.set(id, {
+          transclusionId: id,
+          name,
+          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
+ * `(containingTransclusionId, sourcePageId, transclusionId)` triple found on
+ * `transclusionReference` nodes. Recurses into every container, including
+ * `transclusion` (a source node may contain a reference to another source).
+ * 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, containingTransclusionId: string | null): 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 = `${containingTransclusionId ?? ''}::${sourcePageId}::${transclusionId}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push({
+            containingTransclusionId,
+            sourcePageId,
+            transclusionId,
+          });
+        }
+      }
+      return; // atom node - no children
+    }
+
+    const nextContainer =
+      node.type === TRANSCLUSION_TYPE && typeof node.attrs?.id === 'string'
+        ? node.attrs.id
+        : containingTransclusionId;
+
+    if (Array.isArray(node.content)) {
+      for (const child of node.content) visit(child, nextContainer);
+    }
+  };
+
+  visit(doc, null);
+  return out;
+}

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

@@ -0,0 +1,65 @@
+import { isAttachmentNode } from '../../../../common/helpers/prosemirror/utils';
+
+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/workspace/dto/update-workspace.dto.ts

@@ -41,6 +41,10 @@ export class UpdateWorkspaceDto extends PartialType(CreateWorkspaceDto) {
   @IsBoolean()
   mcpEnabled: boolean;
 
+  @IsOptional()
+  @IsBoolean()
+  isScimEnabled: boolean;
+
   @IsOptional()
   @IsBoolean()
   aiChat: boolean;

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

@@ -331,7 +331,8 @@ export class WorkspaceService {
       typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
       typeof updateWorkspaceDto.mcpEnabled !== 'undefined' ||
       typeof updateWorkspaceDto.restrictApiToAdmins !== 'undefined' ||
-      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined'
+      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined' ||
+      typeof updateWorkspaceDto.isScimEnabled !== 'undefined'
     ) {
       const ws = await this.db
         .selectFrom('workspaces')
@@ -351,6 +352,14 @@ export class WorkspaceService {
         }
       }
 
+      if (typeof updateWorkspaceDto.isScimEnabled !== 'undefined') {
+        if (!this.licenseCheckService.hasFeature(ws.licenseKey, Feature.SCIM, ws.plan)) {
+          throw new ForbiddenException(
+            'This feature requires a valid license',
+          );
+        }
+      }
+
       if (
         typeof updateWorkspaceDto.disablePublicSharing !== 'undefined' ||
         typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
@@ -535,6 +544,7 @@ export class WorkspaceService {
         'enforceSso',
         'enforceMfa',
         'emailDomains',
+        'isScimEnabled',
       ],
       updateWorkspaceDto,
       workspaceBefore,

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-transclusion-references/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/20260501T092214-scim.ts

@@ -0,0 +1,110 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('scim_tokens')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('token_hash', 'varchar', (col) => col.notNull())
+    .addColumn('token_last_four', 'varchar(4)', (col) => col.notNull())
+    .addColumn('last_used_at', 'timestamptz')
+    .addColumn('is_enabled', 'boolean', (col) => col.notNull().defaultTo(true))
+    .addColumn('creator_id', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('deleted_at', 'timestamptz')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_token_hash')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('token_hash')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_workspace_id')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('workspace_id')
+    .execute();
+
+  await db.schema
+    .alterTable('users')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_users_workspace_scim_external_id')
+    .ifNotExists()
+    .on('users')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_groups_workspace_scim_external_id')
+    .ifNotExists()
+    .on('groups')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('is_external', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+
+  // Backfill: mark all non-default groups as external in workspaces with SSO group sync enabled
+  await sql`
+    UPDATE groups SET is_external = true
+    WHERE is_default = false
+    AND workspace_id IN (
+      SELECT workspace_id FROM auth_providers WHERE group_sync = true
+    )
+  `.execute(db);
+
+  await db.schema
+    .alterTable('workspaces')
+    .addColumn('is_scim_enabled', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('scim_tokens').execute();
+
+  await db.schema.dropIndex('idx_users_workspace_scim_external_id').execute();
+  await db.schema.alterTable('users').dropColumn('scim_external_id').execute();
+
+  await db.schema.dropIndex('idx_groups_workspace_scim_external_id').execute();
+  await db.schema.alterTable('groups').dropColumn('scim_external_id').execute();
+
+  await db.schema.alterTable('groups').dropColumn('is_external').execute();
+
+  await db.schema
+    .alterTable('workspaces')
+    .dropColumn('is_scim_enabled')
+    .execute();
+}

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

@@ -0,0 +1,79 @@
+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('page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('transclusion_id', 'varchar', (col) => col.notNull())
+    .addColumn('name', 'text')
+    .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_page_id')
+    .on('page_transclusions')
+    .column('page_id')
+    .execute();
+
+  await db.schema
+    .createTable('page_transclusion_references')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('reference_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('containing_transclusion_id', 'varchar')
+    .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',
+      'containing_transclusion_id',
+      'source_page_id',
+      'transclusion_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('idx_page_transclusion_references_reference_page_id')
+    .on('page_transclusion_references')
+    .column('reference_page_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_container')
+    .on('page_transclusion_references')
+    .columns(['reference_page_id', 'containing_transclusion_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/group/group.repo.ts

@@ -9,7 +9,7 @@ import {
 } from '@docmost/db/types/entity.types';
 import { ExpressionBuilder, sql } from 'kysely';
 import { PaginationOptions } from '../../pagination/pagination-options';
-import { DB } from '@docmost/db/types/db';
+import { DB, Groups } from '@docmost/db/types/db';
 import { DefaultGroup } from '../../../core/group/dto/create-group.dto';
 import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagination';
 
@@ -17,16 +17,34 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 export class GroupRepo {
   constructor(@InjectKysely() private readonly db: KyselyDB) {}
 
+  private baseFields: Array<keyof Groups> = [
+    'id',
+    'name',
+    'description',
+    'isDefault',
+    'isExternal',
+    'creatorId',
+    'workspaceId',
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+  ];
+
   async findById(
     groupId: string,
     workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
   ): Promise<Group> {
     const db = dbOrTx(this.db, opts?.trx);
     return db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where('id', '=', groupId)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -35,13 +53,18 @@ export class GroupRepo {
   async findByName(
     groupName: string,
     workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
   ): Promise<Group> {
     const db = dbOrTx(this.db, opts?.trx);
     return db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where(sql`LOWER(name)`, '=', sql`LOWER(${groupName})`)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -51,8 +74,11 @@ export class GroupRepo {
     updatableGroup: UpdatableGroup,
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<void> {
-    await this.db
+    const db = dbOrTx(this.db, trx);
+
+    await db
       .updateTable('groups')
       .set({ ...updatableGroup, updatedAt: new Date() })
       .where('id', '=', groupId)
@@ -68,7 +94,7 @@ export class GroupRepo {
     return db
       .insertInto('groups')
       .values(insertableGroup)
-      .returningAll()
+      .returning(this.baseFields)
       .executeTakeFirst();
   }
 
@@ -80,7 +106,7 @@ export class GroupRepo {
     return (
       db
         .selectFrom('groups')
-        .selectAll()
+        .select(this.baseFields)
         // .select((eb) => this.withMemberCount(eb))
         .where('isDefault', '=', true)
         .where('workspaceId', '=', workspaceId)
@@ -106,7 +132,7 @@ export class GroupRepo {
   async getGroupsPaginated(workspaceId: string, pagination: PaginationOptions) {
     let baseQuery = this.db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .select((eb) => this.withMemberCount(eb))
       .where('workspaceId', '=', workspaceId);
 

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

@@ -0,0 +1,181 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { sql } from '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 = {
+  containingTransclusionId: string | null;
+  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,
+    trx?: KyselyTransaction,
+  ): Promise<string[]> {
+    const rows = await dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusionReferences')
+      .select('referencePageId')
+      .distinct()
+      .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',
+            'containingTransclusionId',
+            '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([
+              k.containingTransclusionId === null
+                ? eb('containingTransclusionId', 'is', null)
+                : eb(
+                    'containingTransclusionId',
+                    '=',
+                    k.containingTransclusionId,
+                  ),
+              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();
+  }
+
+  async deleteByIds(ids: string[], trx?: KyselyTransaction): Promise<void> {
+    if (ids.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .deleteFrom('pageTransclusionReferences')
+      .where('id', 'in', ids)
+      .execute();
+  }
+
+  /**
+   * Finds reference rows that participate in a cycle reachable from a given
+   * source `(pageId, transclusionId)`. The walk follows source-to-source edges
+   * (rows where `containing_transclusion_id IS NOT NULL`); loose page-level
+   * references are not graph edges and are ignored.
+   *
+   * Returned rows are the *closing edges* — those whose insertion completed a
+   * cycle. They are the safe set to remove to break the cycle while preserving
+   * unrelated structure.
+   */
+  async findCyclicEdgesForSource(
+    sourcePageId: string,
+    transclusionId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusionReference[]> {
+    const rows = await sql<PageTransclusionReference>`
+      WITH RECURSIVE walk(
+        start_page,
+        start_id,
+        page_id,
+        transclusion_id,
+        edge_id,
+        is_cycle,
+        path
+      ) AS (
+        SELECT
+          ${sourcePageId}::uuid,
+          ${transclusionId}::varchar,
+          ${sourcePageId}::uuid,
+          ${transclusionId}::varchar,
+          NULL::uuid,
+          false,
+          ARRAY[(${sourcePageId}::uuid, ${transclusionId}::varchar)]
+        UNION ALL
+        SELECT
+          w.start_page,
+          w.start_id,
+          r.source_page_id,
+          r.transclusion_id,
+          r.id,
+          (r.source_page_id, r.transclusion_id) = ANY(w.path),
+          w.path || ARRAY[(r.source_page_id, r.transclusion_id)]
+        FROM page_transclusion_references r
+        JOIN walk w
+          ON r.reference_page_id = w.page_id
+         AND r.containing_transclusion_id = w.transclusion_id
+        WHERE r.containing_transclusion_id IS NOT NULL
+          AND NOT w.is_cycle
+      )
+      SELECT
+        r.id,
+        r.created_at        AS "createdAt",
+        r.reference_page_id  AS "referencePageId",
+        r.containing_transclusion_id AS "containingTransclusionId",
+        r.source_page_id     AS "sourcePageId",
+        r.transclusion_id    AS "transclusionId"
+      FROM walk w
+      JOIN page_transclusion_references r ON r.id = w.edge_id
+      WHERE w.is_cycle
+    `.execute(dbOrTx(this.db, trx));
+    return rows.rows;
+  }
+}

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';
+import { sql } from 'kysely';
+
+@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(sql`name asc nulls last`)
+      .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 }>,
+    trx?: KyselyTransaction,
+  ): Promise<PageTransclusion[]> {
+    if (keys.length === 0) return [];
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTransclusions')
+      .selectAll()
+      .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/user/user.repo.ts

@@ -44,6 +44,7 @@ export class UserRepo {
     opts?: {
       includePassword?: boolean;
       includeUserMfa?: boolean;
+      includeScimExternalId?: boolean;
       trx?: KyselyTransaction;
     },
   ): Promise<User> {
@@ -53,6 +54,7 @@ export class UserRepo {
       .select(this.baseFields)
       .$if(opts?.includePassword, (qb) => qb.select('password'))
       .$if(opts?.includeUserMfa, (qb) => qb.select(this.withUserMfa))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where('id', '=', userId)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -64,6 +66,7 @@ export class UserRepo {
     opts?: {
       includePassword?: boolean;
       includeUserMfa?: boolean;
+      includeScimExternalId?: boolean;
       trx?: KyselyTransaction;
     },
   ): Promise<User> {
@@ -73,6 +76,7 @@ export class UserRepo {
       .select(this.baseFields)
       .$if(opts?.includePassword, (qb) => qb.select('password'))
       .$if(opts?.includeUserMfa, (qb) => qb.select(this.withUserMfa))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where(sql`LOWER(email)`, '=', sql`LOWER(${email})`)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();

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

@@ -34,6 +34,7 @@ export class WorkspaceRepo {
     'plan',
     'enforceMfa',
     'trashRetentionDays',
+    'isScimEnabled',
   ];
   constructor(@InjectKysely() private readonly db: KyselyDB) {}
 

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

@@ -213,7 +213,9 @@ export interface Groups {
   description: string | null;
   id: Generated<string>;
   isDefault: boolean;
+  isExternal: Generated<boolean>;
   name: string;
+  scimExternalId: string | null;
   updatedAt: Generated<Timestamp>;
   workspaceId: string;
 }
@@ -226,6 +228,25 @@ export interface GroupUsers {
   userId: string;
 }
 
+export interface PageTransclusionReferences {
+  createdAt: Generated<Timestamp>;
+  transclusionId: string;
+  referencePageId: string;
+  containingTransclusionId: string | null;
+  id: Generated<string>;
+  sourcePageId: string;
+}
+
+export interface PageTransclusions {
+  content: Json;
+  createdAt: Generated<Timestamp>;
+  transclusionId: string;
+  id: Generated<string>;
+  name: string | null;
+  pageId: string;
+  updatedAt: Generated<Timestamp>;
+}
+
 export interface PageHistory {
   content: Json | null;
   contributorIds: Generated<string[] | null>;
@@ -338,6 +359,7 @@ export interface Users {
   name: string | null;
   password: string | null;
   role: string | null;
+  scimExternalId: string | null;
   settings: Json | null;
   timezone: string | null;
   updatedAt: Generated<Timestamp>;
@@ -381,6 +403,7 @@ export interface Workspaces {
   enforceMfa: Generated<boolean | null>;
   enforceSso: Generated<boolean>;
   hostname: string | null;
+  isScimEnabled: Generated<boolean>;
   id: Generated<string>;
   licenseKey: string | null;
   logo: string | null;
@@ -410,6 +433,20 @@ export interface Notifications {
   createdAt: Generated<Timestamp>;
 }
 
+export interface ScimTokens {
+  createdAt: Generated<Timestamp>;
+  deletedAt: Timestamp | null;
+  id: Generated<string>;
+  isEnabled: Generated<boolean>;
+  lastUsedAt: Timestamp | null;
+  name: string;
+  tokenHash: string;
+  tokenLastFour: string;
+  creatorId: string | null;
+  updatedAt: Generated<Timestamp>;
+  workspaceId: string;
+}
+
 export interface Watchers {
   id: Generated<string>;
   userId: string;
@@ -553,11 +590,14 @@ export interface DB {
   groupUsers: GroupUsers;
   notifications: Notifications;
   pageAccess: PageAccess;
+  pageTransclusionReferences: PageTransclusionReferences;
+  pageTransclusions: PageTransclusions;
   pagePermissions: PagePermissions;
   pageHistory: PageHistory;
   pageVerifications: PageVerifications;
   pageVerifiers: PageVerifiers;
   pages: Pages;
+  scimTokens: ScimTokens;
   shares: Shares;
   spaceMembers: SpaceMembers;
   spaces: Spaces;

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,
@@ -29,6 +31,7 @@ import {
   UserMfa as _UserMFA,
   UserSessions,
   ApiKeys,
+  ScimTokens,
   Watchers,
   Audit as _Audit,
   Templates,
@@ -144,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>;
@@ -159,6 +174,11 @@ export type ApiKey = Selectable<ApiKeys>;
 export type InsertableApiKey = Insertable<ApiKeys>;
 export type UpdatableApiKey = Updateable<Omit<ApiKeys, 'id'>>;
 
+// Scim Tokens
+export type ScimToken = Selectable<ScimTokens>;
+export type InsertableScimToken = Insertable<ScimTokens>;
+export type UpdatableScimToken = Updateable<Omit<ScimTokens, 'id'>>;
+
 // Page Embedding
 export type PageEmbedding = Selectable<PageEmbeddings>;
 export type InsertablePageEmbedding = Insertable<PageEmbeddings>;

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

@@ -304,4 +304,11 @@ export class EnvironmentService {
   getClickHouseUrl(): string {
     return this.configService.get<string>('CLICKHOUSE_URL');
   }
+
+  getSamlDisableRequestedAuthnContext(): boolean {
+    const disabled = this.configService
+      .get<string>('SAML_DISABLE_REQUESTED_AUTHN_CONTEXT', 'false')
+      .toLowerCase();
+    return disabled === 'true';
+  }
 }

apps/server/src/integrations/import/import.controller.ts

@@ -51,9 +51,9 @@ export class ImportController {
     @AuthUser() user: User,
     @AuthWorkspace() workspace: Workspace,
   ) {
-    const validFileExtensions = ['.md', '.html', '.docx'];
+    const validFileExtensions = ['.md', '.html', '.docx', '.pdf'];
 
-    const maxFileSize = bytes('20mb');
+    const maxFileSize = bytes('30mb');
 
     let file = null;
     try {
@@ -102,6 +102,7 @@ export class ImportController {
       '.md': 'markdown',
       '.html': 'html',
       '.docx': 'docx',
+      '.pdf': 'pdf',
     };
 
     if (createdPage) {

apps/server/src/integrations/import/services/import.service.ts

@@ -29,6 +29,8 @@ import { InjectQueue } from '@nestjs/bullmq';
 import { Queue } from 'bullmq';
 import { QueueJob, QueueName } from '../../queue/constants';
 import { ModuleRef } from '@nestjs/core';
+import { load } from 'cheerio';
+import { normalizeImportHtml } from '../utils/import-formatter';
 
 @Injectable()
 export class ImportService {
@@ -61,7 +63,10 @@ export class ImportService {
     let createdPage = null;
 
     // For DOCX, we need the page ID upfront so images can reference it
-    const pageId = fileExtension === '.docx' ? uuid7() : undefined;
+    const pageId =
+      fileExtension === '.docx' || fileExtension === '.pdf'
+        ? uuid7()
+        : undefined;
 
     try {
       if (fileExtension.endsWith('.md')) {
@@ -76,6 +81,14 @@ export class ImportService {
           pageId,
           userId,
         );
+      } else if (fileExtension.endsWith('.pdf')) {
+        prosemirrorState = await this.processPdf(
+          fileBuffer,
+          workspaceId,
+          spaceId,
+          pageId,
+          userId,
+        );
       }
     } catch (err) {
       const message = 'Error processing file content';
@@ -136,7 +149,9 @@ export class ImportService {
 
   async processHTML(htmlInput: string): Promise<any> {
     try {
-      return htmlToJson(htmlInput);
+      const $ = load(htmlInput);
+      normalizeImportHtml($, $.root());
+      return htmlToJson($.html() || '');
     } catch (err) {
       throw err;
     }
@@ -152,7 +167,7 @@ export class ImportService {
     let DocxImportModule: any;
     try {
       // eslint-disable-next-line @typescript-eslint/no-require-imports
-      DocxImportModule = require('./../../../ee/docx-import/docx-import.service');
+      DocxImportModule = require('./../../../ee/document-import/docx-import.service');
     } catch (err) {
       this.logger.error(
         'DOCX import requested but EE module not bundled in this build',
@@ -178,6 +193,42 @@ export class ImportService {
     return this.processHTML(html);
   }
 
+  async processPdf(
+    fileBuffer: Buffer,
+    workspaceId: string,
+    spaceId: string,
+    pageId: string,
+    userId: string,
+  ): Promise<any> {
+    let PdfImportModule: any;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      PdfImportModule = require('./../../../ee/document-import/pdf-import.service');
+    } catch (err) {
+      this.logger.error(
+        'PDF import requested but EE module not bundled in this build',
+      );
+      throw new BadRequestException(
+        'This feature requires a valid enterprise license.',
+      );
+    }
+
+    const pdfImportService = this.moduleRef.get(
+      PdfImportModule.PdfImportService,
+      { strict: false },
+    );
+
+    const html = await pdfImportService.convertPdfToHtml(
+      fileBuffer,
+      workspaceId,
+      spaceId,
+      pageId,
+      userId,
+    );
+
+    return this.processHTML(html);
+  }
+
   async createYdoc(prosemirrorJson: any): Promise<Buffer | null> {
     if (prosemirrorJson) {
       // this.logger.debug(`Converting prosemirror json state to ydoc`);

apps/server/src/integrations/import/utils/import-formatter.ts

@@ -5,6 +5,7 @@ import { v7 } from 'uuid';
 import { InsertableBacklink } from '@docmost/db/types/entity.types';
 import { Cheerio, CheerioAPI, load } from 'cheerio';
 import slugify from '@sindresorhus/slugify';
+import { normalizeTableColumnWidths } from './table-utils';
 
 // Check if text contains Unicode characters (for emojis/icons)
 function isUnicodeCharacter(text: string): boolean {
@@ -51,9 +52,7 @@ export async function formatImportHtml(opts: {
     }
   }
 
-  notionFormatter($, $root);
-  xwikiFormatter($, $root);
-  defaultHtmlFormatter($, $root);
+  normalizeImportHtml($, $root);
 
   const backlinks = await rewriteInternalLinksToMentionHtml(
     $,
@@ -73,6 +72,23 @@ export async function formatImportHtml(opts: {
   };
 }
 
+/**
+ * Contextless HTML cleanup shared by every import path.
+ * - notionFormatter: no-op on non-Notion HTML (class-selector-based).
+ * - xwikiFormatter: no-op on non-XWiki HTML (looks for #xwikicontent).
+ * - defaultHtmlFormatter: table column widths + provider auto-embeds.
+ *
+ * Does NOT run rewriteInternalLinksToMentionHtml — that requires zip context.
+ */
+export function normalizeImportHtml(
+  $: CheerioAPI,
+  $root: Cheerio<any>,
+): void {
+  notionFormatter($, $root);
+  xwikiFormatter($, $root);
+  defaultHtmlFormatter($, $root);
+}
+
 export function xwikiFormatter($: CheerioAPI, $root: Cheerio<any>) {
   const $content = $root.find('#xwikicontent');
   if ($content.length) {
@@ -82,6 +98,8 @@ export function xwikiFormatter($: CheerioAPI, $root: Cheerio<any>) {
 }
 
 export function defaultHtmlFormatter($: CheerioAPI, $root: Cheerio<any>) {
+  normalizeTableColumnWidths($, $root);
+
   $root.find('a[href]').each((_, el) => {
     const $el = $(el);
     const url = $el.attr('href')!;

apps/server/src/integrations/import/utils/table-utils.ts

@@ -0,0 +1,107 @@
+import { CheerioAPI, Cheerio } from 'cheerio';
+
+const DEFAULT_IMPORT_COL_WIDTH_PX = 150;
+
+/**
+ * Extracts a pixel-integer width from either the `width` attribute or
+ * `style="width: Npx"` on a <col>/<td>/<th>. Returns null when absent,
+ * non-numeric, or a non-px unit (em, %).
+ */
+function parsePixelWidth(el: Cheerio<any>): number | null {
+  const attr = el.attr('width');
+  if (attr) {
+    const n = parseInt(attr, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  const style = el.attr('style') || '';
+  const m = style.match(/(?:^|;)\s*width\s*:\s*([\d.]+)\s*px/i);
+  if (m) {
+    const n = parseInt(m[1], 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+/**
+ * Derives per-column widths for a table, in visual column order.
+ * Priority: <colgroup><col> → first-row cells' own width style.
+ * Returns an array of length = number of columns, with null entries
+ * for columns whose width couldn't be determined.
+ */
+function deriveColumnWidths(
+  $: CheerioAPI,
+  table: Cheerio<any>,
+): (number | null)[] | null {
+  const cols = table.find('> colgroup > col');
+  if (cols.length > 0) {
+    const widths: (number | null)[] = [];
+    cols.each(function () {
+      widths.push(parsePixelWidth($(this)));
+    });
+    if (widths.some((w) => w !== null)) return widths;
+  }
+
+  // Fallback: first row's cells.
+  const firstRow = table.find('> tbody > tr, > thead > tr, > tr').first();
+  if (!firstRow.length) return null;
+
+  const widths: (number | null)[] = [];
+  firstRow.children('td, th').each(function () {
+    const cell = $(this);
+    const colspan = parseInt(cell.attr('colspan') || '1', 10) || 1;
+    const w = parsePixelWidth(cell);
+    for (let i = 0; i < colspan; i++) {
+      widths.push(w !== null ? Math.round(w / colspan) : null);
+    }
+  });
+  if (widths.every((w) => w === null)) return null;
+  return widths;
+}
+
+/**
+ * Apply colwidth attributes to the first row of each table based on
+ * derived column widths. Accounts for colspan. Idempotent — re-running
+ * on already-normalized markup is a no-op.
+ *
+ * This lives upstream of tiptap's generateJSON: tiptap reads
+ * `colwidth="N[,N...]"` on <td>/<th> to build the runtime <colgroup>.
+ */
+export function normalizeTableColumnWidths(
+  $: CheerioAPI,
+  $root: Cheerio<any>,
+): void {
+  $root.find('table').each(function () {
+    const table = $(this);
+    const firstRow = table.find('> tbody > tr, > thead > tr, > tr').first();
+    if (!firstRow.length) return;
+
+    let colWidths = deriveColumnWidths($, table);
+    if (!colWidths) {
+      // No widths anywhere (e.g. markdown-sourced tables). Apply a default
+      // per-column width so the table's intrinsic width can exceed the
+      // editor container, letting .tableWrapper's overflow-x: auto scroll
+      // instead of cramming columns into the available width.
+      let count = 0;
+      firstRow.children('td, th').each(function () {
+        count += parseInt($(this).attr('colspan') || '1', 10) || 1;
+      });
+      if (count === 0) return;
+      colWidths = new Array(count).fill(DEFAULT_IMPORT_COL_WIDTH_PX);
+    }
+
+    let col = 0;
+    firstRow.children('td, th').each(function () {
+      const cell = $(this);
+      if (cell.attr('colwidth')) {
+        col += parseInt(cell.attr('colspan') || '1', 10) || 1;
+        return;
+      }
+      const colspan = parseInt(cell.attr('colspan') || '1', 10) || 1;
+      const slice = colWidths.slice(col, col + colspan);
+      col += colspan;
+      if (slice.length === 0 || slice.every((w) => w === null)) return;
+      const values = slice.map((w) => (w == null ? 100 : w));
+      cell.attr('colwidth', values.join(','));
+    });
+  });
+}

apps/server/src/main.ts

@@ -50,6 +50,22 @@ async function bootstrap() {
   await app.register(fastifyMultipart);
   await app.register(fastifyCookie);
 
+  app
+    .getHttpAdapter()
+    .getInstance()
+    .addContentTypeParser(
+      'application/scim+json',
+      { parseAs: 'string' },
+      (_, body, done) => {
+        try {
+          const json = JSON.parse(body.toString());
+          done(null, json);
+        } catch (err: any) {
+          done(err);
+        }
+      },
+    );
+
   app
     .getHttpAdapter()
     .getInstance()

package.json

@@ -95,7 +95,8 @@
   "packageManager": "pnpm@10.4.0",
   "pnpm": {
     "patchedDependencies": {
-      "react-arborist@3.4.0": "patches/react-arborist@3.4.0.patch"
+      "react-arborist@3.4.0": "patches/react-arborist@3.4.0.patch",
+      "scimmy@1.3.5": "patches/scimmy@1.3.5.patch"
     },
     "overrides": {
       "prosemirror-changeset": "2.4.0",

packages/editor-ext/src/index.ts

@@ -21,6 +21,7 @@ export * from "./lib/markdown";
 export * from "./lib/search-and-replace";
 export * from "./lib/embed-provider";
 export * from "./lib/subpages";
+export * from "./lib/transclusion";
 export * from "./lib/highlight";
 export * from "./lib/heading/heading";
 export * from "./lib/unique-id";

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

@@ -0,0 +1,2 @@
+export * from "./transclusion";
+export * from "./transclusion-reference";