@plannotator/ui 0.53.0 → 0.54.0

package/components/AnnotationPanel.tsx

@@ -1,8 +1,9 @@
-import React, { useState, useRef, useEffect, useId } from 'react';
+import React, { createContext, useContext, useMemo, useState, useRef, useEffect, useId } from 'react';
 import { AnnotationType, type Annotation, type Block, type CodeAnnotation, type EditorAnnotation } from '../types';
 import type { MentionSource } from '../utils/mentions';
 import { useMentionAutocomplete } from '../hooks/useMentionAutocomplete';
 import { MentionAutocompleteMenu, mentionActiveOptionId } from './MentionAutocomplete';
+import { buildSectionRefIndex, parseSectionRefs } from '../utils/sectionRefs';
 import { isCurrentUser } from '../utils/identity';
 import { ImageThumbnail } from './ImageThumbnail';
 import { EditorAnnotationCard } from './EditorAnnotationCard';
@@ -16,6 +17,15 @@ import type { AnnotationScope, AnnotationDocumentGroup } from '../utils/annotati
 import type { QuestionPanelRow } from '../utils/questionAnswers';
 import { QuestionsPanelSection } from './QuestionsPanelSection';
 import { HostTitle } from './HostTitle';
+import { isCommentSubmitKey } from '../utils/commentSubmitKey';
+import { useConfigValue } from '../config/useConfig';
+import { imageRegionNumbers, RegionCardInfo, RegionNumber, regionOf } from './ImageRegions';
+
+/** What a region card (#2100) needs from its panel: each region's number on
+ *  its image, and how to load the image for the crop thumbnail. */
+const RegionCardContext = createContext<{ numbers: ReadonlyMap<string, number>; thumbSrc?: (src: string) => string | null }>({
+  numbers: new Map(),
+});
 
 // Card type-word colors. Deletion uses `destructive` (reliably red on every
 // theme, matching the in-document .deletion highlight). Comment uses the
