@plannotator/ui 0.23.0 → 0.24.0

package/components/AnnotationPanel.tsx

@@ -1,5 +1,5 @@
 import React, { useState, useRef, useEffect } from 'react';
-import { Annotation, AnnotationType, Block, type CodeAnnotation, type EditorAnnotation } from '../types';
+import { AnnotationType, type Annotation, type Block, type CodeAnnotation, type EditorAnnotation } from '../types';
 import { isCurrentUser } from '../utils/identity';
 import { ImageThumbnail } from './ImageThumbnail';
 import { EditorAnnotationCard } from './EditorAnnotationCard';
@@ -73,12 +73,18 @@ interface PanelProps {
   /** Committed direct edits to one or more documents. Rendered as pinned cards
     *  above the annotation timeline with expandable unified diffs. */
   directEdits?: DirectEditsPanelItem[] | null;
+  /** Host slot rendered at the foot of each plan-annotation card (e.g. reply/
+    *  resolve UI). The panel stays presentation-only; clicks inside the slot
+    *  do not select the card. Default: nothing rendered. */
+  renderCardFooter?: (annotation: Annotation) => React.ReactNode;
+  /** Hide every mutation affordance (delete/edit buttons on all card kinds).
+    *  Selection and scrolling still work. Default false — today's behavior. */
+  readOnly?: boolean;
 }
 
 export const AnnotationPanel: React.FC<PanelProps> = ({
   isOpen,
   annotations,
-  blocks,
   onSelect,
   onDelete,
   onEdit,
@@ -97,6 +103,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   otherFileAnnotations,
   onOtherFileAnnotationsClick,
   directEdits = null,
+  renderCardFooter,
+  readOnly = false,
 }) => {
   const isMobile = useIsMobile();
   const [copiedText, setCopiedText] = useState(false);
@@ -195,6 +203,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onSelect={() => onSelect(entry.annotation.id)}
                   onDelete={() => onDelete(entry.annotation.id)}
                   onEdit={onEdit ? (updates: Partial<Annotation>) => onEdit(entry.annotation.id, updates) : undefined}
+                  readOnly={readOnly}
+                  footer={renderCardFooter?.(entry.annotation)}
                 />
               ) : (
                 <CodeAnnotationCard
@@ -205,6 +215,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   onSelect={() => onSelectCodeAnnotation?.(entry.annotation.id)}
                   onDelete={() => onDeleteCodeAnnotation?.(entry.annotation.id)}
                   onEdit={onEditCodeAnnotation ? (updates: Partial<CodeAnnotation>) => onEditCodeAnnotation(entry.annotation.id, updates) : undefined}
+                  readOnly={readOnly}
                 />
               )
             ))}
@@ -221,7 +232,7 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   <EditorAnnotationCard
                     key={ann.id}
                     annotation={ann}
-                    onDelete={() => onDeleteEditorAnnotation?.(ann.id)}
+                    onDelete={readOnly ? undefined : () => onDeleteEditorAnnotation?.(ann.id)}
                   />
                 ))}
               </>
@@ -418,7 +429,9 @@ const AnnotationCard: React.FC<{
   onSelect: () => void;
   onDelete: () => void;
   onEdit?: (updates: Partial<Annotation>) => void;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit }) => {
+  readOnly?: boolean;
+  footer?: React.ReactNode;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -517,26 +530,28 @@ const AnnotationCard: React.FC<{
         <span className="text-[10px] text-muted-foreground/50 truncate">
           {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdA)}
         </span>
-        <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
-          {onEdit && annotation.type !== AnnotationType.DELETION && !isEditing && (
+        {!readOnly && (
+          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
+            {onEdit && annotation.type !== AnnotationType.DELETION && !isEditing && (
+              <button
+                type="button"
+                onClick={handleStartEdit}
+                className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground"
+                title="Edit annotation"
+              >
+                <PencilIcon />
+              </button>
+            )}
             <button
               type="button"
-              onClick={handleStartEdit}
-              className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground"
-              title="Edit annotation"
+              onClick={(e: React.MouseEvent<HTMLButtonElement>) => { e.stopPropagation(); onDelete(); }}
+              className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-destructive"
+              title="Delete annotation"
             >
-              <PencilIcon />
+              <TrashCardIcon />
             </button>
-          )}
-          <button
-            type="button"
-            onClick={(e: React.MouseEvent<HTMLButtonElement>) => { e.stopPropagation(); onDelete(); }}
-            className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-destructive"
-            title="Delete annotation"
-          >
-            <TrashCardIcon />
-          </button>
-        </div>
+          </div>
+        )}
       </div>
 
       {/* Global Comment - show text directly */}
@@ -585,6 +600,19 @@ const AnnotationCard: React.FC<{
           ))}
         </div>
       )}
