@plannotator/ui 0.43.1 → 0.44.0

package/HANDOFF.md

@@ -215,6 +215,7 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `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` (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/composerTokens` | The comment composer's token highlight ranges: `skillTokenRanges`, `mentionTokenRanges`, `mergeTokenRanges` and `ComposerTokenRange`. Pure (no DOM, no styling) — the one place that decides which bytes of a composer's text are a token and which source wins when two claim the same ones. *(Blessed in 0.44.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 +957,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 +974,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;
 }
@@ -1168,8 +1172,158 @@ global composer through its button — and
 HtmlViewer through a bridge pinpoint message and its global button. Plus the two DOM-free pins in
 §3 above.
 
+## Mention token chips in the composer (0.44.0)
+
+0.43.0-0.43.2 gave the composer an `@` picker; the token it inserted was
+then plain text in the textarea. 0.44.0 paints it as a **chip**, so a tag
+looks the same in the picker row, in the input, and in the comment the host
+posts. Same ruling as the three releases before it: 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; core
+is UNCHANGED at `0.25.5`, so **ui 0.44.0 publishes alone**.
+
+### One overlay, two sources (the refactor)
+
+`ComposerTextarea` already used exactly the right technique for skill
+references: a mirrored, aria-hidden overlay rendered BEHIND a
+transparent-text textarea (a textarea cannot style substrings), sharing the
+font/padding/wrapping metrics and mirroring scroll, with `.pn-ref-composing`
+hiding it during IME composition. Chips do not add a second overlay — two
+mirrored layers could never stay pixel-aligned with each other, and only one
+of them could own the scroll sync. Instead the overlay became a TOKEN
+HIGHLIGHT LAYER fed by a merged list of ranges, and it turns on when EITHER
+source is active.
+
+The range computation moved out of the render loop into
+`utils/composerTokens` (pure — no DOM, no styling, no React):
+
+- `skillTokenRanges(tokens)` — today's positioned occurrences, unchanged.
+- `mentionTokenRanges(text, people)` — every occurrence of each surviving
+  person's readable `@Label` token.
+- `mergeTokenRanges(text, groups)` — `groups` in priority order; drops
+  ranges outside `[0, text.length)` and empty/inverted ones, then keeps
+  earlier `start`, longer at the same start, earlier group at the same start
+  and length, and drops anything beginning inside a range already kept.
+  Nothing nests, so the overlay stays a flat sequence of spans.
+
+With a single skill source this reproduces the pre-refactor loop exactly
+(which dropped a token whose `start` fell behind the cursor or whose `end`
+ran past the text). The component keeps the Tailwind classes and the `data-*`
+attributes in `renderTokenSpan`, both so the class scanner still sees them
+and so the metric rule below is read with the classes it governs.
+
+### The chip
+
+A chip is painted only for a person the author PICKED whose token still
+survives — `useMentionAutocomplete` now also returns those survivors as
+`mentions` (frozen-empty with no source, the same treatment `mentionIds`
+gets), so the ranges come from the mention id model and never from a regex
+over arbitrary `@words`. Editing one byte of a token un-chips it in the same
+render that drops the id from `onMentionsChange`, so a chip follows the body
+rather than a stale pick. The one case where the chips and the reported IDS
+can still part company is the prefix case in the limitations below, which
+the chips inherit rather than introduce.
+
+```
+<span data-mention-token="user_1" data-mention-kind="user" class="…">@Marcus Chen</span>
+```
+
+- `data-mention-token` is the opaque host id; `data-mention-kind` carries
+  `MentionPerson.kind` verbatim — the host's styling hook. Know what that
+  means today: the picker offers USERS ONLY (`mentionMatches` drops every
+  person whose `kind !== 'user'`), so only a user can be picked, only a user
+  can be tagged, and the attribute only ever reads `user`. `agent` is the
+  reserved value for the day agents become taggable — a host rule for
+  `[data-mention-kind="agent"]` matches nothing until then.
+- `MentionSource.tokenClassName?: string` (new, optional) is appended to the
+  span verbatim for a host that wants its own look.
+- The package default is `text-primary bg-primary/15` and a 3px radius —
+  the skill-reference treatment one shade stronger, so the two token kinds in
+  one overlay read as siblings. Deliberately no ring: every class it uses is
+  one the package already emitted, so a host's generated CSS is unchanged
+  (and so is the portable guide viewer's bundle — `guide-viewer-manifest.ts`
+  needed no regeneration, which is why core is untouched).
+
+**THE METRIC RULE (and it is the host's too).** A chip may change COLOR,
+BACKGROUND, BORDER-RADIUS, BOX-SHADOW and TEXT-DECORATION only. Padding,
+margin, border width, font-weight, letter-spacing and font-size all move a
+glyph, and the overlay's glyphs must coincide with the textarea's own layout
+or the caret drifts away from the text it is painting. A pill's horizontal
+breathing room is faked with `box-shadow: 0 0 0 Npx <background>`, which
+paints without occupying space — that is the way to a pill look through
+`tokenClassName`, and the reason the rule bans padding rather than the
+appearance.
+
+### What did NOT change
+
+The overlay exists for the whole life of a mention composer, not only once
+somebody is tagged, so the first pick never swaps the textarea element under
+the caret. IME composition, scroll sync, the resize gutter, the placeholder,
+the `/` + `$` skill autocomplete and its menu, the Alt-typing path, drafts
+(`initialDraft` / `draftKey`), image attachments and `Mod+Enter` submit are
+all untouched, and `onSubmit(text, images?, mentions?)` is the same call.
+`Viewer` and `HtmlViewer` needed no change at all: they already forward
+`mentionSource` (0.43.1), and the chips are inside the composer it reaches.
+
+Three inherited limitations are worth stating rather than fixing here:
+
+- **Two people whose labels sanitize to the same token** are
+  indistinguishable in a plain-text body, so the FIRST of them listed owns
+  every occurrence of it. That is the same first-match rule
+  `survivingMentions` already applies to the ids; it renders and never
+  throws.
+- **A restored draft has no chips** until the author picks again, because
+  the survivors come from the picks made in THIS composer — exactly the same
+  reason `onMentionsChange` reports `[]` for a restored draft today (0.43.x
+  behavior, unchanged). It reports no STALE ids either: a reopened draft
+  starts with nobody tagged, so the chips and the ids agree on "none".
+- **A label that is a prefix of another label** (`Ann` and `Anna Lee`, both
+  picked): the CHIPS are right — longest-wins means `@Anna Lee` is painted
+  whole and is never half-covered by an `@Ann` chip. The IDS are the loose
+  end: delete `@Ann` from a body that still reads `@Anna Lee` and
+  `survivingMentions` keeps reporting Ann, because it asks
+  `text.includes('@Ann')`. So the id list can outlive the chip. That is
+  0.43.x behavior in `survivingMentions`, unchanged here — the chips only
+  make it visible.
+
+### 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:
+
+- **No `mentionSource`, no `skillReferences`:** the composer is
+  byte-identical — 3192 bytes, and the same `addEventListener` and
+  `setTimeout` counts (287 / 1 in that harness). No overlay element exists
+  at all.
+- **`skillReferences` only:** the popover (4821 bytes) and the overlay
+  itself (634 bytes) are byte-identical, same listener and timer counts
+  (150 / 1). `data-skill-ref-overlay="true"` is written only when
+  `skillReferences` is on, so a skill composer's overlay keeps the exact
+  attribute list it had; a mentions-only overlay is found by its
+  `data-pn-mobile-editable-mirror` attribute instead.
+- A mention composer's overlay costs exactly one extra listener (the
+  textarea's `scroll`, which is what mirrors the layer) — the same one a
+  skill composer has always paid.
+- **The portable guide viewer's build is byte-identical** (`viewer.*.js` and
+  `viewer.*.css` hashes and their SRI unchanged against `origin/main`), so
+  `packages/core/guide-viewer-manifest.ts` is in sync and core is untouched.
+  That is also why the default chip reuses classes the package already
+  emitted instead of introducing one.
+
+**Real-browser metric proof** (headless Chromium, throwaway Vite harness):
+typing `Nice catch @ma`, picking Marcus and continuing to type, the chip's
+bounding rect and the textarea's own text run for that token agree to
+**0.000px** on both axes and in width — at 420px and 1200px, on a wrapped
+line (3 lines above it) and with the textarea scrolled (`scrollTop` 40) —
+and the caret x after the token is **0.016px** from the span's end.
+
+Tests: `utils/composerTokens.test.ts` (16, DOM-free) and
+`components/CommentPopover.mentionChips.test.tsx` (11, DOM-gated, in the
+workflow's DOM_TESTS step).
+
 ## Publishing & versioning
 
+- **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)".
 - **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.

package/README.md

@@ -245,7 +245,9 @@ in 0.42.0 (proven by diffing the mounted `outerHTML` against the base commit).
 - **`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
@@ -256,6 +258,24 @@ 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.
+- **`CommentPopover` mention chips** (0.44.0): with a `mentionSource`, the
+  `@Label` tokens the picker inserted render as chips in the composer's text —
+  the same mirrored overlay skill references use, never a second layer. Each
+  chip span carries `data-mention-token="<person id>"` and
+  `data-mention-kind`, which is `MentionPerson.kind` verbatim — today that is
+  always `user`, because the picker offers users only; `agent` is reserved
+  and matches nothing yet. `MentionSource.tokenClassName?` is appended to the
+  span for your own look. **Metric rule, yours to keep too:** a chip
+  may change color, background, border-radius, box-shadow and text-decoration
+  ONLY — padding, margin, border width, weight, tracking or size move a glyph
+  and drift the caret off the painted text (want a pill? add
+  `box-shadow: 0 0 0 Npx <background>`, which paints without taking space).
+  Only a person you supplied and the author picked is a chip, and editing a
+  byte of the token un-chips it in the same render that drops the id. Two
+  inherited limits: two labels that sanitize to the same token are one token
+  in a plain-text body, so the first person you list owns every occurrence of
+  it; and a restored draft has no chips (and reports no ids) until the author
+  picks again. No source → no overlay element at all.
 - **`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
@@ -266,7 +286,10 @@ in 0.42.0 (proven by diffing the mounted `outerHTML` against the base commit).
 
 See HANDOFF.md § "Host toolbar seams (0.43.0)" for the grammar, the keyboard
 rules and the threading points, and § "mentionSource on the viewers (0.43.1)"
-for the two viewer props and the annotation field.
+for the two viewer props and the annotation field. § "Mention token chips in
+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).
 
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 

package/components/CommentPopover.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useRef, useCallback, useId } from 'react';
+import React, { useState, useEffect, useMemo, useRef, useCallback, useId } from 'react';
 import { createPortal } from 'react-dom';
 import type { ImageAttachment } from '../types';
 import { AttachmentsButton } from './AttachmentsButton';
@@ -9,9 +9,15 @@ import { hasUnsavedCommentContent } from '../utils/commentContent';
 import { useSkillReferenceAutocomplete } from '../hooks/useSkillReferenceAutocomplete';
 import { HumanOnlySkillNotice, SkillReferenceMenu } from './SkillReferenceMenu';
 import type { SkillReferenceToken } from '../utils/skillReferences';
+import {
+  mentionTokenRanges,
+  mergeTokenRanges,
+  skillTokenRanges,
+  type ComposerTokenRange,
+} from '../utils/composerTokens';
 import { useMentionAutocomplete } from '../hooks/useMentionAutocomplete';
 import { MentionPicker } from './MentionPicker';
-import type { MentionSource } from '../utils/mentions';
+import type { MentionPerson, MentionSource } from '../utils/mentions';
 import {
   hasPrimaryCoarsePointer,
   shouldUseExpandedComposer,
@@ -474,6 +480,19 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     source: mentionSource,
   });
 
+  // The mention half of the composer's highlight layer: present for the whole
+  // life of a mention composer (so the first pick never swaps the textarea
+  // element), null without a source (so the overlay does not exist at all).
+  const mentionChipPeople = mentionAc.mentions;
+  const mentionTokenClassName = mentionSource?.tokenClassName;
+  const mentionChips: ComposerMentionChips | null = useMemo(
+    () =>
+      mentionSource
+        ? { people: mentionChipPeople, tokenClassName: mentionTokenClassName }
+        : null,
+    [mentionSource, mentionChipPeople, mentionTokenClassName],
+  );
+
   const handleSubmit = useCallback(() => {
     const canSubmitEmpty = allowEmptySubmit && initialText.trim().length > 0;
     if (hasUnsavedContent || canSubmitEmpty) {
@@ -684,6 +703,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               sizeClassName="min-h-32 max-h-full"
               skillReferences={skillReferences}
               tokens={skillAc.referenceTokens}
+              mentionChips={mentionChips}
               listboxId={composerListboxId}
               listboxOpen={composerListboxOpen}
               activeOptionId={activeComposerOptionId}
@@ -694,6 +714,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) => {
@@ -848,6 +869,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           sizeClassName="max-h-64 min-h-[4.5rem]"
           skillReferences={skillReferences}
           tokens={skillAc.referenceTokens}
+          mentionChips={mentionChips}
           listboxId={composerListboxId}
           listboxOpen={composerListboxOpen}
           activeOptionId={activeComposerOptionId}
@@ -858,6 +880,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) => {
@@ -991,6 +1014,78 @@ function syncOverlayGutter(
   state.applied = scrollbar;
 }
 
+/**
+ * The default chip look: the theme's primary at a wash, one shade stronger
+ * than a skill reference's so the two token kinds in one overlay read as
+ * siblings rather than the same thing. Deliberately no ring: every class here
+ * is one the package already emitted, so a host build's CSS (and the portable
+ * guide viewer's) is byte-identical to 0.43.2. A host that wants a pill adds
+ * `box-shadow: 0 0 0 Npx <background>` through `tokenClassName` — paint, not
+ * layout, per the metric rule above.
+ */
+const MENTION_CHIP_CLASSES = 'text-primary bg-primary/15 rounded-[3px]';
+
+/**
+ * One token's span in the highlight overlay.
+ *
+ * METRIC RULE, load-bearing for every token kind: a span may change COLOR,
+ * BACKGROUND, BORDER-RADIUS, BOX-SHADOW and TEXT-DECORATION only. Anything
+ * that moves a glyph — padding, margin, border width, font-weight,
+ * letter-spacing, font-size — would shift the overlay's text off the
+ * textarea's own layout and drift the caret away from the painted glyphs. A
+ * pill's breathing room is faked with a paint-only `box-shadow` ring in the
+ * chip's own background color.
+ */
+function renderTokenSpan(
+  range: ComposerTokenRange,
+  text: string,
+  mentionTokenClassName?: string,
+): React.ReactNode {
+  if (range.kind === 'mention') {
+    // `data-mention-token` / `data-mention-kind` are the host's styling hook;
+    // `tokenClassName` is appended verbatim and is the host's to keep
+    // metric-safe (see the rule above).
+    return (
+      <span
+        key={`mention-${range.start}`}
+        data-mention-token={range.person.id}
+        data-mention-kind={range.person.kind}
+        className={`${MENTION_CHIP_CLASSES}${
+          mentionTokenClassName ? ` ${mentionTokenClassName}` : ''
+        }`}
+      >
+        {text}
+      </span>
+    );
+  }
+  // Human-only tokens carry a quiet dotted underline as their inline marker
+  // (text-decoration never affects glyph layout, so overlay alignment is
+  // safe). The accessible explanation lives in HumanOnlySkillNotice below
+  // the textarea — this overlay is aria-hidden.
+  return (
+    <span
+      key={`skill-${range.start}`}
+      data-skill-ref-token={range.skill.entry.name}
+      data-skill-ref-human-only={range.skill.entry.humanOnly ? 'true' : undefined}
+      className={`text-primary bg-primary/10 rounded-[3px] ${
+        range.skill.entry.humanOnly
+          ? 'underline decoration-dotted decoration-primary/60 underline-offset-2'
+          : ''
+      }`}
+    >
+      {text}
+    </span>
+  );
+}
+
+/** The mention half of the highlight layer. Null → no mention source at all. */
+export interface ComposerMentionChips {
+  /** The people whose `@Label` token still survives in the text. */
+  readonly people: readonly MentionPerson[];
+  /** Host class appended to each chip (see `MentionSource.tokenClassName`). */
+  readonly tokenClassName?: string;
+}
+
 interface ComposerTextareaProps {
   value: string;
   onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
@@ -1003,8 +1098,14 @@ interface ComposerTextareaProps {
   textareaRef: (el: HTMLTextAreaElement | null) => void;
   /** Positioned skill-reference occurrences to highlight. */
   tokens: SkillReferenceToken[];
-  /** Off → render the plain pre-feature textarea, byte-for-byte. */
+  /** Off → no skill-reference contribution to the highlight layer. */
   skillReferences: boolean;
+  /**
+   * The mention contribution, or null with no `mentionSource`. Present (even
+   * with nobody tagged yet) it turns the overlay on, so the first pick paints
+   * a chip without swapping the textarea for a different element.
+   */
+  mentionChips: ComposerMentionChips | null;
   /** ARIA relationship to the skill-reference listbox. */
   listboxId: string;
   listboxOpen: boolean;
@@ -1012,13 +1113,15 @@ interface ComposerTextareaProps {
 }
 
 /**
- * The composer's textarea. With `skillReferences` off this is exactly the
- * pre-feature `<textarea>`; with it on, inserted skill-reference tokens are
- * highlighted via a mirrored, aria-hidden overlay rendered BEHIND a
- * transparent-text textarea (a textarea cannot style substrings). The overlay
- * shares the exact font/padding/wrapping metrics and mirrors scroll position,
- * and token spans change ONLY color/background (never font or weight), so the
- * glyphs the browser lays out in the textarea and the glyphs the overlay
+ * The composer's textarea. With NEITHER token source active this is exactly
+ * the pre-feature `<textarea>`; with either one on, its tokens are painted by
+ * a mirrored, aria-hidden overlay rendered BEHIND a transparent-text textarea
+ * (a textarea cannot style substrings). ONE overlay serves both sources: two
+ * mirrored layers could never stay pixel-aligned with each other, and only
+ * one of them could own the scroll sync. The overlay shares the exact
+ * font/padding/wrapping metrics and mirrors scroll position, and token spans
+ * obey the metric rule on `renderTokenSpan` (paint only, never layout), so
+ * the glyphs the browser lays out in the textarea and the glyphs the overlay
  * paints coincide. During IME composition the overlay hides and the textarea
  * text becomes visible again (`.pn-ref-composing`), keeping native
  * composition rendering (underlines, candidate highlights) intact.
@@ -1033,6 +1136,7 @@ const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
   textareaRef,
   tokens,
   skillReferences,
+  mentionChips,
   listboxId,
   listboxOpen,
   activeOptionId,
@@ -1061,6 +1165,23 @@ const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
     [textareaRef],
   );
 
+  // The overlay exists while EITHER source is active. `mentionChips` turns it
+  // on for the whole life of a mention composer, not only once somebody is
+  // tagged, so a pick never swaps the textarea element under the caret.
+  const mentionPeople = mentionChips?.people;
+  const highlight = skillReferences || mentionChips !== null;
+
+  // The one list of spans the overlay paints, from every active source.
+  // Skill references are the earlier group, so they win a byte both claim.
+  const ranges = useMemo(
+    () =>
+      mergeTokenRanges(value, [
+        skillReferences ? skillTokenRanges(tokens) : [],
+        mentionPeople ? mentionTokenRanges(value, mentionPeople) : [],
+      ]),
+    [value, tokens, skillReferences, mentionPeople],
+  );
+
   // Keep the mirror aligned when the value changes without a scroll event
   // (e.g. programmatic insertion moving the caret into a scrolled region).
   useEffect(() => {
@@ -1078,9 +1199,9 @@ const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
     });
     observer.observe(el);
     return () => observer.disconnect();
-  }, [skillReferences, syncScroll]);
+  }, [highlight, syncScroll]);
 
-  if (!skillReferences) {
+  if (!highlight) {
     return (
       <textarea
         data-pn-mobile-editable="true"
@@ -1103,29 +1224,13 @@ const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
 
   const segments: React.ReactNode[] = [];
   let pos = 0;
-  tokens.forEach((token, i) => {
-    if (token.start < pos || token.end > value.length) return; // stale tokens for a different value
-    if (token.start > pos) segments.push(value.slice(pos, token.start));
-    // Human-only tokens carry a quiet dotted underline as their inline marker
-    // (text-decoration never affects glyph layout, so overlay alignment is
-    // safe). The accessible explanation lives in HumanOnlySkillNotice below
-    // the textarea — this overlay is aria-hidden.
+  for (const range of ranges) {
+    if (range.start > pos) segments.push(value.slice(pos, range.start));
     segments.push(
-      <span
-        key={`${token.start}-${i}`}
-        data-skill-ref-token={token.entry.name}
-        data-skill-ref-human-only={token.entry.humanOnly ? 'true' : undefined}
-        className={`text-primary bg-primary/10 rounded-[3px] ${
-          token.entry.humanOnly
-            ? 'underline decoration-dotted decoration-primary/60 underline-offset-2'
-            : ''
-        }`}
-      >
-        {value.slice(token.start, token.end)}
-      </span>,
+      renderTokenSpan(range, value.slice(range.start, range.end), mentionChips?.tokenClassName),
     );
-    pos = token.end;
-  });
+    pos = range.end;
+  }
   segments.push(value.slice(pos));
 
   return (
@@ -1133,7 +1238,10 @@ const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
       <div
         ref={overlayRef}
         aria-hidden="true"
-        data-skill-ref-overlay="true"
+        // Names the SKILL-reference layer, so a skill composer's overlay is
+        // byte-identical to the one it rendered before mentions existed; a
+        // mentions-only overlay is found by its mirror attribute below.
+        data-skill-ref-overlay={skillReferences ? 'true' : undefined}
         data-pn-mobile-editable-mirror="true"
         className={`${COMPOSER_TEXT_CLASSES} ${sizeClassName} pointer-events-none absolute inset-0 overflow-hidden whitespace-pre-wrap break-words`}
         style={composing ? { visibility: 'hidden' } : undefined}

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/hooks/useMentionAutocomplete.ts

@@ -15,6 +15,7 @@ export interface MentionMenuState {
   items: readonly MentionPerson[];
   /** Shown as one non-selectable row when `items` is empty. */
   emptyNotice: string | null;
+  heading: string | null;
   /** Explicitly activated row, or null — the menu opens with NOTHING active. */
   activeIndex: number | null;
   /** Measured textarea rect the portaled picker is placed from. */
@@ -33,6 +34,12 @@ export interface UseMentionAutocompleteResult {
   select: (index: number) => void;
   /** The ids whose readable token still survives in the text. */
   mentionIds: readonly string[];
+  /**
+   * The same survivors as people, for a caller that needs their labels — the
+   * composer paints each surviving token as a chip. Frozen-empty with no
+   * source, the same treatment `mentionIds` gets.
+   */
+  mentions: readonly MentionPerson[];
 }
 
 /**
@@ -92,6 +99,7 @@ export function useMentionAutocomplete(options: {
     () => (enabled ? survivors.map((p) => p.id) : NO_IDS),
     [enabled, survivors],
   );
+  const mentions = enabled ? survivors : NO_PEOPLE;
 
   const onMentionsChange = source?.onMentionsChange;
   const mentionsKey = mentionIds.join('\u0000');
@@ -112,6 +120,7 @@ export function useMentionAutocomplete(options: {
   );
 
   const emptyNotice = source?.emptyNotice ?? null;
+  const heading = source?.heading ?? null;
   const open =
     trigger !== null
     && trigger.from !== dismissedStart
@@ -236,11 +245,12 @@ export function useMentionAutocomplete(options: {
 
   return {
     menu: open && trigger
-      ? { items, emptyNotice, activeIndex: boundedActive, anchor, query: trigger.query }
+      ? { items, emptyNotice, heading, activeIndex: boundedActive, anchor, query: trigger.query }
       : null,
     onKeyDown,
     onSelect: readCaret,
     select,
     mentionIds,
+    mentions,
   };
 }

package/package.json

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