feat(ui): mention tokens render as chips in the comment composer; ui 0.44.0

[backnotprop]

Problem

0.43.0–0.43.2 gave the comment composer an @ picker, but the token it inserts is then plain text in the textarea. A tag therefore looks like three different things: a styled row in the picker, bare prose while you type, and a rendered mention in the host's posted comment. The host asked for the middle one to match.

Approach — and why one overlay

ComposerTextarea already implements exactly the right technique for skill references: with the feature off it renders the plain pre-feature <textarea>; with it on, a mirrored aria-hidden overlay sits behind a transparent-text textarea, sharing font/padding/wrapping metrics, mirroring scroll, and hiding during IME composition (.pn-ref-composing).

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 that overlay became a token highlight layer fed by a merged list of ranges from one or more sources, turning on when either source is active.

The range computation moved out of the render loop into a pure module, packages/ui/utils/composerTokens.ts (no DOM, no styling, no React):

• skillTokenRanges(tokens) — today's positioned occurrences, unchanged.
• mentionTokenRanges(text, people) — every occurrence of each surviving person's @Label token, built on the mention id model (mentionToken / survivingMentions), never a regex over arbitrary @words.
• mergeTokenRanges(text, groups) — groups in priority order; drops ranges outside [0, text.length) and empty/inverted ones, then earlier start wins, longer wins at the same start, earlier group wins at the same start and length, and anything beginning inside a kept range is dropped. Nothing nests.

With a single skill source this reproduces the pre-refactor loop exactly. The component keeps the Tailwind classes and data-* attributes in renderTokenSpan, both so the class scanner still sees them and so the metric rule is read beside the classes it governs.

Change

• Chips. A picked person's surviving token renders as <span data-mention-token="<person id>" data-mention-kind="user|agent">@Marcus Chen</span> inside the existing overlay. Default look: text-primary bg-primary/15 rounded-[3px] — the skill-reference treatment one shade stronger, so the two token kinds in one overlay read as siblings.
• Metric rule (documented on renderTokenSpan, on tokenClassName, in HANDOFF and README): 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 drift the caret off the painted text. A pill's breathing room is faked with box-shadow: 0 0 0 Npx <background>.
• MentionSource.tokenClassName?: string — appended verbatim to each chip, with the metric rule stated as the host's responsibility.
• useMentionAutocomplete also returns the surviving mentions (people, not just ids); same frozen empty array as mentionIds with no source.
• mentionChips is present 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.
• Both composer layouts (popover and expanded/dialog) get it through the one component. Viewer / HtmlViewer needed no change — they already forward mentionSource (0.43.1); pinned by test.
• Two inherited limitations, documented rather than papered over: two people whose labels sanitize to the same token are indistinguishable in a plain-text body (first listed owns every occurrence, never throws), and a restored draft has no chips until the author picks again — the same reason onMentionsChange reports [] for a restored draft today.

No-op guarantee

The same components were mounted on origin/main and on this branch in one harness and their outerHTML diffed:

config	popover	overlay	addEventListener	setTimeout
no mentionSource, no skillReferences	3192 B, identical	none on either side	287 = 287	1 = 1
skillReferences only	4821 B, identical	634 B, identical	150 = 150	1 = 1
mentionSource (host-only)	3192 → 3624 B	none → 302 B	148 → 149	1 = 1

The one extra listener on a mention composer is the textarea's scroll — the one that mirrors the layer, which a skill composer has always paid. data-skill-ref-overlay="true" is written only when skillReferences is on, so a skill composer's overlay keeps its exact attribute list; a mentions-only overlay is found by data-pn-mobile-editable-mirror.

The default chip deliberately reuses classes the package already emitted (an earlier draft added a box-shadow ring and grew the generated CSS by 632 B). Consequence: the portable guide viewer's build is byte-identical — viewer.48O72WuZ.js / viewer.BZXDoJTm.css and their SRI unchanged — check:manifest reports in sync, and @plannotator/core is untouched at 0.25.5. @plannotator/ui 0.44.0 publishes alone.

Tests

• packages/ui/utils/composerTokens.test.ts — 16, DOM-free: single / multiple / adjacent tokens, start and end of text, a deleted token, a one-byte edit un-chipping, duplicate labels, a label that sanitizes to nothing, longest-wins over a prefix label, skill+mention coexistence, both overlap directions, stale/empty/inverted ranges, and the single-skill-source parity pin.
• packages/ui/components/CommentPopover.mentionChips.test.tsx — 11, DOM-gated, added to the DOM_TESTS step in .github/workflows/test.yml (scripts/dom-test-allowlist.test.ts passes): no overlay without a source, overlay on before the first pick, one chip whose text is exactly the token, two picks in document order, a deleted character un-chipping and dropping the id, skill + mention in ONE layer, tokenClassName appended not replacing, composition hiding the overlay, the expanded/dialog composer, Mod+Enter still carrying the ids, and a viewer-shaped source.

Counts (macOS, this branch):

run	result
bun test packages/ui packages/editor packages/review-editor	1582 pass / 0 fail / 1111 skip (2693 across 298 files)
same with DOM_TESTS=1	2678 pass / 5 fail (2684 across 298 files) — the known pre-existing set: 4× DocBadges open-in placement, 1× artifactContentProxyUrl
bun test (full)	4949 pass / 0 fail / 1159 skip (6108 across 530 files)
bun run typecheck	clean

Browser evidence

Headless Chromium over a throwaway Vite harness (scratchpad, not committed). Typed Nice catch @ma, picked Marcus from the real picker, kept typing, then measured the chip's rect against the textarea's own glyph geometry for that token (measured independently through a metrics-cloned mirror + Range.getClientRects):

scenario	dx	dy	dw	caret vs span end
420px	0.000	0.000	0.000	0.016 px
1200px	0.000	0.000	0.000	0.016 px
after a wrap (3 lines above the token)	0.000	0.000	0.000	0.016 px
after a scroll (scrollTop 40)	0.000	0.000	0.000	0.016 px

Computed style asserted paint-only in every scenario (padding: 0px, margin: 0px, border-width: 0px, letter-spacing: normal). Screenshots and the raw results are in the scratchpad: evidence/chip-wide.png, chip-narrow.png, chip-wrapped.png, chip-scrolled.png, chip-proof.json.

Deviations

• No box-shadow ring in the default chip. The brief offered it as the sanctioned way to fake pill padding. It worked and measured clean, but it was the one new Tailwind class in the change and it moved the portable viewer's CSS hash (+632 B), which would have forced a guide-viewer-manifest.ts regeneration and a core content change. Dropping it keeps core untouched and the viewer build byte-identical; the technique is documented for hosts, and tokenClassName is the way to a pill.
• The chips-wt worktree is left in place for review; chips-base has been removed.