From 8df548605e3197f1288335b103479a5962e3653e Mon Sep 17 00:00:00 2001
From: Kalven Schraut <kalvens@rtvision.com>
Date: Sat, 12 Sep 2026 11:30:37 -0500
Subject: [PATCH] feat(web): suggest usernames in PR review comments

---
 .../diffs/DiffCommentAnnotation.tsx           |   6 +-
 .../pullRequest/PullRequestDetailPanel.tsx    |  18 +-
 .../pullRequest/PullRequestMarkdownEditor.tsx |   6 +-
 .../PullRequestMentionProvider.tsx            |  58 +++++++
 .../PullRequestReviewAnnotation.tsx           |   6 +-
 .../pullRequest/PullRequestReviewBar.tsx      |   6 +-
 .../pullRequest/PullRequestSummaryTab.tsx     |   6 +-
 .../components/ui/mention-textarea.test.tsx   |  90 ++++++++++
 .../src/components/ui/mention-textarea.tsx    | 160 ++++++++++++++++++
 .../components/ui/mentionText.logic.test.ts   |  29 ++++
 .../src/components/ui/mentionText.logic.ts    |  39 +++++
 docs/user/source-control.md                   |   4 +
 12 files changed, 412 insertions(+), 16 deletions(-)
 create mode 100644 apps/web/src/components/pullRequest/PullRequestMentionProvider.tsx
 create mode 100644 apps/web/src/components/ui/mention-textarea.test.tsx
 create mode 100644 apps/web/src/components/ui/mention-textarea.tsx
 create mode 100644 apps/web/src/components/ui/mentionText.logic.test.ts
 create mode 100644 apps/web/src/components/ui/mentionText.logic.ts

diff --git a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
index bce9f7e55f58..9fa0f4377c49 100644
--- a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
+++ b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
@@ -2,7 +2,7 @@ import { MessageCircle, Trash2 } from "lucide-react";
 import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
 import { Button } from "~/components/ui/button";
-import { Textarea } from "~/components/ui/textarea";
+import { MentionTextarea } from "~/components/ui/mention-textarea";
 
 import { isCommentSubmitShortcut } from "./commentSubmitShortcut";
 
