@plannotator/ui 0.43.0 → 0.43.2

package/HANDOFF.md

@@ -214,7 +214,7 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `hooks/useHtmlRefresh` | Re-fetch a rendered HTML document through a host-supplied `fetchSnapshot`, remount the viewer on a reload generation, acknowledge the restore report once. See "HTML annotation parity seams". |
 | `shortcuts` (`useHtmlAnnotateShortcuts`, `defineShortcutScope`, the scope registry) | The declarative keyboard-shortcut engine and the per-surface scopes, including the HTML annotate scope (Mod+Shift+A toggles annotate mode, Mod+Shift+X shows/hides the tools). Pure: React plus `utils/platform`; no backend. |
 | `utils/selectionActions` + `components/SelectionActionsDropdown` | The host selection-actions seam: `SelectionAction`, `SelectionActionContext`, the pure `buildSelectionActionContext`, and the dropdown `AnnotationToolbar` opens. Pure React; no backend. *(Blessed in 0.43.0.)* |
-| `utils/mentions` + `components/MentionPicker` + `hooks/useMentionAutocomplete` | The `@` mention seam behind `CommentPopover`'s `mentionSource`: the pure grammar (`mentionTrigger`, `mentionMatches`, `applyMentionPick`, `survivingMentions`), the portaled picker, and the keyboard state machine. Pure React; no backend. *(Blessed in 0.43.0.)* |
+| `utils/mentions` + `components/MentionPicker` + `hooks/useMentionAutocomplete` | The `@` mention seam behind `CommentPopover`'s `mentionSource` (and, since 0.43.1, `Viewer`'s and `HtmlViewer`'s): the pure grammar (`mentionTrigger`, `mentionMatches`, `applyMentionPick`, `survivingMentions`), the portaled picker, and the keyboard state machine. Pure React; no backend. *(Blessed in 0.43.0.)* |
 | `utils/inputMethod` (`getInputMethod`, `saveInputMethod`, `refreshInputMethodStamp`) | The per-surface pinpoint/drag input-method preference with its TTL. Persists through the `storageBackend` seam; no backend of its own. |
 | `utils/codeHighlight` / `utils/codeBlockMark` / `utils/syntaxTheme` | The Shiki-based fence highlighter, swap-surviving annotation marks, and palette→Shiki theme mapping. Replaces all `.hljs` styling. *(Blessed in 0.29.0.)* |
 | `utils/math` (`loadMathRenderer`, `getMathRenderer`, `getMathRendererSource`, `setMathRenderer`, `setMathRendererLoader`, `getMathRendererLoader`, `resetMathRenderer`) and `utils/math-eager` | The math renderer slot and its eager KaTeX registration. Import `utils/math-eager` for synchronous typesetting on the first commit; call `loadMathRenderer()` to pre-warm the lazy path. `resetMathRenderer()` empties the slot and keeps the registered loader; `setMathRendererLoader(null)` drops it. See "Lazy renderers and eager entries". |
@@ -956,6 +956,8 @@ that state out of `Viewer`, exactly as with `AnnotationToolstrip`'s
 
 ### 3. `CommentPopover` `mentionSource` — an `@` mention source for the composer
 
