"use client";

/**
 * PageView — the editor surface for one page:
 *
 * - Header: icon + inline title (PATCH page) + meta (updated, author).
 * - Block list: top-level blocks sorted client-side by fractional position;
 *   each renders via <BlockRenderer>. Nested content (toggle, columns,
 *   synced) is loaded lazily per block type by the renderer.
 * - Trailing empty area: click → creates + focuses a new paragraph.
 * - Drag & drop (dnd-kit): a drop rewrites only the moved block's position
 *   (fractional midpoint, via useMoveBlock) — no reindexing (invariant 4).
 * - Keyboard: Enter in a text block → new sibling; ArrowUp/Down at the
 *   block boundary → previous/next block; Cmd/Ctrl+Z → Tiptap history
 *   (inside the editor); Delete on a selected, non-editing row removes it.
 * - Deep link: focusBlockId scrolls to + highlights the target block.
 */
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useParams } from "next/navigation";
import {
  DndContext,
  PointerSensor,
  KeyboardSensor,
  closestCenter,
  useSensor,
  useSensors,
  type DragEndEvent,
} from "@dnd-kit/core";
import {
  SortableContext,
  arrayMove,
  sortableKeyboardCoordinates,
  useSortable,
  verticalListSortingStrategy,
} from "@dnd-kit/sortable";
import { CSS } from "@dnd-kit/utilities";
import { Clock, FolderOpen, Image as ImageIcon, Link2, MessageSquare, Smile, Sparkles } from "lucide-react";
import { useBacklinks, usePage, usePageBlocks, useUpdatePage } from "@/hooks/use-pages";
import { useWorkspace } from "@/hooks/use-workspace";
import { useDeleteBlock, useInsertBlock, useMoveBlock, useMergedBlocks } from "@/hooks/use-blocks";
import { isEmptyTextBlock, isContentEmpty, isAutoCleanableType } from "@/lib/block-content";
import { getBlockBatchQueue } from "@/lib/batch-queue";
import { usePagePresence } from "@/hooks/use-presence";
import { usePresenceAnnouncer } from "@/hooks/use-presence-announcer";
import { usePresenceToasts } from "@/hooks/use-presence-toasts";
import { useEditorStore } from "@/stores/editor-store";
import { useCommentPillStore } from "@/stores/comment-pill-store";
import { toast, useUiStore } from "@/stores/ui-store";
import { useAuthStore } from "@/lib/auth-store";
import { realtime } from "@/lib/realtime";
import { CommentPanel } from "@/components/comments/comment-panel";
import { RelatedPanel } from "./related-panel";
import { cn, formatRelativeTime, sortByPosition } from "@/lib/utils";
import { useFileUploads } from "@/lib/files/use-file-uploads";
import { BLOCK_TYPE_LABELS } from "@/lib/constants";
import { PresenceBar } from "@/components/collaboration/PresenceBar";
import { CursorLayer } from "@/components/collaboration/CursorLayer";
import { FilePicker } from "@/components/files/FilePicker";
import { BlockRenderer } from "./block-renderer";
import { BlockToolbar } from "./block-toolbar";
import { ContextMenu } from "./context-menu";
import { InsertDialog } from "./insert-dialog";
import { TemplateDialog } from "./template-dialog";
import { SelectionToolbar } from "./selection-toolbar";
import { WritingDialog } from "@/components/ai/writing-diff";
import { ReviewBanner } from "./review-banner";
import { blockApi, templateApi, type BatchBlockOp } from "@/lib/api";
import { useQueryClient } from "@tanstack/react-query";
import {
  htmlHasBlockStructure,
  pasteHtmlToBlocks,
  parseClipboardText,
  type PastedBlockSpec
} from "@/lib/clipboard-import";
import type { WritingAction } from "@/lib/ai";
import type { Block } from "@/lib/types";
import type { SlashCommand } from "./slash-menu";

interface PageViewProps {
  pageId: string;
  focusBlockId?: string | null;
}

