fix(tree): move treeitem role to focusable row + aria-current

* feat: labels (WIP)
* full implementation

apps/client/package.json

@@ -7,13 +7,18 @@
     "build": "tsc && vite build",
     "lint": "eslint .",
     "preview": "vite preview",
-    "format": "prettier --write \"src/**/*.tsx\" \"src/**/*.ts\""
+    "format": "prettier --write \"src/**/*.tsx\" \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
+    "@atlaskit/pragmatic-drag-and-drop": "^1.8.1",
+    "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^2.1.0",
+    "@atlaskit/pragmatic-drag-and-drop-flourish": "^2.0.15",
+    "@atlaskit/pragmatic-drag-and-drop-hitbox": "^1.1.0",
+    "@atlaskit/pragmatic-drag-and-drop-live-region": "^1.3.4",
     "@casl/react": "^5.0.1",
     "@docmost/editor-ext": "workspace:*",
-    "@emoji-mart/data": "^1.2.1",
-    "@emoji-mart/react": "^1.1.1",
     "@excalidraw/excalidraw": "0.18.0-3a5ef40",
     "@mantine/core": "^8.3.18",
     "@mantine/dates": "^8.3.18",
@@ -22,13 +27,16 @@
     "@mantine/modals": "^8.3.18",
     "@mantine/notifications": "^8.3.18",
     "@mantine/spotlight": "^8.3.18",
+    "@slidoapp/emoji-mart": "^5.8.7",
+    "@slidoapp/emoji-mart-data": "^1.2.4",
+    "@slidoapp/emoji-mart-react": "^1.1.5",
     "@tabler/icons-react": "^3.40.0",
     "@tanstack/react-query": "5.90.17",
+    "@tanstack/react-virtual": "3.13.24",
     "alfaaz": "^1.1.0",
-    "axios": "1.15.0",
+    "axios": "1.16.0",
     "blueimp-load-image": "^5.16.0",
     "clsx": "^2.1.1",
-    "emoji-mart": "^5.6.0",
     "file-saver": "^2.0.5",
     "highlightjs-sap-abap": "^0.3.0",
     "i18next": "25.10.1",
@@ -44,7 +52,6 @@
     "mitt": "^3.0.1",
     "posthog-js": "1.372.2",
     "react": "^18.3.1",
-    "react-arborist": "3.4.0",
     "react-clear-modal": "^2.0.18",
     "react-dom": "^18.3.1",
     "react-drawio": "^1.0.7",
@@ -54,12 +61,13 @@
     "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": {
     "@eslint/js": "^9.28.0",
     "@tanstack/eslint-plugin-query": "^5.94.4",
+    "@testing-library/jest-dom": "^6.6.0",
+    "@testing-library/react": "^16.1.0",
     "@types/blueimp-load-image": "^5.16.6",
     "@types/file-saver": "^2.0.7",
     "@types/js-cookie": "^3.0.6",
@@ -73,6 +81,7 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^15.13.0",
+    "jsdom": "^25.0.0",
     "optics-ts": "^2.4.1",
     "postcss": "^8.5.12",
     "postcss-preset-mantine": "^1.18.0",
@@ -80,6 +89,7 @@
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.1",
-    "vite": "8.0.5"
+    "vite": "8.0.5",
+    "vitest": "^4.1.6"
   }
 }

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

@@ -870,6 +870,12 @@
   "Previous 7 days": "Previous 7 days",
   "Previous 30 days": "Previous 30 days",
   "Search chats...": "Search chats...",
+  "Search chats": "Search chats",
+  "Ask anything... Use @ to mention pages": "Ask anything... Use @ to mention pages",
+  "Ask anything or search your workspace": "Ask anything or search your workspace",
+  "Welcome to {{name}}": "Welcome to {{name}}",
+  "Add files": "Add files",
+  "Mention a page": "Mention a page",
   "Start a new chat to see it here.": "Start a new chat to see it here.",
   "Summarize this page": "Summarize this page",
   "Toggle AI Chat": "Toggle AI Chat",
@@ -926,5 +932,70 @@
   "Settings navigation": "Settings navigation",
   "AI navigation": "AI navigation",
   "Breadcrumb": "Breadcrumb",
-  "Skip to main content": "Skip to main content"
+  "Synced block": "Synced block",
+  "Create a block that stays in sync across pages.": "Create a block that stays in sync across pages.",
+  "Editing original": "Editing original",
+  "Copy synced block": "Copy synced block",
+  "Unsync": "Unsync",
+  "Delete synced block": "Delete synced block",
+  "Synced to {{count}} other page_one": "Synced to {{count}} other page",
+  "Synced to {{count}} other page_other": "Synced to {{count}} other pages",
+  "ORIGINAL": "ORIGINAL",
+  "THIS PAGE": "THIS PAGE",
+  "No pages": "No pages",
+  "The original synced block no longer exists": "The original synced block no longer exists",
+  "You don't have access to this synced block": "You don't have access to this synced block",
+  "Failed to load this synced block": "Failed to load this synced block",
+  "Fixed editor toolbar": "Fixed editor toolbar",
+  "Show a formatting toolbar above the editor with quick access to common actions.": "Show a formatting toolbar above the editor with quick access to common actions.",
+  "Toggle fixed editor toolbar": "Toggle fixed editor toolbar",
+  "Normal text": "Normal text",
+  "More inline formatting": "More inline formatting",
+  "Subscript": "Subscript",
+  "Superscript": "Superscript",
+  "Inline code": "Inline code",
+  "Insert media": "Insert media",
+  "Mention": "Mention",
+  "Emoji": "Emoji",
+  "Columns": "Columns",
+  "More inserts": "More inserts",
+  "Embeds": "Embeds",
+  "Diagrams": "Diagrams",
+  "Advanced": "Advanced",
+  "Utility": "Utility",
+  "Decrease indent": "Decrease indent",
+  "Increase indent": "Increase indent",
+  "Clear formatting": "Clear formatting",
+  "Code block": "Code block",
+  "Experimental": "Experimental",
+  "Strikethrough": "Strikethrough",
+  "Undo": "Undo",
+  "Redo": "Redo",
+  "Backlinks": "Backlinks",
+  "Last updated by": "Last updated by",
+  "Last updated": "Last updated",
+  "Stats": "Stats",
+  "Word count": "Word count",
+  "Characters": "Characters",
+  "Incoming links": "Incoming links",
+  "Outgoing links": "Outgoing links",
+  "Incoming links ({{count}})": "Incoming links ({{count}})",
+  "Outgoing links ({{count}})": "Outgoing links ({{count}})",
+  "No pages link here yet.": "No pages link here yet.",
+  "This page doesn't link to other pages yet.": "This page doesn't link to other pages yet.",
+  "Verified until {{date}}": "Verified until {{date}}",
+  "Labels": "Labels",
+  "Add label": "Add label",
+  "No labels yet": "No labels yet",
+  "Already added": "Already added",
+  "Invalid label name": "Invalid label name",
+  "No matches": "No matches",
+  "Search or create…": "Search or create…",
+  "Remove label {{name}}": "Remove label {{name}}",
+  "Failed to add label": "Failed to add label",
+  "Failed to remove label": "Failed to remove label",
+  "No pages with this label": "No pages with this label",
+  "Pages tagged with this label will appear here.": "Pages tagged with this label will appear here.",
+  "No pages match your search.": "No pages match your search.",
+  "Updated {{date}}": "Updated {{date}}"
 }

apps/client/src/App.tsx

@@ -45,6 +45,7 @@ import TemplateEditor from "@/ee/template/pages/template-editor";
 import FavoritesPage from "@/pages/favorites/favorites-page";
 import AiChat from "@/ee/ai-chat/pages/ai-chat.tsx";
 import VerifyEmail from "@/ee/pages/verify-email.tsx";
+import LabelPage from "@/pages/label/label-page";
 
 export default function App() {
   const { t } = useTranslation();
@@ -92,6 +93,7 @@ export default function App() {
           <Route path={"/ai/chat/:chatId"} element={<AiChat />} />
           <Route path={"/spaces"} element={<SpacesPage />} />
           <Route path={"/favorites"} element={<FavoritesPage />} />
+          <Route path={"/labels/:labelName"} element={<LabelPage />} />
           <Route path={"/templates"} element={<TemplateList />} />
           <Route
             path={"/templates/:templateId"}

apps/client/src/components/layouts/global/app-shell.module.css

@@ -27,23 +27,3 @@
     background: light-dark(var(--mantine-color-gray-4), var(--mantine-color-dark-5))
   }
 }
-
-.skipLink {
-  position: fixed;
-  left: 8px;
-  top: 8px;
-  padding: 8px 12px;
-  background: var(--mantine-color-blue-6);
-  color: #fff;
-  border-radius: 4px;
-  text-decoration: none;
-  z-index: 1000;
-  transform: translateY(-150%);
-
-  &:focus {
-    transform: translateY(0);
-    outline: 2px solid var(--mantine-color-blue-3);
-  }
-}
-
-

apps/client/src/components/layouts/global/aside.tsx

@@ -8,6 +8,7 @@ import { TableOfContents } from "@/features/editor/components/table-of-contents/
 import { useAtomValue } from "jotai";
 import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import AsideChatPanel from "@/ee/ai-chat/components/aside-chat-panel";