+
+      {/* Host footer slot (reply/resolve UI etc.) — interactions inside it
+          must not toggle card selection. */}
+      {footer != null && footer !== false && (
+        <div
+          data-annotation-card-footer="true"
+          className="mt-2"
+          onClick={(e: React.MouseEvent) => e.stopPropagation()}
+          onKeyDown={(e: React.KeyboardEvent) => e.stopPropagation()}
+        >
+          {footer}
+        </div>
+      )}
     </div>
   );
 };
@@ -596,7 +624,8 @@ const CodeAnnotationCard: React.FC<{
   onSelect: () => void;
   onDelete: () => void;
   onEdit?: (updates: Partial<CodeAnnotation>) => void;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit }) => {
+  readOnly?: boolean;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -650,26 +679,28 @@ const CodeAnnotationCard: React.FC<{
         <span className="text-[10px] text-muted-foreground/50 truncate">
           {annotation.author ? `${annotation.author}${isMe ? ' (me)' : ''} · ` : ''}{formatTimestamp(annotation.createdAt)}
         </span>
-        <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
-          {onEdit && !isEditing && (
+        {!readOnly && (
+          <div className="ml-auto flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100 [@media(hover:none)]:opacity-100">
+            {onEdit && !isEditing && (
+              <button
+                type="button"
+                onClick={(e) => { e.stopPropagation(); setIsEditing(true); }}
+                className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground"
+                title="Edit annotation"
+              >
+                <PencilIcon />
+              </button>
+            )}
             <button
               type="button"
-              onClick={(e) => { e.stopPropagation(); setIsEditing(true); }}
-              className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-foreground"
-              title="Edit annotation"
+              onClick={(e) => { e.stopPropagation(); onDelete(); }}
+              className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-destructive"
+              title="Delete annotation"
             >
-              <PencilIcon />
+              <TrashCardIcon />
             </button>
-          )}
-          <button
-            type="button"
-            onClick={(e) => { e.stopPropagation(); onDelete(); }}
-            className="relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] hover:text-destructive"
-            title="Delete annotation"
-          >
-            <TrashCardIcon />
-          </button>
-        </div>
+          </div>
+        )}
       </div>
 
       {/* File / line meta */}

package/components/AnnotationToolbar.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useRef, useMemo, useCallback } from "react";
+import React, { useState, useEffect, useRef, useMemo } from "react";
 import { AnnotationType } from "../types";
 import { createPortal } from "react-dom";
 import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";

package/components/BlockRenderer.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Block } from "../types";
+import type { Block } from "../types";
 import { InlineMarkdown } from "./InlineMarkdown";
 import { ListItemBody } from "./ListItemBody";
 import { CodeBlock } from "./blocks/CodeBlock";

package/components/EditorAnnotationCard.tsx

@@ -14,7 +14,8 @@ type EditorAnnotationVariant = 'plan' | 'code-review';
 
 interface EditorAnnotationCardProps {
   annotation: EditorAnnotation;
-  onDelete: () => void;
+  /** Omit to render the card read-only (no delete affordance). */
+  onDelete?: () => void;
   variant?: EditorAnnotationVariant;
 }
 
