From 928891173f8f0f01ac479e3c8edead3decb3b2e6 Mon Sep 17 00:00:00 2001
From: Alan Daniel <stylesshjs@gmail.com>
Date: Sun, 12 Apr 2026 23:02:19 -0400
Subject: [PATCH 1/2] Markdown comment box with @mentions, review fixes, and
 OAuth error handling

- Add reusable MarkdownEditor with Write/Preview tabs, toolbar, and @mention support
- Wire up Send button on PR/issue comment boxes with proper cache invalidation
- Fix submit review flow: async handling, error feedback, and OAuth org restriction warnings
- Add edit mode for pending review comments and redesign comment bubble styling
- Prioritize involved users (author, reviewers, commenters) in mention suggestions
---
 .../components/details/detail-activity.tsx    | 122 ++++++-
 .../issues/detail/issue-detail-activity.tsx   |  40 ++-
 .../issues/detail/issue-detail-page.tsx       |   2 +
 .../pulls/detail/pull-body-section.tsx        | 322 +-----------------
 .../pulls/detail/pull-detail-activity.tsx     |  40 ++-
 .../pulls/review/review-diff-pane.tsx         |   7 +
 .../pulls/review/review-file-diff-block.tsx   | 142 +++++---
 .../components/pulls/review/review-page.tsx   | 112 +++++-
 .../pulls/review/review-submit-popover.tsx    |  12 +-
 apps/dashboard/src/lib/github.functions.ts    |  65 +++-
 apps/dashboard/src/lib/warning-store.ts       |  43 ++-
 11 files changed, 517 insertions(+), 390 deletions(-)