+import { PageDetailsAside } from "@/features/page-details/components/page-details-aside.tsx";
 
 export default function Aside() {
   const [{ tab }] = useAtom(asideStateAtom);
@@ -30,6 +31,10 @@ export default function Aside() {
       component = <AsideChatPanel />;
       title = "AI Chat";
       break;
+    case "details":
+      component = <PageDetailsAside />;
+      title = "Details";
+      break;
     default:
       component = null;
       title = null;

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

@@ -81,11 +81,7 @@ export default function GlobalAppShell({
   const showGlobalSidebar = !isSpaceRoute && !isSettingsRoute && !isAiRoute;
 
   return (
-    <>
-      <a href="#main-content" className={classes.skipLink}>
-        {t("Skip to main content")}
-      </a>
-      <AppShell
+    <AppShell
       header={{ height: 45 }}
       navbar={{
         width: isSpaceRoute ? sidebarWidth : 300,
@@ -151,13 +147,14 @@ export default function GlobalAppShell({
                 ? t("Table of contents")
                 : asideTab === "chat"
                   ? t("AI Chat")
-                  : undefined
+                  : asideTab === "details"
+                    ? t("Details")
+                    : undefined
           }
         >
           <Aside />
         </AppShell.Aside>
       )}
     </AppShell>
-    </>
   );
 }

apps/client/src/components/layouts/global/hooks/atoms/sidebar-atom.ts

@@ -10,6 +10,7 @@ export const desktopSidebarAtom = atomWithWebStorage<boolean>(
 
 export const desktopAsideAtom = atom<boolean>(false);
 
+// Valid `tab` values: "" | "comments" | "toc" | "chat" | "details"
 type AsideStateType = {
   tab: string;
   isAsideOpen: boolean;

apps/client/src/components/settings/app-version.tsx

@@ -29,7 +29,7 @@ export default function AppVersion() {
       >
         <Indicator
           label={t("New update")}
-          color="dark"
+          color="gray"
           inline
           size={16}
           position="middle-end"

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

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

apps/client/src/components/ui/emoji-picker.tsx

@@ -1,4 +1,4 @@
-import React, { ReactNode, useState } from "react";
+import React, { ReactNode, useEffect, useState } from "react";
 import {
   ActionIcon,
   Popover,
@@ -7,9 +7,24 @@ import {
 } from "@mantine/core";
 import { useClickOutside, useDisclosure, useWindowEvent } from "@mantine/hooks";
 import { Suspense } from "react";
-const Picker = React.lazy(() => import("@emoji-mart/react"));
 import { useTranslation } from "react-i18next";
 
+// Load the picker module AND the emoji data in parallel inside the lazy
+// resolution, then bind the data into the component. React.lazy only finishes
+// suspending once both are in memory, so the Suspense boundary hides the
+// Remove button until the Picker can render with real content.
+const Picker = React.lazy(async () => {
+  const [pickerModule, dataModule] = await Promise.all([
+    import("@slidoapp/emoji-mart-react"),
+    import("@slidoapp/emoji-mart-data"),
+  ]);
+  const PickerComp = pickerModule.default;
+  const data = dataModule.default;
+  return {
+    default: (props: any) => <PickerComp {...props} data={data} />,
+  };
+});
+
 export interface EmojiPickerInterface {
   onEmojiSelect: (emoji: any) => void;
   icon: ReactNode;
@@ -19,6 +34,7 @@ export interface EmojiPickerInterface {
     size?: string;
     variant?: string;
     c?: string;
+    tabIndex?: number;
   };
 }
 
@@ -50,6 +66,38 @@ function EmojiPicker({
     }
   });
 
+  // emoji-mart's built-in autoFocus calls .focus() without preventScroll, which
+  // makes the browser scroll every scrollable ancestor of the search input to
+  // bring it on screen — including the page editor's scroll container, so the
+  // page jumps to the top whenever the picker is opened from a scrolled-down
+  // position. The search input lives inside the <em-emoji-picker> custom
+  // element's shadow root, so we poll for it after the dropdown mounts and
+  // focus it ourselves with preventScroll.
+  useEffect(() => {
+    if (!opened || !dropdown) return;
+    let cancelled = false;
+    let rafId = 0;
+    const tryFocus = (attempts: number) => {
+      if (cancelled) return;
+      const pickerEl = dropdown.querySelector("em-emoji-picker");
+      const input = pickerEl?.shadowRoot?.querySelector<HTMLInputElement>(
+        'input[type="search"]',
+      );
+      if (input) {
+        input.focus({ preventScroll: true });
+        return;
+      }
+      if (attempts < 60) {
+        rafId = requestAnimationFrame(() => tryFocus(attempts + 1));
+      }
+    };
+    rafId = requestAnimationFrame(() => tryFocus(0));
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(rafId);
+    };
+  }, [opened, dropdown]);
+
   const handleEmojiSelect = (emoji) => {
     onEmojiSelect(emoji);
     handlers.close();
@@ -74,6 +122,7 @@ function EmojiPicker({
           c={actionIconProps?.c || "gray"}
           variant={actionIconProps?.variant || "transparent"}
           size={actionIconProps?.size}
+          tabIndex={actionIconProps?.tabIndex}
           onClick={handlers.toggle}
           aria-label={t("Pick emoji")}
           aria-haspopup="dialog"
@@ -85,7 +134,6 @@ function EmojiPicker({
       <Suspense fallback={null}>
         <Popover.Dropdown bg="000" style={{ border: "none" }} ref={setDropdown}>
           <Picker
-            data={async () => (await import("@emoji-mart/data")).default}
             onEmojiSelect={handleEmojiSelect}
             perLine={8}
             skinTonePosition="search"

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

@@ -137,7 +137,8 @@ export default function AiChatSidebar() {
 
       <TextInput
         className={classes.searchInput}
-        placeholder="Search chats..."
+        placeholder={t("Search chats...")}
+        aria-label={t("Search chats")}
         leftSection={<IconSearch size={14} />}
         size="xs"
         value={search}

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

@@ -178,6 +178,7 @@ export default function AsideChatPanel() {
             href="/ai"
             variant="subtle"
             color="dark"
+            aria-label={t("New chat")}
             onClick={handleNewChat}
           >
             <IconPlus size={20} stroke={1.75} />
@@ -185,13 +186,23 @@ export default function AsideChatPanel() {
         </Tooltip>
 
         <Tooltip label={t("Open full page")} openDelay={250}>
-          <ActionIcon variant="subtle" color="dark" onClick={handleExpand}>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            aria-label={t("Open full page")}
+            onClick={handleExpand}
+          >
             <IconArrowsDiagonal size={18} stroke={1.5} />
           </ActionIcon>
         </Tooltip>
 
         <Tooltip label={t("Close")} openDelay={250}>
-          <ActionIcon variant="subtle" color="dark" onClick={handleClose}>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            aria-label={t("Close")}
+            onClick={handleClose}
+          >
             <IconX size={20} stroke={1.75} />
           </ActionIcon>
         </Tooltip>

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

@@ -65,7 +65,7 @@ export default function ChatEmptyState({ isStreaming, onSend, onStop }: Props) {
           isStreaming={isStreaming}
           onSend={onSend}
           onStop={onStop}
-          placeholder="Ask anything... Use @ to mention pages"
+          placeholder={t("Ask anything... Use @ to mention pages")}
           autofocus
         />
       </div>

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

@@ -200,7 +200,7 @@ export default function ChatInput({
         link: false,
       }),
       Placeholder.configure({
-        placeholder: placeholder || "Ask anything... Use @ to mention pages",
+        placeholder: placeholder || t("Ask anything... Use @ to mention pages"),
       }),
       CharacterCount.configure({
         limit: 50000,
@@ -225,6 +225,10 @@ export default function ChatInput({
       }),
     ],
     editorProps: {
+      attributes: {
+        "aria-label": placeholder || t("Ask anything... Use @ to mention pages"),
+        "aria-multiline": "true",
+      },
       handleDOMEvents: {
         keydown: (_view, event) => {
           if (
@@ -275,6 +279,8 @@ export default function ChatInput({
         type="file"
         accept={ACCEPTED_FILE_TYPES}
         multiple
+        aria-label={t("Add files")}
+        tabIndex={-1}
         style={{ display: "none" }}
         onChange={(e) => handleFileSelect(e.target.files)}
       />

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

@@ -31,7 +31,16 @@ export default function ChatToolGroup({ toolCalls, isStreaming }: Props) {
     <div className={classes.toolGroup}>
       <div
         className={classes.toolGroupHeader}
+        role="button"
+        tabIndex={0}
+        aria-expanded={expanded}
         onClick={() => setExpanded((prev) => !prev)}
+        onKeyDown={(event) => {
+          if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            setExpanded((prev) => !prev);
+          }
+        }}
       >
         {activeLabel ? (
           <IconLoader2 size={12} className={classes.processingSpinner} />

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

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

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

@@ -43,7 +43,7 @@
   margin-top: 6px;
   text-align: center;
   font-size: var(--mantine-font-size-xs);
-  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+  color: var(--mantine-color-dimmed);
 }
 
 .attachmentChips {

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

@@ -36,7 +36,7 @@
   padding: 4px var(--mantine-spacing-xs);
   font-size: var(--mantine-font-size-xs);
   font-weight: 600;
-  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  color: var(--mantine-color-dimmed);
   user-select: none;
 }
 
@@ -104,7 +104,7 @@
 
 .chatItemDate {
   font-size: var(--mantine-font-size-xs);
-  color: light-dark(var(--mantine-color-gray-5), var(--mantine-color-dark-3));
+  color: var(--mantine-color-dimmed);
   white-space: nowrap;
   transition: opacity 150ms;
 }

apps/client/src/ee/page-verification/components/page-verification-modal.tsx

@@ -118,10 +118,20 @@ export function PageVerificationBadge({
 
   if (status === "none" && readOnly) return null;
 
+  const tooltipLabel =
+    status === "verified" && verificationInfo?.expiresAt
+      ? t("Verified until {{date}}", {
+          date: new Date(verificationInfo.expiresAt).toLocaleDateString(
+            undefined,
+            { month: "long", day: "numeric", year: "numeric" },
+          ),
+        })
+      : getStatusLabel(status, t);
+
   return (
     <>
       {status !== "none" ? (
-        <Tooltip label={getStatusLabel(status, t)} withArrow openDelay={250}>
+        <Tooltip label={tooltipLabel} withArrow openDelay={250}>
           <Group
             gap={4}
             onClick={open}

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

@@ -28,6 +28,18 @@
   }
 }
 
+.colorSwatch:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--mantine-color-blue-6);
+  position: relative;
+  z-index: 1;
+}
+
+.removeColor:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--mantine-color-blue-6);
+}
+
 .buttonRoot {
   height: 34px;
   padding-left: rem(8);

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

@@ -27,7 +27,7 @@ import { isCellSelection, isTextSelected } from "@docmost/editor-ext";
 import { LinkSelector } from "@/features/editor/components/bubble-menu/link-selector.tsx";
 import { useTranslation } from "react-i18next";
 import { showAiMenuAtom, showLinkMenuAtom } from "@/features/editor/atoms/editor-atoms";
-import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
+import { userAtom, workspaceAtom } from "@/features/user/atoms/current-user-atom";
 
 export interface BubbleMenuItem {
   name: string;
@@ -46,6 +46,9 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
   const [showCommentPopup, setShowCommentPopup] = useAtom(showCommentPopupAtom);
   const workspace = useAtomValue(workspaceAtom);
   const isGenerativeAiEnabled = workspace?.settings?.ai?.generative === true;
+  const user = useAtomValue(userAtom);
+  const editorToolbarEnabled =
+    user?.settings?.preferences?.editorToolbar ?? false;
   const [, setDraftCommentId] = useAtom(draftCommentIdAtom);
   const showCommentPopupRef = useRef(showCommentPopup);
   const showAiMenuRef = useRef(showAiMenu);
@@ -149,7 +152,7 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
       return isTextSelected(editor);
     },
     options: {
-      placement: "top",
+      placement: editorToolbarEnabled ? "bottom" : "top",
       offset: 8,
       onHide: () => {
         setIsNodeSelectorOpen(false);
@@ -188,56 +191,60 @@ export const EditorBubbleMenu: FC<EditorBubbleMenuProps> = (props) => {
             <div className={classes.divider} />
           </>
         )}
-        <NodeSelector
-          editor={props.editor}
-          isOpen={isNodeSelectorOpen}
-          setIsOpen={() => {
-            setIsNodeSelectorOpen(!isNodeSelectorOpen);
-            setIsTextAlignmentOpen(false);
-            setIsColorSelectorOpen(false);
-          }}
-        />
+        {!editorToolbarEnabled && (
+          <>
+            <NodeSelector
+              editor={props.editor}
+              isOpen={isNodeSelectorOpen}
+              setIsOpen={() => {
+                setIsNodeSelectorOpen(!isNodeSelectorOpen);
+                setIsTextAlignmentOpen(false);
+                setIsColorSelectorOpen(false);
+              }}
+            />
 
-        <TextAlignmentSelector
-          editor={props.editor}
-          isOpen={isTextAlignmentSelectorOpen}
-          setIsOpen={() => {
-            setIsTextAlignmentOpen(!isTextAlignmentSelectorOpen);
-            setIsNodeSelectorOpen(false);
-            setIsColorSelectorOpen(false);
-          }}
-        />
+            <TextAlignmentSelector
+              editor={props.editor}
+              isOpen={isTextAlignmentSelectorOpen}
+              setIsOpen={() => {
+                setIsTextAlignmentOpen(!isTextAlignmentSelectorOpen);
+                setIsNodeSelectorOpen(false);
+                setIsColorSelectorOpen(false);
+              }}
+            />
 
-        <ActionIcon.Group>
-          {items.map((item, index) => (
-            <Tooltip key={index} label={t(item.name)} withArrow>
-              <ActionIcon
-                key={index}
-                variant="default"
-                size="lg"
-                radius="0"
-                aria-label={t(item.name)}
-                className={clsx({ [classes.active]: item.isActive() })}
-                style={{ border: "none" }}
-                onClick={item.command}
-              >
-                <item.icon style={{ width: rem(16) }} stroke={2} />
-              </ActionIcon>
-            </Tooltip>
-          ))}
-        </ActionIcon.Group>
+            <ActionIcon.Group>
+              {items.map((item, index) => (
+                <Tooltip key={index} label={t(item.name)} withArrow>
+                  <ActionIcon
+                    key={index}
+                    variant="default"
+                    size="lg"
+                    radius="0"
+                    aria-label={t(item.name)}
+                    className={clsx({ [classes.active]: item.isActive() })}
+                    style={{ border: "none" }}
+                    onClick={item.command}
+                  >
+                    <item.icon style={{ width: rem(16) }} stroke={2} />
+                  </ActionIcon>
+                </Tooltip>
+              ))}
+            </ActionIcon.Group>
 
-        <LinkSelector />
+            <LinkSelector />
 
-        <ColorSelector
-          editor={props.editor}
-          isOpen={isColorSelectorOpen}
-          setIsOpen={() => {
-            setIsColorSelectorOpen(!isColorSelectorOpen);
-            setIsNodeSelectorOpen(false);
-            setIsTextAlignmentOpen(false);
-          }}
-        />
+            <ColorSelector
+              editor={props.editor}
+              isOpen={isColorSelectorOpen}
+              setIsOpen={() => {
+                setIsColorSelectorOpen(!isColorSelectorOpen);
+                setIsNodeSelectorOpen(false);
+                setIsTextAlignmentOpen(false);
+              }}
+            />
+          </>
+        )}
 
         <Tooltip label={t(commentItem.name)} withArrow withinPortal={false}>
           <ActionIcon

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

@@ -4,7 +4,6 @@ import {
   Button,
   Popover,
   rem,
-  ScrollArea,
   Text,
   Tooltip,
   SimpleGrid,
@@ -114,6 +113,63 @@ const HIGHLIGHT_COLORS: BubbleColorMenuItem[] = [
   },
 ];
 
+const COLOR_GRID_COLS = 5;
+
+function focusSwatch(grid: "text" | "highlight", index: number) {
+  const el = document.querySelector<HTMLElement>(
+    `[data-color-grid="${grid}"][data-color-index="${index}"]`,
+  );
+  el?.focus();
+}
+
+function handleColorKeyNav(
+  e: React.KeyboardEvent<HTMLDivElement>,
+  index: number,
+  grid: "text" | "highlight",
+) {
+  const cols = COLOR_GRID_COLS;
+  const total =
+    grid === "text" ? TEXT_COLORS.length : HIGHLIGHT_COLORS.length;
+  const col = index % cols;
+
+  if (e.key === "ArrowRight") {
+    e.preventDefault();
+    if (index < total - 1) focusSwatch(grid, index + 1);
+    return;
+  }
+  if (e.key === "ArrowLeft") {
+    e.preventDefault();
+    if (index > 0) focusSwatch(grid, index - 1);
+    return;
+  }
+  if (e.key === "ArrowDown") {
+    e.preventDefault();
+    const next = index + cols;
+    if (next < total) {
+      focusSwatch(grid, next);
+    } else if (grid === "text") {
+      focusSwatch("highlight", Math.min(col, HIGHLIGHT_COLORS.length - 1));
+    } else if (grid === "highlight") {
+      document
+        .querySelector<HTMLElement>('[data-color-grid="remove"]')
+        ?.focus();
+    }
+    return;
+  }
+  if (e.key === "ArrowUp") {
+    e.preventDefault();
+    const prev = index - cols;
+    if (prev >= 0) {
+      focusSwatch(grid, prev);
+    } else if (grid === "highlight") {
+      const lastRowStart =
+        Math.floor((TEXT_COLORS.length - 1) / cols) * cols;
+      focusSwatch("text", Math.min(lastRowStart + col, TEXT_COLORS.length - 1));
+    }
+    return;
+  }
+}
+
 export const ColorSelector: FC<ColorSelectorProps> = ({
   editor,
   isOpen,
@@ -157,13 +213,20 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
   );
 
   return (
-    <Popover width={220} opened={isOpen} withArrow>
+    <Popover
+      width={220}
+      opened={isOpen}
+      onChange={setIsOpen}
+      trapFocus
+      withArrow
+    >
       <Popover.Target>
         <Tooltip label={t("Text color")} withArrow>
           <Button
             variant="default"
             radius="0"
             rightSection={<IconChevronDown size={16} />}
+            onMouseDown={(e) => e.preventDefault()}
             onClick={() => setIsOpen(!isOpen)}
             data-text-color={activeColorItem?.color || ""}
             data-highlight-color={activeHighlightItem?.color || ""}
@@ -181,9 +244,8 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
         </Tooltip>
       </Popover.Target>
 
-      <Popover.Dropdown>
-        <ScrollArea.Autosize type="scroll" mah="400">
-          <Stack gap="md">
+      <Popover.Dropdown onMouseDown={(e) => e.preventDefault()}>
+        <Stack gap="md" p="2px">
             <Box>
               <Text size="sm" fw={600} mb="xs">
                 {t("Text color")}
@@ -207,6 +269,10 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
                     <Box
                       role="button"
                       tabIndex={0}
+                      data-autofocus={index === 0 ? true : undefined}
+                      data-color-grid="text"
+                      data-color-index={index}
+                      className={classes.colorSwatch}
                       aria-label={t(name)}
                       aria-pressed={!!editorState[`text_${color}`]}
                       onClick={applyTextColor}
@@ -214,7 +280,9 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
                         if (e.key === "Enter" || e.key === " ") {
                           e.preventDefault();
                           applyTextColor();
+                          return;
                         }
+                        handleColorKeyNav(e, index, "text");
                       }}
                       style={{
                         width: rem(28),
@@ -267,6 +335,9 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
                     <Box
                       role="button"
                       tabIndex={0}
+                      data-color-grid="highlight"
+                      data-color-index={index}
+                      className={classes.colorSwatch}
                       aria-label={t(name)}
                       aria-pressed={!!editorState[`highlight_${color}`]}
                       onClick={applyHighlight}
@@ -274,7 +345,9 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
                         if (e.key === "Enter" || e.key === " ") {
                           e.preventDefault();
                           applyHighlight();
+                          return;
                         }
+                        handleColorKeyNav(e, index, "highlight");
                       }}
                       style={{
                         width: rem(28),
@@ -310,16 +383,27 @@ export const ColorSelector: FC<ColorSelectorProps> = ({
             <Button
               variant="default"
               fullWidth
+              data-color-grid="remove"
+              className={classes.removeColor}
               onClick={() => {
                 editor.commands.unsetColor();
                 editor.commands.unsetHighlight();
                 setIsOpen(false);
               }}
+              onKeyDown={(e) => {
+                if (e.key === "ArrowUp") {
+                  e.preventDefault();
+                  const lastRowStart =
+                    Math.floor(
+                      (HIGHLIGHT_COLORS.length - 1) / COLOR_GRID_COLS,
+                    ) * COLOR_GRID_COLS;
+                  focusSwatch("highlight", lastRowStart);
+                }
+              }}
             >
               {t("Remove color")}
             </Button>
           </Stack>
-        </ScrollArea.Autosize>
       </Popover.Dropdown>
     </Popover>
   );

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

@@ -12,6 +12,7 @@ import {
   IconInfoCircle,
   IconList,
   IconListNumbers,
+  IconQuote,
   IconTypography,
 } from "@tabler/icons-react";
 import { Popover, Button, ScrollArea, Tooltip } from "@mantine/core";
@@ -59,6 +60,7 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
         isCodeBlock: ctx.editor.isActive("codeBlock"),
         isCallout: ctx.editor.isActive("callout"),
         isDetails: ctx.editor.isActive("details"),
+        isTransclusionSource: ctx.editor.isActive("transclusionSource"),
       };
     },
   });
@@ -122,6 +124,12 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
           .run(),
       isActive: () => editorState?.isBlockquote,
     },
+    {
+      name: "Synced block",
+      icon: IconQuote,
+      command: () => editor.chain().focus().toggleTransclusionSource().run(),
+      isActive: () => editorState?.isTransclusionSource,
+    },
     {
       name: "Code",
       icon: IconCode,
@@ -147,9 +155,14 @@ export const NodeSelector: FC<NodeSelectorProps> = ({
   };
 
   return (
-    <Popover opened={isOpen} withArrow>
+    <Popover opened={isOpen} onChange={setIsOpen} withArrow>
       <Popover.Target>
-        <Tooltip label={t("Turn into")} withArrow withinPortal={false} disabled={isOpen}>
+        <Tooltip
+          label={t("Turn into")}
+          withArrow
+          withinPortal={false}
+          disabled={isOpen}
+        >
           <Button
             className={classes.buttonRoot}
             variant="default"

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

@@ -7,7 +7,7 @@ import {
   IconCheck,
   IconChevronDown,
 } from "@tabler/icons-react";
-import { Popover, Button, ScrollArea, Tooltip, rem } from "@mantine/core";
+import { Menu, Button, Tooltip, rem } from "@mantine/core";
 import type { Editor } from "@tiptap/react";
 import { useEditorState } from "@tiptap/react";
 import { useTranslation } from "react-i18next";
@@ -82,15 +82,22 @@ export const TextAlignmentSelector: FC<TextAlignmentProps> = ({
   const activeItem = items.filter((item) => item.isActive()).pop() ?? items[0];
 
   return (
-    <Popover opened={isOpen} withArrow>
-      <Popover.Target>
-        <Tooltip label={t("Text align")} withArrow withinPortal={false} disabled={isOpen}>
+    <Menu
+      shadow="md"
+      position="bottom-start"
+      withArrow={false}
+      opened={isOpen}
+      onChange={setIsOpen}
+    >
+      <Menu.Target>
+        <Tooltip label={t("Text align")} withArrow disabled={isOpen}>
           <Button
             variant="default"
             style={{ border: "none", height: "34px" }}
             px="5"
             radius="0"
             rightSection={<IconChevronDown size={16} />}
+            onMouseDown={(e) => e.preventDefault()}
             onClick={() => setIsOpen(!isOpen)}
             aria-label={t("Text align")}
             aria-haspopup="menu"
@@ -99,33 +106,25 @@ export const TextAlignmentSelector: FC<TextAlignmentProps> = ({
             <activeItem.icon style={{ width: rem(16) }} stroke={2} />
           </Button>
         </Tooltip>
-      </Popover.Target>
+      </Menu.Target>
 
-      <Popover.Dropdown>
-        <ScrollArea.Autosize type="scroll" mah={400}>
-          <Button.Group orientation="vertical">
-            {items.map((item, index) => (
-              <Button
-                key={index}
-                variant="default"
-                leftSection={<item.icon size={16} />}
-                rightSection={
-                  activeItem.name === item.name && <IconCheck size={16} />
-                }
-                justify="left"
-                fullWidth
-                onClick={() => {
-                  item.command();
-                  setIsOpen(false);
-                }}
-                style={{ border: "none" }}
-              >
-                {t(item.name)}
-              </Button>
-            ))}
-          </Button.Group>
-        </ScrollArea.Autosize>
-      </Popover.Dropdown>
-    </Popover>
+      <Menu.Dropdown>
+        {items.map((item, index) => (
+          <Menu.Item
+            key={index}
+            leftSection={<item.icon size={16} />}
+            rightSection={
+              activeItem.name === item.name ? <IconCheck size={16} /> : null
+            }
+            onClick={() => {
+              item.command();
+              setIsOpen(false);
+            }}
+          >
+            {t(item.name)}
+          </Menu.Item>
+        ))}
+      </Menu.Dropdown>
+    </Menu>
   );
 };

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

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

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

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

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

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

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

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

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

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

apps/client/src/features/editor/components/fixed-toolbar/fixed-toolbar.module.css

@@ -0,0 +1,72 @@
+.fixedToolbar {
+  position: fixed;
+  top: calc(var(--app-shell-header-offset, 0rem) + 45px);
+  inset-inline-start: var(--app-shell-navbar-offset, 0rem);
+  inset-inline-end: var(--app-shell-aside-offset, 0rem);
+  z-index: 50;
+  display: flex;
+  align-items: center;
+  background: var(--mantine-color-body);
+  border-bottom: 1px solid
+    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-4));
+  overflow-x: auto;
+}
+
+.fixedToolbar::-webkit-scrollbar {
+  height: 2px;
+}
+
+.fixedToolbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.fixedToolbar::-webkit-scrollbar-thumb {
+  background: light-dark(
+    var(--mantine-color-gray-4),
+    var(--mantine-color-dark-3)
+  );
+  border-radius: 1px;
+}
+
+.inner {
+  display: flex;
+  align-items: center;
+  flex-wrap: nowrap;
+  gap: 4px;
+  padding: 4px 8px;
+  margin-inline: auto;
+}
+
+.inner > * {
+  flex-shrink: 0;
+}
+
+.spacer {
+  height: 45px;
+}
+
+.divider {
+  flex-shrink: 0;
+  width: 1px;
+  height: 20px;
+  margin: 0 4px;
+  background: light-dark(
+    var(--mantine-color-gray-3),
+    var(--mantine-color-dark-4)
+  );
+}
+
+.active,
+.active:hover {
+  color: var(--mantine-color-blue-6);
+  background-color: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+@media print {
+  .fixedToolbar {
+    display: none;
+  }
+}

apps/client/src/features/editor/components/fixed-toolbar/fixed-toolbar.tsx

@@ -0,0 +1,65 @@
+import { FC } from "react";
+import { useAtomValue } from "jotai";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms";
+import { useToolbarState } from "./use-toolbar-state";
+import { BlockTypeGroup } from "./groups/block-type-group";
+import { InlineMarksGroup } from "./groups/inline-marks-group";
+import { ColorGroup } from "./groups/color-group";
+import { ListsGroup } from "./groups/lists-group";
+import { LinkGroup } from "./groups/link-group";
+import { AlignmentGroup } from "./groups/alignment-group";
+import { MediaGroup } from "./groups/media-group";
+import { QuickInsertsGroup } from "./groups/quick-inserts-group";
+import { MoreInsertsGroup } from "./groups/more-inserts-group";
+import { HistoryGroup } from "./groups/history-group";
+import { AskAiGroup } from "./groups/ask-ai-group";
+import { workspaceAtom } from "@/features/user/atoms/current-user-atom";
+import classes from "./fixed-toolbar.module.css";
+
+export const FixedToolbar: FC = () => {
+  const editor = useAtomValue(pageEditorAtom);
+  const state = useToolbarState(editor);
+  const workspace = useAtomValue(workspaceAtom);
+  const isGenerativeAiEnabled = workspace?.settings?.ai?.generative === true;
+
+  if (!editor || !state) return null;
+
+  return (
+    <>
+      <div
+        className={classes.fixedToolbar}
+        role="toolbar"
+        aria-label="Editor toolbar"
+        onMouseDown={(e) => e.preventDefault()}
+      >
+        <div className={classes.inner}>
+          {/* {isGenerativeAiEnabled && (
+            <>
+              <AskAiGroup />
+              <div className={classes.divider} />
+            </>
+          )} */}
+          <BlockTypeGroup editor={editor} />
+          <div className={classes.divider} />
+          <InlineMarksGroup editor={editor} state={state} />
+          <div className={classes.divider} />
+          <ColorGroup editor={editor} />
+          <div className={classes.divider} />
+          <ListsGroup editor={editor} state={state} />
+          <div className={classes.divider} />
+          <LinkGroup />
+          <div className={classes.divider} />
+          <AlignmentGroup editor={editor} />
+          <div className={classes.divider} />
+          <MediaGroup editor={editor} />
+          <div className={classes.divider} />
+          <QuickInsertsGroup editor={editor} />
+          <MoreInsertsGroup editor={editor} />
+          <div className={classes.divider} />
+          <HistoryGroup editor={editor} state={state} />
+        </div>
+      </div>
+      <div className={classes.spacer} aria-hidden />
+    </>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/alignment-group.tsx

@@ -0,0 +1,28 @@
+import { FC, useEffect, useState } from "react";
+import type { Editor } from "@tiptap/react";
+import { TextAlignmentSelector } from "@/features/editor/components/bubble-menu/text-alignment-selector";
+
+interface Props {
+  editor: Editor;
+}
+
+export const AlignmentGroup: FC<Props> = ({ editor }) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [isOpen]);
+
+  return (
+    <TextAlignmentSelector
+      editor={editor}
+      isOpen={isOpen}
+      setIsOpen={setIsOpen}
+    />
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/ask-ai-group.tsx

@@ -0,0 +1,23 @@
+import { FC } from "react";
+import { Button } from "@mantine/core";
+import { IconSparkles } from "@tabler/icons-react";
+import { useSetAtom } from "jotai";
+import { useTranslation } from "react-i18next";
+import { showAiMenuAtom } from "@/features/editor/atoms/editor-atoms";
+
+export const AskAiGroup: FC = () => {
+  const { t } = useTranslation();
+  const setShowAiMenu = useSetAtom(showAiMenuAtom);
+
+  return (
+    <Button
+      variant="subtle"
+      color="dark"
+      size="xs"
+      leftSection={<IconSparkles size={14} />}
+      onClick={() => setShowAiMenu(true)}
+    >
+      {t("Ask AI")}
+    </Button>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/block-type-group.tsx

@@ -0,0 +1,108 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { useEditorState } from "@tiptap/react";
+import { Button, Menu } from "@mantine/core";
+import {
+  IconBlockquote,
+  IconBraces,
+  IconChevronDown,
+  IconH1,
+  IconH2,
+  IconH3,
+  IconMenu4,
+  IconTypography,
+} from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+
+interface Props {
+  editor: Editor;
+}
+
+export const BlockTypeGroup: FC<Props> = ({ editor }) => {
+  const { t } = useTranslation();
+
+  const state = useEditorState({
+    editor,
+    selector: (ctx) => ({
+      isHeading1: ctx.editor.isActive("heading", { level: 1 }),
+      isHeading2: ctx.editor.isActive("heading", { level: 2 }),
+      isHeading3: ctx.editor.isActive("heading", { level: 3 }),
+      isBlockquote: ctx.editor.isActive("blockquote"),
+      isCodeBlock: ctx.editor.isActive("codeBlock"),
+    }),
+  });
+
+  let label = t("Normal text");
+  if (state.isHeading1) label = t("Heading 1");
+  else if (state.isHeading2) label = t("Heading 2");
+  else if (state.isHeading3) label = t("Heading 3");
+  else if (state.isBlockquote) label = t("Quote");
+  else if (state.isCodeBlock) label = t("Code block");
+
+  return (
+    <Menu shadow="md" position="bottom-start" withArrow={false}>
+      <Menu.Target>
+        <Button
+          variant="subtle"
+          color="dark"
+          size="xs"
+          rightSection={<IconChevronDown size={14} />}
+        >
+          {label}
+        </Button>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item
+          leftSection={<IconTypography size={16} />}
+          onClick={() =>
+            editor.chain().focus().toggleNode("paragraph", "paragraph").run()
+          }
+        >
+          {t("Text")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconH1 size={16} />}
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 1 }).run()
+          }
+        >
+          {t("Heading 1")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconH2 size={16} />}
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 2 }).run()
+          }
+        >
+          {t("Heading 2")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconH3 size={16} />}
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 3 }).run()
+          }
+        >
+          {t("Heading 3")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconBlockquote size={16} />}
+          onClick={() => editor.chain().focus().toggleBlockquote().run()}
+        >
+          {t("Quote")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconBraces size={16} />}
+          onClick={() => editor.chain().focus().toggleCodeBlock().run()}
+        >
+          {t("Code block")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconMenu4 size={16} />}
+          onClick={() => editor.chain().focus().setHorizontalRule().run()}
+        >
+          {t("Divider")}
+        </Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/color-group.tsx

@@ -0,0 +1,24 @@
+import { FC, useEffect, useState } from "react";
+import type { Editor } from "@tiptap/react";
+import { ColorSelector } from "@/features/editor/components/bubble-menu/color-selector";
+
+interface Props {
+  editor: Editor;
+}
+
+export const ColorGroup: FC<Props> = ({ editor }) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [isOpen]);
+
+  return (
+    <ColorSelector editor={editor} isOpen={isOpen} setIsOpen={setIsOpen} />
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/history-group.tsx

@@ -0,0 +1,44 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Tooltip } from "@mantine/core";
+import { IconArrowBackUp, IconArrowForwardUp } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import type { ToolbarState } from "../use-toolbar-state";
+
+interface Props {
+  editor: Editor;
+  state: ToolbarState;
+}
+
+export const HistoryGroup: FC<Props> = ({ editor, state }) => {
+  const { t } = useTranslation();
+
+  return (
+    <ActionIcon.Group>
+      <Tooltip label={t("Undo")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Undo")}
+          disabled={!state.canUndo}
+          onClick={() => editor.chain().focus().undo().run()}
+        >
+          <IconArrowBackUp size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("Redo")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Redo")}
+          disabled={!state.canRedo}
+          onClick={() => editor.chain().focus().redo().run()}
+        >
+          <IconArrowForwardUp size={16} />
+        </ActionIcon>
+      </Tooltip>
+    </ActionIcon.Group>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/inline-marks-group.tsx

@@ -0,0 +1,131 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconBold,
+  IconChevronDown,
+  IconClearFormatting,
+  IconCode,
+  IconIndentDecrease,
+  IconIndentIncrease,
+  IconItalic,
+  IconStrikethrough,
+  IconSubscript,
+  IconSuperscript,
+  IconUnderline,
+} from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import clsx from "clsx";
+import type { ToolbarState } from "../use-toolbar-state";
+import classes from "../fixed-toolbar.module.css";
+
+interface Props {
+  editor: Editor;
+  state: ToolbarState;
+}
+
+export const InlineMarksGroup: FC<Props> = ({ editor, state }) => {
+  const { t } = useTranslation();
+
+  return (
+    <ActionIcon.Group>
+      <Tooltip label={t("Bold")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Bold")}
+          aria-pressed={state.isBold}
+          className={clsx({ [classes.active]: state.isBold })}
+          onClick={() => editor.chain().focus().toggleBold().run()}
+        >
+          <IconBold size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("Underline")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Underline")}
+          aria-pressed={state.isUnderline}
+          className={clsx({ [classes.active]: state.isUnderline })}
+          onClick={() => editor.chain().focus().toggleUnderline().run()}
+        >
+          <IconUnderline size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("Italic")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Italic")}
+          aria-pressed={state.isItalic}
+          className={clsx({ [classes.active]: state.isItalic })}
+          onClick={() => editor.chain().focus().toggleItalic().run()}
+        >
+          <IconItalic size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Menu shadow="md" position="bottom-start" withArrow={false}>
+        <Menu.Target>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            size="md"
+            aria-label={t("More inline formatting")}
+          >
+            <IconChevronDown size={14} />
+          </ActionIcon>
+        </Menu.Target>
+        <Menu.Dropdown>
+          <Menu.Item
+            leftSection={<IconStrikethrough size={16} />}
+            onClick={() => editor.chain().focus().toggleStrike().run()}
+          >
+            {t("Strikethrough")}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconCode size={16} />}
+            onClick={() => editor.chain().focus().toggleCode().run()}
+          >
+            {t("Inline code")}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconSubscript size={16} />}
+            onClick={() => editor.chain().focus().toggleSubscript().run()}
+          >
+            {t("Subscript")}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconSuperscript size={16} />}
+            onClick={() => editor.chain().focus().toggleSuperscript().run()}
+          >
+            {t("Superscript")}
+          </Menu.Item>
+          <Menu.Divider />
+          <Menu.Item
+            leftSection={<IconIndentIncrease size={16} />}
+            onClick={() => editor.chain().focus().indent().run()}
+          >
+            {t("Increase indent")}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconIndentDecrease size={16} />}
+            onClick={() => editor.chain().focus().outdent().run()}
+          >
+            {t("Decrease indent")}
+          </Menu.Item>
+          <Menu.Divider />
+          <Menu.Item
+            leftSection={<IconClearFormatting size={16} />}
+            onClick={() => editor.chain().focus().unsetAllMarks().run()}
+          >
+            {t("Clear formatting")}
+          </Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+    </ActionIcon.Group>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/link-group.tsx

@@ -0,0 +1,6 @@
+import { FC } from "react";
+import { LinkSelector } from "@/features/editor/components/bubble-menu/link-selector";
+
+export const LinkGroup: FC = () => {
+  return <LinkSelector />;
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/lists-group.tsx

@@ -0,0 +1,61 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Tooltip } from "@mantine/core";
+import { IconCheckbox, IconList, IconListNumbers } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import clsx from "clsx";
+import type { ToolbarState } from "../use-toolbar-state";
+import classes from "../fixed-toolbar.module.css";
+
+interface Props {
+  editor: Editor;
+  state: ToolbarState;
+}
+
+export const ListsGroup: FC<Props> = ({ editor, state }) => {
+  const { t } = useTranslation();
+
+  return (
+    <ActionIcon.Group>
+      <Tooltip label={t("Bullet List")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Bullet List")}
+          aria-pressed={state.isBulletList}
+          className={clsx({ [classes.active]: state.isBulletList })}
+          onClick={() => editor.chain().focus().toggleBulletList().run()}
+        >
+          <IconList size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("Numbered List")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Numbered List")}
+          aria-pressed={state.isOrderedList}
+          className={clsx({ [classes.active]: state.isOrderedList })}
+          onClick={() => editor.chain().focus().toggleOrderedList().run()}
+        >
+          <IconListNumbers size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("To-do List")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("To-do List")}
+          aria-pressed={state.isTaskList}
+          className={clsx({ [classes.active]: state.isTaskList })}
+          onClick={() => editor.chain().focus().toggleTaskList().run()}
+        >
+          <IconCheckbox size={16} />
+        </ActionIcon>
+      </Tooltip>
+    </ActionIcon.Group>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/media-group.tsx

@@ -0,0 +1,118 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconFileTypePdf,
+  IconMovie,
+  IconMusic,
+  IconPaperclip,
+  IconPhoto,
+} from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { uploadImageAction } from "@/features/editor/components/image/upload-image-action";
+import { uploadVideoAction } from "@/features/editor/components/video/upload-video-action";
+import { uploadAudioAction } from "@/features/editor/components/audio/upload-audio-action";
+import { uploadAttachmentAction } from "@/features/editor/components/attachment/upload-attachment-action";
+import { uploadPdfAction } from "@/features/editor/components/pdf/upload-pdf-action";
+
+interface Props {
+  editor: Editor;
+}
+
+type UploadFn = (
+  file: File,
+  editor: Editor,
+  pos: number,
+  pageId: string,
+  ...rest: any[]
+) => void;
+
+function pickFile(
+  editor: Editor,
+  accept: string,
+  multiple: boolean,
+  upload: UploadFn,
+  extra?: boolean,
+) {
+  // @ts-ignore — editor.storage.pageId is set by PageEditor.onCreate
+  const pageId = editor.storage?.pageId as string | undefined;
+  if (!pageId) return;
+
+  const input = document.createElement("input");
+  input.type = "file";
+  input.accept = accept;
+  input.multiple = multiple;
+  input.style.display = "none";
+  document.body.appendChild(input);
+  input.onchange = () => {
+    if (input.files?.length) {
+      for (const file of input.files) {
+        const pos = editor.view.state.selection.from;
+        if (extra !== undefined) {
+          upload(file, editor, pos, pageId, extra);
+        } else {
+          upload(file, editor, pos, pageId);
+        }
+      }
+    }
+    input.remove();
+  };
+  input.click();
+}
+
+export const MediaGroup: FC<Props> = ({ editor }) => {
+  const { t } = useTranslation();
+
+  return (
+    <Menu shadow="md" position="bottom-start" withArrow={false}>
+      <Menu.Target>
+        <Tooltip label={t("Insert media")} withArrow>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            size="md"
+            aria-label={t("Insert media")}
+          >
+            <IconPhoto size={16} />
+          </ActionIcon>
+        </Tooltip>
+      </Menu.Target>
+      <Menu.Dropdown>
+        <Menu.Item
+          leftSection={<IconPhoto size={16} />}
+          onClick={() => pickFile(editor, "image/*", true, uploadImageAction)}
+        >
+          {t("Image")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconMovie size={16} />}
+          onClick={() => pickFile(editor, "video/*", true, uploadVideoAction)}
+        >
+          {t("Video")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconMusic size={16} />}
+          onClick={() => pickFile(editor, "audio/*", true, uploadAudioAction)}
+        >
+          {t("Audio")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconFileTypePdf size={16} />}
+          onClick={() =>
+            pickFile(editor, "application/pdf", false, uploadPdfAction)
+          }
+        >
+          PDF
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconPaperclip size={16} />}
+          onClick={() =>
+            pickFile(editor, "", true, uploadAttachmentAction, true)
+          }
+        >
+          {t("File attachment")}
+        </Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/more-inserts-group.tsx

@@ -0,0 +1,217 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconAppWindow,
+  IconCalendar,
+  IconCaretRightFilled,
+  IconChevronDown,
+  IconInfoCircle,
+  IconMath,
+  IconMathFunction,
+  IconRotate2,
+  IconSitemap,
+  IconTag,
+} from "@tabler/icons-react";
+import IconExcalidraw from "@/components/icons/icon-excalidraw";
+import IconMermaid from "@/components/icons/icon-mermaid";
+import IconDrawio from "@/components/icons/icon-drawio";
+import {
+  AirtableIcon,
+  FigmaIcon,
+  FramerIcon,
+  GoogleDriveIcon,
+  GoogleSheetsIcon,
+  LoomIcon,
+  MiroIcon,
+  TypeformIcon,
+  VimeoIcon,
+  YoutubeIcon,
+} from "@/components/icons";
+import { useTranslation } from "react-i18next";
+
+interface Props {
+  editor: Editor;
+}
+
+export const MoreInsertsGroup: FC<Props> = ({ editor }) => {
+  const { t } = useTranslation();
+
+  const setEmbed = (provider: string) =>
+    editor.chain().focus().setEmbed({ provider }).run();
+
+  const insertDate = () => {
+    const currentDate = new Date().toLocaleDateString("en-US", {
+      year: "numeric",
+      month: "long",
+      day: "numeric",
+    });
+    editor.chain().focus().insertContent(currentDate).run();
+  };
+
+  return (
+    <Menu shadow="md" position="bottom-start" withArrow={false} width={240}>
+      <Menu.Target>
+        <Tooltip label={t("More inserts")} withArrow>
+          <ActionIcon
+            variant="subtle"
+            color="dark"
+            size="md"
+            aria-label={t("More inserts")}
+          >
+            <IconChevronDown size={16} />
+          </ActionIcon>
+        </Tooltip>
+      </Menu.Target>
+      <Menu.Dropdown mah={400} style={{ overflowY: "auto" }}>
+        <Menu.Label>{t("Advanced")}</Menu.Label>
+        <Menu.Item
+          leftSection={<IconInfoCircle size={16} />}
+          onClick={() => editor.chain().focus().toggleCallout().run()}
+        >
+          {t("Callout")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconCaretRightFilled size={16} />}
+          onClick={() => editor.chain().focus().setDetails().run()}
+        >
+          {t("Toggle block")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconTag size={16} />}
+          onClick={() =>
+            editor.chain().focus().setStatus({ text: "", color: "gray" }).run()
+          }
+        >
+          {t("Status")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconSitemap size={16} />}
+          onClick={() => editor.chain().focus().insertSubpages().run()}
+        >
+          {t("Subpages")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconRotate2 size={16} />}
+          onClick={() =>
+            editor.chain().focus().insertTransclusionSource().run()
+          }
+        >
+          {t("Synced block")}
+        </Menu.Item>
+
+        <Menu.Divider />
+        <Menu.Label>{t("Diagrams")}</Menu.Label>
+        <Menu.Item
+          leftSection={<IconMermaid size={16} />}
+          onClick={() =>
+            editor
+              .chain()
+              .focus()
+              .setCodeBlock({ language: "mermaid" })
+              .insertContent("flowchart LR\n    A --> B")
+              .run()
+          }
+        >
+          {t("Mermaid diagram")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconDrawio size={16} />}
+          onClick={() => editor.chain().focus().setDrawio().run()}
+        >
+          Draw.io
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconExcalidraw size={16} />}
+          onClick={() => editor.chain().focus().setExcalidraw().run()}
+        >
+          Excalidraw
+        </Menu.Item>
+
+        <Menu.Divider />
+        <Menu.Label>{t("Embeds")}</Menu.Label>
+        <Menu.Item
+          leftSection={<IconAppWindow size={16} />}
+          onClick={() => setEmbed("iframe")}
+        >
+          Iframe
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<YoutubeIcon size={16} />}
+          onClick={() => setEmbed("youtube")}
+        >
+          YouTube
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<VimeoIcon size={16} />}
+          onClick={() => setEmbed("vimeo")}
+        >
+          Vimeo
+        </Menu.Item>
+        <Menu.Item leftSection={<LoomIcon size={16} />} onClick={() => setEmbed("loom")}>
+          Loom
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<FigmaIcon size={16} />}
+          onClick={() => setEmbed("figma")}
+        >
+          Figma
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<AirtableIcon size={16} />}
+          onClick={() => setEmbed("airtable")}
+        >
+          Airtable
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<TypeformIcon size={16} />}
+          onClick={() => setEmbed("typeform")}
+        >
+          Typeform
+        </Menu.Item>
+        <Menu.Item leftSection={<MiroIcon size={16} />} onClick={() => setEmbed("miro")}>
+          Miro
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<FramerIcon size={16} />}
+          onClick={() => setEmbed("framer")}
+        >
+          Framer
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<GoogleDriveIcon size={16} />}
+          onClick={() => setEmbed("gdrive")}
+        >
+          Google Drive
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<GoogleSheetsIcon size={16} />}
+          onClick={() => setEmbed("gsheets")}
+        >
+          Google Sheets
+        </Menu.Item>
+
+        <Menu.Divider />
+        <Menu.Label>{t("Utility")}</Menu.Label>
+        <Menu.Item
+          leftSection={<IconCalendar size={16} />}
+          onClick={insertDate}
+        >
+          {t("Date")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconMathFunction size={16} />}
+          onClick={() => editor.chain().focus().setMathInline().run()}
+        >
+          {t("Math inline")}
+        </Menu.Item>
+        <Menu.Item
+          leftSection={<IconMath size={16} />}
+          onClick={() => editor.chain().focus().setMathBlock().run()}
+        >
+          {t("Math block")}
+        </Menu.Item>
+      </Menu.Dropdown>
+    </Menu>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/groups/quick-inserts-group.tsx

@@ -0,0 +1,117 @@
+import { FC } from "react";
+import type { Editor } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconAt,
+  IconColumns2,
+  IconColumns3,
+  IconMoodSmile,
+  IconTable,
+} from "@tabler/icons-react";
+import { IconColumns4 } from "@/components/icons/icon-columns-4";
+import { IconColumns5 } from "@/components/icons/icon-columns-5";
+import { useTranslation } from "react-i18next";
+
+interface Props {
+  editor: Editor;
+}
+
+export const QuickInsertsGroup: FC<Props> = ({ editor }) => {
+  const { t } = useTranslation();
+
+  return (
+    <ActionIcon.Group>
+      <Tooltip label={t("Mention")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Mention")}
+          onClick={() => editor.chain().focus().insertContent("@").run()}
+        >
+          <IconAt size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Tooltip label={t("Emoji")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Emoji")}
+          onClick={() => editor.chain().focus().insertContent(":").run()}
+        >
+          <IconMoodSmile size={16} />
+        </ActionIcon>
+      </Tooltip>
+      <Menu shadow="md" position="bottom-start" withArrow={false}>
+        <Menu.Target>
+          <Tooltip label={t("Columns")} withArrow>
+            <ActionIcon
+              variant="subtle"
+              color="dark"
+              size="md"
+              aria-label={t("Columns")}
+            >
+              <IconColumns2 size={16} />
+            </ActionIcon>
+          </Tooltip>
+        </Menu.Target>
+        <Menu.Dropdown>
+          <Menu.Item
+            leftSection={<IconColumns2 size={16} />}
+            onClick={() =>
+              editor.chain().focus().insertColumns({ layout: "two_equal" }).run()
+            }
+          >
+            {t("{{count}} Columns", { count: 2 })}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconColumns3 size={16} />}
+            onClick={() =>
+              editor
+                .chain()
+                .focus()
+                .insertColumns({ layout: "three_equal" })
+                .run()
+            }
+          >
+            {t("{{count}} Columns", { count: 3 })}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconColumns4 size={16} />}
+            onClick={() =>
+              editor.chain().focus().insertColumns({ layout: "four_equal" }).run()
+            }
+          >
+            {t("{{count}} Columns", { count: 4 })}
+          </Menu.Item>
+          <Menu.Item
+            leftSection={<IconColumns5 size={16} />}
+            onClick={() =>
+              editor.chain().focus().insertColumns({ layout: "five_equal" }).run()
+            }
+          >
+            {t("{{count}} Columns", { count: 5 })}
+          </Menu.Item>
+        </Menu.Dropdown>
+      </Menu>
+      <Tooltip label={t("Table")} withArrow>
+        <ActionIcon
+          variant="subtle"
+          color="dark"
+          size="md"
+          aria-label={t("Table")}
+          onClick={() =>
+            editor
+              .chain()
+              .focus()
+              .insertTable({ rows: 3, cols: 3, withHeaderRow: true })
+              .run()
+          }
+        >
+          <IconTable size={16} />
+        </ActionIcon>
+      </Tooltip>
+    </ActionIcon.Group>
+  );
+};

apps/client/src/features/editor/components/fixed-toolbar/use-toolbar-state.ts

@@ -0,0 +1,50 @@
+import type { Editor } from "@tiptap/react";
+import { useEditorState } from "@tiptap/react";
+
+export interface ToolbarState {
+  isBold: boolean;
+  isItalic: boolean;
+  isUnderline: boolean;
+  isStrike: boolean;
+  isCode: boolean;
+  isSubscript: boolean;
+  isSuperscript: boolean;
+  isBulletList: boolean;
+  isOrderedList: boolean;
+  isTaskList: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+// Undo/redo come from either StarterKit's history or the Yjs collaboration
+// history extension. During the brief moment a page is rendered with the
+// static editor (mainExtensions only, undoRedo disabled), neither is loaded
+// and editor.can().undo/redo is undefined.
+function safeCan(editor: Editor, command: "undo" | "redo"): boolean {
+  const can = editor.can() as Record<string, unknown>;
+  const fn = can[command];
+  return typeof fn === "function" ? (fn as () => boolean)() : false;
+}
+
+export function useToolbarState(editor: Editor | null): ToolbarState | null {
+  return useEditorState({
+    editor,
+    selector: (ctx) => {
+      if (!ctx.editor) return null;
+      return {
+        isBold: ctx.editor.isActive("bold"),
+        isItalic: ctx.editor.isActive("italic"),
+        isUnderline: ctx.editor.isActive("underline"),
+        isStrike: ctx.editor.isActive("strike"),
+        isCode: ctx.editor.isActive("code"),
+        isSubscript: ctx.editor.isActive("subscript"),
+        isSuperscript: ctx.editor.isActive("superscript"),
+        isBulletList: ctx.editor.isActive("bulletList"),
+        isOrderedList: ctx.editor.isActive("orderedList"),
+        isTaskList: ctx.editor.isActive("taskList"),
+        canUndo: safeCan(ctx.editor, "undo"),
+        canRedo: safeCan(ctx.editor, "redo"),
+      };
+    },
+  });
+}

apps/client/src/features/editor/components/mention/mention-list.tsx

@@ -3,7 +3,6 @@ import React, {
   useCallback,
   useEffect,
   useImperativeHandle,
-  useMemo,
   useRef,
   useState,
 } from "react";
@@ -36,7 +35,7 @@ import {
   usePageQuery,
 } from "@/features/page/queries/page-query";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom";
-import { SimpleTree } from "react-arborist";
+import { treeModel } from "@/features/page/tree/model/tree-model";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { useTranslation } from "react-i18next";
 import { useQueryEmit } from "@/features/websocket/use-query-emit";
@@ -53,7 +52,6 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
   const [renderItems, setRenderItems] = useState<MentionSuggestionItem[]>([]);
   const { t } = useTranslation();
   const [data, setData] = useAtom(treeDataAtom);
-  const tree = useMemo(() => new SimpleTree<SpaceTreeNode>(data), [data]);
   const createPageMutation = useCreatePageMutation();
   const emit = useQueryEmit();
   const isInCommentContext = props.isInCommentContext ?? false;
@@ -220,20 +218,20 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
     try {
       createdPage = await createPageMutation.mutateAsync(payload);
       const parentId = page.id || null;
-      const data = {
+      const newNode: SpaceTreeNode = {
         id: createdPage.id,
         slugId: createdPage.slugId,
         name: createdPage.title,
         position: createdPage.position,
         spaceId: createdPage.spaceId,
         parentPageId: createdPage.parentPageId,
+        hasChildren: false,
         children: [],
-      } as any;
+      };
 
-      const lastIndex = tree.data.length;
+      const lastIndex = data.length;
 
-      tree.create({ parentId, index: lastIndex, data });
-      setData(tree.data);
+      setData(treeModel.insert(data, parentId, newNode, lastIndex));
 
       props.command({
         id: uuid7(),
@@ -251,7 +249,7 @@ const MentionList = forwardRef<any, MentionListProps>((props, ref) => {
           payload: {
             parentId,
             index: lastIndex,
-            data,
+            data: newNode,
           },
         });
       }, 50);

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

@@ -25,6 +25,8 @@ import {
   IconColumns3,
   IconColumns2,
   IconTag,
+  IconMoodSmile,
+  IconRotate2,
 } from "@tabler/icons-react";
 import {
   CommandProps,
@@ -132,7 +134,7 @@ const CommandGroups: SlashMenuGroupedItemsType = {
     {
       title: "Numbered list",
       description: "Create a list with numbering.",
-      searchTerms: ["numbered", "ordered", "list"],
+      searchTerms: ["numbered", "ordered", "list", "ol"],
       icon: IconListNumbers,
       command: ({ editor, range }: CommandProps) => {
         editor.chain().focus().deleteRange(range).toggleOrderedList().run();
@@ -231,7 +233,15 @@ const CommandGroups: SlashMenuGroupedItemsType = {
     {
       title: "Audio",
       description: "Upload any audio from your device.",
-      searchTerms: ["audio", "music", "sound", "mp3", "media", "file", "attachment"],
+      searchTerms: [
+        "audio",
+        "music",
+        "sound",
+        "mp3",
+        "media",
+        "file",
+        "attachment",
+      ],
       icon: IconMusic,
       command: ({ editor, range }) => {
         editor.chain().focus().deleteRange(range).run();
@@ -468,15 +478,53 @@ const CommandGroups: SlashMenuGroupedItemsType = {
           .run();
       },
     },
+    {
+      title: "Emoji",
+      description: "Insert emoji.",
+      searchTerms: ["emoji", "icon", "smiley", "emoticon", "symbol", "reaction"],
+      icon: IconMoodSmile,
+      command: ({ editor, range }: CommandProps) => {
+        editor.chain().focus().deleteRange(range).insertContent(":").run();
+      },
+    },
     {
       title: "Subpages (Child pages)",
       description: "List all subpages of the current page",
-      searchTerms: ["subpages", "child", "children", "nested", "hierarchy"],
+      searchTerms: [
+        "subpages",
+        "child",
+        "children",
+        "nested",
+        "hierarchy",
+        "toc",
+      ],
       icon: IconSitemap,
       command: ({ editor, range }: CommandProps) => {
         editor.chain().focus().deleteRange(range).insertSubpages().run();
       },
     },
+    {
+      title: "Synced block",
+      description: "Create a block that stays in sync across pages.",
+      searchTerms: [
+        "sync",
+        "synced",
+        "synced block",
+        "excerpt",
+        "transclusion",
+        "reusable",
+        "snippet",
+      ],
+      icon: IconRotate2,
+      command: ({ editor, range }: CommandProps) => {
+        editor
+          .chain()
+          .focus()
+          .deleteRange(range)
+          .insertTransclusionSource()
+          .run();
+      },
+    },
     {
       title: "2 Columns",
       description: "Split content into two columns.",

apps/client/src/features/editor/components/table-of-contents/table-of-contents.tsx

@@ -25,7 +25,7 @@ const recalculateLinks = (nodePos: NodePos[]) => {
     (acc, item) => {
       const label = item.node.textContent;
       const level = Number(item.node.attrs.level);
-      if (label.length && level <= 3) {
+      if (label.length && level <= 4) {
         acc.push({
           label,
           level,

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

@@ -0,0 +1,17 @@
+import { IconAlertTriangle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function ErrorPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconAlertTriangle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("Failed to load this synced block")}</span>
+    </div>
+  );
+}

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

@@ -0,0 +1,13 @@
+import { IconEyeOff } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NoAccessPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconEyeOff size={18} stroke={1.6} className={classes.placeholderIcon} />
+      <span>{t("You don't have access to this synced block")}</span>
+    </div>
+  );
+}

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

@@ -0,0 +1,17 @@
+import { IconInfoCircle } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+
+export default function NotFoundPlaceholder() {
+  const { t } = useTranslation();
+  return (
+    <div className={classes.placeholder}>
+      <IconInfoCircle
+        size={18}
+        stroke={1.6}
+        className={classes.placeholderIcon}
+      />
+      <span>{t("The original synced block no longer exists")}</span>
+    </div>
+  );
+}

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

@@ -0,0 +1,48 @@
+import { EditorProvider } from "@tiptap/react";
+import { useMemo } from "react";
+import { mainExtensions } from "@/features/editor/extensions/extensions";
+import { UniqueID } from "@docmost/editor-ext";
+
+type Props = {
+  content: unknown;
+};
+
+export default function TransclusionContent({ content }: Props) {
+  const extensions = useMemo(() => {
+    const filtered = mainExtensions.filter(
+      (e: any) => e.name !== "uniqueID" && e.name !== "globalDragHandle",
+    );
+    return [
+      ...filtered,
+      UniqueID.configure({
+        types: ["heading", "paragraph", "transclusionSource"],
+        updateDocument: false,
+      }),
+    ];
+  }, []);
+
+  // Isolate the nested read-only editor's events from the host editor:
+  // - mousedown/click would otherwise make the host node-select the atom
+  //   wrapper, blocking native text selection inside.
+  // - dragstart/dragover/drop would otherwise let the host treat events
+  //   inside the nested view as drops on the host, duplicating dropped
+  //   files at the transclusion's position.
+  const stop = (e: React.SyntheticEvent) => e.stopPropagation();
+
+  return (
+    <div
+      onMouseDown={stop}
+      onClick={stop}
+      onDragStart={stop}
+      onDragOver={stop}
+      onDrop={stop}
+    >
+      <EditorProvider
+        editable={false}
+        immediatelyRender={true}
+        extensions={extensions}
+        content={content as any}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,213 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  lookupTransclusion,
+  lookupTransclusionForShare,
+} from "@/features/transclusion/services/transclusion-api";
+import type { TransclusionLookup } from "@/features/transclusion/types/transclusion.types";
+
+type LookupKey = string; // `${sourcePageId}::${transclusionId}`
+
+type Subscriber = {
+  key: LookupKey;
+  sourcePageId: string;
+  transclusionId: string;
+  setResult: (r: TransclusionLookup) => void;
+};
+
+type ContextValue = {
+  /** Register a subscriber. Returns an unsubscribe function. */
+  subscribe: (s: Subscriber) => () => void;
+  /**
+   * Force a re-fetch of `key` and resolve when the response arrives (or the
+   * request fails). Bypasses the cache and any in-flight de-dup so the user
+   * always sees a fresh server read.
+   */
+  refresh: (key: LookupKey) => Promise<void>;
+};
+
+const TransclusionLookupContext = createContext<ContextValue | null>(null);
+
+export function TransclusionLookupProvider({
+  children,
+  shareId,
+}: {
+  children: React.ReactNode;
+  /**
+   * When set, lookups go through the share-scoped public endpoint and are
+   * gated by the share graph (source page must have its own share or inherit
+   * one). Used by the public share viewer; left undefined in the authenticated
+   * app, where personal permissions gate access.
+   */
+  shareId?: string;
+}) {
+  const subscribersRef = useRef(new Map<LookupKey, Subscriber[]>());
+  const queueRef = useRef(new Set<LookupKey>());
+  const tickRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Read inside flush() via ref so changing share context doesn't churn the
+  // memoized callbacks (and thus doesn't re-render every consumer).
+  const shareIdRef = useRef<string | undefined>(shareId);
+  shareIdRef.current = shareId;
+  // Last looked-up value for each key. Re-subscribers (e.g. when the editor
+  // remounts after switching from static to live) get this immediately
+  // instead of triggering a duplicate fetch.
+  const resultCacheRef = useRef(new Map<LookupKey, TransclusionLookup>());
+  // Keys that are currently in flight in a batch request. A second subscribe
+  // for the same key while the first request is pending is a no-op; the
+  // subscriber is added to subscribersRef and will be notified when the
+  // pending request completes.
+  const inFlightRef = useRef(new Set<LookupKey>());
+  // Resolvers waiting on the next response for a key. Populated by refresh()
+  // so callers can await the fetch round-trip; resolved on success and on
+  // network error so the UI never hangs in a loading state.
+  const pendingRef = useRef(new Map<LookupKey, Array<() => void>>());
+
+  const flush = useCallback(async () => {
+    tickRef.current = null;
+    const keys = Array.from(queueRef.current);
+    queueRef.current.clear();
+    if (keys.length === 0) return;
+
+    for (const k of keys) inFlightRef.current.add(k);
+
+    const references = keys.map((k) => {
+      const [sourcePageId, transclusionId] = k.split("::");
+      return { sourcePageId, transclusionId };
+    });
+
+    const resolveWaiters = (key: LookupKey) => {
+      const waiters = pendingRef.current.get(key);
+      if (!waiters) return;
+      pendingRef.current.delete(key);
+      for (const w of waiters) w();
+    };
+
+    try {
+      const activeShareId = shareIdRef.current;
+      const { items } = activeShareId
+        ? await lookupTransclusionForShare({
+            shareId: activeShareId,
+            references,
+          })
+        : await lookupTransclusion({ references });
+      for (const r of items) {
+        const key = `${r.sourcePageId}::${r.transclusionId}`;
+        resultCacheRef.current.set(key, r);
+        inFlightRef.current.delete(key);
+        const subs = subscribersRef.current.get(key);
+        if (subs) {
+          for (const s of subs) s.setResult(r);
+        }
+        resolveWaiters(key);
+      }
+    } catch {
+      // Network error — leave subscribers in pending state and clear the
+      // in-flight flag so a future subscribe can retry.
+      for (const k of keys) {
+        inFlightRef.current.delete(k);
+        resolveWaiters(k);
+      }
+    }
+  }, []);
+
+  const enqueue = useCallback(
+    (key: LookupKey) => {
+      queueRef.current.add(key);
+      if (tickRef.current === null) {
+        tickRef.current = setTimeout(flush, 10);
+      }
+    },
+    [flush],
+  );
+
+  const subscribe = useCallback<ContextValue["subscribe"]>(
+    (s) => {
+      const list = subscribersRef.current.get(s.key) ?? [];
+      list.push(s);
+      subscribersRef.current.set(s.key, list);
+
+      const cached = resultCacheRef.current.get(s.key);
+      if (cached) {
+        s.setResult(cached);
+      } else if (!inFlightRef.current.has(s.key)) {
+        enqueue(s.key);
+      }
+
+      return () => {
+        const cur = subscribersRef.current.get(s.key) ?? [];
+        const next = cur.filter((x) => x !== s);
+        if (next.length === 0) subscribersRef.current.delete(s.key);
+        else subscribersRef.current.set(s.key, next);
+      };
+    },
+    [enqueue],
+  );
+
+  const refresh = useCallback<ContextValue["refresh"]>(
+    (key) =>
+      new Promise<void>((resolve) => {
+        resultCacheRef.current.delete(key);
+        inFlightRef.current.delete(key);
+        const waiters = pendingRef.current.get(key) ?? [];
+        waiters.push(resolve);
+        pendingRef.current.set(key, waiters);
+        enqueue(key);
+      }),
+    [enqueue],
+  );
+
+  useEffect(
+    () => () => {
+      if (tickRef.current) clearTimeout(tickRef.current);
+    },
+    [],
+  );
+
+  const value = useMemo<ContextValue>(
+    () => ({ subscribe, refresh }),
+    [subscribe, refresh],
+  );
+
+  return (
+    <TransclusionLookupContext.Provider value={value}>
+      {children}
+    </TransclusionLookupContext.Provider>
+  );
+}
+
+export function useTransclusionLookup(
+  sourcePageId: string | null | undefined,
+  transclusionId: string | null | undefined,
+): {
+  result: TransclusionLookup | null;
+  refresh: () => Promise<void>;
+} {
+  const ctx = useContext(TransclusionLookupContext);
+  const [result, setResult] = useState<TransclusionLookup | null>(null);
+
+  useEffect(() => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    const key = `${sourcePageId}::${transclusionId}`;
+    const unsubscribe = ctx.subscribe({
+      key,
+      sourcePageId,
+      transclusionId,
+      setResult,
+    });
+    return unsubscribe;
+  }, [ctx, sourcePageId, transclusionId]);
+
+  const refresh = useCallback(async () => {
+    if (!ctx || !sourcePageId || !transclusionId) return;
+    await ctx.refresh(`${sourcePageId}::${transclusionId}`);
+  }, [ctx, sourcePageId, transclusionId]);
+
+  return { result, refresh };
+}

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

@@ -0,0 +1,212 @@
+import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import {
+  IconDots,
+  IconLinkOff,
+  IconPencil,
+  IconRefresh,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { ErrorBoundary } from "react-error-boundary";
+import { useTransclusionLookup } from "./transclusion-lookup-context";
+import TransclusionContent from "./transclusion-content";
+import NoAccessPlaceholder from "./no-access-placeholder";
+import NotFoundPlaceholder from "./not-found-placeholder";
+import ErrorPlaceholder from "./error-placeholder";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+import {
+  useReferencesQuery,
+  useUnsyncReferenceMutation,
+} from "@/features/transclusion/queries/transclusion-query";
+import { buildPageUrl } from "@/features/page/page.utils";
+
+export default function TransclusionReferenceView(props: NodeViewProps) {
+  const isEditable = props.editor.isEditable;
+  const sourcePageId: string | null = props.node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = props.node.attrs.transclusionId ?? null;
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  return (
+    <NodeViewWrapper
+      className={classes.includeWrap}
+      data-focused={isEditable && props.selected ? "true" : "false"}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      contentEditable={false}
+    >
+      <ErrorBoundary
+        resetKeys={[sourcePageId, transclusionId]}
+        fallback={<ErrorPlaceholder />}
+      >
+        <TransclusionReferenceBody {...props} trackOpen={trackOpen} />
+      </ErrorBoundary>
+    </NodeViewWrapper>
+  );
+}
+
+function TransclusionReferenceBody({
+  editor,
+  node,
+  deleteNode,
+  getPos,
+  trackOpen,
+}: NodeViewProps & { trackOpen: (open: boolean) => void }) {
+  const { t } = useTranslation();
+  const sourcePageId: string | null = node.attrs.sourcePageId ?? null;
+  const transclusionId: string | null = node.attrs.transclusionId ?? null;
+  const isEditable = editor.isEditable;
+
+  const { result, refresh } = useTransclusionLookup(
+    sourcePageId,
+    transclusionId,
+  );
+  const [refreshing, setRefreshing] = useState(false);
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    try {
+      await refresh();
+    } finally {
+      setRefreshing(false);
+    }
+  };
+  // @ts-ignore - editor.storage.pageId is set by the host editor
+  const hostPageId: string | undefined = editor.storage?.pageId;
+  const unsyncMutation = useUnsyncReferenceMutation();
+  // Cached against the dropdown's identical query so the source link target
+  // is ready as soon as the controls fade in on hover, without a second
+  // fetch.
+  const referencesQuery = useReferencesQuery(
+    sourcePageId,
+    transclusionId,
+    isEditable,
+  );
+  const sourcePageHref = (() => {
+    const source = referencesQuery.data?.source;
+    const base = source?.spaceSlug
+      ? buildPageUrl(source.spaceSlug, source.slugId, source.title)
+      : sourcePageId
+        ? `/p/${sourcePageId}`
+        : null;
+    if (!base) return null;
+    return transclusionId ? `${base}#${transclusionId}` : base;
+  })();
+
+  const handleUnsync = async () => {
+    if (!hostPageId || !sourcePageId || !transclusionId) return;
+    try {
+      const { content } = await unsyncMutation.mutateAsync({
+        referencePageId: hostPageId,
+        sourcePageId,
+        transclusionId,
+      });
+      const pos = getPos();
+      if (typeof pos !== "number") return;
+      const from = pos;
+      const to = pos + node.nodeSize;
+      editor
+        .chain()
+        .focus()
+        .insertContentAt({ from, to }, content as any)
+        .run();
+    } catch {
+      // mutation surfaces errors via React Query; node stays as-is
+    }
+  };
+
+  return (
+    <>
+      {isEditable && (
+        <div
+          className={classes.includeControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && hostPageId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={hostPageId}
+              mode="reference"
+              onOpenChange={trackOpen}
+            />
+          )}
+          <span className={classes.controlsDivider} />
+          <Tooltip label={t("Refresh")}>
+            <ActionIcon
+              variant="subtle"
+              color="gray"
+              size="sm"
+              onClick={handleRefresh}
+              loading={refreshing}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              <IconRefresh size={14} />
+            </ActionIcon>
+          </Tooltip>
+          {sourcePageHref && (
+            <Tooltip label={t("Edit source")}>
+              <ActionIcon
+                component={Link}
+                to={sourcePageHref}
+                variant="subtle"
+                color="gray"
+                size="sm"
+                style={{
+                  textDecoration: "none",
+                  borderBottom: "none",
+                }}
+              >
+                <IconPencil size={14} />
+              </ActionIcon>
+            </Tooltip>
+          )}
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+                disabled={
+                  unsyncMutation.isPending ||
+                  !hostPageId ||
+                  !sourcePageId ||
+                  !transclusionId
+                }
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Remove from page")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      {!sourcePageId || !transclusionId ? (
+        <NotFoundPlaceholder />
+      ) : !result ? (
+        <div style={{ minHeight: 24 }} />
+      ) : !("status" in result) ? (
+        <TransclusionContent content={result.content} />
+      ) : result.status === "no_access" ? (
+        <NoAccessPlaceholder />
+      ) : (
+        <NotFoundPlaceholder />
+      )}
+    </>
+  );
+}

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

@@ -0,0 +1,126 @@
+import {
+  NodeViewContent,
+  NodeViewProps,
+  NodeViewWrapper,
+} from "@tiptap/react";
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+import {
+  IconCheck,
+  IconCopy,
+  IconDots,
+  IconLinkOff,
+  IconTrash,
+} from "@tabler/icons-react";
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import classes from "./transclusion.module.css";
+import SyncBlockReferencesDropdown from "@/features/transclusion/components/sync-block-references-dropdown";
+
+export default function TransclusionView(props: NodeViewProps) {
+  const { editor, node, deleteNode } = props;
+  const { t } = useTranslation();
+  const [openMenus, setOpenMenus] = useState(0);
+  const trackOpen = (open: boolean) =>
+    setOpenMenus((n) => Math.max(0, n + (open ? 1 : -1)));
+
+  const isEditable = editor.isEditable;
+  // @ts-ignore - editor.storage.pageId is set by the host editor (page-editor.tsx onCreate)
+  const sourcePageId: string | undefined = editor.storage?.pageId;
+  const transclusionId: string | null = node.attrs.id ?? null;
+
+  const [copied, setCopied] = useState(false);
+  const handleCopy = async () => {
+    if (!sourcePageId || !transclusionId) return;
+    const html = `<div data-type="transclusionReference" data-source-page-id="${sourcePageId}" data-transclusion-id="${transclusionId}"></div>`;
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/html": new Blob([html], { type: "text/html" }),
+          "text/plain": new Blob([html], { type: "text/plain" }),
+        }),
+      ]);
+    } catch {
+      // Fallback for browsers without ClipboardItem write support
+      try {
+        await navigator.clipboard.writeText(html);
+      } catch {
+        return;
+      }
+    }
+    setCopied(true);
+    window.setTimeout(() => setCopied(false), 2000);
+    notifications.show({
+      message: t("Copied. Paste on any page to embed this synced block."),
+    });
+  };
+
+  const handleUnsync = () => {
+    editor.chain().focus().unsyncTransclusionSource().run();
+  };
+
+  return (
+    <NodeViewWrapper
+      className={classes.transclusionWrap}
+      data-menu-open={openMenus > 0 ? "true" : "false"}
+      data-id={transclusionId ?? undefined}
+    >
+      {isEditable && (
+        <div
+          className={classes.transclusionControls}
+          contentEditable={false}
+          onMouseDown={(e) => e.preventDefault()}
+        >
+          {sourcePageId && transclusionId && (
+            <SyncBlockReferencesDropdown
+              sourcePageId={sourcePageId}
+              transclusionId={transclusionId}
+              currentPageId={sourcePageId}
+              mode="source"
+              onOpenChange={trackOpen}
+            />
+          )}
+
+          <span className={classes.controlsDivider} />
+
+          <Tooltip label={copied ? t("Copied") : t("Copy synced block")}>
+            <ActionIcon
+              variant="subtle"
+              color={copied ? "teal" : "gray"}
+              size="sm"
+              onClick={handleCopy}
+              disabled={!sourcePageId || !transclusionId}
+            >
+              {copied ? <IconCheck size={14} /> : <IconCopy size={14} />}
+            </ActionIcon>
+          </Tooltip>
+
+          <Menu position="bottom-end" withinPortal onChange={trackOpen}>
+            <Menu.Target>
+              <ActionIcon variant="subtle" color="gray" size="sm">
+                <IconDots size={14} />
+              </ActionIcon>
+            </Menu.Target>
+            <Menu.Dropdown>
+              <Menu.Item
+                leftSection={<IconLinkOff size={14} />}
+                onClick={handleUnsync}
+              >
+                {t("Unsync")}
+              </Menu.Item>
+              <Menu.Item
+                color="red"
+                leftSection={<IconTrash size={14} />}
+                onClick={() => deleteNode()}
+              >
+                {t("Delete synced block")}
+              </Menu.Item>
+            </Menu.Dropdown>
+          </Menu>
+        </div>
+      )}
+
+      <NodeViewContent />
+    </NodeViewWrapper>
+  );
+}

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

@@ -0,0 +1,209 @@
+.placeholder {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-radius: var(--mantine-radius-md);
+  background: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  font-size: var(--mantine-font-size-sm);
+  user-select: none;
+}
+
+.placeholderIcon {
+  flex: none;
+  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+}
+
+.transclusionBadge {
+  display: inline-block;
+  padding: 2px 8px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 600;
+  color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-1));
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  border-radius: var(--mantine-radius-sm);
+  margin-bottom: 4px;
+}
+
+.transclusionWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 3rem;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.transclusionWrap:hover,
+.transclusionWrap:focus-within {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.transclusionControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.transclusionControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.transclusionWrap:hover .transclusionControls,
+.transclusionWrap:focus-within .transclusionControls,
+.transclusionWrap[data-menu-open="true"] .transclusionControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.controlsDivider {
+  display: inline-block;
+  width: 1px;
+  height: 16px;
+  background: var(--mantine-color-default-border);
+}
+
+.transclusionControls a[href],
+.includeControls a[href] {
+  color: var(--ai-color);
+  border-bottom: none;
+  font-weight: inherit;
+}
+
+.includeWrap {
+  position: relative;
+  margin-left: -3rem;
+  margin-right: -3rem;
+  width: calc(100% + 6rem);
+  padding: 0.5em 0;
+  border-radius: 8px;
+  border: 2px solid transparent;
+  transition: border 0.3s;
+}
+
+.includeWrap:hover,
+.includeWrap[data-focused="true"],
+.includeWrap[data-menu-open="true"] {
+  border: 2px solid
+    light-dark(
+      var(--mantine-color-orange-2),
+      color-mix(in srgb, var(--mantine-color-orange-9), transparent 55%)
+    );
+}
+
+.includeControls {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  right: 4px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--mantine-color-body);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 6px;
+  padding: 4px 6px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 2;
+}
+
+/* Hover bridge: keeps :hover on the wrap while the cursor crosses the
+   8px gap between wrap and floating chrome, so the menu doesn't fade out
+   on the way to it. */
+.includeControls::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0;
+  right: 0;
+  height: 8px;
+}
+
+.includeWrap:hover .includeControls,
+.includeWrap:focus-within .includeControls,
+.includeWrap[data-focused="true"] .includeControls,
+.includeWrap[data-menu-open="true"] .includeControls {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+:global(.react-renderer.node-transclusionSource.ProseMirror-selectednode),
+:global(.react-renderer.node-transclusionReference.ProseMirror-selectednode) {
+  outline: none;
+}
+
+@media (max-width: 48em) {
+  .transclusionWrap,
+  .includeWrap {
+    margin-left: -1rem;
+    margin-right: -1rem;
+    width: calc(100% + 2rem);
+  }
+
+  .transclusionWrap {
+    padding-left: 1rem;
+    padding-right: 1rem;
+  }
+}
+
+@media print {
+  .transclusionControls,
+  .includeControls {
+    display: none !important;
+  }
+  .transclusionWrap,
+  .includeWrap {
+    border: none !important;
+    margin-left: 0 !important;
+    margin-right: 0 !important;
+    width: 100% !important;
+    padding: 0 !important;
+  }
+}
+
+.editingOriginalTag {
+  display: inline-block;
+  padding: 0 6px;
+  font-size: var(--mantine-font-size-xs);
+  font-weight: 500;
+  color: var(--mantine-color-blue-7);
+  background: light-dark(
+    var(--mantine-color-blue-0),
+    var(--mantine-color-blue-9)
+  );
+  border-radius: var(--mantine-radius-sm);
+}

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

@@ -0,0 +1,419 @@
+import { Extension } from "@tiptap/core";
+import {
+  NodeSelection,
+  Plugin,
+  PluginKey,
+  TextSelection,
+} from "@tiptap/pm/state";
+import { Fragment, Slice, Node } from "@tiptap/pm/model";
+import { EditorView } from "@tiptap/pm/view";
+
+export interface GlobalDragHandleOptions {
+  /**
+   * The width of the drag handle
+   */
+  dragHandleWidth: number;
+
+  /**
+   * The treshold for scrolling
+   */
+  scrollThreshold: number;
+
+  /*
+   * The css selector to query for the drag handle. (eg: '.custom-handle').
+   * If handle element is found, that element will be used as drag handle. If not, a default handle will be created
+   */
+  dragHandleSelector?: string;
+
+  /**
+   * Tags to be excluded for drag handle
+   */
+  excludedTags: string[];
+
+  /**
+   * Custom nodes to be included for drag handle
+   */
+  customNodes: string[];
+}
+function absoluteRect(node: Element) {
+  const data = node.getBoundingClientRect();
+  const modal = node.closest('[role="dialog"]');
+
+  if (modal && window.getComputedStyle(modal).transform !== "none") {
+    const modalRect = modal.getBoundingClientRect();
+
+    return {
+      top: data.top - modalRect.top,
+      left: data.left - modalRect.left,
+      width: data.width,
+    };
+  }
+  return {
+    top: data.top,
+    left: data.left,
+    width: data.width,
+  };
+}
+
+function nodeDOMAtCoords(
+  coords: { x: number; y: number },
+  options: GlobalDragHandleOptions,
+  view: EditorView,
+) {
+  const selectors = [
+    "li",
+    "p:not(:first-child)",
+    "pre",
+    "blockquote",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    ...options.customNodes.map((node) => `[data-type=${node}]`),
+  ].join(", ");
+  return document
+    .elementsFromPoint(coords.x, coords.y)
+    .find((elem: Element) => {
+      // Skip elements that belong to a nested editor (e.g. transclusion
+      // references render their own ProseMirror instance). Only consider
+      // elements whose closest editor is this host view.
+      if (elem.closest(".ProseMirror") !== view.dom) return false;
+      return (
+        elem.parentElement?.matches?.(".ProseMirror") ||
+        elem.matches(selectors)
+      );
+    });
+}
+function nodePosAtDOM(
+  node: Element,
+  view: EditorView,
+  options: GlobalDragHandleOptions,
+) {
+  const boundingRect = node.getBoundingClientRect();
+
+  return view.posAtCoords({
+    left: boundingRect.left + 50 + options.dragHandleWidth,
+    top: boundingRect.top + 1,
+  })?.inside;
+}
+
+function calcNodePos(pos: number, view: EditorView) {
+  const $pos = view.state.doc.resolve(pos);
+  if ($pos.depth > 1) return $pos.before($pos.depth);
+  return pos;
+}
+
+export function DragHandlePlugin(
+  options: GlobalDragHandleOptions & { pluginKey: string },
+) {
+  let listType = "";
+  function handleDragStart(event: DragEvent, view: EditorView) {
+    view.focus();
+
+    if (!event.dataTransfer) return;
+
+    const node = nodeDOMAtCoords(
+      {
+        x: event.clientX + 50 + options.dragHandleWidth,
+        y: event.clientY,
+      },
+      options,
+      view,
+    );
+
+    if (!(node instanceof Element)) return;
+
+    let draggedNodePos = nodePosAtDOM(node, view, options);
+    if (draggedNodePos == null || draggedNodePos < 0) return;
+    draggedNodePos = calcNodePos(draggedNodePos, view);
+
+    const { from, to } = view.state.selection;
+    const diff = from - to;
+
+    const fromSelectionPos = calcNodePos(from, view);
+    let differentNodeSelected = false;
+
+    const nodePos = view.state.doc.resolve(fromSelectionPos);
+
+    // Check if nodePos points to the top level node
+    if (nodePos.node().type.name === "doc") differentNodeSelected = true;
+    else {
+      const nodeSelection = NodeSelection.create(
+        view.state.doc,
+        nodePos.before(),
+      );
+
+      // Check if the node where the drag event started is part of the current selection
+      differentNodeSelected = !(
+        draggedNodePos + 1 >= nodeSelection.$from.pos &&
+        draggedNodePos <= nodeSelection.$to.pos
+      );
+    }
+    let selection = view.state.selection;
+    if (
+      !differentNodeSelected &&
+      diff !== 0 &&
+      !(view.state.selection instanceof NodeSelection)
+    ) {
+      const endSelection = NodeSelection.create(view.state.doc, to - 1);
+      selection = TextSelection.create(
+        view.state.doc,
+        draggedNodePos,
+        endSelection.$to.pos,
+      );
+    } else {
+      selection = NodeSelection.create(view.state.doc, draggedNodePos);
+
+      // if inline node is selected, e.g mention -> go to the parent node to select the whole node
+      // if table row is selected, go to the parent node to select the whole node
+      if (
+        (selection as NodeSelection).node.type.isInline ||
+        (selection as NodeSelection).node.type.name === "tableRow"
+      ) {
+        let $pos = view.state.doc.resolve(selection.from);
+        selection = NodeSelection.create(view.state.doc, $pos.before());
+      }
+    }
+    view.dispatch(view.state.tr.setSelection(selection));
+
+    // If the selected node is a list item, we need to save the type of the wrapping list e.g. OL or UL
+    if (
+      view.state.selection instanceof NodeSelection &&
+      view.state.selection.node.type.name === "listItem"
+    ) {
+      listType = node.parentElement!.tagName;
+    }
+
+    const slice = view.state.selection.content();
+    const { dom, text } = view.serializeForClipboard(slice);
+
+    event.dataTransfer.clearData();
+    event.dataTransfer.setData("text/html", dom.innerHTML);
+    event.dataTransfer.setData("text/plain", text);
+    event.dataTransfer.effectAllowed = "move";
+
+    event.dataTransfer.setDragImage(node, 0, 0);
+
+    view.dragging = { slice, move: event.ctrlKey };
+  }
+
+  let dragHandleElement: HTMLElement | null = null;
+
+  function hideDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.add("hide");
+    }
+  }
+
+  function showDragHandle() {
+    if (dragHandleElement) {
+      dragHandleElement.classList.remove("hide");
+    }
+  }
+
+  function hideHandleOnEditorOut(event: MouseEvent) {
+    if (event.target instanceof Element) {
+      // Check if the relatedTarget class is still inside the editor
+      const relatedTarget = event.relatedTarget as HTMLElement;
+      const isInsideEditor =
+        relatedTarget?.classList.contains("tiptap") ||
+        relatedTarget?.classList.contains("drag-handle");
+
+      if (isInsideEditor) return;
+    }
+    hideDragHandle();
+  }
+
+  return new Plugin({
+    key: new PluginKey(options.pluginKey),
+    view: (view) => {
+      const handleBySelector = options.dragHandleSelector
+        ? document.querySelector<HTMLElement>(options.dragHandleSelector)
+        : null;
+      dragHandleElement = handleBySelector ?? document.createElement("div");
+      dragHandleElement.draggable = true;
+      dragHandleElement.dataset.dragHandle = "";
+      dragHandleElement.classList.add("drag-handle");
+
+      function onDragHandleDragStart(e: DragEvent) {
+        handleDragStart(e, view);
+      }
+
+      dragHandleElement.addEventListener("dragstart", onDragHandleDragStart);
+
+      function onDragHandleDrag(e: DragEvent) {
+        hideDragHandle();
+        let scrollY = window.scrollY;
+        if (e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY - 30, behavior: "smooth" });
+        } else if (window.innerHeight - e.clientY < options.scrollThreshold) {
+          window.scrollTo({ top: scrollY + 30, behavior: "smooth" });
+        }
+      }
+
+      dragHandleElement.addEventListener("drag", onDragHandleDrag);
+
+      hideDragHandle();
+
+      if (!handleBySelector) {
+        view?.dom?.parentElement?.appendChild(dragHandleElement);
+      }
+      view?.dom?.parentElement?.addEventListener(
+        "mouseout",
+        hideHandleOnEditorOut,
+      );
+
+      return {
+        destroy: () => {
+          if (!handleBySelector) {
+            dragHandleElement?.remove?.();
+          }
+          dragHandleElement?.removeEventListener("drag", onDragHandleDrag);
+          dragHandleElement?.removeEventListener(
+            "dragstart",
+            onDragHandleDragStart,
+          );
+          dragHandleElement = null;
+          view?.dom?.parentElement?.removeEventListener(
+            "mouseout",
+            hideHandleOnEditorOut,
+          );
+        },
+      };
+    },
+    props: {
+      handleDOMEvents: {
+        mousemove: (view, event) => {
+          if (!view.editable) {
+            return;
+          }
+
+          const node = nodeDOMAtCoords(
+            {
+              x: event.clientX + 50 + options.dragHandleWidth,
+              y: event.clientY,
+            },
+            options,
+            view,
+          );
+
+          const notDragging = node?.closest(".not-draggable");
+          const excludedTagList = options.excludedTags
+            .concat(["ol", "ul"])
+            .join(", ");
+
+          if (
+            !(node instanceof Element) ||
+            node.matches(excludedTagList) ||
+            notDragging
+          ) {
+            hideDragHandle();
+            return;
+          }
+
+          const compStyle = window.getComputedStyle(node);
+          const parsedLineHeight = parseInt(compStyle.lineHeight, 10);
+          const lineHeight = isNaN(parsedLineHeight)
+            ? parseInt(compStyle.fontSize) * 1.2
+            : parsedLineHeight;
+          const paddingTop = parseInt(compStyle.paddingTop, 10);
+
+          const rect = absoluteRect(node);
+
+          rect.top += (lineHeight - 24) / 2;
+          rect.top += paddingTop;
+          // Li markers
+          if (node.matches("ul:not([data-type=taskList]) li, ol li")) {
+            rect.left -= options.dragHandleWidth;
+          }
+          rect.width = options.dragHandleWidth;
+
+          if (!dragHandleElement) return;
+
+          dragHandleElement.style.left = `${rect.left - rect.width}px`;
+          dragHandleElement.style.top = `${rect.top}px`;
+          showDragHandle();
+        },
+        keydown: () => {
+          hideDragHandle();
+        },
+        mousewheel: () => {
+          hideDragHandle();
+        },
+        // dragging class is used for CSS
+        dragstart: (view) => {
+          view.dom.classList.add("dragging");
+        },
+        drop: (view, event) => {
+          view.dom.classList.remove("dragging");
+          hideDragHandle();
+          let droppedNode: Node | null = null;
+          const dropPos = view.posAtCoords({
+            left: event.clientX,
+            top: event.clientY,
+          });
+
+          if (!dropPos) return;
+
+          if (view.state.selection instanceof NodeSelection) {
+            droppedNode = view.state.selection.node;
+          }
+          if (!droppedNode) return;
+
+          const resolvedPos = view.state.doc.resolve(dropPos.pos);
+
+          const isDroppedInsideList =
+            resolvedPos.parent.type.name === "listItem";
+
+          // If the selected node is a list item and is not dropped inside a list, we need to wrap it inside <ol> tag otherwise ol list items will be transformed into ul list item when dropped
+          if (
+            view.state.selection instanceof NodeSelection &&
+            view.state.selection.node.type.name === "listItem" &&
+            !isDroppedInsideList &&
+            listType == "OL"
+          ) {
+            const newList = view.state.schema.nodes.orderedList?.createAndFill(
+              null,
+              droppedNode,
+            );
+            const slice = new Slice(Fragment.from(newList), 0, 0);
+            view.dragging = { slice, move: event.ctrlKey };
+          }
+        },
+        dragend: (view) => {
+          view.dom.classList.remove("dragging");
+        },
+      },
+    },
+  });
+}
+
+const GlobalDragHandle = Extension.create({
+  name: "globalDragHandle",
+
+  addOptions() {
+    return {
+      dragHandleWidth: 20,
+      scrollThreshold: 100,
+      excludedTags: [],
+      customNodes: [],
+    };
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      DragHandlePlugin({
+        pluginKey: "globalDragHandle",
+        dragHandleWidth: this.options.dragHandleWidth,
+        scrollThreshold: this.options.scrollThreshold,
+        dragHandleSelector: this.options.dragHandleSelector,
+        excludedTags: this.options.excludedTags,
+        customNodes: this.options.customNodes,
+      }),
+    ];
+  },
+});
+
+export default GlobalDragHandle;

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

@@ -9,9 +9,10 @@ import SubScript from "@tiptap/extension-subscript";
 import { Typography } from "@tiptap/extension-typography";
 import { TextStyle } from "@tiptap/extension-text-style";
 import { Color } from "@tiptap/extension-color";
-import GlobalDragHandle from "tiptap-extension-global-drag-handle";
 import { Youtube } from "@tiptap/extension-youtube";
-import SlashCommand, { SlashCommandExtension as Command } from "@/features/editor/extensions/slash-command";
+import SlashCommand, {
+  SlashCommandExtension as Command,
+} from "@/features/editor/extensions/slash-command";
 import renderItems from "@/features/editor/components/slash-menu/render-items";
 import getSuggestionItems from "@/features/editor/components/slash-menu/menu-items";
 import { Collaboration, isChangeOrigin } from "@tiptap/extension-collaboration";
@@ -47,11 +48,14 @@ import {
   Subpages,
   Heading,
   Highlight,
+  Indent,
   UniqueID,
   SharedStorage,
   Columns,
   Column,
   Status,
+  TransclusionSource,
+  TransclusionReference,
 } from "@docmost/editor-ext";
 import {
   randomElement,
@@ -80,6 +84,8 @@ import ExcalidrawView from "@/features/editor/components/excalidraw/excalidraw-v
 import EmbedView from "@/features/editor/components/embed/embed-view.tsx";
 import PdfView from "@/features/editor/components/pdf/pdf-view.tsx";
 import SubpagesView from "@/features/editor/components/subpages/subpages-view.tsx";
+import TransclusionView from "@/features/editor/components/transclusion/transclusion-view.tsx";
+import TransclusionReferenceView from "@/features/editor/components/transclusion/transclusion-reference-view.tsx";
 import { common, createLowlight } from "lowlight";
 import plaintext from "highlight.js/lib/languages/plaintext";
 import powershell from "highlight.js/lib/languages/powershell";
@@ -100,6 +106,7 @@ import { MarkdownClipboard } from "@/features/editor/extensions/markdown-clipboa
 import EmojiCommand from "./emoji-command";
 import { countWords } from "alfaaz";
 import AutoJoiner from "@/features/editor/extensions/autojoiner.ts";
+import GlobalDragHandle from "@/features/editor/extensions/drag-handle.ts";
 
 const lowlight = createLowlight(common);
 lowlight.register("mermaid", plaintext);
@@ -167,7 +174,7 @@ export const mainExtensions = [
   SharedStorage,
   Heading,
   UniqueID.configure({
-    types: ["heading", "paragraph"],
+    types: ["heading", "paragraph", "transclusionSource"],
     filterTransaction: (transaction) => !isChangeOrigin(transaction),
   }),
   Placeholder.configure({
@@ -197,6 +204,7 @@ export const mainExtensions = [
     showOnlyWhenEditable: true,
   }),
   TextAlign.configure({ types: ["heading", "paragraph"] }),
+  Indent,
   TaskList,
   TaskItem.configure({
     nested: true,
@@ -215,7 +223,9 @@ export const mainExtensions = [
   }),
   Typography,
   TrailingNode,
-  GlobalDragHandle,
+  GlobalDragHandle.configure({
+    customNodes: ["transclusionSource", "transclusionReference"],
+  }),
   TextStyle,
   Color,
   SlashCommand,
@@ -305,6 +315,8 @@ export const mainExtensions = [
     view: CodeBlockView,
     //@ts-ignore
     lowlight,
+    enableTabIndentation: true,
+    tabSize: 2,
     HTMLAttributes: {
       spellcheck: false,
     },
@@ -351,6 +363,12 @@ export const mainExtensions = [
   Status.configure({
     view: StatusView,
   }),
+  TransclusionSource.configure({
+    view: TransclusionView,
+  }),
+  TransclusionReference.configure({
+    view: TransclusionReferenceView,
+  }),
   MarkdownClipboard.configure({
     transformPastedText: true,
   }),
@@ -393,7 +411,10 @@ const TEMPLATE_EXCLUDED_SLASH_ITEMS = new Set([
 const TemplateSlashCommand = Command.configure({
   suggestion: {
     items: ({ query }: { query: string }) =>
-      getSuggestionItems({ query, excludeItems: TEMPLATE_EXCLUDED_SLASH_ITEMS }),
+      getSuggestionItems({
+        query,
+        excludeItems: TEMPLATE_EXCLUDED_SLASH_ITEMS,
+      }),
     render: renderItems,
   },
 });

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

@@ -3,20 +3,27 @@ import React from "react";
 import { TitleEditor } from "@/features/editor/title-editor";
 import PageEditor from "@/features/editor/page-editor";
 import {
+  ActionIcon,
   Container,
   Divider,
   Group,
   Popover,
   Stack,
   Text,
+  Tooltip,
   UnstyledButton,
 } from "@mantine/core";
+import { IconInfoCircle } from "@tabler/icons-react";
 import { useAtom } from "jotai";
 import { userAtom } from "@/features/user/atoms/current-user-atom.ts";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
 import { PageVerificationBadge } from "@/ee/page-verification";
 import { useTranslation } from "react-i18next";
 import { IContributor } from "@/features/page/types/page.types.ts";
+import { FixedToolbar } from "@/features/editor/components/fixed-toolbar/fixed-toolbar";
+import { PageEditMode } from "@/features/user/types/user.types.ts";
+import useToggleAside from "@/hooks/use-toggle-aside.tsx";
+import clsx from "clsx";
 
 const MemoizedTitleEditor = React.memo(TitleEditor);
 const MemoizedPageEditor = React.memo(PageEditor);
@@ -52,6 +59,11 @@ export function FullEditor({
 }: FullEditorProps) {
   const [user] = useAtom(userAtom);
   const fullPageWidth = user.settings?.preferences?.fullPageWidth;
+  const editorToolbarEnabled =
+    user.settings?.preferences?.editorToolbar ?? false;
+  const userPageEditMode =
+    user.settings?.preferences?.pageEditMode ?? PageEditMode.Edit;
+  const isEditMode = userPageEditMode === PageEditMode.Edit;
 
   return (
     <Container
@@ -59,6 +71,7 @@ export function FullEditor({
       size={!fullPageWidth && 900}
       className={classes.editor}
     >
+      {editorToolbarEnabled && editable && isEditMode && <FixedToolbar />}
       <MemoizedTitleEditor
         pageId={pageId}
         slugId={slugId}
@@ -93,6 +106,7 @@ function PageByline({
   readOnly,
 }: PageBylineProps) {
   const { t } = useTranslation();
+  const toggleAside = useToggleAside();
 
   const otherContributors = (contributors ?? []).filter(
     (c) => c.id !== creator?.id,
@@ -102,8 +116,8 @@ function PageByline({
     <Group
       gap="sm"
       mb="md"
-      className="print-hide"
-      style={{ marginTop: "-0.5em", paddingLeft: "3rem" }}
+      className={clsx("print-hide", classes.byline)}
+      style={{ marginTop: "-0.5em" }}
     >
       {creator && (
         <Popover position="bottom-start" shadow="md" width={280} withArrow>
@@ -165,6 +179,17 @@ function PageByline({
           </Popover.Dropdown>
         </Popover>
       )}
+      <Tooltip label={t("Details")} withArrow openDelay={250}>
+        <ActionIcon
+          variant="subtle"
+          color="gray"
+          aria-label={t("Details")}
+          onClick={() => toggleAside("details")}
+        >
+          <IconInfoCircle size={20} stroke={1.5} />
+        </ActionIcon>
+      </Tooltip>
+
       <PageVerificationBadge readOnly={readOnly} />
     </Group>
   );

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

@@ -71,6 +71,7 @@ import { useEditorScroll } from "./hooks/use-editor-scroll";
 import { EditorAiMenu } from "@/ee/ai/components/editor/ai-menu/ai-menu";
 import { EditorLinkMenu } from "@/features/editor/components/link/link-menu";
 import ColumnsMenu from "@/features/editor/components/columns/columns-menu.tsx";
+import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";
 
 interface PageEditorProps {
   pageId: string;
@@ -399,55 +400,60 @@ export default function PageEditor({
     }
   }, [yjsConnectionStatus, isSynced]);
 
-  if (showStatic) {
-    return (
-      <EditorProvider
-        editable={false}
-        immediatelyRender={true}
-        extensions={mainExtensions}
-        content={content}
-      />
-    );
-  }
-
   return (
-    <div className="editor-container" style={{ position: "relative" }}>
-      <div ref={menuContainerRef}>
-        <EditorContent editor={editor} />
+    <TransclusionLookupProvider>
+      {showStatic ? (
+        <EditorProvider
+          editable={false}
+          immediatelyRender={true}
+          extensions={mainExtensions}
+          content={content}
+        />
+      ) : (
+        <div className="editor-container" style={{ position: "relative" }}>
+          <div ref={menuContainerRef}>
+            <EditorContent editor={editor} />
 
-        {editor && (
-          <SearchAndReplaceDialog editor={editor} editable={editable} />
-        )}
+            {editor && (
+              <SearchAndReplaceDialog editor={editor} editable={editable} />
+            )}
 
-        {editor && editorIsEditable && (
-          <div>
-            <EditorAiMenu editor={editor} />
-            <EditorLinkMenu editor={editor} />
-            <EditorBubbleMenu editor={editor} />
-            <TableMenu editor={editor} />
-            <TableCellMenu editor={editor} appendTo={menuContainerRef} />
-            <ImageMenu editor={editor} />
-            <VideoMenu editor={editor} />
-            <PdfMenu editor={editor} />
-            <CalloutMenu editor={editor} />
-            <SubpagesMenu editor={editor} />
-            <ExcalidrawMenu editor={editor} />
-            <DrawioMenu editor={editor} />
-            <ColumnsMenu editor={editor} />
+            {editor && editorIsEditable && (
+              <div>
+                <EditorAiMenu editor={editor} />
+                <EditorLinkMenu editor={editor} />
+                <EditorBubbleMenu editor={editor} />
+                <TableMenu editor={editor} />
+                <TableCellMenu editor={editor} appendTo={menuContainerRef} />
+                <ImageMenu editor={editor} />
+                <VideoMenu editor={editor} />
+                <PdfMenu editor={editor} />
+                <CalloutMenu editor={editor} />
+                <SubpagesMenu editor={editor} />
+                <ExcalidrawMenu editor={editor} />
+                <DrawioMenu editor={editor} />
+                <ColumnsMenu editor={editor} />
+              </div>
+            )}
+            {editor &&
+              !editorIsEditable &&
+              (editable || canComment) &&
+              providersRef.current && (
+                <ReadonlyBubbleMenu editor={editor} />
+              )}
+            {showCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} />
+            )}
+            {showReadOnlyCommentPopup && (
+              <CommentDialog editor={editor} pageId={pageId} readOnly />
+            )}
           </div>
-        )}
-        {editor && !editorIsEditable && (editable || canComment) && providersRef.current && (
-          <ReadonlyBubbleMenu editor={editor} />
-        )}
-        {showCommentPopup && <CommentDialog editor={editor} pageId={pageId} />}
-        {showReadOnlyCommentPopup && (
-          <CommentDialog editor={editor} pageId={pageId} readOnly />
-        )}
-      </div>
-      <div
-        onClick={() => editor.commands.focus("end")}
-        style={{ paddingBottom: "20vh" }}
-      ></div>
-    </div>
+          <div
+            onClick={() => editor.commands.focus("end")}
+            style={{ paddingBottom: "20vh" }}
+          ></div>
+        </div>
+      )}
+    </TransclusionLookupProvider>
   );
 }

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

@@ -9,17 +9,26 @@ import { Placeholder } from "@tiptap/extension-placeholder";
 import { useAtom } from "jotai";
 import { readOnlyEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
 import { useEditorScroll } from "./hooks/use-editor-scroll";
+import { TransclusionLookupProvider } from "@/features/editor/components/transclusion/transclusion-lookup-context";
 
 interface PageEditorProps {
   title: string;
   content: any;
   pageId?: string;
+  /**
+   * When rendering inside a public share, pass the share's id (or key). Lookups
+   * for transclusion content then resolve against the share graph instead of
+   * the viewer's personal permissions, so a share never leaks source content
+   * that isn't itself shared.
+   */
+  shareId?: string;
 }
 
 export default function ReadonlyPageEditor({
   title,
   content,
   pageId,
+  shareId,
 }: PageEditorProps) {
   const [, setReadOnlyEditor] = useAtom(readOnlyEditorAtom);
   const isComponentMounted = useRef(false);
@@ -65,7 +74,7 @@ export default function ReadonlyPageEditor({
   ];
 
   return (
-    <>
+    <TransclusionLookupProvider shareId={shareId}>
       <div className="page-title">
         <EditorProvider
           editable={false}
@@ -95,6 +104,6 @@ export default function ReadonlyPageEditor({
         }}
       ></EditorProvider>
       <div style={{ paddingBottom: "20vh" }}></div>
-    </>
+    </TransclusionLookupProvider>
   );
 }

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

@@ -9,3 +9,15 @@
     }
 }
 
+.byline {
+    padding-left: 3rem;
+
+    @media (max-width: $mantine-breakpoint-sm) {
+        padding-left: 1rem;
+    }
+
+    @media print {
+        padding-left: 0;
+    }
+}
+

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

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

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

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

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

@@ -16,7 +16,7 @@
 
 .subtitle {
   font-size: var(--mantine-font-size-sm);
-  color: light-dark(var(--mantine-color-gray-6), var(--mantine-color-dark-2));
+  color: var(--mantine-color-dimmed);
   text-align: center;
   margin-top: 6px;
   margin-bottom: var(--mantine-spacing-lg);

apps/client/src/features/label/components/label-chip.tsx

@@ -0,0 +1,51 @@
+import { Link } from "react-router-dom";
+import { useComputedColorScheme } from "@mantine/core";
+import { IconX } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { ILabel } from "@/features/label/types/label.types.ts";
+import { getLabelColor } from "@/features/label/utils/label-colors.ts";
+import classes from "@/features/label/label.module.css";
+
+type LabelChipProps = {
+  label: Pick<ILabel, "id" | "name">;
+  onRemove?: () => void;
+  asLink?: boolean;
+};
+
+export function LabelChip({ label, onRemove, asLink }: LabelChipProps) {
+  const { t } = useTranslation();
+  const scheme = useComputedColorScheme("light");
+  const c = getLabelColor(label.name, scheme);
+
+  const nameNode = asLink ? (
+    <Link
+      to={`/labels/${encodeURIComponent(label.name)}`}
+      className={classes.chipLink}
+      onClick={(e) => e.stopPropagation()}
+    >
+      <span className={classes.chipName}>{label.name}</span>
+    </Link>
+  ) : (
+    <span className={classes.chipName}>{label.name}</span>
+  );
+
+  return (
+    <span className={classes.chip} style={{ background: c.bg, color: c.fg }}>
+      {nameNode}
+      {onRemove && (
+        <button
+          type="button"
+          className={classes.chipX}
+          onClick={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            onRemove();
+          }}
+          aria-label={t("Remove label {{name}}", { name: label.name })}
+        >
+          <IconX size={12} stroke={2} />
+        </button>
+      )}
+    </span>
+  );
+}

apps/client/src/features/label/components/label-page-row-skeleton.tsx

@@ -0,0 +1,29 @@
+import { Skeleton } from "@mantine/core";
+import classes from "@/features/label/label.module.css";
+
+type LabelPageRowSkeletonProps = {
+  titleWidth?: number;
+  metaWidth?: number;
+};
+
+export function LabelPageRowSkeleton({
+  titleWidth = 220,
+  metaWidth = 180,
+}: LabelPageRowSkeletonProps) {
+  return (
+    <div className={classes.row} aria-hidden="true">
+      <div className={classes.rowMain}>
+        <div className={classes.rowIcon}>
+          <Skeleton height={18} width={18} radius="sm" />
+        </div>
+        <div className={classes.rowBody}>
+          <Skeleton height={15} width={titleWidth} radius="xs" />
+          <div className={classes.rowMeta}>
+            <Skeleton height={18} width={18} radius="sm" />
+            <Skeleton height={12} width={metaWidth} radius="xs" />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

apps/client/src/features/label/components/label-page-row.tsx

@@ -0,0 +1,91 @@
+import { Link } from "react-router-dom";
+import { ThemeIcon, Tooltip } from "@mantine/core";
+import { IconFileDescription } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { ILabelPageItem } from "@/features/label/types/label.types.ts";
+import { LabelChip } from "@/features/label/components/label-chip.tsx";
+import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import { AvatarIconType } from "@/features/attachments/types/attachment.types.ts";
+import { buildPageUrl } from "@/features/page/page.utils";
+import { formatLabelListDate } from "@/features/label/utils/format-label-date.ts";
+import classes from "@/features/label/label.module.css";
+
+type LabelPageRowProps = {
+  page: ILabelPageItem;
+  currentLabelName: string;
+};
+
+const MAX_VISIBLE_CHIPS = 3;
+
+export function LabelPageRow({ page, currentLabelName }: LabelPageRowProps) {
+  const { t } = useTranslation();
+
+  const otherLabels = page.labels.filter((l) => l.name !== currentLabelName);
+  const visibleLabels = otherLabels.slice(0, MAX_VISIBLE_CHIPS);
+  const hiddenLabels = otherLabels.slice(MAX_VISIBLE_CHIPS);
+
+  return (
+    <Link
+      to={buildPageUrl(page.space?.slug, page.slugId, page.title ?? undefined)}
+      className={classes.row}
+    >
+      <div className={classes.rowMain}>
+        <div className={classes.rowIcon}>
+          {page.icon ? (
+            <span style={{ fontSize: 16, lineHeight: 1 }}>{page.icon}</span>
+          ) : (
+            <ThemeIcon variant="transparent" color="gray" size={18}>
+              <IconFileDescription size={18} />
+            </ThemeIcon>
+          )}
+        </div>
+        <div className={classes.rowBody}>
+          <div className={classes.rowTitle}>
+            {page.title || t("Untitled")}
+          </div>
+          <div className={classes.rowMeta}>
+            {page.space && (
+              <>
+                <CustomAvatar
+                  name={page.space.name}
+                  avatarUrl={page.space.logo ?? undefined}
+                  type={AvatarIconType.SPACE_ICON}
+                  color="initials"
+                  variant="filled"
+                  size={18}
+                />
+                <span>{page.space.name}</span>
+                <span className={classes.metaDot} aria-hidden="true">
+                  •
+                </span>
+              </>
+            )}
+            <span className={classes.rowDate}>
+              {t("Updated {{date}}", {
+                date: formatLabelListDate(new Date(page.updatedAt)),
+              })}
+            </span>
+          </div>
+          {/* {otherLabels.length > 0 && (
+            <div className={classes.rowChips}>
+              {visibleLabels.map((label) => (
+                <LabelChip key={label.id} label={label} asLink />
+              ))}
+              {hiddenLabels.length > 0 && (
+                <Tooltip
+                  label={hiddenLabels.map((l) => l.name).join(", ")}
+                  withArrow
+                  openDelay={200}
+                >
+                  <span className={classes.chipMore}>
+                    +{hiddenLabels.length}
+                  </span>
+                </Tooltip>
+              )}
+            </div>
+          )} */}
+        </div>
+      </div>
+    </Link>
+  );
+}

apps/client/src/features/label/components/label-picker.tsx

@@ -0,0 +1,160 @@
+import { useMemo, useRef, useState, KeyboardEvent } from "react";
+import clsx from "clsx";
+import { IconPlus } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { useComputedColorScheme } from "@mantine/core";
+import { ILabel } from "@/features/label/types/label.types.ts";
+import { useWorkspaceLabelsQuery } from "@/features/label/queries/label-query.ts";
+import { getLabelColor } from "@/features/label/utils/label-colors.ts";
+import { normalizeLabelName } from "@/features/label/utils/normalize-label.ts";
+import classes from "@/features/label/label.module.css";
+
+type LabelPickerProps = {
+  applied: ILabel[];
+  enabled: boolean;
+  onAdd: (name: string) => void;
+  onClose: () => void;
+};
+
+const NAME_PATTERN = /^[a-z0-9_-][a-z0-9_~-]*$/;
+const MAX_LABEL_NAME_LENGTH = 100;
+
+function isValidLabelName(name: string): boolean {
+  return (
+    name.length > 0 &&
+    name.length <= MAX_LABEL_NAME_LENGTH &&
+    NAME_PATTERN.test(name)
+  );
+}
+
+export function LabelPicker({
+  applied,
+  enabled,
+  onAdd,
+  onClose,
+}: LabelPickerProps) {
+  const { t } = useTranslation();
+  const scheme = useComputedColorScheme("light");
+  const [query, setQuery] = useState("");
+  const [hover, setHover] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const normalized = normalizeLabelName(query);
+  const { data } = useWorkspaceLabelsQuery(normalized, enabled);
+
+  const appliedNames = useMemo(
+    () => new Set(applied.map((l) => l.name.toLowerCase())),
+    [applied],
+  );
+
+  const suggestions = useMemo(() => {
+    const items = data?.items ?? [];
+    return items.filter((l) => !appliedNames.has(l.name.toLowerCase()));
+  }, [data, appliedNames]);
+
+  const exact = suggestions.find((l) => l.name === normalized);
+  const canCreate =
+    !exact && !appliedNames.has(normalized) && isValidLabelName(normalized);
+
+  const total = suggestions.length + (canCreate ? 1 : 0);
+
+  const select = (idx: number) => {
+    if (idx < suggestions.length) {
+      onAdd(suggestions[idx].name);
+    } else if (canCreate) {
+      onAdd(normalized);
+    }
+    setQuery("");
+    setHover(0);
+    inputRef.current?.focus();
+  };
+
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setHover((h) => Math.min(Math.max(total - 1, 0), h + 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setHover((h) => Math.max(0, h - 1));
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      if (total === 0) return;
+      select(hover);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      onClose();
+    }
+  };
+
+  return (
+    <div className={classes.popover}>
+      <div className={classes.popoverSearch}>
+        <input
+          ref={inputRef}
+          type="text"
+          autoFocus
+          maxLength={MAX_LABEL_NAME_LENGTH}
+          placeholder={t("Search or create…")}
+          value={query}
+          onChange={(e) => {
+            setQuery(e.target.value);
+            setHover(0);
+          }}
+          onKeyDown={onKey}
+        />
+      </div>
+      <div className={classes.popoverList}>
+        {total === 0 && (
+          <div className={classes.popoverEmpty}>
+            {normalized.length === 0
+              ? t("No labels yet")
+              : appliedNames.has(normalized)
+                ? t("Already added")
+                : !isValidLabelName(normalized)
+                  ? t("Invalid label name")
+                  : t("No matches")}
+          </div>
+        )}
+        {suggestions.map((s, i) => {
+          const c = getLabelColor(s.name, scheme);
+          return (
+            <button
+              key={s.id}
+              type="button"
+              className={clsx(
+                classes.popoverItem,
+                hover === i && classes.popoverItemHover,
+              )}
+              onMouseEnter={() => setHover(i)}
+              onClick={() => select(i)}
+            >
+              <span
+                className={classes.popoverItemDot}
+                style={{ background: c.dot }}
+              />
+              <span className={classes.popoverItemName}>{s.name}</span>
+            </button>
+          );
+        })}
+        {canCreate && (
+          <button
+            type="button"
+            className={clsx(
+              classes.popoverItem,
+              hover === suggestions.length && classes.popoverItemHover,
+            )}
+            onMouseEnter={() => setHover(suggestions.length)}
+            onClick={() => select(suggestions.length)}
+          >
+            <span className={classes.popoverCreatePlus}>
+              <IconPlus size={12} stroke={2} />
+            </span>
+            <span className={classes.popoverItemName}>
+              {t("Create")} <b>"{normalized}"</b>
+            </span>
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

apps/client/src/features/label/components/labels-section.tsx

@@ -0,0 +1,93 @@
+import { useState } from "react";
+import clsx from "clsx";
+import { Divider, Popover, Stack, Text } from "@mantine/core";
+import { IconPlus } from "@tabler/icons-react";
+import { useTranslation } from "react-i18next";
+import { LabelChip } from "@/features/label/components/label-chip.tsx";
+import { LabelPicker } from "@/features/label/components/label-picker.tsx";
+import {
+  useAddLabelsMutation,
+  usePageLabelsQuery,
+  useRemoveLabelMutation,
+} from "@/features/label/queries/label-query.ts";
+import classes from "@/features/label/label.module.css";
+
+type LabelsSectionProps = {
+  pageId: string;
+  canEdit: boolean;
+};
+
+export function LabelsSection({ pageId, canEdit }: LabelsSectionProps) {
+  const { t } = useTranslation();
+  const [open, setOpen] = useState(false);
+
+  const { data } = usePageLabelsQuery(pageId);
+  const addMutation = useAddLabelsMutation(pageId);
+  const removeMutation = useRemoveLabelMutation(pageId);
+
+  const labels = data?.items ?? [];
+
+  if (!canEdit && labels.length === 0) {
+    return null;
+  }
+
+  const handleAdd = (name: string) => {
+    addMutation.mutate({ pageId, names: [name] });
+  };
+
+  const handleRemove = (labelId: string) => {
+    removeMutation.mutate({ pageId, labelId });
+  };
+
+  return (
+    <>
+      <Divider />
+      <Stack gap="xs">
+        <Text size="xs" fw={500} c="dimmed">
+          {t("Labels")}
+        </Text>
+        <div className={classes.labelsWrap}>
+          {labels.map((label) => (
+            <LabelChip
+              key={label.id}
+              label={label}
+              asLink
+              onRemove={canEdit ? () => handleRemove(label.id) : undefined}
+            />
+          ))}
+          {canEdit && (
+            <Popover
+              opened={open}
+              onChange={setOpen}
+              position="bottom-end"
+              shadow="lg"
+              withinPortal
+              offset={6}
+            >
+              <Popover.Target>
+                <button
+                  type="button"
+                  className={clsx(classes.addBtn, open && classes.addBtnOpen)}
+                  onClick={() => setOpen((v) => !v)}
+                >
+                  <IconPlus size={12} stroke={2} />
+                  <span>
+                    {labels.length === 0 ? t("Add label") : t("Add")}
+                  </span>
+                </button>
+              </Popover.Target>
+              <Popover.Dropdown p={0} className={classes.popover}>
+                <LabelPicker
+                  applied={labels}
+                  enabled={open}
+                  onAdd={(name) => handleAdd(name)}
+                  onClose={() => setOpen(false)}
+                />
+              </Popover.Dropdown>
+            </Popover>
+          )}
+        </div>
+      </Stack>
+    </>
+  );
+}

apps/client/src/features/label/label.module.css

@@ -0,0 +1,325 @@
+.labelsWrap {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: center;
+  margin-top: 4px;
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 24px;
+  padding: 0 8px;
+  border-radius: 4px;
+  font-size: 12.5px;
+  font-weight: 500;
+  line-height: 1;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.chipName {
+  letter-spacing: 0.005em;
+}
+
+.chipX {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  color: currentColor;
+  width: 18px;
+  height: 18px;
+  border-radius: 4px;
+  margin-right: -4px;
+  margin-left: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  padding: 0;
+  opacity: 0.6;
+}
+
+.chipX:hover {
+  opacity: 1;
+  background: light-dark(rgba(0, 0, 0, 0.08), rgba(255, 255, 255, 0.12));
+}
+
+.addBtn {
+  appearance: none;
+  border: 1px dashed
+    light-dark(var(--mantine-color-gray-4), var(--mantine-color-dark-3));
+  background: transparent;
+  color: var(--mantine-color-dimmed);
+  height: 24px;
+  padding: 0 8px;
+  border-radius: 4px;
+  font: inherit;
+  font-size: 12.5px;
+  font-weight: 500;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  cursor: pointer;
+  transition:
+    background 100ms ease,
+    border-color 100ms ease,
+    color 100ms ease;
+}
+
+.addBtn:hover {
+  background: light-dark(rgba(0, 0, 0, 0.03), rgba(255, 255, 255, 0.04));
+  color: var(--mantine-color-text);
+  border-color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+}
+
+.addBtnOpen {
+  background: var(--mantine-color-body);
+  border-style: solid;
+  border-color: light-dark(
+    var(--mantine-color-gray-5),
+    var(--mantine-color-dark-2)
+  );
+  color: var(--mantine-color-text);
+}
+
+.popover {
+  width: 240px;
+  padding: 0;
+  overflow: hidden;
+}
+
+.popoverSearch {
+  padding: 8px 8px 4px;
+  border-bottom: 1px solid
+    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-5));
+}
+
+.popoverSearch input {
+  width: 100%;
+  border: 0;
+  background: transparent;
+  font: inherit;
+  font-size: 13px;
+  padding: 4px 4px;
+  color: var(--mantine-color-text);
+  outline: none;
+}
+
+.popoverSearch input::placeholder {
+  color: var(--mantine-color-placeholder);
+}
+
+.popoverList {
+  max-height: 240px;
+  overflow-y: auto;
+  padding: 4px;
+}
+
+.popoverEmpty {
+  padding: 12px 8px;
+  color: var(--mantine-color-dimmed);
+  font-size: 12.5px;
+  text-align: center;
+}
+
+.popoverItem {
+  appearance: none;
+  width: 100%;
+  border: 0;
+  background: transparent;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  font: inherit;
+  font-size: 13px;
+  color: var(--mantine-color-text);
+  cursor: pointer;
+  text-align: left;
+}
+
+.popoverItemHover {
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+}
+
+.popoverItemDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.popoverItemName {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.popoverCreatePlus {
+  width: 14px;
+  height: 14px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--mantine-color-dimmed);
+}
+
+.headerChip {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  height: 36px;
+  padding: 0 14px;
+  border-radius: 8px;
+  font-size: 22px;
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: -0.005em;
+  text-decoration: none;
+  user-select: none;
+  transition: filter 100ms ease;
+}
+
+.headerChip:hover {
+  filter: brightness(0.97);
+}
+
+.headerDot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.row {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 14px 12px;
+  margin: 0 -12px;
+  border-radius: 8px;
+  text-decoration: none;
+  color: inherit;
+  cursor: pointer;
+  transition: background-color 80ms ease;
+}
+
+.row + .row {
+  border-top: 1px solid
+    light-dark(var(--mantine-color-gray-2), var(--mantine-color-dark-5));
+}
+
+.row:hover {
+  background-color: light-dark(
+    var(--mantine-color-gray-0),
+    var(--mantine-color-dark-6)
+  );
+}
+
+.row:hover + .row,
+.row:has(+ .row:hover) {
+  border-top-color: transparent;
+}
+
+.rowMain {
+  display: flex;
+  gap: 12px;
+  min-width: 0;
+  flex: 1;
+}
+
+.rowIcon {
+  width: 20px;
+  height: 20px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: var(--mantine-color-dimmed);
+  margin-top: 2px;
+}
+
+.rowBody {
+  min-width: 0;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.rowTitle {
+  font-size: 15px;
+  font-weight: 500;
+  color: var(--mantine-color-text);
+  line-height: 1.3;
+  word-break: break-word;
+}
+
+.rowChips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.chipMore {
+  display: inline-flex;
+  align-items: center;
+  height: 24px;
+  padding: 0 8px;
+  border-radius: 4px;
+  font-size: 12.5px;
+  font-weight: 500;
+  line-height: 1;
+  color: var(--mantine-color-dimmed);
+  background: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  user-select: none;
+  white-space: nowrap;
+}
+
+.rowMeta {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex-wrap: wrap;
+  color: var(--mantine-color-dimmed);
+  font-size: 13px;
+}
+
+.rowDate {
+  color: var(--mantine-color-dimmed);
+  font-size: 13px;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.metaDot {
+  font-size: 14px;
+  line-height: 1;
+  color: var(--mantine-color-dimmed);
+}
+
+.chipLink {
+  text-decoration: none;
+  color: inherit;
+  display: inline-flex;
+}
+
+.chipLink:hover {
+  filter: brightness(0.97);
+}

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

@@ -0,0 +1,157 @@
+import {
+  keepPreviousData,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+import {
+  addLabelsToPage,
+  findPagesByLabel,
+  getLabelInfo,
+  getPageLabels,
+  getWorkspaceLabels,
+  removeLabelFromPage,
+} from "@/features/label/services/label-service.ts";
+import {
+  IAddLabels,
+  ILabel,
+  IRemoveLabel,
+} from "@/features/label/types/label.types.ts";
+import { IPagination } from "@/lib/types.ts";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
+
+const PAGE_LABELS_KEY = (pageId: string) => ["page-labels", pageId];
+const WORKSPACE_LABELS_KEY = (query?: string) => ["workspace-labels", query ?? ""];
+
+export function usePageLabelsQuery(pageId: string | undefined) {
+  return useQuery({
+    queryKey: PAGE_LABELS_KEY(pageId ?? ""),
+    queryFn: () => getPageLabels({ pageId: pageId as string, limit: 100 }),
+    enabled: !!pageId,
+  });
+}
+
+export function useWorkspaceLabelsQuery(query: string, enabled: boolean) {
+  return useQuery({
+    queryKey: WORKSPACE_LABELS_KEY(query),
+    queryFn: () => getWorkspaceLabels({ type: "page", query, limit: 50 }),
+    enabled,
+    staleTime: 30 * 1000,
+  });
+}
+
+export function useAddLabelsMutation(pageId: string | undefined) {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<ILabel[], Error, IAddLabels>({
+    mutationFn: (data) => addLabelsToPage(data),
+    onSuccess: (added) => {
+      queryClient.setQueryData<IPagination<ILabel>>(
+        PAGE_LABELS_KEY(pageId ?? ""),
+        (cache) => {
+          if (!cache) return cache;
+          const existing = new Set(cache.items.map((l) => l.id));
+          const additions = added.filter((l) => !existing.has(l.id));
+          if (additions.length === 0) return cache;
+          return { ...cache, items: [...cache.items, ...additions] };
+        },
+      );
+
+      queryClient.setQueriesData<IPagination<ILabel>>(
+        { queryKey: ["workspace-labels"] },
+        (cache) => {
+          if (!cache) return cache;
+          const existing = new Set(cache.items.map((l) => l.id));
+          const additions = added.filter((l) => !existing.has(l.id));
+          if (additions.length === 0) return cache;
+          return {
+            ...cache,
+            items: [...cache.items, ...additions].sort((a, b) =>
+              a.name.localeCompare(b.name),
+            ),
+          };
+        },
+      );
+
+      queryClient.invalidateQueries({ queryKey: ["label-pages"] });
+      queryClient.invalidateQueries({ queryKey: ["label-info"] });
+    },
+    onError: (error: any) => {
+      notifications.show({
+        message: error?.response?.data?.message ?? t("Failed to add label"),
+        color: "red",
+      });
+    },
+  });
+}
+
+export function useRemoveLabelMutation(pageId: string | undefined) {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+
+  return useMutation<void, Error, IRemoveLabel>({
+    mutationFn: (data) => removeLabelFromPage(data),
+    onSuccess: (_data, variables) => {
+      const cache = queryClient.getQueryData<IPagination<ILabel>>(
+        PAGE_LABELS_KEY(pageId ?? ""),
+      );
+      if (cache) {
+        queryClient.setQueryData<IPagination<ILabel>>(
+          PAGE_LABELS_KEY(pageId ?? ""),
+          {
+            ...cache,
+            items: cache.items.filter((l) => l.id !== variables.labelId),
+          },
+        );
+      }
+      queryClient.invalidateQueries({ queryKey: ["workspace-labels"] });
+      queryClient.invalidateQueries({ queryKey: ["label-pages"] });
+      queryClient.invalidateQueries({ queryKey: ["label-info"] });
+    },
+    onError: () => {
+      notifications.show({
+        message: t("Failed to remove label"),
+        color: "red",
+      });
+    },
+  });
+}
+
+export function useLabelInfoQuery(name: string, spaceId?: string) {
+  return useQuery({
+    queryKey: ["label-info", name, spaceId ?? ""],
+    queryFn: () => getLabelInfo({ name, type: "page", spaceId }),
+    enabled: !!name,
+    placeholderData: keepPreviousData,
+  });
+}
+
+const LABEL_PAGES_LIMIT = 25;
+
+export function useLabelPagesQuery(
+  name: string,
+  query: string,
+  spaceId?: string,
+) {
+  return useInfiniteQuery({
+    queryKey: ["label-pages", name, query, spaceId ?? ""],
+    queryFn: ({ pageParam }) =>
+      findPagesByLabel({
+        name,
+        query,
+        spaceId,
+        cursor: pageParam,
+        limit: LABEL_PAGES_LIMIT,
+      }),
+    enabled: !!name,
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) =>
+      lastPage.meta.hasNextPage
+        ? (lastPage.meta.nextCursor ?? undefined)
+        : undefined,
+    placeholderData: keepPreviousData,
+  });
+}

apps/client/src/features/label/services/label-service.ts

@@ -0,0 +1,55 @@
+import api from "@/lib/api-client";
+import { IPagination } from "@/lib/types.ts";
+import {
+  IAddLabels,
+  IFindPagesByLabelParams,
+  ILabel,
+  ILabelInfo,
+  ILabelInfoParams,
+  ILabelPageItem,
+  IListLabelsParams,
+  IPageLabelsParams,
+  IRemoveLabel,
+} from "@/features/label/types/label.types.ts";
+
+export async function getPageLabels(
+  params: IPageLabelsParams,
+): Promise<IPagination<ILabel>> {
+  const req = await api.post<IPagination<ILabel>>("/pages/labels", params);
+  return req.data;
+}
+
+export async function getWorkspaceLabels(
+  params: IListLabelsParams,
+): Promise<IPagination<ILabel>> {
+  const req = await api.post<IPagination<ILabel>>("/labels", params);
+  return req.data;
+}
+
+export async function addLabelsToPage(
+  data: IAddLabels,
+): Promise<ILabel[]> {
+  const req = await api.post<ILabel[]>("/pages/labels/add", data);
+  return req.data;
+}
+
+export async function removeLabelFromPage(data: IRemoveLabel): Promise<void> {
+  await api.post("/pages/labels/remove", data);
+}
+
+export async function getLabelInfo(
+  params: ILabelInfoParams,
+): Promise<ILabelInfo> {
+  const req = await api.post<ILabelInfo>("/labels/info", params);
+  return req.data;
+}
+
+export async function findPagesByLabel(
+  params: IFindPagesByLabelParams,
+): Promise<IPagination<ILabelPageItem>> {
+  const req = await api.post<IPagination<ILabelPageItem>>(
+    "/labels/pages",
+    params,
+  );
+  return req.data;
+}

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

@@ -0,0 +1,70 @@
+import { QueryParams } from "@/lib/types.ts";
+
+export type LabelType = "page" | "space";
+
+export interface ILabel {
+  id: string;
+  name: string;
+  type: LabelType;
+  workspaceId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IAddLabels {
+  pageId: string;
+  names: string[];
+}
+
+export interface IRemoveLabel {
+  pageId: string;
+  labelId: string;
+}
+
+export interface IPageLabelsParams {
+  pageId: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface IListLabelsParams {
+  type: LabelType;
+  query?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ILabelInfo {
+  name: string;
+  usageCount: number;
+}
+
+export interface ILabelPageItem {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  createdAt: string;
+  updatedAt: string;
+  space: {
+    id: string;
+    name: string;
+    slug: string;
+    logo: string | null;
+  } | null;
+  creator: { id: string; name: string; avatarUrl: string | null } | null;
+  labels: { id: string; name: string }[];
+}
+
+export interface IFindPagesByLabelParams extends QueryParams {
+  labelId?: string;
+  name?: string;
+  spaceId?: string;
+}
+
+export interface ILabelInfoParams {
+  name: string;
+  type: LabelType;
+  spaceId?: string;
+}

apps/client/src/features/label/utils/format-label-date.ts

@@ -0,0 +1,15 @@
+import { format, isThisYear, isToday, isYesterday } from "date-fns";
+import i18n from "@/i18n.ts";
+
+export function formatLabelListDate(date: Date): string {
+  if (isToday(date)) {
+    return i18n.t("Today, {{time}}", { time: format(date, "h:mma") });
+  }
+  if (isYesterday(date)) {
+    return i18n.t("Yesterday, {{time}}", { time: format(date, "h:mma") });
+  }
+  if (isThisYear(date)) {
+    return format(date, "MMM dd");
+  }
+  return format(date, "MMM dd, yyyy");
+}

apps/client/src/features/label/utils/label-colors.ts

@@ -0,0 +1,55 @@
+type LabelColor = {
+  bg: string;
+  fg: string;
+  dot: string;
+};
+
+const LABEL_PALETTE: Record<string, LabelColor> = {
+  slate: { bg: "#eef1f5", fg: "#3b475a", dot: "#6b7a90" },
+  blue: { bg: "#e6f0ff", fg: "#1e4fbf", dot: "#3b82f6" },
+  green: { bg: "#e3f5ea", fg: "#1f7a47", dot: "#22a05a" },
+  amber: { bg: "#fbf0d9", fg: "#8a5a00", dot: "#d99c1f" },
+  red: { bg: "#fde6e6", fg: "#a02b2b", dot: "#dc4a4a" },
+  purple: { bg: "#efe9fb", fg: "#5a3aa8", dot: "#8b6bd9" },
+  pink: { bg: "#fce6ee", fg: "#a8336d", dot: "#dc6699" },
+  teal: { bg: "#daf1ee", fg: "#1f6f6a", dot: "#2fa39a" },
+};
+
+const PALETTE_KEYS = Object.keys(LABEL_PALETTE);
+
+const DARK_PALETTE: Record<string, LabelColor> = {
+  slate: { bg: "#2a3140", fg: "#c8d3e3", dot: "#7e8da8" },
+  blue: { bg: "#152a52", fg: "#a9c4ff", dot: "#5b9aff" },
+  green: { bg: "#143b27", fg: "#9ce3b8", dot: "#3ec97c" },
+  amber: { bg: "#3d2c0e", fg: "#f5cf85", dot: "#e6b34a" },
+  red: { bg: "#401a1a", fg: "#f1a8a8", dot: "#e26565" },
+  purple: { bg: "#2a1f4d", fg: "#c8b4f4", dot: "#a48ce6" },
+  pink: { bg: "#3c1a2a", fg: "#f3a9c9", dot: "#e07ab0" },
+  teal: { bg: "#103633", fg: "#92d5cf", dot: "#48b8af" },
+};
+
+function hashName(name: string): number {
+  // Per-char accumulation with 31. Note: 31 ≡ -1 (mod 8), so the low bits of
+  // this hash are highly correlated across short strings — `% 8` would cluster.
+  let h = 0;
+  for (let i = 0; i < name.length; i++) {
+    h = (Math.imul(h, 31) + name.charCodeAt(i)) | 0;
+  }
+  // Murmur3 fmix32 finalizer — avalanches high bits into low bits so the
+  // subsequent `% palette.length` (small power of two) is well-distributed.
+  h ^= h >>> 16;
+  h = Math.imul(h, 0x85ebca6b);
+  h ^= h >>> 13;
+  h = Math.imul(h, 0xc2b2ae35);
+  h ^= h >>> 16;
+  return h >>> 0;
+}
+
+export function getLabelColor(
+  name: string,
+  scheme: "light" | "dark" = "light",
+): LabelColor {
+  const key = PALETTE_KEYS[hashName(name) % PALETTE_KEYS.length];
+  const palette = scheme === "dark" ? DARK_PALETTE : LABEL_PALETTE;
+  return palette[key];
+}

apps/client/src/features/label/utils/normalize-label.ts

@@ -0,0 +1,3 @@
+export function normalizeLabelName(name: string): string {
+  return name.trim().replace(/\s+/g, "-").toLowerCase();
+}

apps/client/src/features/page-details/components/backlinks-list.tsx

@@ -0,0 +1,113 @@
+import {
+  Button,
+  Center,
+  Group,
+  Loader,
+  Stack,
+  Text,
+  UnstyledButton,
+} from "@mantine/core";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { useBacklinksQuery } from "@/features/page-details/queries/backlinks-query.ts";
+import {
+  BacklinkDirection,
+  IBacklinkPageItem,
+} from "@/features/page-details/types/backlink.types.ts";
+import { buildPageUrl } from "@/features/page/page.utils.ts";
+import { getPageIcon } from "@/lib";
+
+interface BacklinksListProps {
+  pageId: string;
+  direction: BacklinkDirection;
+  enabled: boolean;
+  onItemClick: () => void;
+}
+
+export function BacklinksList({
+  pageId,
+  direction,
+  enabled,
+  onItemClick,
+}: BacklinksListProps) {
+  const { t } = useTranslation();
+  const { data, isLoading, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    useBacklinksQuery(pageId, direction, enabled);
+
+  if (!enabled) return null;
+
+  if (isLoading) {
+    return (
+      <Center py="sm">
+        <Loader size="sm" />
+      </Center>
+    );
+  }
+
+  const items: IBacklinkPageItem[] =
+    data?.pages.flatMap((page) => page.items) ?? [];
+
+  if (items.length === 0) {
+    return (
+      <Text c="dimmed" size="sm" py="md">
+        {direction === "incoming"
+          ? t("No pages link here yet.")
+          : t("This page doesn't link to other pages yet.")}
+      </Text>
+    );
+  }
+
+  const handleClick = (e: React.MouseEvent) => {
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.button === 1) {
+      return;
+    }
+    onItemClick();
+  };
+
+  return (
+    <Stack gap={4}>
+      {items.map((item) => (
+        <UnstyledButton
+          key={item.id}
+          component={Link}
+          to={
+            item.space?.slug
+              ? buildPageUrl(
+                  item.space.slug,
+                  item.slugId,
+                  item.title ?? undefined,
+                )
+              : "#"
+          }
+          onClick={handleClick}
+          style={{ padding: "8px 4px", borderRadius: 4, userSelect: "none" }}
+        >
+          <Group gap="xs" wrap="nowrap">
+            {getPageIcon(item.icon ?? "")}
+            <Stack gap={0} style={{ flex: 1, minWidth: 0 }}>
+              <Text size="sm" fw={500} lineClamp={1}>
+                {item.title || t("Untitled")}
+              </Text>
+              {item.space?.name && (
+                <Text size="xs" c="dimmed" lineClamp={1}>
+                  {item.space.name}
+                </Text>
+              )}
+            </Stack>
+          </Group>
+        </UnstyledButton>
+      ))}
+      {hasNextPage && (
+        <Button
+          variant="subtle"
+          size="xs"
+          loading={isFetchingNextPage}
+          onClick={() => fetchNextPage()}
+          mt="xs"
+        >
+          {t("Load more")}
+        </Button>
+      )}
+    </Stack>
+  );
+}

apps/client/src/features/page-details/components/backlinks-modal.tsx

@@ -0,0 +1,62 @@
+import { Modal, Stack, Text } from "@mantine/core";
+import { useTranslation } from "react-i18next";
+import { useBacklinksCountQuery } from "@/features/page-details/queries/backlinks-query.ts";
+import { BacklinksList } from "./backlinks-list";
+
+interface BacklinksModalProps {
+  pageId: string;
+  opened: boolean;
+  onClose: () => void;
+}
+
+export function BacklinksModal({
+  pageId,
+  opened,
+  onClose,
+}: BacklinksModalProps) {
+  const { t } = useTranslation();
+  const { data: counts } = useBacklinksCountQuery(pageId);
+
+  return (
+    <Modal.Root opened={opened} onClose={onClose} size={640} yOffset="10vh">
+      <Modal.Overlay />
+      <Modal.Content>
+        <Modal.Header>
+          <Modal.Title fw={500}>{t("Backlinks")}</Modal.Title>
+          <Modal.CloseButton />
+        </Modal.Header>
+        <Modal.Body>
+          <Stack gap="lg">
+            <Stack gap="xs">
+              <Text size="sm" fw={500} c="dimmed">
+                {t("Incoming links ({{count}})", {
+                  count: counts?.incoming ?? 0,
+                })}
+              </Text>
+              <BacklinksList
+                pageId={pageId}
+                direction="incoming"
+                enabled={opened}
+                onItemClick={onClose}
+              />
+            </Stack>
+
+            <Stack gap="xs">
+              <Text size="sm" fw={500} c="dimmed">
+                {t("Outgoing links ({{count}})", {
+                  count: counts?.outgoing ?? 0,
+                })}
+              </Text>
+              <BacklinksList
+                pageId={pageId}
+                direction="outgoing"
+                enabled={opened}
+                onItemClick={onClose}
+              />
+            </Stack>
+          </Stack>
+        </Modal.Body>
+      </Modal.Content>
+    </Modal.Root>
+  );
+}

apps/client/src/features/page-details/components/page-details-aside.tsx

@@ -0,0 +1,239 @@
+import {
+  Divider,
+  Group,
+  Skeleton,
+  Stack,
+  Text,
+  UnstyledButton,
+} from "@mantine/core";
+import { IconChevronRight } from "@tabler/icons-react";
+import { useDisclosure } from "@mantine/hooks";
+import { useAtomValue } from "jotai";
+import { useParams } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { extractPageSlugId } from "@/lib";
+import { usePageQuery } from "@/features/page/queries/page-query.ts";
+import { pageEditorAtom } from "@/features/editor/atoms/editor-atoms.ts";
+import { useBacklinksCountQuery } from "@/features/page-details/queries/backlinks-query.ts";
+import { BacklinksModal } from "./backlinks-modal";
+import { formattedDate, timeAgo } from "@/lib/time.ts";
+import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
+import { LabelsSection } from "@/features/label/components/labels-section.tsx";
+
+export function PageDetailsAside() {
+  const { pageSlug } = useParams();
+  const { data: page } = usePageQuery({
+    pageId: extractPageSlugId(pageSlug),
+  });
+  const pageEditor = useAtomValue(pageEditorAtom);
+  const { data: counts, isLoading: countsLoading } = useBacklinksCountQuery(page?.id);
+  const [modalOpened, { open: openModal, close: closeModal }] =
+    useDisclosure(false);
+
+  if (!page) return null;
+
+  const wordCount: number =
+    pageEditor?.storage?.characterCount?.words?.() ?? 0;
+  const characterCount: number =
+    pageEditor?.storage?.characterCount?.characters?.() ?? 0;
+
+  return (
+    <>
+      <Stack gap="md">
+        <PeopleSection
+          creator={page.creator}
+          lastUpdatedBy={page.lastUpdatedBy}
+        />
+
+        <Divider />
+
+        <StatsSection
+          wordCount={wordCount}
+          characterCount={characterCount}
+          createdAt={page.createdAt}
+          updatedAt={page.updatedAt}
+        />
+
+        <Divider />
+
+        <BacklinksSection
+          incomingCount={counts?.incoming ?? 0}
+          outgoingCount={counts?.outgoing ?? 0}
+          isLoading={countsLoading}
+          onClick={openModal}
+        />
+
+        <LabelsSection
+          pageId={page.id}
+          canEdit={page.permissions?.canEdit ?? false}
+        />
+      </Stack>
+
+      <BacklinksModal
+        pageId={page.id}
+        opened={modalOpened}
+        onClose={closeModal}
+      />
+    </>
+  );
+}
+
+function PeopleSection({
+  creator,
+  lastUpdatedBy,
+}: {
+  creator: { id: string; name: string; avatarUrl: string } | null;
+  lastUpdatedBy: { id: string; name: string; avatarUrl: string } | null;
+}) {
+  const { t } = useTranslation();
+  return (
+    <Stack gap="xs">
+      <PersonRow label={t("Created by")} person={creator} />
+      <PersonRow label={t("Last updated by")} person={lastUpdatedBy} />
+    </Stack>
+  );
+}
+
+function PersonRow({
+  label,
+  person,
+}: {
+  label: string;
+  person: { id: string; name: string; avatarUrl: string } | null;
+}) {
+  return (
+    <Group justify="space-between" wrap="nowrap">
+      <Text size="sm" c="dimmed">
+        {label}
+      </Text>
+      {person ? (
+        <Group gap={6} wrap="nowrap">
+          <CustomAvatar
+            avatarUrl={person.avatarUrl}
+            name={person.name}
+            size={20}
+            radius="xl"
+          />
+          <Text size="sm" lineClamp={1}>
+            {person.name}
+          </Text>
+        </Group>
+      ) : (
+        <Text size="sm" c="dimmed">
+          —
+        </Text>
+      )}
+    </Group>
+  );
+}
+
+function StatsSection({
+  wordCount,
+  characterCount,
+  createdAt,
+  updatedAt,
+}: {
+  wordCount: number;
+  characterCount: number;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}) {
+  const { t } = useTranslation();
+  return (
+    <Stack gap="xs">
+      <Text size="xs" fw={500} c="dimmed">
+        {t("Stats")}
+      </Text>
+      <StatRow label={t("Word count")} value={String(wordCount)} />
+      <StatRow label={t("Characters")} value={String(characterCount)} />
+      <StatRow
+        label={t("Created")}
+        value={formattedDate(new Date(createdAt))}
+      />
+      <StatRow
+        label={t("Last updated")}
+        value={timeAgo(new Date(updatedAt))}
+      />
+    </Stack>
+  );
+}
+
+function StatRow({ label, value }: { label: string; value: string }) {
+  return (
+    <Group justify="space-between" wrap="nowrap">
+      <Text size="sm" c="dimmed">
+        {label}
+      </Text>
+      <Text size="sm">{value}</Text>
+    </Group>
+  );
+}
+
+function BacklinksSection({
+  incomingCount,
+  outgoingCount,
+  isLoading,
+  onClick,
+}: {
+  incomingCount: number;
+  outgoingCount: number;
+  isLoading: boolean;
+  onClick: () => void;
+}) {
+  const { t } = useTranslation();
+  return (
+    <Stack gap="xs">
+      <Text size="xs" fw={500} c="dimmed">
+        {t("Backlinks")}
+      </Text>
+      <BacklinksRow
+        label={t("Incoming links")}
+        count={incomingCount}
+        isLoading={isLoading}
+        onClick={onClick}
+      />
+      <BacklinksRow
+        label={t("Outgoing links")}
+        count={outgoingCount}
+        isLoading={isLoading}
+        onClick={onClick}
+      />
+    </Stack>
+  );
+}
+
+function BacklinksRow({
+  label,
+  count,
+  isLoading,
+  onClick,
+}: {
+  label: string;
+  count: number;
+  isLoading: boolean;
+  onClick: () => void;
+}) {
+  return (
+    <UnstyledButton
+      onClick={onClick}
+      style={{
+        padding: "4px 4px",
+        borderRadius: 4,
+      }}
+    >
+      <Group justify="space-between" wrap="nowrap">
+        <Text size="sm" c="dimmed">
+          {label}
+        </Text>
+        <Group gap={6} wrap="nowrap">
+          {isLoading ? (
+            <Skeleton height={18} width={20} />
+          ) : (
+            <Text size="sm">{count}</Text>
+          )}
+          <IconChevronRight size={16} stroke={2} color="var(--mantine-color-dimmed)" />
+        </Group>
+      </Group>
+    </UnstyledButton>
+  );
+}

apps/client/src/features/page-details/queries/backlinks-query.ts

@@ -0,0 +1,45 @@
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import {
+  getBacklinks,
+  getBacklinksCount,
+} from "@/features/page-details/services/backlinks-service.ts";
+import {
+  BacklinkDirection,
+  IBacklinkCount,
+} from "@/features/page-details/types/backlink.types.ts";
+
+const BACKLINKS_STALE_TIME = 30 * 1000;
+const BACKLINKS_PAGE_LIMIT = 100;
+
+export function useBacklinksCountQuery(pageId: string | undefined) {
+  return useQuery<IBacklinkCount>({
+    queryKey: ["backlinks-count", pageId],
+    queryFn: () => getBacklinksCount(pageId as string),
+    enabled: !!pageId,
+    staleTime: BACKLINKS_STALE_TIME,
+  });
+}
+
+export function useBacklinksQuery(
+  pageId: string | undefined,
+  direction: BacklinkDirection,
+  enabled: boolean,
+) {
+  return useInfiniteQuery({
+    queryKey: ["backlinks", pageId, direction],
+    queryFn: ({ pageParam }) =>
+      getBacklinks({
+        pageId: pageId as string,
+        direction,
+        cursor: pageParam,
+        limit: BACKLINKS_PAGE_LIMIT,
+      }),
+    enabled: enabled && !!pageId,
+    initialPageParam: undefined as string | undefined,
+    getNextPageParam: (lastPage) =>
+      lastPage.meta.hasNextPage
+        ? (lastPage.meta.nextCursor ?? undefined)
+        : undefined,
+    staleTime: BACKLINKS_STALE_TIME,
+  });
+}

apps/client/src/features/page-details/services/backlinks-service.ts

@@ -0,0 +1,26 @@
+import api from "@/lib/api-client";
+import { IPagination } from "@/lib/types.ts";
+import {
+  IBacklinkCount,
+  IBacklinkPageItem,
+  IBacklinksListParams,
+} from "@/features/page-details/types/backlink.types.ts";
+
+export async function getBacklinksCount(
+  pageId: string,
+): Promise<IBacklinkCount> {
+  const req = await api.post<IBacklinkCount>("/pages/backlinks-count", {
+    pageId,
+  });
+  return req.data;
+}
+
+export async function getBacklinks(
+  params: IBacklinksListParams,
+): Promise<IPagination<IBacklinkPageItem>> {
+  const req = await api.post<IPagination<IBacklinkPageItem>>(
+    "/pages/backlinks",
+    params,
+  );
+  return req.data;
+}

apps/client/src/features/page-details/types/backlink.types.ts

@@ -0,0 +1,23 @@
+export type BacklinkDirection = "incoming" | "outgoing";
+
+export interface IBacklinkCount {
+  incoming: number;
+  outgoing: number;
+}
+
+export interface IBacklinkPageItem {
+  id: string;
+  slugId: string;
+  title: string | null;
+  icon: string | null;
+  spaceId: string;
+  space: { id: string; slug: string; name: string } | null;
+  updatedAt: string;
+}
+
+export interface IBacklinksListParams {
+  pageId: string;
+  direction: BacklinkDirection;
+  cursor?: string;
+  limit?: number;
+}

apps/client/src/features/page/components/header/page-header-menu.tsx

@@ -29,7 +29,7 @@ import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { notifications } from "@mantine/notifications";
 import { getAppUrl } from "@/lib/config.ts";
 import { extractPageSlugId } from "@/lib";
-import { treeApiAtom } from "@/features/page/tree/atoms/tree-api-atom.ts";
+import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
 import { PageWidthToggle } from "@/features/user/components/page-width-pref.tsx";
 import { Trans, useTranslation } from "react-i18next";
@@ -134,7 +134,7 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
     pageId: extractPageSlugId(pageSlug),
   });
   const { openDeleteModal } = useDeletePageModal();
-  const [tree] = useAtom(treeApiAtom);
+  const { handleDelete } = useTreeMutation(page?.spaceId ?? "");
   const [exportOpened, { open: openExportModal, close: closeExportModal }] =
     useDisclosure(false);
   const [
@@ -183,7 +183,7 @@ function PageActionMenu({ readOnly }: PageActionMenuProps) {
   };
 
   const handleDeletePage = () => {
-    openDeleteModal({ onConfirm: () => tree?.delete(page.id) });
+    openDeleteModal({ onConfirm: () => handleDelete(page.id) });
   };
 
   const handleToggleFavorite = () => {

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

@@ -37,7 +37,7 @@ import { validate as isValidUuid } from "uuid";
 import { useTranslation } from "react-i18next";
 import { useAtom } from "jotai";
 import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom";
-import { SimpleTree } from "react-arborist";
+import { treeModel } from "@/features/page/tree/model/tree-model";
 import { SpaceTreeNode } from "@/features/page/tree/types";
 import { useQueryEmit } from "@/features/websocket/use-query-emit";
 
@@ -170,11 +170,8 @@ export function useRestorePageMutation() {
     onSuccess: async (restoredPage) => {
       notifications.show({ message: "Page restored successfully" });
 
-      // Add the restored page back to the tree
-      const treeApi = new SimpleTree<SpaceTreeNode>(treeData);
-
       // Check if the page already exists in the tree (it shouldn't)
-      if (!treeApi.find(restoredPage.id)) {
+      if (!treeModel.find(treeData, restoredPage.id)) {
         // Create the tree node data with hasChildren from backend
         const nodeData: SpaceTreeNode = {
           id: restoredPage.id,
@@ -193,24 +190,17 @@ export function useRestorePageMutation() {
         let index = 0;
 
         if (parentId) {
-          const parentNode = treeApi.find(parentId);
+          const parentNode = treeModel.find(treeData, parentId);
           if (parentNode) {
             index = parentNode.children?.length || 0;
           }
         } else {
           // Root level page
-          index = treeApi.data.length;
+          index = treeData.length;
         }
 
         // Add the node to the tree
-        treeApi.create({
-          parentId,
-          index,
-          data: nodeData,
-        });
-
-        // Update the tree data
-        setTreeData(treeApi.data);
+        setTreeData(treeModel.insert(treeData, parentId, nodeData, index));
 
         // Emit websocket event to sync with other users
         setTimeout(() => {

apps/client/src/features/page/tree/atoms/open-tree-nodes-atom.ts

@@ -0,0 +1,5 @@
+import { atom } from "jotai";
+
+export type OpenMap = Record<string, boolean>;
+
+export const openTreeNodesAtom = atom<OpenMap>({});

apps/client/src/features/page/tree/atoms/tree-api-atom.ts

@@ -1,5 +0,0 @@
-import { atom } from "jotai";
-import { TreeApi } from "react-arborist";
-import { SpaceTreeNode } from "../types";
-
-export const treeApiAtom = atom<TreeApi<SpaceTreeNode> | null>(null);

apps/client/src/features/page/tree/components/doc-tree-drag-preview.module.css

@@ -0,0 +1,26 @@
+.preview {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 10px;
+    border-radius: 6px;
+    font-size: 13px;
+    font-weight: 500;
+    background-color: light-dark(
+        var(--mantine-color-white),
+        var(--mantine-color-dark-6)
+    );
+    color: light-dark(
+        var(--mantine-color-gray-9),
+        var(--mantine-color-dark-0)
+    );
+    box-shadow: 0 4px 10px rgba(0, 0, 0, 0.18);
+    border: 1px solid light-dark(
+        var(--mantine-color-gray-3),
+        var(--mantine-color-dark-4)
+    );
+    max-width: 260px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}

apps/client/src/features/page/tree/components/doc-tree-drag-preview.tsx

@@ -0,0 +1,9 @@
+import styles from './doc-tree-drag-preview.module.css';
+
+type Props = {
+  label: string;
+};
+
+export function DocTreeDragPreview({ label }: Props) {
+  return <div className={styles.preview}>{label || 'Untitled'}</div>;
+}

apps/client/src/features/page/tree/components/doc-tree-drop-indicator.tsx

@@ -0,0 +1,39 @@
+import type { Instruction } from '@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item';
+import styles from '../styles/tree.module.css';
+
+type Props = {
+  instruction: Instruction;
+  indentPx: number;
+};
+
+export function DocTreeDropIndicator({ instruction, indentPx }: Props) {
+  const blocked = instruction.type === 'instruction-blocked';
+  const inst = blocked ? instruction.desired : instruction;
+
+  const style = {
+    ['--drop-line-indent' as never]: `${indentPx}px`,
+  } as React.CSSProperties;
+
+  if (inst.type === 'reorder-above') {
+    return (
+      <div
+        className={styles.dropLine}
+        data-edge="top"
+        data-blocked={blocked || undefined}
+        style={style}
+      />
+    );
+  }
+  if (inst.type === 'reorder-below') {
+    return (
+      <div
+        className={styles.dropLine}
+        data-edge="bottom"
+        data-blocked={blocked || undefined}
+        style={style}
+      />
+    );
+  }
+  // 'combine' (make-child) is rendered via [data-receiving-drop] on the row itself.
+  return null;
+}

apps/client/src/features/page/tree/components/doc-tree-row.tsx

@@ -0,0 +1,398 @@
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+import { createRoot } from 'react-dom/client';
+import { combine } from '@atlaskit/pragmatic-drag-and-drop/combine';
+import {
+  draggable,
+  dropTargetForElements,
+} from '@atlaskit/pragmatic-drag-and-drop/element/adapter';
+import { pointerOutsideOfPreview } from '@atlaskit/pragmatic-drag-and-drop/element/pointer-outside-of-preview';
+import { setCustomNativeDragPreview } from '@atlaskit/pragmatic-drag-and-drop/element/set-custom-native-drag-preview';
+import {
+  attachInstruction,
+  extractInstruction,
+  type Instruction,
+  type ItemMode,
+} from '@atlaskit/pragmatic-drag-and-drop-hitbox/tree-item';
+import { triggerPostMoveFlash } from '@atlaskit/pragmatic-drag-and-drop-flourish/trigger-post-move-flash';
+import * as liveRegion from '@atlaskit/pragmatic-drag-and-drop-live-region';
+
+import type { TreeNode, DropOp } from '../model/tree-model.types';
+import { treeModel } from '../model/tree-model';
+import { DocTreeDropIndicator } from './doc-tree-drop-indicator';
+import { DocTreeDragPreview } from './doc-tree-drag-preview';
+import type { RenderRowProps } from './doc-tree';
+import styles from '../styles/tree.module.css';
+
+type Props<T extends object> = {
+  node: TreeNode<T>;
+  level: number;
+  isLastSibling: boolean;
+  openIds: ReadonlySet<string>;
+  selectedId?: string;
+  // Roving tabindex: the single row that currently carries tabIndex={0}.
+  activeId?: string;
+  renderRow: (props: RenderRowProps<T>) => ReactNode;
+  indentPerLevel: number;
+  onMove: (sourceId: string, op: DropOp) => void | Promise<void>;
+  onToggle: (id: string, isOpen: boolean) => void;
+  readOnly: boolean;
+  disableDrag?: (node: TreeNode<T>) => boolean;
+  disableDrop?: (node: TreeNode<T>) => boolean;
+  getDragLabel: (node: TreeNode<T>) => string;
+  contextId: symbol;
+  registerRowElement: (id: string, el: HTMLElement | null) => void;
+  // Stable accessor — calling it returns the latest tree. Avoids passing the
+  // tree itself as a prop (which would break memo and re-run every row's DnD
+  // useEffect on every mutation).
+  getRootData: () => TreeNode<T>[];
+};
+
+const DRAG_TYPE = 'doc-tree-item';
+const AUTO_EXPAND_MS = 500;
+
+function DocTreeRowInner<T extends object>(props: Props<T>) {
+  const {
+    node,
+    level,
+    isLastSibling,
+    openIds,
+    selectedId,
+    activeId,
+    renderRow,
+    indentPerLevel,
+    onMove,
+    onToggle,
+    readOnly,
+    disableDrag,
+    disableDrop,
+    getDragLabel,
+    contextId,
+    registerRowElement,
+    getRootData,
+  } = props;
+
+  const isOpen = openIds.has(node.id);
+  // "Has children" includes both already-loaded children AND the consumer's
+  // own server-side flag (`hasChildren` is a docmost convention on
+  // SpaceTreeNode / SharedPageTreeNode). The flag lets the chevron and the
+  // auto-expand timer recognize unloaded subtrees so the consumer's lazy-load
+  // (via onToggle) can populate them on demand.
+  const hasLoadedChildren = !!node.children && node.children.length > 0;
+  const declaredHasChildren =
+    (node as { hasChildren?: boolean }).hasChildren === true;
+  const hasChildren = hasLoadedChildren || declaredHasChildren;
+  const isSelected = selectedId === node.id;
+
+  const rowRef = useRef<HTMLElement>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [instruction, setInstruction] = useState<Instruction | null>(null);
+  const autoExpandTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelAutoExpand = useCallback(() => {
+    if (autoExpandTimerRef.current) {
+      clearTimeout(autoExpandTimerRef.current);
+      autoExpandTimerRef.current = null;
+    }
+  }, []);
+
+  const toggleOpen = useCallback(() => {
+    onToggle(node.id, !isOpen);
+  }, [onToggle, node.id, isOpen]);
+
+  useEffect(() => {
+    registerRowElement(node.id, rowRef.current);
+    return () => registerRowElement(node.id, null);
+  }, [registerRowElement, node.id]);
+
+  // Restore lazy-loaded children when the row mounts open but its children
+  // aren't loaded (e.g. cross-space page move drops a node into a new tree
+  // that still has its id in openIds). Calling onToggle(id, true) is
+  // idempotent for open state and triggers the consumer's lazy-load.
+  useEffect(() => {
+    if (isOpen && declaredHasChildren && !hasLoadedChildren) {
+      onToggle(node.id, true);
+    }
+  }, [isOpen, declaredHasChildren, hasLoadedChildren, node.id, onToggle]);
+
+  useEffect(() => {
+    const el = rowRef.current;
+    if (!el || readOnly) return;
+    const dragDisabled = disableDrag?.(node) ?? false;
+    const dropDisabled = disableDrop?.(node) ?? false;
+
+    const cleanups: Array<() => void> = [];
+
+    if (!dragDisabled) {
+      cleanups.push(
+        draggable({
+          element: el,
+          getInitialData: () => ({
+            id: node.id,
+            type: DRAG_TYPE,
+            uniqueContextId: contextId,
+            isOpenOnDragStart: isOpen,
+          }),
+          onGenerateDragPreview: ({ nativeSetDragImage }) => {
+            setCustomNativeDragPreview({
+              nativeSetDragImage,
+              getOffset: pointerOutsideOfPreview({ x: '16px', y: '8px' }),
+              render: ({ container }) => {
+                const root = createRoot(container);
+                root.render(<DocTreeDragPreview label={getDragLabel(node)} />);
+                return () => root.unmount();
+              },
+            });
+          },
+          onDragStart: () => setIsDragging(true),
+          onDrop: () => setIsDragging(false),
+        }),
+      );
+    }
+
+    if (!dropDisabled) {
+      const mode: ItemMode =
+        isOpen && hasChildren
+          ? 'expanded'
+          : isLastSibling
+            ? 'last-in-group'
+            : 'standard';
+      // Always block 'reparent' (out of scope per spec).
+      // Block 'reorder-below' when the row is open with children — ambiguous gesture,
+      // force users to drop into the folder via 'make-child' instead.
+      const block: Instruction['type'][] = ['reparent'];
+      if (isOpen && hasChildren) block.push('reorder-below');
+
+      cleanups.push(
+        dropTargetForElements({
+          element: el,
+          canDrop: ({ source }) =>
+            source.data.type === DRAG_TYPE &&
+            source.data.uniqueContextId === contextId &&
+            source.data.id !== node.id &&
+            !treeModel.isDescendant(
+              getRootData(),
+              source.data.id as string,
+              node.id,
+            ),
+          getData: ({ input, element }) =>
+            attachInstruction(
+              { id: node.id, type: DRAG_TYPE },
+              {
+                input,
+                element,
+                currentLevel: level,
+                indentPerLevel,
+                mode,
+                block,
+              },
+            ),
+          onDrag: ({ self }) => {
+            const inst = extractInstruction(self.data);
+            setInstruction(inst);
+            // Auto-expand on hover over any collapsed row that has children,
+            // regardless of the specific instruction type. Reorder-before and
+            // reorder-after also benefit: once expanded, the user can see the
+            // children and refine their drop target.
+            if (
+              inst &&
+              hasChildren &&
+              !isOpen &&
+              !autoExpandTimerRef.current
+            ) {
+              autoExpandTimerRef.current = setTimeout(() => {
+                onToggle(node.id, true);
+                autoExpandTimerRef.current = null;
+              }, AUTO_EXPAND_MS);
+            }
+          },
+          onDragLeave: () => {
+            setInstruction(null);
+            cancelAutoExpand();
+          },
+          onDrop: ({ source, self }) => {
+            setInstruction(null);
+            cancelAutoExpand();
+            const inst = extractInstruction(self.data);
+            if (!inst || inst.type === 'instruction-blocked') return;
+            const sourceId = source.data.id as string;
+            const op: DropOp =
+              inst.type === 'reorder-above'
+                ? { kind: 'reorder-before', targetId: node.id }
+                : inst.type === 'reorder-below'
+                  ? { kind: 'reorder-after', targetId: node.id }
+                  : inst.type === 'make-child'
+                    ? { kind: 'make-child', targetId: node.id }
+                    : null!;
+            if (!op) return;
+            onMove(sourceId, op);
+            triggerPostMoveFlash(el);
+            const liveTree = getRootData();
+            const parentName =
+              op.kind === 'make-child'
+                ? getDragLabel(node)
+                : (() => {
+                    const sib = treeModel.siblingsOf(liveTree, op.targetId);
+                    const parent = sib?.parentId
+                      ? treeModel.find(liveTree, sib.parentId)
+                      : null;
+                    return parent ? getDragLabel(parent) : 'root';
+                  })();
+            const sourceNode = treeModel.find(liveTree, sourceId);
+            const sourceLabel = sourceNode
+              ? getDragLabel(sourceNode)
+              : 'item';
+            liveRegion.announce(`Moved ${sourceLabel} under ${parentName}.`);
+            // After a make-child drop, expand this row so the user sees the
+            // just-dropped child — especially important when the row had no
+            // children before (chevron just appeared) so the drop would
+            // otherwise be invisible.
+            if (op.kind === 'make-child') onToggle(node.id, true);
+            if (source.data.isOpenOnDragStart) onToggle(sourceId, true);
+          },
+        }),
+      );
+    }
+
+    return combine(...cleanups);
+  }, [
+    node,
+    level,
+    isOpen,
+    hasChildren,
+    isLastSibling,
+    readOnly,
+    disableDrag,
+    disableDrop,
+    contextId,
+    indentPerLevel,
+    getDragLabel,
+    onMove,
+    onToggle,
+    getRootData,
+    cancelAutoExpand,
+  ]);
+
+  useEffect(() => () => cancelAutoExpand(), [cancelAutoExpand]);
+
+  const effectiveInst =
+    instruction?.type === 'instruction-blocked'
+      ? instruction.desired
+      : instruction;
+  const blocked = instruction?.type === 'instruction-blocked';
+  const receivingDrop: 'before' | 'after' | 'make-child' | null = (() => {
+    if (!effectiveInst) return null;
+    if (effectiveInst.type === 'reorder-above') return 'before';
+    if (effectiveInst.type === 'reorder-below') return 'after';
+    if (effectiveInst.type === 'make-child') return 'make-child';
+    return null;
+  })();
+
+  // Treeitem semantics ride on the row's focusable element (the consumer's
+  // <a>). The outer <li> is presentational layout. aria-label uses the row's
+  // label so the SR's accessible name is just the page title, not the
+  // concatenation of inner action-button aria-labels.
+  const treeItemProps = {
+    role: 'treeitem' as const,
+    'aria-level': level + 1,
+    'aria-expanded': hasChildren ? isOpen : undefined,
+    'aria-selected': isSelected ? (true as const) : undefined,
+    'aria-current': isSelected ? ('page' as const) : undefined,
+    'aria-label': getDragLabel(node),
+    'data-row-id': node.id,
+  };
+
+  return (
+    <div
+      className={styles.rowWrapper}
+      style={{ paddingLeft: level * indentPerLevel }}
+    >
+      <div
+        className={styles.node}
+        data-dragging={isDragging || undefined}
+        data-selected={isSelected || undefined}
+        data-receiving-drop={
+          receivingDrop === 'make-child'
+            ? blocked
+              ? 'make-child-blocked'
+              : 'make-child'
+            : undefined
+        }
+      >
+        {renderRow({
+          node,
+          level,
+          isOpen,
+          hasChildren,
+          isSelected,
+          isDragging,
+          isReceivingDrop: receivingDrop,
+          rowRef,
+          tabIndex: activeId === node.id ? 0 : -1,
+          treeItemProps,
+          toggleOpen,
+        })}
+      </div>
+      {instruction && (
+        <DocTreeDropIndicator
+          instruction={instruction}
+          indentPx={level * indentPerLevel}
+        />
+      )}
+    </div>
+  );
+}
+
+// Custom memo comparator. The default shallow compare re-renders every row
+// when `openIds` (a Set) or `selectedId` (a string) on the parent changes,
+// because all rows receive the same reference via {...props} spread. With 1K
+// rows that's a perceptible stall on every expand and every navigate.
+//
+// Resolve openIds / selectedId per-row: only re-render if THIS row's own
+// open-state or selected-state actually flipped. Everything else uses
+// reference equality (callbacks are useCallback-stable from the parent).
+function arePropsEqual<T extends object>(
+  prev: Props<T>,
+  next: Props<T>,
+): boolean {
+  if (prev.node !== next.node) return false;
+  if (prev.level !== next.level) return false;
+  if (prev.isLastSibling !== next.isLastSibling) return false;
+  if (prev.readOnly !== next.readOnly) return false;
+  if (prev.contextId !== next.contextId) return false;
+  if (prev.indentPerLevel !== next.indentPerLevel) return false;
+  if (prev.renderRow !== next.renderRow) return false;
+  if (prev.onMove !== next.onMove) return false;
+  if (prev.onToggle !== next.onToggle) return false;
+  if (prev.disableDrag !== next.disableDrag) return false;
+  if (prev.disableDrop !== next.disableDrop) return false;
+  if (prev.getDragLabel !== next.getDragLabel) return false;
+  if (prev.registerRowElement !== next.registerRowElement) return false;
+  if (prev.getRootData !== next.getRootData) return false;
+
+  const id = next.node.id;
+  // openIds: only this row's own membership matters.
+  if (prev.openIds.has(id) !== next.openIds.has(id)) return false;
+  // selectedId: re-render only the rows whose isSelected actually flipped.
+  const wasSelected = prev.selectedId === id;
+  const isSelected = next.selectedId === id;
+  if (wasSelected !== isSelected) return false;
+  // activeId: same trick — only the outgoing and incoming active rows
+  // re-render when the user moves focus through the tree.
+  const wasActive = prev.activeId === id;
+  const isActive = next.activeId === id;
+  if (wasActive !== isActive) return false;
+
+  return true;
+}
+
+export const DocTreeRow = memo(
+  DocTreeRowInner,
+  arePropsEqual,
+) as typeof DocTreeRowInner;

apps/client/src/features/page/tree/components/doc-tree.tsx

@@ -0,0 +1,541 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+  type Ref,
+} from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { autoScrollForElements } from '@atlaskit/pragmatic-drag-and-drop-auto-scroll/element';
+import type { TreeNode, DropOp } from '../model/tree-model.types';
+import { treeModel } from '../model/tree-model';
+import { DocTreeRow } from './doc-tree-row';
+import styles from '../styles/tree.module.css';
+
+export type RenderRowProps<T extends object> = {
+  node: TreeNode<T>;
+  level: number;
+  isOpen: boolean;
+  hasChildren: boolean;
+  isSelected: boolean;
+  isDragging: boolean;
+  isReceivingDrop: 'before' | 'after' | 'make-child' | null;
+
+  rowRef: Ref<HTMLElement>;
+  // Roving tabindex: exactly one row in the tree carries tabIndex={0} (the
+  // active row); every other row gets tabIndex={-1}. Consumers must spread
+  // this onto the same element they wire rowRef to.
+  tabIndex: 0 | -1;
+  // Treeitem semantics for the row's focusable element. Consumers MUST spread
+  // these onto the same element rowRef points at, so the focused element IS
+  // the treeitem. This makes screen readers announce "treeitem" (not "link")
+  // and replaces the descendant-text accname with the row's label, so action
+  // button labels inside the row don't get concatenated.
+  treeItemProps: {
+    role: 'treeitem';
+    'aria-level': number;
+    'aria-expanded'?: boolean;
+    'aria-selected'?: true;
+    'aria-current'?: 'page';
+    'aria-label': string;
+    'data-row-id': string;
+  };
+  toggleOpen: () => void;
+};
+
+export type DocTreeProps<T extends object> = {
+  data: TreeNode<T>[];
+  openIds: ReadonlySet<string>;
+  selectedId?: string;
+
+  renderRow: (props: RenderRowProps<T>) => ReactNode;
+  indentPerLevel?: number;
+  rowHeight?: number;
+  emptyState?: ReactNode;
+
+  onMove: (sourceId: string, op: DropOp) => void | Promise<void>;
+  onToggle: (id: string, isOpen: boolean) => void;
+  onSelect?: (id: string) => void;
+
+  readOnly?: boolean;
+  disableDrag?: (node: TreeNode<T>) => boolean;
+  disableDrop?: (node: TreeNode<T>) => boolean;
+
+  getDragLabel: (node: TreeNode<T>) => string;
+  uniqueContextId?: symbol;
+
+  // Accessible name for the tree itself (e.g. "Pages"). Rendered as
+  // aria-label on the <ul role="tree"> so screen readers announce what
+  // collection of items the user has entered.
+  'aria-label'?: string;
+};
+
+export type DocTreeApi = {
+  select: (
+    id: string,
+    opts?: { scrollIntoView?: boolean; focus?: boolean },
+  ) => void;
+  scrollTo: (id: string) => void;
+  focus: (id: string) => void;
+};
+
+type FlatRow<T extends object> = {
+  node: TreeNode<T>;
+  level: number;
+  isLastSibling: boolean;
+};
+
+// DFS-walk the tree, emitting only the visible nodes (root nodes always, plus
+// the descendants of nodes whose id is in `openIds`). Each emitted row carries
+// the precomputed `level` and `isLastSibling` it needs.
+function flattenVisible<T extends object>(
+  data: TreeNode<T>[],
+  openIds: ReadonlySet<string>,
+): FlatRow<T>[] {
+  const out: FlatRow<T>[] = [];
+  const walk = (nodes: TreeNode<T>[], level: number) => {
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i];
+      out.push({ node, level, isLastSibling: i === nodes.length - 1 });
+      if (openIds.has(node.id) && node.children?.length) {
+        walk(node.children, level + 1);
+      }
+    }
+  };
+  walk(data, 0);
+  return out;
+}
+
+type RowElementMap = Map<string, HTMLElement>;
+
+function DocTreeInner<T extends object>(
+  props: DocTreeProps<T>,
+  ref: Ref<DocTreeApi>,
+) {
+  const {
+    data,
+    openIds,
+    selectedId,
+    renderRow,
+    indentPerLevel = 16,
+    rowHeight = 32,
+    onMove,
+    onToggle,
+    onSelect,
+    readOnly = false,
+    disableDrag,
+    disableDrop,
+    getDragLabel,
+    uniqueContextId,
+    emptyState,
+    'aria-label': ariaLabel,
+  } = props;
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const rowElementsRef = useRef<RowElementMap>(new Map());
+  // Set by the keyboard handler when the navigation target hasn't been
+  // virtualized yet. Consumed by registerRowElement when the row mounts.
+  const pendingFocusIdRef = useRef<string | null>(null);
+  // Typeahead state: accumulated buffer, plus the timer that clears it after
+  // ~500ms of no typing. Refs only — no re-render needed per keystroke.
+  const typeaheadBufferRef = useRef('');
+  const typeaheadTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Roving tabindex: the row most-recently focused by the user. Falls back
+  // to selectedId, then to the first visible row, when the tracked id is
+  // gone from the flat list (e.g. its branch was collapsed).
+  const [activeId, setActiveId] = useState<string | undefined>(undefined);
+  const contextId = useMemo(
+    () => uniqueContextId ?? Symbol('doc-tree'),
+    [uniqueContextId],
+  );
+
+  const registerRowElement = useCallback(
+    (id: string, el: HTMLElement | null) => {
+      if (el) {
+        rowElementsRef.current.set(id, el);
+        if (pendingFocusIdRef.current === id) {
+          pendingFocusIdRef.current = null;
+          // rAF lets the virtualizer settle layout/transform before focus,
+          // so the freshly-scrolled-in row is actually painted in view.
+          requestAnimationFrame(() => el.focus());
+        }
+      } else {
+        rowElementsRef.current.delete(id);
+      }
+    },
+    [],
+  );
+
+  // Stable live tree accessor — keeps the row useEffect deps stable across
+  // tree mutations.
+  const rootDataRef = useRef(data);
+  rootDataRef.current = data;
+  const getRootData = useCallback(() => rootDataRef.current, []);
+
+  // Flat visible list drives virtualization. Re-flattens on data or openIds
+  // change — cheap O(N) walk of the loaded tree.
+  const flat = useMemo(
+    () => flattenVisible(data, openIds),
+    [data, openIds],
+  );
+
+  // Membership lookup for the flat list. Used to validate activeId/selectedId
+  // before promoting them to the effective active row.
+  const flatIds = useMemo(() => new Set(flat.map((r) => r.node.id)), [flat]);
+
+  // Effective active row for tabindex purposes. Prefers user-focused row,
+  // then the currently selected page, then the first visible row. The user's
+  // arrow / Home / End / typeahead navigation updates activeId via the focus
+  // event delegated on the <ul>; explicit clicks also flow through focus.
+  const effectiveActiveId = useMemo(() => {
+    if (activeId && flatIds.has(activeId)) return activeId;
+    if (selectedId && flatIds.has(selectedId)) return selectedId;
+    return flat[0]?.node.id;
+  }, [activeId, selectedId, flatIds, flat]);
+
+  const virtualizer = useVirtualizer({
+    count: flat.length,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => rowHeight,
+    overscan: 10,
+  });
+
+  useImperativeHandle(
+    ref,
+    (): DocTreeApi => ({
+      select: (id, opts) => {
+        onSelect?.(id);
+        const idx = flat.findIndex((r) => r.node.id === id);
+        if (idx >= 0 && opts?.scrollIntoView) {
+          virtualizer.scrollToIndex(idx, { align: 'auto' });
+        }
+        if (opts?.focus) rowElementsRef.current.get(id)?.focus();
+      },
+      scrollTo: (id) => {
+        const idx = flat.findIndex((r) => r.node.id === id);
+        if (idx >= 0) virtualizer.scrollToIndex(idx, { align: 'auto' });
+      },
+      focus: (id) => {
+        rowElementsRef.current.get(id)?.focus();
+      },
+    }),
+    [onSelect, flat, virtualizer],
+  );
+
+  // Auto-scroll the container during drag so users can target rows currently
+  // scrolled off-screen. Scoped to drags originating in this DocTree instance
+  // via uniqueContextId.
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    return autoScrollForElements({
+      element: el,
+      canScroll: ({ source }) =>
+        source.data.uniqueContextId === contextId,
+    });
+  }, [contextId]);
+
+  // Scroll the selected row into view when it enters the flat list. If the
+  // row is already fully visible, leave the user's scroll position alone —
+  // only scroll when it's off-screen, and when we do, center it for context.
+  // Deep pages may not be in flat at the moment selectedId changes (ancestors
+  // still lazy-loading); the effect re-fires once flat contains the row.
+  // Guarded by a ref so subsequent flat changes don't fight manual scroll.
+  const lastScrolledIdRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!selectedId) {
+      lastScrolledIdRef.current = undefined;
+      return;
+    }
+    if (lastScrolledIdRef.current === selectedId) return;
+    const idx = flat.findIndex((r) => r.node.id === selectedId);
+    if (idx < 0) return;
+
+    const containerHeight = scrollRef.current?.clientHeight ?? 0;
+    const scrollOffset = virtualizer.scrollOffset ?? 0;
+    const item = virtualizer
+      .getVirtualItems()
+      .find((v) => v.index === idx);
+    const isFullyVisible =
+      !!item &&
+      item.start >= scrollOffset &&
+      item.start + item.size <= scrollOffset + containerHeight;
+
+    if (!isFullyVisible) {
+      virtualizer.scrollToIndex(idx, { align: 'center' });
+    }
+    lastScrolledIdRef.current = selectedId;
+  }, [selectedId, flat, virtualizer]);
+
+  // Keyboard navigation handler — single delegated listener on the <ul role="tree">.
+  // The focused row is identified by walking up the DOM to the nearest element
+  // carrying data-row-id, so this works whether the user has focused the row
+  // itself or one of its inner buttons (chevron, +). No per-row re-renders;
+  // focus is moved via .focus() on the registered element, with a pending-id
+  // hand-off when the target row is currently virtualized out of view.
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLUListElement>) => {
+      // Ctrl/Alt/Meta are reserved for browser/OS shortcuts; bail out.
+      // Shift is allowed through so typeahead can match capital letters.
+      if (e.altKey || e.ctrlKey || e.metaKey) return;
+      const isNavKey =
+        !e.shiftKey &&
+        (e.key === 'ArrowDown' ||
+          e.key === 'ArrowUp' ||
+          e.key === 'ArrowLeft' ||
+          e.key === 'ArrowRight' ||
+          e.key === 'Home' ||
+          e.key === 'End');
+      // Star expands all sibling subtrees of the focused row (WAI-ARIA tree
+      // pattern). Allowed with Shift since on most keyboards Shift+8 is how
+      // "*" is produced. Handled separately from typeahead.
+      const isStarKey = e.key === '*';
+      // Space activates the focused row — same effect as clicking it. Native
+      // <a> doesn't get this for free (only <button> does), so we wire it up
+      // explicitly to satisfy the WAI-ARIA tree pattern.
+      const isActivateKey = e.key === ' ';
+      // Single printable character → typeahead. e.key.length === 1 excludes
+      // multi-char names like "ArrowDown", "Enter", "Tab", etc.
+      const isTypeahead =
+        e.key.length === 1 && !isNavKey && !isStarKey && !isActivateKey;
+      if (!isNavKey && !isTypeahead && !isStarKey && !isActivateKey) return;
+
+      const target = e.target as HTMLElement;
+      if (target.matches('input, textarea, [contenteditable="true"]')) return;
+      const rowEl = target.closest('[data-row-id]');
+      if (!rowEl) return;
+      const id = rowEl.getAttribute('data-row-id');
+      if (!id) return;
+
+      const idx = flat.findIndex((r) => r.node.id === id);
+      if (idx < 0) return;
+
+      const focusByIndex = (targetIdx: number) => {
+        if (targetIdx < 0 || targetIdx >= flat.length) return;
+        const targetId = flat[targetIdx].node.id;
+        const existing = rowElementsRef.current.get(targetId);
+        if (existing) {
+          existing.focus();
+        } else {
+          pendingFocusIdRef.current = targetId;
+          virtualizer.scrollToIndex(targetIdx, { align: 'auto' });
+        }
+      };
+
+      // Space activates the focused row by synthesizing a click on the
+      // registered row element (its <a> Link). Skip if focus is on an inner
+      // button (chevron, +, menu) — those handle Space via native button
+      // semantics, and intercepting here would block their default behavior.
+      if (isActivateKey) {
+        const registered = rowElementsRef.current.get(id);
+        if (target === registered) {
+          e.preventDefault();
+          registered.click();
+        }
+        return;
+      }
+
+      // Typeahead: accumulate printable chars, jump to next row whose label
+      // starts with the buffer. Same-letter presses cycle through matches; a
+      // multi-char buffer searches from the current row so the user can
+      // refine the prefix. Buffer resets after ~500ms of no typing.
+      if (isTypeahead) {
+        e.preventDefault();
+        const wasEmpty = typeaheadBufferRef.current.length === 0;
+        typeaheadBufferRef.current = (
+          typeaheadBufferRef.current + e.key
+        ).toLowerCase();
+        const buffer = typeaheadBufferRef.current;
+        if (typeaheadTimerRef.current) {
+          clearTimeout(typeaheadTimerRef.current);
+        }
+        typeaheadTimerRef.current = setTimeout(() => {
+          typeaheadBufferRef.current = '';
+          typeaheadTimerRef.current = null;
+        }, 500);
+        // Single-char buffer cycles to the next match (start at idx + 1);
+        // multi-char buffer can keep matching the current row.
+        const startIdx = wasEmpty ? (idx + 1) % flat.length : idx;
+        for (let i = 0; i < flat.length; i++) {
+          const probeIdx = (startIdx + i) % flat.length;
+          const label = getDragLabel(flat[probeIdx].node).toLowerCase();
+          if (label.startsWith(buffer)) {
+            focusByIndex(probeIdx);
+            break;
+          }
+        }
+        return;
+      }
+
+      const row = flat[idx];
+      const hasChildren =
+        (row.node.children && row.node.children.length > 0) ||
+        (row.node as { hasChildren?: boolean }).hasChildren === true;
+      const isOpen = openIds.has(row.node.id);
+
+      // Asterisk: expand every sibling subtree at the focused row's level.
+      // Walks the authoritative tree (not flat, which only carries visible
+      // rows) so we also expand siblings whose own subtree is currently
+      // collapsed. Focus and selection stay put per the WAI-ARIA pattern.
+      if (isStarKey) {
+        e.preventDefault();
+        const info = treeModel.siblingsOf(rootDataRef.current, row.node.id);
+        if (info) {
+          for (const sib of info.siblings) {
+            const sibHasChildren =
+              (sib.children && sib.children.length > 0) ||
+              (sib as { hasChildren?: boolean }).hasChildren === true;
+            if (sibHasChildren && !openIds.has(sib.id)) {
+              onToggle(sib.id, true);
+            }
+          }
+        }
+        return;
+      }
+
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          focusByIndex(idx + 1);
+          break;
+        case 'ArrowUp':
+          e.preventDefault();
+          focusByIndex(idx - 1);
+          break;
+        case 'ArrowRight':
+          e.preventDefault();
+          if (hasChildren && !isOpen) {
+            onToggle(row.node.id, true);
+          } else if (
+            isOpen &&
+            row.node.children &&
+            row.node.children.length > 0
+          ) {
+            focusByIndex(idx + 1);
+          }
+          break;
+        case 'ArrowLeft': {
+          e.preventDefault();
+          if (isOpen && hasChildren) {
+            onToggle(row.node.id, false);
+          } else {
+            // Move to parent — first preceding row with smaller level.
+            // Bounded by sibling-count to parent in the flat list; tree depth
+            // and sibling counts are small in practice.
+            const currentLevel = row.level;
+            for (let i = idx - 1; i >= 0; i--) {
+              if (flat[i].level < currentLevel) {
+                focusByIndex(i);
+                break;
+              }
+            }
+          }
+          break;
+        }
+        case 'Home':
+          e.preventDefault();
+          focusByIndex(0);
+          break;
+        case 'End':
+          e.preventDefault();
+          focusByIndex(flat.length - 1);
+          break;
+      }
+    },
+    [flat, openIds, onToggle, virtualizer, getDragLabel],
+  );
+
+  // Clear the typeahead timer if the component unmounts mid-buffer.
+  useEffect(
+    () => () => {
+      if (typeaheadTimerRef.current) clearTimeout(typeaheadTimerRef.current);
+    },
+    [],
+  );
+
+  // Event-delegated focus tracking — when any descendant (a row's Link, or an
+  // inner action button) gains focus, mark the enclosing row as active. Keeps
+  // tabIndex aligned with the user's current position whether they got there
+  // by click, arrow nav, or focusByIndex's programmatic .focus() call.
+  const handleFocusIn = useCallback(
+    (e: React.FocusEvent<HTMLUListElement>) => {
+      const rowEl = (e.target as HTMLElement).closest('[data-row-id]');
+      const id = rowEl?.getAttribute('data-row-id');
+      if (id) setActiveId(id);
+    },
+    [],
+  );
+
+  if (data.length === 0 && emptyState) {
+    return <div className={styles.treeContainer}>{emptyState}</div>;
+  }
+
+  const virtualItems = virtualizer.getVirtualItems();
+  const totalSize = virtualizer.getTotalSize();
+
+  return (
+    <div ref={scrollRef} className={styles.treeContainer}>
+      <ul
+        role="tree"
+        aria-label={ariaLabel}
+        onKeyDown={handleKeyDown}
+        onFocus={handleFocusIn}
+        style={{
+          position: 'relative',
+          height: totalSize,
+          margin: 0,
+          padding: 0,
+          listStyle: 'none',
+        }}
+      >
+        {virtualItems.map((virtualItem) => {
+          const row = flat[virtualItem.index];
+          return (
+            <li
+              key={row.node.id}
+              // role="none" — the treeitem role lives on the focusable child
+              // (the row's <a>), so screen readers announce "treeitem" on
+              // navigation. The <li> is just layout glue.
+              role="none"
+              style={{
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                transform: `translateY(${virtualItem.start}px)`,
+              }}
+            >
+              <DocTreeRow
+                node={row.node}
+                level={row.level}
+                isLastSibling={row.isLastSibling}
+                openIds={openIds}
+                selectedId={selectedId}
+                activeId={effectiveActiveId}
+                renderRow={renderRow}
+                indentPerLevel={indentPerLevel}
+                onMove={onMove}
+                onToggle={onToggle}
+                readOnly={readOnly}
+                disableDrag={disableDrag}
+                disableDrop={disableDrop}
+                getDragLabel={getDragLabel}
+                contextId={contextId}
+                registerRowElement={registerRowElement}
+                getRootData={getRootData}
+              />
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
+
+export const DocTree = forwardRef(DocTreeInner) as <T extends object>(
+  props: DocTreeProps<T> & { ref?: Ref<DocTreeApi> },
+) => ReturnType<typeof DocTreeInner>;

apps/client/src/features/page/tree/components/space-tree-node-menu.tsx

@@ -0,0 +1,259 @@
+import { useAtom } from "jotai";
+import { useTranslation } from "react-i18next";
+import { useParams } from "react-router-dom";
+import { ActionIcon, Menu, rem } from "@mantine/core";
+import { useDisclosure } from "@mantine/hooks";
+import { notifications } from "@mantine/notifications";
+import {
+  IconArrowRight,
+  IconCopy,
+  IconDotsVertical,
+  IconFileExport,
+  IconLink,
+  IconStar,
+  IconStarFilled,
+  IconTrash,
+} from "@tabler/icons-react";
+
+import ExportModal from "@/components/common/export-modal";
+import MovePageModal from "@/features/page/components/move-page-modal.tsx";
+import CopyPageModal from "@/features/page/components/copy-page-modal.tsx";
+import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
+import { buildPageUrl } from "@/features/page/page.utils.ts";
+import { duplicatePage } from "@/features/page/services/page-service.ts";
+import { useClipboard } from "@/hooks/use-clipboard";
+import { getAppUrl } from "@/lib/config.ts";
+import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
+import {
+  useFavoriteIds,
+  useAddFavoriteMutation,
+  useRemoveFavoriteMutation,
+} from "@/features/favorite/queries/favorite-query";
+
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
+
+export interface NodeMenuProps {
+  node: SpaceTreeNode;
+  canEdit: boolean;
+}
+
+export function NodeMenu({ node, canEdit }: NodeMenuProps) {
+  const { t } = useTranslation();
+  const clipboard = useClipboard({ timeout: 500 });
+  const { spaceSlug } = useParams();
+  const { openDeleteModal } = useDeletePageModal();
+  const { handleDelete } = useTreeMutation(node.spaceId);
+  const [data, setData] = useAtom(treeDataAtom);
+  const emit = useQueryEmit();
+  const [exportOpened, { open: openExportModal, close: closeExportModal }] =
+    useDisclosure(false);
+  const [
+    movePageModalOpened,
+    { open: openMovePageModal, close: closeMoveSpaceModal },
+  ] = useDisclosure(false);
+  const [
+    copyPageModalOpened,
+    { open: openCopyPageModal, close: closeCopySpaceModal },
+  ] = useDisclosure(false);
+  const favoriteIds = useFavoriteIds("page", node.spaceId);
+  const addFavorite = useAddFavoriteMutation();
+  const removeFavorite = useRemoveFavoriteMutation();
+  const isFavorited = favoriteIds.has(node.id);
+
+  const handleCopyLink = () => {
+    const pageUrl =
+      getAppUrl() + buildPageUrl(spaceSlug, node.slugId, node.name);
+    clipboard.copy(pageUrl);
+    notifications.show({ message: t("Link copied") });
+  };
+
+  const handleDuplicatePage = async () => {
+    try {
+      const duplicatedPage = await duplicatePage({ pageId: node.id });
+
+      // figure out parent + insertion index
+      const siblings = treeModel.siblingsOf(data, node.id);
+      const parentId = siblings?.parentId ?? null;
+      const currentIndex = siblings?.index ?? 0;
+      const newIndex = currentIndex + 1;
+
+      const treeNodeData: SpaceTreeNode = {
+        id: duplicatedPage.id,
+        slugId: duplicatedPage.slugId,
+        name: duplicatedPage.title,
+        position: duplicatedPage.position,
+        spaceId: duplicatedPage.spaceId,
+        parentPageId: duplicatedPage.parentPageId,
+        icon: duplicatedPage.icon,
+        hasChildren: duplicatedPage.hasChildren,
+        canEdit: true,
+        children: [],
+      };
+
+      setData((prev) =>
+        treeModel.insert(prev, parentId, treeNodeData, newIndex),
+      );
+
+      setTimeout(() => {
+        emit({
+          operation: "addTreeNode",
+          spaceId: node.spaceId,
+          payload: {
+            parentId,
+            index: newIndex,
+            data: treeNodeData,
+          },
+        });
+      }, 50);
+
+      notifications.show({ message: t("Page duplicated successfully") });
+    } catch (err: any) {
+      notifications.show({
+        message: err?.response?.data?.message || "An error occurred",
+        color: "red",
+      });
+    }
+  };
+
+  return (
+    <>
+      <Menu shadow="md" width={200}>
+        <Menu.Target>
+          <ActionIcon
+            variant="transparent"
+            c="gray"
+            aria-label={t("Page menu")}
+            tabIndex={-1}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+            }}
+          >
+            <IconDotsVertical
+              style={{ width: rem(20), height: rem(20) }}
+              stroke={2}
+            />
+          </ActionIcon>
+        </Menu.Target>
+
+        <Menu.Dropdown>
+          <Menu.Item
+            leftSection={<IconLink size={16} />}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              handleCopyLink();
+            }}
+          >
+            {t("Copy link")}
+          </Menu.Item>
+
+          <Menu.Item
+            leftSection={
+              isFavorited ? <IconStarFilled size={16} /> : <IconStar size={16} />
+            }
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              if (isFavorited) {
+                removeFavorite.mutate({ type: "page", pageId: node.id });
+              } else {
+                addFavorite.mutate({ type: "page", pageId: node.id });
+              }
+            }}
+          >
+            {isFavorited ? t("Remove from favorites") : t("Add to favorites")}
+          </Menu.Item>
+
+          <Menu.Item
+            leftSection={<IconFileExport size={16} />}
+            onClick={(e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              openExportModal();
+            }}
+          >
+            {t("Export page")}
+          </Menu.Item>
+
+          {canEdit && (
+            <>
+              <Menu.Item
+                leftSection={<IconCopy size={16} />}
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  handleDuplicatePage();
+                }}
+              >
+                {t("Duplicate")}
+              </Menu.Item>
+
+              <Menu.Item
+                leftSection={<IconArrowRight size={16} />}
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  openMovePageModal();
+                }}
+              >
+                {t("Move")}
+              </Menu.Item>
+
+              <Menu.Item
+                leftSection={<IconCopy size={16} />}
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  openCopyPageModal();
+                }}
+              >
+                {t("Copy to space")}
+              </Menu.Item>
+
+              <Menu.Divider />
+              <Menu.Item
+                c="red"
+                leftSection={<IconTrash size={16} />}
+                onClick={(e) => {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  openDeleteModal({
+                    onConfirm: () => handleDelete(node.id),
+                  });
+                }}
+              >
+                {t("Move to trash")}
+              </Menu.Item>
+            </>
+          )}
+        </Menu.Dropdown>
+      </Menu>
+
+      <MovePageModal
+        pageId={node.id}
+        slugId={node.slugId}
+        currentSpaceSlug={spaceSlug}
+        onClose={closeMoveSpaceModal}
+        open={movePageModalOpened}
+      />
+
+      <CopyPageModal
+        pageId={node.id}
+        currentSpaceSlug={spaceSlug}
+        onClose={closeCopySpaceModal}
+        open={copyPageModalOpened}
+      />
+
+      <ExportModal
+        type="page"
+        id={node.id}
+        open={exportOpened}
+        onClose={closeExportModal}
+      />
+    </>
+  );
+}

apps/client/src/features/page/tree/components/space-tree-row.tsx

@@ -0,0 +1,288 @@
+import { useRef } from "react";
+import { Link, useParams } from "react-router-dom";
+import { useAtom } from "jotai";
+import { useTranslation } from "react-i18next";
+import { ActionIcon, rem } from "@mantine/core";
+import {
+  IconChevronDown,
+  IconChevronRight,
+  IconFileDescription,
+  IconPlus,
+  IconPointFilled,
+} from "@tabler/icons-react";
+
+import EmojiPicker from "@/components/ui/emoji-picker.tsx";
+import { queryClient } from "@/main.tsx";
+import { buildPageUrl } from "@/features/page/page.utils.ts";
+import { getPageById } from "@/features/page/services/page-service.ts";
+import {
+  useUpdatePageMutation,
+  fetchAllAncestorChildren,
+} from "@/features/page/queries/page-query.ts";
+import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
+import { mobileSidebarAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
+import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
+
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
+import type { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import type { RenderRowProps } from "./doc-tree";
+import { NodeMenu } from "./space-tree-node-menu";
+import classes from "@/features/page/tree/styles/tree.module.css";
+import { updateTreeNodeIcon } from "@/features/page/tree/utils/utils.ts";
+
+type SpaceTreeRowProps = RenderRowProps<SpaceTreeNode> & {
+  readOnly: boolean;
+};
+
+export function SpaceTreeRow({
+  node,
+  isOpen,
+  hasChildren,
+  toggleOpen,
+  rowRef,
+  tabIndex,
+  treeItemProps,
+  readOnly,
+}: SpaceTreeRowProps) {
+  const { t } = useTranslation();
+  const { spaceSlug } = useParams();
+  const updatePageMutation = useUpdatePageMutation();
+  const [, setTreeData] = useAtom(treeDataAtom);
+  const emit = useQueryEmit();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [mobileSidebarOpened] = useAtom(mobileSidebarAtom);
+  const toggleMobileSidebar = useToggleSidebar(mobileSidebarAtom);
+
+  const canEdit = !readOnly && node.canEdit !== false;
+  const pageUrl = buildPageUrl(spaceSlug, node.slugId, node.name);
+
+  const prefetchPage = () => {
+    timerRef.current = setTimeout(async () => {
+      const page = await queryClient.fetchQuery({
+        queryKey: ["pages", node.id],
+        queryFn: () => getPageById({ pageId: node.id }),
+        staleTime: 5 * 60 * 1000,
+      });
+      if (page?.slugId) {
+        queryClient.setQueryData(["pages", page.slugId], page);
+      }
+    }, 150);
+  };
+
+  const cancelPagePrefetch = () => {
+    if (timerRef.current) {
+      window.clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  };
+
+  const handleUpdateNodeIcon = (nodeId: string, newIcon: string | null) => {
+    setTreeData((prev) =>
+      updateTreeNodeIcon(prev, nodeId, newIcon),
+    );
+  };
+
+  const handleEmojiIconClick = (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+  };
+
+  const handleEmojiSelect = (emoji: { native: string }) => {
+    handleUpdateNodeIcon(node.id, emoji.native);
+    updatePageMutation
+      .mutateAsync({ pageId: node.id, icon: emoji.native })
+      .then((data) => {
+        setTimeout(() => {
+          emit({
+            operation: "updateOne",
+            spaceId: node.spaceId,
+            entity: ["pages"],
+            id: node.id,
+            payload: { icon: emoji.native, parentPageId: data.parentPageId },
+          });
+        }, 50);
+      });
+  };
+
+  const handleRemoveEmoji = () => {
+    handleUpdateNodeIcon(node.id, null);
+    updatePageMutation.mutateAsync({ pageId: node.id, icon: null });
+
+    setTimeout(() => {
+      emit({
+        operation: "updateOne",
+        spaceId: node.spaceId,
+        entity: ["pages"],
+        id: node.id,
+        payload: { icon: null },
+      });
+    }, 50);
+  };
+
+  const handleLoadChildren = async () => {
+    if (!node.hasChildren) return;
+    try {
+      const childrenTree = await fetchAllAncestorChildren({
+        pageId: node.id,
+        spaceId: node.spaceId,
+      });
+      setTreeData((prev) =>
+        treeModel.appendChildren(prev, node.id, childrenTree),
+      );
+    } catch (error) {
+      console.error("Failed to fetch children:", error);
+    }
+  };
+
+  return (
+    <Link
+      ref={rowRef as React.Ref<HTMLAnchorElement>}
+      to={pageUrl}
+      className={classes.node}
+      tabIndex={tabIndex}
+      {...treeItemProps}
+      onClick={() => {
+        if (mobileSidebarOpened) {
+          toggleMobileSidebar();
+        }
+      }}
+      onMouseEnter={prefetchPage}
+      onMouseLeave={cancelPagePrefetch}
+    >
+      <PageArrow
+        isOpen={isOpen}
+        hasChildren={hasChildren}
+        onToggle={toggleOpen}
+      />
+
+      <div onClick={handleEmojiIconClick} style={{ marginRight: "4px" }}>
+        <EmojiPicker
+          onEmojiSelect={handleEmojiSelect}
+          icon={
+            node.icon ? node.icon : <IconFileDescription size="18" />
+          }
+          readOnly={!canEdit}
+          removeEmojiAction={handleRemoveEmoji}
+          actionIconProps={{ tabIndex: -1 }}
+        />
+      </div>
+
+      <span className={classes.text}>{node.name || t("untitled")}</span>
+
+      <div className={classes.actions}>
+        <NodeMenu node={node} canEdit={canEdit} />
+
+        {canEdit && (
+          <CreateNode
+            node={node}
+            isOpen={isOpen}
+            hasChildren={hasChildren}
+            onToggle={toggleOpen}
+            onExpandTree={handleLoadChildren}
+          />
+        )}
+      </div>
+    </Link>
+  );
+}
+
+interface PageArrowProps {
+  isOpen: boolean;
+  hasChildren: boolean;
+  onToggle: () => void;
+}
+
+function PageArrow({ isOpen, hasChildren, onToggle }: PageArrowProps) {
+  const { t } = useTranslation();
+
+  if (!hasChildren) {
+    return (
+      <span
+        aria-hidden
+        style={{
+          width: 20,
+          height: 20,
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          color: "var(--mantine-color-gray-6)",
+          flexShrink: 0,
+        }}
+      >
+        <IconPointFilled size={8} />
+      </span>
+    );
+  }
+
+  return (
+    <ActionIcon
+      size={20}
+      variant="subtle"
+      c="gray"
+      aria-label={isOpen ? t("Collapse") : t("Expand")}
+      aria-expanded={isOpen}
+      tabIndex={-1}
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onToggle();
+      }}
+    >
+      {isOpen ? (
+        <IconChevronDown stroke={2} size={18} />
+      ) : (
+        <IconChevronRight stroke={2} size={18} />
+      )}
+    </ActionIcon>
+  );
+}
+
+interface CreateNodeProps {
+  node: SpaceTreeNode;
+  isOpen: boolean;
+  hasChildren: boolean;
+  onToggle: () => void;
+  onExpandTree: () => Promise<void> | void;
+}
+
+function CreateNode({
+  node,
+  isOpen,
+  hasChildren,
+  onToggle,
+  onExpandTree,
+}: CreateNodeProps) {
+  const { t } = useTranslation();
+  const { handleCreate } = useTreeMutation(node.spaceId);
+
+  async function handleClickCreate() {
+    if (node.hasChildren && !hasChildren) {
+      // Expand and lazy-load before creating a child. handleCreate reads the
+      // latest tree imperatively (via useStore) so we no longer need a
+      // setTimeout to wait for React to rerun the closure with fresh data.
+      if (!isOpen) onToggle();
+      await onExpandTree();
+    } else if (!isOpen) {
+      onToggle();
+    }
+    handleCreate(node.id);
+  }
+
+  return (
+    <ActionIcon
+      variant="transparent"
+      c="gray"
+      aria-label={t("Create page")}
+      tabIndex={-1}
+      onClick={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        handleClickCreate();
+      }}
+    >
+      <IconPlus style={{ width: rem(20), height: rem(20) }} stroke={2} />
+    </ActionIcon>
+  );
+}

apps/client/src/features/page/tree/components/space-tree.tsx

@@ -1,110 +1,47 @@
-import {
-  NodeApi,
-  NodeRendererProps,
-  Tree,
-  TreeApi,
-  SimpleTree,
-} from "react-arborist";
-import { atom, useAtom } from "jotai";
-import { treeApiAtom } from "@/features/page/tree/atoms/tree-api-atom.ts";
+import { useAtom } from "jotai";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useParams } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { Text } from "@mantine/core";
 import {
   fetchAllAncestorChildren,
   useGetRootSidebarPagesQuery,
   usePageQuery,
-  useUpdatePageMutation,
 } from "@/features/page/queries/page-query.ts";
-import { useEffect, useRef, useState } from "react";
-import { Link, useParams } from "react-router-dom";
 import classes from "@/features/page/tree/styles/tree.module.css";
-import { ActionIcon, Box, Menu, rem, Text } from "@mantine/core";
-import {
-  IconArrowRight,
-  IconChevronDown,
-  IconChevronRight,
-  IconCopy,
-  IconDotsVertical,
-  IconFileDescription,
-  IconFileExport,
-  IconLink,
-  IconPlus,
-  IconPointFilled,
-  IconStar,
-  IconStarFilled,
-  IconTrash,
-} from "@tabler/icons-react";
-import {
-  appendNodeChildrenAtom,
-  treeDataAtom,
-} from "@/features/page/tree/atoms/tree-data-atom.ts";
-import clsx from "clsx";
-import EmojiPicker from "@/components/ui/emoji-picker.tsx";
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { openTreeNodesAtom } from "@/features/page/tree/atoms/open-tree-nodes-atom.ts";
 import { useTreeMutation } from "@/features/page/tree/hooks/use-tree-mutation.ts";
 import {
-  appendNodeChildren,
   buildTree,
   buildTreeWithChildren,
   mergeRootTrees,
-  updateTreeNodeIcon,
 } from "@/features/page/tree/utils/utils.ts";
 import { SpaceTreeNode } from "@/features/page/tree/types.ts";
-import {
-  getPageBreadcrumbs,
-  getPageById,
-  getSidebarPages,
-} from "@/features/page/services/page-service.ts";
-import { IPage, SidebarPagesParams } from "@/features/page/types/page.types.ts";
-import { queryClient } from "@/main.tsx";
-import { OpenMap } from "react-arborist/dist/main/state/open-slice";
-import { useDisclosure, useElementSize, useMergedRef } from "@mantine/hooks";
-import { useClipboard } from "@/hooks/use-clipboard";
-import { dfs } from "react-arborist/dist/module/utils";
-import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
-import { buildPageUrl } from "@/features/page/page.utils.ts";
-import { notifications } from "@mantine/notifications";
-import { getAppUrl } from "@/lib/config.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import { getPageBreadcrumbs } from "@/features/page/services/page-service.ts";
+import { IPage } from "@/features/page/types/page.types.ts";
 import { extractPageSlugId } from "@/lib";
-import { useDeletePageModal } from "@/features/page/hooks/use-delete-page-modal.tsx";
-import { useTranslation } from "react-i18next";
-import ExportModal from "@/components/common/export-modal";
-import MovePageModal from "../../components/move-page-modal.tsx";
-import { mobileSidebarAtom } from "@/components/layouts/global/hooks/atoms/sidebar-atom.ts";
-import { useToggleSidebar } from "@/components/layouts/global/hooks/hooks/use-toggle-sidebar.ts";
-import CopyPageModal from "../../components/copy-page-modal.tsx";
-import { duplicatePage } from "../../services/page-service.ts";
-import { useFavoriteIds, useAddFavoriteMutation, useRemoveFavoriteMutation } from "@/features/favorite/queries/favorite-query";
+import { DocTree } from "./doc-tree";
+import { SpaceTreeRow } from "./space-tree-row";
 
 interface SpaceTreeProps {
   spaceId: string;
   readOnly: boolean;
 }
 
-const openTreeNodesAtom = atom<OpenMap>({});
-
 export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
   const { t } = useTranslation();
   const { pageSlug } = useParams();
-  const { data, setData, controllers } =
-    useTreeMutation<TreeApi<SpaceTreeNode>>(spaceId);
+  const [data, setData] = useAtom(treeDataAtom);
+  const { handleMove } = useTreeMutation(spaceId);
   const {
     data: pagesData,
     hasNextPage,
     fetchNextPage,
     isFetching,
-  } = useGetRootSidebarPagesQuery({
-    spaceId,
-  });
-  const [, setTreeApi] = useAtom<TreeApi<SpaceTreeNode>>(treeApiAtom);
-  const treeApiRef = useRef<TreeApi<SpaceTreeNode>>();
-  const [openTreeNodes, setOpenTreeNodes] = useAtom<OpenMap>(openTreeNodesAtom);
-  const rootElement = useRef<HTMLDivElement>();
-  const [isRootReady, setIsRootReady] = useState(false);
-  const { ref: sizeRef, width, height } = useElementSize();
-  const mergedRef = useMergedRef((element) => {
-    rootElement.current = element;
-    if (element && !isRootReady) {
-      setIsRootReady(true);
-    }
-  }, sizeRef);
+  } = useGetRootSidebarPagesQuery({ spaceId });
+  const [openTreeNodes, setOpenTreeNodes] = useAtom(openTreeNodesAtom);
   const [isDataLoaded, setIsDataLoaded] = useState(false);
   const spaceIdRef = useRef(spaceId);
   spaceIdRef.current = spaceId;
@@ -123,23 +60,24 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
   }, [hasNextPage, fetchNextPage, isFetching, spaceId]);
 
   useEffect(() => {
-    if (pagesData?.pages && !hasNextPage) {
-      const allItems = pagesData.pages.flatMap((page) => page.items);
-      const treeData = buildTree(allItems);
+    if (!pagesData?.pages || hasNextPage) return;
 
-      setData((prev) => {
-        // fresh space; full reset
-        if (prev.length === 0 || prev[0]?.spaceId !== spaceId) {
-          setIsDataLoaded(true);
-          setOpenTreeNodes({});
-          return treeData;
-        }
+    const allItems = pagesData.pages.flatMap((page) => page.items);
+    const treeData = buildTree(allItems);
 
-        // same space; append only missing roots
-        setIsDataLoaded(true);
-        return mergeRootTrees(prev, treeData);
-      });
-    }
+    setData((prev) => {
+      // Keep nodes belonging to other spaces — filteredData filters by spaceId
+      // for rendering, so accumulating is safe. Preserves lazy-loaded children
+      // and open-state when the user returns to a previously-visited space.
+      const otherSpaces = prev.filter((n) => n?.spaceId !== spaceId);
+      const currentSpace = prev.filter((n) => n?.spaceId === spaceId);
+      const refreshed =
+        currentSpace.length > 0
+          ? mergeRootTrees(currentSpace, treeData)
+          : treeData;
+      return [...otherSpaces, ...refreshed];
+    });
+    setIsDataLoaded(true);
   }, [pagesData, hasNextPage, spaceId]);
 
   useEffect(() => {
@@ -148,7 +86,7 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
     const fetchData = async () => {
       if (isDataLoaded && currentPage) {
         // check if pageId node is present in the tree
-        const node = dfs(treeApiRef.current?.root, currentPage.id);
+        const node = treeModel.find(data, currentPage.id);
         if (node) {
           // if node is found, no need to traverse its ancestors
           return;
@@ -160,14 +98,12 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
 
         if (spaceIdRef.current !== effectSpaceId) return;
 
-        if (ancestors && ancestors?.length > 1) {
+        if (ancestors && ancestors.length > 1) {
           let flatTreeItems = [...buildTree(ancestors)];
 
           const fetchAndUpdateChildren = async (ancestor: IPage) => {
             // we don't want to fetch the children of the opened page
-            if (ancestor.id === currentPage.id) {
-              return;
-            }
+            if (ancestor.id === currentPage.id) return;
             const children = await fetchAllAncestorChildren({
               pageId: ancestor.id,
               spaceId: ancestor.spaceId,
@@ -185,7 +121,6 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
             fetchAndUpdateChildren(ancestor),
           );
 
-          // Wait for all fetch operations to complete
           Promise.all(fetchPromises).then(() => {
             if (spaceIdRef.current !== effectSpaceId) return;
 
@@ -195,15 +130,24 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
             const rootChild = ancestorsTree[0];
 
             // attach built ancestors to tree using functional updater
-            // to avoid stale closure overwriting the current tree data
             setData((currentData) =>
-              appendNodeChildren(currentData, rootChild.id, rootChild.children),
+              treeModel.appendChildren(
+                currentData,
+                rootChild.id,
+                rootChild.children ?? [],
+              ),
             );
 
-            setTimeout(() => {
-              // focus on node and open all parents
-              treeApiRef.current?.select(currentPage.id);
-            }, 100);
+            // open all ancestors of the current page. DocTree picks up the
+            // selectedId change and scrolls the row into view on its own once
+            // flat contains it.
+            setOpenTreeNodes((prev) => {
+              const next = { ...prev };
+              for (const a of ancestors) {
+                if (a.id !== currentPage.id) next[a.id] = true;
+              }
+              return next;
+            });
           });
         }
       }
@@ -212,556 +156,76 @@ export default function SpaceTree({ spaceId, readOnly }: SpaceTreeProps) {
     fetchData();
   }, [isDataLoaded, currentPage?.id]);
 
-  useEffect(() => {
-    if (currentPage?.id) {
-      setTimeout(() => {
-        // focus on node and open all parents
-        treeApiRef.current?.select(currentPage.id, { align: "auto" });
-      }, 200);
-    } else {
-      treeApiRef.current?.deselectAll();
-    }
-  }, [currentPage?.id]);
+  const openIds = useMemo(
+    () => new Set(Object.keys(openTreeNodes).filter((k) => openTreeNodes[k])),
+    [openTreeNodes],
+  );
 
-  // Clean up tree API on unmount
-  useEffect(() => {
-    return () => {
-      // @ts-ignore
-      setTreeApi(null);
-    };
-  }, [setTreeApi]);
+  const handleToggle = useCallback(
+    async (id: string, isOpen: boolean) => {
+      setOpenTreeNodes((prev) => ({ ...prev, [id]: isOpen }));
+      if (isOpen) {
+        const node = treeModel.find(data, id) as SpaceTreeNode | null;
+        if (
+          node?.hasChildren &&
+          (!node.children || node.children.length === 0)
+        ) {
+          const fetched = await fetchAllAncestorChildren({
+            pageId: id,
+            spaceId: node.spaceId,
+          });
+          setData((prev) => treeModel.appendChildren(prev, id, fetched));
+        }
+      }
+    },
+    [data, setOpenTreeNodes, setData],
+  );
 
-  const filteredData = data.filter((node) => node?.spaceId === spaceId);
+  const filteredData = useMemo(
+    () => data.filter((node) => node?.spaceId === spaceId),
+    [data, spaceId],
+  );
+
+  // Stable callbacks for DocTree. Without these, every parent render recreates
+  // the props and tears down every row's draggable/dropTarget subscription,
+  // defeating memo(DocTreeRow).
+  const renderRow = useCallback(
+    (rowProps: Parameters<typeof SpaceTreeRow>[0]) => (
+      <SpaceTreeRow {...rowProps} readOnly={readOnly} />
+    ),
+    [readOnly],
+  );
+  const disableDragDrop = useCallback(
+    (n: SpaceTreeNode) => n.canEdit === false,
+    [],
+  );
+  const getDragLabel = useCallback(
+    (n: SpaceTreeNode) => n.name || t("untitled"),
+    [t],
+  );
 
   return (
-    <div ref={mergedRef} className={classes.treeContainer}>
+    <div className={classes.treeContainer}>
       {isDataLoaded && filteredData.length === 0 && (
         <Text size="xs" c="dimmed" py="xs" px="sm">
           {t("No pages yet")}
         </Text>
       )}
-      {isRootReady && rootElement.current && (
-        <Tree
+      {isDataLoaded && filteredData.length > 0 && (
+        <DocTree<SpaceTreeNode>
           data={filteredData}
-          disableDrag={
-            readOnly
-              ? true
-              : (data) => {
-                  return data.canEdit === false;
-                }
-          }
-          disableDrop={
-            readOnly
-              ? true
-              : ({ parentNode }) => parentNode?.data?.canEdit === false
-          }
-          disableEdit={readOnly ? true : (data) => data.canEdit === false}
-          {...controllers}
-          width={width}
-          height={rootElement.current.clientHeight}
-          ref={(ref) => {
-            treeApiRef.current = ref;
-            if (ref) {
-              //@ts-ignore
-              setTreeApi(ref);
-            }
-          }}
-          openByDefault={false}
-          disableMultiSelection={true}
-          className={classes.tree}
-          rowClassName={classes.row}
-          rowHeight={30}
-          overscanCount={10}
-          dndRootElement={rootElement.current}
-          onToggle={() => {
-            setOpenTreeNodes(treeApiRef.current?.openState);
-          }}
-          initialOpenState={openTreeNodes}
-        >
-          {Node}
-        </Tree>
+          openIds={openIds}
+          selectedId={currentPage?.id}
+          renderRow={renderRow}
+          onMove={handleMove}
+          onToggle={handleToggle}
+          readOnly={readOnly}
+          disableDrag={disableDragDrop}
+          disableDrop={disableDragDrop}
+          getDragLabel={getDragLabel}
+          aria-label={t("Pages")}
+        />
       )}
     </div>
   );
 }
-
-function Node({ node, style, dragHandle, tree }: NodeRendererProps<any>) {
-  const { t } = useTranslation();
-  const updatePageMutation = useUpdatePageMutation();
-  const [treeData, setTreeData] = useAtom(treeDataAtom);
-  const [, appendChildren] = useAtom(appendNodeChildrenAtom);
-  const emit = useQueryEmit();
-  const { spaceSlug } = useParams();
-  const timerRef = useRef(null);
-  const [mobileSidebarOpened] = useAtom(mobileSidebarAtom);
-  const toggleMobileSidebar = useToggleSidebar(mobileSidebarAtom);
-
-  const prefetchPage = () => {
-    timerRef.current = setTimeout(async () => {
-      const page = await queryClient.fetchQuery({
-        queryKey: ["pages", node.data.id],
-        queryFn: () => getPageById({ pageId: node.data.id }),
-        staleTime: 5 * 60 * 1000,
-      });
-      if (page?.slugId) {
-        queryClient.setQueryData(["pages", page.slugId], page);
-      }
-    }, 150);
-  };
-
-  const cancelPagePrefetch = () => {
-    if (timerRef.current) {
-      window.clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-  };
-
-  async function handleLoadChildren(node: NodeApi<SpaceTreeNode>) {
-    if (!node.data.hasChildren) return;
-    // in conflict with use-query-subscription.ts => case "addTreeNode","moveTreeNode" etc with websocket
-    // if (node.data.children && node.data.children.length > 0) {
-    //   return;
-    // }
-
-    try {
-      const params: SidebarPagesParams = {
-        pageId: node.data.id,
-        spaceId: node.data.spaceId,
-      };
-
-      const childrenTree = await fetchAllAncestorChildren(params);
-
-      appendChildren({
-        parentId: node.data.id,
-        children: childrenTree,
-      });
-    } catch (error) {
-      console.error("Failed to fetch children:", error);
-    }
-  }
-
-  const handleUpdateNodeIcon = (nodeId: string, newIcon: string) => {
-    const updatedTree = updateTreeNodeIcon(treeData, nodeId, newIcon);
-    setTreeData(updatedTree);
-  };
-
-  const handleEmojiIconClick = (e: any) => {
-    e.preventDefault();
-    e.stopPropagation();
-  };
-
-  const handleEmojiSelect = (emoji: { native: string }) => {
-    handleUpdateNodeIcon(node.id, emoji.native);
-    updatePageMutation
-      .mutateAsync({ pageId: node.id, icon: emoji.native })
-      .then((data) => {
-        setTimeout(() => {
-          emit({
-            operation: "updateOne",
-            spaceId: node.data.spaceId,
-            entity: ["pages"],
-            id: node.id,
-            payload: { icon: emoji.native, parentPageId: data.parentPageId },
-          });
-        }, 50);
-      });
-  };
-
-  const handleRemoveEmoji = () => {
-    handleUpdateNodeIcon(node.id, null);
-    updatePageMutation.mutateAsync({ pageId: node.id, icon: null });
-
-    setTimeout(() => {
-      emit({
-        operation: "updateOne",
-        spaceId: node.data.spaceId,
-        entity: ["pages"],
-        id: node.id,
-        payload: { icon: null },
-      });
-    }, 50);
-  };
-
-  if (
-    node.willReceiveDrop &&
-    node.isClosed &&
-    (node.children.length > 0 || node.data.hasChildren)
-  ) {
-    handleLoadChildren(node);
-    setTimeout(() => {
-      if (node.state.willReceiveDrop) {
-        node.open();
-      }
-    }, 650);
-  }
-
-  const pageUrl = buildPageUrl(spaceSlug, node.data.slugId, node.data.name);
-
-  return (
-    <>
-      <Box
-        style={style}
-        className={clsx(classes.node, node.state)}
-        component={Link}
-        to={pageUrl}
-        // @ts-ignore
-        ref={dragHandle}
-        onClick={() => {
-          if (mobileSidebarOpened) {
-            toggleMobileSidebar();
-          }
-        }}
-        onMouseEnter={prefetchPage}
-        onMouseLeave={cancelPagePrefetch}
-      >
-        <PageArrow node={node} onExpandTree={() => handleLoadChildren(node)} />
-
-        <div onClick={handleEmojiIconClick} style={{ marginRight: "4px" }}>
-          <EmojiPicker
-            onEmojiSelect={handleEmojiSelect}
-            icon={
-              node.data.icon ? (
-                node.data.icon
-              ) : (
-                <IconFileDescription size="18" />
-              )
-            }
-            readOnly={
-              tree.props.disableEdit === true || node.data.canEdit === false
-            }
-            removeEmojiAction={handleRemoveEmoji}
-          />
-        </div>
-
-        <span className={classes.text}>{node.data.name || t("untitled")}</span>
-
-        <div className={classes.actions}>
-          <NodeMenu node={node} treeApi={tree} spaceId={node.data.spaceId} />
-
-          {tree.props.disableEdit !== true && node.data.canEdit !== false && (
-            <CreateNode
-              node={node}
-              treeApi={tree}
-              onExpandTree={() => handleLoadChildren(node)}
-            />
-          )}
-        </div>
-      </Box>
-    </>
-  );
-}
-
-interface CreateNodeProps {
-  node: NodeApi<SpaceTreeNode>;
-  treeApi: TreeApi<SpaceTreeNode>;
-  onExpandTree?: () => void;
-}
-
-function CreateNode({ node, treeApi, onExpandTree }: CreateNodeProps) {
-  const { t } = useTranslation();
-
-  function handleCreate() {
-    if (node.data.hasChildren && node.children.length === 0) {
-      node.toggle();
-      onExpandTree();
-
-      setTimeout(() => {
-        treeApi?.create({ type: "internal", parentId: node.id, index: 0 });
-      }, 500);
-    } else {
-      treeApi?.create({ type: "internal", parentId: node.id });
-    }
-  }
-
-  return (
-    <ActionIcon
-      variant="transparent"
-      c="gray"
-      aria-label={t("Create page")}
-      onClick={(e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        handleCreate();
-      }}
-    >
-      <IconPlus style={{ width: rem(20), height: rem(20) }} stroke={2} />
-    </ActionIcon>
-  );
-}
-
-interface NodeMenuProps {
-  node: NodeApi<SpaceTreeNode>;
-  treeApi: TreeApi<SpaceTreeNode>;
-  spaceId: string;
-}
-
-function NodeMenu({ node, treeApi, spaceId }: NodeMenuProps) {
-  const { t } = useTranslation();
-  const clipboard = useClipboard({ timeout: 500 });
-  const { spaceSlug } = useParams();
-  const { openDeleteModal } = useDeletePageModal();
-  const [data, setData] = useAtom(treeDataAtom);
-  const emit = useQueryEmit();
-  const [exportOpened, { open: openExportModal, close: closeExportModal }] =
-    useDisclosure(false);
-  const [
-    movePageModalOpened,
-    { open: openMovePageModal, close: closeMoveSpaceModal },
-  ] = useDisclosure(false);
-  const [
-    copyPageModalOpened,
-    { open: openCopyPageModal, close: closeCopySpaceModal },
-  ] = useDisclosure(false);
-  const favoriteIds = useFavoriteIds("page", spaceId);
-  const addFavorite = useAddFavoriteMutation();
-  const removeFavorite = useRemoveFavoriteMutation();
-  const isFavorited = favoriteIds.has(node.data.id);
-
-  const handleCopyLink = () => {
-    const pageUrl =
-      getAppUrl() + buildPageUrl(spaceSlug, node.data.slugId, node.data.name);
-    clipboard.copy(pageUrl);
-    notifications.show({ message: t("Link copied") });
-  };
-
-  const handleDuplicatePage = async () => {
-    try {
-      const duplicatedPage = await duplicatePage({
-        pageId: node.id,
-      });
-
-      // Find the index of the current node
-      const parentId =
-        node.parent?.id === "__REACT_ARBORIST_INTERNAL_ROOT__"
-          ? null
-          : node.parent?.id;
-      const siblings = parentId ? node.parent.children : treeApi?.props.data;
-      const currentIndex =
-        siblings?.findIndex((sibling) => sibling.id === node.id) || 0;
-      const newIndex = currentIndex + 1;
-
-      // Add the duplicated page to the tree
-      const treeNodeData: SpaceTreeNode = {
-        id: duplicatedPage.id,
-        slugId: duplicatedPage.slugId,
-        name: duplicatedPage.title,
-        position: duplicatedPage.position,
-        spaceId: duplicatedPage.spaceId,
-        parentPageId: duplicatedPage.parentPageId,
-        icon: duplicatedPage.icon,
-        hasChildren: duplicatedPage.hasChildren,
-        canEdit: true,
-        children: [],
-      };
-
-      // Update local tree
-      const simpleTree = new SimpleTree(data);
-      simpleTree.create({
-        parentId,
-        index: newIndex,
-        data: treeNodeData,
-      });
-      setData(simpleTree.data);
-
-      // Emit socket event
-      setTimeout(() => {
-        emit({
-          operation: "addTreeNode",
-          spaceId: spaceId,
-          payload: {
-            parentId,
-            index: newIndex,
-            data: treeNodeData,
-          },
-        });
-      }, 50);
-
-      notifications.show({
-        message: t("Page duplicated successfully"),
-      });
-    } catch (err) {
-      notifications.show({
-        message: err.response?.data.message || "An error occurred",
-        color: "red",
-      });
-    }
-  };
-
-  return (
-    <>
-      <Menu shadow="md" width={200}>
-        <Menu.Target>
-          <ActionIcon
-            variant="transparent"
-            c="gray"
-            aria-label={t("Page menu")}
-            onClick={(e) => {
-              e.preventDefault();
-              e.stopPropagation();
-            }}
-          >
-            <IconDotsVertical
-              style={{ width: rem(20), height: rem(20) }}
-              stroke={2}
-            />
-          </ActionIcon>
-        </Menu.Target>
-
-        <Menu.Dropdown>
-          <Menu.Item
-            leftSection={<IconLink size={16} />}
-            onClick={(e) => {
-              e.preventDefault();
-              e.stopPropagation();
-              handleCopyLink();
-            }}
-          >
-            {t("Copy link")}
-          </Menu.Item>
-
-          <Menu.Item
-            leftSection={isFavorited ? <IconStarFilled size={16} /> : <IconStar size={16} />}
-            onClick={(e) => {
-              e.preventDefault();
-              e.stopPropagation();
-              if (isFavorited) {
-                removeFavorite.mutate({ type: "page", pageId: node.data.id });
-              } else {
-                addFavorite.mutate({ type: "page", pageId: node.data.id });
-              }
-            }}
-          >
-            {isFavorited ? t("Remove from favorites") : t("Add to favorites")}
-          </Menu.Item>
-
-          <Menu.Item
-            leftSection={<IconFileExport size={16} />}
-            onClick={(e) => {
-              e.preventDefault();
-              e.stopPropagation();
-              openExportModal();
-            }}
-          >
-            {t("Export page")}
-          </Menu.Item>
-
-          {treeApi.props.disableEdit !== true &&
-            node.data.canEdit !== false && (
-              <>
-                <Menu.Item
-                  leftSection={<IconCopy size={16} />}
-                  onClick={(e) => {
-                    e.preventDefault();
-                    e.stopPropagation();
-                    handleDuplicatePage();
-                  }}
-                >
-                  {t("Duplicate")}
-                </Menu.Item>
-
-                <Menu.Item
-                  leftSection={<IconArrowRight size={16} />}
-                  onClick={(e) => {
-                    e.preventDefault();
-                    e.stopPropagation();
-                    openMovePageModal();
-                  }}
-                >
-                  {t("Move")}
-                </Menu.Item>
-
-                <Menu.Item
-                  leftSection={<IconCopy size={16} />}
-                  onClick={(e) => {
-                    e.preventDefault();
-                    e.stopPropagation();
-                    openCopyPageModal();
-                  }}
-                >
-                  {t("Copy to space")}
-                </Menu.Item>
-
-                <Menu.Divider />
-                <Menu.Item
-                  c="red"
-                  leftSection={<IconTrash size={16} />}
-                  onClick={(e) => {
-                    e.preventDefault();
-                    e.stopPropagation();
-                    openDeleteModal({ onConfirm: () => treeApi?.delete(node) });
-                  }}
-                >
-                  {t("Move to trash")}
-                </Menu.Item>
-              </>
-            )}
-        </Menu.Dropdown>
-      </Menu>
-
-      <MovePageModal
-        pageId={node.id}
-        slugId={node.data.slugId}
-        currentSpaceSlug={spaceSlug}
-        onClose={closeMoveSpaceModal}
-        open={movePageModalOpened}
-      />
-
-      <CopyPageModal
-        pageId={node.id}
-        currentSpaceSlug={spaceSlug}
-        onClose={closeCopySpaceModal}
-        open={copyPageModalOpened}
-      />
-
-      <ExportModal
-        type="page"
-        id={node.id}
-        open={exportOpened}
-        onClose={closeExportModal}
-      />
-    </>
-  );
-}
-
-interface PageArrowProps {
-  node: NodeApi<SpaceTreeNode>;
-  onExpandTree?: () => void;
-}
-
-function PageArrow({ node, onExpandTree }: PageArrowProps) {
-  const { t } = useTranslation();
-
-  useEffect(() => {
-    if (node.isOpen) {
-      onExpandTree();
-    }
-  }, []);
-
-  return (
-    <ActionIcon
-      size={20}
-      variant="subtle"
-      c="gray"
-      aria-label={node.isOpen ? t("Collapse") : t("Expand")}
-      aria-expanded={node.isInternal ? node.isOpen : undefined}
-      onClick={(e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        node.toggle();
-        onExpandTree();
-      }}
-    >
-      {node.isInternal ? (
-        node.children && (node.children.length > 0 || node.data.hasChildren) ? (
-          node.isOpen ? (
-            <IconChevronDown stroke={2} size={18} />
-          ) : (
-            <IconChevronRight stroke={2} size={18} />
-          )
-        ) : (
-          <IconPointFilled size={8} />
-        )
-      ) : null}
-    </ActionIcon>
-  );
-}

apps/client/src/features/page/tree/hooks/drop-op-to-move-payload.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { SpaceTreeNode } from '@/features/page/tree/types';
+import { dropOpToMovePayload } from './drop-op-to-move-payload';
+
+vi.mock('fractional-indexing-jittered', () => ({
+  generateJitteredKeyBetween: (a: string | null, b: string | null) =>
+    `${a ?? 'START'}|${b ?? 'END'}`,
+}));
+
+const n = (id: string, position: string, children?: SpaceTreeNode[]): SpaceTreeNode =>
+  ({ id, position, children, name: id } as unknown as SpaceTreeNode);
+
+const tree: SpaceTreeNode[] = [
+  n('a', 'A', [n('a1', 'AA'), n('a2', 'AB')]),
+  n('b', 'B'),
+];
+
+describe('dropOpToMovePayload', () => {
+  it('reorder-before computes parentId + position between prev and target', () => {
+    const p = dropOpToMovePayload(tree, 'a2', {
+      kind: 'reorder-before',
+      targetId: 'a1',
+    });
+    expect(p).toEqual({ pageId: 'a2', parentPageId: 'a', position: 'START|AA' });
+  });
+
+  it('reorder-after computes position between target and next', () => {
+    const p = dropOpToMovePayload(tree, 'a1', {
+      kind: 'reorder-after',
+      targetId: 'a2',
+    });
+    expect(p).toEqual({ pageId: 'a1', parentPageId: 'a', position: 'AB|END' });
+  });
+
+  it('make-child appends with position after last child', () => {
+    const p = dropOpToMovePayload(tree, 'b', {
+      kind: 'make-child',
+      targetId: 'a',
+    });
+    expect(p).toEqual({ pageId: 'b', parentPageId: 'a', position: 'AB|END' });
+  });
+
+  it('reorder-before at root: parentPageId is null', () => {
+    const p = dropOpToMovePayload(tree, 'b', {
+      kind: 'reorder-before',
+      targetId: 'a',
+    });
+    expect(p).toEqual({ pageId: 'b', parentPageId: null, position: 'START|A' });
+  });
+
+  // Regression: when source is already adjacent to target, the BEFORE-tree
+  // treats source itself as the target's neighbor and falls back to null,
+  // producing an unbounded fractional key that overshoots other siblings.
+  // The fix uses the AFTER-tree, where source occupies its destination slot
+  // surrounded by its REAL neighbors.
+  it('reorder-after when source is immediately after target uses post-move neighbors', () => {
+    const adjacent: SpaceTreeNode[] = [
+      n('a', 'A'),
+      n('b', 'AB'),
+      n('c', 'B'),
+      n('d', 'BC'),
+    ];
+    const p = dropOpToMovePayload(adjacent, 'b', {
+      kind: 'reorder-after',
+      targetId: 'a',
+    });
+    // After-tree is [a, b, c, d] (no-op shape). Source 'b' at index 1.
+    // prev = 'A', next = 'B'. Old buggy code returned prev='A', next=null.
+    expect(p).toEqual({ pageId: 'b', parentPageId: null, position: 'A|B' });
+  });
+
+  it('reorder-before when source is immediately before target uses post-move neighbors', () => {
+    const adjacent: SpaceTreeNode[] = [
+      n('a', 'A'),
+      n('b', 'AB'),
+      n('c', 'B'),
+      n('d', 'BC'),
+    ];
+    const p = dropOpToMovePayload(adjacent, 'b', {
+      kind: 'reorder-before',
+      targetId: 'c',
+    });
+    // After-tree is [a, b, c, d]. Source 'b' at index 1.
+    // prev = 'A', next = 'B'. Old buggy code returned prev=null, next='B'.
+    expect(p).toEqual({ pageId: 'b', parentPageId: null, position: 'A|B' });
+  });
+
+  it('make-child when source is already last child of target uses post-move neighbors', () => {
+    const t: SpaceTreeNode[] = [
+      n('p', 'P', [n('x', 'X'), n('y', 'Y')]),
+    ];
+    const p = dropOpToMovePayload(t, 'y', {
+      kind: 'make-child',
+      targetId: 'p',
+    });
+    // After-tree: 'y' becomes last child of 'p' → [x, y]. y at index 1.
+    // prev = 'X', next = null. Old buggy: prev=Y (source's own position), next=null.
+    expect(p).toEqual({ pageId: 'y', parentPageId: 'p', position: 'X|END' });
+  });
+});

apps/client/src/features/page/tree/hooks/drop-op-to-move-payload.ts

@@ -0,0 +1,36 @@
+import { generateJitteredKeyBetween } from 'fractional-indexing-jittered';
+import type { SpaceTreeNode } from '@/features/page/tree/types';
+import type { IMovePage } from '@/features/page/types/page.types';
+import type { DropOp } from '@/features/page/tree/model/tree-model.types';
+import { treeModel } from '@/features/page/tree/model/tree-model';
+
+export function dropOpToMovePayload(
+  tree: SpaceTreeNode[],
+  sourceId: string,
+  op: DropOp,
+): IMovePage {
+  // Compute the post-move tree so we read source's REAL neighbors at its new
+  // position. Reading from the before-tree would mean treating source itself
+  // as a neighbor of the target — wrong when source is adjacent to target.
+  const { tree: after } = treeModel.move(tree, sourceId, op);
+  const info = treeModel.siblingsOf(after, sourceId);
+  if (!info) {
+    return {
+      pageId: sourceId,
+      parentPageId: null,
+      position: generateJitteredKeyBetween(null, null),
+    };
+  }
+
+  const prev = info.siblings[info.index - 1] as SpaceTreeNode | undefined;
+  const next = info.siblings[info.index + 1] as SpaceTreeNode | undefined;
+
+  return {
+    pageId: sourceId,
+    parentPageId: info.parentId,
+    position: generateJitteredKeyBetween(
+      prev?.position ?? null,
+      next?.position ?? null,
+    ),
+  };
+}

apps/client/src/features/page/tree/hooks/use-tree-mutation.ts

@@ -1,16 +1,15 @@
-import { useMemo } from "react";
-import {
-  CreateHandler,
-  DeleteHandler,
-  MoveHandler,
-  NodeApi,
-  RenameHandler,
-  SimpleTree,
-} from "react-arborist";
-import { useAtom } from "jotai";
-import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
-import { IMovePage, IPage } from "@/features/page/types/page.types.ts";
+import { useCallback } from "react";
+import { useAtom, useStore } from "jotai";
+import { notifications } from "@mantine/notifications";
+import { useTranslation } from "react-i18next";
 import { useNavigate, useParams } from "react-router-dom";
+
+import { treeDataAtom } from "@/features/page/tree/atoms/tree-data-atom.ts";
+import { treeModel } from "@/features/page/tree/model/tree-model";
+import type { DropOp } from "@/features/page/tree/model/tree-model.types";
+import { dropOpToMovePayload } from "./drop-op-to-move-payload";
+import { SpaceTreeNode } from "@/features/page/tree/types.ts";
+import { IPage } from "@/features/page/types/page.types.ts";
 import {
   useCreatePageMutation,
   useRemovePageMutation,
@@ -18,258 +17,250 @@ import {
   useUpdatePageMutation,
   updateCacheOnMovePage,
 } from "@/features/page/queries/page-query.ts";
-import { generateJitteredKeyBetween } from "fractional-indexing-jittered";
-import { SpaceTreeNode } from "@/features/page/tree/types.ts";
 import { buildPageUrl } from "@/features/page/page.utils.ts";
 import { getSpaceUrl } from "@/lib/config.ts";
 import { useQueryEmit } from "@/features/websocket/use-query-emit.ts";
 
-export function useTreeMutation<T>(spaceId: string) {
-  const [data, setData] = useAtom(treeDataAtom);
-  const tree = useMemo(() => new SimpleTree<SpaceTreeNode>(data), [data]);
+export type UseTreeMutation = {
+  handleMove: (sourceId: string, op: DropOp) => Promise<void>;
+  handleCreate: (parentId: string | null) => Promise<void>;
+  handleRename: (id: string, name: string) => Promise<void>;
+  handleDelete: (id: string) => Promise<void>;
+};
+
+export function useTreeMutation(spaceId: string): UseTreeMutation {
+  const { t } = useTranslation();
+  const [, setData] = useAtom(treeDataAtom);
+  // `store` reads the *current* treeDataAtom imperatively in handlers — avoids
+  // stale-closure issues when the caller updates the tree (e.g. lazy-load
+  // children) and then immediately invokes a handler.
+  const store = useStore();
   const createPageMutation = useCreatePageMutation();
   const updatePageMutation = useUpdatePageMutation();
   const removePageMutation = useRemovePageMutation();
   const movePageMutation = useMovePageMutation();
   const navigate = useNavigate();
-  const { spaceSlug } = useParams();
-  const { pageSlug } = useParams();
+  const { spaceSlug, pageSlug } = useParams();
   const emit = useQueryEmit();
 
-  const onCreate: CreateHandler<T> = async ({ parentId, index, type }) => {
-    const payload: { spaceId: string; parentPageId?: string } = {
-      spaceId: spaceId,
-    };
-    if (parentId) {
-      payload.parentPageId = parentId;
-    }
+  const handleMove = useCallback(
+    async (sourceId: string, op: DropOp) => {
+      const before = store.get(treeDataAtom);
+      const { tree: after, result } = treeModel.move(before, sourceId, op);
+      if (after === before) return;
 
-    let createdPage: IPage;
-    try {
-      createdPage = await createPageMutation.mutateAsync(payload);
-    } catch (err) {
-      throw new Error("Failed to create page");
-    }
+      const payload = dropOpToMovePayload(before, sourceId, op);
+      const source = treeModel.find(before, sourceId) as SpaceTreeNode | null;
+      if (!source) return;
+      const oldParentId = source.parentPageId ?? null;
 
-    const data = {
-      id: createdPage.id,
-      slugId: createdPage.slugId,
-      name: "",
-      position: createdPage.position,
-      spaceId: createdPage.spaceId,
-      parentPageId: createdPage.parentPageId,
-      children: [],
-    } as any;
+      // optimistic apply with the new position from the payload
+      let optimistic = treeModel.update(after, sourceId, {
+        position: payload.position,
+        parentPageId: payload.parentPageId,
+      } as Partial<SpaceTreeNode>);
 
-    let lastIndex: number;
-    if (parentId === null) {
-      lastIndex = tree.data.length;
-    } else {
-      lastIndex = tree.find(parentId).children.length;
-    }
-    // to place the newly created node at the bottom
-    index = lastIndex;
-
-    tree.create({ parentId, index, data });
-    setData(tree.data);
-
-    setTimeout(() => {
-      emit({
-        operation: "addTreeNode",
-        spaceId: spaceId,
-        payload: {
-          parentId,
-          index,
-          data,
-        },
-      });
-    }, 50);
-
-    const pageUrl = buildPageUrl(
-      spaceSlug,
-      createdPage.slugId,
-      createdPage.title
-    );
-    navigate(pageUrl);
-    return data;
-  };
-
-  const onMove: MoveHandler<T> = async (args: {
-    dragIds: string[];
-    dragNodes: NodeApi<T>[];
-    parentId: string | null;
-    parentNode: NodeApi<T> | null;
-    index: number;
-  }) => {
-    const draggedNodeId = args.dragIds[0];
-
-    tree.move({
-      id: draggedNodeId,
-      parentId: args.parentId,
-      index: args.index,
-    });
-
-    const newDragIndex = tree.find(draggedNodeId)?.childIndex;
-
-    const currentTreeData = args.parentId
-      ? tree.find(args.parentId).children
-      : tree.data;
-
-    // if there is a parentId, tree.find(args.parentId).children returns a SimpleNode array
-    // we have to access the node differently via currentTreeData[args.index]?.data?.position
-    // this makes it possible to correctly sort children of a parent node that is not the root
-
-    const afterPosition =
-      // @ts-ignore
-      currentTreeData[newDragIndex - 1]?.position ||
-      // @ts-ignore
-      currentTreeData[args.index - 1]?.data?.position ||
-      null;
-
-    const beforePosition =
-      // @ts-ignore
-      currentTreeData[newDragIndex + 1]?.position ||
-      // @ts-ignore
-      currentTreeData[args.index + 1]?.data?.position ||
-      null;
-
-    let newPosition: string;
-
-    if (afterPosition && beforePosition && afterPosition === beforePosition) {
-      // if after is equal to before, put it next to the after node
-      newPosition = generateJitteredKeyBetween(afterPosition, null);
-    } else {
-      // if both are null then, it is the first index
-      newPosition = generateJitteredKeyBetween(afterPosition, beforePosition);
-    }
-
-    // update the node position in tree
-    tree.update({
-      id: draggedNodeId,
-      changes: { position: newPosition } as any,
-    });
-
-    const previousParent = args.dragNodes[0].parent;
-    if (
-      previousParent.id !== args.parentId &&
-      previousParent.id !== "__REACT_ARBORIST_INTERNAL_ROOT__"
-    ) {
-      // if the page was moved to another parent,
-      // check if the previous still has children
-      // if no children left, change 'hasChildren' to false, to make the page toggle arrows work properly
-      const childrenCount = previousParent.children.filter(
-        (child) => child.id !== draggedNodeId
-      ).length;
-      if (childrenCount === 0) {
-        tree.update({
-          id: previousParent.id,
-          changes: { ...previousParent.data, hasChildren: false } as any,
-        });
+      // If the old parent has no children left, mark hasChildren: false so the
+      // chevron disappears. Without this, the empty parent keeps rendering an
+      // expand toggle that fetches zero rows on click.
+      if (oldParentId) {
+        const oldParent = treeModel.find(optimistic, oldParentId);
+        if (!oldParent?.children?.length) {
+          optimistic = treeModel.update(optimistic, oldParentId, {
+            hasChildren: false,
+          } as Partial<SpaceTreeNode>);
+        }
       }
-    }
 
-    setData(tree.data);
+      // For make-child onto a previously-childless target: flip hasChildren on
+      // so the new parent shows its chevron.
+      if (op.kind === "make-child") {
+        optimistic = treeModel.update(optimistic, op.targetId, {
+          hasChildren: true,
+        } as Partial<SpaceTreeNode>);
+      }
 
-    const payload: IMovePage = {
-      pageId: draggedNodeId,
-      position: newPosition,
-      parentPageId: args.parentId,
-    };
+      setData(optimistic);
 
-    const draggedNode = args.dragNodes[0];
-    const nodeData = draggedNode.data as SpaceTreeNode;
-    const oldParentId = nodeData.parentPageId ?? null;
-    const pageData = {
-      id: nodeData.id,
-      slugId: nodeData.slugId,
-      title: nodeData.name,
-      icon: nodeData.icon,
-      position: newPosition,
-      spaceId: nodeData.spaceId,
-      parentPageId: args.parentId,
-      hasChildren: nodeData.hasChildren,
-    };
+      try {
+        await movePageMutation.mutateAsync(payload);
+      } catch {
+        setData(before);
+        notifications.show({
+          message: t("Failed to move page"),
+          color: "red",
+        });
+        return;
+      }
 
-    try {
-      await movePageMutation.mutateAsync(payload);
+      const pageData: Partial<IPage> = {
+        id: source.id,
+        slugId: source.slugId,
+        title: source.name,
+        icon: source.icon,
+        position: payload.position,
+        spaceId: source.spaceId,
+        parentPageId: payload.parentPageId,
+        hasChildren: source.hasChildren,
+      };
 
-      updateCacheOnMovePage(spaceId, draggedNodeId, oldParentId, args.parentId, pageData);
+      updateCacheOnMovePage(
+        spaceId,
+        sourceId,
+        oldParentId,
+        payload.parentPageId,
+        pageData,
+      );
 
       setTimeout(() => {
         emit({
           operation: "moveTreeNode",
           spaceId: spaceId,
           payload: {
-            id: draggedNodeId,
-            parentId: args.parentId,
+            id: sourceId,
+            parentId: payload.parentPageId,
             oldParentId,
-            index: args.index,
-            position: newPosition,
+            index: result.index,
+            position: payload.position,
             pageData,
           },
         });
       }, 50);
-    } catch (error) {
-      console.error("Error moving page:", error);
-    }
-  };
+    },
+    [setData, store, movePageMutation, spaceId, emit, t],
+  );
 
-  const onRename: RenameHandler<T> = ({ name, id }) => {
-    tree.update({ id, changes: { name } as any });
-    setData(tree.data);
+  const handleCreate = useCallback(
+    async (parentId: string | null) => {
+      const payload: { spaceId: string; parentPageId?: string } = { spaceId };
+      if (parentId) payload.parentPageId = parentId;
 
-    try {
-      updatePageMutation.mutateAsync({ pageId: id, title: name });
-    } catch (error) {
-      console.error("Error updating page title:", error);
-    }
-  };
+      let createdPage: IPage;
+      try {
+        createdPage = await createPageMutation.mutateAsync(payload);
+      } catch {
+        throw new Error("Failed to create page");
+      }
 
-  const isPageInNode = (
-    node: { data: SpaceTreeNode; children?: any[] },
-    pageSlug: string
-  ): boolean => {
-    if (node.data.slugId === pageSlug) {
-      return true;
-    }
-    for (const item of node.children) {
-      if (item.data.slugId === pageSlug) {
-        return true;
+      const newNode: SpaceTreeNode = {
+        id: createdPage.id,
+        slugId: createdPage.slugId,
+        name: "",
+        position: createdPage.position,
+        spaceId: createdPage.spaceId,
+        parentPageId: createdPage.parentPageId,
+        hasChildren: false,
+        children: [],
+      };
+
+      // Read latest tree at call time. Without this, callers that mutate the
+      // tree (e.g. lazy-load children on expand) immediately before calling
+      // handleCreate hit a stale closure and compute lastIndex against the
+      // pre-load tree, requiring a setTimeout-based wait at the call site.
+      const current = store.get(treeDataAtom);
+      let lastIndex: number;
+      if (parentId === null) {
+        lastIndex = current.length;
       } else {
-        return isPageInNode(item, pageSlug);
-      }
-    }
-    return false;
-  };
-
-  const onDelete: DeleteHandler<T> = async (args: { ids: string[] }) => {
-    try {
-      await removePageMutation.mutateAsync(args.ids[0]);
-
-      const node = tree.find(args.ids[0]);
-      if (!node) {
-        return;
+        const parent = treeModel.find(current, parentId);
+        lastIndex = parent?.children?.length ?? 0;
       }
 
-      tree.drop({ id: args.ids[0] });
-      setData(tree.data);
-
-      if (pageSlug && isPageInNode(node, pageSlug.split("-")[1])) {
-        navigate(getSpaceUrl(spaceSlug));
-      }
+      setData((prev) => treeModel.insert(prev, parentId, newNode, lastIndex));
 
       setTimeout(() => {
         emit({
-          operation: "deleteTreeNode",
-          spaceId: spaceId,
-          payload: { node: node.data },
+          operation: "addTreeNode",
+          spaceId,
+          payload: {
+            parentId,
+            index: lastIndex,
+            data: newNode,
+          },
         });
       }, 50);
-    } catch (error) {
-      console.error("Failed to delete page:", error);
-    }
-  };
 
-  const controllers = { onMove, onRename, onCreate, onDelete };
-  return { data, setData, controllers } as const;
+      const pageUrl = buildPageUrl(
+        spaceSlug,
+        createdPage.slugId,
+        createdPage.title,
+      );
+      navigate(pageUrl);
+    },
+    [spaceId, createPageMutation, setData, store, emit, navigate, spaceSlug],
+  );
+
+  const handleRename = useCallback(
+    async (id: string, name: string) => {
+      setData((prev) =>
+        treeModel.update(prev, id, { name } as Partial<SpaceTreeNode>),
+      );
+      try {
+        await updatePageMutation.mutateAsync({ pageId: id, title: name });
+      } catch (error) {
+        console.error("Error updating page title:", error);
+      }
+    },
+    [updatePageMutation, setData],
+  );
+
+  const handleDelete = useCallback(
+    async (id: string) => {
+      const node = treeModel.find(
+        store.get(treeDataAtom),
+        id,
+      ) as SpaceTreeNode | null;
+      const parentPageId = node?.parentPageId ?? null;
+      try {
+        await removePageMutation.mutateAsync(id);
+        setData((prev) => {
+          let next = treeModel.remove(prev, id);
+          // If the parent has no children left, mark hasChildren: false so the
+          // chevron disappears. Without this, the empty parent keeps rendering an
+          // expand toggle that fetches zero rows on click.
+          if (parentPageId) {
+            const parent = treeModel.find(next, parentPageId);
+            if (!parent?.children?.length) {
+              next = treeModel.update(next, parentPageId, {
+                hasChildren: false,
+              } as Partial<SpaceTreeNode>);
+            }
+          }
+          return next;
+        });
+
+        if (
+          node &&
+          pageSlug &&
+          (node.slugId === pageSlug.split("-")[1] ||
+            isPageInNode(node, pageSlug.split("-")[1]))
+        ) {
+          navigate(getSpaceUrl(spaceSlug));
+        }
+
+        setTimeout(() => {
+          if (!node) return;
+          emit({
+            operation: "deleteTreeNode",
+            spaceId,
+            payload: { node },
+          });
+        }, 50);
+      } catch (error) {
+        console.error("Failed to delete page:", error);
+      }
+    },
+    [removePageMutation, setData, store, pageSlug, navigate, spaceSlug, emit, spaceId],
+  );
+
+  return { handleMove, handleCreate, handleRename, handleDelete };
+}
+
+function isPageInNode(node: SpaceTreeNode, pageSlug: string): boolean {
+  if (node.slugId === pageSlug) return true;
+  if (!node.children) return false;
+  for (const child of node.children) {
+    if (isPageInNode(child, pageSlug)) return true;
+  }
+  return false;
 }

apps/client/src/features/page/tree/model/tree-model.test.ts

@@ -0,0 +1,329 @@
+import { describe, it, expect } from 'vitest';
+import { treeModel } from './tree-model';
+import type { TreeNode } from './tree-model.types';
+
+type N = TreeNode<{ name: string }>;
+
+const fixture: N[] = [
+  {
+    id: 'a',
+    name: 'A',
+    children: [
+      { id: 'a1', name: 'A1', children: [{ id: 'a1a', name: 'A1a' }] },
+      { id: 'a2', name: 'A2' },
+    ],
+  },
+  { id: 'b', name: 'B' },
+];
+
+describe('treeModel.find', () => {
+  it('finds a root node', () => {
+    expect(treeModel.find(fixture, 'a')?.name).toBe('A');
+  });
+  it('finds a deeply nested node', () => {
+    expect(treeModel.find(fixture, 'a1a')?.name).toBe('A1a');
+  });
+  it('returns null for unknown id', () => {
+    expect(treeModel.find(fixture, 'zzz')).toBeNull();
+  });
+});
+
+describe('treeModel.path', () => {
+  it('returns root-to-leaf path for nested id', () => {
+    const p = treeModel.path(fixture, 'a1a');
+    expect(p?.map((n) => n.id)).toEqual(['a', 'a1', 'a1a']);
+  });
+  it('returns [node] for root-level id', () => {
+    expect(treeModel.path(fixture, 'b')?.map((n) => n.id)).toEqual(['b']);
+  });
+  it('returns null for unknown id', () => {
+    expect(treeModel.path(fixture, 'zzz')).toBeNull();
+  });
+});
+
+describe('treeModel.siblingsOf', () => {
+  it('returns siblings + parent + index for a child', () => {
+    const info = treeModel.siblingsOf(fixture, 'a2');
+    expect(info?.parentId).toBe('a');
+    expect(info?.siblings.map((n) => n.id)).toEqual(['a1', 'a2']);
+    expect(info?.index).toBe(1);
+  });
+  it('returns parentId null + root siblings for a root id', () => {
+    const info = treeModel.siblingsOf(fixture, 'b');
+    expect(info?.parentId).toBeNull();
+    expect(info?.siblings.map((n) => n.id)).toEqual(['a', 'b']);
+    expect(info?.index).toBe(1);
+  });
+  it('returns null for unknown id', () => {
+    expect(treeModel.siblingsOf(fixture, 'zzz')).toBeNull();
+  });
+});
+
+describe('treeModel.isDescendant', () => {
+  it('returns true when descendantId is nested under ancestorId', () => {
+    expect(treeModel.isDescendant(fixture, 'a', 'a1a')).toBe(true);
+  });
+  it('returns false when ids are siblings', () => {
+    expect(treeModel.isDescendant(fixture, 'a1', 'a2')).toBe(false);
+  });
+  it('returns false when ancestorId is the same as descendantId', () => {
+    expect(treeModel.isDescendant(fixture, 'a', 'a')).toBe(false);
+  });
+  it('returns false for unknown ids', () => {
+    expect(treeModel.isDescendant(fixture, 'zzz', 'a')).toBe(false);
+  });
+});
+
+describe('treeModel.visible', () => {
+  it('returns only root nodes when no openIds', () => {
+    const v = treeModel.visible(fixture, new Set());
+    expect(v.map((n) => n.id)).toEqual(['a', 'b']);
+  });
+  it('includes children of open ids in DFS order', () => {
+    const v = treeModel.visible(fixture, new Set(['a']));
+    expect(v.map((n) => n.id)).toEqual(['a', 'a1', 'a2', 'b']);
+  });
+  it('recursively descends through chains of open ids', () => {
+    const v = treeModel.visible(fixture, new Set(['a', 'a1']));
+    expect(v.map((n) => n.id)).toEqual(['a', 'a1', 'a1a', 'a2', 'b']);
+  });
+  it('ignores openIds that are not in the tree', () => {
+    const v = treeModel.visible(fixture, new Set(['ghost']));
+    expect(v.map((n) => n.id)).toEqual(['a', 'b']);
+  });
+});
+
+describe('treeModel.insert', () => {
+  const leaf = (id: string): N => ({ id, name: id.toUpperCase() });
+
+  it('inserts at end when index is undefined', () => {
+    const t = treeModel.insert(fixture, 'a', leaf('a3'));
+    expect(treeModel.siblingsOf(t, 'a3')?.siblings.map((n) => n.id)).toEqual([
+      'a1', 'a2', 'a3',
+    ]);
+  });
+  it('inserts at index 0', () => {
+    const t = treeModel.insert(fixture, 'a', leaf('a0'), 0);
+    expect(treeModel.siblingsOf(t, 'a0')?.siblings.map((n) => n.id)).toEqual([
+      'a0', 'a1', 'a2',
+    ]);
+  });
+  it('inserts in the middle', () => {
+    const t = treeModel.insert(fixture, 'a', leaf('a1half'), 1);
+    expect(
+      treeModel.siblingsOf(t, 'a1half')?.siblings.map((n) => n.id),
+    ).toEqual(['a1', 'a1half', 'a2']);
+  });
+  it('inserts at root when parentId is null', () => {
+    const t = treeModel.insert(fixture, null, leaf('c'));
+    expect(t.map((n) => n.id)).toEqual(['a', 'b', 'c']);
+  });
+  it('returns same array reference for unknown parentId', () => {
+    const t = treeModel.insert(fixture, 'ghost', leaf('zz'));
+    expect(t).toBe(fixture);
+  });
+  it('initializes children array when parent had no children', () => {
+    const t = treeModel.insert(fixture, 'b', leaf('b1'));
+    expect(treeModel.find(t, 'b')?.children?.map((n) => n.id)).toEqual(['b1']);
+  });
+});
+
+describe('treeModel.remove', () => {
+  it('removes a leaf', () => {
+    const t = treeModel.remove(fixture, 'a2');
+    expect(treeModel.find(t, 'a2')).toBeNull();
+  });
+  it('removes a subtree', () => {
+    const t = treeModel.remove(fixture, 'a1');
+    expect(treeModel.find(t, 'a1')).toBeNull();
+    expect(treeModel.find(t, 'a1a')).toBeNull();
+  });
+  it('removes a root node', () => {
+    const t = treeModel.remove(fixture, 'b');
+    expect(t.map((n) => n.id)).toEqual(['a']);
+  });
+  it('returns same array reference for unknown id', () => {
+    expect(treeModel.remove(fixture, 'ghost')).toBe(fixture);
+  });
+});
+
+describe('treeModel.update', () => {
+  it('shallow-merges a patch on the matching node', () => {
+    const t = treeModel.update(fixture, 'a1', { name: 'A1-renamed' });
+    expect(treeModel.find(t, 'a1')?.name).toBe('A1-renamed');
+  });
+  it('returns same array reference for unknown id', () => {
+    expect(treeModel.update(fixture, 'ghost', { name: 'x' })).toBe(fixture);
+  });
+  it("preserves children when patching parent's own fields", () => {
+    const t = treeModel.update(fixture, 'a', { name: 'A-renamed' });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a1', 'a2',
+    ]);
+  });
+  it('preserves reference identity of unrelated subtrees', () => {
+    const t = treeModel.update(fixture, 'a1', { name: 'X' });
+    expect(t[1]).toBe(fixture[1]);
+  });
+});
+
+describe('treeModel.appendChildren', () => {
+  const kid = (id: string): N => ({ id, name: id });
+
+  it('appends to existing children', () => {
+    const t = treeModel.appendChildren(fixture, 'a', [kid('a3'), kid('a4')]);
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a1', 'a2', 'a3', 'a4',
+    ]);
+  });
+  it('initializes children when parent had none', () => {
+    const t = treeModel.appendChildren(fixture, 'b', [kid('b1')]);
+    expect(treeModel.find(t, 'b')?.children?.map((n) => n.id)).toEqual(['b1']);
+  });
+  it('returns same array reference for unknown parentId', () => {
+    expect(treeModel.appendChildren(fixture, 'ghost', [kid('zz')])).toBe(
+      fixture,
+    );
+  });
+
+  // Regression: lazy-load + auto-expand can race and call appendChildren with
+  // children that overlap what's already there. React then crashes on duplicate
+  // keys. Defensive dedup at the model level.
+  it('dedups against existing children by id', () => {
+    const t1 = treeModel.appendChildren(fixture, 'a', [
+      kid('a3'),
+      kid('a4'),
+    ]);
+    const t2 = treeModel.appendChildren(t1, 'a', [
+      kid('a3'),
+      kid('a4'),
+      kid('a5'),
+    ]);
+    expect(treeModel.find(t2, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a1', 'a2', 'a3', 'a4', 'a5',
+    ]);
+  });
+
+  it('returns same array reference when every child is a duplicate', () => {
+    const t1 = treeModel.appendChildren(fixture, 'a', [kid('a3')]);
+    const t2 = treeModel.appendChildren(t1, 'a', [kid('a3')]);
+    expect(t2).toBe(t1);
+  });
+});
+
+describe('treeModel.place', () => {
+  it('moves a node to a new parent at a given index', () => {
+    const t = treeModel.place(fixture, 'a2', { parentId: 'b', index: 0 });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual(['a1']);
+    expect(treeModel.find(t, 'b')?.children?.map((n) => n.id)).toEqual(['a2']);
+  });
+  it('moves a node to root', () => {
+    const t = treeModel.place(fixture, 'a1', { parentId: null, index: 0 });
+    expect(t.map((n) => n.id)).toEqual(['a1', 'a', 'b']);
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual(['a2']);
+  });
+  it('reorders within the same parent', () => {
+    const t = treeModel.place(fixture, 'a2', { parentId: 'a', index: 0 });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a2', 'a1',
+    ]);
+  });
+  it('returns same array reference for unknown source', () => {
+    expect(
+      treeModel.place(fixture, 'ghost', { parentId: 'a', index: 0 }),
+    ).toBe(fixture);
+  });
+  it('returns same array reference for unknown destination parent', () => {
+    expect(
+      treeModel.place(fixture, 'a1', { parentId: 'ghost', index: 0 }),
+    ).toBe(fixture);
+  });
+});
+
+describe('treeModel.move', () => {
+  it('reorder-before within same parent: moves source to target index', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'a2', {
+      kind: 'reorder-before',
+      targetId: 'a1',
+    });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a2', 'a1',
+    ]);
+    expect(result).toEqual({ parentId: 'a', index: 0 });
+  });
+  it('reorder-after within same parent', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'a1', {
+      kind: 'reorder-after',
+      targetId: 'a2',
+    });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a2', 'a1',
+    ]);
+    expect(result).toEqual({ parentId: 'a', index: 1 });
+  });
+  it('make-child appends at end of target children', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'b', {
+      kind: 'make-child',
+      targetId: 'a',
+    });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'a1', 'a2', 'b',
+    ]);
+    expect(result).toEqual({ parentId: 'a', index: 2 });
+  });
+  it('make-child initializes children when target had none', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'a2', {
+      kind: 'make-child',
+      targetId: 'b',
+    });
+    expect(treeModel.find(t, 'b')?.children?.map((n) => n.id)).toEqual(['a2']);
+    expect(result).toEqual({ parentId: 'b', index: 0 });
+  });
+  it('reorder-before across parents', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'b', {
+      kind: 'reorder-before',
+      targetId: 'a1',
+    });
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual([
+      'b', 'a1', 'a2',
+    ]);
+    expect(result).toEqual({ parentId: 'a', index: 0 });
+  });
+  it('reorder-after to root', () => {
+    const { tree: t, result } = treeModel.move(fixture, 'a1', {
+      kind: 'reorder-after',
+      targetId: 'a',
+    });
+    expect(t.map((n) => n.id)).toEqual(['a', 'a1', 'b']);
+    expect(treeModel.find(t, 'a')?.children?.map((n) => n.id)).toEqual(['a2']);
+    expect(result).toEqual({ parentId: null, index: 1 });
+  });
+  it('no-op when sourceId === targetId', () => {
+    const out = treeModel.move(fixture, 'a', {
+      kind: 'make-child',
+      targetId: 'a',
+    });
+    expect(out.tree).toBe(fixture);
+  });
+  it('no-op when target is descendant of source', () => {
+    const out = treeModel.move(fixture, 'a', {
+      kind: 'make-child',
+      targetId: 'a1a',
+    });
+    expect(out.tree).toBe(fixture);
+  });
+  it('no-op when source is unknown', () => {
+    const out = treeModel.move(fixture, 'ghost', {
+      kind: 'reorder-before',
+      targetId: 'a',
+    });
+    expect(out.tree).toBe(fixture);
+  });
+  it('no-op when target is unknown', () => {
+    const out = treeModel.move(fixture, 'a1', {
+      kind: 'reorder-before',
+      targetId: 'ghost',
+    });
+    expect(out.tree).toBe(fixture);
+  });
+});

apps/client/src/features/page/tree/model/tree-model.ts

@@ -0,0 +1,222 @@
+import type { TreeNode, SiblingsInfo } from './tree-model.types';
+
+function findInternal<T extends object>(
+  nodes: TreeNode<T>[],
+  id: string,
+): { parents: TreeNode<T>[]; node: TreeNode<T> } | null {
+  for (const node of nodes) {
+    if (node.id === id) return { parents: [], node };
+    if (node.children) {
+      const inner = findInternal(node.children, id);
+      if (inner) return { parents: [node, ...inner.parents], node: inner.node };
+    }
+  }
+  return null;
+}
+
+export const treeModel = {
+  find<T extends object>(tree: TreeNode<T>[], id: string): TreeNode<T> | null {
+    return findInternal(tree, id)?.node ?? null;
+  },
+
+  path<T extends object>(tree: TreeNode<T>[], id: string): TreeNode<T>[] | null {
+    const found = findInternal(tree, id);
+    if (!found) return null;
+    return [...found.parents, found.node];
+  },
+
+  siblingsOf<T extends object>(
+    tree: TreeNode<T>[],
+    id: string,
+  ): SiblingsInfo<T> | null {
+    const found = findInternal(tree, id);
+    if (!found) return null;
+    const parent = found.parents[found.parents.length - 1];
+    const siblings = parent ? parent.children! : tree;
+    return {
+      parentId: parent?.id ?? null,
+      siblings,
+      index: siblings.findIndex((n) => n.id === id),
+    };
+  },
+
+  isDescendant<T extends object>(
+    tree: TreeNode<T>[],
+    ancestorId: string,
+    descendantId: string,
+  ): boolean {
+    if (ancestorId === descendantId) return false;
+    const ancestor = treeModel.find(tree, ancestorId);
+    if (!ancestor?.children) return false;
+    return findInternal(ancestor.children, descendantId) !== null;
+  },
+
+  visible<T extends object>(
+    tree: TreeNode<T>[],
+    openIds: ReadonlySet<string>,
+  ): TreeNode<T>[] {
+    const out: TreeNode<T>[] = [];
+    const walk = (nodes: TreeNode<T>[]) => {
+      for (const node of nodes) {
+        out.push(node);
+        if (openIds.has(node.id) && node.children?.length) walk(node.children);
+      }
+    };
+    walk(tree);
+    return out;
+  },
+
+  insert<T extends object>(
+    tree: TreeNode<T>[],
+    parentId: string | null,
+    node: TreeNode<T>,
+    index?: number,
+  ): TreeNode<T>[] {
+    if (parentId === null) {
+      const idx = index ?? tree.length;
+      return [...tree.slice(0, idx), node, ...tree.slice(idx)];
+    }
+    let touched = false;
+    const walk = (nodes: TreeNode<T>[]): TreeNode<T>[] =>
+      nodes.map((n) => {
+        if (n.id === parentId) {
+          touched = true;
+          const kids = n.children ?? [];
+          const idx = index ?? kids.length;
+          return {
+            ...n,
+            children: [...kids.slice(0, idx), node, ...kids.slice(idx)],
+          };
+        }
+        if (n.children) {
+          const next = walk(n.children);
+          if (next !== n.children) return { ...n, children: next };
+        }
+        return n;
+      });
+    const out = walk(tree);
+    return touched ? out : tree;
+  },
+
+  remove<T extends object>(tree: TreeNode<T>[], id: string): TreeNode<T>[] {
+    let touched = false;
+    const walk = (nodes: TreeNode<T>[]): TreeNode<T>[] => {
+      const filtered = nodes.filter((n) => {
+        if (n.id === id) {
+          touched = true;
+          return false;
+        }
+        return true;
+      });
+      return filtered.map((n) => {
+        if (n.children) {
+          const next = walk(n.children);
+          if (next !== n.children) return { ...n, children: next };
+        }
+        return n;
+      });
+    };
+    const out = walk(tree);
+    return touched ? out : tree;
+  },
+
+  // `patch` excludes `id` (immutable) and `children` (use insert / remove /
+  // appendChildren for structural changes — otherwise referential identity of
+  // unrelated subtrees gets blown away).
+  update<T extends object>(
+    tree: TreeNode<T>[],
+    id: string,
+    patch: Omit<Partial<T>, "id" | "children">,
+  ): TreeNode<T>[] {
+    let touched = false;
+    const walk = (nodes: TreeNode<T>[]): TreeNode<T>[] =>
+      nodes.map((n) => {
+        if (n.id === id) {
+          touched = true;
+          return { ...n, ...patch };
+        }
+        if (n.children) {
+          const next = walk(n.children);
+          if (next !== n.children) return { ...n, children: next };
+        }
+        return n;
+      });
+    const out = walk(tree);
+    return touched ? out : tree;
+  },
+
+  appendChildren<T extends object>(
+    tree: TreeNode<T>[],
+    parentId: string,
+    children: TreeNode<T>[],
+  ): TreeNode<T>[] {
+    let touched = false;
+    const walk = (nodes: TreeNode<T>[]): TreeNode<T>[] =>
+      nodes.map((n) => {
+        if (n.id === parentId) {
+          const existing = n.children ?? [];
+          // Dedup against existing ids — auto-expand + manual toggle can race
+          // and produce overlapping fetches; we don't want React to see two
+          // children with the same key.
+          const existingIds = new Set(existing.map((c) => c.id));
+          const fresh = children.filter((c) => !existingIds.has(c.id));
+          if (fresh.length === 0) return n;
+          touched = true;
+          return { ...n, children: [...existing, ...fresh] };
+        }
+        if (n.children) {
+          const next = walk(n.children);
+          if (next !== n.children) return { ...n, children: next };
+        }
+        return n;
+      });
+    const out = walk(tree);
+    return touched ? out : tree;
+  },
+
+  place<T extends object>(
+    tree: TreeNode<T>[],
+    sourceId: string,
+    to: { parentId: string | null; index: number },
+  ): TreeNode<T>[] {
+    const source = treeModel.find(tree, sourceId);
+    if (!source) return tree;
+    if (to.parentId !== null && !treeModel.find(tree, to.parentId)) return tree;
+    const removed = treeModel.remove(tree, sourceId);
+    return treeModel.insert(removed, to.parentId, source, to.index);
+  },
+
+  move<T extends object>(
+    tree: TreeNode<T>[],
+    sourceId: string,
+    op: import('./tree-model.types').DropOp,
+  ): { tree: TreeNode<T>[]; result: import('./tree-model.types').DropResult } {
+    if (sourceId === op.targetId) return { tree, result: { parentId: null, index: 0 } };
+    if (!treeModel.find(tree, sourceId) || !treeModel.find(tree, op.targetId)) {
+      return { tree, result: { parentId: null, index: 0 } };
+    }
+    if (treeModel.isDescendant(tree, sourceId, op.targetId)) {
+      return { tree, result: { parentId: null, index: 0 } };
+    }
+
+    let parentId: string | null;
+    let index: number;
+
+    if (op.kind === 'make-child') {
+      parentId = op.targetId;
+      const target = treeModel.find(tree, op.targetId)!;
+      index = target.children?.length ?? 0;
+    } else {
+      const info = treeModel.siblingsOf(tree, op.targetId)!;
+      parentId = info.parentId;
+      const sourceInfo = treeModel.siblingsOf(tree, sourceId)!;
+      const sameParent = sourceInfo.parentId === parentId;
+      const adjust =
+        sameParent && sourceInfo.index < info.index ? -1 : 0;
+      index = info.index + adjust + (op.kind === 'reorder-after' ? 1 : 0);
+    }
+
+    const next = treeModel.place(tree, sourceId, { parentId, index });
+    return { tree: next, result: { parentId, index } };
+  },
+};

apps/client/src/features/page/tree/model/tree-model.types.ts

@@ -0,0 +1,20 @@
+export type TreeNode<T extends object = object> = T & {
+  id: string;
+  children?: TreeNode<T>[];
+};
+
+export type DropOp =
+  | { kind: 'reorder-before'; targetId: string }
+  | { kind: 'reorder-after'; targetId: string }
+  | { kind: 'make-child'; targetId: string };
+
+export type DropResult = {
+  parentId: string | null;
+  index: number;
+};
+
+export type SiblingsInfo<T extends object> = {
+  parentId: string | null;
+  siblings: TreeNode<T>[];
+  index: number;
+};

apps/client/src/features/page/tree/styles/tree.module.css

@@ -5,10 +5,11 @@
 .treeContainer {
     height: 100%;
     min-width: 0;
-
-    > div, > div > .tree {
-        height: 100% !important;
-    }
+    /* DocTree renders a vanilla <ul role="tree"> with no internal virtualizer,
+       so the container must own the scroll. Without this the tree grows past
+       its parent and the page scrolls instead. */
+    overflow-y: auto;
+    overflow-x: hidden;
 }
 
 .node {
@@ -17,76 +18,39 @@
     display: flex;
     align-items: center;
     height: 100%;
-    width: 93%; /* not to overlap with scroll bar */
+    width: 100%;
     text-decoration: none;
     color: light-dark(var(--mantine-color-gray-7), var(--mantine-color-dark-0));
 
-    &:hover {
-        background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-5));
-        /*background-color: light-dark(var(--mantine-color-gray-1), var(--mantine-color-dark-6));*/
-     }
+    /* Gate hover styles to mouse-capable devices. Touch browsers synthesize
+       :hover on the first tap (sticky hover) and only fire click on the
+       second tap, requiring a double-tap to navigate. */
+    @media (hover: hover) {
+        &:hover {
+            background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-5));
+        }
 
+        &:hover .actions {
+            opacity: 1;
+            pointer-events: auto;
+        }
+    }
 
     .actions {
-        visibility: hidden;
-        position: absolute;
-        height: 100%;
-        top: 0;
-        right: 0;
-        border-top-right-radius: 4px;
-        border-bottom-right-radius: 4px;
-        background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-6));
+        display: inline-flex;
+        flex-shrink: 0;
+        align-items: center;
+        margin-left: 4px;
+        opacity: 0;
+        pointer-events: none;
     }
 
-      &:hover .actions {
-       visibility: visible;
+    &:focus-within .actions {
+        opacity: 1;
+        pointer-events: auto;
     }
-
 }
 
-.node:global(.willReceiveDrop) {
-    background-color: light-dark(var(--mantine-color-blue-1), var(--mantine-color-gray-7));
-}
-
-.node:global(.isSelected) {
-    border-radius: 0;
-
-    background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-6));
-/*
-    color: white;
-
- // background-color: light-dark(
-  //  var(--mantine-color-gray-0),
-   // var(--mantine-color-dark-6)
-  //);
-  //background: rgb(20, 127, 250, 0.5);*/
-}
-
-.node:global(.isSelectedStart.isSelectedEnd) {
-    border-radius: 4px;
-}
-
-.row:focus .node:global(.isSelected) {
-    background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-5));
-}
-
-.row:focus .node:global(.isFocused) {
-    background-color: light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-5));
-}
-
-.row {
-    white-space: nowrap;
-    cursor: pointer;
-}
-
-.row:focus {
-    outline: none;
-}
-
-.row:focus .node {
-    /** come back to this **/
-   /* background-color: light-dark(var(--mantine-color-red-2), var(--mantine-color-dark-5));*/
-}
 
 .icon {
     margin: 0 rem(10px);
@@ -95,8 +59,12 @@
 
 .text {
     flex: 1;
+    /* min-width: 0 lets a flex child shrink below its content size — required
+       for text-overflow: ellipsis on flex items. */
+    min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
+    white-space: nowrap;
     font-size: rem(14px);
     font-weight: 500;
 }
@@ -108,3 +76,113 @@
 [role="treeitem"] {
     padding-bottom: 2px;
 }
+
+/* Strip the browser's default <ul> bullet + indent from the DocTree
+   <ul role="tree"> and nested <ul role="group"> nodes. The tree's own indent
+   is driven by paddingLeft on .rowWrapper. */
+[role="tree"],
+[role="tree"] [role="group"] {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+/* ---- pragmatic-tree additions ---- */
+
+.rowWrapper {
+    position: relative;
+    display: flex;
+    align-items: center;
+    border-radius: 4px;
+}
+
+.node[data-dragging="true"] {
+    opacity: 0.4;
+}
+
+.node:focus-visible {
+    outline: 2px solid light-dark(
+        var(--mantine-color-blue-5),
+        var(--mantine-color-blue-4)
+    );
+    outline-offset: -2px;
+}
+
+.node :focus-visible {
+    outline-offset: -2px;
+}
+
+.node[data-selected="true"] {
+    background-color: light-dark(
+        var(--mantine-color-gray-3),
+        var(--mantine-color-dark-6)
+    );
+}
+
+.node[data-selected="true"] .actions {
+    opacity: 1;
+    pointer-events: auto;
+}
+
+.node[data-receiving-drop="make-child"] {
+    background-color: light-dark(
+        var(--mantine-color-blue-1),
+        rgba(56, 139, 253, 0.15)
+    );
+    outline: 2px solid light-dark(
+        var(--mantine-color-blue-5),
+        var(--mantine-color-blue-7)
+    );
+    outline-offset: -1px;
+}
+
+.node[data-receiving-drop="make-child-blocked"] {
+    outline-color: light-dark(
+        var(--mantine-color-red-5),
+        var(--mantine-color-red-7)
+    );
+}
+
+.dropLine {
+    position: absolute;
+    left: var(--drop-line-indent, 0);
+    right: 8px;
+    height: 2px;
+    background: light-dark(
+        var(--mantine-color-blue-5),
+        var(--mantine-color-blue-4)
+    );
+    pointer-events: none;
+    z-index: 1;
+}
+
+.dropLine::before {
+    content: "";
+    position: absolute;
+    left: -4px;
+    top: -3px;
+    width: 8px;
+    height: 8px;
+    border: 2px solid currentColor;
+    border-radius: 50%;
+    color: light-dark(
+        var(--mantine-color-blue-5),
+        var(--mantine-color-blue-4)
+    );
+    background: var(--mantine-color-body);
+}
+
+.dropLine[data-blocked="true"] {
+    background: light-dark(
+        var(--mantine-color-red-5),
+        var(--mantine-color-red-4)
+    );
+}
+
+.dropLine[data-edge="top"] {
+    top: -1px;
+}
+
+.dropLine[data-edge="bottom"] {
+    bottom: -1px;
+}