@plannotator/ui 0.53.0 → 0.53.1

package/components/CodeFilePopout.tsx

@@ -180,7 +180,7 @@ const CodeInlineAnnotation: React.FC<{
         <span className="rounded bg-muted px-1.5 py-0.5 font-mono normal-case text-foreground">
           {lineLabel(annotation.lineStart, annotation.lineEnd)}
         </span>
-        {annotation.author && <span className="truncate normal-case">by {annotation.author}</span>}
+        {annotation.author && <span className="truncate normal-case">by <bdi>{annotation.author}</bdi></span>}
         <div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 [@media(hover:none)]:opacity-100">
           {onEdit && !isEditing && (
             <button

package/components/CommentPopover.tsx

@@ -726,6 +726,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               activeOptionId={activeComposerOptionId}
             />
             <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
+            {mentionSource?.renderNotice?.(mentionChipPeople)}
             <MentionAutocompleteMenu
               id={mentionListboxId}
               menu={mentionAc.menu}
@@ -879,6 +880,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           activeOptionId={activeComposerOptionId}
         />
         <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
+        {mentionSource?.renderNotice?.(mentionChipPeople)}
         <MentionAutocompleteMenu
           id={mentionListboxId}
           menu={mentionAc.menu}

package/components/HtmlSurfaceControls.tsx

@@ -31,6 +31,7 @@
  */
 import React from 'react';
 import { Tooltip } from './Tooltip';
+import { modKey } from '../utils/platform';
 import { formatShortcutBindingText, formatShortcutBindingTokens } from '../shortcuts/core';
 import { htmlAnnotateShortcuts } from '../shortcuts/plan-review/htmlAnnotate.shortcuts';
 
@@ -135,7 +136,7 @@ export interface HtmlSurfaceControlLabels {
 export const DEFAULT_HTML_SURFACE_CONTROL_LABELS: Required<
   Omit<HtmlSurfaceControlLabels, 'annotateLabel' | 'interactLabel'>
 > = {
-  annotateTitle: 'Annotate mode: click an element or select text to comment. Esc to interact',
+  annotateTitle: `Annotate mode: click an element or select text to comment; links open (${modKey}-click one to comment on it). Esc to interact`,
   interactTitle: 'Interact mode: clicks reach the page (text selection still comments). Click to annotate',
   hideTools: 'Hide tools',
   showTools: 'Show tools',

package/components/MentionPicker.tsx

@@ -34,6 +34,18 @@ export function mentionAnchorOf(element: HTMLElement | null): MentionAnchor | nu
   return { top: rect.top, bottom: rect.bottom, left: rect.left, width: rect.width };
 }
 
+/** Consecutive runs of people with the same `group`, with each run's first index in the flat list. */
+export function mentionGroups(people: readonly MentionPerson[]): { group: string; start: number; people: MentionPerson[] }[] {
+  const runs: { group: string; start: number; people: MentionPerson[] }[] = [];
+  people.forEach((person, index) => {
+    const group = person.group ?? '';
+    const last = runs[runs.length - 1];
+    if (last && last.group === group) last.people.push(person);
+    else runs.push({ group, start: index, people: [person] });
+  });
+  return runs;
+}
+
 /** The optional avatar column: an image, else initials on a tinted disc. */
 function MentionAvatar({
   avatar,
@@ -116,6 +128,45 @@ export function MentionPicker({
         <p data-mention-empty className="px-2 py-1 text-[11px] text-muted-foreground">
           {emptyNotice}
         </p>
+      ) : people.some((person) => person.group) ? (
+        // Grouped (a host set `group`): each run of one group is a `role="group"` labelled by its heading.
+        mentionGroups(people).map((run) => {
+          const headingId = id ? `${id}-group-${run.start}` : undefined;
+          return (
+            <div key={`${run.group}-${run.start}`} role="group" aria-labelledby={headingId} data-mention-group={run.group}>
+              <p id={headingId} data-mention-group-heading className="px-2 pb-1 pt-1.5 text-[10px] font-medium text-muted-foreground">
+                {run.group}
+              </p>
+              {run.people.map((person, offset) => {
+                const index = run.start + offset;
+                return (
+                  <button
+                    key={person.id}
+                    type="button"
+                    role="option"
+                    id={id ? `${id}-option-${index}` : undefined}
+                    aria-selected={active === index}
+                    data-mention-option={person.id}
+                    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'
+                    }`}
+                  >
+                    {person.avatar && <MentionAvatar avatar={person.avatar} label={person.label} />}
+                    <span className="min-w-0 flex-1 truncate">{person.label}</span>
+                    {person.detail && (
+                      <span className="min-w-0 max-w-[44%] shrink-0 truncate text-[10px] text-muted-foreground">{person.detail}</span>
+                    )}
+                  </button>
+                );
+              })}
+            </div>
+          );
+        })
       ) : (
         people.map((person, index) => (
           <button

package/components/SkillReferenceMenu.tsx

@@ -15,6 +15,16 @@ interface SkillReferenceMenuProps {
   /** Explicitly activated row, or null — the menu opens with nothing active. */
   activeIndex: number | null;
   onSelect: (index: number) => void;
+  /**
+   * The box the menu must stay inside, in viewport coordinates, read at each
+   * measure. Default: the viewport. A host whose composer sits in a dialog
+   * with a footer passes the dialog's area above the footer.
+   */
+  boundary?: () => { top: number; bottom: number } | null;
+  /** Which side of the anchor the menu tries first. Default: above. */
+  prefer?: 'above' | 'below';
+  /** Upper bound on the list's height, in px. Default: 256. */
+  maxListHeight?: number;
 }
 
 /** Vertical gap between the composer wrapper and the menu (mb-1.5 / mt-1.5 = 6px). */
@@ -40,24 +50,29 @@ interface MenuPlacement {
  * When neither side fits the whole list, the side with more room wins and the
  * list is clamped to it, so the menu never extends past a viewport edge.
  */
-function computeMenuPlacement(
+export function computeMenuPlacement(
   anchorRect: Pick<DOMRect, 'top' | 'bottom'>,
   naturalListHeight: number,
   chromeHeight: number,
   viewportHeight: number,
+  options: { boundaryTop?: number; prefer?: 'above' | 'below'; maxListHeight?: number } = {},
 ): MenuPlacement {
-  const spaceAbove = anchorRect.top - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
+  const boundaryTop = options.boundaryTop ?? 0;
+  const cap = options.maxListHeight ?? MAX_LIST_HEIGHT;
+  const spaceAbove = anchorRect.top - boundaryTop - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
   const spaceBelow = viewportHeight - anchorRect.bottom - MENU_GAP - MENU_VIEWPORT_MARGIN - chromeHeight;
-  const needed = Math.min(naturalListHeight, MAX_LIST_HEIGHT);
+  const needed = Math.min(naturalListHeight, cap);
+  const [first, second] = options.prefer === 'below' ? (['below', 'above'] as const) : (['above', 'below'] as const);
+  const space = (side: MenuPlacement['direction']) => (side === 'above' ? spaceAbove : spaceBelow);
   const direction: MenuPlacement['direction'] =
-    needed <= spaceAbove ? 'above'
-    : needed <= spaceBelow ? 'below'
-    : spaceAbove >= spaceBelow ? 'above'
-    : 'below';
-  const available = direction === 'above' ? spaceAbove : spaceBelow;
+    needed <= space(first) ? first
+    : needed <= space(second) ? second
+    : space(first) >= space(second) ? first
+    : second;
+  const available = space(direction);
   return {
     direction,
-    maxListHeight: Math.max(0, Math.min(MAX_LIST_HEIGHT, Math.round(available))),
+    maxListHeight: Math.max(0, Math.min(cap, Math.round(available))),
   };
 }
 
@@ -85,13 +100,19 @@ export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
   items,
   activeIndex,
   onSelect,
+  boundary,
+  prefer,
+  maxListHeight,
 }) => {
   const menuRef = useRef<HTMLDivElement>(null);
   const listRef = useRef<HTMLDivElement>(null);
   const [placement, setPlacement] = useState<MenuPlacement>({
-    direction: 'above',
-    maxListHeight: MAX_LIST_HEIGHT,
+    direction: prefer ?? 'above',
+    maxListHeight: maxListHeight ?? MAX_LIST_HEIGHT,
   });
+  // The optional seams, read through a ref so `measure` stays stable for its listeners.
+  const optionsRef = useRef({ boundary, prefer, maxListHeight });
+  optionsRef.current = { boundary, prefer, maxListHeight };
 
   const measure = useCallback(() => {
     const menuEl = menuRef.current;
@@ -106,7 +127,13 @@ export const SkillReferenceMenu: React.FC<SkillReferenceMenuProps> = ({
     // jitter loop this component once shipped.
     const chrome = Math.max(0, menuEl.offsetHeight - listEl.offsetHeight);
     // scrollHeight reports full content height even while clamped.
-    const next = computeMenuPlacement(rect, listEl.scrollHeight, chrome, window.innerHeight);
+    const { boundary: readBoundary, prefer: side, maxListHeight: cap } = optionsRef.current;
+    const box = readBoundary?.() ?? null;
+    const next = computeMenuPlacement(rect, listEl.scrollHeight, chrome, box ? box.bottom : window.innerHeight, {
+      boundaryTop: box ? box.top : 0,
+      prefer: side,
+      maxListHeight: cap,
+    });
     setPlacement((prev) =>
       prev.direction === next.direction && prev.maxListHeight === next.maxListHeight
         ? prev

package/components/Viewer.tsx

@@ -326,6 +326,18 @@ export interface ViewerProps {
    * blocks and no comments on its text. Absent → unchanged.
    */
   answerOnly?: boolean;
+  /**
+   * Opt-in host capability, with `answerOnly`: the reader may comment on the
+   * text. A text selection opens the selection toolbar, comment-only
+   * (Comment and the one-click 👍; no Delete, no label picker), and its
+   * comment composer; `annotations` are drawn as highlights. Question cards
+   * are left out of selection (their text is not commented on), and nothing
+   * else of authoring comes back (no pinpoint, code-block toolbar, Global
+   * comment or Copy, no Vim). For a host that shows a message whose words
+   * can be commented on (the Plannotator Inbox's agent messages). Ignored
+   * without `answerOnly` and under `readOnly`. Absent → unchanged.
+   */
+  textComments?: boolean;
   /** Opt-in Vim-style keyboard selection. Default false for compatibility. */
   vimModeEnabled?: boolean;
   /** Replace the compact Vim badge with the live video-style key HUD. */
@@ -731,6 +743,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   allowImages = true,
   readOnly = false,
   answerOnly = false,
+  textComments = false,
   vimModeEnabled = false,
   vimHudEnabled = false,
   vimHudKeyPanelEnabled = true,
@@ -740,6 +753,11 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   // Annotation authoring is off when read-only, and when the host only wants
   // answers (`answerOnly`); question cards and checkboxes follow `readOnly`.
   const authoringOff = readOnly || answerOnly;
+  // `textComments`: an answer-only document whose words still take comments
+  // (the selection toolbar, comment-only, and its composer); everything else
+  // of authoring stays off. Without it this is exactly `!authoringOff`.
+  const textCommentsOnly = answerOnly && textComments && !readOnly;
+  const selectionCommentsOn = !authoringOff || textCommentsOnly;
   const hostComposes = onHostDraft !== undefined && !authoringOff;
   const viewerAnnotationHeader = authoringOff ? undefined : annotationHeader;
   const hasViewerAnnotationHeader = viewerAnnotationHeader !== undefined;
@@ -883,7 +901,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     onSelectAnnotation,
     selectedAnnotationId,
     mode,
-    enabled: !authoringOff,
+    enabled: selectionCommentsOn,
     // Markdown documents drift between the moment a draft/share is written and
     // the moment it is restored (a plan revision, a re-rendered block, a
     // renderer change that adds or drops elements — #1509 hoisted an alert's
@@ -1697,12 +1715,12 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 : undefined;
               if (hostCard !== undefined) {
                 return (
-                  <div key={group.block.id} data-block-id={group.block.id} data-block-type="directive">
+                  <div key={group.block.id} data-block-id={group.block.id} data-block-type="directive" className={textCommentsOnly ? 'annotation-exclude' : undefined}>
                     {hostCard}
                   </div>
                 );
               }
-              return (
+              const rendered = (
                 <BlockRenderer
                   imageBaseDir={imageBaseDir}
                   onImageClick={(src, alt) => setLightbox({ src, alt })}
@@ -1732,16 +1750,28 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                   renderQuestionBelowPrompt={renderQuestionBelowPrompt}
                 />
               );
+              // `textComments`: a question card's words are not commented on
+              // (its own controls already are excluded); a box-less wrapper
+              // keeps its layout.
+              if (question && textCommentsOnly) {
+                return (
+                  <div key={group.block.id} className="annotation-exclude" style={{ display: 'contents' }}>
+                    {rendered}
+                  </div>
+                );
+              }
+              return rendered;
             })()
           )
         )}
 
         {/* Text selection toolbar */}
-        {!authoringOff && !hostComposes && toolbarState && (
+        {selectionCommentsOn && !hostComposes && toolbarState && (
           <ToolbarErrorBoundary>
             <AnnotationToolbar
               element={toolbarState.element}
               positionMode="center-above"
+              commentOnly={textCommentsOnly || undefined}
               onAnnotate={handleAnnotate}
               onClose={handleToolbarClose}
               onRequestComment={handleRequestComment}
@@ -1876,7 +1906,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
         )}
 
         {/* Comment popover — hook handles text selection, Viewer handles global + code block */}
-        {!authoringOff && !hostComposes && hookCommentPopover && (
+        {selectionCommentsOn && !hostComposes && hookCommentPopover && (
             <CommentPopover
               anchorEl={hookCommentPopover.anchorEl}
               contextText={hookCommentPopover.contextText}
@@ -1928,7 +1958,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
         )}
 
         {/* Quick Label floating picker — hook handles text selection, Viewer handles code blocks */}
-        {!authoringOff && !hostComposes && hookQuickLabelPicker && (
+        {selectionCommentsOn && !hostComposes && hookQuickLabelPicker && (
           <FloatingQuickLabelPicker
             anchorEl={hookQuickLabelPicker.anchorEl}
             cursorHint={hookQuickLabelPicker.cursorHint}

package/components/blocks/QuestionContext.tsx

@@ -18,6 +18,9 @@ const QUESTION_CONTEXT_CSS = `
 .question-context > :first-child { margin-top: 0; }
 .question-context > :last-child { margin-bottom: 0; }
 .question-context p, .question-context .text-sm { font-size: 13px; line-height: 1.5; }
+/* Context lines stay lines ("Stopped: …" then "Holds up: …"), as the
+   authoring guide writes them; the parser keeps them as soft breaks. */
+.question-context p { white-space: pre-line; }
 .question-context p, .question-context [data-question-context-list] span { color: inherit; }
 .question-context h1, .question-context h2, .question-context h3 { margin: 0.75rem 0 0.25rem; font-size: 14px; }
 .question-context h3 { font-size: 13.5px; }

package/components/html-viewer/HtmlViewer.tsx

@@ -239,6 +239,13 @@ export interface HtmlViewerProps {
    *  key. Honored only while the frame holds focus, and at most once per
    *  STEP_MESSAGE_MIN_INTERVAL_MS. Absent: the message is ignored, as before. */
   onStep?: (dir: 1 | -1) => void;
+  /** Escape pressed inside the page in Interact that the page did not use
+   *  itself (no handler of the page cancelled it or stopped it, and focus was
+   *  not in one of its text fields): the host may close something of its own
+   *  (the Inbox leaves full screen). Never sent in Annotate, whose Escape is
+   *  `onAnnotateModeExit`. Honored only while the frame holds focus, and at
+   *  most once per STEP_MESSAGE_MIN_INTERVAL_MS. Absent: ignored, as before. */
+  onPageEscape?: () => void;
   /** Opt-in Vim-style keyboard selection. Default false for compatibility. */
   vimModeEnabled?: boolean;
   /** Replace the iframe-local compact badge with the shared live key HUD. */
@@ -384,6 +391,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onAnnotateModeToggle,
       onToolsToggle,
       onStep,
+      onPageEscape,
       vimModeEnabled = false,
       vimHudEnabled = false,
       vimHudKeyPanelEnabled = true,
@@ -452,6 +460,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     const annotateModeActiveRef = useRef(annotateModeActive);
     annotateModeActiveRef.current = annotateModeActive;
     const lastStepAtRef = useRef(0);
+    const onPageEscapeRef = useRef(onPageEscape);
+    onPageEscapeRef.current = onPageEscape;
+    const lastPageEscapeAtRef = useRef(0);
 
     /** Single choke point for direct-to-bridge posts: live sessions get the
      *  token + concrete targetOrigin, srcdoc keeps "*" and no token. */
@@ -809,6 +820,17 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
           onStepRef.current?.(dir);
           return;
         }
+        if (isRecord(e.data) && e.data.type === `${PREFIX}page-escape`) {
+          // Like a step, the page could post this itself: honored only for a
+          // key pressed in the frame, in Interact, at most once per interval.
+          if (annotateModeActiveRef.current) return;
+          if (document.activeElement !== iframeRef.current) return;
+          const now = Date.now();
+          if (now - lastPageEscapeAtRef.current < STEP_MESSAGE_MIN_INTERVAL_MS) return;
+          lastPageEscapeAtRef.current = now;
+          onPageEscapeRef.current?.();
+          return;
+        }
         const vimCopy = parseVimBridgeCopy(e.data);
         if (vimCopy !== null) {
           const iframe = iframeRef.current;