@@ -120,6 +130,8 @@ interface PanelProps {
   editorAnnotations?: EditorAnnotation[];
   onDeleteEditorAnnotation?: (id: string) => void;
   onClose?: () => void;
+  /** Navigate the document to a heading anchor, for `#Heading` references in comment text. */
+  onNavigateAnchor?: (hash: string) => void;
   /** Copy the full feedback payload. May resolve a success boolean; resolving
     *  `false` suppresses the "Copied" flash. A void resolution (existing hosts)
     *  is treated as success, preserving the original behavior. */
@@ -213,13 +225,30 @@ interface PanelProps {
    * the frame in `renderCardHeader`) turns them off per card. Absent: both
    * drawn, exactly as before.
    */
-  cardParts?: (annotation: Annotation) => { quote?: boolean; images?: boolean };
+  cardParts?: (annotation: Annotation) => { quote?: boolean; images?: boolean; text?: boolean };
+  /**
+   * Optional: the host's own body for a plan-annotation card, drawn where the
+   * comment text goes, inside the card (a click on it selects the card). The
+   * Inbox draws a drawing that has no words as its picture, with `cardParts`
+   * `text: false` (its stored text is a stand-in for the agent, not the
+   * person's words: not drawn, and the edit box starts empty). Absent:
+   * nothing extra, exactly as before.
+   */
+  renderCardBody?: (annotation: Annotation) => React.ReactNode;
+  /**
+   * Comments on part of an image (`imageRegion`, #2100) draw a crop of their
+   * box in place of the quote; this turns an image's src as written into a
+   * URL the browser can load (null: no crop, the file and size still show).
+   * Absent: no crop.
+   */
+  imageRegionSrc?: (src: string) => string | null;
 }
 
 export const AnnotationPanel: React.FC<PanelProps> = ({
   emptyHint = 'Select text to annotate',
   isOpen,
   annotations,
+  blocks,
   onSelect,
   onDelete,
   onEdit,
@@ -256,7 +285,19 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   title = 'Annotations',
   titleNote,
   cardParts,
+  renderCardBody,
+  imageRegionSrc,
+  onNavigateAnchor,
 }) => {
+  // `#Heading` links in comment text; nothing is parsed unless the host can navigate.
+  const sectionRefs = useMemo(
+    () => (onNavigateAnchor ? buildSectionRefIndex(blocks) : undefined),
+    [blocks, onNavigateAnchor],
+  );
+  const regionCards = useMemo(
+    () => ({ numbers: imageRegionNumbers(annotations), thumbSrc: imageRegionSrc }),
+    [annotations, imageRegionSrc],
+  );
   const isMobile = useIsMobile();
   const embedded = presentation === 'embedded';
   const mobilePanel = isMobile && !embedded;
@@ -517,8 +558,11 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                             footer={group.isCurrent ? renderCardFooter?.(annotation) : undefined}
                             header={group.isCurrent ? renderCardHeader?.(annotation) : undefined}
                             parts={group.isCurrent ? cardParts?.(annotation) : undefined}
+                            body={group.isCurrent ? renderCardBody?.(annotation) : undefined}
                             mentionSource={mentionSource}
                             unanchored={group.isCurrent ? (unanchoredIds?.has(annotation.id) ?? false) : false}
+                            sectionRefs={group.isCurrent ? sectionRefs : undefined}
+                            onNavigateAnchor={onNavigateAnchor}
                           />
                         );
                         return isReply ? (
@@ -623,6 +667,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   >
                     <AnnotationCard
                       annotation={entry.annotation}
+                      sectionRefs={sectionRefs}
+                      onNavigateAnchor={onNavigateAnchor}
                       isSelected={selectedId === entry.annotation.id}
                       isMe={isCurrentUser(entry.annotation.author)}
                       onSelect={() => onSelect(entry.annotation.id)}
@@ -632,6 +678,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                       footer={renderCardFooter?.(entry.annotation)}
                       header={renderCardHeader?.(entry.annotation)}
                   parts={cardParts?.(entry.annotation)}
+                  body={renderCardBody?.(entry.annotation)}
                       mentionSource={mentionSource}
                       unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                     />
@@ -640,6 +687,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                 <AnnotationCard
                   key={entry.annotation.id}
                   annotation={entry.annotation}
+                  sectionRefs={sectionRefs}
+                  onNavigateAnchor={onNavigateAnchor}
                   isSelected={selectedId === entry.annotation.id}
                   isMe={isCurrentUser(entry.annotation.author)}
                   onSelect={() => onSelect(entry.annotation.id)}
@@ -649,6 +698,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   footer={renderCardFooter?.(entry.annotation)}
                   header={renderCardHeader?.(entry.annotation)}
                   parts={cardParts?.(entry.annotation)}
+                  body={renderCardBody?.(entry.annotation)}
                   mentionSource={mentionSource}
                   unanchored={unanchoredIds?.has(entry.annotation.id) ?? false}
                 />
@@ -691,7 +741,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
       </OverlayScrollArea>
 
       {/* Quick Actions Footer */}
-      {headerCount > 0 && (
+      {headerCount > 0 && (onQuickCopy || (sharingEnabled && onShare)) && (
         <div className="border-t border-border/50 px-3 py-2 flex gap-1.5">
           {onQuickCopy && (
             <button
@@ -745,12 +795,12 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
           className="fixed inset-0 z-[59] bg-background/60 backdrop-blur-sm"
           onClick={onClose}
         />
-        {panel}
+        <RegionCardContext.Provider value={regionCards}>{panel}</RegionCardContext.Provider>
       </>
     );
   }
 
-  return panel;
+  return <RegionCardContext.Provider value={regionCards}>{panel}</RegionCardContext.Provider>;
 };
 
 function formatTimestamp(ts: number): string {
@@ -766,9 +816,38 @@ function formatTimestamp(ts: number): string {
   if (hours < 24) return `${hours}h`;
   if (days < 7) return `${days}d`;
 
-  return new Date(ts).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+  // An older date names its year: "Oct 20" alone reads as this October.
+  const date = new Date(ts);
+  const thisYear = date.getFullYear() === new Date(now).getFullYear();
+  return date.toLocaleDateString(
+    undefined,
+    thisYear ? { month: 'short', day: 'numeric' } : { month: 'short', day: 'numeric', year: 'numeric' },
+  );
 }
 
+/**
+ * A card's "author · time" line. The author truncates (its full name in the
+ * title) while the time never shrinks, so a long name cannot push the time
+ * out; `<bdi>` keeps a right-to-left name from reordering the time around it.
+ * The text reads exactly as before: "Alice (me) · 5m".
+ */
+const CardByline: React.FC<{ author?: string; isMe: boolean; timestamp: number }> = ({ author, isMe, timestamp }) => (
+  <span data-annotation-byline="true" className="flex min-w-0 items-center text-[10px] text-muted-foreground/50">
+    {author ? (
+      <>
+        <HostTitle title={author} cut>
+          <span data-annotation-author="true" className="min-w-0 truncate">
+            <bdi>{author}</bdi>
+          </span>
+        </HostTitle>
+        {isMe ? <span data-annotation-me="true" className="shrink-0 whitespace-pre"> (me)</span> : null}
+        <span className="shrink-0 whitespace-pre"> · </span>
+      </>
+    ) : null}
+    <span data-annotation-time="true" className="shrink-0">{formatTimestamp(timestamp)}</span>
+  </span>
+);
+
 /** Pinned card for committed direct edits: +N/−M summary, expandable unified
  *  diff, and a two-step discard. Not part of the annotation timeline — edits
  *  are document state, not a selection-anchored note. */
@@ -870,6 +949,44 @@ const DirectEditsCard: React.FC<{
   );
 };
 
+/** Comment text, with each `#Heading text` as a link that scrolls to that heading. */
+const AnnotationText: React.FC<{
+  text: string;
+  className: string;
+  sectionRefs?: Map<string, string>;
+  onNavigateAnchor?: (hash: string) => void;
+}> = ({ text, className, sectionRefs, onNavigateAnchor }) => {
+  const parts = React.useMemo(
+    () => (sectionRefs && onNavigateAnchor ? parseSectionRefs(text, sectionRefs) : [text]),
+    [text, sectionRefs, onNavigateAnchor],
+  );
+
+  return (
+    <p className={className}>
+      {parts.map((part, i) =>
+        typeof part === 'string' ? (
+          part
+        ) : (
+          <a
+            key={i}
+            href={`#${part.anchor}`}
+            className="rounded-sm font-medium text-primary underline-offset-2 hover:underline focus-visible:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
+            onClick={(e) => {
+              // The host scrolls; the card's own onSelect would scroll to the
+              // annotation instead, and the URL hash stays as it was.
+              e.preventDefault();
+              e.stopPropagation();
+              onNavigateAnchor!(`#${part.anchor}`);
+            }}
+          >
+            {part.label}
+          </a>
+        ),
+      )}
+    </p>
+  );
+};
+
 /**
  * The plan-annotation card's edit box.
  *
@@ -900,6 +1017,7 @@ const AnnotationEditComposer: React.FC<{
   const mention = useMentionAutocomplete({ text: value, setText: onChange, textareaRef, source: mentionSource });
   const listboxId = `annotation-card-mentions-${useId().replace(/:/g, '')}`;
   const menuOpen = mention.menu !== null;
+  const enterSavesComment = useConfigValue('enterSavesComment');
 
   // Focus-on-open, unchanged: this component mounts exactly when editing starts.
   useEffect(() => {
@@ -914,7 +1032,7 @@ const AnnotationEditComposer: React.FC<{
     // (and only a second Escape cancels the edit), and an arrowed-to row
     // takes Enter. Mod+Enter is never consumed by the menu.
     if (mention.onKeyDown(e)) return;
-    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+    if (isCommentSubmitKey(e, enterSavesComment)) {
       e.preventDefault();
       onSave(mention.mentionIds);
     } else if (e.key === 'Escape') {
@@ -967,21 +1085,32 @@ const AnnotationCard: React.FC<{
   /** The annotation has no live location in the document (host-reported). */
   unanchored?: boolean;
   /** Built-in parts to draw (see `cardParts`). */
-  parts?: { quote?: boolean; images?: boolean };
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, header, mentionSource, unanchored = false, parts }) => {
+  parts?: { quote?: boolean; images?: boolean; text?: boolean };
+  /** Host body, drawn where the comment text goes (see `renderCardBody`). */
+  body?: React.ReactNode;
+  sectionRefs?: Map<string, string>;
+  onNavigateAnchor?: (hash: string) => void;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, header, mentionSource, unanchored = false, parts, body, sectionRefs, onNavigateAnchor }) => {
+  // `text: false`: the stored text is the host's stand-in, never the person's words; the edit box starts empty.
+  const shownText = parts?.text === false ? '' : annotation.text || '';
   const [isEditing, setIsEditing] = useState(false);
-  const [editText, setEditText] = useState(annotation.text || '');
+  const [editText, setEditText] = useState(shownText);
+  // A comment on part of an image (#2100): numbered like its box, with the
+  // crop, file, size and line in place of the quote.
+  const regionCards = useContext(RegionCardContext);
+  const region = regionOf(annotation);
+  const regionNumber = region ? regionCards.numbers.get(annotation.id) : undefined;
 
   // Update editText when annotation.text changes
   useEffect(() => {
     if (!isEditing) {
-      setEditText(annotation.text || '');
+      setEditText(shownText);
     }
-  }, [annotation.text, isEditing]);
+  }, [shownText, isEditing]);
 
   const handleStartEdit = (e: React.MouseEvent) => {
     e.stopPropagation();
-    setEditText(annotation.text || '');
+    setEditText(shownText);
     setIsEditing(true);
   };
 