@@ -38,15 +39,17 @@ export const EditorAnnotationCard: React.FC<EditorAnnotationCardProps> = ({ anno
         <span className="text-[10px] font-mono text-muted-foreground/50 truncate" title={annotation.filePath}>
           {annotation.filePath}:{lineRange}
         </span>
-        <button
-          onClick={(e) => { e.stopPropagation(); onDelete(); }}
-          className="ml-auto relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] opacity-0 group-hover:opacity-100 [@media(hover:none)]:opacity-100 hover:text-destructive"
-          title="Delete annotation"
-        >
-          <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-            <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
-          </svg>
-        </button>
+        {onDelete && (
+          <button
+            onClick={(e) => { e.stopPropagation(); onDelete(); }}
+            className="ml-auto relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] opacity-0 group-hover:opacity-100 [@media(hover:none)]:opacity-100 hover:text-destructive"
+            title="Delete annotation"
+          >
+            <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+            </svg>
+          </button>
+        )}
       </div>
 
       {/* Selected text */}

package/components/ImageAnnotator/index.tsx

@@ -2,7 +2,7 @@ import React, { useState, useCallback, useEffect, useRef } from 'react';
 import { Canvas } from './Canvas';
 import { Toolbar } from './Toolbar';
 import { renderStroke } from './utils';
-import type { Point, Stroke, Tool, AnnotatorState } from './types';
+import type { Point, AnnotatorState } from './types';
 import { DEFAULT_STATE } from './types';
 
 interface ImageAnnotatorProps {

package/components/Viewer.tsx

@@ -1,8 +1,8 @@
 import React, { useRef, useState, useEffect, useMemo, forwardRef, useImperativeHandle, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import hljs from 'highlight.js';
-import { Block, Annotation, AnnotationType, EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
-import { Frontmatter, computeListIndices, groupBlocks } from '../utils/parser';
+import { AnnotationType, type Block, type Annotation, type EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
+import { computeListIndices, groupBlocks, type Frontmatter } from '../utils/parser';
 import { buildHeadingSlugMap } from '../utils/slugify';
 import { BlockRenderer } from './BlockRenderer';
 import { CodeBlock } from './blocks/CodeBlock';
@@ -11,7 +11,6 @@ import { TableToolbar } from './blocks/TableToolbar';
 import { TablePopout } from './blocks/TablePopout';
 import { CodePathValidationContext } from './CodePathValidationContext';
 import { useValidatedCodePaths } from '../hooks/useValidatedCodePaths';
-import { ListMarker } from './ListMarker';
 import { AnnotationToolbar } from './AnnotationToolbar';
 import { FloatingQuickLabelPicker } from './FloatingQuickLabelPicker';
 
@@ -33,13 +32,12 @@ class ToolbarErrorBoundary extends React.Component<
   }
 }
 
-import { CommentPopover, type CommentAskAIContext, type CommentAskAIHandler } from './CommentPopover';
+import { CommentPopover, type CommentAskAIHandler } from './CommentPopover';
 import { TaterSpriteSitting } from './TaterSpriteSitting';
 import { AttachmentsButton } from './AttachmentsButton';
 import { MessagesIcon } from './icons/MessagesIcon';
 import { GraphvizBlock } from './GraphvizBlock';
 import { MermaidBlock } from './MermaidBlock';
-import { getImageSrc } from './ImageThumbnail';
 import { isGraphvizLanguage, isMermaidLanguage } from './diagramLanguages';
 import { getIdentity } from '../utils/identity';
 import { type QuickLabel } from '../utils/quickLabels';
@@ -112,6 +110,15 @@ interface ViewerProps {
   onToggleCheckbox?: (blockId: string, checked: boolean) => void;
   checkboxOverrides?: Map<string, boolean>;
   onAskAI?: CommentAskAIHandler;
+  /** Whether comment popovers offer image attachments. Hosts without an
+   *  uploadTransport pass false so the attach affordance never dead-ends.
+   *  Default true — today's behavior. */
+  allowImages?: boolean;
+  /** View-only mode: suppresses every annotation-creation entry point
+   *  (selection toolbar, comment popovers, quick labels, pinpoint, global
+   *  comment, attachments, checkbox toggles). Existing annotations still
+   *  render and remain selectable. Default false — today's behavior. */
+  readOnly?: boolean;
 }
 
 export interface ViewerHandle {
@@ -191,6 +198,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   onToggleCheckbox,
   checkboxOverrides,
   onAskAI,
+  allowImages = true,
+  readOnly = false,
 }, ref) => {
   const [copied, setCopied] = useState(false);
   const [lightbox, setLightbox] = useState<{ src: string; alt: string } | null>(null);
@@ -283,6 +292,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     onSelectAnnotation,
     selectedAnnotationId,
     mode,
+    enabled: !readOnly,
   });
 
   // Refs for code block annotation path
@@ -319,7 +329,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     containerRef,
     highlighterRef,
     inputMethod,
-    enabled: !toolbarState && !hookCommentPopover && !viewerCommentPopover && !hookQuickLabelPicker && !codeBlockQuickLabelPicker && !(isPlanDiffActive ?? false),
+    enabled: !readOnly && !toolbarState && !hookCommentPopover && !viewerCommentPopover && !hookQuickLabelPicker && !codeBlockQuickLabelPicker && !(isPlanDiffActive ?? false),
     onCodeBlockClick: handlePinpointCodeBlockClick,
   });
 