export function PageView({ pageId, focusBlockId }: PageViewProps) {
  const qc = useQueryClient();
  const { data: page } = usePage(pageId);
  const { data: serverBlocks } = usePageBlocks(pageId, null);
  const blocks = useMergedBlocks(pageId, serverBlocks ?? []);
  const sorted = useMemo(() => sortByPosition(blocks), [blocks]);
  // Every page carries a title block (properties.isTitle). The Home empty-state
  // card means "no CONTENT yet" — so count content blocks (title excluded); a
  // freshly created page has exactly the title and shows the card.
  const contentBlockCount = useMemo(
    () => sorted.filter((b) => b.properties?.isTitle !== true).length,
    [sorted],
  );

  // TASK-0126 — the "Generate page with AI" entry points (header button + Home
  // empty-state card) need EDIT; hidden for GUEST (the server still returns
  // 403 — this is the UI gate, AC item 6). The role comes from the workspace
  // loaded by the [workspace] layout (React Query cache hit).
  const wsParams = useParams<{ workspace: string }>();
  const { data: wsRoleData } = useWorkspace(wsParams?.workspace ?? "");
  const canGenerate = (wsRoleData?.role ?? "").toLowerCase() !== "guest";

  // Presence (TASK-0093): the page's OTHER peers (self excluded by the
  // server + defensively below), the a11y live-region text (≤ 1/s, state
  // changes only), the join/leave toasts (the ui-store toggle, default on),
  // and a block-id → type-label map for the bar's "editing Heading 1".
  const selfUserId = useAuthStore((s) => s.user?.id ?? null);
  const presence = usePagePresence(pageId);
  const others = useMemo(
    () => (selfUserId ? presence.filter((p) => p.userId !== selfUserId) : presence),
    [presence, selfUserId],
  );
  const announcement = usePresenceAnnouncer(pageId, selfUserId);
  usePresenceToasts(pageId, selfUserId);
  const blockTypeFor = useCallback(
    (blockId: string) => {
      const b = blocks.find((x) => x.id === blockId);
      return b ? BLOCK_TYPE_LABELS[b.type] : null;
    },
    [blocks],
  );
  const blockIds = useMemo(() => sorted.map((b) => b.id), [sorted]);

  // T-194 — the seeded title block (properties.isTitle) is NOT body content:
  // the header's `page-title` contenteditable is the canonical title (it PATCHes
  // the page and the server syncs the title block's text). The render loop maps
  // only REAL content blocks, so a fresh page (just the title) shows an empty
  // canvas + the `new-block` trailing surface — clicking it creates + focuses
  // the first paragraph (onTrailingAreaClick), which is where the slash menu
  // and typing begin. Consistent with the two existing isTitle exclusions
  // (contentBlockCount above; handleEmptyBlur's skip). `sorted` stays
  // title-inclusive for position math (drag/drop, focusSibling, slash anchor).
  const renderBlocks = useMemo(() => sorted.filter((b) => b.properties?.isTitle !== true), [sorted]);

  const updatePage = useUpdatePage(page?.workspaceId ?? "");
  const insertBlock = useInsertBlock(pageId);
  const moveBlock = useMoveBlock(pageId);
  const deleteBlock = useDeleteBlock(pageId);
  const { setSelection } = useEditorStore();
  const storeSelected = useEditorStore((s) => s.selectedBlockId);

  // TASK-0103 — upload paths (a) drag-drop from the OS and (b) paste an
  // image. Both funnel into the SAME upload service (useFileUploads →
  // lib/files/upload.ts): pre-check → presigned session → XHR PUT (progress
  // on the block) → complete → poll. The raw-`src` paths in the insert dialog
  // / legacy blocks are untouched.
  const { start: startUpload } = useFileUploads(page?.workspaceId ?? null, pageId);
  const [fileDragActive, setFileDragActive] = useState(false);
  const fileDragDepth = useRef(0);
  const lastDropPosition = useRef<string | null>(null);
  const sortedRef = useRef(sorted);
  sortedRef.current = sorted;

  const dropTargetPosition = useCallback(
    (clientY: number): string | null => {
      // nearest block ABOVE the pointer → insert after it (null = end)
      const els = Array.from(
        pageRef.current?.querySelectorAll<HTMLElement>("[data-block-id]") ?? [],
      );
      let best: string | null = null;
      let bestDist = Infinity;
      for (const el of els) {
        const rect = el.getBoundingClientRect();
        if (clientY < rect.top) continue; // the pointer is above this block
        const dist = clientY - rect.top;
        if (dist < bestDist) {
          bestDist = dist;
          best = el.dataset.blockId ?? null;
        }
      }
      if (!best) return null;
      const above = sortedRef.current.find((b) => b.id === best);
      return above ? above.position : null;
    },
    // pageRef is stable
    [],
  );

  const onFilesDropped = useCallback(
    async (e: React.DragEvent) => {
      e.preventDefault();
      fileDragDepth.current = 0;
      setFileDragActive(false);
      const files = Array.from(e.dataTransfer?.files ?? []);
      if (files.length === 0) return;
      const position = dropTargetPosition(e.clientY);
      lastDropPosition.current = position;
      for (const file of files) {
        await startUpload(file, { parentId: null, position });
      }
    },
    [startUpload, dropTargetPosition],
  );

  const onDragEnter = useCallback((e: React.DragEvent) => {
    if (!e.dataTransfer?.types?.includes("Files")) return;
    fileDragDepth.current += 1;
    setFileDragActive(true);
  }, []);
  const onDragOver = useCallback((e: React.DragEvent) => {
    if (fileDragActive) e.preventDefault(); // allow the drop
  }, [fileDragActive]);
  const onDragLeave = useCallback(() => {
    fileDragDepth.current = Math.max(0, fileDragDepth.current - 1);
    if (fileDragDepth.current === 0) setFileDragActive(false);
  }, []);

  /**
   * Focus a freshly created block: it is not in the DOM yet (the list
   * refetches after the mutation), so the retry effect below scrolls to it
   * once it lands in the sorted list. (Declared before the paste handler —
   * the paste path focuses the first pasted block the same way.)
   */
  const focusNewBlock = useCallback((id: string) => {
    setFocusTarget(id);
    pendingFocus.current = id;
    hasScrolledFocus.current = true;
  }, []);

  // (b) paste:
  //  - image blob → upload at the selected block;
  //  - structural HTML (Notion/Word/Docs: lists, toggles, headings, quotes)
  //    → BLOCK-level import (lib/clipboard-import) preserving indentation and
  //    toggle parent-child structure (the QA "copy from Notion" case);
  //  - the app's internal clipboard payload (multi-block copy) → block import.
  // Plain inline text/HTML stays with the focused InlineEditor (ProseMirror's
  // native inline paste) — we never hijack a text-only paste.
  const runPasteImport = useCallback(
    async (specs: PastedBlockSpec[], anchorBlockId: string | null) => {
      // Anchor: the selected block's LAST DESCENDANT (paste under a TOGGLE
      // lands INSIDE it — matching where the caret is); otherwise top-level.
      // The page list is top-level only (depth 1), so the anchor's own
      // descendants are fetched on demand (bounded: one subtree).
      const sorted = sortedRef.current;
      const anchor = anchorBlockId ? sorted.find((b) => b.id === anchorBlockId) ?? null : null;
      let anchorAfter: string | null = null;
      if (anchor) {
        anchorAfter = anchor.id;
        try {
          // Walk the last-child chain (one direct-children fetch per level;
          // the list is position-sorted → last element = last sibling).
          let deepest = anchor.id;
          for (let d = 0; d < 8; d += 1) {
            const kids = await blockApi.list(pageId, { parentId: deepest });
            const last = kids[kids.length - 1];
            if (!last) break;
            deepest = last.id;
            if (deepest === anchor.id) break;
          }
          anchorAfter = deepest;
        } catch {
          /* fall back to anchoring at the block itself */
        }
      }

      // ONE op per spec (parents precede their children in document order —
      // the parser guarantees it), chained: each block lands after the
      // PREVIOUSLY PASTED sibling (first in a parent group: after the parent
      // itself / the page anchor). The server assigns the fractional
      // position per op (same transaction, FIFO). Chaining per sibling group
      // (not all to the anchor) keeps the source order: two inserts "after
      // the same anchor" inside one tx would interleave reversed.
      const lastInGroup = new Map<string, string>(); // parentId (or "__top__") → last pasted id
      const ops: BatchBlockOp[] = specs.map((s) => {
        const groupKey = s.parentId ?? "__top__";
        const chainFrom = lastInGroup.get(groupKey) ?? (s.parentId ?? anchorAfter);
        lastInGroup.set(groupKey, s.id);
        return {
          op: "upsert" as const,
          block: {
            id: s.id,
            type: s.type,
            content: s.content,
            ...(s.properties ? { properties: s.properties } : { properties: {} }),
            parentId: s.parentId ?? null,
            ...(chainFrom ? { afterBlockId: chainFrom } : {})
          }
        };
      });

      // The batch endpoint caps at 200 ops → chunk (preserving order).
      try {
        for (let i = 0; i < ops.length; i += 200) {
          await blockApi.batch(pageId, ops.slice(i, i + 200));
        }
        qc.invalidateQueries({ queryKey: ["pages", pageId, "blocks"] });
        toast("success", `Pasted ${specs.length} block${specs.length === 1 ? "" : "s"}`);
        // Focus the first top-level pasted block (it is in the DOM after the
        // invalidation refetch — the pendingFocus retry effect handles it).
        const firstRoot = specs.find((s) => s.parentId === null);
        if (firstRoot) focusNewBlock(firstRoot.id);
      } catch (err) {
        toast("error", "Paste failed", err instanceof Error ? err.message : undefined);
      }
    },
    [pageId, focusNewBlock]
  );

  useEffect(() => {
    const onPaste = (e: ClipboardEvent) => {
      if (useEditorStore.getState().activePageId !== pageId) return;
      const cd = e.clipboardData;
      if (!cd) return;

      // 1) image blob wins (unchanged legacy path).
      const fileItem = Array.from(cd.items ?? []).find((i) => i.kind === "file" && i.type.startsWith("image/"));
      if (fileItem) {
        const file = fileItem.getAsFile();
        if (file) {
          e.preventDefault();
          const selected = useEditorStore.getState().selectedBlockId;
          const anchor = sortedRef.current.find((b) => b.id === selected);
          void startUpload(file, { parentId: null, position: anchor ? anchor.position : null });
          return;
        }
      }

      // 2) internal payload (our Copy, incl. subtree) — highest fidelity.
      const internal = parseClipboardText(cd.getData("text/plain"));
      if (internal) {
        e.preventDefault();
        void runPasteImport(internal, useEditorStore.getState().selectedBlockId);
        return;
      }

      // 3) structural HTML from other apps (Notion/Word/Docs).
      const html = cd.getData("text/html");
      if (html && htmlHasBlockStructure(html)) {
        e.preventDefault();
        const specs = pasteHtmlToBlocks(html);
        if (specs.length > 0) void runPasteImport(specs, useEditorStore.getState().selectedBlockId);
        return;
      }
      // otherwise: inline text paste → the focused editor handles it.
    };
    window.addEventListener("paste", onPaste);
    return () => window.removeEventListener("paste", onPaste);
  }, [pageId, startUpload, runPasteImport]);

  const [filesPickerOpen, setFilesPickerOpen] = useState(false);
  const [focusTarget, setFocusTarget] = useState<string | null>(null);
  const [menu, setMenu] = useState<{ x: number; y: number; block: Block } | null>(null);
  // TASK-0038 icon/cover pickers (T-192).
  const [iconPickerOpen, setIconPickerOpen] = useState(false);
  const [coverPickerOpen, setCoverPickerOpen] = useState(false);
  // The title is a contenteditable (NOT an <input>): the E2E contract reads
  // it via toContainText (tests/README `page-title` = "editable text"), which
  // only matches an element's TEXT CONTENT — an input's title lives in the
  // `value` attribute and would never match (T-192). Text is set
  // imperatively so React re-renders don't fight the caret; we re-sync from
  // the server only while the field is NOT focused.
  const titleRef = useRef<HTMLDivElement>(null);
  useEffect(() => {
    const el = titleRef.current;
    if (!el) return;
    if (document.activeElement === el) return; // don't clobber the caret mid-edit
    el.textContent = page?.title ?? "";
  }, [page?.id, page?.title]);
  // T-192: the title commit is DEBOUNCED — one commit per typing burst,
  // flushed on blur/Enter/Escape/unmount. Committing on every keystroke fired
  // N concurrent PATCHes the server applies in arbitrary order, so an
  // intermediate partial ("Chil") could overwrite the final "Child Page"
  // (the UI shows the DOM text while the server holds the stale partial — the
  // nested E2E flaked on exactly this). The commit targets the route `pageId`
  // (always current, unlike `page?.id` which lags the load), so it is correct
  // even before the page query resolves.
  const titleCommitTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const commitTitleNow = () => {
    if (titleCommitTimer.current) {
      clearTimeout(titleCommitTimer.current);
      titleCommitTimer.current = null;
    }
    const el = titleRef.current;
    if (!el) return;
    updatePage.mutate({ id: pageId, title: el.textContent ?? "" });
  };
  const commitTitleRef = useRef(commitTitleNow);
  commitTitleRef.current = commitTitleNow;
  useEffect(() => {
    // Flush a pending title when leaving the page (soft navigation unmounts
    // without a blur) so the last-typed value still wins.
    return () => {
      if (titleCommitTimer.current) {
        clearTimeout(titleCommitTimer.current);
        titleCommitTimer.current = null;
      }
      const el = titleRef.current;
      if (el && el.textContent) commitTitleRef.current();
    };
  }, []);
  const [insert, setInsert] = useState<{
    block: Block;
    tab: "image" | "link" | "table" | "database";
  } | null>(null);
  const [templateOpen, setTemplateOpen] = useState(false);
  const [commentsOpen, setCommentsOpen] = useState(false);
  // T-140: the "Related" (backlinks) slide-over.
  const [relatedOpen, setRelatedOpen] = useState(false);
  const backlinks = useBacklinks(pageId);
  const setAiPanel = useUiStore((s) => s.setAiPanel);
  const setGenerate = useUiStore((s) => s.setGenerate);
  const commentPill = useCommentPillStore((s) => s.byPage[pageId] ?? 0);
  const pageRef = useRef<HTMLDivElement>(null);
  const useCommentsOpenRef = useRef(commentsOpen);
  useEffect(() => {
    useCommentsOpenRef.current = commentsOpen;
  }, [commentsOpen]);
  const pendingFocus = useRef<string | null>(null);
  const hasScrolledFocus = useRef(false);

  // TASK-0094 R2 — the "New comments (n)" pill: a `comment.event` frame
  // (created / replied) for this page bumps the pill while the panel is
  // CLOSED. The socket + the `page:<id>` channel are open (the page layout's
  // usePageRealtime) — the same connection. Opening the panel clears the
  // pill (the panel refetches, showing the new comments).
  useEffect(() => {
    const off = realtime.on("comment.event", (frame) => {
      if (frame.type !== "comment.event" || frame.pageId !== pageId) return;
      if (frame.kind !== "created" && frame.kind !== "replied") return;
      if (useCommentsOpenRef.current) return; // the panel shows it live
      useCommentPillStore.getState().add(pageId);
    });
    return () => off();
  }, [pageId]);

  // Single-block selection (the store is the source of truth — set by row
  // clicks, deep links and the AI panel). `storeSelected` is null until the
  // first selection; the row ring + the Delete-on-Backspace key use it.
  const selectedBlockId = storeSelected;

  // TASK-0123 — multi-block selection (the writing tools' entry point).
  // ⌘/Ctrl+click toggles a row into the set; Shift+click selects the range
  // from the last anchor; a plain click keeps the existing single-selection
  // behavior (backward compatible). The set is page-scoped (cleared on page
  // change) and drives the floating SelectionToolbar.
  const selectedBlockIds = useEditorStore((s) => s.selectedBlockIds);
  const toggleSelected = useEditorStore((s) => s.toggleSelected);
  const setManySelected = useEditorStore((s) => s.setManySelected);
  const shiftAnchorId = useRef<string | null>(null);
  const [writing, setWriting] = useState<{
    open: boolean;
    action: WritingAction;
    language?: string;
    blockIds: string[];
  }>({ open: false, action: "summarize", blockIds: [] });

  const selectedBlocks = useMemo(() => {
    const byId = new Map(sorted.map((b) => [b.id, b]));
    return selectedBlockIds.map((id) => byId.get(id)).filter((b): b is Block => !!b);
  }, [selectedBlockIds, sorted]);

  // The dialog's blocks: resolve the requested ids against the FULL page
  // list (not just the multi-selection — the context-menu path opens for a
  // single block that was never added to the selection).
  const dialogBlocks = useMemo(
    () => sorted.filter((b) => writing.blockIds.includes(b.id)),
    [sorted, writing.blockIds]
  );

  const openWriting = useCallback(
    (action: WritingAction, blockIds: string[], language?: string) => {
      setWriting({ open: true, action, language, blockIds });
    },
    []
  );

  /** Handle a row selection, honoring the modifier keys for multi-select. */
  const selectRow = useCallback(
    (id: string, e?: { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean }) => {
      if (e?.metaKey || e?.ctrlKey) {
        // toggle into the multi-selection
        const next = selectedBlockIds.includes(id)
          ? selectedBlockIds.filter((x) => x !== id)
          : [...selectedBlockIds, id];
        setManySelected(next);
        shiftAnchorId.current = id;
        setSelection(id);
        return;
      }
      if (e?.shiftKey && shiftAnchorId.current) {
        // range from the anchor to this row
        const a = sorted.findIndex((b) => b.id === shiftAnchorId.current);
        const b = sorted.findIndex((x) => x.id === id);
        if (a !== -1 && b !== -1) {
          const [lo, hi] = a < b ? [a, b] : [b, a];
          setManySelected(sorted.slice(lo, hi + 1).map((x) => x.id));
        } else {
          setManySelected([id]);
        }
        setSelection(id);
        return;
      }
      // plain click: the existing single-selection toggle (backward compat).
      setSelection(id === selectedBlockId ? null : id);
      shiftAnchorId.current = id;
    },
    [selectedBlockIds, selectedBlockId, sorted, setManySelected, setSelection]
  );

  const clearSelection = useCallback(() => {
    setManySelected([]);
    shiftAnchorId.current = null;
  }, [setManySelected]);

  const scrollAndFlash = useCallback((id: string) => {
    const el = pageRef.current?.querySelector<HTMLElement>(`[data-block-id="${id}"]`);
    if (!el) return false;
    el.scrollIntoView({ block: "center", behavior: "smooth" });
    el.classList.add("block-focus-flash");
    setTimeout(() => el.classList.remove("block-focus-flash"), 1600);
    return true;
  }, []);

  // Deep link (route [block] segment or ?focus=): scroll + flash the target.
  // The block may not be in the DOM yet (fresh query / just-created block),
  // so the scroll is retried until it appears in the sorted list.
  useEffect(() => {
    const target = focusBlockId ?? useEditorStore.getState().focusBlockId;
    if (!target) return;
    if (hasScrolledFocus.current && target === pendingFocus.current) return;
    hasScrolledFocus.current = true;
    pendingFocus.current = target;
    const t = setTimeout(() => {
      if (scrollAndFlash(target)) {
        pendingFocus.current = null;
        setFocusTarget(target);
        useEditorStore.getState().setFocus(null);
      }
    }, 80);
    return () => clearTimeout(t);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [focusBlockId, page]);

  // Retry focus once the (re)sorted list contains the pending block.
  useEffect(() => {
    if (!pendingFocus.current) return;
    if (!sorted.some((b) => b.id === pendingFocus.current)) return;
    const t = setTimeout(() => {
      if (scrollAndFlash(pendingFocus.current as string)) {
        setFocusTarget(pendingFocus.current);
        pendingFocus.current = null;
      }
    }, 40);
    return () => clearTimeout(t);
  }, [sorted, scrollAndFlash]);

  // Slash-menu command: insert a sibling block after the one the menu was
  // opened in. Plain types go straight to the API; media/database open the
  // insert dialog; "template" opens the template picker.
  const onSlashPick = useCallback(
    async (command: SlashCommand, context: { parentId: string | null; position: string }) => {
      // The slash menu is opened INSIDE a block: resolve that block (the
      // anchor) and hand the hook its ID — the API's resolvePosition owns the
      // fractional position (client-side position math threw on server
      // base-62 positions). If the anchor is gone (stale sort), fall back to
      // an append at the end of the same parent.
      const anchor = sorted.find(
        (b) => b.position === context.position && b.parentId === context.parentId,
      );
      if (command.blockType) {
        try {
          const created = await insertBlock.mutateAsync({
            parentId: context.parentId,
            afterBlockId: anchor?.id ?? null,
            type: command.blockType,
          });
          focusNewBlock(created.id);
        } catch (e) {
          toast("error", "Insert failed", e instanceof Error ? e.message : undefined);
        }
        return;
      }
      if (command.special === "image") {
        // One-step image insert: open the insert dialog's Image tab (file
        // picker → presigned upload → image block with the signed URL). The
        // anchor is the block the menu was opened in.
        if (anchor) setInsert({ block: anchor, tab: "image" });
      } else if (command.special === "table") {
        // Open the insert dialog's Table tab (rows × cols → grid pre-created).
        // A bare table block has no columns/rows — the renderer draws nothing.
        if (anchor) setInsert({ block: anchor, tab: "table" });
      } else if (command.special === "database") {
        // The dialog needs the concrete anchor block (its id/parentId).
        if (anchor) setInsert({ block: anchor, tab: "database" });
      } else if (command.special === "template") {
        setTemplateOpen(true);
      } else if (command.special === "synced") {
        // Synced blocks reference a target page/block; MVP inserts an empty
        // synced block the user links afterwards (targetPageId property).
        try {
          await insertBlock.mutateAsync({
            parentId: context.parentId,
            afterBlockId: anchor?.id ?? null,
            type: "synced_block",
            properties: { targetPageId: null, targetBlockId: null },
          });
        } catch (e) {
          toast("error", "Insert failed", e instanceof Error ? e.message : undefined);
        }
      }
    },
    [insertBlock, sorted, focusNewBlock],
  );

  const createSibling = useCallback(
    (afterBlock: Block | null) => {
      // Anchor by block ID (the server computes the position); null anchor →
      // append after the last top-level sibling.
      void insertBlock
        .mutateAsync({
          parentId: null,
          afterBlockId: afterBlock?.id ?? null,
          type: "paragraph",
        })
        .then((created) => focusNewBlock(created.id));
    },
    [insertBlock, focusNewBlock],
  );

  /** Focus a block row's editable region (Tiptap contenteditable, the todo
   *  checkbox, a button or a link) — the shared caret mover for
   *  ArrowUp/Down navigation and the blank-area click (see
   *  `onTrailingAreaClick`). */
  const focusBlockEditable = useCallback((blockId: string) => {
    const el = pageRef.current?.querySelector<HTMLElement>(
      `[data-block-id="${blockId}"] [contenteditable], [data-block-id="${blockId}"] input[type="checkbox"], [data-block-id="${blockId}"] button, [data-block-id="${blockId}"] a`,
    );
    el?.focus();
  }, []);

  /** TASK-0136 — the trailing blank area. Notion semantics: the area is a
   *  "keep typing" surface, not a "add a row" button.
   *
   *   - The page's LAST block is an EMPTY text block (paragraph / heading /
   *     list / quote / callout / todo — NOT the title, NOT media/structural)
   *     → focus THAT block. This is what stops the reported pile-up:
   *     clicking the blank area with nothing typed reuses the empty row
   *     instead of stacking another one behind it.
   *   - Otherwise (last block has content, is media/structural, or the page
   *     is empty) → create + focus a fresh paragraph, exactly as before.
   */
  const onTrailingAreaClick = useCallback(() => {
    const last = sortedRef.current[sortedRef.current.length - 1] ?? null;
    if (last && isEmptyTextBlock(last)) {
      focusBlockEditable(last.id);
      return;
    }
    createSibling(last);
  }, [createSibling, focusBlockEditable]);

  const focusSibling = useCallback(
    (from: Block, dir: -1 | 1) => {
      const idx = sorted.findIndex((b) => b.id === from.id);
      const next = sorted[idx + dir];
      if (next) {
        focusBlockEditable(next.id);
      } else if (dir === 1) {
        createSibling(from);
      }
    },
    [sorted, createSibling, focusBlockEditable],
  );

  /** TASK-0136 — empty-block cleanup (QA "blank-page input fields keep
   *  piling up"): a text block (paragraph / heading / list / quote /
   *  callout / todo) that LOSES FOCUS while still empty (nothing was
   *  typed) is deleted, so the input field disappears instead of leaving a
   *  blank row behind.
   *
   *  Two guards, two sources of truth:
   *   - TYPE + TITLE come from the stored block: `isAutoCleanableType`
   *     (text types only — never media/structural) and `isTitle` (the
   *     page-title block is protected).
   *   - EMPTINESS comes from the editor's LIVE html (the blur argument):
   *     the stored content lags behind the 500 ms debounce window and is
   *     the empty `{}` default on a freshly created block, so it cannot
   *     answer "did the user type anything and then clear it?" — the live
   *     html can. If the live html has real content the block stays.
   *
   *  Deleting the last content block is fine: a page with only its title
   *  is the intended empty state, and the trailing area stays clickable. */
  const handleEmptyBlur = useCallback(
    (block: Block, html: string) => {
      if (block.properties?.isTitle === true) return;
      if (!isAutoCleanableType(block.type)) return;
      // Never clean up the anchor of an OPEN insert dialog (table/image/
      // database/link): it is the dialog's insertion point (`afterBlockId`).
      // The slash pick that opened the dialog cleared this block, so it is
      // empty and would blur-delete the moment focus moves into the dialog —
      // leaving the dialog's insertBlock({afterBlockId}) pointing at a
      // deleted id (404, dialog never closes). Leave the block while it is
      // the anchor (matches pre-TASK-0136 behavior for the dialog flow).
      if (insert && insert.block.id === block.id) return;
      const live = typeof html === "string" ? html : "";
      if (live !== "" && !isContentEmpty(live)) return;
      // The blur save (saveNow) may have raced ahead of this cleanup, or a
      // queued 500 ms batch may still carry this block's content — drop the
      // pending ops so the flush never `update`s an id we are deleting
      // (the batch endpoint 400s on a missing id and aborts the whole batch).
      getBlockBatchQueue(pageId).dropBlock(block.id);
      deleteBlock.mutate(block.id, {
        onError: (e: Error) => toast("error", "Delete failed", e.message),
      });
    },
    [pageId, deleteBlock, insert],
  );

  const onDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;
    if (!over || active.id === over.id) return;
    const oldIndex = sorted.findIndex((b) => b.id === active.id);
    const newIndex = sorted.findIndex((b) => b.id === over.id);
    if (oldIndex < 0 || newIndex < 0) return;
    const moved = arrayMove(sorted, oldIndex, newIndex);
    const block = moved[newIndex];
    const prev = moved[newIndex - 1];
    const next = moved[newIndex + 1];
    if (!block) return;
    // TASK-0135: delegate the position to the SERVER. The web's base-36 shared
    // engine rejected the API's base-62 positions (uppercase, e.g. "Zz") and
    // `positionForInsert` threw on every reorder of an API-created page — DnD
    // was 100% broken. The server resolves the position from the neighbor
    // block ids with its own canonical base-62 engine (blocks.service
    // `resolvePosition`). Server semantics: `afterBlockId` = insert AFTER that
    // block (it sits ABOVE the new slot), `beforeBlockId` = insert BEFORE it
    // (it sits BELOW the new slot) — verified against the live endpoint.
    moveBlock.mutate(
      {
        id: block.id,
        parentId: null,
        afterBlockId: prev?.id ?? null,
        beforeBlockId: next?.id ?? null,
      },
      { onError: (e: Error) => toast("error", "Move failed", e.message) },
    );
  };

  const sensors = useSensors(
    useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
    // TASK-0100 S5: `sortableKeyboardCoordinates` is a keyboard
    // coordinate-GETTER, not a sensor — passing it bare to useSensor made
    // `Sensor.activators` undefined and crashed DndContext ("reading 'map'").
    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
  );

  // Delete key removes a selected block that is not currently being edited.
  const onKeyDown = (e: React.KeyboardEvent) => {
    if (e.key !== "Delete" || !selectedBlockId) return;
    const target = e.target as HTMLElement;
    if (target.isContentEditable || target.tagName === "INPUT" || target.tagName === "TEXTAREA")
      return;
    e.preventDefault();
    deleteBlock.mutate(selectedBlockId, {
      onSuccess: () => setSelection(null),
    });
  };

  // Numbered runs: consecutive `numbered` blocks share a 1-based counter.
  const numberedIndices = useMemo(() => {
    const map = new Map<string, number>();
    let count = 0;
    for (const b of sorted) {
      if (b.type === "numbered_list") {
        count += 1;
        map.set(b.id, count);
      } else {
        count = 0;
      }
    }
    return map;
  }, [sorted]);

  return (
    <div
      ref={pageRef}
      data-testid="editor-root"
      data-page-view
      className="editor-page relative mx-auto w-full max-w-3xl px-12 pb-48"
      onClick={(e) => {
        if (e.target === e.currentTarget) {
          setSelection(null);
          setManySelected([]);
        }
      }}
      onKeyDown={onKeyDown}
      onDragEnter={onDragEnter}
      onDragOver={onDragOver}
      onDragLeave={onDragLeave}
      onDrop={onFilesDropped}
      data-file-drop={fileDragActive ? "active" : undefined}
    >
      {/* TASK-0103 (a): the drag-drop indicator — a full-canvas overlay while
          an OS file drag is over the page (the block list is untouched, so
          dnd-kit's block-reorder drag is unaffected). */}
      {fileDragActive ? (
        <div
          className="pointer-events-none fixed inset-0 z-40 flex items-start justify-center bg-primary/5 p-6"
          aria-hidden
        >
          <div className="rounded-md border-2 border-dashed border-primary bg-background/90 px-4 py-2 text-sm font-medium text-primary shadow-sm">
            Drop to upload
          </div>
        </div>
      ) : null}
      {/* T-163: the review workflow banner (state chip + per-role actions;
          rendered for every state — including "No review yet" on fresh
          pages, which is where "Request review" starts). */}
      {page ? <ReviewBanner pageId={page.id} workspaceId={page.workspaceId} /> : null}
      {/* Header */}
      <header className="relative mb-4">
        {/* Cover band (TASK-0038, T-192): the visible `page-cover` — the
            selected gradient, above the icon/title row. */}
        {page?.cover ? (
          <div
            data-testid="page-cover"
            aria-hidden
            className="absolute inset-x-0 top-0 -z-10 h-20 rounded-xl"
            style={{ background: coverBackground(page.cover) }}
          />
        ) : null}
        <div className="flex items-start gap-3">
          {/* Icon (when set) + the icon-picker button; the cover-picker
              button sits beside them. Both persist via PATCH /pages/:id
              (`icon`, `coverUrl` — see useUpdatePage's field mapping). */}
          <div className="flex shrink-0 items-start gap-1.5 pt-1.5">
            {page?.icon ? (
              <span data-testid="page-icon" className="block text-4xl leading-none" aria-hidden>
                {page.icon}
              </span>
            ) : null}
            <div className="relative">
              <button
                type="button"
                data-testid="page-icon-button"
                aria-label="Change icon"
                title="Change icon"
                onClick={() => setIconPickerOpen((v) => !v)}
                className="rounded-md border border-border/60 p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground"
              >
                <Smile className="size-4" aria-hidden />
              </button>
              {iconPickerOpen && page ? (
                <IconPicker
                  onPick={(icon) => {
                    setIconPickerOpen(false);
                    updatePage.mutate({ id: page.id, icon });
                  }}
                />
              ) : null}
            </div>
            <div className="relative">
              <button
                type="button"
                data-testid="page-cover-picker"
                aria-label="Change cover"
                title="Change cover"
                onClick={() => setCoverPickerOpen((v) => !v)}
                className="rounded-md border border-border/60 p-1.5 text-muted-foreground hover:bg-accent hover:text-foreground"
              >
                <ImageIcon className="size-4" aria-hidden />
              </button>
              {coverPickerOpen && page ? (
                <CoverPicker
                  onPick={(cover) => {
                    setCoverPickerOpen(false);
                    updatePage.mutate({ id: page.id, cover });
                  }}
                />
              ) : null}
            </div>
          </div>
          <div className="min-w-0 flex-1">
            {/* `page-title` (tests/README): an editable TEXT surface — the
                E2E asserts toContainText, so the title is text content, not
                an input value. Commits on input (same as the old input's
                onChange) + on blur; Enter keeps the caret (no form submit). */}
            <div
              ref={titleRef}
              contentEditable
              suppressContentEditableWarning
              role="textbox"
              aria-label="Page title"
              data-testid="page-title"
              // The id the title currently commits to (page?.id) — lets tests
              // gate on "the child page is really loaded" (the persistent
              // contenteditable lags a client-side route change; a text-based
              // gate is unreliable, T-192 nested E2E).
              data-page-id={page?.id}
              onInput={() => {
                // Debounced commit (see titleCommitTimer): schedule a flush
                // 600ms after the last keystroke; blur/Enter/Escape flush
                // immediately. Never fires N concurrent PATCHes per title.
                if (titleCommitTimer.current) clearTimeout(titleCommitTimer.current);
                titleCommitTimer.current = setTimeout(() => commitTitleNow(), 600);
              }}
              onKeyDown={(e) => {
                if (e.key === "Enter") {
                  // Single-line title (the old <input> never took a newline).
                  // Flush the pending commit BEFORE blur (blur fires second
                  // and finds nothing pending).
                  commitTitleNow();
                  e.preventDefault();
                  (e.target as HTMLDivElement).blur();
                } else if (e.key === "Escape") {
                  // Flush too — the E2E convention commits on Escape (and a
                  // user pressing Escape has finished typing the title).
                  commitTitleNow();
                  (e.target as HTMLDivElement).blur();
                }
              }}
              onBlur={() => {
                commitTitleNow();
              }}
              className="w-full rounded-sm bg-transparent px-1 text-4xl font-bold tracking-tight outline-none empty:before:content-[attr(data-placeholder)] empty:before:text-muted-foreground"
              data-placeholder="Untitled"
            />
            <div className="mt-1.5 flex items-center gap-2 px-1 text-xs text-muted-foreground">
              {page ? (
                <>
                  <span className="inline-flex items-center gap-1">
                    <Clock className="size-3" aria-hidden />
                    Updated {formatRelativeTime(page.updatedAt)}
                  </span>
                  {page.createdByUser ? <span>· by {page.createdByUser.name}</span> : null}
                </>
              ) : null}
            </div>
          </div>
          {/* Presence (TASK-0093): the OTHERS' avatar bar — absent at 0
              others (the empty state). The live region (below) is the SR
              channel; the bar is a plain list with per-avatar names. */}
          <PresenceBar
            peers={others}
            selfUserId={selfUserId}
            blockTypeFor={blockTypeFor}
            className="mt-2 shrink-0"
          />
          {/* TASK-0094 R2 — the comment button + the realtime "New comments
              (n)" pill (bumped by comment.event frames while the panel is
              closed; cleared when it opens). */}
          <button
            type="button"
            data-testid="comment-button"
            className="relative mt-2 inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
            onClick={() => setCommentsOpen(true)}
            aria-label={
              commentPill > 0
                ? `Open comments (${commentPill} new)`
                : "Open comments"
            }
          >
            <MessageSquare className="size-3.5" aria-hidden />
            Comments
            {commentPill > 0 ? (
              <span
                className="inline-flex min-w-4 items-center justify-center rounded-full bg-primary px-1 text-[10px] font-semibold leading-4 text-primary-foreground"
                aria-hidden
              >
                {commentPill > 99 ? "99+" : commentPill}
              </span>
            ) : null}
          </button>
          {/* T-140 — Related: the pages that reference this one (backlinks).
              Mirrors the Comments button; opens a read-only slide-over. */}
          <button
            type="button"
            data-testid="related-button"
            className="relative mt-2 inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
            onClick={() => setRelatedOpen(true)}
            aria-label="Open related pages"
          >
            <Link2 className="size-3.5" aria-hidden />
            Related
            {(backlinks.data?.length ?? 0) > 0 ? (
              <span
                className="inline-flex min-w-4 items-center justify-center rounded-full bg-primary px-1 text-[10px] font-semibold leading-4 text-primary-foreground"
                aria-hidden
              >
                {backlinks.data!.length > 99 ? "99+" : backlinks.data!.length}
              </span>
            ) : null}
          </button>
          {/* TASK-0103 (4): the page file picker — insert an existing file as
              a block at the cursor (sidebar "Files" for the active page). */}
          <button
            type="button"
            data-testid="files-picker-toggle"
            onClick={() => setFilesPickerOpen((v) => !v)}
            aria-expanded={filesPickerOpen}
            className="relative mt-2 inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
          >
            <FolderOpen className="size-3.5" aria-hidden />
            Files
          </button>
          {/* TASK-0122 — Ask AI: opens the panel bound to this page (and the
              selected block, when one is highlighted). */}
          <button
            type="button"
            data-testid="ask-ai-button"
            onClick={() =>
              setAiPanel(true, {
                pageId,
                ...(selectedBlockId ? { blockId: selectedBlockId } : {}),
                ...(page?.title?.trim() ? { label: page.title } : {})
              })
            }
            className="relative mt-2 inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
            aria-label="Ask AI about this page"
          >
            <Sparkles className="size-3.5" aria-hidden />
            Ask AI
          </button>
          {/* TASK-0126 — Generate: opens the page-generation dialog (nested
              under this page when one is open). Hidden for GUEST (EDIT gate). */}
          {canGenerate ? (
            <button
              type="button"
              data-testid="generate-page-button"
              onClick={() => setGenerate(true, { parentId: pageId })}
              className="relative mt-2 inline-flex shrink-0 items-center gap-1.5 rounded-md border border-border px-2 py-1 text-xs text-foreground/80 hover:bg-accent hover:text-foreground"
              aria-label="Generate a page with AI"
            >
              <Sparkles className="size-3.5" aria-hidden />
              Generate
            </button>
          ) : null}
        </div>
      </header>

      {filesPickerOpen && page?.workspaceId ? (
        <FilePicker
          workspaceId={page.workspaceId}
          pageId={pageId}
          onClose={() => setFilesPickerOpen(false)}
        />
      ) : null}

      {/* Presence (TASK-0093 R5): the polite live region — SR announcements
          for join/edit-start/edit-stop/leave, ≤ 1/s, state changes only.
          Visually hidden (the avatars + toasts are the visual channel). */}
      <p role="status" aria-live="polite" className="sr-only">
        {announcement}
      </p>

      {/* Blocks */}
      <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={onDragEnd}>
        <SortableContext items={renderBlocks.map((b) => b.id)} strategy={verticalListSortingStrategy}>
          <div className="relative">
            {renderBlocks.map((block) => (
              <SortableBlockRow
                key={block.id}
                block={block}
                selected={selectedBlockId === block.id}
                multiSelected={selectedBlockIds.includes(block.id)}
                focusTarget={focusTarget}
                numberedIndex={numberedIndices.get(block.id)}
                onSelect={(id, mods) => selectRow(id, mods)}
                onContextMenu={(x, y, b) => setMenu({ x, y, block: b })}
                onWritingAction={(action, blockIds, language) => openWriting(action, blockIds, language)}
                onEnterKey={createSibling}
                onNavigate={(b, dir) => focusSibling(b, dir)}
                onSlashPick={(cmd, ctx) => void onSlashPick(cmd, ctx)}
                onEmptyBlur={(b, html) => handleEmptyBlur(b, html)}
              />
            ))}
            {/* Presence (TASK-0093 R4): the remote cursors + name labels +
                selection highlights, overlaid on the block list (the layer
                is an absolute, pointer-events-none, decorative overlay). */}
            <CursorLayer peers={others} blockIds={blockIds} />
          </div>
        </SortableContext>
      </DndContext>

      {/* TASK-0126 — empty-state "Describe a page…" card (the Home page with
          no blocks; the workspace root redirects here on a fresh workspace).
          Opens the page-generation dialog. Hidden for GUEST (EDIT gate). */}
      {contentBlockCount === 0 && canGenerate ? (
        <button
          type="button"
          data-testid="home-generate-card"
          onClick={() => setGenerate(true, { parentId: pageId })}
          className="group mb-4 flex w-full max-w-xl items-center gap-3 rounded-lg border border-dashed border-border bg-background/60 px-4 py-3 text-left hover:border-primary/50 hover:bg-accent/40"
        >
          <Sparkles className="size-4 shrink-0 text-muted-foreground group-hover:text-primary" aria-hidden />
          <span className="min-w-0 flex-1">
            <span className="block text-sm font-medium">Describe a page…</span>
            <span className="block text-xs text-muted-foreground">
              e.g. "A product launch plan with objectives, a timeline, and a tasks database"
            </span>
          </span>
        </button>
      ) : null}

      {/* "Add a sub-page" (tests/README.md `subpage-create`, T-192): the
          in-page way to nest a child page (the sidebar tree row has the
          same action on hover). Reuses the sidebar's `factory:new-page`
          event — the handler creates the child + navigates to it, and its
          invalidation refreshes the sidebar tree (listener stays mounted
          even while the sidebar is collapsed). Hidden for GUEST (no EDIT). */}
      {canGenerate ? (
        <button
          type="button"
          data-testid="subpage-create"
          onClick={() =>
            window.dispatchEvent(
              new CustomEvent("factory:new-page", { detail: { parentId: pageId } })
            )
          }
          className="mb-2 flex items-center gap-1.5 rounded-md px-2 py-1 text-xs text-muted-foreground hover:bg-accent hover:text-foreground"
        >
          <FolderOpen className="size-3.5" aria-hidden />
          Add a sub-page
        </button>
      ) : null}

      {/* Trailing empty area — TASK-0136: focus the last block when it is
          already an empty text block (reuse, no pile-up), otherwise create
          + focus a new paragraph (see onTrailingAreaClick). */}
      <div
        data-testid="new-block"
        className="min-h-[16vh] cursor-text"
        onClick={onTrailingAreaClick}
        aria-hidden
      />

      {/* Right-click context menu */}
      {menu ? (
        <ContextMenu
          x={menu.x}
          y={menu.y}
          block={menu.block}
          pageId={pageId}
          onClose={() => setMenu(null)}
          onWritingAction={page?.workspaceId ? (action, blockIds, language) => openWriting(action, blockIds, language) : undefined}
          canGenerate={canGenerate}
        />
      ) : null}

      {/* TASK-0123 — the floating multi-selection toolbar (the writing
          tools' entry point) + the suggestion dialog (accept-diff). */}
      {selectedBlocks.length > 0 && page?.workspaceId ? (
        <SelectionToolbar
          pageId={pageId}
          blocks={selectedBlocks}
          onClear={clearSelection}
          onAction={(action, language) => openWriting(action, selectedBlocks.map((b) => b.id), language)}
        />
      ) : null}
      {writing.open && page?.workspaceId ? (
        <WritingDialog
          open
          workspaceId={page.workspaceId}
          pageId={pageId}
          blocks={dialogBlocks}
          action={writing.action}
          language={writing.language}
          onClose={() => setWriting((w) => ({ ...w, open: false }))}
        />
      ) : null}

      {/* TASK-0094 R2 — the comment drawer (the Phase-3 panel, now live). */}
      <CommentPanel
        pageId={pageId}
        workspaceId={page?.workspaceId ?? ""}
        open={commentsOpen}
        onClose={() => setCommentsOpen(false)}
      />

      {/* T-140 — the "Related" (backlinks) slide-over. The query lives in
          useBacklinks (30 s staleTime); the panel is a pure presenter. */}
      <RelatedPanel
        pageId={pageId}
        workspaceSlug={wsParams?.workspace ?? ""}
        open={relatedOpen}
        onClose={() => setRelatedOpen(false)}
        refs={backlinks.data ?? []}
        isLoading={backlinks.isLoading}
        isError={backlinks.isError}
      />

      {/* Slash-command insert flows */}
      {insert ? (
        <InsertDialog
          open
          initialTab={insert.tab}
          afterBlockId={insert.block.id}
          parentId={insert.block.parentId}
          pageId={pageId}
          workspaceId={page?.workspaceId ?? ""}
          onClose={() => setInsert(null)}
        />
      ) : null}
      {templateOpen ? (
        <TemplateDialog
          workspaceId={page?.workspaceId ?? ""}
          onClose={() => setTemplateOpen(false)}
          onApply={async (templateId, title) => {
            // Apply duplicates the template into this workspace; then focus
            // the new page's first block for immediate editing.
            const created = await templateApi.apply(templateId, { workspaceId: page?.workspaceId ?? "", parentId: null });
            setTemplateOpen(false);
            useEditorStore.getState().setSelection(null);
            toast("success", "Template inserted", title);
            void created;
          }}
        />
      ) : null}
    </div>
  );
}

