@plannotator/ui 0.53.0 → 0.53.1

package/components/html-viewer/bridge-script.ts

@@ -60,6 +60,47 @@ body[data-plannotator-pinpoint-cursor],
 body[data-plannotator-pinpoint-cursor] * {
   cursor: crosshair !important;
 }
+/* A plain click on a link with a real destination follows it while armed
+ * (Cmd/Ctrl-click pins it), so such a link keeps the pointer that says so,
+ * until the modifier is held. A link that goes nowhere (no href, "", "#",
+ * javascript:) is not followed and keeps the crosshair. SVG links may carry
+ * only xlink:href, hence the any-namespace attribute. */
+body[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) :is(a, area)[href]:not([href=""]):not([href="#"]):not([href^="javascript:" i]),
+body[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) :is(a, area)[href]:not([href=""]):not([href="#"]):not([href^="javascript:" i]) *,
+body[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) svg a:not([href])[*|href]:not([*|href=""]):not([*|href="#"]):not([*|href^="javascript:" i]),
+body[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) svg a:not([href])[*|href]:not([*|href=""]):not([*|href="#"]):not([*|href^="javascript:" i]) * {
+  cursor: pointer !important;
+}
+/* Touch, armed: a tap on a link follows it and a press-and-hold pins it for
+ * a comment. iOS's link callout would take that hold, so it is off on links
+ * while armed, once a touch is seen (data-plannotator-touch) or on screens
+ * without hover. The callout is all: link text stays selectable, so a drag
+ * across a link (a trackpad, a touchscreen laptop) still quotes its words.
+ * Only while a hold on a link is in progress (data-plannotator-link-hold,
+ * from its touchstart to its release) is selection off too, so the platform's
+ * long-press does not start a native text selection under the finger. */
+body[data-plannotator-pinpoint-cursor][data-plannotator-touch] :is(a, area),
+body[data-plannotator-pinpoint-cursor][data-plannotator-touch] :is(a, area) *,
+body[data-plannotator-pinpoint-cursor][data-plannotator-touch] svg a,
+body[data-plannotator-pinpoint-cursor][data-plannotator-touch] svg a * {
+  -webkit-touch-callout: none !important;
+}
+@media (hover: none) {
+  body[data-plannotator-pinpoint-cursor] :is(a, area),
+  body[data-plannotator-pinpoint-cursor] :is(a, area) *,
+  body[data-plannotator-pinpoint-cursor] svg a,
+  body[data-plannotator-pinpoint-cursor] svg a * {
+    -webkit-touch-callout: none !important;
+  }
+}
+body[data-plannotator-link-hold] :is(a, area),
+body[data-plannotator-link-hold] :is(a, area) *,
+body[data-plannotator-link-hold] svg a,
+body[data-plannotator-link-hold] svg a * {
+  -webkit-touch-callout: none !important;
+  -webkit-user-select: none !important;
+  user-select: none !important;
+}
 /* Armed pinpoint over an EMBEDDED local document: the embed is one element
  * from the outer page's point of view, and the bridge is never injected into a
  * nested frame, so a click inside it would simply vanish into another document.
@@ -1357,6 +1398,14 @@ export const BRIDGE_SCRIPT = `(function() {
   // changes); shared by mousemove and the scroll/resize reconcile pass.
   // Per-event hit-testing only — never builds the semantic graph.
   function updatePinpointHover(x, y, fallbackNode) {
+    // A link a plain click follows shows no pin outline unless Cmd/Ctrl is
+    // held: the outline always matches what a click there will do.
+    if (!pinModifierHeld && !pendingPinEl && (followableLinkAt(fallbackNode) || followableLinkAt(deepElementFromPoint(x, y)))) {
+      pinpointHover = null;
+      hidePinpointBox();
+      hidePinpointLabel();
+      return;
+    }
     var el = pinpointLeafAt(x, y, fallbackNode);
     // The 25px marker bubble owns clicks over it (they select its comment),
     // so hover must advertise the MARKER's own identity — no annotate box,
@@ -1387,9 +1436,36 @@ export const BRIDGE_SCRIPT = `(function() {
     positionPinpointLabel(el, pinpointHoverLabel(el));
   }
 
+  // Cmd or Ctrl held (the pin modifier): a link under the pointer shows the
+  // pin outline and the crosshair instead of the follow pointer. Read from
+  // the key itself (as the token-hover gate does) and from every pointer
+  // move, so a key pressed with focus outside this frame still counts.
+  var pinModifierHeld = false;
+  function setPinModifier(held) {
+    if (held === pinModifierHeld) return;
+    pinModifierHeld = held;
+    if (document.body) {
+      if (held) document.body.setAttribute('data-plannotator-pin-modifier', '');
+      else document.body.removeAttribute('data-plannotator-pin-modifier');
+    }
+    if (annotateModeActive && currentInputMethod === 'pinpoint' && lastPointer && !(vimEnabled && vimPhase !== 'inactive')) {
+      updatePinpointHover(lastPointer.x, lastPointer.y, lastPointerNode || pinpointHover);
+    }
+  }
+  document.addEventListener('keydown', function(e) {
+    if (e.key === 'Meta' || e.key === 'Control') setPinModifier(true);
+  }, true);
+  document.addEventListener('keyup', function(e) {
+    if (e.key === 'Meta' || e.key === 'Control') setPinModifier(e.metaKey || e.ctrlKey);
+  }, true);
+  window.addEventListener('blur', function() { setPinModifier(false); });
+
   var lastPointer = null;
+  var lastPointerNode = null;
   document.addEventListener('mousemove', function(e) {
     lastPointer = { x: e.clientX, y: e.clientY };
+    lastPointerNode = e.target && e.target.nodeType === 1 ? e.target : null;
+    if (!!(e.metaKey || e.ctrlKey) !== pinModifierHeld) setPinModifier(!!(e.metaKey || e.ctrlKey));
     updateDragYield(e);
     if (!annotateModeActive) return; // Interact mode: no hover affordances
     if (currentInputMethod !== 'pinpoint') {
@@ -3899,6 +3975,230 @@ export const BRIDGE_SCRIPT = `(function() {
     return true;
   }
 
+  // --- Touch: a tap on a link follows it, press-and-hold pins it ---
+  // The owner's amendment to html-link-click (2026-10-20): on a phone there is
+  // no Cmd/Ctrl, so while armed a TAP on a link follows it (the click handlers
+  // below take it as a plain click) and a PRESS-AND-HOLD of HOLD_PIN_MS opens
+  // a comment on it, pinned exactly as a Cmd-click pins it. Every surface
+  // alike: srcdoc pages (annotate, plan review's HTML, the Inbox) and live apps.
+  // A finger that moves past HOLD_SLOP_PX (a scroll), a second finger, or a
+  // scroll cancels the hold. The release of a hold that pinned never follows
+  // the link and never reaches the page: its pointerup and touchend are
+  // stopped at the window (registered before a live app's own listeners),
+  // touchend is cancelled so no click is synthesized, and a click that still
+  // arrives is swallowed once. That swallow ends at the next touch, mouse
+  // press or key, so it never eats an unrelated click.
+  // While a hold is in progress, link text is not selectable (the CSS above),
+  // so the platform's long-press starts no native selection under the finger;
+  // Android's contextmenu, its long-press signal, fires the hold at once.
+  var HOLD_PIN_MS = 500;
+  var HOLD_SLOP_PX = 10;
+  var HOLD_SWALLOW_MAX_MS = 10000; // a release never seen (an app stopped touchend)
+  var linkHold = null; // { timer, x, y, id, target }
+  // After a hold pinned: { pointerId, released, until } until its release's
+  // click (if any) is swallowed or the next gesture starts.
+  var heldGesture = null;
+  var lastTouchPointerId = null;
+  function holdArmed() {
+    return annotateModeActive && currentInputMethod === 'pinpoint' && !(vimEnabled && vimPhase !== 'inactive');
+  }
+  function setLinkHoldStyle(on) {
+    if (!document.body) return;
+    if (on) document.body.setAttribute('data-plannotator-link-hold', '');
+    else document.body.removeAttribute('data-plannotator-link-hold');
+  }
+  function cancelLinkHold() {
+    if (!linkHold) return;
+    clearTimeout(linkHold.timer);
+    linkHold = null;
+    setLinkHoldStyle(false);
+  }
+  function fireLinkHold() {
+    var hold = linkHold;
+    if (!hold) return false;
+    clearTimeout(hold.timer);
+    linkHold = null;
+    if (!holdArmed() || !hold.target.isConnected) {
+      setLinkHoldStyle(false);
+      return false;
+    }
+    var el = resolvePinpointTargetAt(hold.x, hold.y, hold.target);
+    if (!el) {
+      setLinkHoldStyle(false);
+      return false;
+    }
+    heldGesture = { pointerId: lastTouchPointerId, released: false, pointerUpSeen: false, pointerEnded: false, touchEnded: false, target: hold.target, touchId: hold.id, x: hold.x, y: hold.y, until: Date.now() + HOLD_SWALLOW_MAX_MS };
+    // The same pin a Cmd-click makes: the link's own words as a text range.
+    // Selection is back on for that, then off again until the finger lifts.
+    setLinkHoldStyle(false);
+    try { window.getSelection().removeAllRanges(); } catch (ex) {}
+    annotateElement(el, undefined, true, { x: hold.x, y: hold.y });
+    setLinkHoldStyle(true);
+    return true;
+  }
+  function endHeldGesture() {
+    heldGesture = null;
+  }
+  function touchById(list, id) {
+    for (var i = 0; list && i < list.length; i++) if (list[i].identifier === id) return list[i];
+    return null;
+  }
+  // The release of a hold is stopped, so the page never sees it end: a press
+  // library (React Aria's usePress, Motion's whileTap, dnd-kit) would keep the
+  // press open. In its place the page gets a pointercancel and a touchcancel
+  // on the element the finger went down on, which end a press without
+  // activating it. The bridge's own listeners ignore those two.
+  var bridgeSynthetic = typeof WeakSet === 'function' ? new WeakSet() : null;
+  function isBridgeSynthetic(e) {
+    return !!(bridgeSynthetic && bridgeSynthetic.has(e));
+  }
+  function dispatchSynthetic(target, event) {
+    if (bridgeSynthetic) bridgeSynthetic.add(event);
+    try { target.dispatchEvent(event); } catch (ex) {}
+  }
+  function sendPointerCancel(g, pointerId) {
+    if (g.pointerEnded || pointerId === null || pointerId === undefined) return;
+    g.pointerEnded = true;
+    var target = g.target && g.target.isConnected ? g.target : document.body;
+    if (!target) return;
+    var init = { bubbles: true, cancelable: false, composed: true, pointerId: pointerId, pointerType: 'touch', isPrimary: true, clientX: g.x, clientY: g.y };
+    var event = null;
+    try { if (typeof PointerEvent === 'function') event = new PointerEvent('pointercancel', init); } catch (ex) {}
+    if (!event) {
+      event = new Event('pointercancel', { bubbles: true, cancelable: false, composed: true });
+      try {
+        Object.defineProperty(event, 'pointerId', { value: pointerId });
+        Object.defineProperty(event, 'pointerType', { value: 'touch' });
+        Object.defineProperty(event, 'isPrimary', { value: true });
+      } catch (ex) {}
+    }
+    dispatchSynthetic(target, event);
+  }
+  function sendTouchCancel(g) {
+    if (g.touchEnded) return;
+    g.touchEnded = true;
+    var target = g.target && g.target.isConnected ? g.target : document.body;
+    if (!target) return;
+    var event = null;
+    try {
+      if (typeof TouchEvent === 'function' && typeof Touch === 'function') {
+        var t = new Touch({ identifier: g.touchId, target: target, clientX: g.x, clientY: g.y });
+        event = new TouchEvent('touchcancel', { bubbles: true, cancelable: false, composed: true, touches: [], targetTouches: [], changedTouches: [t] });
+      }
+    } catch (ex) { event = null; }
+    if (!event) {
+      event = new Event('touchcancel', { bubbles: true, cancelable: false, composed: true });
+      var point = { identifier: g.touchId, target: target, clientX: g.x, clientY: g.y };
+      try {
+        Object.defineProperty(event, 'touches', { value: [] });
+        Object.defineProperty(event, 'targetTouches', { value: [] });
+        Object.defineProperty(event, 'changedTouches', { value: [point] });
+      } catch (ex) {}
+    }
+    dispatchSynthetic(target, event);
+  }
+  // Pointer events come before touch events; the touch's pointerId names the
+  // release's pointerup.
+  window.addEventListener('pointerdown', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    if (e.pointerType === 'touch') {
+      lastTouchPointerId = e.pointerId;
+      if (heldGesture && heldGesture.released) endHeldGesture();
+      return;
+    }
+    // A mouse or pen press: whatever click comes next is its own.
+    endHeldGesture();
+  }, true);
+  window.addEventListener('keydown', function() { if (heldGesture && heldGesture.released) endHeldGesture(); }, true);
+  function heldPointer(e) {
+    if (!heldGesture || e.pointerType !== 'touch') return false;
+    return heldGesture.pointerId === null || e.pointerId === heldGesture.pointerId;
+  }
+  window.addEventListener('pointerup', function(e) {
+    if (isBridgeSynthetic(e) || !heldPointer(e) || heldGesture.pointerUpSeen) return;
+    heldGesture.pointerUpSeen = true;
+    e.stopImmediatePropagation();
+    sendPointerCancel(heldGesture, e.pointerId);
+  }, true);
+  // The browser ended the held pointer itself (it took the touch): nothing to stand in for.
+  window.addEventListener('pointercancel', function(e) {
+    if (isBridgeSynthetic(e) || !heldPointer(e)) return;
+    heldGesture.pointerUpSeen = true;
+    heldGesture.pointerEnded = true;
+  }, true);
+  window.addEventListener('touchend', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    if (heldGesture && !heldGesture.released) {
+      // The release of the hold that pinned: no click, no navigation, and
+      // the page's own touchend never runs on it; it gets cancels instead.
+      if (e.cancelable) e.preventDefault();
+      e.stopImmediatePropagation();
+      var g = heldGesture;
+      g.released = true;
+      g.until = Date.now() + 800;
+      setLinkHoldStyle(false);
+      // Engines that send touchend before pointerup: the pointer ends here
+      // (its own pointerup, when it comes, is still stopped).
+      sendPointerCancel(g, g.pointerId);
+      sendTouchCancel(g);
+      return;
+    }
+    cancelLinkHold(); // a tap: the click that follows it follows the link
+  }, { capture: true, passive: false });
+  window.addEventListener('touchcancel', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    cancelLinkHold();
+    setLinkHoldStyle(false);
+    if (heldGesture) {
+      heldGesture.released = true;
+      heldGesture.touchEnded = true;
+      heldGesture.until = Date.now() + 800;
+    }
+  }, true);
+  document.addEventListener('touchstart', function(e) {
+    if (document.body && !document.body.hasAttribute('data-plannotator-touch')) {
+      document.body.setAttribute('data-plannotator-touch', '');
+    }
+    cancelLinkHold();
+    // A new touch: whatever click comes next is its own, even if the last
+    // hold's release was never seen.
+    endHeldGesture();
+    setLinkHoldStyle(false);
+    if (!holdArmed() || !e.touches || e.touches.length !== 1) return;
+    if (isViewerOverlayNode(e.target) || !followableLinkAt(e.target)) return;
+    var t = e.touches[0];
+    linkHold = { x: t.clientX, y: t.clientY, id: t.identifier, target: e.target, timer: 0 };
+    linkHold.timer = setTimeout(fireLinkHold, HOLD_PIN_MS);
+    setLinkHoldStyle(true);
+  }, { capture: true, passive: true });
+  document.addEventListener('touchmove', function(e) {
+    if (!linkHold) return;
+    var t = touchById(e.touches, linkHold.id);
+    if (!t || e.touches.length !== 1 || Math.abs(t.clientX - linkHold.x) > HOLD_SLOP_PX || Math.abs(t.clientY - linkHold.y) > HOLD_SLOP_PX) {
+      cancelLinkHold();
+    }
+  }, { capture: true, passive: true });
+  window.addEventListener('scroll', cancelLinkHold, true);
+  document.addEventListener('contextmenu', function(e) {
+    if (linkHold) {
+      e.preventDefault();
+      fireLinkHold();
+      return;
+    }
+    if (heldGesture && Date.now() < heldGesture.until) e.preventDefault();
+  }, true);
+  // On the window, before every other click handler of the bridge and a live
+  // app's own, so the release of a hold reaches neither the link handler nor
+  // the pinpoint one, nor the page (a live app would navigate).
+  window.addEventListener('click', function(e) {
+    if (!heldGesture) return;
+    var swallow = Date.now() < heldGesture.until;
+    endHeldGesture();
+    if (!swallow) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+  }, true);
+
   // --- Local-site link navigation (srcdoc sessions only) ---
   // A srcdoc document has no URL of its own: its base URL is the PARENT page's,
   // which is the Plannotator server. So a plain link to 02-detail.html resolves
@@ -3910,8 +4210,14 @@ export const BRIDGE_SCRIPT = `(function() {
   // The frame therefore never navigates itself. In-page fragments scroll here;
   // everything else is handed to the parent, which owns resolution against the
   // current document's directory and is the trust boundary for the href.
-  // Registered BEFORE the pinpoint handler and never stopping propagation, so
-  // an armed click still pins the link element exactly as it always did.
+  // Registered BEFORE the pinpoint handler and never stopping propagation.
+  //
+  // One rule while armed (the owner's ruling, html-link-click, 2026-10-20):
+  // a plain click on a link FOLLOWS it, exactly as in Interact; a click with
+  // the platform modifier (Cmd on macOS, Ctrl elsewhere: either is taken)
+  // PINS it for a comment through the pinpoint handler below, as does a
+  // shift-click that adds it to an open multi-select draft. A drag that ended
+  // on the link owns its click: it neither follows nor pins.
   //
   // Live app sessions are excluded outright: they navigate a real origin
   // through the proxy, which is the whole point of that surface.
@@ -3934,6 +4240,25 @@ export const BRIDGE_SCRIPT = `(function() {
     return true;
   }
 
+  // While armed, whether a click on a link pins it instead of following it:
+  // the platform modifier (Cmd or Ctrl), a shift-click adding to an open
+  // multi-select draft, or the trailing click of a drag that selected text.
+  function armedClickPins(e) {
+    if (e.metaKey || e.ctrlKey || dragEndedClick) return true;
+    return !!(e.shiftKey && pendingPinEl && multiSelectArmed && pendingSelection);
+  }
+
+  // A link with a real destination: one a plain click follows while armed.
+  // No href, "", "#" and javascript: go nowhere, so a click on them pins
+  // the element as on any other (agents' mocks use <a href="#"> for buttons).
+  function isFollowableHref(raw) {
+    return !!raw && raw !== '#' && !/^javascript:/i.test(raw);
+  }
+
+  function followableLinkAt(node) {
+    return !!node && isFollowableHref(navigableLinkHref(node));
+  }
+
   function navigableLinkHref(node) {
     var el = node && node.nodeType === 1 ? node : node && node.parentElement;
     if (!el || !el.closest) return '';
@@ -3953,26 +4278,30 @@ export const BRIDGE_SCRIPT = `(function() {
       if (!raw) return;
       // The page's own scripting, not a navigation: leave it alone.
       if (/^javascript:/i.test(raw)) return;
+      // Armed and pinning (a link that goes nowhere, the modifier, or a
+      // drag's trailing click): the frame never navigates, and the pinpoint
+      // handler below takes the click.
+      if (annotateModeActive && currentInputMethod === 'pinpoint' && (!isFollowableHref(raw) || armedClickPins(e))) {
+        e.preventDefault();
+        return;
+      }
       if (raw.charAt(0) === '#') {
         e.preventDefault();
         scrollToLocalFragment(raw.slice(1));
         return;
       }
       e.preventDefault();
+      // Only a person's click follows a link: a page's own script calling
+      // a.click() never navigates the viewer or pushes the host's history.
+      if (!e.isTrusted) return;
       // A native host decides links itself: a person's tap opens the link as a
       // new window, which the host's web view hands to its own delegate (the
       // frame never navigates; the host page's CSP would refuse it anyway).
       if (hostNavigates) {
-        if (e.isTrusted && !(annotateModeActive && currentInputMethod === 'pinpoint')) {
-          var target = (e.target && e.target.closest) ? e.target.closest('a,area') : null;
-          try { window.open(target && target.href ? target.href : raw, '_blank', 'noopener'); } catch (ex) {}
-        }
+        var target = (e.target && e.target.closest) ? e.target.closest('a,area') : null;
+        try { window.open(target && target.href ? target.href : raw, '_blank', 'noopener'); } catch (ex) {}
         return;
       }
-      // Armed pinpoint: the click belongs to annotation, and the capture-phase
-      // pinpoint handler below is about to pin this element. Navigation is
-      // already suppressed above, which is all this surface owes the click.
-      if (annotateModeActive && currentInputMethod === 'pinpoint') return;
       postToParent({ type: PREFIX + 'link-click', href: raw.slice(0, 2048) });
     }, true);
   }
@@ -3991,7 +4320,12 @@ export const BRIDGE_SCRIPT = `(function() {
     // and mousedown clears a prior pin's leftover selection, so stale
     // selection state never blocks the next plain re-pin click. One-shot:
     // only the drag's own trailing click is suppressed.
-    if (dragEndedClick) { dragEndedClick = false; return; }
+    if (dragEndedClick) {
+      dragEndedClick = false;
+      // Never a navigation either (a live app's link would otherwise follow).
+      if (navigableLinkHref(e.target)) e.preventDefault();
+      return;
+    }
     // Shift-click while an ARMED pinpoint draft is open: toggle the element
     // in/out of the SAME draft comment instead of replacing the selection.
     // Unarmed drafts (modes the parent does not mirror, e.g. quickLabel)
@@ -4005,6 +4339,9 @@ export const BRIDGE_SCRIPT = `(function() {
       if (multiEl) toggleMultiTarget(multiEl, { x: e.clientX, y: e.clientY });
       return;
     }
+    // A plain click on a link follows it (the link handler above posted it;
+    // in a live app the browser navigates for real). The modifier pins it.
+    if (isFollowableHref(navigableLinkHref(e.target)) && !armedClickPins(e)) return;
     // Click what the hover box shows: the currently hovered element is the
     // target the user aimed at. Fall back to a fresh hit-test at the click
     // point (e.g. a click with no preceding mousemove).
@@ -4032,12 +4369,36 @@ export const BRIDGE_SCRIPT = `(function() {
     window.getSelection().removeAllRanges();
     renderAnnotationOverlay();
   }
+  // An Escape in Interact that the page did not use (no handler cancelled it
+  // or stopped it on its way up, focus not in one of its text fields) is
+  // offered to the host as page-escape, after every handler had its turn: the
+  // Inbox leaves full screen with it. The page still got the key first.
+  var escapeReachedWindow = null;
+  window.addEventListener('keydown', function(e) {
+    if (e.key === 'Escape') escapeReachedWindow = e;
+  });
+  function offerUnusedEscape(e) {
+    if (e.repeat || e.isComposing || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
+    var t = e.target;
+    if (t && t.nodeType === 1) {
+      var tag = t.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable) return;
+      if (t.closest && t.closest('[contenteditable]:not([contenteditable="false"])')) return;
+    }
+    // The page's own dialog closes on this Escape (the browser's default, not a handler).
+    if (document.querySelector('dialog[open]')) return;
+    setTimeout(function() {
+      if (escapeReachedWindow !== e || e.defaultPrevented) return;
+      postToParent({ type: PREFIX + 'page-escape' });
+    }, 0);
+  }
   document.addEventListener('keydown', function(e) {
     if (e.key !== 'Escape' || vimEnabled) return;
     if (!annotateModeActive) {
       // Interact mode: Esc belongs to the page — except an open drag-comment
       // draft (drag-selection stays live in Interact) still closes first.
       if (pendingSelection) closePendingDraft();
+      else offerUnusedEscape(e);
       return;
     }
     if (pendingSelection) {

package/hooks/useMentionAutocomplete.ts

@@ -115,7 +115,7 @@ export function useMentionAutocomplete(options: {
   }, [mentionsKey, onMentionsChange]);
 
   const items = useMemo(
-    () => (source && trigger ? mentionMatches(source.people, trigger, taggedIds) : []),
+    () => (source && trigger ? mentionMatches(source.people, trigger, taggedIds, source.kinds, source.matchDetail ?? true) : []),
     [source, trigger, taggedIds],
   );
 

package/hooks/useSkillReferenceAutocomplete.ts

@@ -59,14 +59,18 @@ export interface UseSkillReferenceAutocompleteResult {
  * active row and dismisses the menu when the user has engaged with it (a row
  * is active or a query was typed); on a bare-trigger menu with no engagement
  * it passes through, so Escape still closes the composer in one press.
+ * `bareEscapeDismisses` (default off) makes Escape close any open menu first,
+ * for a composer where Escape costs more than a press (the Inbox's compose
+ * dialog asks whether to keep a draft).
  */
 export function useSkillReferenceAutocomplete(options: {
   text: string;
   setText: (text: string) => void;
   textareaRef: React.RefObject<HTMLTextAreaElement | null>;
   enabled: boolean;
+  bareEscapeDismisses?: boolean;
 }): UseSkillReferenceAutocompleteResult {
-  const { text, setText, textareaRef, enabled } = options;
+  const { text, setText, textareaRef, enabled, bareEscapeDismisses = false } = options;
   // Seed from the memory cache only when the surface opted in — a disabled
   // composer must stay inert even after another surface warmed the catalog.
   const [catalog, setCatalog] = useState<SkillCatalogEntry[]>(() =>
@@ -205,7 +209,7 @@ export function useSkillReferenceAutocomplete(options: {
           // Only consume Escape when the user engaged with the menu (typed a
           // query or activated a row). A bare-trigger menu the user ignored
           // must not cost an extra Escape on the way to closing the composer.
-          if (boundedActive === null && trigger.query.length === 0) return false;
+          if (!bareEscapeDismisses && boundedActive === null && trigger.query.length === 0) return false;
           e.preventDefault();
           e.stopPropagation();
           setActiveIndex(null);
@@ -215,7 +219,7 @@ export function useSkillReferenceAutocomplete(options: {
           return false;
       }
     },
-    [boundedActive, items.length, open, select, trigger],
+    [bareEscapeDismisses, boundedActive, items.length, open, select, trigger],
   );
 
   const humanOnlyReferences = useMemo(

package/hooks/useVimSelection.ts

@@ -317,8 +317,16 @@ export function useVimSelection({
     return next;
   }, [containerRef, setState]);
 
+  // Whether vim was on since the last reset. The disabled branch below resets
+  // only when vim actually goes from on to off: on a mount where vim was never
+  // on there is nothing to reset, and `window.getSelection()` in
+  // `clearSelectionWithin` forces a layout on every document open.
+  const wasEnabledRef = useRef(enabled);
+
   useEffect(() => {
     if (!enabled) {
+      if (!wasEnabledRef.current) return;
+      wasEnabledRef.current = false;
       setState(createInitialVimSelectionState());
       setFocused(false);
       setHelpOpen(false);
@@ -326,6 +334,7 @@ export function useVimSelection({
       clearSelectionWithin(containerRef.current);
       return;
     }
+    wasEnabledRef.current = true;
     if (!focused) return;
     if (restoringFocusRef.current) {
       restoringFocusRef.current = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.53.0",
+  "version": "0.53.1",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {

package/shortcuts/runtime.ts

@@ -27,6 +27,12 @@ export interface UseShortcutScopeOptions<TScope extends ShortcutScopeDefinition<
   handlers: ShortcutHandlers<TScope>;
   target?: ShortcutEventTarget;
   stopOnMatch?: boolean;
+  /**
+   * Listen in the capture phase: the scope sees a key before the focused
+   * element does (a guard that must run before a component's own handler).
+   * Default false (bubble), so a component that used the key first can say so.
+   */
+  capture?: boolean;
 }
 
 interface ShortcutSequenceCandidate {
@@ -123,6 +129,7 @@ export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
   handlers,
   target = 'window',
   stopOnMatch = true,
+  capture = false,
 }: UseShortcutScopeOptions<TScope>) {
   const handlersRef = useRef(handlers);
   const sequenceRef = useRef<ShortcutSequenceState | null>(null);
@@ -206,11 +213,11 @@ export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
       if (started.length > 0) keyboardEvent.preventDefault();
     };
 
-    eventTarget.addEventListener('keydown', handleKeyDown);
+    eventTarget.addEventListener('keydown', handleKeyDown, capture);
     return () => {
-      eventTarget.removeEventListener('keydown', handleKeyDown);
+      eventTarget.removeEventListener('keydown', handleKeyDown, capture);
     };
-  }, [scope, stopOnMatch, target]);
+  }, [scope, stopOnMatch, target, capture]);
 }
 
 export function createShortcutScopeHook<TScope extends ShortcutScopeDefinition<any>>(scope: TScope) {

package/utils/mentions.ts

@@ -11,6 +11,7 @@
  * Nothing here touches the DOM, fetches, or persists. A composer with no
  * `mentionSource` never calls any of it.
  */
+import type { ReactNode } from 'react';
 
 /** One pickable identity, supplied by the host. */
 export interface MentionPerson {
@@ -32,6 +33,13 @@ export interface MentionPerson {
    * supplied `onPickBlocked` (see `MentionSource`).
    */
   readonly canOpen: boolean;
+  /**
+   * Optional group heading: consecutive people with the same
+   * `group` are drawn under one heading, as a `role="group"` labelled by it
+   * (the Inbox groups agents by kind). Absent on every person → the flat
+   * list, exactly as before.
+   */
+  readonly group?: string;
 }
 
 /** The opt-in `@` mention source for `CommentPopover`'s composer. */
@@ -61,6 +69,24 @@ export interface MentionSource {
   readonly tokenClassName?: string;
   /** Fires on every text change with the ids whose token still survives in the body. */
   readonly onMentionsChange?: (ids: readonly string[]) => void;
+  /**
+   * Which kinds of people this composer offers. Absent → users only,
+   * as before (an agent is not taggable in a host's comments by default). A
+   * host whose agents can be tagged (the Inbox) passes `['agent']` or both.
+   */
+  readonly kinds?: readonly MentionPerson['kind'][];
+  /**
+   * Whether a query also matches the `detail` line. Absent → true, as
+   * before. A host whose detail is incidental (the Inbox's "billing-api ·
+   * idle") passes false, so `@p` finds Pi, not every row with a "p" in it.
+   */
+  readonly matchDetail?: boolean;
+  /**
+   * Optional line drawn under the composer field, from the people
+   * the draft still tags: a host's "Goes to …" and heads-up. Absent → nothing
+   * is drawn, as before.
+   */
+  readonly renderNotice?: (tagged: readonly MentionPerson[]) => ReactNode;
   /**
    * A `canOpen: false` person was picked. When supplied, NOTHING is inserted
    * and the host shows its own no-access affordance. When absent, such a
@@ -115,24 +141,27 @@ export function mentionTrigger(text: string, caret: number): MentionTrigger | nu
 }
 
 /**
- * The people this trigger offers: users only (an agent is not taggable in a
- * comment), never one already tagged in this draft, de-duplicated by id, and
- * filtered on label or detail once a query character exists.
+ * The people this trigger offers: users only by default (an agent is not
+ * taggable in a comment unless the host says so with `kinds`), never one
+ * already tagged in this draft, de-duplicated by id, and filtered on label or
+ * detail once a query character exists.
  */
 export function mentionMatches(
   people: readonly MentionPerson[],
   trigger: MentionTrigger,
   alreadyTagged: ReadonlySet<string>,
+  kinds: readonly MentionPerson['kind'][] = ['user'],
+  matchDetail = true,
 ): readonly MentionPerson[] {
   const seen = new Set<string>();
   return people.filter((person) => {
-    if (person.kind !== 'user') return false;
+    if (!kinds.includes(person.kind)) return false;
     if (alreadyTagged.has(person.id) || seen.has(person.id)) return false;
     seen.add(person.id);
     if (trigger.query === '') return true;
     return (
       person.label.toLowerCase().includes(trigger.query) ||
-      (person.detail ?? '').toLowerCase().includes(trigger.query)
+      (matchDetail && (person.detail ?? '').toLowerCase().includes(trigger.query))
     );
   });
 }