@plannotator/ui 0.44.0 → 0.45.0

package/HANDOFF.md

@@ -1321,8 +1321,180 @@ Tests: `utils/composerTokens.test.ts` (16, DOM-free) and
 `components/CommentPopover.mentionChips.test.tsx` (11, DOM-gated, in the
 workflow's DOM_TESTS step).
 
+## Annotation card header slot and mentions on the edit box (0.45.0)
+
+0.43.1 closed with an open question: "Editing an existing comment happens in
+`AnnotationPanel`'s card, a plain textarea that has never had an `@` picker…
+If you want the panel editor to pick people too, that is a separate prop on
+`AnnotationPanel` and worth asking for." It was asked for, so 0.45.0 adds it —
+together with the header twin of the panel's existing `renderCardFooter`.
+Same ruling as the four releases before it: opt-in host capabilities that
+change nothing for Plannotator's own users when they are not supplied.
+`packages/editor` and `packages/review-editor` have ZERO source diff in this
+release; core is UNCHANGED at `0.25.5`, so **ui 0.45.0 publishes alone**.
+
+### 1. `renderCardHeader` — the twin of `renderCardFooter`
+
+```ts
+renderCardHeader?: (annotation: Annotation) => React.ReactNode;
+```
+
+Rendered inside each plan-annotation card's HEADER row — the row carrying the
+type word, the `diff` / page / `Unanchored` chips and `author · time` — after
+the timestamp and before the built-in edit/delete cluster, which keeps the
+right edge on its `ml-auto`. That is the slot for a status stamp (resolved,
+needs reply, a reviewer badge); the footer remains the slot for reply and
+resolve UI.
+
+It follows the footer's contract line for line:
+
+- The wrapper is `[data-annotation-card-header="true"]` (the footer's
+  `[data-annotation-card-footer="true"]` spelled for the header — the attribute
+  the host queries and styles), and it stops `click` and `keydown`
+  propagation, so interacting with your stamp never selects the card.
+- **It renders under `readOnly`**, exactly as the footer does and for the same
+  reason: the contents are host-owned and a stamp is a read affordance. The
+  built-in mutation affordances stay hidden.
+- In the All-files grouped view it rides the OPEN document's cards only
+  (`group.isCurrent`), the footer's rule — a slot built from the open
+  document's state has nothing to say about another document's card.
+- Returning `null` / `undefined` / `false` for a card renders no wrapper for
+  that card. Omitting the prop renders no wrapper anywhere: there is no empty
+  container to lay out or style around.
+- The header row is ONE non-wrapping flex line shared with the type word, the
+  `diff` / page / `Unanchored` chips and the timestamp. The wrapper is
+  `min-w-0` and shrinks, but a host node that cannot shrink will overflow
+  toward the built-in actions rather than wrap — keep the stamp compact, or
+  give it its own truncation.
+
+**Not on `CodeAnnotation` cards.** `CodeAnnotationCard` (the review-editor
+shape) takes no `renderCardFooter` either, so neither new prop was threaded
+into it; mirroring the footer is the rule. Ask if a host needs both there.
+
+### 2. `mentionSource` — the `@` picker on the card's edit box
+
+```ts
+mentionSource?: MentionSource;   // the same type, unchanged, from 0.43.0
+```
+
+Supplied on the panel and threaded to every plan-annotation card, it gives the
+card's EDIT textarea the same `@` machinery `CommentPopover` has:
+`useMentionAutocomplete` over the host's `people`, the portaled `MentionPicker`,
+the same grammar (`@` at a word boundary, never inside `a@b.com`), the same
+no-preselection keyboard rule (Enter is a newline until an arrow engages a
+row), the same `onMentionsChange`, and the same `onPickBlocked` no-access
+behavior (a blocked pick inserts NOTHING and the host shows its own dialog).
+
+**Key order at the textarea.** The menu is offered the key FIRST, then the
+card's own handlers run only if it did not consume the event:
+
+- `Escape` while the menu is open closes the MENU (the hook consumes it and
+  stops propagation). A second `Escape` cancels the edit, as it always did.
+- `Enter` with a row arrowed to inserts that person. `Enter` with nothing
+  active is untouched — still a newline.
+- `Mod+Enter` is never consumed by the menu (the hook declines any event
+  carrying a modifier), so save still saves.
+
+ARIA follows `CommentPopover`: `aria-autocomplete="list"` and
+`aria-haspopup="listbox"` exist only when a source is supplied,
+`aria-controls` / `aria-owns` only while the menu is open, and
+`aria-activedescendant` only while a row is active. With no source all five
+resolve to `undefined`, so the rendered attribute list is the one the edit box
+has always had.
+
+### 3. The save rule
+
+`handleSaveEdit` called `onEdit({ text })`. It now calls:
+
+```ts
+if (mentionSource && mentions.length > 0) onEdit({ text: editText, mentions });
+else onEdit({ text: editText });
+```
+
+which is the presence rule the creation composers already keep, one level
+down: **the key exists only when a source was supplied AND at least one id
+survived to save.** Never `mentions: []`, never the key with an `undefined`
+value — an untouched or pick-less edit calls `onEdit({ text })` byte for byte
+as it did in 0.44.0, so it can never wipe tags the annotation already carries.
+`source.onMentionsChange` fires from the hook exactly as it does in the
+composer, which on this surface means it reports `[]` once when the editor
+OPENS, before any pick: it is the live state of this edit session, not the
+annotation's stored `mentions`. Only `onEdit` is authoritative — a host that
+mirrors `onMentionsChange` into its own record must not treat that opening
+`[]` as a clear. The Save BUTTON and `Mod+Enter` go through the same call.
+
+**"This edit session" is literal.** The edit box was extracted into
+`AnnotationEditComposer`, mounted only while a card is in edit mode, so the
+hook's tagged-people state lives and dies with one session: reopen the editor
+and nobody is picked, and a save with no new pick is `{ text }` again — even
+if the previous session's `@Label` token is still sitting in the body. That is
+the conservative direction (the host owns `mentions` from then on, 0.43.1 §4),
+and it is the same reason a restored draft starts with nobody tagged.
+
+### 4. No chips in the edit box (known difference, and the follow-up)
+
+A picked token renders as a CHIP in `CommentPopover` (0.44.0) and as plain
+text here. The chip layer is `ComposerTextarea`'s mirrored, aria-hidden
+overlay behind a transparent-text textarea, with scroll mirroring and IME
+handling; the card's edit box is a plain `<textarea>` with its own sizing and
+classes. Duplicating that overlay for one more textarea is exactly the "two
+mirrored layers" mistake 0.44.0 avoided.
+
+**Named follow-up: move the card's edit box onto `ComposerTextarea`.** That is
+the one change that gets chips here without a second overlay, and it is a
+visible change to a surface Plannotator itself renders — a separate PR with
+its own no-op argument, not a rider on a seam release.
+
+Everything else about mentions is inherited unchanged and documented in the
+0.43.x / 0.44.0 sections above, including the three limits: two labels that
+sanitize to the same token, a restored draft reporting no ids, and a label
+that is a prefix of another label.
+
+### 5. One internal module, not a new seam
+
+`components/MentionAutocomplete.tsx` (`MentionAutocompleteMenu` +
+`mentionActiveOptionId`) is the glue between a `useMentionAutocomplete` result
+and `MentionPicker` — the id→index lookup, the no-op hover and the
+`aria-activedescendant` string. It exists so the third mount did not become a
+third verbatim copy of the same fifteen lines; `CommentPopover`'s two mounts
+were moved onto it in the same change, with no DOM difference (proven below).
+It is **internal**: it is not on the supported-import list and hosts never
+touch it — they pass `mentionSource`.
+
+### The no-op guarantee, and how it is pinned
+
+The same components were mounted on `origin/main` and on this branch in one
+harness and their `outerHTML` diffed, with `addEventListener` and `setTimeout`
+counts taken across each mount. With NEITHER new prop supplied, all six are
+byte-identical with identical counts:
+
+| scenario | bytes | listeners | timers |
+| --- | --- | --- | --- |
+| empty panel | 733 | 140 | 0 |
+| nine cards (comment, deletion, global, quick label, external `source`, unanchored, `inReplyTo` reply, a card with `renderCardFooter`, a `diffContext` card) | 17543 | 141 | 0 |
+| the same panel `readOnly` | 7854 | 141 | 0 |
+| a card in EDIT mode | 18586 | 142 | 0 |
+| the All-files grouped view (two document groups) | 19629 | 141 | 0 |
+| `CommentPopover` (the module the glue refactor touched) | 3130 | 286 | 1 |
+
+The edit-mode row is the one that matters for the hook: mounted with
+`source: undefined`, `useMentionAutocomplete` registers no listener, opens no
+menu state, returns the frozen empty id array, and the picker renders nothing —
+one extra listener would have shown up as 143.
+
+On top of the diff, committed tests pin the structure rather than a snapshot:
+with neither prop there is no `[data-annotation-card-header]` on any card, the
+edit textarea carries none of the five mention ARIA attributes, typing `@`
+opens nothing, and `onEdit` is called with an updates object whose key list is
+exactly `['text']`.
+
+Tests (both DOM-gated, both added to the workflow's DOM_TESTS step):
+`components/AnnotationPanel.cardHeader.test.tsx` (6) and
+`components/AnnotationPanel.editMentions.test.tsx` (10).
+
 ## Publishing & versioning
 
+- **ui 0.45.0 (annotation card header slot + mentions on the card's edit box): `@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.44.0, both props on `AnnotationPanel`: `renderCardHeader` (the header-row twin of `renderCardFooter`, wrapper `[data-annotation-card-header]`, renders under `readOnly`, open-document cards only in the All-files view) and `mentionSource` (the 0.43.0 type, applied to the card's EDIT box, saving `onEdit(id, { text, mentions })` only when a source was supplied and a pick survived). Nothing is removed, no new supported imports (`components/MentionAutocomplete` is internal glue), no export-, share- or archive-visible change, and Plannotator passes neither — `packages/editor` and `packages/review-editor` have zero source diff, and the panel is byte-identical to 0.44.0. Known difference from `CommentPopover`: no chips in the card's edit box (follow-up named in the section). See "Annotation card header slot and mentions on the edit box (0.45.0)".
 - **ui 0.44.0 (mention token chips in the composer): `@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.2: the `@Label` tokens a `mentionSource` composer inserted render as chips in the composer's existing highlight overlay, `MentionSource.tokenClassName?` lets a host restyle them (under the metric rule), `useMentionAutocomplete` also returns the surviving `mentions`, and `utils/composerTokens` joins the supported-import list. Nothing is removed, no export-, share- or archive-visible change, and Plannotator passes none of it — with neither `mentionSource` nor `skillReferences` the composer is byte-identical to 0.43.2. See "Mention token chips in the composer (0.44.0)".
 - **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)".

package/README.md

@@ -291,6 +291,47 @@ the composer (0.44.0)" covers the chips, the metric rule, the merged-range
 refactor behind them, and the three inherited limits (duplicate labels,
 restored drafts, and a label that is a prefix of another label).
 
+### Annotation card seams (`AnnotationPanel`; 0.45.0)
+
+Two more opt-in props, both on the panel and both defaulting to today's
+behavior — pass neither and the panel renders byte-for-byte what it rendered
+in 0.44.0 (proven by diffing mounted `outerHTML` against the base commit for
+an empty panel, every card kind, a card in edit mode, `readOnly` and the
+All-files view).
+
+- **`renderCardHeader?: (annotation) => ReactNode`** — the twin of
+  `renderCardFooter`, rendered inside each plan-annotation card's header row
+  after `author · time` and before the built-in edit/delete actions: the place
+  for a status stamp (resolved, needs reply, a reviewer badge). Its wrapper is
+  `[data-annotation-card-header]` and swallows clicks and keydowns, so
+  interacting with your stamp never selects the card. It renders under
+  `readOnly` for the same reason the footer does — a stamp is a read
+  affordance — and, like the footer, only on the OPEN document's cards in the
+  All-files grouped view. Return `null` for a card and no wrapper exists for
+  it; omit the prop and no wrapper exists at all. The header row is one
+  non-wrapping flex line, so keep the stamp compact: the wrapper shrinks but
+  a node that cannot will overflow toward the built-in actions.
+- **`mentionSource?: MentionSource`** — the same source `Viewer` and
+  `HtmlViewer` take (0.43.1), applied to the card's EDIT box, so a comment can
+  be re-tagged after it was written. The grammar, the picker, the keyboard
+  rules and `onPickBlocked` are the ones documented above. Saving an edit
+  calls `onEdit(id, { text, mentions })` **only** when a source is supplied
+  AND at least one person was picked in that edit session whose token
+  survives; otherwise it is the `onEdit(id, { text })` it always was, so an
+  untouched or pick-less edit can never wipe tags the annotation already
+  carries. Reopening the editor starts a fresh session with nobody picked, and
+  `onMentionsChange` follows that session — it reports `[]` once when the
+  editor opens, so treat it as the live picker state, never as the
+  annotation's stored tags.
+  **One difference from `CommentPopover`: no chips** — the token stays plain
+  text, because the chip layer lives in the composer's mirrored overlay and is
+  not worth duplicating; the follow-up is to move the card's edit box onto
+  `ComposerTextarea`.
+
+Neither prop reaches `CodeAnnotation` cards (the review-editor shape), which
+take no `renderCardFooter` either. See HANDOFF.md § "Annotation card header
+slot and mentions on the edit box (0.45.0)".
+
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 
 The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.

package/components/AnnotationPanel.tsx

@@ -1,5 +1,8 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useState, useRef, useEffect, useId } from 'react';
 import { AnnotationType, type Annotation, type Block, type CodeAnnotation, type EditorAnnotation } from '../types';
+import type { MentionSource } from '../utils/mentions';
+import { useMentionAutocomplete } from '../hooks/useMentionAutocomplete';
+import { MentionAutocompleteMenu, mentionActiveOptionId } from './MentionAutocomplete';
 import { isCurrentUser } from '../utils/identity';
 import { ImageThumbnail } from './ImageThumbnail';
 import { EditorAnnotationCard } from './EditorAnnotationCard';
@@ -126,6 +129,21 @@ interface PanelProps {
     *  resolve UI). The panel stays presentation-only; clicks inside the slot
     *  do not select the card. Default: nothing rendered. */
   renderCardFooter?: (annotation: Annotation) => React.ReactNode;
+  /** Host slot rendered inside the header row of each plan-annotation card,
+    *  after `author · time` and before the built-in edit/delete actions — the
+    *  place for a status stamp (resolved, needs reply, a reviewer badge). Twin
+    *  of `renderCardFooter`: the panel stays presentation-only, clicks inside
+    *  the slot do not select the card, and it renders under `readOnly` too
+    *  (a stamp is a read affordance). Default: nothing rendered, and no
+    *  wrapper element exists at all. */
+  renderCardHeader?: (annotation: Annotation) => React.ReactNode;
+  /** Opt-in host capability: an `@` mention source for the EDIT box of each
+    *  plan-annotation card, the same `MentionSource` `Viewer` and `HtmlViewer`
+    *  take for their creation composers. Supplied → the edit textarea grows
+    *  the `@` picker and a save that follows a pick carries the surviving ids
+    *  as `Annotation.mentions`. Absent → the edit box is exactly what it was:
+    *  no listener, no picker, no `mentions` key. */
+  mentionSource?: MentionSource;
   /** Hide every built-in mutation affordance (delete/edit, direct-edit
     *  discard). The host footer slot still renders: its contents are
     *  host-owned and may be read affordances (replies, links), so the host
@@ -183,6 +201,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   onOtherFileAnnotationsClick,
   directEdits = null,
   renderCardFooter,
+  renderCardHeader,
+  mentionSource,
   readOnly = false,
   presentation = 'panel',
   unanchoredIds,
@@ -421,6 +441,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                               : (onEditInDocument ? (updates: Partial<Annotation>) => onEditInDocument(group.path, annotation.id, updates) : undefined)}
                             readOnly={readOnly}
                             footer={group.isCurrent ? renderCardFooter?.(annotation) : undefined}
+                            header={group.isCurrent ? renderCardHeader?.(annotation) : undefined}
+                            mentionSource={mentionSource}
                             unanchored={group.isCurrent ? (unanchoredIds?.has(annotation.id) ?? false) : false}
                           />
                         );
@@ -528,6 +550,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                       onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
                       readOnly={readOnly}
                       footer={renderCardFooter?.(entry.annotation)}
+                      header={renderCardHeader?.(entry.annotation)}
+                      mentionSource={mentionSource}
                       unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                     />
                   </div>
@@ -542,6 +566,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
                   readOnly={readOnly}
                   footer={renderCardFooter?.(entry.annotation)}
+                  header={renderCardHeader?.(entry.annotation)}
+                  mentionSource={mentionSource}
                   unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                 />
                 )
@@ -762,6 +788,87 @@ const DirectEditsCard: React.FC<{
   );
 };
 
+/**
+ * The plan-annotation card's edit box.
+ *
+ * Mounted only while a card is in edit mode, which is also what scopes an
+ * `@` pick to ONE edit session: `useMentionAutocomplete`'s tagged-people
+ * state lives and dies with this component, so reopening the editor starts
+ * with nobody picked and a pick-less save is `{ text }` again.
+ *
+ * Without a `mentionSource` every mention path here is inert — no listener,
+ * no menu state, no picker DOM, and the textarea's attributes are exactly
+ * the ones it rendered before the prop existed (all five mention-related
+ * ARIA attributes resolve to `undefined`).
+ *
+ * KNOWN DIFFERENCE from `CommentPopover`: no chip overlay. The token stays
+ * plain text here. Chips live in `ComposerTextarea` (mirrored overlay behind
+ * a transparent-text textarea) and duplicating that layer is not the way to
+ * get them — the follow-up is to make this box use `ComposerTextarea`.
+ */
+const AnnotationEditComposer: React.FC<{
+  value: string;
+  onChange: (text: string) => void;
+  /** Save with the mention ids the body still tags (empty without a source). */
+  onSave: (mentions: readonly string[]) => void;
+  onCancel: () => void;
+  mentionSource?: MentionSource;
+}> = ({ value, onChange, onSave, onCancel, mentionSource }) => {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const mention = useMentionAutocomplete({ text: value, setText: onChange, textareaRef, source: mentionSource });
+  const listboxId = `annotation-card-mentions-${useId().replace(/:/g, '')}`;
+  const menuOpen = mention.menu !== null;
+
+  // Focus-on-open, unchanged: this component mounts exactly when editing starts.
+  useEffect(() => {
+    if (textareaRef.current) {
+      textareaRef.current.focus();
+      textareaRef.current.select();
+    }
+  }, []);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    // The menu is offered the key FIRST: while it is open Escape closes it
+    // (and only a second Escape cancels the edit), and an arrowed-to row
+    // takes Enter. Mod+Enter is never consumed by the menu.
+    if (mention.onKeyDown(e)) return;
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+      e.preventDefault();
+      onSave(mention.mentionIds);
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      onCancel();
+    }
+  };
+
+  return (
+    <div onClick={(e: React.MouseEvent) => e.stopPropagation()}>
+      <textarea
+        data-pn-mobile-editable="true"
+        ref={textareaRef}
+        value={value}
+        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => { onChange(e.target.value); mention.onSelect(); }}
+        onSelect={mention.onSelect}
+        onKeyDown={handleKeyDown}
+        placeholder="Add your comment..."
+        aria-label="Annotation comment"
+        aria-autocomplete={mentionSource ? 'list' : undefined}
+        aria-haspopup={mentionSource ? 'listbox' : undefined}
+        aria-controls={menuOpen ? listboxId : undefined}
+        aria-owns={menuOpen ? listboxId : undefined}
+        aria-activedescendant={mentionActiveOptionId(listboxId, mention.menu)}
+        className="w-full resize-none rounded-lg border border-border/50 bg-card px-2.5 py-2 text-base leading-relaxed text-foreground outline-none transition-colors placeholder:text-muted-foreground/50 focus:border-primary/40 focus:ring-1 focus:ring-primary/20"
+        style={{ fieldSizing: 'content', minHeight: 44 } as React.CSSProperties}
+      />
+      <div className="mt-1.5 flex justify-end gap-1.5">
+        <Button variant="ghost" size="xxs" onClick={onCancel}>Cancel</Button>
+        <Button size="xxs" disabled={!value.trim()} onClick={() => onSave(mention.mentionIds)}>Save</Button>
+      </div>
+      <MentionAutocompleteMenu id={listboxId} menu={mention.menu} onSelect={mention.select} />
+    </div>
+  );
+};
+
 const AnnotationCard: React.FC<{
   annotation: Annotation;
   isSelected: boolean;
@@ -771,19 +878,15 @@ const AnnotationCard: React.FC<{
   onEdit?: (updates: Partial<Annotation>) => void;
   readOnly?: boolean;
   footer?: React.ReactNode;
+  /** Host slot in the card's header row (see `renderCardHeader`). */
+  header?: React.ReactNode;
+  /** An `@` mention source for the edit box (see `mentionSource`). */
+  mentionSource?: MentionSource;
   /** The annotation has no live location in the document (host-reported). */
   unanchored?: boolean;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, unanchored = false }) => {
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, header, mentionSource, unanchored = false }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
-  const textareaRef = useRef<HTMLTextAreaElement>(null);
-
-  useEffect(() => {
-    if (isEditing && textareaRef.current) {
-      textareaRef.current.focus();
-      textareaRef.current.select();
-    }
-  }, [isEditing]);
 
   // Update editText when annotation.text changes
   useEffect(() => {
@@ -798,9 +901,14 @@ const AnnotationCard: React.FC<{
     setIsEditing(true);
   };
 
-  const handleSaveEdit = () => {
+  const handleSaveEdit = (mentions: readonly string[]) => {
     if (onEdit) {
-      onEdit({ text: editText });
+      // The presence rule, same as the creation composers': the key exists
+      // only when a source was supplied AND at least one id survived to save,
+      // so an untouched or pick-less edit can never wipe tags the annotation
+      // already carries.
+      if (mentionSource && mentions.length > 0) onEdit({ text: editText, mentions });
+      else onEdit({ text: editText });
     }
     setIsEditing(false);
   };
@@ -810,39 +918,19 @@ const AnnotationCard: React.FC<{
     setIsEditing(false);
   };
 
-  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
-      e.preventDefault();
-      handleSaveEdit();
-    } else if (e.key === 'Escape') {
-      e.preventDefault();
-      handleCancelEdit();
-    }
-  };
-
   const typeColor = TYPE_COLOR[annotation.type] ?? 'text-muted-foreground';
   const typeLabel = TYPE_LABEL[annotation.type] ?? 'Note';
   const isGlobal = annotation.type === AnnotationType.GLOBAL_COMMENT;
 
-  // Shared edit textarea — matches the prototype composer primitive
+  // The edit box, mounted only while editing (see AnnotationEditComposer).
   const editComposer = (
-    <div onClick={(e: React.MouseEvent) => e.stopPropagation()}>
-      <textarea
-        data-pn-mobile-editable="true"
-        ref={textareaRef}
-        value={editText}
-        onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setEditText(e.target.value)}
-        onKeyDown={handleKeyDown}
-        placeholder="Add your comment..."
-        aria-label="Annotation comment"
-        className="w-full resize-none rounded-lg border border-border/50 bg-card px-2.5 py-2 text-base leading-relaxed text-foreground outline-none transition-colors placeholder:text-muted-foreground/50 focus:border-primary/40 focus:ring-1 focus:ring-primary/20"
-        style={{ fieldSizing: 'content', minHeight: 44 } as React.CSSProperties}
-      />
-      <div className="mt-1.5 flex justify-end gap-1.5">
-        <Button variant="ghost" size="xxs" onClick={handleCancelEdit}>Cancel</Button>
-        <Button size="xxs" disabled={!editText.trim()} onClick={handleSaveEdit}>Save</Button>
-      </div>
-    </div>
+    <AnnotationEditComposer
+      value={editText}
+      onChange={setEditText}
+      onSave={handleSaveEdit}
+      onCancel={handleCancelEdit}
+      mentionSource={mentionSource}
+    />
   );
 
   return (
@@ -890,6 +978,19 @@ const AnnotationCard: React.FC<{
         <span className="text-[10px] text-muted-foreground/50 truncate">
           {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdA)}
         </span>
+        {/* Host header slot (a status stamp etc.) — interactions inside it
+            must not toggle card selection, exactly like the footer slot.
+            Rendered under readOnly too: its contents are host-owned. */}
+        {header != null && header !== false && (
+          <div
+            data-annotation-card-header="true"
+            className="flex min-w-0 items-center"
+            onClick={(e: React.MouseEvent) => e.stopPropagation()}
+            onKeyDown={(e: React.KeyboardEvent) => e.stopPropagation()}
+          >
+            {header}
+          </div>
+        )}
         {!readOnly && (
           <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
             {onEdit && annotation.type !== AnnotationType.DELETION && !isEditing && (

package/components/CommentPopover.tsx

@@ -16,7 +16,7 @@ import {
   type ComposerTokenRange,
 } from '../utils/composerTokens';
 import { useMentionAutocomplete } from '../hooks/useMentionAutocomplete';
-import { MentionPicker } from './MentionPicker';
+import { MentionAutocompleteMenu, mentionActiveOptionId } from './MentionAutocomplete';
 import type { MentionPerson, MentionSource } from '../utils/mentions';
 import {
   hasPrimaryCoarsePointer,
@@ -551,10 +551,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   // the textarea's ARIA relationship points at whichever one is. All three are
   // `undefined`/false with no menu open, which is every render Plannotator
   // makes without a `mentionSource`.
-  const activeMentionOptionId =
-    mentionAc.menu === null || mentionAc.menu.activeIndex === null
-      ? undefined
-      : `${mentionListboxId}-option-${mentionAc.menu.activeIndex}`;
+  const activeMentionOptionId = mentionActiveOptionId(mentionListboxId, mentionAc.menu);
   const composerListboxId = mentionAc.menu !== null ? mentionListboxId : skillListboxId;
   const composerListboxOpen = skillAc.menu !== null || mentionAc.menu !== null;
   const activeComposerOptionId = activeSkillOptionId ?? activeMentionOptionId;
@@ -709,21 +706,11 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               activeOptionId={activeComposerOptionId}
             />
             <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
-            {mentionAc.menu && (
-              <MentionPicker
-                id={mentionListboxId}
-                people={mentionAc.menu.items}
-                emptyNotice={mentionAc.menu.emptyNotice}
-                heading={mentionAc.menu.heading}
-                active={mentionAc.menu.activeIndex}
-                anchor={mentionAc.menu.anchor}
-                onPick={(person) => {
-                  const index = mentionAc.menu?.items.findIndex((p) => p.id === person.id) ?? -1;
-                  if (index >= 0) mentionAc.select(index);
-                }}
-                onHover={() => {}}
-              />
-            )}
+            <MentionAutocompleteMenu
+              id={mentionListboxId}
+              menu={mentionAc.menu}
+              onSelect={mentionAc.select}
+            />
           </div>
 
           {/* Footer — DOM order sets tab order (Save first); row-reverse keeps the visual layout unchanged */}
@@ -875,21 +862,11 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           activeOptionId={activeComposerOptionId}
         />
         <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
-        {mentionAc.menu && (
-          <MentionPicker
-            id={mentionListboxId}
-            people={mentionAc.menu.items}
-            emptyNotice={mentionAc.menu.emptyNotice}
-            heading={mentionAc.menu.heading}
-            active={mentionAc.menu.activeIndex}
-            anchor={mentionAc.menu.anchor}
-            onPick={(person) => {
-              const index = mentionAc.menu?.items.findIndex((p) => p.id === person.id) ?? -1;
-              if (index >= 0) mentionAc.select(index);
-            }}
-            onHover={() => {}}
-          />
-        )}
+        <MentionAutocompleteMenu
+          id={mentionListboxId}
+          menu={mentionAc.menu}
+          onSelect={mentionAc.select}
+        />
       </div>
 
       {/* Footer — same DOM-order/row-reverse pattern as the dialog footer above */}

package/components/MentionAutocomplete.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { MentionPicker } from './MentionPicker';
+import type { MentionMenuState } from '../hooks/useMentionAutocomplete';
+
+/**
+ * Internal glue between `useMentionAutocomplete` and `MentionPicker`: the
+ * id→index lookup, the no-op hover and the `aria-activedescendant` string
+ * that every composer mounting an `@` menu would otherwise repeat verbatim.
+ *
+ * Not a host seam — hosts pass `mentionSource` and never see this. It exists
+ * so the third mount (the annotation card's edit box) did not become a third
+ * copy of the same fifteen lines.
+ */
+
+/**
+ * The picker for a `useMentionAutocomplete` result. Renders nothing while no
+ * menu is open — which, with no `MentionSource`, is always.
+ */
+export const MentionAutocompleteMenu: React.FC<{
+  /** Listbox id the driving textarea points `aria-controls` at. */
+  readonly id: string;
+  readonly menu: MentionMenuState | null;
+  /** `useMentionAutocomplete`'s `select`. */
+  readonly onSelect: (index: number) => void;
+}> = ({ id, menu, onSelect }) => {
+  if (menu === null) return null;
+  return (
+    <MentionPicker
+      id={id}
+      people={menu.items}
+      emptyNotice={menu.emptyNotice}
+      heading={menu.heading}
+      active={menu.activeIndex}
+      anchor={menu.anchor}
+      onPick={(person) => {
+        const index = menu.items.findIndex((p) => p.id === person.id);
+        if (index >= 0) onSelect(index);
+      }}
+      onHover={() => {}}
+    />
+  );
+};
+
+/**
+ * `aria-activedescendant` for the textarea driving that menu: the id of the
+ * arrow-focused row, or `undefined` while nothing is active (the menu opens
+ * with nothing preselected) and while no menu is open at all.
+ */
+export function mentionActiveOptionId(
+  listboxId: string,
+  menu: MentionMenuState | null,
+): string | undefined {
+  if (menu === null || menu.activeIndex === null) return undefined;
+  return `${listboxId}-option-${menu.activeIndex}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",