/** dnd-kit sortable wrapper: selection ring, hover toolbar, the block body. */
function SortableBlockRow({
  block,
  selected,
  multiSelected,
  focusTarget,
  numberedIndex,
  onSelect,
  onContextMenu,
  onEnterKey,
  onNavigate,
  onSlashPick,
  onWritingAction,
  onEmptyBlur,
}: {
  block: Block;
  selected: boolean;
  /** TASK-0123 — part of the multi-selection (a distinct ring, so a ⌘+click
   *  selection is visible even when another row is the single highlight). */
  multiSelected?: boolean;
  focusTarget: string | null;
  numberedIndex?: number;
  /** The row's selection click, carrying the modifier keys (multi-select). */
  onSelect: (id: string, mods: { metaKey: boolean; ctrlKey: boolean; shiftKey: boolean }) => void;
  onContextMenu: (x: number, y: number, block: Block) => void;
  onEnterKey: (block: Block) => void;
  onNavigate: (block: Block, dir: -1 | 1) => void;
  onSlashPick: (
    command: SlashCommand,
    context: { parentId: string | null; position: string },
  ) => void;
  onWritingAction?: (action: WritingAction, blockIds: string[], language?: string) => void;
  /** TASK-0136 — empty-block cleanup: called with the block's FINAL html on
   *  blur so the page can delete it if it is still empty (nothing typed). */
  onEmptyBlur?: (block: Block, html: string) => void;
}) {
  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
    id: block.id,
    data: { type: "block", blockId: block.id },
  });
  // TASK-0123: capture the modifier keys at mousedown (the inner block's
  // `onSelect` fires without an event, so the row must remember the press).
  const modsRef = useRef({ metaKey: false, ctrlKey: false, shiftKey: false });

  return (
    <div
      ref={setNodeRef}
      data-block-id={block.id}
      data-testid={`block-${block.id}`}
      data-multi-selected={multiSelected || undefined}
      style={{ transform: CSS.Transform.toString(transform), transition }}
      // TASK-0135: the `group` marker must live on the ROW (the TASK-0100 S5
      // note below the .block-row CSS says the marker moved to the JSX "at the
      // usage sites" — nested rows in block-renderer.tsx carry `group block-row`,
      // but this top-level row lost it). Without it the left gutter's
      // `group-hover:opacity-100` + `group-hover:pointer-events-auto` never
      // activate, so the grip drag handle stayed opacity-0 AND
      // pointer-events-none forever — dnd-kit reordering was silently dead
      // (verified: elementFromPoint at the grip's center = #workspace-main).
      className={cn("group block-row", (selected || multiSelected) && "is-selected", multiSelected && "is-multi-selected", isDragging && "z-10 opacity-90")}
      onMouseDownCapture={(e) => {
        modsRef.current = { metaKey: e.metaKey, ctrlKey: e.ctrlKey, shiftKey: e.shiftKey };
      }}
      onClick={(e) => {
        if (e.target === e.currentTarget) onSelect(block.id, modsRef.current);
      }}
      onContextMenu={(e) => {
        e.preventDefault();
        onContextMenu(e.clientX, e.clientY, block);
      }}
    >
      {/* Block toolbar gutter. Desktop (≥768px): the LEFT gutter, revealed
          on row hover (the `group-hover` utilities). Mobile (<768px): the
          RIGHT gutter, ALWAYS visible (docs/product/ux-requirements.md —
          "single-column everything; editor: full-width blocks, ⋮⋮ always
          visible in the right gutter"; the hover state does not exist for
          touch). The element is a single toolbar repositioned per breakpoint
          (one `data-testid="drag-handle"`, so the e2e helper's `.first()` is
          stable on both). The turn-into/more actions are additionally
          reachable on mobile via the block context menu.
          `z-30` = the "block toolbar" level of the ux z-index tokens
          (content 0 → block toolbar 30): on mobile the toolbar overlaps the
          row's own content, and the row content comes later in the DOM, so
          without the z-level the paragraph would paint over the grip and
          intercept pointer events at the handle. */}
      <div className="absolute right-0 top-1 z-30 flex items-center opacity-100 transition-opacity md:left-0 md:right-auto md:-translate-x-full md:pointer-events-none md:opacity-0 md:group-hover:pointer-events-auto md:group-hover:opacity-100">
        <BlockToolbar
          block={block}
          gripProps={{ attributes, listeners }}
          onWritingAction={(action, blockIds, language) => onWritingAction?.(action, blockIds, language)}
        />
      </div>
      <BlockRenderer
        block={block}
        selected={selected || multiSelected}
        requestFocus={focusTarget === block.id}
        numberedIndex={numberedIndex}
        onEnterKey={() => onEnterKey(block)}
        onNavigate={(dir) => onNavigate(block, dir)}
        onSelect={() => onSelect(block.id, modsRef.current)}
        onSlashPick={onSlashPick}
        // TASK-0136 — forward the empty-block cleanup down to the renderer;
        // without this the row's `onEmptyBlur` prop is dropped and an empty
        // text block that loses focus is never deleted (dead feature).
        onEmptyBlur={onEmptyBlur}
      />
    </div>
  );
}

