@plannotator/ui 0.41.2 → 0.43.0

package/components/MentionPicker.tsx

@@ -0,0 +1,110 @@
+import { createPortal } from 'react-dom';
+import type { MentionPerson } from '../utils/mentions';
+
+/**
+ * The `@` menu over the comment composer's textarea.
+ *
+ * NOTHING IS PRESELECTED (`active === null` until the person arrows into the
+ * list), the same rule `useSkillReferenceAutocomplete` keeps for `/` and `$`:
+ * until then Enter and Tab mean what they always meant in a comment box.
+ *
+ * PORTALED AND FIXED, not absolute inside the composer: the popover clips its
+ * own box and the expanded dialog scrolls, so a menu positioned inside the
+ * textarea's wrapper is cut off at the card's edge. It is placed from the
+ * textarea's measured rect instead — above it by default, below when the
+ * composer sits too close to the top of the window for the menu to open
+ * upward.
+ */
+
+export interface MentionAnchor {
+  readonly top: number;
+  readonly bottom: number;
+  readonly left: number;
+  readonly width: number;
+}
+
+/** The menu's own height cap (max-h-48 = 12rem), in px. */
+const MENU_MAX_PX = 192;
+const MENU_GAP_PX = 4;
+
+/** Measure the composer textarea for {@link MentionPicker}. Null closes the menu. */
+export function mentionAnchorOf(element: HTMLElement | null): MentionAnchor | null {
+  if (element === null) return null;
+  const rect = element.getBoundingClientRect();
+  return { top: rect.top, bottom: rect.bottom, left: rect.left, width: rect.width };
+}
+
+export function MentionPicker({
+  id,
+  people,
+  emptyNotice,
+  active,
+  anchor,
+  onPick,
+  onHover,
+}: {
+  /** Id referenced by the focused textarea's aria-controls attribute. */
+  readonly id?: string;
+  readonly people: readonly MentionPerson[];
+  /** Shown as one non-selectable row when `people` is empty. */
+  readonly emptyNotice?: string | null;
+  /** Index of the arrow-focused row, or null for "nothing preselected". */
+  readonly active: number | null;
+  readonly anchor: MentionAnchor | null;
+  readonly onPick: (person: MentionPerson) => void;
+  readonly onHover: (index: number) => void;
+}) {
+  if (anchor === null || typeof document === 'undefined') return null;
+  if (people.length === 0 && !emptyNotice) return null;
+  const above = anchor.top >= MENU_MAX_PX + MENU_GAP_PX;
+  const style = above
+    ? { bottom: window.innerHeight - anchor.top + MENU_GAP_PX }
+    : { top: anchor.bottom + MENU_GAP_PX };
+  return createPortal(
+    <div
+      id={id}
+      role="listbox"
+      aria-label="People"
+      data-mention-picker
+      data-placement={above ? 'above' : 'below'}
+      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"
+    >
+      {people.length === 0 ? (
+        <p data-mention-empty className="px-2 py-1 text-[11px] text-muted-foreground">
+          {emptyNotice}
+        </p>
+      ) : (
+        people.map((person, index) => (
+          <button
+            key={person.id}
+            type="button"
+            role="option"
+            id={id ? `${id}-option-${index}` : undefined}
+            aria-selected={active === index}
+            data-mention-option={person.id}
+            // The pick must run before the textarea loses focus, or the blur
+            // would close the menu and swallow the click.
+            onMouseDown={(event) => {
+              event.preventDefault();
+              onPick(person);
+            }}
+            onMouseEnter={() => onHover(index)}
+            className={`flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-1 text-left text-xs transition-colors ${
+              active === index ? 'bg-muted text-foreground' : 'text-foreground/85 hover:bg-muted/60'
+            }`}
+          >
+            <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.
+              <span className="min-w-0 max-w-[44%] shrink-0 truncate text-[10px] text-muted-foreground">
+                {person.detail}
+              </span>
+            )}
+          </button>
+        ))
+      )}
+    </div>,
+    document.body,
+  );
+}

package/components/SelectionActionsDropdown.tsx