@@ -612,7 +622,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
           )}
 
           {/* Attachments button */}
-          {onAddGlobalAttachment && onRemoveGlobalAttachment && (
+          {!readOnly && onAddGlobalAttachment && onRemoveGlobalAttachment && (
             <AttachmentsButton
               images={globalAttachments}
               onAdd={onAddGlobalAttachment}
@@ -623,6 +633,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
           )}
 
           {/* <span className="md:hidden">Comment</span><span className="hidden md:inline">Global comment</span> button */}
+          {!readOnly && (
           <button
             ref={globalCommentButtonRef}
             onClick={() => {
@@ -641,6 +652,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
             {actionsLabelMode === 'full' && <span>Global comment</span>}
             {actionsLabelMode === 'short' && <span>Comment</span>}
           </button>
+          )}
 
           {/* Copy plan/file button */}
           <button
@@ -683,7 +695,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                       orderedIndex={indices[i]}
                       onOpenLinkedDoc={onOpenLinkedDoc}
                       onOpenCodeFile={onOpenCodeFile}
-                      onToggleCheckbox={onToggleCheckbox}
+                      onToggleCheckbox={readOnly ? undefined : onToggleCheckbox}
                       checkboxOverrides={checkboxOverrides}
                       githubRepo={repoInfo?.display}
                       headingAnchorId={headingSlugMap.get(block.id)}
@@ -758,7 +770,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               isHovered={inputMethod !== 'pinpoint' && hoveredCodeBlock?.block.id === group.block.id}
             />
           ) : (
-            <BlockRenderer imageBaseDir={imageBaseDir} onImageClick={(src, alt) => setLightbox({ src, alt })} key={group.block.id} block={group.block} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} onNavigateAnchor={scrollToAnchor} onToggleCheckbox={onToggleCheckbox} checkboxOverrides={checkboxOverrides} githubRepo={repoInfo?.display} headingAnchorId={headingSlugMap.get(group.block.id)} />
+            <BlockRenderer imageBaseDir={imageBaseDir} onImageClick={(src, alt) => setLightbox({ src, alt })} key={group.block.id} block={group.block} onOpenLinkedDoc={onOpenLinkedDoc} onOpenCodeFile={onOpenCodeFile} onNavigateAnchor={scrollToAnchor} onToggleCheckbox={readOnly ? undefined : onToggleCheckbox} checkboxOverrides={checkboxOverrides} githubRepo={repoInfo?.display} headingAnchorId={headingSlugMap.get(group.block.id)} />
           )
         )}
 
@@ -875,6 +887,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
               initialText={hookCommentPopover.initialText}
               onSubmit={hookCommentSubmit}
               onClose={hookCommentClose}