/* ------------------------------------------------------------------------
 * TASK-0038 icon + cover pickers (T-192) — the minimal emoji / solid-
 * gradient pickers the E2E contract (`icon-picker`, `cover-picker`,
 * `cover-color-{i}`, `page-icon`, `page-cover`) requires. Both write back
 * through `updatePage.mutate` (icon / cover → PATCH /pages/:id coverUrl).
 * ---------------------------------------------------------------------- */

/** Cover tokens (T-192). The cover is persisted as a STRING that the API's
 *  `UpdatePageDto.coverUrl` validates with Zod `.url().max(2048)` — a raw CSS
 *  gradient string is NOT a URL and 400s on PATCH (recorded conflict, T-192).
 *  So each token is a data-URI SVG (Zod accepts `data:` URIs) built from the
 *  same color stops, which renders identically in the picker swatch and the
 *  `page-cover` band (exact round-trip, no mapping drift). `btoa` is used
 *  (browser-safe; the SVG is pure ASCII) rather than Node's `Buffer`. */
const COVER_STOPS: [string, string][] = [
  ["#6366f1", "#8b5cf6"], // 0 indigo
  ["#f43f5e", "#f97316"], // 1 rose→orange
  ["#10b981", "#14b8a6"], // 2 emerald
  ["#0ea5e9", "#6366f1"], // 3 sky→indigo
  ["#f59e0b", "#f43f5e"], // 4 amber→rose
  ["#1e293b", "#475569"]  // 5 slate
];

