@plannotator/ui 0.23.0 → 0.25.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/components/html-viewer/HtmlViewer.tsx

@@ -17,39 +17,16 @@ import { CommentPopover, type CommentAskAIHandler } from "../CommentPopover";
 import { FloatingQuickLabelPicker } from "../FloatingQuickLabelPicker";
 import type { ViewerHandle } from "../Viewer";
 import { useHtmlAnnotation } from "./useHtmlAnnotation";
-import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+import {
+  THEME_TOKENS,
+  buildSrcdocInjection,
+  buildThemeTokenPayload,
+  hasHostThemeOptIn,
+  injectIntoHead,
+} from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
 
-const THEME_TOKENS = [
-  "--background",
-  "--foreground",
-  "--card",
-  "--card-foreground",
-  "--primary",
-  "--primary-foreground",
-  "--secondary",
-  "--secondary-foreground",
-  "--muted",
-  "--muted-foreground",
-  "--accent",
-  "--accent-foreground",
-  "--destructive",
-  "--destructive-foreground",
-  "--success",
-  "--success-foreground",
-  "--warning",
-  "--warning-foreground",
-  "--border",
-  "--input",
-  "--ring",
-  "--code-bg",
-  "--focus-highlight",
-  "--font-sans",
-  "--font-mono",
-  "--radius",
-] as const;
-
 function readThemeTokens(): Record<string, string> {
   const style = getComputedStyle(document.documentElement);
   const tokens: Record<string, string> = {};
@@ -124,26 +101,19 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       contextText: string;
     } | null>(null);
 