+              allowImages={allowImages}
               onAskAI={onAskAI}
               askAIContext={{
                 kind: 'selection',
@@ -892,6 +905,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
             initialText={viewerCommentPopover.initialText}
             onSubmit={handleViewerCommentSubmit}
             onClose={handleViewerCommentClose}
+            allowImages={allowImages}
             onAskAI={onAskAI}
             askAIContext={{
               kind: viewerCommentPopover.isGlobal ? 'general' : 'selection',

package/components/blocks/CodeBlock.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useRef, useEffect, useCallback } from 'react';
 import hljs from 'highlight.js';
 import 'highlight.js/styles/github-dark.css';
-import { Block } from '../../types';
+import type { Block } from '../../types';
 
 interface CodeBlockProps {
   block: Block;
@@ -10,7 +10,7 @@ interface CodeBlockProps {
   isHovered: boolean;
 }
 
-export const CodeBlock: React.FC<CodeBlockProps> = ({ block, onHover, onLeave, isHovered }) => {
+export const CodeBlock: React.FC<CodeBlockProps> = ({ block, onHover, onLeave }) => {
   const [copied, setCopied] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
   const codeRef = useRef<HTMLElement>(null);

package/components/blocks/HtmlBlock.tsx

@@ -1,6 +1,6 @@
 import React, { useRef, useEffect } from "react";
 import { isCodeFilePath } from "@plannotator/core/code-file";
-import { Block } from "../../types";
+import type { Block } from "../../types";
 import { sanitizeBlockHtml } from "../../utils/sanitizeHtml";
 import { getImageSrc } from "../ImageThumbnail";
 

package/components/blocks/TableBlock.tsx

@@ -1,5 +1,5 @@
 import React, { useRef } from 'react';
-import { Block } from '../../types';
+import type { Block } from '../../types';
 import { InlineMarkdown } from '../InlineMarkdown';
 
 interface TableBlockProps {

package/components/blocks/TablePopout.tsx

@@ -9,7 +9,7 @@ import {
   type ColumnDef,
   type SortingState,
 } from '@tanstack/react-table';
-import { Block } from '../../types';
+import type { Block } from '../../types';
 import { InlineMarkdown } from '../InlineMarkdown';
 import { PopoutDialog } from '../PopoutDialog';
 import { parseTableContent, buildCsvFromRows, buildMarkdownTable } from './TableBlock';

package/hooks/useAnnotationHighlighter.ts

@@ -174,6 +174,12 @@ const escapeAttrValue = (value: string): string => {
   return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 };
 
+/** Whitespace-insensitive comparison for restore verification: a highlight
+ *  spanning element boundaries legitimately differs from `originalText` in
+ *  whitespace, so only content differences count as a mismatch. */
+const normalizeForRestoreCompare = (value: string): string =>
+  value.replace(/\s+/g, ' ').trim();
+
 const applyMathAnnotationClass = (
   element: HTMLElement,
   id: string,
@@ -227,6 +233,15 @@ export interface UseAnnotationHighlighterOptions {
   selectedAnnotationId: string | null;
   mode: EditorMode;
   enabled?: boolean;
+  /** Opt-in: after a meta-based restore (`fromStore`), verify the painted text
+   *  matches the annotation's `originalText` (whitespace-normalized). On
+   *  mismatch the wrong highlight is removed and the text-search fallback
+   *  runs instead; if that also fails, `onRestoreMismatch` fires and nothing
+   *  is painted. Default false — today's behavior (positions are trusted). */
+  verifyRestoredContent?: boolean;
+  /** Fires when a restore was rejected (content mismatch) and the text-search
+   *  fallback could not re-anchor the annotation either. */
+  onRestoreMismatch?: (annotation: Annotation, restoredText: string) => void;
 }
 
 export interface UseAnnotationHighlighterReturn {
@@ -258,6 +273,8 @@ export function useAnnotationHighlighter({
   selectedAnnotationId,
   mode,
   enabled = true,
+  verifyRestoredContent = false,
+  onRestoreMismatch,
 }: UseAnnotationHighlighterOptions): UseAnnotationHighlighterReturn {
   const highlighterRef = useRef<Highlighter | null>(null);
   const modeRef = useRef<EditorMode>(mode);
@@ -278,6 +295,8 @@ export function useAnnotationHighlighter({
   useEffect(() => { modeRef.current = mode; }, [mode]);
   useEffect(() => { onAddAnnotationRef.current = onAddAnnotation; }, [onAddAnnotation]);
   useEffect(() => { onSelectAnnotationRef.current = onSelectAnnotation; }, [onSelectAnnotation]);
+  const onRestoreMismatchRef = useRef(onRestoreMismatch);
+  useEffect(() => { onRestoreMismatchRef.current = onRestoreMismatch; }, [onRestoreMismatch]);
 
   const clearPendingSelection = useCallback(() => {
     pendingSourceRef.current = null;
@@ -625,23 +644,42 @@ export function useAnnotationHighlighter({
         }
       }
 
+      // When a meta-based restore paints text that no longer matches the
+      // anchor's originalText (document drift), remember what it painted so
+      // the mismatch can be reported if the text fallback also fails.
+      let rejectedRestoreText: string | null = null;
+
       if (ann.startMeta && ann.endMeta) {
         try {
           highlighter.fromStore(ann.startMeta, ann.endMeta, ann.originalText, ann.id);
           const restoredDoms = highlighter.getDoms(ann.id);
           if (restoredDoms && restoredDoms.length > 0) {
-            if (ann.type === AnnotationType.DELETION) {
-              highlighter.addClass('deletion', ann.id);
-            } else if (ann.type === AnnotationType.COMMENT) {
-              highlighter.addClass('comment', ann.id);
+            const restoredText = restoredDoms.map(dom => dom.textContent ?? '').join('');
+            if (
+              verifyRestoredContent &&
+              normalizeForRestoreCompare(restoredText) !== normalizeForRestoreCompare(ann.originalText)
+            ) {
+              // Positions resolved, but onto the WRONG text — remove the bad
+              // highlight and fall through to the text-search fallback.
+              try { highlighter.remove(ann.id); } catch {}
+              rejectedRestoreText = restoredText;
+            } else {
+              if (ann.type === AnnotationType.DELETION) {
+                highlighter.addClass('deletion', ann.id);
+              } else if (ann.type === AnnotationType.COMMENT) {
+                highlighter.addClass('comment', ann.id);
+              }
+              return;
             }
-            return;
           }
         } catch {}
       }
 
       const range = findTextInDOM(ann.originalText);
       if (!range) {
+        if (rejectedRestoreText !== null) {
+          onRestoreMismatchRef.current?.(ann, rejectedRestoreText);
+        }
         console.warn(`Could not find text for annotation ${ann.id}: "${ann.originalText.slice(0, 50)}..."`);
         return;
       }
@@ -720,7 +758,7 @@ export function useAnnotationHighlighter({
         console.warn(`Failed to apply highlight for annotation ${ann.id}:`, e);
       }
     });
-  }, [findMathElementsForAnnotation, findTextInDOM]);
+  }, [findMathElementsForAnnotation, findTextInDOM, verifyRestoredContent]);
 
   const removeHighlight = useCallback((id: string) => {
     highlighterRef.current?.remove(id);

package/hooks/useCodeAnnotationDraft.ts

@@ -20,11 +20,6 @@ interface DraftData {
   ts: number;
 }
 
-interface MissingDraftData {
-  found?: false;
-  draftGeneration?: number;
-}
-
 function readDraftGeneration(value: unknown): number | null {
   return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
 }

package/hooks/usePinpoint.ts

@@ -1,7 +1,7 @@
-import { useEffect, useState, useCallback, type RefObject } from 'react';
+import { useEffect, useState, type RefObject } from 'react';
 import type Highlighter from '@plannotator/web-highlighter';
 import type { InputMethod } from '../types';
-import { resolvePinpointTarget, type PinpointTarget } from '../utils/blockTargeting';
+import { resolvePinpointTarget } from '../utils/blockTargeting';
 
 export interface UsePinpointOptions {
   containerRef: RefObject<HTMLElement | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",

package/utils/parser.ts

@@ -1,4 +1,4 @@
-import { Block, type Annotation, type CodeAnnotation, type EditorAnnotation, type ImageAttachment } from '../types';
+import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachment } from '../types';
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
 
 /**

package/utils/sharing.ts

@@ -8,7 +8,7 @@
  * Inspired by textarea.my's approach.
  */
 
-import { Annotation, AnnotationType, type ImageAttachment } from '../types';
+import { AnnotationType, type Annotation, type ImageAttachment } from '../types';
 import { compress, decompress } from '@plannotator/core/compress';
 import { encrypt, decrypt } from '@plannotator/core/crypto';