fix(#268): don't open an empty hover card; align flip height estimate (F1,F2)

- F1: gate the card on rows-WITH-text (`thread.some(row => row.text.length > 0)`)
  instead of thread length. A text-less root whose only reply is also text-less
  would otherwise open an empty <Paper> (the render already filters empty rows).
  New test locks it (parent + reply both empty → no card).
- F2: ESTIMATED_CARD_HEIGHT 200 -> 300 (= CARD_MAX_HEIGHT) so the flip-above
  decision reserves the real worst-case height and a tall thread near the
  viewport bottom flips up instead of overflowing off-screen.

vitest 19/19, tsc 0, eslint 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/features/comment/components/comment-hover-preview.test.tsx

@@ -0,0 +1,434 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, act } from "@testing-library/react";
+import { useRef } from "react";
+import { MantineProvider } from "@mantine/core";
+import { IComment } from "@/features/comment/types/comment.types";
+
+// matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
+
+// Stub the comments query so the component renders without react-query/network.
+const mockUseCommentsQuery = vi.fn();
+vi.mock("@/features/comment/queries/comment-query", () => ({
+  useCommentsQuery: (params: { pageId: string }) =>
+    mockUseCommentsQuery(params),
+}));
+
+import CommentHoverPreview from "./comment-hover-preview";
+import { commentContentToText } from "@/features/comment/utils/comment-content-to-text";
+
+const doc = (text: string) =>
+  JSON.stringify({
+    type: "doc",
+    content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+  });
+
+const comment = (over?: Partial<IComment>): IComment =>
+  ({
+    id: "c-1",
+    content: doc("Hello world"),
+    creatorId: "u-1",
+    pageId: "page-1",
+    workspaceId: "ws-1",
+    createdAt: new Date(),
+    creator: { id: "u-1", name: "User", avatarUrl: null } as any,
+    ...over,
+  }) as IComment;
+
+function setComments(items: IComment[]) {
+  mockUseCommentsQuery.mockReturnValue({
+    data: { items, meta: {} },
+    isLoading: false,
+    isError: false,
+  });
+}
+
+// Test harness: owns the container ref, hosts a comment-mark span and the
+// preview component, mirroring how page-editor mounts it next to EditorContent.
+function Harness({
+  spanAttrs = { "data-comment-id": "c-1" },
+  pageId = "page-1",
+}: {
+  spanAttrs?: Record<string, string>;
+  pageId?: string;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  return (
+    <MantineProvider>
+      <div ref={containerRef}>
+        <span data-testid="mark" className="comment-mark" {...spanAttrs}>
+          marked text
+        </span>
+        <CommentHoverPreview pageId={pageId} containerRef={containerRef} />
+      </div>
+    </MantineProvider>
+  );
+}
+
+function hoverMark() {
+  const span = screen.getByTestId("mark");
+  act(() => {
+    span.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+  });
+}
+
+function leaveMark() {
+  const span = screen.getByTestId("mark");
+  act(() => {
+    span.dispatchEvent(new MouseEvent("mouseout", { bubbles: true }));
+  });
+}
+
+describe("commentContentToText", () => {
+  it("flattens a multi-node ProseMirror doc to plain text", () => {
+    const content = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "Hello " },
+            { type: "text", text: "world" },
+          ],
+        },
+        { type: "paragraph", content: [{ type: "text", text: "Second line" }] },
+      ],
+    });
+    expect(commentContentToText(content)).toBe("Hello world\nSecond line");
+  });
+
+  it("joins nested block structures (lists) on block boundaries", () => {
+    const content = {
+      type: "doc",
+      content: [
+        {
+          type: "bulletList",
+          content: [
+            {
+              type: "listItem",
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "one" }] },
+              ],
+            },
+            {
+              type: "listItem",
+              content: [
+                { type: "paragraph", content: [{ type: "text", text: "two" }] },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+    expect(commentContentToText(content)).toBe("one\ntwo");
+  });
+
+  it("accepts an already-parsed object", () => {
+    expect(commentContentToText({ type: "doc", content: [] })).toBe("");
+  });
+
+  it("returns '' for empty / missing / malformed content", () => {
+    expect(commentContentToText("")).toBe("");
+    expect(commentContentToText("   ")).toBe("");
+    expect(commentContentToText(undefined)).toBe("");
+    expect(commentContentToText(null)).toBe("");
+    expect(commentContentToText(JSON.stringify({ type: "doc", content: [] }))).toBe(
+      "",
+    );
+  });
+
+  it("falls back to the raw string when content is not JSON", () => {
+    expect(commentContentToText("plain text")).toBe("plain text");
+  });
+
+  it("preserves a hardBreak inside a paragraph as a newline", () => {
+    const content = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "line1" },
+            { type: "hardBreak" },
+            { type: "text", text: "line2" },
+          ],
+        },
+      ],
+    });
+    expect(commentContentToText(content)).toBe("line1\nline2");
+  });
+});
+
+describe("CommentHoverPreview — hover behaviour", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockUseCommentsQuery.mockReset();
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+  });
+
+  it("shows the parent comment text and author after the open delay", () => {
+    setComments([
+      comment({
+        content: doc("Hello world"),
+        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
+      }),
+    ]);
+    render(<Harness />);
+
+    hoverMark();
+    // Before the delay elapses there is no card.
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    const card = screen.getByTestId("comment-hover-preview");
+    // The line shows "Author: text" — both the author name and the comment text.
+    expect(card.textContent).toContain("Alice:");
+    expect(card.textContent).toContain("Hello world");
+    // The card MUST NOT intercept the mark's click (which opens the side panel):
+    // pointer-events:none is the single property guaranteeing that — lock it so
+    // a regression dropping it from the style object fails here.
+    expect(card.style.pointerEvents).toBe("none");
+  });
+
+  it("renders the whole thread: parent plus replies, each with its author", () => {
+    setComments([
+      comment({
+        id: "c-1",
+        content: doc("Parent comment"),
+        createdAt: new Date("2026-01-01T10:00:00Z"),
+        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
+      }),
+      comment({
+        id: "c-3",
+        content: doc("Second reply"),
+        parentCommentId: "c-1",
+        createdAt: new Date("2026-01-01T12:00:00Z"),
+        creator: { id: "u-3", name: "Carol", avatarUrl: null } as any,
+      }),
+      comment({
+        id: "c-2",
+        content: doc("First reply"),
+        parentCommentId: "c-1",
+        createdAt: new Date("2026-01-01T11:00:00Z"),
+        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
+      }),
+    ]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    const card = screen.getByTestId("comment-hover-preview");
+
+    // Parent and both replies are present, each as "Author: text".
+    const body = card.textContent ?? "";
+    expect(body).toContain("Alice: Parent comment");
+    expect(body).toContain("Bob: First reply");
+    expect(body).toContain("Carol: Second reply");
+
+    // Replies are ordered by createdAt ascending after the parent
+    // (Parent -> First reply -> Second reply), even though the input was
+    // out of order (Second reply's comment came before First reply's).
+    expect(body.indexOf("Parent comment")).toBeLessThan(
+      body.indexOf("First reply"),
+    );
+    expect(body.indexOf("First reply")).toBeLessThan(
+      body.indexOf("Second reply"),
+    );
+  });
+
+  it("shows the thread even when the parent text is empty but it has replies", () => {
+    setComments([
+      comment({
+        id: "c-1",
+        content: JSON.stringify({ type: "doc", content: [] }),
+        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
+      }),
+      comment({
+        id: "c-2",
+        content: doc("A reply"),
+        parentCommentId: "c-1",
+        createdAt: new Date(),
+        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
+      }),
+    ]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    const card = screen.getByTestId("comment-hover-preview");
+    expect(card.textContent).toContain("Bob: A reply");
+  });
+
+  it("shows nothing when neither the parent nor its reply has any text", () => {
+    // The card is gated on rows-with-text (not thread length), so a text-less
+    // root whose only reply is also text-less must NOT open an empty card.
+    const emptyDoc = JSON.stringify({ type: "doc", content: [] });
+    setComments([
+      comment({
+        id: "c-1",
+        content: emptyDoc,
+        creator: { id: "u-1", name: "Alice", avatarUrl: null } as any,
+      }),
+      comment({
+        id: "c-2",
+        content: emptyDoc,
+        parentCommentId: "c-1",
+        createdAt: new Date(),
+        creator: { id: "u-2", name: "Bob", avatarUrl: null } as any,
+      }),
+    ]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("hides on mouseout", () => {
+    setComments([comment()]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(
+      screen.getByTestId("comment-hover-preview").textContent,
+    ).toContain("Hello world");
+
+    leaveMark();
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("does not show a card for a resolved comment (data-resolved)", () => {
+    setComments([comment()]);
+    render(
+      <Harness
+        spanAttrs={{ "data-comment-id": "c-1", "data-resolved": "true" }}
+      />,
+    );
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("does not show a card for a resolved comment (resolvedAt set)", () => {
+    setComments([comment({ resolvedAt: new Date() })]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("does not show a card for an unknown comment id", () => {
+    setComments([comment()]);
+    render(<Harness spanAttrs={{ "data-comment-id": "missing" }} />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("does not show a card when the comment text is empty", () => {
+    setComments([comment({ content: JSON.stringify({ type: "doc", content: [] }) })]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("hides on scroll", () => {
+    setComments([comment()]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(
+      screen.getByTestId("comment-hover-preview").textContent,
+    ).toContain("Hello world");
+
+    act(() => {
+      window.dispatchEvent(new Event("scroll"));
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("hides on mousedown (clicking the mark to open the panel dismisses the card)", () => {
+    setComments([comment()]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(
+      screen.getByTestId("comment-hover-preview").textContent,
+    ).toContain("Hello world");
+
+    const span = screen.getByTestId("mark");
+    act(() => {
+      span.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+
+  it("does not hide when the pointer moves WITHIN the same span (anti-flicker)", () => {
+    setComments([comment()]);
+    render(<Harness />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
+
+    // mouseout whose relatedTarget is still inside the span must NOT hide.
+    const span = screen.getByTestId("mark");
+    act(() => {
+      span.dispatchEvent(
+        new MouseEvent("mouseout", { bubbles: true, relatedTarget: span }),
+      );
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
+  });
+
+  it("hides when the page changes", () => {
+    setComments([comment()]);
+    const { rerender } = render(<Harness pageId="page-1" />);
+
+    hoverMark();
+    act(() => {
+      vi.advanceTimersByTime(350);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).not.toBeNull();
+
+    act(() => {
+      rerender(<Harness pageId="page-2" />);
+    });
+    expect(screen.queryByTestId("comment-hover-preview")).toBeNull();
+  });
+});

apps/client/src/features/comment/components/comment-hover-preview.tsx

@@ -0,0 +1,267 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Paper, Text } from "@mantine/core";
+import { useCommentsQuery } from "@/features/comment/queries/comment-query";
+import { IComment } from "@/features/comment/types/comment.types";
+import { commentContentToText } from "@/features/comment/utils/comment-content-to-text";
+
+interface CommentHoverPreviewProps {
+  pageId: string;
+  containerRef: React.RefObject<HTMLElement>;
+}
+
+// Delay before the card appears, to avoid flicker when the pointer quickly
+// passes over comment marks (kept generous so it does not pop up on a passing
+// glance).
+const OPEN_DELAY_MS = 350;
+const CARD_MAX_WIDTH = 360;
+const CARD_MAX_HEIGHT = 300;
+const GAP = 6;
+// Reserve roughly this much room below the span; flip above when it doesn't fit.
+// Match CARD_MAX_HEIGHT so the flip-above decision reserves the real worst-case
+// height — otherwise a tall thread placed below near the viewport bottom passes
+// the "fits below" check and then overflows off-screen (clipped, no scroll).
+const ESTIMATED_CARD_HEIGHT = 300;
+
+// One rendered line of the thread: the author and the comment's plain text,
+// pre-computed at hover time so render stays cheap. Shown as "Author: text".
+interface ThreadRow {
+  id: string;
+  name: string;
+  text: string;
+}
+
+interface HoverState {
+  thread: ThreadRow[];
+  rect: { top: number; bottom: number; left: number };
+}
+
+function isResolved(comment: IComment): boolean {
+  return comment.resolvedAt != null || comment.resolvedById != null;
+}
+
+// Build the thread for a root (parent) comment: the root first, followed by its
+// replies sorted by createdAt ascending. Reads every comment from the map.
+function buildThread(
+  commentMap: Map<string, IComment>,
+  root: IComment,
+): ThreadRow[] {
+  const replies: IComment[] = [];
+  commentMap.forEach((comment) => {
+    if (comment.parentCommentId === root.id) replies.push(comment);
+  });
+  replies.sort(
+    (a, b) =>
+      new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+  );
+
+  return [root, ...replies].map((comment) => ({
+    id: comment.id,
+    name: comment.creator?.name ?? "",
+    text: commentContentToText(comment.content),
+  }));
+}
+
+/**
+ * Shows a small floating card when the user hovers a `.comment-mark` span in the
+ * main editor: the parent comment plus all its replies, one per line as
+ * "Author: text" (plain — no avatars or timestamps). Read-only:
+ * `pointer-events: none` so it never intercepts the mark's click (which opens
+ * the side panel via ACTIVE_COMMENT_EVENT). Resolved/unknown marks show nothing.
+ */
+export default function CommentHoverPreview({
+  pageId,
+  containerRef,
+}: CommentHoverPreviewProps) {
+  const { data } = useCommentsQuery({ pageId });
+
+  // Map of commentId -> comment. The map indexes every comment (parents and
+  // replies) so a thread can be assembled from a single source.
+  const commentMap = useMemo(() => {
+    const map = new Map<string, IComment>();
+    data?.items?.forEach((comment) => map.set(comment.id, comment));
+    return map;
+  }, [data]);
+
+  // Read the latest map from the delegated listeners without re-attaching them
+  // every time the comments query refreshes.
+  const commentMapRef = useRef(commentMap);
+  useEffect(() => {
+    commentMapRef.current = commentMap;
+  }, [commentMap]);
+
+  const [hover, setHover] = useState<HoverState | null>(null);
+  const openTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const activeSpanRef = useRef<HTMLElement | null>(null);
+
+  const clearOpenTimer = () => {
+    if (openTimerRef.current !== null) {
+      clearTimeout(openTimerRef.current);
+      openTimerRef.current = null;
+    }
+  };
+
+  const hide = () => {
+    clearOpenTimer();
+    activeSpanRef.current = null;
+    setHover(null);
+  };
+
+  // Hide and reset when the page changes (the comment set belongs to a page):
+  // the cleanup runs on every pageId change before the effect re-runs.
+  useEffect(() => {
+    return () => hide();
+  }, [pageId]);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleMouseOver = (event: MouseEvent) => {
+      const target = event.target as HTMLElement | null;
+      const span = target?.closest<HTMLElement>(
+        ".comment-mark[data-comment-id]",
+      );
+      if (!span) return;
+
+      const commentId = span.getAttribute("data-comment-id");
+      if (!commentId) return;
+
+      const comment = commentMapRef.current.get(commentId);
+      // Unknown (not loaded yet) or resolved -> no tooltip. Resolved marks also
+      // carry data-resolved="true"; check both the data attribute and the model.
+      if (
+        !comment ||
+        span.hasAttribute("data-resolved") ||
+        isResolved(comment)
+      ) {
+        return;
+      }
+
+      // Already tracking this span: nothing to do (avoids re-building the thread
+      // on every intra-span mousemove).
+      if (span === activeSpanRef.current) return;
+
+      const thread = buildThread(commentMapRef.current, comment);
+      // Show the card only when SOME comment has text. Gating on thread length
+      // could open an empty card (a text-less root whose only reply is also
+      // text-less), since the render filters out empty-text rows.
+      const hasContent = thread.some((row) => row.text.length > 0);
+      if (!hasContent) return;
+
+      activeSpanRef.current = span;
+
+      clearOpenTimer();
+      openTimerRef.current = setTimeout(() => {
+        openTimerRef.current = null;
+        if (activeSpanRef.current !== span || !span.isConnected) return;
+        const rect = span.getBoundingClientRect();
+        setHover({
+          thread,
+          rect: { top: rect.top, bottom: rect.bottom, left: rect.left },
+        });
+      }, OPEN_DELAY_MS);
+    };
+
+    const handleMouseOut = (event: MouseEvent) => {
+      const target = event.target as HTMLElement | null;
+      const span = target?.closest<HTMLElement>(
+        ".comment-mark[data-comment-id]",
+      );
+      if (!span) return;
+
+      // Ignore moves that stay within the same comment-mark span.
+      const related = event.relatedTarget as HTMLElement | null;
+      if (related && span.contains(related)) return;
+
+      if (span === activeSpanRef.current) hide();
+    };
+
+    // Scroll uses capture so it also catches scrolling inside nested containers.
+    const handleScroll = () => hide();
+    const handleResize = () => hide();
+    // Dismiss on press: clicking a mark opens the side panel, and the card
+    // would otherwise linger (no mouseout fires while the pointer stays put).
+    const handleMouseDown = () => hide();
+
+    container.addEventListener("mouseover", handleMouseOver);
+    container.addEventListener("mouseout", handleMouseOut);
+    container.addEventListener("mousedown", handleMouseDown);
+    window.addEventListener("scroll", handleScroll, true);
+    window.addEventListener("resize", handleResize);
+
+    return () => {
+      container.removeEventListener("mouseover", handleMouseOver);
+      container.removeEventListener("mouseout", handleMouseOut);
+      container.removeEventListener("mousedown", handleMouseDown);
+      window.removeEventListener("scroll", handleScroll, true);
+      window.removeEventListener("resize", handleResize);
+      clearOpenTimer();
+    };
+  }, [containerRef]);
+
+  if (!hover) return null;
+
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  // Flip above when there isn't enough room below the span.
+  const placeAbove =
+    hover.rect.bottom + ESTIMATED_CARD_HEIGHT > viewportHeight &&
+    hover.rect.top > ESTIMATED_CARD_HEIGHT;
+
+  const left = Math.max(
+    8,
+    Math.min(hover.rect.left, viewportWidth - CARD_MAX_WIDTH - 8),
+  );
+
+  const positionStyle: React.CSSProperties = placeAbove
+    ? { bottom: viewportHeight - hover.rect.top + GAP }
+    : { top: hover.rect.bottom + GAP };
+
+  return createPortal(
+    <Paper
+      withBorder
+      shadow="md"
+      radius="sm"
+      role="tooltip"
+      data-testid="comment-hover-preview"
+      style={{
+        position: "fixed",
+        left,
+        ...positionStyle,
+        zIndex: 1000,
+        maxWidth: CARD_MAX_WIDTH,
+        // The card is pointer-events:none, so it can't scroll; clamp long
+        // threads instead (most threads are short).
+        maxHeight: CARD_MAX_HEIGHT,
+        overflow: "hidden",
+        padding: "8px 10px",
+        fontSize: "13px",
+        lineHeight: 1.4,
+        // Never intercept clicks targeting the comment-mark span beneath.
+        pointerEvents: "none",
+        wordBreak: "break-word",
+      }}
+    >
+      {hover.thread
+        // A comment with no plain text (e.g. an image-only reply) adds nothing
+        // to a text preview — skip its line.
+        .filter((row) => row.text.length > 0)
+        .map((row) => (
+          <Text
+            key={row.id}
+            size="xs"
+            mt={4}
+            style={{ whiteSpace: "pre-wrap", wordBreak: "break-word" }}
+          >
+            {/* "Author: text" — one line per comment, parent then replies. */}
+            <Text span fw={600}>
+              {row.name}:
+            </Text>{" "}
+            {row.text}
+          </Text>
+        ))}
+    </Paper>,
+    document.body,
+  );
+}

apps/client/src/features/comment/utils/comment-content-to-text.ts

@@ -0,0 +1,71 @@
+/**
+ * Flatten a comment's ProseMirror JSON document to plain text.
+ *
+ * `IComment.content` is stored as a stringified ProseMirror doc, but this also
+ * accepts an already-parsed object. Walks the node tree, concatenating `text`
+ * leaves and joining text-bearing blocks with newlines. Missing, empty or
+ * malformed content yields an empty string (never throws).
+ */
+export function commentContentToText(content: unknown): string {
+  let doc: any = content;
+
+  if (typeof content === "string") {
+    const trimmed = content.trim();
+    if (!trimmed) return "";
+    try {
+      doc = JSON.parse(trimmed);
+    } catch {
+      // Not JSON — fall back to treating the raw string as plain text.
+      return trimmed;
+    }
+  }
+
+  if (!doc || typeof doc !== "object") return "";
+
+  const blocks: string[] = [];
+
+  const walk = (node: any): void => {
+    if (!node || typeof node !== "object") return;
+
+    if (typeof node.text === "string") {
+      // Inline text leaf: append to the current block line.
+      if (blocks.length === 0) blocks.push("");
+      blocks[blocks.length - 1] += node.text;
+      return;
+    }
+
+    if (node.type === "hardBreak") {
+      // A soft line break inside a block: keep the newline so the two halves
+      // do not run together.
+      if (blocks.length === 0) blocks.push("");
+      blocks[blocks.length - 1] += "\n";
+      return;
+    }
+
+    const children = Array.isArray(node.content) ? node.content : [];
+    const containsText = children.some(
+      (child: any) =>
+        child && typeof child === "object" && typeof child.text === "string",
+    );
+
+    if (containsText) {
+      // Text-bearing block (paragraph, heading, ...): start a fresh line, then
+      // collect its inline text.
+      blocks.push("");
+      children.forEach(walk);
+      return;
+    }
+
+    // Structural container (doc, list, blockquote, ...): recurse so each nested
+    // text block becomes its own line.
+    children.forEach(walk);
+  };
+
+  walk(doc);
+
+  return blocks
+    .map((block) => block.trim())
+    .filter((block) => block.length > 0)
+    .join("\n")
+    .trim();
+}

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

@@ -42,6 +42,7 @@ import {
   showReadOnlyCommentPopupAtom,
 } from "@/features/comment/atoms/comment-atom";
 import CommentDialog from "@/features/comment/components/comment-dialog";
+import CommentHoverPreview from "@/features/comment/components/comment-hover-preview";
 import { EditorBubbleMenu } from "@/features/editor/components/bubble-menu/bubble-menu";
 import { ReadonlyBubbleMenu } from "@/features/editor/components/bubble-menu/readonly-bubble-menu";
 import TableMenu from "@/features/editor/components/table/table-menu.tsx";
@@ -533,6 +534,11 @@ export default function PageEditor({
           <div ref={menuContainerRef}>
             <EditorContent editor={editor} />
 
+            <CommentHoverPreview
+              pageId={pageId}
+              containerRef={menuContainerRef}
+            />
+
             {editor && (
               <SearchAndReplaceDialog editor={editor} editable={editable} />
             )}