diff --git a/apps/dashboard/src/components/details/detail-activity.tsx b/apps/dashboard/src/components/details/detail-activity.tsx
index 7980900..b9d79b0 100644
--- a/apps/dashboard/src/components/details/detail-activity.tsx
+++ b/apps/dashboard/src/components/details/detail-activity.tsx
@@ -1,4 +1,20 @@
-import { useState } from "react";
+import {
+	MarkdownEditor,
+	type MentionCandidate,
+} from "@diffkit/ui/components/markdown-editor";
+import { toast } from "@diffkit/ui/components/sonner";
+import { Spinner } from "@diffkit/ui/components/spinner";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useMemo, useState } from "react";
+import { createComment } from "#/lib/github.functions";
+import {
+	type GitHubQueryScope,
+	githubQueryKeys,
+	githubRepoCollaboratorsQueryOptions,
+	githubViewerQueryOptions,
+} from "#/lib/github.query";
+import type { GitHubActor } from "#/lib/github.types";
+import { checkPermissionWarning } from "#/lib/warning-store";
 
 export function DetailActivityHeader({
 	title,
@@ -19,24 +35,112 @@ export function DetailActivityHeader({
 	);
 }
 
-export function DetailCommentBox() {
+export function DetailCommentBox({
+	owner,
+	repo,
+	issueNumber,
+	scope,
+	involvedUsers,
+}: {
+	owner: string;
+	repo: string;
+	issueNumber: number;
+	scope: GitHubQueryScope;
+	involvedUsers?: GitHubActor[];
+}) {
 	const [value, setValue] = useState("");
+	const [isSending, setIsSending] = useState(false);
+	const [mentionActivated, setMentionActivated] = useState(false);
+	const queryClient = useQueryClient();
+
+	const viewerQuery = useQuery(githubViewerQueryOptions(scope));
+	const viewerLogin = viewerQuery.data?.login;
+
+	const collaboratorsQuery = useQuery({
+		...githubRepoCollaboratorsQueryOptions(scope, { owner, repo }),
+		enabled: mentionActivated,
+	});
+
+	const mentionCandidates: MentionCandidate[] = useMemo(() => {
+		const seen = new Set<string>();
+		const candidates: MentionCandidate[] = [];
+
+		// Exclude the current user
+		if (viewerLogin) seen.add(viewerLogin);
+
+		// Involved users first (commenters, reviewers, author)
+		if (involvedUsers) {
+			for (const user of involvedUsers) {
+				if (seen.has(user.login)) continue;
+				seen.add(user.login);
+				candidates.push({
+					id: user.login,
+					label: user.login,
+					avatarUrl: user.avatarUrl,
+					secondary: user.type === "Bot" ? "Bot" : undefined,
+				});
+			}
+		}
+
+		// Remaining collaborators
+		for (const c of collaboratorsQuery.data ?? []) {
+			if (seen.has(c.login)) continue;
+			seen.add(c.login);
+			candidates.push({
+				id: c.login,
+				label: c.login,
+				avatarUrl: c.avatarUrl,
+				secondary: c.type === "Bot" ? "Bot" : undefined,
+			});
+		}
+
+		return candidates;
+	}, [viewerLogin, involvedUsers, collaboratorsQuery.data]);
+
+	const handleSend = async () => {
+		if (!value.trim()) return;
+		setIsSending(true);
+		try {
+			const result = await createComment({
+				data: { owner, repo, issueNumber, body: value.trim() },
+			});
+			if (result.ok) {
+				setValue("");
+				void queryClient.invalidateQueries({
+					queryKey: githubQueryKeys.all,
+				});
+			} else {
+				toast.error(result.error);
+				checkPermissionWarning(result, `${owner}/${repo}`);
+			}
+		} catch {
+			toast.error("Failed to send comment");
+		} finally {
+			setIsSending(false);
+		}
+	};
 
 	return (
-		<div className="flex flex-col gap-2 rounded-lg border bg-surface-0 p-3">
-			<textarea
+		<div className="flex flex-col gap-2">
+			<MarkdownEditor
 				value={value}
-				onChange={(event) => setValue(event.target.value)}
+				onChange={setValue}
 				placeholder="Leave a comment..."
-				rows={3}
-				className="w-full resize-none bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+				compact
+				mentions={{
+					candidates: mentionCandidates,
+					onActivate: () => setMentionActivated(true),
+					isLoading: collaboratorsQuery.isLoading && mentionActivated,
+				}}
 			/>
 			<div className="flex justify-end">
 				<button
 					type="button"
-					disabled={!value.trim()}
-					className="rounded-lg bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-opacity disabled:opacity-40"
+					disabled={!value.trim() || isSending}
+					onClick={handleSend}
+					className="flex items-center gap-1.5 rounded-lg bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-opacity disabled:opacity-40"
 				>
+					{isSending && <Spinner size={12} />}
 					Send
 				</button>
 			</div>
diff --git a/apps/dashboard/src/components/issues/detail/issue-detail-activity.tsx b/apps/dashboard/src/components/issues/detail/issue-detail-activity.tsx
index 7ad9427..9fcd7c5 100644
--- a/apps/dashboard/src/components/issues/detail/issue-detail-activity.tsx
+++ b/apps/dashboard/src/components/issues/detail/issue-detail-activity.tsx
@@ -18,9 +18,11 @@ import {
 import { LabelPill } from "#/components/details/label-pill";
 import { formatRelativeTime } from "#/lib/format-relative-time";
 import { getCommentPage, getTimelineEventPage } from "#/lib/github.functions";
+import type { GitHubQueryScope } from "#/lib/github.query";
 import type {
 	CommentPagination,
 	EventPagination,
+	GitHubActor,
 	IssueComment,
 	IssuePageData,
 	TimelineEvent,
@@ -234,6 +236,8 @@ export function IssueDetailActivitySection({
 	owner,
 	repo,
 	issueNumber,
+	scope,
+	issueAuthor,
 }: {
 	comments?: IssueComment[];
 	events?: TimelineEvent[];
@@ -244,6 +248,8 @@ export function IssueDetailActivitySection({
 	owner: string;
 	repo: string;
 	issueNumber: number;
+	scope: GitHubQueryScope;
+	issueAuthor: GitHubActor | null;
 }) {
 	const allItems: IssueTimelineItem[] = [
 		...(comments ?? []).map((comment) => ({
@@ -423,12 +429,44 @@ export function IssueDetailActivitySection({
 			)}
 
 			<div className="mt-6">
-				<DetailCommentBox />
+				<DetailCommentBox
+					owner={owner}
+					repo={repo}
+					issueNumber={issueNumber}
+					scope={scope}
+					involvedUsers={getInvolvedUsers(issueAuthor, comments)}
+				/>
 			</div>
 		</div>
 	);
 }
 
+function getInvolvedUsers(
+	issueAuthor: GitHubActor | null,
+	comments?: IssueComment[],
+): GitHubActor[] {
+	const seen = new Set<string>();
+	const users: GitHubActor[] = [];
+
+	const add = (actor: GitHubActor | null | undefined) => {
+		if (!actor || seen.has(actor.login)) return;
+		seen.add(actor.login);
+		users.push(actor);
+	};
+
+	// Issue author first
+	add(issueAuthor);
+
+	// Commenters (most recent first)
+	if (comments) {
+		for (let i = comments.length - 1; i >= 0; i--) {
+			add(comments[i].author);
+		}
+	}
+
+	return users;
+}
+
 // ── Load more divider ───────────────────────────────────────────────
 
 function LoadMoreDivider({
diff --git a/apps/dashboard/src/components/issues/detail/issue-detail-page.tsx b/apps/dashboard/src/components/issues/detail/issue-detail-page.tsx
index 32b0322..f916bcb 100644
--- a/apps/dashboard/src/components/issues/detail/issue-detail-page.tsx
+++ b/apps/dashboard/src/components/issues/detail/issue-detail-page.tsx
@@ -71,6 +71,8 @@ export function IssueDetailPage() {
 						owner={owner}
 						repo={repo}
 						issueNumber={issueNumber}
+						scope={scope}
+						issueAuthor={issue.author}
 					/>
 				</>
 			}
diff --git a/apps/dashboard/src/components/pulls/detail/pull-body-section.tsx b/apps/dashboard/src/components/pulls/detail/pull-body-section.tsx
index d82697c..39b4294 100644
--- a/apps/dashboard/src/components/pulls/detail/pull-body-section.tsx
+++ b/apps/dashboard/src/components/pulls/detail/pull-body-section.tsx
@@ -10,20 +10,13 @@ import {
 	DropdownMenuItem,
 	DropdownMenuTrigger,
 } from "@diffkit/ui/components/dropdown-menu";
-import { highlightCode, Markdown } from "@diffkit/ui/components/markdown";
+import { Markdown } from "@diffkit/ui/components/markdown";
+import { MarkdownEditor } from "@diffkit/ui/components/markdown-editor";
 import { Spinner } from "@diffkit/ui/components/spinner";
-import {
-	Tooltip,
-	TooltipContent,
-	TooltipProvider,
-	TooltipTrigger,
-} from "@diffkit/ui/components/tooltip";
-import { cn } from "@diffkit/ui/lib/utils";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useState } from "react";
 import { updatePullBody } from "#/lib/github.functions";
 import { type GitHubQueryScope, githubQueryKeys } from "#/lib/github.query";
 import type { PullDetail, PullPageData } from "#/lib/github.types";
-import { matchesShortcut } from "#/lib/shortcuts";
 import { useOptimisticMutation } from "#/lib/use-optimistic-mutation";
 
 export function PullBodySection({
@@ -43,76 +36,8 @@ export function PullBodySection({
 }) {
 	const { mutate } = useOptimisticMutation();
 	const [isEditing, setIsEditing] = useState(false);
-	const [editTab, setEditTab] = useState<"edit" | "preview">("edit");
 	const [draft, setDraft] = useState(pr.body);
 	const [isSaving, setIsSaving] = useState(false);
-	const editorRef = useRef<HTMLTextAreaElement>(null);
-
-	const insertMarkdown = useCallback(
-		(before: string, after = "", placeholder = "") => {
-			const textarea = editorRef.current;
-			if (!textarea) return;
-			const start = textarea.selectionStart;
-			const end = textarea.selectionEnd;
-			const selected = draft.slice(start, end);
-			const text = selected || placeholder;
-			const newValue = `${draft.slice(0, start)}${before}${text}${after}${draft.slice(end)}`;
-			setDraft(newValue);
-			requestAnimationFrame(() => {
-				textarea.focus();
-				const cursorStart = start + before.length;
-				textarea.setSelectionRange(cursorStart, cursorStart + text.length);
-			});
-		},
-		[draft],
-	);
-
-	const handleEditorKeyDown = useCallback(
-		(event: React.KeyboardEvent<HTMLTextAreaElement>) => {
-			const action = [
-				{
-					shortcut: { key: "b", mod: true },
-					run: () => insertMarkdown("**", "**", "bold"),
-				},
-				{
-					shortcut: { key: "i", mod: true },
-					run: () => insertMarkdown("_", "_", "italic"),
-				},
-				{
-					shortcut: { key: "e", mod: true },
-					run: () => insertMarkdown("`", "`", "code"),
-				},
-				{
-					shortcut: { key: "k", mod: true },
-					run: () => insertMarkdown("[", "](url)", "text"),
-				},
-				{
-					shortcut: { key: "h", mod: true },
-					run: () => insertMarkdown("### ", "", "heading"),
-				},
-				{
-					shortcut: { key: ".", mod: true, shift: true },
-					run: () => insertMarkdown("> ", "", "quote"),
-				},
-				{
-					shortcut: { key: "8", mod: true, shift: true },
-					run: () => insertMarkdown("- ", "", "item"),
-				},
-				{
-					shortcut: { key: "7", mod: true, shift: true },
-					run: () => insertMarkdown("1. ", "", "item"),
-				},
-			].find(({ shortcut }) => matchesShortcut(event, shortcut));
-
-			if (!action) {
-				return;
-			}
-
-			event.preventDefault();
-			action.run();
-		},
-		[insertMarkdown],
-	);
 
 	const pageQueryKey = githubQueryKeys.pulls.page(scope, {
 		owner,
@@ -122,7 +47,6 @@ export function PullBodySection({
 
 	const startEditing = () => {
 		setDraft(pr.body);
-		setEditTab("edit");
 		setIsEditing(true);
 	};
 
@@ -155,128 +79,11 @@ export function PullBodySection({
 	if (isEditing) {
 		return (
 			<div className="flex flex-col gap-2">
-				<div className="flex items-center justify-between">
-					<div className="flex items-center gap-0.5">
-						<button
-							type="button"
-							onClick={() => setEditTab("edit")}
-							className={cn(
-								"rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-								editTab === "edit"
-									? "bg-surface-1 text-foreground"
-									: "text-muted-foreground hover:bg-surface-1 hover:text-foreground",
-							)}
-						>
-							Edit
-						</button>
-						<button
-							type="button"
-							onClick={() => setEditTab("preview")}
-							className={cn(
-								"rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-								editTab === "preview"
-									? "bg-surface-1 text-foreground"
-									: "text-muted-foreground hover:bg-surface-1 hover:text-foreground",
-							)}
-						>
-							Preview
-						</button>
-					</div>
-					{editTab === "edit" && (
-						<TooltipProvider delayDuration={300}>
-							<div className="flex items-center gap-0.5 text-muted-foreground">
-								<MdToolbarButton
-									label="Heading"
-									shortcut="⌘H"
-									onClick={() => insertMarkdown("### ", "", "heading")}
-								>
-									<path d="M4 12h8M4 4v16M12 4v16M20 8v8" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Bold"
-									shortcut="⌘B"
-									onClick={() => insertMarkdown("**", "**", "bold")}
-								>
-									<path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6zM6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Italic"
-									shortcut="⌘I"
-									onClick={() => insertMarkdown("_", "_", "italic")}
-								>
-									<path d="M10 4h4M8 20h4M15 4l-6 16" />
-								</MdToolbarButton>
-								<span className="mx-1 h-4 w-px bg-border" />
-								<MdToolbarButton
-									label="Code"
-									shortcut="⌘E"
-									onClick={() => insertMarkdown("`", "`", "code")}
-								>
-									<path d="M16 18l6-6-6-6M8 6l-6 6 6 6" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Link"
-									shortcut="⌘K"
-									onClick={() => insertMarkdown("[", "](url)", "text")}
-								>
-									<path d="M10 14a3.5 3.5 0 0 0 5 0l4-4a3.5 3.5 0 0 0-5-5l-.5.5" />
-									<path d="M14 10a3.5 3.5 0 0 0-5 0l-4 4a3.5 3.5 0 0 0 5 5l.5-.5" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Quote"
-									shortcut="⌘⇧."
-									onClick={() => insertMarkdown("> ", "", "quote")}
-								>
-									<path d="M3 21c3 0 7-1 7-8V5c0-1.25-.756-2.017-2-2H4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2 1 0 1 0 1 1v1c0 1-1 2-2 2s-1 .008-1 1.031V21z" />
-									<path d="M15 21c3 0 7-1 7-8V5c0-1.25-.757-2.017-2-2h-4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2h.75c0 2.25.25 4-2.75 4v3c0 1 0 1 1 1z" />
-								</MdToolbarButton>
-								<span className="mx-1 h-4 w-px bg-border" />
-								<MdToolbarButton
-									label="Unordered list"
-									shortcut="⌘⇧8"
-									onClick={() => insertMarkdown("- ", "", "item")}
-								>
-									<path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Ordered list"
-									shortcut="⌘⇧7"
-									onClick={() => insertMarkdown("1. ", "", "item")}
-								>
-									<path d="M10 6h11M10 12h11M10 18h11M4 6h1v4M3 10h3M4 14.5a.5.5 0 0 1 .5-.5H5a.5.5 0 0 1 .5.5v0a1.5 1.5 0 0 1-1.5 1.5H3.5a.5.5 0 0 0-.5.5v0a.5.5 0 0 0 .5.5H5a.5.5 0 0 1 .5.5v0a1.5 1.5 0 0 1-1.5 1.5H3" />
-								</MdToolbarButton>
-								<MdToolbarButton
-									label="Task list"
-									onClick={() => insertMarkdown("- [ ] ", "", "task")}
-								>
-									<path d="M9 11l3 3L22 4" />
-									<path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11" />
-								</MdToolbarButton>
-							</div>
-						</TooltipProvider>
-					)}
-				</div>
-				<div className="rounded-lg border bg-surface-0">
-					{editTab === "edit" ? (
-						<HighlightedMarkdownEditor
-							value={draft}
-							onChange={setDraft}
-							placeholder="Write a description..."
-							textareaRef={editorRef}
-							onKeyDown={handleEditorKeyDown}
-						/>
-					) : (
-						<div className="min-h-[200px] p-5">
-							{draft ? (
-								<Markdown>{draft}</Markdown>
-							) : (
-								<p className="text-sm italic text-muted-foreground">
-									Nothing to preview
-								</p>
-							)}
-						</div>
-					)}
-				</div>
+				<MarkdownEditor
+					value={draft}
+					onChange={setDraft}
+					placeholder="Write a description..."
+				/>
 				<div className="flex items-center justify-end gap-2 pt-2">
 					<button
 						type="button"
@@ -348,116 +155,3 @@ export function PullBodySection({
 		</div>
 	);
 }
-
-function MdToolbarButton({
-	label,
-	shortcut,
-	onClick,
-	children,
-}: {
-	label: string;
-	shortcut?: string;
-	onClick: () => void;
-	children: React.ReactNode;
-}) {
-	return (
-		<Tooltip>
-			<TooltipTrigger asChild>
-				<button
-					type="button"
-					onClick={onClick}
-					className="flex size-7 items-center justify-center rounded-md transition-colors hover:bg-surface-1 hover:text-foreground"
-				>
-					<svg
-						aria-hidden="true"
-						fill="none"
-						height={15}
-						stroke="currentColor"
-						strokeLinecap="round"
-						strokeLinejoin="round"
-						strokeWidth={2}
-						viewBox="0 0 24 24"
-						width={15}
-					>
-						{children}
-					</svg>
-				</button>
-			</TooltipTrigger>
-			<TooltipContent>
-				<span className="flex items-center gap-1.5">
-					{label}
-					{shortcut && (
-						<kbd className="rounded bg-foreground/10 px-1 font-mono text-[10px]">
-							{shortcut}
-						</kbd>
-					)}
-				</span>
-			</TooltipContent>
-		</Tooltip>
-	);
-}
-
-function HighlightedMarkdownEditor({
-	value,
-	onChange,
-	placeholder,
-	textareaRef: externalRef,
-	onKeyDown,
-}: {
-	value: string;
-	onChange: (value: string) => void;
-	placeholder?: string;
-	textareaRef?: React.RefObject<HTMLTextAreaElement | null>;
-	onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
-}) {
-	const [highlightedHtml, setHighlightedHtml] = useState("");
-	const internalRef = useRef<HTMLTextAreaElement>(null);
-	const textareaRef = externalRef || internalRef;
-	const highlightRef = useRef<HTMLDivElement>(null);
-
-	useEffect(() => {
-		let cancelled = false;
-		if (!value) {
-			setHighlightedHtml("");
-			return;
-		}
-		highlightCode(value, "markdown").then((html) => {
-			if (!cancelled) {
-				setHighlightedHtml(html);
-			}
-		});
-		return () => {
-			cancelled = true;
-		};
-	}, [value]);
-
-	const syncScroll = () => {
-		if (highlightRef.current && textareaRef.current) {
-			highlightRef.current.scrollTop = textareaRef.current.scrollTop;
-			highlightRef.current.scrollLeft = textareaRef.current.scrollLeft;
-		}
-	};
-
-	return (
-		<div className="relative" style={{ height: 640, maxHeight: 1200 }}>
-			<div
-				ref={highlightRef}
-				aria-hidden
-				className="pointer-events-none absolute inset-0 overflow-auto whitespace-pre-wrap break-words p-5 [scrollbar-width:none] [word-break:break-all] [&::-webkit-scrollbar]:hidden [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:!whitespace-pre-wrap [&_pre]:!break-words [&_pre]:font-mono [&_pre]:text-sm [&_pre]:!leading-[1.625] [&_code]:!font-mono [&_code]:!text-sm [&_code]:!leading-[1.625]"
-				// biome-ignore lint/security/noDangerouslySetInnerHtml: HTML from shiki highlighter is trusted
-				dangerouslySetInnerHTML={{ __html: highlightedHtml }}
-			/>
-			<textarea
-				ref={textareaRef}
-				value={value}
-				onChange={(event) => onChange(event.target.value)}
-				onKeyDown={onKeyDown}
-				onScroll={syncScroll}
-				className="relative w-full resize-y whitespace-pre-wrap break-words bg-transparent p-5 font-mono text-sm leading-[1.625] text-transparent caret-foreground outline-none [word-break:break-all] placeholder:text-muted-foreground"
-				style={{ height: 640, maxHeight: 1200 }}
-				placeholder={placeholder}
-				spellCheck={false}
-			/>
-		</div>
-	);
-}
diff --git a/apps/dashboard/src/components/pulls/detail/pull-detail-activity.tsx b/apps/dashboard/src/components/pulls/detail/pull-detail-activity.tsx
index 03927a1..29ff637 100644
--- a/apps/dashboard/src/components/pulls/detail/pull-detail-activity.tsx
+++ b/apps/dashboard/src/components/pulls/detail/pull-detail-activity.tsx
@@ -57,6 +57,7 @@ import {
 import type {
 	CommentPagination,
 	EventPagination,
+	GitHubActor,
 	PullCheckRun,
 	PullComment,
 	PullCommit,
@@ -178,12 +179,49 @@ export function PullDetailActivitySection({
 			)}
 
 			<div className="mt-6">
-				<DetailCommentBox />
+				<DetailCommentBox
+					owner={owner}
+					repo={repo}
+					issueNumber={pullNumber}
+					scope={scope}
+					involvedUsers={getInvolvedUsers(pr, comments)}
+				/>
 			</div>
 		</div>
 	);
 }
 
+function getInvolvedUsers(
+	pr: PullDetail,
+	comments?: PullComment[],
+): GitHubActor[] {
+	const seen = new Set<string>();
+	const users: GitHubActor[] = [];
+
+	const add = (actor: GitHubActor | null | undefined) => {
+		if (!actor || seen.has(actor.login)) return;
+		seen.add(actor.login);
+		users.push(actor);
+	};
+
+	// PR author first
+	add(pr.author);
+
+	// Requested reviewers
+	for (const reviewer of pr.requestedReviewers) {
+		add(reviewer);
+	}
+
+	// Commenters (most recent first to prioritize active participants)
+	if (comments) {
+		for (let i = comments.length - 1; i >= 0; i--) {
+			add(comments[i].author);
+		}
+	}
+
+	return users;
+}
+
 // ── Merge status section — owns its own polling query ────────────────
 
 function MergeStatusSection({
diff --git a/apps/dashboard/src/components/pulls/review/review-diff-pane.tsx b/apps/dashboard/src/components/pulls/review/review-diff-pane.tsx
index daec247..1c9a14d 100644
--- a/apps/dashboard/src/components/pulls/review/review-diff-pane.tsx
+++ b/apps/dashboard/src/components/pulls/review/review-diff-pane.tsx
@@ -1,3 +1,4 @@
+import type { MentionConfig } from "@diffkit/ui/components/markdown-editor";
 import type { SelectedLineRange } from "@pierre/diffs";
 import type { DiffLineAnnotation } from "@pierre/diffs/react";
 import {
@@ -43,6 +44,8 @@ type ReviewDiffPaneProps = {
 	onStartComment: (filename: string, range: SelectedLineRange) => void;
 	onCancelComment: () => void;
 	onAddComment: (comment: PendingComment) => void;
+	onEditComment: (original: PendingComment, newBody: string) => void;
+	mentionConfig?: MentionConfig;
 };
 
 export const ReviewDiffPane = memo(
@@ -62,6 +65,8 @@ export const ReviewDiffPane = memo(
 			onStartComment,
 			onCancelComment,
 			onAddComment,
+			onEditComment,
+			mentionConfig,
 		},
 		ref,
 	) {
@@ -348,6 +353,8 @@ export const ReviewDiffPane = memo(
 							onGutterClick={onStartComment}
 							onCancelComment={onCancelComment}
 							onAddComment={onAddComment}
+							onEditComment={onEditComment}
+							mentionConfig={mentionConfig}
 						/>
 					))}
 
diff --git a/apps/dashboard/src/components/pulls/review/review-file-diff-block.tsx b/apps/dashboard/src/components/pulls/review/review-file-diff-block.tsx
index b663430..c85c731 100644
--- a/apps/dashboard/src/components/pulls/review/review-file-diff-block.tsx
+++ b/apps/dashboard/src/components/pulls/review/review-file-diff-block.tsx
@@ -1,5 +1,9 @@
-import { CheckIcon, CommentIcon, CopyIcon } from "@diffkit/icons";
+import { CheckIcon, CommentIcon, CopyIcon, EditIcon } from "@diffkit/icons";
 import { Markdown } from "@diffkit/ui/components/markdown";
+import {
+	MarkdownEditor,
+	type MentionConfig,
+} from "@diffkit/ui/components/markdown-editor";
 import { vercelDark, vercelLight } from "@diffkit/ui/lib/shiki-themes";
 import { cn } from "@diffkit/ui/lib/utils";
 import type { SelectedLineRange } from "@pierre/diffs";
@@ -12,9 +16,7 @@ import {
 	memo,
 	Suspense,
 	useCallback,
-	useEffect,
 	useMemo,
-	useRef,
 	useState,
 } from "react";
 import { formatRelativeTime } from "#/lib/format-relative-time";
@@ -78,6 +80,8 @@ export const ReviewFileDiffBlock = memo(function ReviewFileDiffBlock({
 	onGutterClick,
 	onCancelComment,
 	onAddComment,
+	onEditComment,
+	mentionConfig,
 }: {
 	id: string;
 	file: PullFile;
@@ -90,6 +94,8 @@ export const ReviewFileDiffBlock = memo(function ReviewFileDiffBlock({
 	onGutterClick: (filename: string, range: SelectedLineRange) => void;
 	onCancelComment: () => void;
 	onAddComment: (comment: PendingComment) => void;
+	onEditComment: (original: PendingComment, newBody: string) => void;
+	mentionConfig?: MentionConfig;
 }) {
 	const [isCollapsed, setIsCollapsed] = useState(false);
 	const { resolvedTheme } = useTheme();
@@ -239,13 +245,18 @@ export const ReviewFileDiffBlock = memo(function ReviewFileDiffBlock({
 												})
 											}
 											onCancel={onCancelComment}
+											mentionConfig={mentionConfig}
 										/>
 									);
 								}
 
 								if ("body" in data && !("id" in data)) {
 									return (
-										<PendingCommentBubble comment={data as PendingComment} />
+										<PendingCommentBubble
+											comment={data as PendingComment}
+											onEdit={onEditComment}
+											mentionConfig={mentionConfig}
+										/>
 									);
 								}
 
@@ -353,33 +364,30 @@ function InlineCommentForm({
 	endLine,
 	onSubmit,
 	onCancel,
+	mentionConfig,
 }: {
 	isMultiLine?: boolean;
 	startLine?: number;
 	endLine?: number;
 	onSubmit: (body: string) => void;
 	onCancel: () => void;
+	mentionConfig?: MentionConfig;
 }) {
 	const [body, setBody] = useState("");
-	const textareaRef = useRef<HTMLTextAreaElement>(null);
-
-	useEffect(() => {
-		textareaRef.current?.focus();
-	}, []);
 
 	return (
-		<div className="mx-2 my-1 flex flex-col gap-2 rounded-lg border bg-surface-0 p-3">
+		<div className="mx-2 my-1 flex flex-col gap-2">
 			{isMultiLine && startLine != null && endLine != null && (
 				<div className="text-xs text-muted-foreground">
 					Commenting on lines {startLine}–{endLine}
 				</div>
 			)}
-			<textarea
-				ref={textareaRef}
+			<MarkdownEditor
 				value={body}
-				onChange={(event) => setBody(event.target.value)}
+				onChange={setBody}
 				placeholder="Leave a comment..."
-				className="min-h-[60px] w-full resize-y rounded-md border bg-background px-3 py-2 text-xs outline-none placeholder:text-muted-foreground focus:border-blue-500 focus:ring-1 focus:ring-blue-500"
+				compact
+				mentions={mentionConfig}
 			/>
 			<div className="flex items-center justify-end gap-2">
 				<button
@@ -406,45 +414,103 @@ function InlineCommentForm({
 
 function ReviewCommentBubble({ comment }: { comment: PullReviewComment }) {
 	return (
-		<div className="mx-2 my-1 rounded-lg border bg-surface-0 p-3">
-			<div className="mb-2 flex items-center gap-2">
-				{comment.author && (
-					<>
-						<img
-							src={comment.author.avatarUrl}
-							alt={comment.author.login}
-							className="size-5 rounded-full border border-border"
-						/>
-						<span className="text-xs font-medium">{comment.author.login}</span>
-					</>
+		<div className="mx-2 my-1 rounded-lg border bg-surface-0 px-3 py-2.5">
+			<div className="mb-1.5 flex items-center gap-1.5">
+				{comment.author ? (
+					<img
+						src={comment.author.avatarUrl}
+						alt={comment.author.login}
+						className="size-4 rounded-full border border-border"
+					/>
+				) : (
+					<div className="size-4 rounded-full bg-surface-2" />
 				)}
-				<span className="text-xs text-muted-foreground">
+				<span className="text-[13px] font-medium">
+					{comment.author?.login ?? "Unknown"}
+				</span>
+				<span className="text-[13px] text-muted-foreground">
 					{formatRelativeTime(comment.createdAt)}
 				</span>
 			</div>
-			<div className="text-xs">
-				<Markdown>{comment.body}</Markdown>
-			</div>
+			<Markdown className="text-muted-foreground">{comment.body}</Markdown>
 		</div>
 	);
 }
 
-function PendingCommentBubble({ comment }: { comment: PendingComment }) {
+function PendingCommentBubble({
+	comment,
+	onEdit,
+	mentionConfig,
+}: {
+	comment: PendingComment;
+	onEdit: (original: PendingComment, newBody: string) => void;
+	mentionConfig?: MentionConfig;
+}) {
 	const isMultiLine =
 		comment.startLine != null && comment.startLine !== comment.line;
+	const [isEditing, setIsEditing] = useState(false);
+	const [draft, setDraft] = useState(comment.body);
+
+	if (isEditing) {
+		return (
+			<div className="mx-2 my-1 flex flex-col gap-2">
+				<MarkdownEditor
+					value={draft}
+					onChange={setDraft}
+					placeholder="Leave a comment..."
+					compact
+					mentions={mentionConfig}
+				/>
+				<div className="flex items-center justify-end gap-2">
+					<button
+						type="button"
+						onClick={() => {
+							setDraft(comment.body);
+							setIsEditing(false);
+						}}
+						className="rounded-md px-3 py-1.5 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground"
+					>
+						Cancel
+					</button>
+					<button
+						type="button"
+						onClick={() => {
+							if (draft.trim()) {
+								onEdit(comment, draft.trim());
+								setIsEditing(false);
+							}
+						}}
+						disabled={!draft.trim()}
+						className="rounded-md bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-opacity disabled:opacity-50"
+					>
+						Update
+					</button>
+				</div>
+			</div>
+		);
+	}
 
 	return (
-		<div className="mx-2 my-1 rounded-lg border border-yellow-500/30 bg-yellow-500/5 p-3">
-			<div className="mb-1 flex items-center gap-1.5 text-xs text-yellow-600 dark:text-yellow-400">
-				<CommentIcon size={12} strokeWidth={2} />
-				<span className="font-medium">
+		<div className="mx-2 my-1 rounded-lg border border-dashed bg-surface-0 px-3 py-2.5">
+			<div className="mb-1.5 flex items-center gap-1.5">
+				<CommentIcon
+					size={12}
+					strokeWidth={2}
+					className="text-muted-foreground"
+				/>
+				<span className="text-[13px] font-medium text-muted-foreground">
 					Pending
-					{isMultiLine ? ` (lines ${comment.startLine}–${comment.line})` : ""}
+					{isMultiLine ? ` · lines ${comment.startLine}–${comment.line}` : ""}
 				</span>
+				<button
+					type="button"
+					onClick={() => setIsEditing(true)}
+					className="ml-auto flex size-6 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-surface-1 hover:text-foreground"
+				>
+					<EditIcon size={12} strokeWidth={2} />
+				</button>
 			</div>
-			<div className="text-xs">
-				<Markdown>{comment.body}</Markdown>
-			</div>
+			<Markdown className="text-muted-foreground">{comment.body}</Markdown>
 		</div>
 	);
 }
diff --git a/apps/dashboard/src/components/pulls/review/review-page.tsx b/apps/dashboard/src/components/pulls/review/review-page.tsx
index c7d412c..d40c0a2 100644
--- a/apps/dashboard/src/components/pulls/review/review-page.tsx
+++ b/apps/dashboard/src/components/pulls/review/review-page.tsx
@@ -9,11 +9,13 @@ import {
 	DrawerContent,
 	DrawerTitle,
 } from "@diffkit/ui/components/drawer";
+import type { MentionConfig } from "@diffkit/ui/components/markdown-editor";
 import {
 	ResizableHandle,
 	ResizablePanel,
 	ResizablePanelGroup,
 } from "@diffkit/ui/components/resizable";
+import { toast } from "@diffkit/ui/components/sonner";
 import { cn } from "@diffkit/ui/lib/utils";
 import type { SelectedLineRange } from "@pierre/diffs";
 import type { DiffLineAnnotation } from "@pierre/diffs/react";
@@ -41,13 +43,17 @@ import {
 	githubPullPageQueryOptions,
 	githubPullReviewCommentsQueryOptions,
 	githubQueryKeys,
+	githubRepoCollaboratorsQueryOptions,
+	githubViewerQueryOptions,
 } from "#/lib/github.query";
 import type {
+	GitHubActor,
 	PullDetail,
 	PullFileSummary,
 	PullReviewComment,
 } from "#/lib/github.types";
 import { useRegisterTab } from "#/lib/use-register-tab";
+import { checkPermissionWarning } from "#/lib/warning-store";
 import type { ReviewDiffPaneHandle } from "./review-diff-pane";
 import {
 	type ActiveFileStore,
@@ -140,6 +146,69 @@ export function ReviewPage() {
 	);
 	const reviewComments = reviewCommentsQuery.data ?? [];
 
+	// ── Mention support for inline comment forms ──────────────────────
+	const [mentionActivated, setMentionActivated] = useState(false);
+	const viewerQuery = useQuery(githubViewerQueryOptions(scope));
+	const collaboratorsQuery = useQuery({
+		...githubRepoCollaboratorsQueryOptions(scope, { owner, repo }),
+		enabled: mentionActivated,
+	});
+
+	const mentionConfig: MentionConfig = useMemo(() => {
+		const viewerLogin = viewerQuery.data?.login;
+		const seen = new Set<string>();
+		const candidates: MentionConfig["candidates"] = [];
+
+		if (viewerLogin) seen.add(viewerLogin);
+
+		const add = (actor: GitHubActor | null | undefined) => {
+			if (!actor || seen.has(actor.login)) return;
+			seen.add(actor.login);
+			candidates.push({
+				id: actor.login,
+				label: actor.login,
+				avatarUrl: actor.avatarUrl,
+				secondary: actor.type === "Bot" ? "Bot" : undefined,
+			});
+		};
+
+		// PR author first
+		if (pr) {
+			add(pr.author);
+			for (const r of pr.requestedReviewers) add(r);
+		}
+
+		// Review commenters (most recent first)
+		for (let i = reviewComments.length - 1; i >= 0; i--) {
+			add(reviewComments[i].author);
+		}
+
+		// Remaining collaborators
+		for (const c of collaboratorsQuery.data ?? []) {
+			if (seen.has(c.login)) continue;
+			seen.add(c.login);
+			candidates.push({
+				id: c.login,
+				label: c.login,
+				avatarUrl: c.avatarUrl,
+				secondary: c.type === "Bot" ? "Bot" : undefined,
+			});
+		}
+
+		return {
+			candidates,
+			onActivate: () => setMentionActivated(true),
+			isLoading: collaboratorsQuery.isLoading && mentionActivated,
+		};
+	}, [
+		viewerQuery.data?.login,
+		pr,
+		reviewComments,
+		collaboratorsQuery.data,
+		collaboratorsQuery.isLoading,
+		mentionActivated,
+	]);
+
 	const [diffStyle, setDiffStyle] = useState<"unified" | "split">("unified");
 	const [pendingComments, setPendingComments] = useState<PendingComment[]>([]);
 	const [activeCommentForm, setActiveCommentForm] =
@@ -223,6 +292,22 @@ export function ReviewPage() {
 		setActiveCommentForm(null);
 	}, []);
 
+	const handleEditComment = useCallback(
+		(original: PendingComment, newBody: string) => {
+			setPendingComments((previous) =>
+				previous.map((c) =>
+					c.path === original.path &&
+					c.line === original.line &&
+					c.side === original.side &&
+					c.startLine === original.startLine
+						? { ...c, body: newBody }
+						: c,
+				),
+			);
+		},
+		[],
+	);
+
 	const handleCancelComment = useCallback(() => {
 		setActiveCommentForm(null);
 		setSelectedLines(null);
@@ -266,7 +351,7 @@ export function ReviewPage() {
 	);
 
 	const handleSubmitReview = useCallback(
-		async (body: string, event: ReviewEvent) => {
+		async (body: string, event: ReviewEvent): Promise<boolean> => {
 			setIsSubmitting(true);
 			try {
 				const success = await submitPullReview({
@@ -297,7 +382,28 @@ export function ReviewPage() {
 					void queryClient.invalidateQueries({
 						queryKey: githubQueryKeys.all,
 					});
+				} else {
+					toast.error("Failed to submit review");
+				}
+
+				return success;
+			} catch (error) {
+				console.error("[submitReview]", error);
+				const message =
+					error instanceof Error ? error.message : "Unknown error";
+				const isAccessRestriction =
+					message.includes("OAuth App access restrictions") ||
+					message.includes("Insufficient permissions");
+				checkPermissionWarning(
+					{ ok: false, error: message },
+					`${owner}/${repo}`,
+				);
+				if (!isAccessRestriction) {
+					toast.error("Failed to submit review", {
+						description: message,
+					});
 				}
+				return false;
 			} finally {
 				setIsSubmitting(false);
 			}
@@ -348,6 +454,8 @@ export function ReviewPage() {
 				onStartComment={handleStartComment}
 				onCancelComment={handleCancelComment}
 				onAddComment={handleAddComment}
+				onEditComment={handleEditComment}
+				mentionConfig={mentionConfig}
 			/>
 		</Suspense>
 	) : (
@@ -436,7 +544,7 @@ const ReviewToolbar = memo(function ReviewToolbar({
 	onSetDiffStyle: (style: "unified" | "split") => void;
 	pendingCount: number;
 	isSubmitting: boolean;
-	onSubmitReview: (body: string, event: ReviewEvent) => Promise<void>;
+	onSubmitReview: (body: string, event: ReviewEvent) => Promise<boolean>;
 	onOpenFileSheet: () => void;
 	isDesktop: boolean;
 }) {
diff --git a/apps/dashboard/src/components/pulls/review/review-submit-popover.tsx b/apps/dashboard/src/components/pulls/review/review-submit-popover.tsx
index 0e2c5c4..895aed1 100644
--- a/apps/dashboard/src/components/pulls/review/review-submit-popover.tsx
+++ b/apps/dashboard/src/components/pulls/review/review-submit-popover.tsx
@@ -70,17 +70,19 @@ export function ReviewSubmitPopover({
 }: {
 	pendingCount: number;
 	isSubmitting: boolean;
-	onSubmit: (body: string, event: ReviewEvent) => void;
+	onSubmit: (body: string, event: ReviewEvent) => Promise<boolean>;
 }) {
 	const [body, setBody] = useState("");
 	const [event, setEvent] = useState<ReviewEvent>("COMMENT");
 	const [isOpen, setIsOpen] = useState(false);
 	const isDesktop = useIsDesktop();
 
-	const handleSubmit = () => {
-		onSubmit(body, event);
-		setBody("");
-		setIsOpen(false);
+	const handleSubmit = async () => {
+		const success = await onSubmit(body, event);
+		if (success) {
+			setBody("");
+			setIsOpen(false);
+		}
 	};
 
 	const trigger = (
diff --git a/apps/dashboard/src/lib/github.functions.ts b/apps/dashboard/src/lib/github.functions.ts
index 3d229e6..02766c3 100644
--- a/apps/dashboard/src/lib/github.functions.ts
+++ b/apps/dashboard/src/lib/github.functions.ts
@@ -3602,8 +3602,10 @@ export const submitPullReview = createServerFn({ method: "POST" })
 				pullNumber: data.pullNumber,
 			});
 			return true;
-		} catch {
-			return false;
+		} catch (error) {
+			console.error("[submitPullReview] Failed:", error);
+			const message = error instanceof Error ? error.message : "Unknown error";
+			throw new Error(message);
 		}
 	});
 
@@ -3658,6 +3660,65 @@ export const createReviewComment = createServerFn({ method: "POST" })
 		}
 	});
 
+// ── Create issue/PR comment ────────────────────────────────────────
+
+export type CreateCommentInput = {
+	owner: string;
+	repo: string;
+	issueNumber: number;
+	body: string;
+};
+
+export const createComment = createServerFn({ method: "POST" })
+	.inputValidator(identityValidator<CreateCommentInput>)
+	.handler(async ({ data }): Promise<MutationResult> => {
+		const context = await getGitHubUserContextForRepository(data);
+		if (!context) {
+			return { ok: false, error: "Not authenticated" };
+		}
+
+		try {
+			await context.octokit.rest.issues.createComment({
+				owner: data.owner,
+				repo: data.repo,
+				issue_number: data.issueNumber,
+				body: data.body,
+			});
+
+			// Bust caches so the comment appears immediately
+			const userId = context.session.user.id;
+			await Promise.all([
+				bustGitHubCache(userId, "issues.comments", {
+					owner: data.owner,
+					repo: data.repo,
+					issueNumber: data.issueNumber,
+				}),
+				bustGitHubCache(userId, "pulls.comments", {
+					owner: data.owner,
+					repo: data.repo,
+					pullNumber: data.issueNumber,
+				}),
+				// Bump namespace versions to invalidate split-mode KV payloads
+				bumpGitHubCacheNamespaces([
+					githubRevalidationSignalKeys.pullEntity({
+						owner: data.owner,
+						repo: data.repo,
+						pullNumber: data.issueNumber,
+					}),
+					githubRevalidationSignalKeys.issueEntity({
+						owner: data.owner,
+						repo: data.repo,
+						issueNumber: data.issueNumber,
+					}),
+				]),
+			]);
+
+			return { ok: true };
+		} catch (error) {
+			return toMutationError("create comment", error);
+		}
+	});
+
 export type RepoCollaboratorsInput = {
 	owner: string;
 	repo: string;
diff --git a/apps/dashboard/src/lib/warning-store.ts b/apps/dashboard/src/lib/warning-store.ts
index 613a317..18fdf62 100644
--- a/apps/dashboard/src/lib/warning-store.ts
+++ b/apps/dashboard/src/lib/warning-store.ts
@@ -62,24 +62,31 @@ export function checkPermissionWarning(
 	result: { ok: boolean; error?: string; installUrl?: string },
 	repo: string,
 ) {
-	if (
-		!result.ok &&
-		result.error &&
-		result.error.includes("Insufficient permissions")
-	) {
-		const [owner = repo] = repo.split("/");
+	if (!result.ok && result.error) {
+		const isInsufficientPermissions = result.error.includes(
+			"Insufficient permissions",
+		);
+		const isOrgRestriction = result.error.includes(
+			"OAuth App access restrictions",
+		);
 
-		addWarning({
-			id: `permissions:${repo}`,
-			message: `Your GitHub App may not have sufficient permissions for ${repo}.`,
-			dismissible: true,
-			action: {
-				kind: "github-access",
-				label: "Configure access",
-				href: result.installUrl,
-				owner,
-				repo,
-			},
-		});
+		if (isInsufficientPermissions || isOrgRestriction) {
+			const [owner = repo] = repo.split("/");
+
+			addWarning({
+				id: `permissions:${repo}`,
+				message: isOrgRestriction
+					? `The organization that owns ${repo} has restricted third-party access. You need to request or grant access.`
+					: `Your GitHub App may not have sufficient permissions for ${repo}.`,
+				dismissible: true,
+				action: {
+					kind: "github-access",
+					label: "Configure access",
+					href: result.installUrl,
+					owner,
+					repo,
+				},
+			});
+		}
 	}
 }

From d95a05dd5ec897660e2f0270f4efa6a7b6fcb7a3 Mon Sep 17 00:00:00 2001
From: Alan Daniel <stylesshjs@gmail.com>
Date: Sun, 12 Apr 2026 23:05:49 -0400
Subject: [PATCH 2/2] Add MarkdownEditor component and caret coordinates
 utility

---
 .../ui/src/components/markdown-editor.tsx     | 643 ++++++++++++++++++
 packages/ui/src/lib/get-caret-coordinates.ts  |  80 +++
 2 files changed, 723 insertions(+)
 create mode 100644 packages/ui/src/components/markdown-editor.tsx
 create mode 100644 packages/ui/src/lib/get-caret-coordinates.ts

diff --git a/packages/ui/src/components/markdown-editor.tsx b/packages/ui/src/components/markdown-editor.tsx
new file mode 100644
index 0000000..549f6c2
--- /dev/null
+++ b/packages/ui/src/components/markdown-editor.tsx
@@ -0,0 +1,643 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { getCaretCoordinates } from "../lib/get-caret-coordinates";
+import { cn } from "../lib/utils";
+import { highlightCode, Markdown } from "./markdown";
+import { Spinner } from "./spinner";
+import {
+	Tooltip,
+	TooltipContent,
+	TooltipProvider,
+	TooltipTrigger,
+} from "./tooltip";
+
+// ── Mention types ─────────────────────────────────────────────────
+
+export type MentionCandidate = {
+	id: string;
+	label: string;
+	avatarUrl?: string;
+	secondary?: string;
+};
+
+export type MentionConfig = {
+	candidates: MentionCandidate[];
+	onActivate?: () => void;
+	isLoading?: boolean;
+};
+
+// ── Editor props ──────────────────────────────────────────────────
+
+type MarkdownEditorProps = {
+	value: string;
+	onChange: (value: string) => void;
+	placeholder?: string;
+	/** Compact mode for comment boxes — shorter height, no syntax highlight overlay */
+	compact?: boolean;
+	onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+	textareaRef?: React.RefObject<HTMLTextAreaElement | null>;
+	mentions?: MentionConfig;
+};
+
+// ── Mention hook ──────────────────────────────────────────────────
+
+type MentionState = {
+	query: string;
+	triggerIndex: number;
+} | null;
+
+function useMentions(
+	editorRef: React.RefObject<HTMLTextAreaElement | null>,
+	value: string,
+	onChange: (value: string) => void,
+	config?: MentionConfig,
+) {
+	const [mentionState, setMentionState] = useState<MentionState>(null);
+	const [activeIndex, setActiveIndex] = useState(0);
+	const [dropdownPos, setDropdownPos] = useState<{
+		top: number;
+		left: number;
+	} | null>(null);
+	const activatedRef = useRef(false);
+
+	const filtered = useMemo(() => {
+		if (!mentionState || !config) return [];
+		const q = mentionState.query.toLowerCase();
+		return config.candidates.filter((c) => c.label.toLowerCase().includes(q));
+	}, [mentionState, config]);
+
+	const detectMention = useCallback(() => {
+		const textarea = editorRef.current;
+		if (!textarea || !config) return;
+
+		const cursor = textarea.selectionStart;
+		const text = value.slice(0, cursor);
+
+		// Walk backwards to find @ preceded by whitespace or at start
+		let triggerIdx = -1;
+		for (let i = text.length - 1; i >= 0; i--) {
+			const ch = text[i];
+			if (ch === "@") {
+				if (i === 0 || /\s/.test(text[i - 1])) {
+					triggerIdx = i;
+				}
+				break;
+			}
+			// Stop on whitespace — no valid @mention
+			if (/\s/.test(ch)) break;
+		}
+
+		if (triggerIdx === -1) {
+			setMentionState(null);
+			return;
+		}
+
+		const query = text.slice(triggerIdx + 1);
+		setMentionState({ query, triggerIndex: triggerIdx });
+		setActiveIndex(0);
+
+		// Fire onActivate once
+		if (!activatedRef.current) {
+			activatedRef.current = true;
+			config.onActivate?.();
+		}
+
+		// Measure caret position for dropdown
+		const coords = getCaretCoordinates(textarea, cursor);
+		const rect = textarea.getBoundingClientRect();
+		setDropdownPos({
+			top: rect.top + coords.top + 20,
+			left: rect.left + coords.left,
+		});
+	}, [editorRef, value, config]);
+
+	const selectCandidate = useCallback(
+		(candidate: MentionCandidate) => {
+			if (!mentionState) return;
+			const textarea = editorRef.current;
+			if (!textarea) return;
+
+			const before = value.slice(0, mentionState.triggerIndex);
+			const after = value.slice(
+				mentionState.triggerIndex + 1 + mentionState.query.length,
+			);
+			const insertion = `@${candidate.label} `;
+			const newValue = before + insertion + after;
+			onChange(newValue);
+
+			const cursorPos = mentionState.triggerIndex + insertion.length;
+			requestAnimationFrame(() => {
+				textarea.focus();
+				textarea.setSelectionRange(cursorPos, cursorPos);
+			});
+
+			setMentionState(null);
+		},
+		[mentionState, value, onChange, editorRef],
+	);
+
+	const handleMentionKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLTextAreaElement>): boolean => {
+			if (!mentionState || filtered.length === 0) return false;
+
+			switch (event.key) {
+				case "ArrowDown":
+					event.preventDefault();
+					setActiveIndex((i) => (i + 1) % filtered.length);
+					return true;
+				case "ArrowUp":
+					event.preventDefault();
+					setActiveIndex((i) => (i <= 0 ? filtered.length - 1 : i - 1));
+					return true;
+				case "Enter":
+				case "Tab":
+					event.preventDefault();
+					selectCandidate(filtered[activeIndex]);
+					return true;
+				case "Escape":
+					event.preventDefault();
+					setMentionState(null);
+					return true;
+				default:
+					return false;
+			}
+		},
+		[mentionState, filtered, activeIndex, selectCandidate],
+	);
+
+	const dismiss = useCallback(() => setMentionState(null), []);
+
+	return {
+		mentionState,
+		filtered,
+		activeIndex,
+		dropdownPos,
+		isLoading: config?.isLoading ?? false,
+		detectMention,
+		handleMentionKeyDown,
+		selectCandidate,
+		dismiss,
+	};
+}
+
+// ── Main component ────────────────────────────────────────────────
+
+export function MarkdownEditor({
+	value,
+	onChange,
+	placeholder = "Leave a comment...",
+	compact,
+	onKeyDown: externalOnKeyDown,
+	textareaRef: externalRef,
+	mentions: mentionConfig,
+}: MarkdownEditorProps) {
+	const [tab, setTab] = useState<"write" | "preview">("write");
+	const internalRef = useRef<HTMLTextAreaElement>(null);
+	const editorRef = externalRef || internalRef;
+
+	const {
+		mentionState,
+		filtered,
+		activeIndex,
+		dropdownPos,
+		isLoading: mentionLoading,
+		detectMention,
+		handleMentionKeyDown,
+		selectCandidate,
+		dismiss: dismissMention,
+	} = useMentions(editorRef, value, onChange, mentionConfig);
+
+	const insertMarkdown = useCallback(
+		(before: string, after = "", placeholderText = "") => {
+			const textarea = editorRef.current;
+			if (!textarea) return;
+			const start = textarea.selectionStart;
+			const end = textarea.selectionEnd;
+			const selected = value.slice(start, end);
+			const text = selected || placeholderText;
+			const newValue = `${value.slice(0, start)}${before}${text}${after}${value.slice(end)}`;
+			onChange(newValue);
+			requestAnimationFrame(() => {
+				textarea.focus();
+				const cursorStart = start + before.length;
+				textarea.setSelectionRange(cursorStart, cursorStart + text.length);
+			});
+		},
+		[value, onChange, editorRef],
+	);
+
+	const handleKeyDown = useCallback(
+		(event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+			// Mention dropdown takes priority
+			if (handleMentionKeyDown(event)) return;
+
+			const mod = event.metaKey || event.ctrlKey;
+			if (mod) {
+				const shortcuts: Record<string, () => void> = {
+					b: () => insertMarkdown("**", "**", "bold"),
+					i: () => insertMarkdown("_", "_", "italic"),
+					e: () => insertMarkdown("`", "`", "code"),
+					k: () => insertMarkdown("[", "](url)", "text"),
+					h: () => insertMarkdown("### ", "", "heading"),
+				};
+				const shiftShortcuts: Record<string, () => void> = {
+					".": () => insertMarkdown("> ", "", "quote"),
+					"8": () => insertMarkdown("- ", "", "item"),
+					"7": () => insertMarkdown("1. ", "", "item"),
+				};
+
+				const key = event.key.toLowerCase();
+				const action = event.shiftKey ? shiftShortcuts[key] : shortcuts[key];
+
+				if (action) {
+					event.preventDefault();
+					action();
+					return;
+				}
+			}
+			externalOnKeyDown?.(event);
+		},
+		[handleMentionKeyDown, insertMarkdown, externalOnKeyDown],
+	);
+
+	const handleChange = useCallback(
+		(newValue: string) => {
+			onChange(newValue);
+		},
+		[onChange],
+	);
+
+	// Detect mentions after value or cursor changes
+	// biome-ignore lint/correctness/useExhaustiveDependencies: value triggers re-detection of @mentions on text change
+	useEffect(() => {
+		if (tab === "write" && mentionConfig) {
+			detectMention();
+		}
+	}, [value, tab, mentionConfig, detectMention]);
+
+	return (
+		<div className="flex flex-col rounded-lg border bg-surface-0 overflow-hidden">
+			{/* Tabs + Toolbar */}
+			<div className="flex items-center justify-between border-b px-2 py-1.5 bg-surface-1">
+				<div className="flex items-center gap-0.5">
+					<button
+						type="button"
+						onClick={() => setTab("write")}
+						className={cn(
+							"rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+							tab === "write"
+								? "bg-surface-2 text-foreground"
+								: "text-muted-foreground hover:bg-surface-2 hover:text-foreground",
+						)}
+					>
+						Write
+					</button>
+					<button
+						type="button"
+						onClick={() => setTab("preview")}
+						className={cn(
+							"rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
+							tab === "preview"
+								? "bg-surface-2 text-foreground"
+								: "text-muted-foreground hover:bg-surface-2 hover:text-foreground",
+						)}
+					>
+						Preview
+					</button>
+				</div>
+
+				<TooltipProvider delayDuration={300}>
+					<div
+						className={cn(
+							"flex items-center gap-0.5 text-muted-foreground",
+							tab !== "write" && "invisible",
+						)}
+					>
+						<MdToolbarButton
+							label="Heading"
+							shortcut="⌘H"
+							onClick={() => insertMarkdown("### ", "", "heading")}
+						>
+							<path d="M4 12h8M4 4v16M12 4v16M20 8v8" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Bold"
+							shortcut="⌘B"
+							onClick={() => insertMarkdown("**", "**", "bold")}
+						>
+							<path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6zM6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Italic"
+							shortcut="⌘I"
+							onClick={() => insertMarkdown("_", "_", "italic")}
+						>
+							<path d="M10 4h4M8 20h4M15 4l-6 16" />
+						</MdToolbarButton>
+						<span className="mx-1 h-4 w-px bg-border" />
+						<MdToolbarButton
+							label="Code"
+							shortcut="⌘E"
+							onClick={() => insertMarkdown("`", "`", "code")}
+						>
+							<path d="M16 18l6-6-6-6M8 6l-6 6 6 6" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Link"
+							shortcut="⌘K"
+							onClick={() => insertMarkdown("[", "](url)", "text")}
+						>
+							<path d="M10 14a3.5 3.5 0 0 0 5 0l4-4a3.5 3.5 0 0 0-5-5l-.5.5" />
+							<path d="M14 10a3.5 3.5 0 0 0-5 0l-4 4a3.5 3.5 0 0 0 5 5l.5-.5" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Quote"
+							shortcut="⌘⇧."
+							onClick={() => insertMarkdown("> ", "", "quote")}
+						>
+							<path d="M3 21c3 0 7-1 7-8V5c0-1.25-.756-2.017-2-2H4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2 1 0 1 0 1 1v1c0 1-1 2-2 2s-1 .008-1 1.031V21z" />
+							<path d="M15 21c3 0 7-1 7-8V5c0-1.25-.757-2.017-2-2h-4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2h.75c0 2.25.25 4-2.75 4v3c0 1 0 1 1 1z" />
+						</MdToolbarButton>
+						<span className="mx-1 h-4 w-px bg-border" />
+						<MdToolbarButton
+							label="Unordered list"
+							shortcut="⌘⇧8"
+							onClick={() => insertMarkdown("- ", "", "item")}
+						>
+							<path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Ordered list"
+							shortcut="⌘⇧7"
+							onClick={() => insertMarkdown("1. ", "", "item")}
+						>
+							<path d="M10 6h11M10 12h11M10 18h11M4 6h1v4M3 10h3M4 14.5a.5.5 0 0 1 .5-.5H5a.5.5 0 0 1 .5.5v0a1.5 1.5 0 0 1-1.5 1.5H3.5a.5.5 0 0 0-.5.5v0a.5.5 0 0 0 .5.5H5a.5.5 0 0 1 .5.5v0a1.5 1.5 0 0 1-1.5 1.5H3" />
+						</MdToolbarButton>
+						<MdToolbarButton
+							label="Task list"
+							onClick={() => insertMarkdown("- [ ] ", "", "task")}
+						>
+							<path d="M9 11l3 3L22 4" />
+							<path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11" />
+						</MdToolbarButton>
+					</div>
+				</TooltipProvider>
+			</div>
+
+			{/* Editor / Preview */}
+			{tab === "write" ? (
+				<div className="relative">
+					{compact ? (
+						<textarea
+							ref={editorRef}
+							value={value}
+							onChange={(event) => handleChange(event.target.value)}
+							onKeyDown={handleKeyDown}
+							placeholder={placeholder}
+							rows={4}
+							className="w-full resize-none bg-transparent p-3 text-sm outline-none placeholder:text-muted-foreground"
+						/>
+					) : (
+						<HighlightedMarkdownEditor
+							value={value}
+							onChange={handleChange}
+							placeholder={placeholder}
+							textareaRef={editorRef}
+							onKeyDown={handleKeyDown}
+						/>
+					)}
+					{mentionState && dropdownPos && (
+						<MentionDropdown
+							candidates={filtered}
+							activeIndex={activeIndex}
+							isLoading={mentionLoading}
+							position={dropdownPos}
+							onSelect={selectCandidate}
+							onDismiss={dismissMention}
+						/>
+					)}
+				</div>
+			) : (
+				<div className={cn("p-4", compact ? "min-h-[120px]" : "min-h-[200px]")}>
+					{value ? (
+						<Markdown>{value}</Markdown>
+					) : (
+						<p className="text-sm italic text-muted-foreground">
+							Nothing to preview
+						</p>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}
+
+// ── Mention dropdown ──────────────────────────────────────────────
+
+function MentionDropdown({
+	candidates,
+	activeIndex,
+	isLoading,
+	position,
+	onSelect,
+	onDismiss,
+}: {
+	candidates: MentionCandidate[];
+	activeIndex: number;
+	isLoading: boolean;
+	position: { top: number; left: number };
+	onSelect: (candidate: MentionCandidate) => void;
+	onDismiss: () => void;
+}) {
+	const listRef = useRef<HTMLDivElement>(null);
+
+	// Scroll active item into view
+	useEffect(() => {
+		const list = listRef.current;
+		if (!list) return;
+		const item = list.children[activeIndex] as HTMLElement | undefined;
+		item?.scrollIntoView({ block: "nearest" });
+	}, [activeIndex]);
+
+	// Dismiss on outside click
+	useEffect(() => {
+		const handleClick = (e: MouseEvent) => {
+			if (listRef.current && !listRef.current.contains(e.target as Node)) {
+				onDismiss();
+			}
+		};
+		document.addEventListener("mousedown", handleClick);
+		return () => document.removeEventListener("mousedown", handleClick);
+	}, [onDismiss]);
+
+	const isEmpty = candidates.length === 0 && !isLoading;
+
+	return createPortal(
+		<div
+			ref={listRef}
+			className="fixed z-50 max-h-48 min-w-[200px] overflow-y-auto rounded-lg border bg-surface-0 py-1 shadow-lg"
+			style={{ top: position.top, left: position.left }}
+		>
+			{isLoading && candidates.length === 0 && (
+				<div className="flex items-center justify-center px-3 py-2">
+					<Spinner size={14} className="text-muted-foreground" />
+				</div>
+			)}
+			{isEmpty && (
+				<div className="px-3 py-2 text-xs text-muted-foreground">
+					No users found
+				</div>
+			)}
+			{candidates.map((candidate, index) => (
+				<button
+					key={candidate.id}
+					type="button"
+					onMouseDown={(e) => {
+						e.preventDefault();
+						onSelect(candidate);
+					}}
+					className={cn(
+						"flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm transition-colors",
+						index === activeIndex
+							? "bg-surface-2 text-foreground"
+							: "text-muted-foreground hover:bg-surface-1 hover:text-foreground",
+					)}
+				>
+					{candidate.avatarUrl ? (
+						<img
+							src={candidate.avatarUrl}
+							alt={candidate.label}
+							className="size-4 rounded-full"
+						/>
+					) : (
+						<div className="size-4 rounded-full bg-surface-2" />
+					)}
+					<span className="truncate">{candidate.label}</span>
+					{candidate.secondary && (
+						<span className="ml-auto shrink-0 text-xs text-muted-foreground">
+							{candidate.secondary}
+						</span>
+					)}
+				</button>
+			))}
+		</div>,
+		document.body,
+	);
+}
+
+// ── Toolbar button ─────────────────────────────────────────────────
+
+function MdToolbarButton({
+	label,
+	shortcut,
+	onClick,
+	children,
+}: {
+	label: string;
+	shortcut?: string;
+	onClick: () => void;
+	children: React.ReactNode;
+}) {
+	return (
+		<Tooltip>
+			<TooltipTrigger asChild>
+				<button
+					type="button"
+					onClick={onClick}
+					className="flex size-7 items-center justify-center rounded-md transition-colors hover:bg-surface-1 hover:text-foreground"
+				>
+					<svg
+						aria-hidden="true"
+						fill="none"
+						height={15}
+						stroke="currentColor"
+						strokeLinecap="round"
+						strokeLinejoin="round"
+						strokeWidth={2}
+						viewBox="0 0 24 24"
+						width={15}
+					>
+						{children}
+					</svg>
+				</button>
+			</TooltipTrigger>
+			<TooltipContent>
+				<span className="flex items-center gap-1.5">
+					{label}
+					{shortcut && (
+						<kbd className="rounded bg-foreground/10 px-1 font-mono text-[10px]">
+							{shortcut}
+						</kbd>
+					)}
+				</span>
+			</TooltipContent>
+		</Tooltip>
+	);
+}
+
+// ── Highlighted editor (full mode) ────────────────────────────────
+
+function HighlightedMarkdownEditor({
+	value,
+	onChange,
+	placeholder,
+	textareaRef: externalRef,
+	onKeyDown,
+}: {
+	value: string;
+	onChange: (value: string) => void;
+	placeholder?: string;
+	textareaRef?: React.RefObject<HTMLTextAreaElement | null>;
+	onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
+}) {
+	const [highlightedHtml, setHighlightedHtml] = useState("");
+	const internalRef = useRef<HTMLTextAreaElement>(null);
+	const textareaRef = externalRef || internalRef;
+	const highlightRef = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		let cancelled = false;
+		if (!value) {
+			setHighlightedHtml("");
+			return;
+		}
+		highlightCode(value, "markdown").then((html) => {
+			if (!cancelled) {
+				setHighlightedHtml(html);
+			}
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [value]);
+
+	const syncScroll = () => {
+		if (highlightRef.current && textareaRef.current) {
+			highlightRef.current.scrollTop = textareaRef.current.scrollTop;
+			highlightRef.current.scrollLeft = textareaRef.current.scrollLeft;
+		}
+	};
+
+	return (
+		<div className="relative" style={{ height: 640, maxHeight: 1200 }}>
+			<div
+				ref={highlightRef}
+				aria-hidden
+				className="pointer-events-none absolute inset-0 overflow-auto whitespace-pre-wrap break-words p-5 [scrollbar-width:none] [word-break:break-all] [&::-webkit-scrollbar]:hidden [&_pre]:!m-0 [&_pre]:!bg-transparent [&_pre]:!p-0 [&_pre]:!whitespace-pre-wrap [&_pre]:!break-words [&_pre]:font-mono [&_pre]:text-sm [&_pre]:!leading-[1.625] [&_code]:!font-mono [&_code]:!text-sm [&_code]:!leading-[1.625]"
+				// biome-ignore lint/security/noDangerouslySetInnerHtml: HTML from shiki highlighter is trusted
+				dangerouslySetInnerHTML={{ __html: highlightedHtml }}
+			/>
+			<textarea
+				ref={textareaRef}
+				value={value}
+				onChange={(event) => onChange(event.target.value)}
+				onKeyDown={onKeyDown}
+				onScroll={syncScroll}
+				className="relative w-full resize-y whitespace-pre-wrap break-words bg-transparent p-5 font-mono text-sm leading-[1.625] text-transparent caret-foreground outline-none [word-break:break-all] placeholder:text-muted-foreground"
+				style={{ height: 640, maxHeight: 1200 }}
+				placeholder={placeholder}
+				spellCheck={false}
+			/>
+		</div>
+	);
+}
diff --git a/packages/ui/src/lib/get-caret-coordinates.ts b/packages/ui/src/lib/get-caret-coordinates.ts
new file mode 100644
index 0000000..1d82a19
--- /dev/null
+++ b/packages/ui/src/lib/get-caret-coordinates.ts
@@ -0,0 +1,80 @@
+const MIRROR_PROPS = [
+	"direction",
+	"boxSizing",
+	"width",
+	"height",
+	"overflowX",
+	"overflowY",
+	"borderTopWidth",
+	"borderRightWidth",
+	"borderBottomWidth",
+	"borderLeftWidth",
+	"borderStyle",
+	"paddingTop",
+	"paddingRight",
+	"paddingBottom",
+	"paddingLeft",
+	"fontStyle",
+	"fontVariant",
+	"fontWeight",
+	"fontStretch",
+	"fontSize",
+	"fontSizeAdjust",
+	"lineHeight",
+	"fontFamily",
+	"textAlign",
+	"textTransform",
+	"textIndent",
+	"textDecoration",
+	"letterSpacing",
+	"wordSpacing",
+	"tabSize",
+	"MozTabSize",
+	"whiteSpace",
+	"wordWrap",
+	"wordBreak",
+] as const;
+
+/**
+ * Measures the pixel coordinates of a caret position within a textarea
+ * using a hidden mirror div that replicates the textarea's styling.
+ *
+ * Returns coordinates relative to the textarea's top-left corner,
+ * adjusted for scroll offset.
+ */
+export function getCaretCoordinates(
+	textarea: HTMLTextAreaElement,
+	position: number,
+): { top: number; left: number } {
+	const mirror = document.createElement("div");
+	mirror.id = "caret-mirror";
+
+	const style = mirror.style;
+	const computed = getComputedStyle(textarea);
+
+	style.whiteSpace = "pre-wrap";
+	style.wordWrap = "break-word";
+	style.position = "absolute";
+	style.visibility = "hidden";
+	style.overflow = "hidden";
+
+	for (const prop of MIRROR_PROPS) {
+		style.setProperty(prop, computed.getPropertyValue(prop));
+	}
+
+	mirror.textContent = textarea.value.substring(0, position);
+
+	const marker = document.createElement("span");
+	// Use a zero-width space so the span has dimensions
+	marker.textContent = "\u200b";
+	mirror.appendChild(marker);
+
+	document.body.appendChild(mirror);
+
+	const top = marker.offsetTop - textarea.scrollTop;
+	const left = marker.offsetLeft - textarea.scrollLeft;
+
+	document.body.removeChild(mirror);
+
+	return { top, left };
+}