@@ -998,7 +1127,7 @@ const AnnotationCard: React.FC<{
   };
 
   const handleCancelEdit = () => {
-    setEditText(annotation.text || '');
+    setEditText(shownText);
     setIsEditing(false);
   };
 
@@ -1037,6 +1166,12 @@ const AnnotationCard: React.FC<{
       {/* Header: type word + author · time + actions */}
       <div className="mb-1.5 flex items-center gap-1.5">
         <span className={cn('text-[11px] font-medium', typeColor)}>{typeLabel}</span>
+        {region && regionNumber !== undefined && <RegionNumber n={regionNumber} selected={isSelected} />}
+        {region && (
+          <span data-annotation-region="true" className="text-[9px] px-1.5 py-0.5 rounded font-medium bg-muted text-muted-foreground">
+            Region
+          </span>
+        )}
         {annotation.diffContext && (
           <span className="text-[9px] px-1.5 py-0.5 rounded font-medium bg-muted text-muted-foreground">
             diff
@@ -1056,9 +1191,7 @@ const AnnotationCard: React.FC<{
             </span>
           </HostTitle>
         )}
-        <span className="text-[10px] text-muted-foreground/50 truncate">
-          {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdA)}
-        </span>
+        <CardByline author={annotation.author} isMe={isMe} timestamp={annotation.createdA} />
         {/* Host header slot (a status stamp etc.) — interactions inside it
             must not toggle card selection, exactly like the footer slot.
             Rendered under readOnly too: its contents are host-owned. */}
@@ -1073,7 +1206,7 @@ const AnnotationCard: React.FC<{
           </div>
         )}
         {!readOnly && (
-          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
+          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100">
             {onEdit && annotation.type !== AnnotationType.DELETION && !isEditing && (
               <HostTitle title="Edit annotation" name>
                 <button
@@ -1103,15 +1236,22 @@ const AnnotationCard: React.FC<{
         isEditing ? (
           editComposer
         ) : (
-          <p className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90">
-            {annotation.text}
-          </p>
+          <AnnotationText
+            text={annotation.text || ''}
+            className="whitespace-pre-wrap [overflow-wrap:anywhere] text-[13px] leading-relaxed text-foreground/90"
+            sectionRefs={sectionRefs}
+            onNavigateAnchor={onNavigateAnchor}
+          />
         )
       ) : (
         <>
+          {/* A region shows its crop, file, size and line instead of a quote. */}
+          {region && parts?.quote !== false && (
+            <RegionCardInfo region={region} thumbSrc={regionCards.thumbSrc?.(region.src) ?? null} />
+          )}
           {/* Quote — the annotated text */}
-          {parts?.quote !== false && (
-            <p className="mb-1.5 line-clamp-2 whitespace-pre-wrap font-mono text-[11px] leading-relaxed text-muted-foreground/80">
+          {!region && parts?.quote !== false && (
+            <p className="mb-1.5 line-clamp-2 whitespace-pre-wrap [overflow-wrap:anywhere] font-mono text-[11px] leading-relaxed text-muted-foreground/80">
               "{annotation.originalText}"
             </p>
           )}
@@ -1121,13 +1261,17 @@ const AnnotationCard: React.FC<{
             isEditing ? (
               editComposer
             ) : (
-              annotation.text && (
-                <p className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90">
-                  {annotation.text}
-                </p>
+              shownText && (
+                <AnnotationText
+                  text={shownText}
+                  className="whitespace-pre-wrap [overflow-wrap:anywhere] text-[13px] leading-relaxed text-foreground/90"
+                  sectionRefs={sectionRefs}
+                  onNavigateAnchor={onNavigateAnchor}
+                />
               )
             )
           )}
+          {body != null && body !== false && body}
         </>
       )}
 
@@ -1176,6 +1320,7 @@ const CodeAnnotationCard: React.FC<{
 }> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
+  const enterSavesComment = useConfigValue('enterSavesComment');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
 
   useEffect(() => {
@@ -1224,11 +1369,9 @@ const CodeAnnotationCard: React.FC<{
       {/* Header: type word + author · time + actions */}
       <div className="mb-1.5 flex items-center gap-1.5">
         <span className="text-[11px] font-medium text-primary">Code</span>
-        <span className="text-[10px] text-muted-foreground/50 truncate">
-          {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdAt)}
-        </span>
+        <CardByline author={annotation.author} isMe={isMe} timestamp={annotation.createdAt} />
         {!readOnly && (
-          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
+          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100">
             {onEdit && !isEditing && (
               <HostTitle title="Edit annotation" name>
                 <button
@@ -1261,7 +1404,7 @@ const CodeAnnotationCard: React.FC<{
       </HostTitle>
 
       {annotation.originalCode && (
-        <p className="mt-1.5 line-clamp-2 whitespace-pre-wrap font-mono text-[11px] leading-relaxed text-muted-foreground/80">
+        <p className="mt-1.5 line-clamp-2 whitespace-pre-wrap [overflow-wrap:anywhere] font-mono text-[11px] leading-relaxed text-muted-foreground/80">
           {annotation.originalCode}
         </p>
       )}
@@ -1274,7 +1417,7 @@ const CodeAnnotationCard: React.FC<{
             value={editText}
             onChange={(e) => setEditText(e.target.value)}
             onKeyDown={(e) => {
-              if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+              if (isCommentSubmitKey(e, enterSavesComment)) {
                 e.preventDefault();
                 handleSaveEdit();
               } else if (e.key === 'Escape') {
@@ -1294,7 +1437,7 @@ const CodeAnnotationCard: React.FC<{
         </div>
       ) : (
         annotation.text && (
-          <p className="mt-1.5 whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90">
+          <p className="mt-1.5 whitespace-pre-wrap [overflow-wrap:anywhere] text-[13px] leading-relaxed text-foreground/90">
             {annotation.text}
           </p>
         )

package/components/AnnotationSidebar.tsx

@@ -61,7 +61,7 @@ export const AnnotationSidebar: React.FC<SidebarProps> = ({
                 </span>
                 <button
                   onClick={(e) => { e.stopPropagation(); onDelete(ann.id); }}
-                  className="opacity-0 group-hover:opacity-100 text-muted-foreground hover:text-destructive transition-all p-1 rounded hover:bg-destructive/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  className="opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100 text-muted-foreground hover:text-destructive transition-all p-1 rounded hover:bg-destructive/10 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
                   title="Remove Annotation"
                 >
                   <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>

package/components/AnnotationToolbar.tsx

@@ -4,6 +4,7 @@ import { createPortal } from "react-dom";
 import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";
 import { type QuickLabel, getQuickLabels, quickLabelIndexForDigit, THUMBS_UP_LABEL } from "../utils/quickLabels";
 import { copyTextToClipboard } from "../utils/clipboard";
+import { copyRichSelection, richCopyOutcomeLabel, type RichCopyOutcome, type RichCopySource } from "../utils/richClipboard";
 import { acquireTypeToCommentCapture } from "../shortcuts/plan-review/annotationMode.shortcuts";
 import { FloatingQuickLabelPicker } from "./FloatingQuickLabelPicker";
 import { FloatingSelectionActionsPicker } from "./SelectionActionsDropdown";
@@ -30,6 +31,12 @@ interface AnnotationToolbarProps {
   onQuickLabel?: (label: QuickLabel) => void;
   /** Text to copy when the button is clicked */
   copyText?: string;
+  /** Builds the captured text selection's sanitized HTML and plain text when
+   *  Copy is pressed (never before). When present, Copy writes text/html plus
+   *  text/plain in one clipboard write (a plain field still pastes plain
+   *  text), and the Copy button shows even where hideCopyButton hides it.
+   *  Absent: Copy copies plain text, exactly as before. No shortcut. */
+  getRichCopy?: () => RichCopySource | Promise<RichCopySource>;
   /** Comment-only surfaces (HTML / live-app viewer): hide the Delete action,
    *  the quick-label picker, and the Alt+digit label shortcuts. A provided
    *  onQuickLabel then renders ONLY the hardcoded 👍 "Looks good" button —
@@ -57,7 +64,7 @@ interface AnnotationToolbarProps {
    * this toolbar. The one-click 👍 is a separate affordance and is unaffected.
    */
   quickLabels?: boolean;
-  /** Hide the copy button (set when a keyboard copy handler exists) */
+  /** Hide the plain copy button (set when a keyboard copy handler exists) */
   hideCopyButton?: boolean;
   /** Close toolbar when element scrolls out of viewport */
   closeOnScrollOut?: boolean;
@@ -79,6 +86,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   selectionActionsIcon,
   quickLabels: quickLabelsEnabled = true,
   copyText,
+  getRichCopy,
   commentOnly = false,
   hideCopyButton = false,
   closeOnScrollOut = false,
@@ -88,6 +96,10 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
 }) => {
   const [position, setPosition] = useState<{ top: number; left?: number; right?: number } | null>(null);
   const [copied, setCopied] = useState(false);
+  const [richCopied, setRichCopied] = useState<RichCopyOutcome | false>(false);
+  const richCopyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const richCopySelectionRef = useRef({ element, getRichCopy });
+  richCopySelectionRef.current = { element, getRichCopy };
   const [showQuickLabels, setShowQuickLabels] = useState(false);
   const [showSelectionActions, setShowSelectionActions] = useState(false);
   const toolbarRef = useRef<HTMLDivElement>(null);
@@ -107,7 +119,18 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   const selectionActionsOpen = showSelectionActions && hasSelectionActions;
   const quickLabelsOpen = showQuickLabels && !commentOnly && quickLabelsEnabled;
 
-  useEffect(() => { setCopied(false); }, [element]);
+  useEffect(() => {
+    setCopied(false);
+    setRichCopied(false);
+  }, [element]);
+  useEffect(() => {
+    setRichCopied(false);
+    if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+    richCopyTimeoutRef.current = null;
+  }, [element, getRichCopy]);
+  useEffect(() => () => {
+    if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+  }, []);
 
   const handleCopy = async () => {
     let textToCopy = copyText;
@@ -121,6 +144,24 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
     }
   };
 
+  const handleRichCopy = async () => {
+    setRichCopied(false);
+    const build = getRichCopy;
+    if (!build) return;
+    const fallback = copyText || element.querySelector('code')?.textContent || element.textContent || '';
+    const result = await copyRichSelection(build, fallback);
+    const current = richCopySelectionRef.current;
+    if (current.element !== element || current.getRichCopy !== build) return;
+    if (result) {
+      setRichCopied(result);
+      if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+      richCopyTimeoutRef.current = setTimeout(() => {
+        setRichCopied(false);
+        richCopyTimeoutRef.current = null;
+      }, 1500);
+    }
+  };
+
   // Update position on scroll/resize
   useEffect(() => {
     const updatePosition = () => {
@@ -252,14 +293,28 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         }
       `}</style>
       <div data-pn-annotation-toolbar-row="true" className="flex items-center p-1 gap-0.5">
-        {!hideCopyButton && (
+        {(!hideCopyButton || getRichCopy) && (
           <>
-            <ToolbarButton
-              onClick={handleCopy}
-              icon={copied ? <CheckIcon /> : <CopyIcon />}
-              label={copied ? "Copied!" : "Copy"}
-              className={copied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
-            />
+            {getRichCopy ? (
+              // One Copy button: rich text (text/html plus text/plain) where
+              // the host turned rich copy on. "Copied!" for a rich copy; a
+              // plain-text fallback says what went on the clipboard.
+              <ToolbarButton
+                onClick={handleRichCopy}
+                icon={richCopied ? <CheckIcon /> : <CopyIcon />}
+                label={!richCopied ? "Copy"
+                  : richCopied.copied === 'rich' ? "Copied!"
+                  : richCopyOutcomeLabel(richCopied)}
+                className={richCopied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
+              />
+            ) : (
+              <ToolbarButton
+                onClick={handleCopy}
+                icon={copied ? <CheckIcon /> : <CopyIcon />}
+                label={copied ? "Copied!" : "Copy"}
+                className={copied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
+              />
+            )}
             <div className="w-px h-5 bg-border mx-0.5" />
           </>
         )}