const coverToken = ([from, to]: [string, string]): string => {
  const svg =
    `<svg xmlns="http://www.w3.org/2000/svg" width="160" height="90">` +
    `<defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">` +
    `<stop offset="0" stop-color="${from}"/><stop offset="1" stop-color="${to}"/>` +
    `</linearGradient></defs><rect width="160" height="90" fill="url(#g)"/></svg>`;
  return `data:image/svg+xml;base64,${btoa(svg)}`;
};

const COVER_TOKENS: string[] = COVER_STOPS.map(coverToken);

function coverBackground(cover: string): string {
  // A stored token (our own data-URI SVG) renders as a background image;
  // anything else (a future real image URL / free text) degrades to a neutral
  // block so the `page-cover` band is still visible + styled.
  return COVER_TOKENS.includes(cover)
    ? `url("${cover}") center / cover no-repeat`
    : "linear-gradient(135deg, #64748b, #334155)";
}

const ICON_EMOJI: string[] = [
  "🚀", "📄", "📌", "⭐", "💡", "🎯", "🔥", "✅",
  "📊", "🗓️", "🔒", "🌱", "☁️", "🧠", "🛠️", "🎉"
];

/** Emoji picker popover (anchored to the icon button). */
function IconPicker({ onPick }: { onPick: (icon: string) => void }) {
  return (
    <div
      data-testid="icon-picker"
      role="menu"
      aria-label="Choose icon"
      className="absolute left-0 top-8 z-[75] grid w-56 grid-cols-8 gap-1 rounded-md border border-border bg-popover p-2 shadow-xl"
    >
      {ICON_EMOJI.map((e) => (
        <button
          key={e}
          type="button"
          role="menuitem"
          onClick={() => onPick(e)}
          className="rounded p-1 text-lg hover:bg-accent"
        >
          {e}
        </button>
      ))}
    </div>
  );
}

/** Solid-gradient cover picker popover (anchored to the cover button). */
function CoverPicker({ onPick }: { onPick: (cover: string) => void }) {
  return (
    <div
      data-testid="cover-picker"
      role="menu"
      aria-label="Choose cover"
      className="absolute left-0 top-8 z-[75] grid w-56 grid-cols-3 gap-1.5 rounded-md border border-border bg-popover p-2 shadow-xl"
    >
      {COVER_TOKENS.map((g, i) => (
        <button
          key={g}
          type="button"
          role="menuitem"
          data-testid={`cover-color-${i}`}
          aria-label={`Cover color ${i + 1}`}
          onClick={() => onPick(g)}
          className="h-10 w-full rounded-md border border-border/40"
          style={{ background: coverBackground(g) }}
        />
      ))}
    </div>
  );
}