@@ -0,0 +1,173 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import type { SelectionAction } from '../utils/selectionActions';
+
+/**
+ * The host-actions dropdown: the same context-menu shape `QuickLabelDropdown`
+ * draws (single column, accent bar, full-width rows) and the same floating
+ * placement `FloatingQuickLabelPicker` computes, opened directly below the
+ * toolbar's wand button.
+ *
+ * Keyboard here is arrows + Enter + Escape rather than the quick labels'
+ * digit keys: a host's list is not a fixed ten with memorized numbers.
+ * Nothing is preselected until the first arrow, so a stray Enter while the
+ * dropdown is open never invokes a host command.
+ */
+
+const PICKER_WIDTH = 224;
+const GAP = 6;
+const VIEWPORT_PADDING = 12;
+/** Room the dropdown wants below the anchor before it flips above. */
+const FLIP_THRESHOLD = 220;
+
+function computePosition(anchorEl: HTMLElement): { top: number; left: number; flipAbove: boolean } {
+  const rect = anchorEl.getBoundingClientRect();
+  const flipAbove = window.innerHeight - rect.bottom < FLIP_THRESHOLD;
+  const top = flipAbove ? rect.top - GAP : rect.bottom + GAP;
+  let left = rect.left + rect.width / 2 - PICKER_WIDTH / 2;
+  left = Math.max(
+    VIEWPORT_PADDING,
+    Math.min(left, window.innerWidth - PICKER_WIDTH - VIEWPORT_PADDING),
+  );
+  return { top, left, flipAbove };
+}
+
+export const SelectionActionsDropdown: React.FC<{
+  actions: SelectionAction[];
+  activeIndex: number | null;
+  onSelect: (action: SelectionAction) => void;
+  onHover: (index: number) => void;
+}> = ({ actions, activeIndex, onSelect, onHover }) => (
+  <div className="py-1" onMouseDown={(e) => e.stopPropagation()}>
+    {actions.map((action, index) => (
+      <button
+        key={action.id}
+        type="button"
+        role="option"
+        aria-selected={activeIndex === index}
+        data-selection-action={action.id}
+        onClick={() => onSelect(action)}
+        onMouseEnter={() => onHover(index)}
+        className={`group w-full flex items-center gap-2 px-2 py-[5px] text-left transition-colors ${
+          activeIndex === index ? 'bg-muted' : 'hover:bg-muted/60 active:bg-muted'
+        }`}
+      >
+        {action.icon ? (
+          <span className="flex-shrink-0 w-4 h-4 flex items-center justify-center text-muted-foreground">
+            {action.icon}
+          </span>
+        ) : (
+          <span className="w-[3px] self-stretch rounded-full flex-shrink-0 bg-primary/70" />
+        )}
+        <span className="min-w-0 flex-1">
+          <span className="block text-[11px] leading-tight text-foreground/85 group-hover:text-foreground truncate">
+            {action.label}
+          </span>
+          {action.detail && (
+            <span className="block text-[9px] leading-tight text-muted-foreground/70 truncate">
+              {action.detail}
+            </span>
+          )}
+        </span>
+      </button>
+    ))}
+  </div>
+);
+
+export const FloatingSelectionActionsPicker: React.FC<{
+  anchorEl: HTMLElement;
+  actions: SelectionAction[];
+  onSelect: (action: SelectionAction) => void;
+  onDismiss: () => void;
+}> = ({ anchorEl, actions, onSelect, onDismiss }) => {
+  const [position, setPosition] = useState<{ top: number; left: number; flipAbove: boolean } | null>(null);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const update = () => setPosition(computePosition(anchorEl));
+    update();
+    window.addEventListener('scroll', update, true);
+    window.addEventListener('resize', update);
+    return () => {
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+    };
+  }, [anchorEl]);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.isComposing) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onDismiss();
+        return;
+      }
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+        e.preventDefault();
+        setActiveIndex((prev) => {
+          if (actions.length === 0) return null;
+          if (prev === null) return e.key === 'ArrowDown' ? 0 : actions.length - 1;
+          return e.key === 'ArrowDown'
+            ? (prev + 1) % actions.length
+            : (prev - 1 + actions.length) % actions.length;
+        });
+        return;
+      }
+      if (e.key === 'Enter') {
+        // Nothing preselected: Enter before the first arrow is not aimed here.
+        if (activeIndex === null) return;
+        e.preventDefault();
+        const action = actions[activeIndex];
+        if (action) onSelect(action);
+      }
+    };
+    window.addEventListener('keydown', handleKeyDown, true);
+    return () => window.removeEventListener('keydown', handleKeyDown, true);
+  }, [actions, activeIndex, onDismiss, onSelect]);
+
+  // Click outside dismisses. Deferred capture-phase registration, so the click
+  // that opened the dropdown does not immediately close it.
+  useEffect(() => {
+    const handlePointerDown = (e: PointerEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) onDismiss();
+    };
+    const timer = setTimeout(() => {
+      document.addEventListener('pointerdown', handlePointerDown, true);
+    }, 0);
+    return () => {
+      clearTimeout(timer);
+      document.removeEventListener('pointerdown', handlePointerDown, true);
+    };
+  }, [onDismiss]);
+
+  if (!position) return null;
+
+  return createPortal(
+    <div
+      ref={ref}
+      role="listbox"
+      aria-label="Actions"
+      data-selection-actions-picker
+      data-floating-picker="true"
+      className="fixed z-[100]"
+      style={{
+        top: position.top,
+        left: position.left,
+        width: PICKER_WIDTH,
+        ...(position.flipAbove ? { transform: 'translateY(-100%)' } : {}),
+      }}
+      onMouseDown={(e) => e.stopPropagation()}
+    >
+      <div className="bg-popover border border-border/60 rounded-lg shadow-xl overflow-hidden">
+        <SelectionActionsDropdown
+          actions={actions}
+          activeIndex={activeIndex}
+          onSelect={onSelect}
+          onHover={setActiveIndex}
+        />
+      </div>
+    </div>,
+    document.body,
+  );
+};