@@ -88,7 +88,7 @@ export function DiffCommentAnnotation({
       contentEditable={false}
       onPointerDown={(event) => event.stopPropagation()}
     >
-      <Textarea
+      <MentionTextarea
         ref={textareaRef}
         autoFocus={focusOnMount}
         unstyled
@@ -97,7 +97,7 @@ export function DiffCommentAnnotation({
         value={displayedText}
         placeholder={placeholder}
         aria-label={`Comment on lines ${rangeLabel}`}
-        onChange={(event) => (onTextChange ?? setLocalDraftText)(event.target.value)}
+        onValueChange={onTextChange ?? setLocalDraftText}
         onFocus={(event) => {
           const end = event.currentTarget.value.length;
           event.currentTarget.setSelectionRange(end, end);
diff --git a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
index e565492a931c..712243a09f67 100644
--- a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
@@ -1,5 +1,6 @@
 import { parseChangeRequestUrl } from "@t3tools/shared/changeRequestUrl";
 import { usePullRequestStack } from "~/state/usePullRequestStack";
+import { PullRequestMentionProvider } from "./PullRequestMentionProvider";
 import { RefreshIcon } from "~/components/ui/refresh-icon";
 import { scopedThreadKey, scopeProjectRef } from "@t3tools/client-runtime/environment";
 import { squashAtomCommandFailure } from "@t3tools/client-runtime/state/runtime";
@@ -1460,7 +1461,7 @@ export function PullRequestDetailPanel({
     return <PullRequestDetailGhost seed={matchingListEntry} />;
   }
 
-  return (
+  const content = (
     <div className="flex h-full min-h-0 w-full flex-col bg-background">
       {threadPickerOpen && detail ? (
         <PullRequestThreadLinks
@@ -2693,4 +2694,19 @@ export function PullRequestDetailPanel({
       </AlertDialog>
     </div>
   );
+  return (
+    <PullRequestMentionProvider
+      key={JSON.stringify([
+        environmentId,
+        reference.projectId,
+        reference.repository,
+        reference.number,
+      ])}
+      environmentId={environmentId}
+      reference={reference}
+      detail={detail}
+    >
+      {content}
+    </PullRequestMentionProvider>
+  );
 }
diff --git a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
index a92418bbb862..1876d2d357f8 100644
--- a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
@@ -4,7 +4,7 @@ import type { EnvironmentId, ScopedThreadRef } from "@t3tools/contracts";
 import { cn } from "~/lib/utils";
 
 import { Button } from "../ui/button";
-import { Textarea } from "../ui/textarea";
+import { MentionTextarea } from "../ui/mention-textarea";
 import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { PullRequestMarkdown } from "./PullRequestMarkdown";
 
@@ -105,14 +105,14 @@ export function PullRequestMarkdownEditor({
           )}
         </div>
       ) : (
-        <Textarea
+        <MentionTextarea
           autoFocus
           disabled={saving}
           value={draft}
           rows={6}
           placeholder={placeholder}
           aria-label={label}
-          onChange={(event) => setDraft(event.target.value)}
+          onValueChange={setDraft}
         />
       )}
       <div className="flex justify-end gap-2">
diff --git a/apps/web/src/components/pullRequest/PullRequestMentionProvider.tsx b/apps/web/src/components/pullRequest/PullRequestMentionProvider.tsx
new file mode 100644
index 000000000000..d531386af6e9
--- /dev/null
+++ b/apps/web/src/components/pullRequest/PullRequestMentionProvider.tsx
@@ -0,0 +1,58 @@
+import type { EnvironmentId, PullRequestDetailView, PullRequestRef } from "@t3tools/contracts";
+import { useMemo, useState, type ReactNode } from "react";
+import { pullRequestEnvironment } from "~/state/pullRequests";
+import { useEnvironmentQuery } from "~/state/query";
+import { MentionSuggestionsContext } from "../ui/mention-textarea";
+
+export function PullRequestMentionProvider({
+  environmentId,
+  reference,
+  detail,
+  children,
+}: {
+  environmentId: EnvironmentId;
+  reference: PullRequestRef;
+  detail: PullRequestDetailView | null;
+  children: ReactNode;
+}) {
+  const [requested, setRequested] = useState(false);
+  // These hosts accept @login. Other hosts require identities their actor records do not carry.
+  const supported = detail && ["github", "gitea", "gitlab"].includes(detail.provider);
+  const loadCandidates =
+    supported &&
+    requested &&
+    detail.capabilities.reviewers.listCandidates &&
+    detail.viewerPermissions.requestReviewers;
+  const query = useEnvironmentQuery(
+    loadCandidates
+      ? pullRequestEnvironment.reviewerCandidates({ environmentId, input: reference })
+      : null,
+  );
+  const candidates = useMemo(() => {
+    if (!detail) return [];
+    return [
+      ...(detail.author ? [detail.author] : []),
+      ...detail.reviewers,
+      ...detail.comments.flatMap((comment) => (comment.author ? [comment.author] : [])),
+      ...detail.reviewThreads.flatMap((thread) =>
+        thread.comments.flatMap((comment) => (comment.author ? [comment.author] : [])),
+      ),
+      ...(query.data?.candidates.filter((candidate) => candidate.kind === "user") ?? []),
+    ];
+  }, [detail, query.data]);
+  return (
+    <MentionSuggestionsContext
+      value={
+        supported
+          ? {
+              candidates,
+              onRequest: () => setRequested(true),
+              pending: !!loadCandidates && query.isPending,
+            }
+          : null
+      }
+    >
+      {children}
+    </MentionSuggestionsContext>
+  );
+}
diff --git a/apps/web/src/components/pullRequest/PullRequestReviewAnnotation.tsx b/apps/web/src/components/pullRequest/PullRequestReviewAnnotation.tsx
index 90a1926d1fad..8df6ab9308f2 100644
--- a/apps/web/src/components/pullRequest/PullRequestReviewAnnotation.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestReviewAnnotation.tsx
@@ -23,7 +23,7 @@ import { formatRelativeTimeLabel } from "~/timestampFormat";
 import { cn } from "~/lib/utils";
 
 import { Button } from "../ui/button";
-import { Textarea } from "../ui/textarea";
+import { MentionTextarea } from "../ui/mention-textarea";
 import { isCommentSubmitShortcut } from "../diffs/commentSubmitShortcut";
 import {
   editPullRequestThreadComment,
@@ -329,13 +329,13 @@ export function ReviewThreadCard({
           {canReply ? (
             replying ? (
               <div className="mt-2">
-                <Textarea
+                <MentionTextarea
                   autoFocus
                   size="sm"
                   value={reply}
                   placeholder="Reply"
                   aria-label="Reply to this conversation"
-                  onChange={(event) => setReply(event.target.value)}
+                  onValueChange={setReply}
                   onKeyDown={submitKeys({
                     value: reply,
                     pending,
diff --git a/apps/web/src/components/pullRequest/PullRequestReviewBar.tsx b/apps/web/src/components/pullRequest/PullRequestReviewBar.tsx
index f32352734685..c5056fbe11a2 100644
--- a/apps/web/src/components/pullRequest/PullRequestReviewBar.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestReviewBar.tsx
@@ -12,7 +12,7 @@ import { pullRequestEnvironment } from "~/state/pullRequests";
 import { useAtomCommand } from "~/state/use-atom-command";
 
 import { Button } from "../ui/button";
-import { Textarea } from "../ui/textarea";
+import { MentionTextarea } from "../ui/mention-textarea";
 import { toastManager } from "../ui/toast";
 import {
   pullRequestReviewKey,
@@ -124,13 +124,13 @@ export function PullRequestReviewBar({
           </Button>
         ) : null}
       </div>
-      <Textarea
+      <MentionTextarea
         size="sm"
         className="mt-2"
         value={body}
         placeholder="Summarize your review (optional)"
         aria-label="Review summary"
-        onChange={(event) => setSummary(reviewKey, event.target.value)}
+        onValueChange={(value) => setSummary(reviewKey, value)}
       />
       <div className="mt-2 flex flex-wrap justify-end gap-2">
         {offered.map((verdict) => (
diff --git a/apps/web/src/components/pullRequest/PullRequestSummaryTab.tsx b/apps/web/src/components/pullRequest/PullRequestSummaryTab.tsx
index 30151975a1b9..86aedc3a35fa 100644
--- a/apps/web/src/components/pullRequest/PullRequestSummaryTab.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestSummaryTab.tsx
@@ -30,7 +30,7 @@ import { formatRelativeTimeLabel } from "~/timestampFormat";
 
 import { Button } from "../ui/button";
 import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../ui/collapsible";
-import { Textarea } from "../ui/textarea";
+import { MentionTextarea } from "../ui/mention-textarea";
 import { toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import {
@@ -375,7 +375,7 @@ function CommentComposer({
 
   return (
     <div className="mt-3 space-y-2">
-      <Textarea
+      <MentionTextarea
         // Locked while posting: the body is cleared on success, which would otherwise throw
         // away a new draft typed while the request was still in flight.
         disabled={submitting !== null || actionPending}
@@ -383,7 +383,7 @@ function CommentComposer({
         rows={3}
         placeholder="Leave a comment"
         aria-label="Comment on this pull request"
-        onChange={(event) => setBody(event.target.value)}
+        onValueChange={setBody}
       />
       <div className="flex justify-end gap-2">
         {followUpAction === null ? null : (
diff --git a/apps/web/src/components/ui/mention-textarea.test.tsx b/apps/web/src/components/ui/mention-textarea.test.tsx
new file mode 100644
index 000000000000..9ca36a823d6c
--- /dev/null
+++ b/apps/web/src/components/ui/mention-textarea.test.tsx
@@ -0,0 +1,90 @@
+import { act, useState } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, expect, it, vi } from "vite-plus/test";
+import { MentionSuggestionsContext, MentionTextarea } from "./mention-textarea";
+
+vi.mock("./textarea", () => ({
+  Textarea: (props: React.ComponentProps<"textarea">) => <textarea {...props} />,
+}));
+
+let renderer: ReactTestRenderer;
+const onKeyDown = vi.fn();
+const onRequest = vi.fn();
+function Editor() {
+  const [value, setValue] = useState("Please @a review this");
+  return (
+    <MentionSuggestionsContext
+      value={{ candidates: [{ login: "alice" }, { login: "adam" }], pending: false, onRequest }}
+    >
+      <MentionTextarea value={value} onValueChange={setValue} onKeyDown={onKeyDown} />
+      <button type="button" onClick={() => setValue("")}>
+        Clear
+      </button>
+    </MentionSuggestionsContext>
+  );
+}
+const input = () => renderer.root.findByType("textarea");
+const keyboard = (key: string, ctrlKey = false) => ({
+  key,
+  ctrlKey,
+  nativeEvent: { isComposing: false },
+  preventDefault: vi.fn(),
+  stopPropagation: vi.fn(),
+});
+
+beforeEach(async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("requestAnimationFrame", (callback: () => void) => {
+    callback();
+    return 1;
+  });
+  onKeyDown.mockClear();
+  onRequest.mockClear();
+  await act(async () => {
+    renderer = create(<Editor />);
+  });
+  await act(async () =>
+    input().props.onSelect({
+      currentTarget: { value: "Please @a review this", selectionStart: 9, selectionEnd: 9 },
+    }),
+  );
+});
+afterEach(async () => {
+  await act(async () => renderer.unmount());
+  vi.unstubAllGlobals();
+});
+
+it("completes the selected person without submitting or losing the rest of the review", async () => {
+  expect(onRequest).toHaveBeenCalledOnce();
+  await act(async () => input().props.onKeyDown(keyboard("ArrowDown")));
+  const enter = keyboard("Enter");
+  await act(async () => input().props.onKeyDown(enter));
+  expect(input().props.value).toBe("Please @adam review this");
+  expect(enter.preventDefault).toHaveBeenCalledOnce();
+  expect(onKeyDown).not.toHaveBeenCalled();
+  expect(renderer.root.findAllByProps({ role: "listbox" })).toHaveLength(0);
+});
+
+it("dismisses suggestions before Escape reaches the review editor", async () => {
+  await act(async () => input().props.onKeyDown(keyboard("Escape")));
+  expect(onKeyDown).not.toHaveBeenCalled();
+  expect(input().props.value).toBe("Please @a review this");
+  await act(async () => input().props.onKeyDown(keyboard("Escape")));
+  expect(onKeyDown).toHaveBeenCalledOnce();
+});
+
+it("keeps Ctrl+Enter available for submitting the review", async () => {
+  const shortcut = keyboard("Enter", true);
+  await act(async () => input().props.onKeyDown(shortcut));
+  expect(onKeyDown).toHaveBeenCalledWith(shortcut);
+  expect(input().props.value).toBe("Please @a review this");
+});
+
+it("dismisses a stale mention when the parent clears the comment without blurring", async () => {
+  expect(renderer.root.findAllByProps({ role: "listbox" })).toHaveLength(1);
+  await act(async () => renderer.root.findByType("button").props.onClick());
+  expect(renderer.root.findAllByProps({ role: "listbox" })).toHaveLength(0);
+  await act(async () => input().props.onKeyDown(keyboard("Enter")));
+  expect(input().props.value).toBe("");
+  expect(onKeyDown).toHaveBeenCalledOnce();
+});
diff --git a/apps/web/src/components/ui/mention-textarea.tsx b/apps/web/src/components/ui/mention-textarea.tsx
new file mode 100644
index 000000000000..141765cf8f12
--- /dev/null
+++ b/apps/web/src/components/ui/mention-textarea.tsx
@@ -0,0 +1,160 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from "react";
+import { Textarea, type TextareaProps } from "./textarea";
+import {
+  insertMention,
+  mentionAtCursor,
+  mentionCandidates,
+  type MentionCandidate,
+} from "./mentionText.logic";
+
+export const MentionSuggestionsContext = createContext<{
+  candidates: ReadonlyArray<MentionCandidate>;
+  onRequest: () => void;
+  pending: boolean;
+} | null>(null);
+
+/** A plain text field. Selecting a suggestion inserts the host's @login syntax. */
+export function MentionTextarea({
+  value,
+  onValueChange,
+  ref,
+  onKeyDown,
+  onSelect,
+  onBlur,
+  ...props
+}: Omit<TextareaProps, "value" | "onChange"> & {
+  value: string;
+  onValueChange: (value: string) => void;
+}) {
+  const source = useContext(MentionSuggestionsContext);
+  const input = useRef<HTMLTextAreaElement>(null);
+  useImperativeHandle(ref, () => input.current!);
+  const listId = useId();
+  const [range, setRange] = useState<ReturnType<typeof mentionAtCursor>>(null);
+  const [active, setActive] = useState(0);
+  if (range && value.slice(range.start, range.end) !== `@${range.query}`) {
+    setRange(null);
+  }
+  const matches = source && range ? mentionCandidates(source.candidates, range.query) : [];
+  const open = source !== null && range !== null && !props.disabled;
+  const selected = Math.min(active, Math.max(0, matches.length - 1));
+  const activeLogin = open ? matches[selected]?.login : undefined;
+  const activeOption = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (activeLogin) activeOption.current?.scrollIntoView({ block: "nearest" });
+  }, [activeLogin]);
+
+  const updateRange = (element: HTMLTextAreaElement) => {
+    const next = mentionAtCursor(element.value, element.selectionStart, element.selectionEnd);
+    setRange(next);
+    setActive(0);
+    if (next) source?.onRequest();
+  };
+  const choose = (login: string) => {
+    if (!range) return;
+    const next = insertMention(value, range, login);
+    onValueChange(next.value);
+    setRange(null);
+    requestAnimationFrame(() => {
+      input.current?.focus();
+      input.current?.setSelectionRange(next.cursor, next.cursor);
+    });
+  };
+
+  return (
+    <div className="min-w-0">
+      <Textarea
+        {...props}
+        ref={input}
+        value={value}
+        aria-autocomplete={source ? "list" : undefined}
+        aria-controls={open ? listId : undefined}
+        aria-activedescendant={open && matches.length ? `${listId}-${selected}` : undefined}
+        onChange={(event) => {
+          onValueChange(event.target.value);
+          updateRange(event.currentTarget);
+        }}
+        onSelect={(event) => {
+          updateRange(event.currentTarget);
+          onSelect?.(event);
+        }}
+        onBlur={(event) => {
+          setRange(null);
+          onBlur?.(event);
+        }}
+        onKeyDown={(event) => {
+          if (open && !event.nativeEvent.isComposing) {
+            if (event.key === "Escape") {
+              event.preventDefault();
+              event.stopPropagation();
+              setRange(null);
+              return;
+            }
+            if (matches.length && (event.key === "ArrowDown" || event.key === "ArrowUp")) {
+              event.preventDefault();
+              setActive(
+                (selected + (event.key === "ArrowDown" ? 1 : -1) + matches.length) % matches.length,
+              );
+              return;
+            }
+            if (
+              matches.length &&
+              (event.key === "Enter" || event.key === "Tab") &&
+              !event.ctrlKey &&
+              !event.metaKey &&
+              !event.shiftKey
+            ) {
+              event.preventDefault();
+              choose(matches[selected]!.login);
+              return;
+            }
+          }
+          onKeyDown?.(event);
+        }}
+      />
+      {open ? (
+        <div className="mt-1 rounded-md border border-border bg-popover p-1 text-xs shadow-sm">
+          <div
+            id={listId}
+            role="listbox"
+            aria-label="Mention a person"
+            className="max-h-40 overflow-y-auto"
+          >
+            {matches.map((candidate, index) => (
+              <div
+                id={`${listId}-${index}`}
+                key={candidate.login}
+                ref={index === selected ? activeOption : undefined}
+                role="option"
+                aria-selected={index === selected}
+                className={`cursor-pointer rounded px-2 py-1.5 ${index === selected ? "bg-accent text-accent-foreground" : ""}`}
+                onPointerDown={(event) => event.preventDefault()}
+                onClick={() => choose(candidate.login)}
+              >
+                @{candidate.login}
+                {candidate.name ? (
+                  <span className="ml-2 text-muted-foreground">{candidate.name}</span>
+                ) : null}
+              </div>
+            ))}
+          </div>
+          {matches.length === 0 ? (
+            <p role="status" className="px-2 py-1 text-muted-foreground">
+              {source.pending
+                ? "Loading people..."
+                : "No suggestions. You can still type a username."}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/ui/mentionText.logic.test.ts b/apps/web/src/components/ui/mentionText.logic.test.ts
new file mode 100644
index 000000000000..777c5f1478ce
--- /dev/null
+++ b/apps/web/src/components/ui/mentionText.logic.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vite-plus/test";
+import { insertMention, mentionAtCursor, mentionCandidates } from "./mentionText.logic";
+
+describe("review mentions", () => {
+  it("recognizes a mention at the caret without treating email addresses as mentions", () => {
+    expect(mentionAtCursor("Please @al", 10)).toEqual({ start: 7, end: 10, query: "al" });
+    expect(mentionAtCursor("@", 1)).toEqual({ start: 0, end: 1, query: "" });
+    expect(mentionAtCursor("a@example.com", 13)).toBeNull();
+    expect(mentionAtCursor("@alice", 1, 6)).toBeNull();
+  });
+  it("matches names, removes duplicate logins, and prefers matching usernames", () => {
+    expect(
+      mentionCandidates(
+        [{ login: "bob", name: "Alice Brown" }, { login: "alice" }, { login: "Alice" }],
+        "ali",
+      ).map((person) => person.login),
+    ).toEqual(["alice", "bob"]);
+  });
+  it("replaces only the typed mention and keeps the surrounding review intact", () => {
+    expect(insertMention("Please @al review this", { start: 7, end: 10 }, "alice")).toEqual({
+      value: "Please @alice review this",
+      cursor: 14,
+    });
+    expect(insertMention("@al", { start: 0, end: 3 }, "alice")).toEqual({
+      value: "@alice ",
+      cursor: 7,
+    });
+  });
+});
diff --git a/apps/web/src/components/ui/mentionText.logic.ts b/apps/web/src/components/ui/mentionText.logic.ts
new file mode 100644
index 000000000000..4fa309501a7a
--- /dev/null
+++ b/apps/web/src/components/ui/mentionText.logic.ts
@@ -0,0 +1,39 @@
+export interface MentionCandidate {
+  readonly login: string;
+  readonly name?: string | null;
+}
+
+export function mentionAtCursor(value: string, start: number, end = start) {
+  if (start !== end) return null;
+  const match = /(?:^|[\s([{])@([\w.-]*)$/.exec(value.slice(0, start));
+  if (!match) return null;
+  return { start: start - match[1]!.length - 1, end: start, query: match[1]! };
+}
+
+export function mentionCandidates(candidates: ReadonlyArray<MentionCandidate>, query: string) {
+  const needle = query.toLowerCase();
+  const unique = new Map<string, MentionCandidate>();
+  for (const candidate of candidates) {
+    const key = candidate.login.toLowerCase();
+    if (!/^[\w.-]+$/.test(candidate.login) || unique.has(key)) continue;
+    if (key.includes(needle) || candidate.name?.toLowerCase().includes(needle)) {
+      unique.set(key, candidate);
+    }
+  }
+  return [...unique.values()]
+    .sort(
+      (a, b) =>
+        Number(b.login.toLowerCase().startsWith(needle)) -
+        Number(a.login.toLowerCase().startsWith(needle)),
+    )
+    .slice(0, 8);
+}
+
+export function insertMention(value: string, range: { start: number; end: number }, login: string) {
+  const suffix = value.slice(range.end);
+  const inserted = `@${login}${/^\s/.test(suffix) ? "" : " "}`;
+  return {
+    value: value.slice(0, range.start) + inserted + suffix,
+    cursor: range.start + inserted.length + (/^\s/.test(suffix) ? 1 : 0),
+  };
+}
diff --git a/docs/user/source-control.md b/docs/user/source-control.md
index c20c29afc299..0c18453efc64 100644
--- a/docs/user/source-control.md
+++ b/docs/user/source-control.md
@@ -107,6 +107,10 @@ Open **Pull requests** to review changes and comments, request reviewers, check
 or merge. You can edit review titles and descriptions and your own comments where the host allows it.
 GitLab calls these merge requests.
 
+Type `@` in a review comment or reply to suggest people from the pull request and repository
+on GitHub, Gitea, and GitLab. Select a name with the arrow keys and Enter or Tab. The mention
+is sent when you submit the comment or review.
+
 In the Code tab, mark files as **Viewed** to save your progress to the connected host account.
 Uncheck a file to review it again. Progress follows that account across devices, and the host
 marks changed files as needing another look. This is available on GitHub and Gitea servers