-    const srcdoc = useMemo(() => {
-      const tokens = readThemeTokens();
-      let themeCSS = ":root {\n";
-      for (const [key, val] of Object.entries(tokens)) {
-        themeCSS += `  ${key}: ${val};\n`;
-      }
-      themeCSS += "}\n";
-      if (isLightTheme()) themeCSS += ":root { color-scheme: light; }\n:root.light, :root { }\n";
+    // Host theming is opt-in per document (Plannotator-generated artifacts tag
+    // themselves); arbitrary HTML renders untouched, like a standalone tab.
+    const hostTheme = useMemo(() => hasHostThemeOptIn(rawHtml), [rawHtml]);
 
-      // Version-diff highlights: htmlDiff wraps changed text in <ins>/<del>.
-      const diffCSS =
-        "ins{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
-        "del{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
-      const injection = `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
-      const headClose = rawHtml.indexOf("</head>");
-      if (headClose !== -1) {
-        return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
-      }
-      return injection + rawHtml;
-    }, [rawHtml]);
+    const srcdoc = useMemo(() => {
+      const injection = buildSrcdocInjection({
+        tokens: readThemeTokens(),
+        isLight: isLightTheme(),
+        hostTheme,
+        diffActive: !!diffActive,
+      });
+      return injectIntoHead(rawHtml, injection);
+    }, [rawHtml, hostTheme, diffActive]);
 
     const handleResize = useCallback((height: number) => {
       setIframeHeight(height);
@@ -189,9 +159,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useEffect(() => {
       if (!iframeReady) return;
       function sendTheme() {
-        const tokens = readThemeTokens();
         iframeRef.current?.contentWindow?.postMessage(
-          { type: `${PREFIX}theme`, tokens, isLight: isLightTheme() },
+          {
+            type: `${PREFIX}theme`,
+            tokens: buildThemeTokenPayload(readThemeTokens(), hostTheme),
+            isLight: isLightTheme(),
+            hostTheme,
+          },
           "*",
         );
       }
@@ -202,7 +176,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         attributeFilter: ["class", "style"],
       });
       return () => observer.disconnect();
-    }, [iframeReady]);
+    }, [iframeReady, hostTheme]);
 
     useImperativeHandle(ref, () => ({
       removeHighlight: hook.removeHighlight,

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

@@ -9,6 +9,11 @@
  * No external dependencies.
  */
 
+/**
+ * Reads only viewer-namespaced \`--pn-*\` variables (with fallbacks): arbitrary
+ * documents may define bare token names like \`--accent\` for themselves, and the
+ * viewer must never depend on — or collide with — the author's namespace.
+ */
 export const ANNOTATION_HIGHLIGHT_CSS = `
 .annotation-highlight {
   border-radius: 2px;
@@ -17,33 +22,33 @@ export const ANNOTATION_HIGHLIGHT_CSS = `
   cursor: pointer;
 }
 .annotation-highlight.deletion {
-  background: oklch(from var(--destructive, #c0392b) l c h / 0.35);
+  background: oklch(from var(--pn-destructive, #c0392b) l c h / 0.35);
   text-decoration: line-through;
-  text-decoration-color: var(--destructive, #c0392b);
+  text-decoration-color: var(--pn-destructive, #c0392b);
   text-decoration-thickness: 2px;
 }
 .annotation-highlight.comment {
   background: oklch(0.70 0.18 60 / 0.3);
-  border-bottom: 2px solid var(--accent, #d97757);
+  border-bottom: 2px solid var(--pn-accent, #d97757);
 }
 .annotation-highlight.focused {
-  background: oklch(from var(--focus-highlight, #4493f8) l c h / 0.45) !important;
-  box-shadow: 0 0 8px oklch(from var(--focus-highlight, #4493f8) l c h / 0.4);
-  border-bottom: 2px solid var(--focus-highlight, #4493f8);
+  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.45) !important;
+  box-shadow: 0 0 8px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.4);
+  border-bottom: 2px solid var(--pn-focus-highlight, #4493f8);
   filter: none;
 }
 .annotation-highlight:hover {
   filter: brightness(1.2);
 }
 .plannotator-pinpoint-hover {
-  outline: 2px solid var(--focus-highlight, #4493f8) !important;
+  outline: 2px solid var(--pn-focus-highlight, #4493f8) !important;
   outline-offset: 1px;
   cursor: crosshair !important;
 }
 /* SVG nodes can't take a CSS outline — stroke their shapes instead. */
 .plannotator-pinpoint-hover rect, .plannotator-pinpoint-hover path,
 .plannotator-pinpoint-hover circle, .plannotator-pinpoint-hover ellipse, .plannotator-pinpoint-hover polygon {
-  stroke: var(--focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
+  stroke: var(--pn-focus-highlight, #4493f8) !important; stroke-width: 2.5px !important;
 }
 `;
 
@@ -51,15 +56,23 @@ export const BRIDGE_SCRIPT = `(function() {
   var PREFIX = 'plannotator-bridge-';
 
   // --- Theme ---
+  // The author owns this document. Unless it opted in to host theming
+  // (hostTheme), only viewer-namespaced --pn-* properties may be written to its
+  // root, and its class list is never touched.
   window.addEventListener('message', function(e) {
     if (!e.data || e.data.type !== PREFIX + 'theme') return;
     var root = document.documentElement;
-    var tokens = e.data.tokens;
+    var tokens = e.data.tokens || {};
+    var hostTheme = !!e.data.hostTheme;
     for (var key in tokens) {
-      if (tokens.hasOwnProperty(key)) root.style.setProperty(key, tokens[key]);
+      if (!tokens.hasOwnProperty(key)) continue;
+      if (!hostTheme && key.indexOf('--pn-') !== 0) continue;
+      root.style.setProperty(key, tokens[key]);
+    }
+    if (hostTheme) {
+      root.classList.remove('light');
+      if (e.data.isLight) root.classList.add('light');
     }
-    root.classList.remove('light');
-    if (e.data.isLight) root.classList.add('light');
   });
 
   // --- Resize ---
@@ -244,7 +257,7 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!pinpointLabelEl) {
       pinpointLabelEl = document.createElement('div');
       pinpointLabelEl.setAttribute('data-plannotator-pinpoint-label', '');
-      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
+      pinpointLabelEl.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:none;font:600 11px/1.3 system-ui,-apple-system,sans-serif;padding:2px 7px;border-radius:5px;background:var(--pn-focus-highlight,#4493f8);color:#fff;white-space:nowrap;box-shadow:0 1px 5px rgba(0,0,0,.35);';
       document.body.appendChild(pinpointLabelEl);
     }
     return pinpointLabelEl;

package/components/html-viewer/srcdoc.ts

@@ -0,0 +1,130 @@
+/**
+ * Srcdoc injection builder for the HTML viewer.
+ *
+ * Product rule: arbitrary HTML must render exactly as it would in a plain
+ * browser tab. The viewer never writes into the document's namespace — no bare
+ * CSS custom properties, no classes on the author's root, no `color-scheme`,
+ * no styling of author elements. Host theme tokens are pushed under the
+ * viewer-owned `--pn-*` prefix, which the annotation CSS reads.
+ *
+ * Documents that WANT to follow the host theme (e.g. Plannotator-generated
+ * artifacts) opt in with `<meta name="plannotator-theme" content="host">`,
+ * which re-enables the bare-token push, the `light` class on their root, and
+ * `color-scheme` sync — for that document only.
+ *
+ * Pure string logic (no DOM) so the rendering-neutrality contract is unit-testable.
+ */
+import { ANNOTATION_HIGHLIGHT_CSS, BRIDGE_SCRIPT } from "./bridge-script";
+
+export const THEME_TOKENS = [
+  "--background",
+  "--foreground",
+  "--card",
+  "--card-foreground",
+  "--primary",
+  "--primary-foreground",
+  "--secondary",
+  "--secondary-foreground",
+  "--muted",
+  "--muted-foreground",
+  "--accent",
+  "--accent-foreground",
+  "--destructive",
+  "--destructive-foreground",
+  "--success",
+  "--success-foreground",
+  "--warning",
+  "--warning-foreground",
+  "--border",
+  "--input",
+  "--ring",
+  "--code-bg",
+  "--focus-highlight",
+  "--font-sans",
+  "--font-mono",
+  "--radius",
+] as const;
+
+/** Viewer-owned namespace for properties injected into the document. */
+export const PN_TOKEN_PREFIX = "--pn-";
+
+/**
+ * Version-diff highlights. htmlDiff tags the <ins>/<del> it generates with
+ * this class so author-written <ins>/<del> markup is never restyled.
+ */
+export const DIFF_HIGHLIGHT_CSS =
+  "ins.plannotator-diff{background:#e6ffec;color:#0a7d33;text-decoration:none;border-radius:2px;box-shadow:0 0 0 1px #abf2bc inset}" +
+  "del.plannotator-diff{background:#ffebe9;color:#b31d28;text-decoration:line-through;border-radius:2px;box-shadow:0 0 0 1px #ffc1bc inset}";
+
+/**
+ * True when the document opts in to following the host theme via
+ * `<meta name="plannotator-theme" content="host">` (attribute order/quoting agnostic).
+ */
+export function hasHostThemeOptIn(rawHtml: string): boolean {
+  const metas = rawHtml.match(/<meta\b[^>]*>/gi);
+  if (!metas) return false;
+  return metas.some(
+    (tag) =>
+      /\bname\s*=\s*["']?plannotator-theme["']?/i.test(tag) &&
+      /\bcontent\s*=\s*["']?host["']?/i.test(tag),
+  );
+}
+
+/**
+ * Build the theme properties to write into the document. Bare host token names
+ * (`--muted`, `--background`, …) collide with author variables, so they are
+ * remapped to `--pn-*`; the originals ride along only for host-theme documents.
+ */
+export function buildThemeTokenPayload(
+  tokens: Record<string, string>,
+  hostTheme: boolean,
+): Record<string, string> {
+  const payload: Record<string, string> = {};
+  for (const [key, val] of Object.entries(tokens)) {
+    payload[PN_TOKEN_PREFIX + key.slice(2)] = val;
+    if (hostTheme) payload[key] = val;
+  }
+  return payload;
+}
+
+export interface SrcdocInjectionOptions {
+  /** Host theme tokens, keyed by bare name (as read from the host root). */
+  tokens: Record<string, string>;
+  /** Whether the host is currently in its light theme. */
+  isLight: boolean;
+  /** Document opted in to host theming (see {@link hasHostThemeOptIn}). */
+  hostTheme: boolean;
+  /** The version-diff view is showing (rawHtml is htmlDiff output). */
+  diffActive: boolean;
+}
+
+/** The `<style>` + `<script>` block spliced into the document's head. */
+export function buildSrcdocInjection({
+  tokens,
+  isLight,
+  hostTheme,
+  diffActive,
+}: SrcdocInjectionOptions): string {
+  const payload = buildThemeTokenPayload(tokens, hostTheme);
+  let themeCSS = ":root {\n";
+  for (const [key, val] of Object.entries(payload)) {
+    themeCSS += `  ${key}: ${val};\n`;
+  }
+  themeCSS += "}\n";
+  // Host-theme documents mirror the host's light/dark; arbitrary documents keep
+  // their own color-scheme resolution (document + OS), like a standalone tab.
+  if (hostTheme) {
+    themeCSS += `:root { color-scheme: ${isLight ? "light" : "dark"}; }\n`;
+  }
+  const diffCSS = diffActive ? DIFF_HIGHLIGHT_CSS : "";
+  return `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style><script>${BRIDGE_SCRIPT}</script>`;
+}
+
+/** Splice the injection just before `</head>`, or prepend when there is none. */
+export function injectIntoHead(rawHtml: string, injection: string): string {
+  const headClose = rawHtml.indexOf("</head>");
+  if (headClose !== -1) {
+    return rawHtml.slice(0, headClose) + injection + rawHtml.slice(headClose);
+  }
+  return injection + rawHtml;
+}

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.25.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';