package/components/Viewer.tsx

@@ -59,6 +59,7 @@ import { DiagramBlockPending } from './diagram/DiagramPending';
 import { isGraphvizLanguage, isMermaidLanguage } from './diagramLanguages';
 import { getIdentity } from '../utils/identity';
 import { type QuickLabel } from '../utils/quickLabels';
+import type { SelectionAction } from '../utils/selectionActions';
 import { DocBadges, type DocBadgesProps, type LinkedDocBadgeInfo } from './DocBadges';
 import { PinpointOverlay } from './PinpointOverlay';
 import { usePinpoint } from '../hooks/usePinpoint';
@@ -91,6 +92,18 @@ export interface ViewerAnnotationHeaderConfig {
 
 /** Public properties for the Markdown document Viewer. */
 export interface ViewerProps {
+  /**
+   * Opt-in host capability, passed straight through to the selection
+   * toolbars: the host's own commands for the current selection, rendered as
+   * one wand button that opens the package's dropdown. Absent → unchanged.
+   */
+  selectionActions?: SelectionAction[];
+  /**
+   * 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;
   blocks: Block[];
   markdown: string;
   frontmatter?: Frontmatter | null;
@@ -360,6 +373,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   mode,
   inputMethod = 'drag',
   taterMode,
+  selectionActions,
+  quickLabels,
   globalAttachments = [],
   onAddGlobalAttachment,
   onRemoveGlobalAttachment,
@@ -1296,6 +1311,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               onClose={handleToolbarClose}
               onRequestComment={handleRequestComment}
               onQuickLabel={handleQuickLabel}
+              selectionActions={selectionActions}
+              quickLabels={quickLabels}
               copyText={toolbarState.selectionText}
               hideCopyButton={!isTouchDevice}
               closeOnScrollOut
@@ -1351,6 +1368,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 onClose={handleCodeBlockToolbarClose}
                 onRequestComment={handleCodeBlockRequestComment}
                 onQuickLabel={handleCodeBlockQuickLabel}
+                selectionActions={selectionActions}
+                quickLabels={quickLabels}
                 isExiting={isCodeBlockToolbarExiting}
                 onMouseEnter={() => {
                   if (hoverTimeoutRef.current) {

package/components/html-viewer/HtmlViewer.tsx

@@ -24,6 +24,7 @@ import {
   type VimHudCommand,
 } from "../../utils/vimHud";
 import { AnnotationToolbar } from "../AnnotationToolbar";
+import type { SelectionAction } from "../../utils/selectionActions";
 import { AttachmentsButton } from "../AttachmentsButton";
 import {
   CommentPopover,
@@ -265,6 +266,10 @@ export interface HtmlViewerProps {
    *  to the bridge so the in-page toggle stops at the same number. Default
    *  16 (the package cap); absent leaves every message unchanged. */
   maxAdditionalTargets?: number;
+  /** Opt-in host capability, passed straight through to the selection
+   *  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[];
   /** 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. */
@@ -352,6 +357,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       readOnly = false,
       onUnanchoredChange,
       maxAdditionalTargets,
+      selectionActions,
       scrollBehavior,
       title = "HTML Plan Viewer",
       bridgeScriptUrl,
@@ -1202,6 +1208,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               // wrapper filters by id as defense in depth, so no present or
               // future toolbar path can emit an arbitrary label here.
               commentOnly
+              selectionActions={selectionActions}
               onQuickLabel={(label) => {
                 if (label.id === THUMBS_UP_LABEL.id) hook.handleQuickLabel(label);
               }}

package/hooks/useLinkedDoc.ts

@@ -8,7 +8,8 @@
 
 import { useState, useCallback, useRef } from "react";
 import { normalizeBrowserPath } from "@plannotator/core/browser-paths";
-import type { Annotation, ImageAttachment } from "../types";
+import { isDiagramRenderKind } from "@plannotator/core/annotatable";
+import type { Annotation, DocumentRenderAs, ImageAttachment } from "../types";
 import type { ViewerHandle } from "../components/Viewer";
 import type { SidebarTab } from "./useSidebar";
 import type { SourceSaveCapability } from "@plannotator/core/source-save";
@@ -18,7 +19,7 @@ export interface LinkedDocLoadData {
   markdown?: string;
   filepath?: string;
   isConverted?: boolean;
-  renderAs?: 'markdown' | 'html';
+  renderAs?: DocumentRenderAs;
   rawHtml?: string;
   shareHtml?: string;
   sourceSave?: SourceSaveCapability;
@@ -72,10 +73,10 @@ export interface UseLinkedDocOptions {
   setGlobalAttachments: (att: ImageAttachment[]) => void;
   /** Current render mode + raw HTML of the base document. An HTML linked/folder file
    *  swaps these to render raw; back() restores the base values from this snapshot. */
-  renderAs: 'markdown' | 'html';
+  renderAs: DocumentRenderAs;
   rawHtml: string;
   shareHtml: string;
-  setRenderAs: (r: 'markdown' | 'html') => void;
+  setRenderAs: (r: DocumentRenderAs) => void;
   setRawHtml: (html: string) => void;
   setShareHtml: (html: string) => void;
   viewerRef: React.RefObject<ViewerHandle | null>;
@@ -105,7 +106,7 @@ interface SavedPlanState {
   annotations: Annotation[];
   selectedAnnotationId: string | null;
   globalAttachments: ImageAttachment[];
-  renderAs: 'markdown' | 'html';
+  renderAs: DocumentRenderAs;
   rawHtml: string;
   shareHtml: string;
 }
@@ -382,7 +383,11 @@ export function useLinkedDoc(options: UseLinkedDocOptions): UseLinkedDocReturn {
     // Swap to linked doc — an .html file renders raw (HtmlViewer), a markdown
     // file parses to blocks (Viewer). Drive renderAs/rawHtml per file so the
     // App's renderAs === 'html' ? HtmlViewer : Viewer switch flips automatically.
-    const docRenderAs = data.renderAs === 'html' ? 'html' : 'markdown';
+    // A diagram source (.mmd/.dot) keeps the markdown state path — the raw
+    // text is the document body — but names its engine so the App renders it
+    // as one diagram instead of parsing it as markdown.
+    const docRenderAs: DocumentRenderAs =
+      data.renderAs === 'html' ? 'html' : isDiagramRenderKind(data.renderAs) ? data.renderAs : 'markdown';
     const hostMarkdown = docRenderAs === 'html' || !notifyDocumentLoaded ? undefined : onDocumentLoaded?.(data);
     const nextMarkdown = notifyDocumentLoaded
       ? hostMarkdown ?? cached?.markdown ?? data.markdown ?? ''

package/hooks/useMentionAutocomplete.ts

@@ -0,0 +1,246 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type React from 'react';
+import {
+  applyMentionPick,
+  mentionMatches,
+  mentionTrigger,
+  survivingMentions,
+  type MentionPerson,
+  type MentionSource,
+  type MentionTrigger,
+} from '../utils/mentions';
+import { mentionAnchorOf, type MentionAnchor } from '../components/MentionPicker';
+
+export interface MentionMenuState {
+  items: readonly MentionPerson[];
+  /** Shown as one non-selectable row when `items` is empty. */
+  emptyNotice: 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. */
+  anchor: MentionAnchor | null;
+  query: string;
+}
+
+export interface UseMentionAutocompleteResult {
+  /** Open menu state, or null. Render MentionPicker from this. */
+  menu: MentionMenuState | null;
+  /** Call in the textarea's onKeyDown; true means the event was consumed. */
+  onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => boolean;
+  /** Call from the textarea's onSelect and onChange (every caret move + input). */
+  onSelect: () => void;
+  /** Insert the given menu item at the active trigger. */
+  select: (index: number) => void;
+  /** The ids whose readable token still survives in the text. */
+  mentionIds: readonly string[];
+}
+
+/**
+ * `@` mention autocomplete for a comment textarea, driven entirely by a
+ * host-supplied `MentionSource`. With no source every path here is inert:
+ * no listener is registered, no menu state is ever open, `mentionIds` stays
+ * the same frozen empty array, and the composer renders and behaves exactly
+ * as it did before the prop existed.
+ *
+ * NO-PRESELECTION INVARIANT (shared with `useSkillReferenceAutocomplete`):
+ * the menu opens with no row active, and while no row is active Enter and
+ * Tab behave exactly as if the menu were not open — a body that ends
+ * "ping @" plus Enter is still a newline. A row becomes active only through
+ * explicit keyboard navigation (ArrowDown from none lands on the FIRST row,
+ * ArrowUp from none on the LAST) or a pointer click, which inserts directly.
+ *
+ * DELIBERATE DIFFERENCE from the `/` and `$` skill trigger: the arrows engage
+ * this menu even on a BARE trigger (`@` with no query typed). `$` and `/` are
+ * ordinary prose characters, so their menu must yield the arrows back to
+ * caret navigation; `@` at a word boundary is an unambiguous tag gesture, and
+ * typing `@` then ArrowDown is how the host's own reply box already behaves.
+ * Escape closes the menu whenever it is visible, for the same reason.
+ */
+const NO_IDS: readonly string[] = Object.freeze([]);
+const NO_PEOPLE: readonly MentionPerson[] = Object.freeze([]);
+
+export function useMentionAutocomplete(options: {
+  text: string;
+  setText: (text: string) => void;
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+  source?: MentionSource;
+}): UseMentionAutocompleteResult {
+  const { text, setText, textareaRef, source } = options;
+  const enabled = !!source;
+  const [caret, setCaret] = useState<number | null>(null);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [tagged, setTagged] = useState<readonly MentionPerson[]>(NO_PEOPLE);
+  const [anchor, setAnchor] = useState<MentionAnchor | null>(null);
+  // Escape dismisses the menu for the trigger it was open on; the same trigger
+  // does not reopen until the caret leaves it.
+  const [dismissedStart, setDismissedStart] = useState<number | null>(null);
+
+  const trigger: MentionTrigger | null = useMemo(() => {
+    if (!enabled || caret === null) return null;
+    return mentionTrigger(text, caret);
+  }, [enabled, text, caret]);
+
+  // A token the author deleted stops being a tag, so the body and the
+  // reported ids never disagree about who was named.
+  const survivors = useMemo(() => survivingMentions(text, tagged), [text, tagged]);
+  useEffect(() => {
+    if (survivors.length !== tagged.length) setTagged(survivors);
+  }, [survivors, tagged]);
+
+  const taggedIds = useMemo(() => new Set(survivors.map((p) => p.id)), [survivors]);
+  const mentionIds = useMemo(
+    () => (enabled ? survivors.map((p) => p.id) : NO_IDS),
+    [enabled, survivors],
+  );
+
+  const onMentionsChange = source?.onMentionsChange;
+  const mentionsKey = mentionIds.join('\u0000');
+  const lastReported = useRef<string | null>(null);
+  useEffect(() => {
+    if (!onMentionsChange) return;
+    if (lastReported.current === mentionsKey) return;
+    lastReported.current = mentionsKey;
+    onMentionsChange(mentionIds);
+    // mentionIds is keyed by mentionsKey; re-running on identity alone would
+    // report the same ids on every render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mentionsKey, onMentionsChange]);
+
+  const items = useMemo(
+    () => (source && trigger ? mentionMatches(source.people, trigger, taggedIds) : []),
+    [source, trigger, taggedIds],
+  );
+
+  const emptyNotice = source?.emptyNotice ?? null;
+  const open =
+    trigger !== null
+    && trigger.from !== dismissedStart
+    && (items.length > 0 || !!emptyNotice);
+
+  // A new trigger start clears the dismissal memory.
+  const triggerStart = trigger?.from ?? null;
+  const lastTriggerStart = useRef<number | null>(null);
+  useEffect(() => {
+    if (triggerStart !== lastTriggerStart.current) {
+      lastTriggerStart.current = triggerStart;
+      setDismissedStart(null);
+    }
+  }, [triggerStart]);
+
+  // Any trigger change — a new one, or more typing re-filtering the same one —
+  // disarms the active row, so an activation always refers to the exact list
+  // the user was looking at.
+  const triggerQuery = trigger?.query ?? null;
+  useEffect(() => {
+    setActiveIndex(null);
+  }, [triggerStart, triggerQuery]);
+
+  // Measure the composer while the menu is open (and follow scroll/resize).
+  useEffect(() => {
+    if (!open) {
+      setAnchor(null);
+      return;
+    }
+    const measure = () => setAnchor(mentionAnchorOf(textareaRef.current));
+    measure();
+    window.addEventListener('scroll', measure, true);
+    window.addEventListener('resize', measure);
+    return () => {
+      window.removeEventListener('scroll', measure, true);
+      window.removeEventListener('resize', measure);
+    };
+  }, [open, textareaRef, triggerStart, triggerQuery]);
+
+  const boundedActive =
+    activeIndex !== null && activeIndex >= 0 && activeIndex < items.length ? activeIndex : null;
+
+  const readCaret = useCallback(() => {
+    if (!enabled) return;
+    const el = textareaRef.current;
+    setCaret(el ? el.selectionStart : null);
+  }, [enabled, textareaRef]);
+
+  const select = useCallback(
+    (index: number) => {
+      const el = textareaRef.current;
+      if (!source || !trigger) return;
+      const person = items[index];
+      if (!person) return;
+      if (person.canOpen === false && source.onPickBlocked) {
+        // Nothing is inserted: the host owns the no-access affordance.
+        source.onPickBlocked(person);
+        setActiveIndex(null);
+        setDismissedStart(trigger.from);
+        return;
+      }
+      const result = applyMentionPick(text, trigger, person);
+      setText(result.text);
+      setCaret(result.caret);
+      setTagged((prev) => (prev.some((p) => p.id === person.id) ? prev : [...prev, person]));
+      setActiveIndex(null);
+      // Close deterministically: the DOM caret only moves in the timer below,
+      // and React's select plugin can re-read the STALE caret before then,
+      // transiently reopening the menu on the just-replaced query.
+      setDismissedStart(trigger.from);
+      setTimeout(() => {
+        if (!el || !el.isConnected) return;
+        el.focus();
+        el.setSelectionRange(result.caret, result.caret);
+      }, 0);
+    },
+    [items, setText, source, text, textareaRef, trigger],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>): boolean => {
+      if (!open || !trigger) return false;
+      // Never consume keys mid-composition: for Pinyin, Telex and friends the
+      // composition buffer is ASCII, so Enter can mean "commit this candidate".
+      if (e.nativeEvent.isComposing) return false;
+      if (e.metaKey || e.ctrlKey || e.altKey) return false;
+      switch (e.key) {
+        case 'ArrowDown':
+        case 'ArrowUp':
+          if (items.length === 0) return false; // the empty-notice row is not navigable
+          e.preventDefault();
+          if (e.key === 'ArrowDown') {
+            setActiveIndex(boundedActive === null ? 0 : (boundedActive + 1) % items.length);
+          } else {
+            setActiveIndex(
+              boundedActive === null
+                ? items.length - 1
+                : (boundedActive - 1 + items.length) % items.length,
+            );
+          }
+          return true;
+        case 'Enter':
+        case 'Tab':
+          // NO row active means these keys were NOT aimed at the menu: Enter
+          // stays a newline, Tab still leaves the field.
+          if (boundedActive === null) return false;
+          e.preventDefault();
+          select(boundedActive);
+          return true;
+        case 'Escape':
+          e.preventDefault();
+          e.stopPropagation();
+          setActiveIndex(null);
+          setDismissedStart(trigger.from);
+          return true;
+        default:
+          return false;
+      }
+    },
+    [boundedActive, items.length, open, select, trigger],
+  );
+
+  return {
+    menu: open && trigger
+      ? { items, emptyNotice, activeIndex: boundedActive, anchor, query: trigger.query }
+      : null,
+    onKeyDown,
+    onSelect: readCaret,
+    select,
+    mentionIds,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.41.2",
+  "version": "0.43.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -76,7 +76,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.6",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.25.4",
+    "@plannotator/core": "0.25.5",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",