+> **0.43.2 additions (opt-in, byte-identical when absent):** `MentionSource.heading?: string | null` draws one non-selectable heading row (`data-mention-heading`, e.g. "People in this workspace") above the list; `MentionPerson.avatar?: { url?, initials?, tint? }` draws an avatar (`data-mention-avatar="image" | "initials"`) before the label — an `<img>` when `url` is set, else `initials` (defaulting to the label's first letter) on a disc tinted with `tint` (any CSS color; absent means the muted surface). Neither the grammar, the keyboard state machine, `onMentionsChange`, `onPickBlocked` nor `Annotation.mentions` changes.
+
 ```ts
 import type { MentionPerson, MentionSource } from "@plannotator/ui/types";
 // (also @plannotator/ui/utils/mentions)
@@ -971,6 +973,7 @@ interface MentionPerson {
 interface MentionSource {
   readonly people: readonly MentionPerson[];
   readonly emptyNotice?: string | null;                     // honest-empty row
+  readonly heading?: string | null;                         // 0.43.2: heading row above the list, absent → none
   readonly onMentionsChange?: (ids: readonly string[]) => void;
   readonly onPickBlocked?: (person: MentionPerson) => void;
 }
@@ -1026,7 +1029,7 @@ the people and what a mention means.
 
 ### Threading points
 
-- `AnnotationToolbar` (`selectionActions`, `quickLabels`) — the props live here.
+- `AnnotationToolbar` (`selectionActions`, `selectionActionsIcon`, `quickLabels`) — the props live here. `selectionActionsIcon?: React.ReactNode` (0.43.1) is the glyph on the wand button, forwarded by `Viewer` (both toolbars) and `HtmlViewer`; absent → the package's own wand, which 0.43.1 also simplified to one thick diagonal with a single star (the six-spark glyph read as noise at 16px). Name, `data-selection-actions`, size and behavior of the button are untouched either way.
 - `Viewer` forwards both to BOTH of its toolbars (the text-selection toolbar
   and the code-block hover toolbar).
 - `HtmlViewer` forwards `selectionActions` to its selection toolbar. It does
@@ -1038,6 +1041,7 @@ the people and what a mention means.
 - `CommentPopover` (`mentionSource`). `Viewer` does NOT forward it: the viewer
   owns several composers and a per-composer decision belongs to the host that
   renders them. Ask if you would rather pass it once on `Viewer`.
+  **Answered in 0.43.1 — both viewers now forward it; see the next section.**
 
 ### The no-op guarantee, and how it is pinned
 
@@ -1058,8 +1062,118 @@ Tests: `utils/mentions.test.ts` (11, DOM-free),
 `components/AnnotationToolbar.selectionActions.test.tsx` (8, DOM-gated),
 `components/CommentPopover.mentionSource.test.tsx` (11, DOM-gated).
 
+## `mentionSource` on the viewers (0.43.1)
+
+0.43.0 left `mentionSource` on `CommentPopover` alone, with an open question
+("ask if you would rather pass it once on `Viewer`"). The answer is yes, so
+0.43.1 threads it one level up and gives the picked ids somewhere to land.
+Same ruling as 0.43.0: an opt-in host capability that changes nothing for
+Plannotator's own users when it is not supplied. `packages/editor` and
+`packages/review-editor` are untouched by this release; core is UNCHANGED at
+`0.25.5`, so **ui 0.43.1 publishes alone**.
+
+### 1. The prop
+
+`Viewer` and `HtmlViewer` each gain `mentionSource?: MentionSource` — the same
+type, unchanged, from `@plannotator/ui/types` (also `utils/mentions`) — and
+each forwards it to EVERY comment composer it mounts:
+
+- `Viewer` → the text-selection composer (`useAnnotationHighlighter`'s) and the
+  global / code-block one.
+- `HtmlViewer` → the pinpoint (selection) composer and the global one.
+
+A host that wants mentions on a surface passes one prop instead of reaching
+into the viewer's composers. Passing it directly to a `CommentPopover` you
+mount yourself still works and is unchanged.
+
+Deliberately NOT threaded: `plan-diff/PlanCleanDiffView`, `CodeFilePopout` and
+`goal-setup/GoalSetupSurface` mount composers too, but they are Plannotator-only
+surfaces off the supported-import list — the same line 0.43.0 drew for
+`selectionActions`. Ask if a host needs one.
+
+### 2. `Annotation.mentions` — where the ids go
+
+```ts
+interface Annotation {
+  // …
+  mentions?: readonly string[];   // opaque host ids, additive
+}
+```
+
+`onSubmit(text, images?, mentions?)` used to stop at the viewer: the third
+argument was received and dropped. It now rides onto the annotation the viewer
+hands `onAddAnnotation`, on every creation path behind those composers
+(`createAnnotationFromSource`, `createAnnotationFromMathSource`, the code-block
+path, both global comments, and the HTML pinpoint comment).
+
+**The presence rule** is the whole no-op guarantee, so it is worth stating
+exactly: the key exists only when a `mentionSource` was supplied AND at least
+one id survived to submit. No source → no third argument → no key. A source
+whose tokens the author deleted before submitting → `[]` from the composer →
+still no key, never an empty array. Every write is a conditional spread
+(`...(mentions && mentions.length > 0 ? { mentions } : {})`), not `mentions,`,
+because the bare shorthand would put the key on the object with an `undefined`
+value and `'mentions' in ann` would start answering true for Plannotator.
+
+The ids are opaque to the package. Mapping one to a person, notifying them, or
+rendering an avatar is entirely the host's business — `MentionPerson.id` is
+reported back verbatim, exactly as it was handed in.
+
+### 3. What the field does NOT touch
+
+An id from a host's directory means nothing outside that host, so the field
+stays out of everything Plannotator produces:
+
+- **Export.** `exportAnnotations`, `exportAnnotationEntry` and
+  `exportLinkedDocAnnotations` never print it: an annotation carrying
+  `mentions` exports byte-identically to the same annotation without it
+  (`utils/parser.mentions.test.ts`). The readable `@Label` token is in the
+  comment body, which is what the coding agent reads.
+- **Share links.** Dropped exactly like `htmlAnchor`, `elementContext` and
+  `diagramAnchor` — the compact tuple format never carried extra fields, and a
+  round trip restores `mentions: undefined` (pinned in
+  `utils/sharing.multiTarget.test.ts`).
+- **External annotations.** `POST /api/external-annotations` builds its rows
+  from an explicit field list and `PATCH` from an allowlist, so a `mentions`
+  key on the wire is dropped as any unknown key is. No change was needed in
+  `@plannotator/core/external-annotation`, in either runtime.
+- **The feedback archive.** `packages/shared/feedback-archive.ts` copies named
+  fields into its record; `mentions` is not one of them and never reaches
+  `index.jsonl` or a sidecar. No change needed.
+- **Drafts** carry it for free (annotations are opaque JSON to the draft
+  transport), which is the behavior a host wants: a restored draft still knows
+  who was named.
+
+### 4. Edit and reply paths
+
+There is none to thread in these two viewers: both `Viewer` composers and both
+`HtmlViewer` composers are CREATION composers. Editing an existing comment
+happens in `AnnotationPanel`'s card, a plain textarea that has never had an
+`@` picker and takes no `mentionSource`; replies (`inReplyTo`) are created by
+the WebMCP catalog, not by a composer. So no annotation's `mentions` is
+rewritten after creation by this package — a host that edits a comment owns
+the field from then on. If you want the panel editor to pick people too, that
+is a separate prop on `AnnotationPanel` and worth asking for.
+
+### No-op guarantee, and how it is pinned
+
+With no `mentionSource`, both viewers mount the composers they always did, no
+`@` listener is registered, no picker DOM exists, and the annotation object
+handed to `onAddAnnotation` has no `mentions` key at all (`'mentions' in ann`
+is false, asserted rather than `toBeUndefined()` — the difference between the
+conditional spread and the bare shorthand is invisible to the latter).
+
+Tests (both DOM-gated, both in the workflow's DOM_TESTS step):
+`components/Viewer.mentionSource.test.tsx` (5) drives the real Viewer — the
+selection composer through the Vim toolbar's type-to-comment gesture and the
+global composer through its button — and
+`components/html-viewer/HtmlViewer.mentionSource.test.tsx` (3) drives the real
+HtmlViewer through a bridge pinpoint message and its global button. Plus the two DOM-free pins in
+§3 above.
+
 ## Publishing & versioning
 
+- **ui 0.43.1 (`mentionSource` on the viewers): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive over 0.43.0: `mentionSource` on `Viewer` and `HtmlViewer` (forwarded to every comment composer each mounts) and the optional `Annotation.mentions` field the picked ids land on, set only when a source was supplied and a token survived. Nothing is removed, no new modules, no export-, share- or archive-visible change, and Plannotator passes none of it. See "`mentionSource` on the viewers (0.43.1)".
 - **ui 0.43.0 (host toolbar seams): `@plannotator/ui` only — `@plannotator/core` is UNCHANGED at `0.25.5`, so this publishes alone** (core 0.25.5 must already be published). Purely additive: `selectionActions` + `quickLabels` on `AnnotationToolbar` (forwarded by `Viewer`; `selectionActions` also by `HtmlViewer`), `mentionSource` on `CommentPopover`, an optional third `mentions` argument on that component's `onSubmit`, and the new supported modules `utils/selectionActions`, `utils/mentions`, `components/SelectionActionsDropdown`, `components/MentionPicker`, `hooks/useMentionAutocomplete`. Nothing is removed and Plannotator passes none of it. See "Host toolbar seams (0.43.0)".
 - **core 0.25.5 / ui 0.42.0 (diagram FILES, `.mmd`/`.mermaid`/`.dot`/`.gv`): additive on both packages, so the next publish is core-first.** `@plannotator/core/annotatable` gains `DiagramRenderKind`, `diagramRenderKindForPath`, `isDiagramRenderKind` and `annotateDiagramRenderKind`, and its built-in annotatable sets now include the four diagram extensions (`shouldStripFrontmatter` returns false for them — Mermaid's `--- … ---` config block is content — and they can no longer be registered through `markdownExtensions`). `@plannotator/ui` gains `diagramDocumentBlocks(text, kind)` on `utils/parser` (the ONE `code` block a whole-file diagram source renders as), `shareableDocumentMarkdown(markdown, renderAs)` on `utils/sharing`, the `DocumentRenderAs` type on `types` (`'markdown' | 'html' | DiagramRenderKind`, re-exporting core's kind), and an optional `Block.diagramSourceLineOffset` that `DiagramBlock` prefers over `Block.startLine` when resolving a diagram comment's `sourceLine` (unset on every parser-produced fence, so fences are byte-identical). `useLinkedDoc`'s `renderAs`/`setRenderAs`/`LinkedDocLoadData.renderAs` widen from `'markdown' | 'html'` to `DocumentRenderAs` — source-compatible for a host that only ever passes the old two, but a host whose own state is typed `'markdown' | 'html'` must widen its setter. Since core changes, **publish `core` first** and update UI's exact core dependency before packing ui.
 - **The current pair is `@plannotator/ui` `0.41.2` on `@plannotator/core` `0.25.4`.** Core is UNCHANGED from 0.41.1, so 0.41.2 publishes alone (`ui` only; core 0.25.4 must already be published). 0.41.2 ships the palette-derived Mermaid node shadow at a default of 70% (`DEFAULT_MERMAID_SHADOW_AMOUNT`) and the Settings → Display "Diagram Shadow" control (0 / 40 / 70 / 100); see "Node shadow (the one thing that is not a colour)" under "Theme-aware Mermaid diagrams (0.40.0)" for the mapping — no API removal, only additive exports (`buildMermaidShadow`, `DEFAULT_MERMAID_SHADOW_AMOUNT`, `utils/diagramShadow`).

package/README.md

@@ -238,10 +238,16 @@ in 0.42.0 (proven by diffing the mounted `outerHTML` against the base commit).
   `startOffset: 0` on a surface with no blocks, such as raw HTML) — and the
   toolbar closes. **The package creates no annotation:** what an action does is yours.
   An empty array renders no button.
+- **`AnnotationToolbar` `selectionActionsIcon`** (forwarded by `Viewer` and
+  `HtmlViewer`): the glyph on the `selectionActions` button, so a host can match
+  the wand it draws elsewhere. Absent means the package's own wand; nothing else
+  about the button changes.
 - **`AnnotationToolbar` `quickLabels`** (default `true`): `false` hides the Zap
   picker and makes the Alt+digit label shortcuts inert on that toolbar. The
   one-click 👍 is unaffected, and mode state is still yours to clamp.
-- **`CommentPopover` `mentionSource`**: `{ people, emptyNotice?,
+- **`CommentPopover` `mentionSource`** (0.43.2 adds `heading?` above the list
+  and an optional `avatar?: { url?, initials?, tint? }` per person, drawn before
+  the label; both absent → the 0.43.1 rows): `{ people, emptyNotice?,
   onMentionsChange?, onPickBlocked? }` over `MentionPerson`
   (`{ id, kind, label, detail, canOpen }`). Typing `@` at a word boundary opens
   a portaled picker measured from the textarea; picking inserts the readable
@@ -252,9 +258,17 @@ in 0.42.0 (proven by diffing the mounted `outerHTML` against the base commit).
   no-access dialog) and inserts normally when you do not. Not wired to any
   Plannotator data and not a `configurePlannotatorUI` seam — pass it where you
   render the composer.
+- **`Viewer` / `HtmlViewer` `mentionSource`** (0.43.1): the same prop on the two
+  viewers, forwarded to every comment composer each of them mounts, so a host
+  wires mentions once per surface instead of per composer. The ids the author
+  kept ride onto the created annotation as `Annotation.mentions`
+  (`readonly string[]`, present only when a source was supplied and at least
+  one token survived). It is host data: the package never renders, exports,
+  shares or archives it.
 
 See HANDOFF.md § "Host toolbar seams (0.43.0)" for the grammar, the keyboard
-rules and the threading points.
+rules and the threading points, and § "mentionSource on the viewers (0.43.1)"
+for the two viewer props and the annotation field.
 
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 

package/components/AnnotationToolbar.tsx

@@ -44,6 +44,12 @@ interface AnnotationToolbarProps {
    * Absent or empty → no button, no dropdown: today's toolbar.
    */
   selectionActions?: SelectionAction[];
+  /**
+   * Opt-in host capability: the glyph on the `selectionActions` button, so a
+   * host can match the wand it draws elsewhere. Absent → the package's own
+   * wand. Nothing else about the button changes (name, data attribute, size).
+   */
+  selectionActionsIcon?: React.ReactNode;
   /**
    * Whether the package's own quick labels are offered (default true).
    * `false` hides the Zap picker button and the Alt+digit label shortcuts on
@@ -69,6 +75,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   onRequestComment,
   onQuickLabel,
   selectionActions,
+  selectionActionsIcon,
   quickLabels: quickLabelsEnabled = true,
   copyText,
   commentOnly = false,
@@ -273,7 +280,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
           <ToolbarButton
             ref={actionsButtonRef}
             onClick={() => setShowSelectionActions(prev => !prev)}
-            icon={<WandIcon />}
+            icon={selectionActionsIcon ?? <WandIcon />}
             label="Actions"
             className={selectionActionsOpen ? "text-primary bg-primary/10" : "text-primary hover:bg-primary/10"}
             dataAttributes={{ 'data-selection-actions': 'true' }}
@@ -370,9 +377,11 @@ const ZapIcon = () => (
   </svg>
 );
 
+// One thick diagonal wand with a single four-point star at its tip: the
+// earlier glyph carried six sparks and read as noise at 16px.
 const WandIcon = () => (
-  <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-    <path strokeLinecap="round" strokeLinejoin="round" d="M15 4V2m0 16v-2M8 9h2m10 0h2M17.8 11.8L19 13M15 9h0M17.8 6.2L19 5M3 21l9-9M12.2 6.2L11 5" />
+  <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+    <path strokeLinecap="round" strokeLinejoin="round" d="M3 21L13.5 10.5M17 3v7M13.5 6.5h7" />
   </svg>
 );
 

package/components/CommentPopover.tsx

@@ -694,6 +694,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
                 id={mentionListboxId}
                 people={mentionAc.menu.items}
                 emptyNotice={mentionAc.menu.emptyNotice}
+                heading={mentionAc.menu.heading}
                 active={mentionAc.menu.activeIndex}
                 anchor={mentionAc.menu.anchor}
                 onPick={(person) => {
@@ -858,6 +859,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             id={mentionListboxId}
             people={mentionAc.menu.items}
             emptyNotice={mentionAc.menu.emptyNotice}
+            heading={mentionAc.menu.heading}
             active={mentionAc.menu.activeIndex}
             anchor={mentionAc.menu.anchor}
             onPick={(person) => {

package/components/MentionPicker.tsx

@@ -34,10 +34,45 @@ export function mentionAnchorOf(element: HTMLElement | null): MentionAnchor | nu
   return { top: rect.top, bottom: rect.bottom, left: rect.left, width: rect.width };
 }
 
+/** The optional avatar column: an image, else initials on a tinted disc. */
+function MentionAvatar({
+  avatar,
+  label,
+}: {
+  readonly avatar: NonNullable<MentionPerson['avatar']>;
+  readonly label: string;
+}) {
+  if (avatar.url) {
+    return (
+      <img
+        data-mention-avatar="image"
+        src={avatar.url}
+        alt=""
+        aria-hidden="true"
+        className="h-4 w-4 shrink-0 rounded-full object-cover"
+      />
+    );
+  }
+  const initials = (avatar.initials ?? label.trim().charAt(0)).slice(0, 2).toUpperCase();
+  return (
+    <span
+      data-mention-avatar="initials"
+      aria-hidden="true"
+      style={avatar.tint ? { backgroundColor: avatar.tint } : undefined}
+      className={`flex h-4 w-4 shrink-0 items-center justify-center rounded-full text-[8px] font-semibold leading-none ${
+        avatar.tint ? 'text-white' : 'bg-muted text-foreground/80'
+      }`}
+    >
+      {initials}
+    </span>
+  );
+}
+
 export function MentionPicker({
   id,
   people,
   emptyNotice,
+  heading,
   active,
   anchor,
   onPick,
@@ -48,6 +83,8 @@ export function MentionPicker({
   readonly people: readonly MentionPerson[];
   /** Shown as one non-selectable row when `people` is empty. */
   readonly emptyNotice?: string | null;
+  /** Optional heading above the list. Absent → nothing rendered. */
+  readonly heading?: string | null;
   /** Index of the arrow-focused row, or null for "nothing preselected". */
   readonly active: number | null;
   readonly anchor: MentionAnchor | null;
@@ -70,6 +107,11 @@ export function MentionPicker({
       style={{ position: 'fixed', left: anchor.left, width: anchor.width, ...style }}
       className="z-[120] max-h-48 overflow-y-auto rounded-md border border-border bg-popover p-1 shadow-xl"
     >
+      {heading && (
+        <p data-mention-heading className="px-2 pb-1 pt-0.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground">
+          {heading}
+        </p>
+      )}
       {people.length === 0 ? (
         <p data-mention-empty className="px-2 py-1 text-[11px] text-muted-foreground">
           {emptyNotice}
@@ -94,6 +136,7 @@ export function MentionPicker({
               active === index ? 'bg-muted text-foreground' : 'text-foreground/85 hover:bg-muted/60'
             }`}
           >
+            {person.avatar && <MentionAvatar avatar={person.avatar} label={person.label} />}
             <span className="min-w-0 flex-1 truncate">{person.label}</span>
             {person.detail && (
               // The NAME is what the person reads; the detail gives way first.

package/components/Viewer.tsx

@@ -60,6 +60,7 @@ import { isGraphvizLanguage, isMermaidLanguage } from './diagramLanguages';
 import { getIdentity } from '../utils/identity';
 import { type QuickLabel } from '../utils/quickLabels';
 import type { SelectionAction } from '../utils/selectionActions';
+import type { MentionSource } from '../utils/mentions';
 import { DocBadges, type DocBadgesProps, type LinkedDocBadgeInfo } from './DocBadges';
 import { PinpointOverlay } from './PinpointOverlay';
 import { usePinpoint } from '../hooks/usePinpoint';
@@ -98,12 +99,22 @@ export interface ViewerProps {
    * one wand button that opens the package's dropdown. Absent → unchanged.
    */
   selectionActions?: SelectionAction[];
+  /** Opt-in host capability: the glyph on the `selectionActions` button on
+   *  both toolbars. Absent → the package's own wand. */
+  selectionActionsIcon?: React.ReactNode;
   /**
    * Whether the package's quick labels are offered on the selection toolbars
    * (default true). `false` hides the Zap picker and the Alt+digit label
    * shortcuts; the 👍 button is unaffected.
    */
   quickLabels?: boolean;
+  /**
+   * Opt-in host capability, forwarded to BOTH comment composers this viewer
+   * mounts (the text-selection composer and the global / code-block one): the
+   * `@` mention source for the composer's picker. The picked ids ride onto the
+   * created annotation as `Annotation.mentions`. Absent → unchanged.
+   */
+  mentionSource?: MentionSource;
   blocks: Block[];
   markdown: string;
   frontmatter?: Frontmatter | null;
@@ -374,7 +385,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   inputMethod = 'drag',
   taterMode,
   selectionActions,
+  selectionActionsIcon,
   quickLabels,
+  mentionSource,
   globalAttachments = [],
   onAddGlobalAttachment,
   onRemoveGlobalAttachment,
@@ -558,6 +571,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     images?: ImageAttachment[],
     isQuickLabel?: boolean,
     quickLabelTip?: string,
+    mentions?: readonly string[],
   ) => {
     if (readOnlyRef.current) return;
 
@@ -577,6 +591,9 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
       createdA: Date.now(),
       author: getIdentity(),
       images,
+      // Host capability: present only when a mentionSource was supplied AND a
+      // token survived, so a code-block comment without one is unchanged.
+      ...(mentions && mentions.length > 0 ? { mentions } : {}),
       ...(isQuickLabel ? { isQuickLabel: true } : {}),
       ...(quickLabelTip ? { quickLabelTip } : {}),
     };
@@ -957,7 +974,11 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     setCodeBlockToolbar(null);
   };
 
-  const handleViewerCommentSubmit = (text: string, images?: ImageAttachment[]) => {
+  const handleViewerCommentSubmit = (
+    text: string,
+    images?: ImageAttachment[],
+    mentions?: readonly string[],
+  ) => {
     if (readOnlyRef.current || !viewerCommentPopover) return;
 
     if (viewerCommentPopover.isGlobal) {
@@ -975,12 +996,22 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
         createdA: Date.now(),
         author: getIdentity(),
         images,
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
       };
       onAddAnnotation(newAnnotation);
     } else if (viewerCommentPopover.codeBlock) {
       const codeEl = viewerCommentPopover.codeBlock.element.querySelector('code');
       if (codeEl) {
-        applyCodeBlockAnnotation(viewerCommentPopover.codeBlock.block.id, codeEl, AnnotationType.COMMENT, text, images);
+        applyCodeBlockAnnotation(
+          viewerCommentPopover.codeBlock.block.id,
+          codeEl,
+          AnnotationType.COMMENT,
+          text,
+          images,
+          undefined,
+          undefined,
+          mentions,
+        );
       }
     }
 
@@ -1312,6 +1343,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               onRequestComment={handleRequestComment}
               onQuickLabel={handleQuickLabel}
               selectionActions={selectionActions}
+              selectionActionsIcon={selectionActionsIcon}
               quickLabels={quickLabels}
               copyText={toolbarState.selectionText}
               hideCopyButton={!isTouchDevice}
@@ -1369,6 +1401,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 onRequestComment={handleCodeBlockRequestComment}
                 onQuickLabel={handleCodeBlockQuickLabel}
                 selectionActions={selectionActions}
+                selectionActionsIcon={selectionActionsIcon}
                 quickLabels={quickLabels}
                 isExiting={isCodeBlockToolbarExiting}
                 onMouseEnter={() => {
@@ -1447,6 +1480,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               draftKey={`plan:${commentDraftScope}:${hookCommentPopover.draftKey}`}
               onSubmit={hookCommentSubmit}
               onClose={hookCommentClose}
+              mentionSource={mentionSource}
               allowImages={allowImages}
               skillReferences
               onAskAI={onAskAI}
@@ -1471,6 +1505,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
             }`}
             onSubmit={handleViewerCommentSubmit}
             onClose={handleViewerCommentClose}
+            mentionSource={mentionSource}
             allowImages={allowImages}
             skillReferences
             onAskAI={onAskAI}

package/components/html-viewer/HtmlViewer.tsx

@@ -6,6 +6,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
 import { useVimDocumentFocus } from "../../hooks/useVimDocumentFocus";
@@ -25,6 +26,7 @@ import {
 } from "../../utils/vimHud";
 import { AnnotationToolbar } from "../AnnotationToolbar";
 import type { SelectionAction } from "../../utils/selectionActions";
+import type { MentionSource } from "../../utils/mentions";
 import { AttachmentsButton } from "../AttachmentsButton";
 import {
   CommentPopover,
@@ -270,6 +272,14 @@ export interface HtmlViewerProps {
    *  toolbar: the host's own commands for the current selection, rendered as
    *  one wand button that opens the package's dropdown. Absent → unchanged. */
   selectionActions?: SelectionAction[];
+  /** Opt-in host capability: the glyph on the `selectionActions` button.
+   *  Absent → the package's own wand. */
+  selectionActionsIcon?: ReactNode;
+  /** Opt-in host capability, forwarded to BOTH comment composers this viewer
+   *  mounts (the pinpoint/selection composer and the global one): the `@`
+   *  mention source for the composer's picker. The picked ids ride onto the
+   *  created annotation as `Annotation.mentions`. Absent → unchanged. */
+  mentionSource?: MentionSource;
   /** scrollIntoView behavior when a selected annotation is scrolled into
    *  view inside the page. Default 'smooth'; pass 'auto' to carry the
    *  parent's reduced-motion preference across the iframe boundary. */
@@ -358,6 +368,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onUnanchoredChange,
       maxAdditionalTargets,
       selectionActions,
+      selectionActionsIcon,
+      mentionSource,
       scrollBehavior,
       title = "HTML Plan Viewer",
       bridgeScriptUrl,
@@ -995,7 +1007,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     }));
 
     const handleGlobalCommentSubmit = useCallback(
-      (text: string, images?: ImageAttachment[]) => {
+      (text: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
         if (readOnly) return;
         onAddAnnotation({
           id: `global-${Date.now()}`,
@@ -1008,6 +1020,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
           author: getIdentity(),
           createdA: Date.now(),
           images,
+          ...(mentions && mentions.length > 0 ? { mentions } : {}),
         });
         setGlobalCommentPopover(null);
       },
@@ -1209,6 +1222,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               // future toolbar path can emit an arbitrary label here.
               commentOnly
               selectionActions={selectionActions}
+              selectionActionsIcon={selectionActionsIcon}
               onQuickLabel={(label) => {
                 if (label.id === THUMBS_UP_LABEL.id) hook.handleQuickLabel(label);
               }}
@@ -1229,6 +1243,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               isGlobal={false}
               draftKey={`html:${hook.commentPopover.draftKey}`}
               onSubmit={hook.handleCommentSubmit}
+              mentionSource={mentionSource}
               // Pinpoint clicks open this composer directly, so it carries
               // the surface's one-click "Looks good" (the global composer
               // does not: a document-wide thumbs-up is not a thing).
@@ -1260,6 +1275,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               isGlobal={true}
               onSubmit={handleGlobalCommentSubmit}
               onClose={() => setGlobalCommentPopover(null)}
+              mentionSource={mentionSource}
               skillReferences
               onAskAI={onAskAI}
               askAIContext={{ kind: "general", label: "Document" }}

package/components/html-viewer/useHtmlAnnotation.ts

@@ -911,7 +911,7 @@ export function useHtmlAnnotation({
   );
 
   const handleCommentSubmit = useCallback(
-    (comment: string, images?: ImageAttachment[]) => {
+    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
       if (!enabledRef.current) return;
       // Prefer the text captured when the popover opened — it can't be clobbered by
       // a later selection change or clear while the user is composing the comment.
@@ -944,6 +944,9 @@ export function useHtmlAnnotation({
         author: getIdentity(),
         createdA: Date.now(),
         images,
+        // Host capability: present only when a mentionSource was supplied AND
+        // a token survived, so a comment without one is unchanged.
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
         htmlAnchor: pendingAnchorRef.current ?? undefined,
         elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,

package/hooks/useAnnotationHighlighter.ts

@@ -631,7 +631,13 @@ export interface UseAnnotationHighlighterReturn {
   handleQuickLabel: (label: QuickLabel) => void;
   handleToolbarClose: () => void;
   handleRequestComment: (initialChar?: string) => void;
-  handleCommentSubmit: (text: string, images?: ImageAttachment[]) => void;
+  /** The composer's submit. `mentions` arrives only from a `CommentPopover`
+   *  the host gave a `mentionSource`; the ids ride onto the new annotation. */
+  handleCommentSubmit: (
+    text: string,
+    images?: ImageAttachment[],
+    mentions?: readonly string[],
+  ) => void;
   handleCommentClose: () => void;
   handleFloatingQuickLabel: (label: QuickLabel) => void;
   handleQuickLabelPickerDismiss: () => void;
@@ -870,6 +876,7 @@ export function useAnnotationHighlighter({
     images?: ImageAttachment[],
     isQuickLabel?: boolean,
     quickLabelTip?: string,
+    mentions?: readonly string[],
   ) => {
     const doms = highlighter.getDoms(source.id);
     let blockId = '';
@@ -904,6 +911,9 @@ export function useAnnotationHighlighter({
       startMeta: source.startMeta,
       endMeta: source.endMeta,
       images,
+      // Host capability: present only when a mentionSource was supplied AND a
+      // token survived, so an annotation created without one is unchanged.
+      ...(mentions && mentions.length > 0 ? { mentions } : {}),
       ...(mathTargets.length > 0 ? {
         mathTargets: mathTargets.map(target => ({
           blockId: target.blockId,
@@ -933,6 +943,7 @@ export function useAnnotationHighlighter({
     images?: ImageAttachment[],
     isQuickLabel?: boolean,
     quickLabelTip?: string,
+    mentions?: readonly string[],
   ) => {
     const id = annotationId();
     applyMathAnnotationClass(source.element, id, type, source.displayMode);
@@ -951,6 +962,7 @@ export function useAnnotationHighlighter({
       createdA: Date.now(),
       author: getIdentity(),
       images,
+      ...(mentions && mentions.length > 0 ? { mentions } : {}),
       ...(isQuickLabel ? { isQuickLabel: true } : {}),
       ...(quickLabelTip ? { quickLabelTip } : {}),
     };
@@ -1695,7 +1707,11 @@ export function useAnnotationHighlighter({
     setToolbarState(null);
   };
 
-  const handleCommentSubmit = (text: string, images?: ImageAttachment[]) => {
+  const handleCommentSubmit = (
+    text: string,
+    images?: ImageAttachment[],
+    mentions?: readonly string[],
+  ) => {
     if (!commentPopover) return;
     if (isMathAnnotationSource(commentPopover.source)) {
       createAnnotationFromMathSource(
@@ -1703,6 +1719,9 @@ export function useAnnotationHighlighter({
         AnnotationType.COMMENT,
         text,
         images,
+        undefined,
+        undefined,
+        mentions,
       );
       clearPendingSelection();
       window.getSelection()?.removeAllRanges();
@@ -1712,7 +1731,7 @@ export function useAnnotationHighlighter({
     if (commentPopover.source && highlighterRef.current) {
       createAnnotationFromSource(
         highlighterRef.current, commentPopover.source,
-        AnnotationType.COMMENT, text, images
+        AnnotationType.COMMENT, text, images, undefined, undefined, mentions
       );
       clearPendingSelection();
       window.getSelection()?.removeAllRanges();