feat: synced blocks (transclusion) (#2163)

* feat: synced blocks (transclusion) * fix:remove name * make placeholders smaller * feat: enforce strict transclusion schema * fix: scope synced blocks to workspace, gate unsync on edit permission * fix collab module error
2026-05-20 00:14:10 +08:00 · 2026-05-08 13:23:16 +01:00
parent c9fa6e20b3
commit de60aa7e61
64 changed files with 4388 additions and 105 deletions
@@ -0,0 +1,17 @@
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function ErrorPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconAlertTriangle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("Failed to load this synced block")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,13 @@
+import { IconEyeOff } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NoAccessPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconEyeOff size={18} stroke={1.6} className={classes.placeholderIcon} />
+      <span>{t("You don't have access to this synced block")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,17 @@
+import { IconInfoCircle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NotFoundPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconInfoCircle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("The original synced block no longer exists")}</span>
+    </div>
+  );
+}
@@ -0,0 +1,48 @@
+import { EditorProvider } from "@tiptap/react";
+import { useMemo } from "react";
+import { mainExtensions } from "@/features/editor/extensions/extensions";
+import { UniqueID } from "@docmost/editor-ext";
+
+type Props = {
+  content: unknown;
+};
+
+export default function TransclusionContent({ content }: Props) {
+  const extensions = useMemo(() => {
+    const filtered = mainExtensions.filter(
+      (e: any) => e.name !== "uniqueID" && e.name !== "globalDragHandle",
+    );
+    return [
+      ...filtered,
+      UniqueID.configure({
+        types: ["heading", "paragraph", "transclusionSource"],
+        updateDocument: false,
+      }),
+    ];
+  }, []);
+
+  // Isolate the nested read-only editor's events from the host editor:
+  // - mousedown/click would otherwise make the host node-select the atom
+  //   wrapper, blocking native text selection inside.
+  // - dragstart/dragover/drop would otherwise let the host treat events
+  //   inside the nested view as drops on the host, duplicating dropped
+  //   files at the transclusion's position.
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation();
+
+  return (
+    <div
+      onMouseDown={stop}
+      onClick={stop}
+      onDragStart={stop}
+      onDragOver={stop}
+      onDrop={stop}
+    >
+      <EditorProvider
+        editable={false}
+        immediatelyRender={true}
+        extensions={extensions}
+        content={content as any}
+      />
+    </div>
+  );
+}
@@ -0,0 +1,213 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  lookupTransclusion,
+  lookupTransclusionForShare,
+} from "@/features/transclusion/services/transclusion-api";
+import type { TransclusionLookup } from "@/features/transclusion/types/transclusion.types";
+
+type LookupKey = string; // `${sourcePageId}::${transclusionId}`
+
+type Subscriber = {
+  key: LookupKey;
+  sourcePageId: string;
+  transclusionId: string;
+  setResult: (r: TransclusionLookup) => void;
+};
+
+type ContextValue = {
+  /** Register a subscriber. Returns an unsubscribe function. */
+  subscribe: (s: Subscriber) => () => void;
+  /**
+   * Force a re-fetch of `key` and resolve when the response arrives (or the
+   * request fails). Bypasses the cache and any in-flight de-dup so the user
+   * always sees a fresh server read.
+   */
+  refresh: (key: LookupKey) => Promise<void>;
+};
+
+const TransclusionLookupContext = createContext<ContextValue | null>(null);
+
+export function TransclusionLookupProvider({
+  children,
+  shareId,
+}: {
+  children: React.ReactNode;
+  /**
+   * When set, lookups go through the share-scoped public endpoint and are
+   * gated by the share graph (source page must have its own share or inherit
+   * one). Used by the public share viewer; left undefined in the authenticated
+   * app, where personal permissions gate access.
+   */
+  shareId?: string;
+}) {
+  const subscribersRef = useRef(new Map<LookupKey, Subscriber[]>());
+  const queueRef = useRef(new Set<LookupKey>());
+  const tickRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Read inside flush() via ref so changing share context doesn't churn the
+  // memoized callbacks (and thus doesn't re-render every consumer).
+  const shareIdRef = useRef<string | undefined>(shareId);
+  shareIdRef.current = shareId;
+  // Last looked-up value for each key. Re-subscribers (e.g. when the editor
+  // remounts after switching from static to live) get this immediately
+  // instead of triggering a duplicate fetch.
+  const resultCacheRef = useRef(new Map<LookupKey, TransclusionLookup>());
+  // Keys that are currently in flight in a batch request. A second subscribe
+  // for the same key while the first request is pending is a no-op; the
+  // subscriber is added to subscribersRef and will be notified when the
+  // pending request completes.
+  const inFlightRef = useRef(new Set<LookupKey>());
+  // Resolvers waiting on the next response for a key. Populated by refresh()
+  // so callers can await the fetch round-trip; resolved on success and on
+  // network error so the UI never hangs in a loading state.
+  const pendingRef = useRef(new Map<LookupKey, Array<() => void>>());
+
+  const flush = useCallback(async () => {
+    tickRef.current = null;
+    const keys = Array.from(queueRef.current);
+    queueRef.current.clear();
+    if (keys.length === 0) return;
+
+    for (const k of keys) inFlightRef.current.add(k);
+
+    const references = keys.map((k) => {
+      const [sourcePageId, transclusionId] = k.split("::");
+      return { sourcePageId, transclusionId };
+    });
+
+    const resolveWaiters = (key: LookupKey) => {
+      const waiters = pendingRef.current.get(key);
+      if (!waiters) return;
+      pendingRef.current.delete(key);
+      for (const w of waiters) w();
+    };
+
+    try {
+      const activeShareId = shareIdRef.current;
+      const { items } = activeShareId
+        ? await lookupTransclusionForShare({
+            shareId: activeShareId,
+            references,
+          })
+        : await lookupTransclusion({ references });
+      for (const r of items) {
+        const key = `${r.sourcePageId}::${r.transclusionId}`;
+        resultCacheRef.current.set(key, r);
+        inFlightRef.current.delete(key);
+        const subs = subscribersRef.current.get(key);
+        if (subs) {
+          for (const s of subs) s.setResult(r);
+        }
+        resolveWaiters(key);
+      }
+    } catch {
+      // Network error — leave subscribers in pending state and clear the
+      // in-flight flag so a future subscribe can retry.
+      for (const k of keys) {
+        inFlightRef.current.delete(k);
+        resolveWaiters(k);
+      }
+    }
+  }, []);
+
+  const enqueue = useCallback(
+    (key: LookupKey) => {
+      queueRef.current.add(key);
+      if (tickRef.current === null) {
+        tickRef.current = setTimeout(flush, 10);
+      }
+    },
+    [flush],
+  );
+
+  const subscribe = useCallback<ContextValue["subscribe"]>(
+    (s) => {
+      const list = subscribersRef.current.get(s.key) ?? [];
+      list.push(s);
+      subscribersRef.current.set(s.key, list);
+
+      const cached = resultCacheRef.current.get(s.key);
+      if (cached) {
+        s.setResult(cached);
+      } else if (!inFlightRef.current.has(s.key)) {
+        enqueue(s.key);
+      }
+
+      return () => {
+        const cur = subscribersRef.current.get(s.key) ?? [];
+        const next = cur.filter((x) => x !== s);
+        if (next.length === 0) subscribersRef.current.delete(s.key);
+        else subscribersRef.current.set(s.key, next);
+      };
+    },
+    [enqueue],
+  );
+
+  const refresh = useCallback<ContextValue["refresh"]>(
+    (key) =>
+      new Promise<void>((resolve) => {
+        resultCacheRef.current.delete(key);
+        inFlightRef.current.delete(key);
+        const waiters = pendingRef.current.get(key) ?? [];
+        waiters.push(resolve);
+        pendingRef.current.set(key, waiters);
+        enqueue(key);
+      }),
+    [enqueue],
+  );
+
+  useEffect(
+    () => () => {
+      if (tickRef.current) clearTimeout(tickRef.current);
+    },
+    [],
+  );
+
+  const value = useMemo<ContextValue>(
+    () => ({ subscribe, refresh }),
+    [subscribe, refresh],
+  );
+
+  return (
+    <TransclusionLookupContext.Provider value={value}>
+      {children}
+    </TransclusionLookupContext.Provider>
+  );
+}
+
+export function useTransclusionLookup(
+  sourcePageId: string | null | undefined,
+  transclusionId: string | null | undefined,
+): {
+  result: TransclusionLookup | null;
+  refresh: () => Promise<void>;
+} {
+  const ctx = useContext(TransclusionLookupContext);
+  const [result, setResult] = useState<TransclusionLookup | null>(null);
+
+  useEffect(() => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    const key = `${sourcePageId}::${transclusionId}`;
+    const unsubscribe = ctx.subscribe({
+      key,
+      sourcePageId,
+      transclusionId,
+      setResult,
+    });
+    return unsubscribe;
+  }, [ctx, sourcePageId, transclusionId]);
+
+  const refresh = useCallback(async () => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    await ctx.refresh(`${sourcePageId}::${transclusionId}`);
+  }, [ctx, sourcePageId, transclusionId]);
+
+  return { result, refresh };
+}
@@ -0,0 +1,212 @@
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconDots,
+  IconLinkOff,
+  IconPencil,
+  IconRefresh,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { ErrorBoundary } from "react-error-boundary";
+import { useTransclusionLookup } from "./transclusion-lookup-context";
+import TransclusionContent from "./transclusion-content";
+import NoAccessPlaceholder from "./no-access-placeholder";
+import NotFoundPlaceholder from "./not-found-placeholder";
+import ErrorPlaceholder from "./error-placeholder";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+import {
+  useReferencesQuery,
+  useUnsyncReferenceMutation,
+} from "@/features/transclusion/queries/transclusion-query";
+import { buildPageUrl } from "@/features/page/page.utils";
+
+export default function TransclusionReferenceView(props: NodeViewProps) {
+  const isEditable = props.editor.isEditable;
+  const sourcePageId: string | null = props.node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = props.node.attrs.transclusionId ?? null;
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  return (
+    <NodeViewWrapper
+      className={classes.includeWrap}
+      data-focused={isEditable && props.selected ? "true" : "false"}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      contentEditable={false}
+    >
+      <ErrorBoundary
+        resetKeys={[sourcePageId, transclusionId]}
+        fallback={<ErrorPlaceholder />}
+      >
+        <TransclusionReferenceBody {...props} trackOpen={trackOpen} />
+      </ErrorBoundary>
+    </NodeViewWrapper>
+  );
+}
+
+function TransclusionReferenceBody({
+  editor,
+  node,
+  deleteNode,
+  getPos,
+  trackOpen,
+}: NodeViewProps & { trackOpen: (open: boolean) => void }) {
+  const { t } = useTranslation();
+  const sourcePageId: string | null = node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = node.attrs.transclusionId ?? null;
+  const isEditable = editor.isEditable;
+
+  const { result, refresh } = useTransclusionLookup(
+    sourcePageId,
+    transclusionId,
+  );
+  const [refreshing, setRefreshing] = useState(false);
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    try {
+      await refresh();
+    } finally {
+      setRefreshing(false);
+    }
+  };
+  // @ts-ignore - editor.storage.pageId is set by the host editor
+  const hostPageId: string | undefined = editor.storage?.pageId;
+  const unsyncMutation = useUnsyncReferenceMutation();
+  // Cached against the dropdown's identical query so the source link target
+  // is ready as soon as the controls fade in on hover, without a second
+  // fetch.
+  const referencesQuery = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    isEditable,
+  );
+  const sourcePageHref = (() => {
+    const source = referencesQuery.data?.source;
+    const base = source?.spaceSlug
+      ? buildPageUrl(source.spaceSlug, source.slugId, source.title)
+      : sourcePageId
+        ? `/p/${sourcePageId}`
+        : null;
+    if (!base) return null;
+    return transclusionId ? `${base}#${transclusionId}` : base;
+  })();
+
+  const handleUnsync = async () => {
+    if (!hostPageId || !sourcePageId || !transclusionId) return;
+    try {
+      const { content } = await unsyncMutation.mutateAsync({
+        referencePageId: hostPageId,
+        sourcePageId,
+        transclusionId,
+      });
+      const pos = getPos();
+      if (typeof pos !== "number") return;
+      const from = pos;
+      const to = pos + node.nodeSize;
+      editor
+        .chain()
+        .focus()
+        .insertContentAt({ from, to }, content as any)
+        .run();
+    } catch {
+      // mutation surfaces errors via React Query; node stays as-is
+    }
+  };
+
+  return (
+    <>
+      {isEditable && (
+        <div
+          className={classes.includeControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && hostPageId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={hostPageId}
+              mode="reference"
+              onOpenChange={trackOpen}
+            />
+          )}
+          <span className={classes.controlsDivider} />
+          <Tooltip label={t("Refresh")}>
+            <ActionIcon
+              variant="subtle"
+              color="gray"
+              size="sm"
+              onClick={handleRefresh}
+              loading={refreshing}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              <IconRefresh size={14} />
+            </ActionIcon>
+          </Tooltip>
+          {sourcePageHref && (
+            <Tooltip label={t("Edit source")}>
+              <ActionIcon
+                component={Link}
+                to={sourcePageHref}
+                variant="subtle"
+                color="gray"
+                size="sm"
+                style={{
+                  textDecoration: "none",
+                  borderBottom: "none",
+                }}
+              >
+                <IconPencil size={14} />
+              </ActionIcon>
+            </Tooltip>
+          )}
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+                disabled={
+                  unsyncMutation.isPending ||
+                  !hostPageId ||
+                  !sourcePageId ||
+                  !transclusionId
+                }
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Remove from page")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      {!sourcePageId || !transclusionId ? (
+        <NotFoundPlaceholder />
+      ) : !result ? (
+        <div style={{ minHeight: 24 }} />
+      ) : !("status" in result) ? (
+        <TransclusionContent content={result.content} />
+      ) : result.status === "no_access" ? (
+        <NoAccessPlaceholder />
+      ) : (
+        <NotFoundPlaceholder />
+      )}
+    </>
+  );
+}
@@ -0,0 +1,126 @@
+import {
+  NodeViewContent,
+  NodeViewProps,
+  NodeViewWrapper,
+} from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import {
+  IconCheck,
+  IconCopy,
+  IconDots,
+  IconLinkOff,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+
+export default function TransclusionView(props: NodeViewProps) {
+  const { editor, node, deleteNode } = props;
+  const { t } = useTranslation();
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  const isEditable = editor.isEditable;
+  // @ts-ignore - editor.storage.pageId is set by the host editor (page-editor.tsx onCreate)
+  const sourcePageId: string | undefined = editor.storage?.pageId;
+  const transclusionId: string | null = node.attrs.id ?? null;
+
+  const [copied, setCopied] = useState(false);
+  const handleCopy = async () => {
+    if (!sourcePageId || !transclusionId) return;
+    const html = `<div data-type="transclusionReference" data-source-page-id="${sourcePageId}" data-transclusion-id="${transclusionId}"></div>`;
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob([html], { type: "text/html" }),
+          "text/plain": new Blob([html], { type: "text/plain" }),
+        }),
+      ]);
+    } catch {
+      // Fallback for browsers without ClipboardItem write support
+      try {
+        await navigator.clipboard.writeText(html);
+      } catch {
+        return;
+      }
+    }
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 2000);
+    notifications.show({
+      message: t("Copied. Paste on any page to embed this synced block."),
+    });
+  };
+
+  const handleUnsync = () => {
+    editor.chain().focus().unsyncTransclusionSource().run();
+  };
+
+  return (
+    <NodeViewWrapper
+      className={classes.transclusionWrap}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      data-id={transclusionId ?? undefined}
+    >
+      {isEditable && (
+        <div
+          className={classes.transclusionControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={sourcePageId}
+              mode="source"
+              onOpenChange={trackOpen}
+            />
+          )}
+
+          <span className={classes.controlsDivider} />
+
+          <Tooltip label={copied ? t("Copied") : t("Copy synced block")}>
+            <ActionIcon
+              variant="subtle"
+              color={copied ? "teal" : "gray"}
+              size="sm"
+              onClick={handleCopy}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              {copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+            </ActionIcon>
+          </Tooltip>
+
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Delete synced block")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}
@@ -0,0 +1,209 @@
+.placeholder {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-radius: var(--mantine-radius-md);
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  font-size: var(--mantine-font-size-sm);
+  user-select: none;
+}
+
+.placeholderIcon {
+  flex: none;
+  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+}
+
+.transclusionBadge {
+  display: inline-block;
+  padding: 2px 8px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 600;
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  border-radius: var(--mantine-radius-sm);
+  margin-bottom: 4px;
+}
+
+.transclusionWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 3rem;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.transclusionWrap:hover,
+.transclusionWrap:focus-within {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.transclusionControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.transclusionControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.transclusionWrap:hover .transclusionControls,
+.transclusionWrap:focus-within .transclusionControls,
+.transclusionWrap[data-menu-open="true"] .transclusionControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.controlsDivider {
+  display: inline-block;
+  width: 1px;
+  height: 16px;
+  background: var(--mantine-color-default-border);
+}
+
+.transclusionControls a[href],
+.includeControls a[href] {
+  color: var(--ai-color);
+  border-bottom: none;
+  font-weight: inherit;
+}
+
+.includeWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 0;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.includeWrap:hover,
+.includeWrap[data-focused="true"],
+.includeWrap[data-menu-open="true"] {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.includeControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.includeControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.includeWrap:hover .includeControls,
+.includeWrap:focus-within .includeControls,
+.includeWrap[data-focused="true"] .includeControls,
+.includeWrap[data-menu-open="true"] .includeControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+:global(.react-renderer.node-transclusionSource.ProseMirror-selectednode),
+:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode) {
+  outline: none;
+}
+
+@media (max-width: 48em) {
+  .transclusionWrap,
+  .includeWrap {
+    margin-left: -1rem;
+    margin-right: -1rem;
+    width: calc(100% + 2rem);
+  }
+
+  .transclusionWrap {
+    padding-left: 1rem;
+    padding-right: 1rem;
+  }
+}
+
+@media print {
+  .transclusionControls,
+  .includeControls {
+    display: none !important;
+  }
+  .transclusionWrap,
+  .includeWrap {
+    border: none !important;
+    margin-left: 0 !important;
+    margin-right: 0 !important;
+    width: 100% !important;
+    padding: 0 !important;
+  }
+}
+
+.editingOriginalTag {
+  display: inline-block;
+  padding: 0 6px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: var(--mantine-color-blue-7);
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  border-radius: var(--mantine-radius-sm);
+}