@plannotator/ui 0.31.0 → 0.32.0

package/components/HtmlSurfaceControls.tsx

@@ -0,0 +1,170 @@
+/**
+ * Header controls for a raw-HTML or live-app annotation surface: the eye
+ * (show/hide the floating tools over the page), the optional refresh, and
+ * the pen (Annotate/Interact toggle). Presentation only; every state lives
+ * in the host. Each control renders only when its handler is passed, so a
+ * read-only document can show the eye without a pen.
+ *
+ * The markup, data attributes (`data-html-tools-toggle`, `data-html-refresh`,
+ * `data-html-annotate-toggle`), aria state and the pixel-stable pen border
+ * are the exact ones Plannotator's header shipped with; hosts get the same
+ * control, and `labels` overrides the strings without touching the DOM.
+ */
+
+/** String overrides. Every key optional; defaults are Plannotator's strings. */
+export interface HtmlSurfaceControlLabels {
+  /** Pen title while Annotate is armed. */
+  annotateTitle?: string;
+  /** Pen title while in Interact mode. */
+  interactTitle?: string;
+  /** Pen aria-label while armed. Default: none (the title carries the name). */
+  annotateLabel?: string;
+  /** Pen aria-label while in Interact mode. Default: none. */
+  interactLabel?: string;
+  /** Eye title and screen-reader text while the tools are visible. */
+  hideTools?: string;
+  /** Eye title and screen-reader text while the tools are hidden. */
+  showTools?: string;
+  /** Refresh visible text while idle. */
+  refresh?: string;
+  /** Refresh visible text while a refresh is in flight. */
+  refreshing?: string;
+  /** Refresh title and aria-label while idle. */
+  refreshTitle?: string;
+  /** Refresh title and aria-label while a refresh is in flight. */
+  refreshingTitle?: string;
+}
+
+export const DEFAULT_HTML_SURFACE_CONTROL_LABELS: Required<
+  Omit<HtmlSurfaceControlLabels, 'annotateLabel' | 'interactLabel'>
+> = {
+  annotateTitle: 'Annotate mode: click an element or select text to comment. Esc to interact',
+  interactTitle: 'Interact mode: clicks reach the page (text selection still comments). Click to annotate',
+  hideTools: 'Hide tools',
+  showTools: 'Show tools',
+  refresh: 'Refresh',
+  refreshing: 'Refreshing',
+  refreshTitle: 'Refresh document',
+  refreshingTitle: 'Refreshing document',
+};
+
+export interface HtmlSurfaceControlsProps {
+  /** Whether Annotate is armed (pen pressed). */
+  armed: boolean;
+  /** Flip Annotate/Interact. The pen renders only when provided. */
+  onToggleArmed?: () => void;
+  /** Whether the floating tools over the page are hidden (eye-off). */
+  toolsHidden?: boolean;
+  /** Flip the tools. The eye (and the refresh beside it) render only when provided. */
+  onToggleTools?: () => void;
+  /** Whether a refresh is offered for this document. */
+  canRefresh?: boolean;
+  onRefresh?: () => void;
+  isRefreshing?: boolean;
+  /** Compact touch shells put these actions in a menu instead: render nothing. */
+  compact?: boolean;
+  labels?: HtmlSurfaceControlLabels;
+}
+
+export function HtmlSurfaceControls({
+  armed,
+  onToggleArmed,
+  toolsHidden = false,
+  onToggleTools,
+  canRefresh = false,
+  onRefresh,
+  isRefreshing = false,
+  compact = false,
+  labels,
+}: HtmlSurfaceControlsProps) {
+  if (compact) return null;
+  const text = { ...DEFAULT_HTML_SURFACE_CONTROL_LABELS, ...labels };
+  const penLabel = armed ? labels?.annotateLabel : labels?.interactLabel;
+  return (
+    <>
+      {/* Show/hide tools: removes ALL floating chrome (sidebar tongue tabs +
+          the comment/attachments cluster) from the DOM, leaving nothing over
+          the page. Sits left of the pen; this button is the only way back,
+          so it never hides itself. Eye = tools visible, eye-off = hidden. */}
+      {onToggleTools && (
+        <div className="ml-1 flex items-center gap-0.5">
+          {canRefresh && onRefresh && (
+            <button
+              type="button"
+              data-html-refresh
+              // aria-disabled rather than disabled: a disabled control drops
+              // keyboard focus to body when activated. useHtmlRefresh already
+              // dedups in-flight requests, so an extra click is harmless.
+              onClick={isRefreshing ? undefined : onRefresh}
+              aria-disabled={isRefreshing}
+              className="flex items-center gap-1.5 rounded px-1.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:text-foreground aria-disabled:cursor-wait aria-disabled:opacity-70"
+              title={isRefreshing ? text.refreshingTitle : text.refreshTitle}
+              aria-label={isRefreshing ? text.refreshingTitle : text.refreshTitle}
+            >
+              <svg
+                aria-hidden="true"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className={`h-3.5 w-3.5 ${isRefreshing ? 'animate-spin motion-reduce:animate-none' : ''}`}
+              >
+                <path d="M20 11a8.1 8.1 0 0 0-15.5-2M4 4v5h5" />
+                <path d="M4 13a8.1 8.1 0 0 0 15.5 2M20 20v-5h-5" />
+              </svg>
+              <span className="hidden sm:inline">{isRefreshing ? text.refreshing : text.refresh}</span>
+            </button>
+          )}
+          <button
+            type="button"
+            data-html-tools-toggle
+            onClick={onToggleTools}
+            aria-pressed={toolsHidden}
+            className="cursor-pointer rounded-md border border-transparent p-1.5 text-xs font-medium text-muted-foreground transition-all hover:bg-muted hover:text-foreground"
+            title={toolsHidden ? text.showTools : text.hideTools}
+          >
+            {toolsHidden ? (
+              <svg aria-hidden="true" className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M3.98 8.223A10.477 10.477 0 0 0 1.934 12C3.226 16.338 7.244 19.5 12 19.5c.993 0 1.953-.138 2.863-.395M6.228 6.228A10.45 10.45 0 0 1 12 4.5c4.756 0 8.773 3.162 10.065 7.498a10.523 10.523 0 0 1-4.293 5.774M6.228 6.228 3 3m3.228 3.228 3.65 3.65m7.894 7.894L21 21m-3.228-3.228-3.65-3.65m0 0a3 3 0 1 0-4.243-4.243m4.242 4.242L9.88 9.88" />
+              </svg>
+            ) : (
+              <svg aria-hidden="true" className="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M2.036 12.322a1.012 1.012 0 0 1 0-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178Z" />
+                <path strokeLinecap="round" strokeLinejoin="round" d="M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z" />
+              </svg>
+            )}
+            <span className="sr-only">{toolsHidden ? text.showTools : text.hideTools}</span>
+          </button>
+        </div>
+      )}
+
+      {/* Interact/Annotate toggle. A PEN icon (deliberately not a speech
+          bubble: an annotations-panel bubble beside it must stay
+          distinguishable at a glance, and so must AI sparkles). Always the
+          same icon: armed shows the accent color plus a visible border;
+          unarmed is muted with a TRANSPARENT border of the same width, so
+          the button's box is pixel-identical in both states. */}
+      {onToggleArmed && (
+        <button
+          type="button"
+          data-html-annotate-toggle
+          onClick={onToggleArmed}
+          aria-pressed={armed}
+          className={`p-1.5 rounded-md border text-xs font-medium transition-all cursor-pointer ${
+            armed
+              ? 'border-primary/60 bg-primary/15 text-primary'
+              : 'border-transparent text-muted-foreground hover:text-foreground hover:bg-muted'
+          }`}
+          title={armed ? text.annotateTitle : text.interactTitle}
+          {...(penLabel !== undefined ? { 'aria-label': penLabel } : {})}
+        >
+          <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M16.862 4.487l1.687-1.688a1.875 1.875 0 112.652 2.652L6.832 19.82a4.5 4.5 0 01-1.897 1.13l-2.685.8.8-2.685a4.5 4.5 0 011.13-1.897L16.862 4.487zm0 0L19.5 7.125" />
+          </svg>
+        </button>
+      )}
+    </>
+  );
+}

package/components/InlineMarkdown.tsx

@@ -9,7 +9,8 @@ import { getImageSrc } from "./ImageThumbnail";
 import { useCodePathValidation, type CodePathValidationContextValue } from "./CodePathValidationContext";
 import type { ValidationEntry } from "../hooks/useValidatedCodePaths";
 import { CodeFilePicker } from "./CodeFilePicker";
-import { normalizeMathTex, renderMathToHtml } from "./blocks/MathBlock";
+import { normalizeMathTex, renderMathToHtml } from "../utils/math";
+import { useMathRenderer } from "../hooks/useMathRenderer";
 
 export interface DocPreviewResult {
   contents?: string;
@@ -42,6 +43,9 @@ export const resetDocPreviewFetcher = (): void => {
   docPreviewFetcher = defaultDocPreviewFetcher;
 };
 
+/** Read the active fetcher at call time (so a late override is honored). */
+export const getDocPreviewFetcher = (): DocPreviewFetcher => docPreviewFetcher;
+
 /**
  * Decide how a candidate code-file path should render based on validation state:
  *   - 'link'           → clickable, opens directly via onOpenCodeFile(resolvedOrInput)
@@ -309,7 +313,23 @@ const CodeFileIcon = () => (
 
 const InlineMath: React.FC<{ tex: string }> = ({ tex }) => {
   const normalizedTex = normalizeMathTex(tex);
-  const html = useMemo(() => renderMathToHtml(normalizedTex, false), [normalizedTex]);
+  const renderer = useMathRenderer();
+  const html = useMemo(() => renderMathToHtml(normalizedTex, false, renderer), [normalizedTex, renderer]);
+
+  // Same wrapper in both branches (see MathBlock): the placeholder carries the
+  // attributes annotation restore keys on, with the TeX as a text child.
+  if (html === null) {
+    return (
+      <span
+        className="math-inline math-annotatable text-foreground"
+        data-math-tex={normalizedTex}
+        data-math-display="false"
+        aria-label={normalizedTex}
+      >
+        {normalizedTex}
+      </span>
+    );
+  }
 
   return (
     <span

package/components/MermaidBlock.tsx

@@ -1,33 +1,26 @@
 import React, { useRef, useState, useEffect, useCallback } from 'react';
 import { createPortal } from 'react-dom';
-import mermaid from 'mermaid';
+import type { Mermaid } from 'mermaid';
 import type { Block } from '../types';
 import { normalizeMermaidSvgMarkup } from './mermaidSvg';
+import {
+  MERMAID_CONFIG,
+  getMermaidRetryDelayMs,
+  loadMermaidRuntime,
+  __setMermaidRuntimeLoaderForTests,
+} from '../utils/mermaid';
 
-mermaid.initialize({
-  startOnLoad: false,
-  securityLevel: 'strict',
-  theme: 'dark',
-  themeVariables: {
-    primaryColor: '#3b82f6',
-    primaryTextColor: '#f8fafc',
-    primaryBorderColor: '#475569',
-    lineColor: '#64748b',
-    secondaryColor: '#1e293b',
-    tertiaryColor: '#0f172a',
-    background: '#1e293b',
-    mainBkg: '#1e293b',
-    nodeBorder: '#475569',
-    clusterBkg: '#1e293b',
-    clusterBorder: '#475569',
-    titleColor: '#f8fafc',
-    edgeLabelBackground: '#1e293b',
-  },
-  flowchart: {
-    htmlLabels: true,
-    curve: 'basis',
-  },
-});
+// Re-exported: the config pin test and the lazy-retry test import them from here.
+export { MERMAID_CONFIG, __setMermaidRuntimeLoaderForTests };
+
+/**
+ * The runtime comes from the slot in utils/mermaid: filled eagerly by
+ * Plannotator (utils/mermaid-eager, imported by the editor App), loaded
+ * lazily otherwise. See that module for the retry contract.
+ */
+const getMermaid = loadMermaidRuntime;
+
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
 
 interface ViewBox {
   x: number;
@@ -133,6 +126,11 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
   const expandedOverlayRef = useRef<HTMLDivElement>(null);
   const [svg, setSvg] = useState('');
   const [error, setError] = useState<string | null>(null);
+  // True when the failure was the runtime import itself (a chunking host's
+  // fetch), which is the only failure a Retry can change; a diagram syntax
+  // error keeps the panel exactly as it always was.
+  const [runtimeUnavailable, setRuntimeUnavailable] = useState(false);
+  const [retryToken, setRetryToken] = useState(0);
   const [showSource, setShowSource] = useState(false);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -188,6 +186,27 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
 
     // Render mermaid diagram
     const renderDiagram = async () => {
+      let mermaid: Mermaid;
+      try {
+        try {
+          mermaid = await getMermaid();
+        } catch {
+          // Transient chunk failure on a chunking host: one automatic
+          // re-attempt with a fresh import() after a short delay. In a
+          // single-file build the first await never rejects, so this branch
+          // is unreachable there and the success path is unchanged.
+          await wait(getMermaidRetryDelayMs());
+          if (cancelled) return;
+          mermaid = await getMermaid();
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(true);
+          setSvg('');
+        }
+        return;
+      }
       try {
         const id = `mermaid-${block.id}`;
         const { svg: renderedSvg } = await mermaid.render(id, block.content);
@@ -196,10 +215,12 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
           naturalBoundsRef.current = parseViewBoxFromMarkup(normalizedSvg);
           setSvg(normalizedSvg);
           setError(null);
+          setRuntimeUnavailable(false);
         }
       } catch (err) {
         if (!cancelled) {
           setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setRuntimeUnavailable(false);
           setSvg('');
         }
       }
@@ -210,7 +231,7 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
     return () => {
       cancelled = true;
     };
-  }, [block.content, block.id]);
+  }, [block.content, block.id, retryToken]);
 
   // Reset zoom and pan when content changes
   useEffect(() => {
@@ -419,6 +440,19 @@ const MermaidBlockImpl: React.FC<{ block: Block }> = ({ block }) => {
             <path strokeLinecap="round" strokeLinejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
           </svg>
           <span className="text-xs text-destructive font-medium">Mermaid Error</span>
+          {runtimeUnavailable && (
+            <button
+              type="button"
+              onClick={() => {
+                setError(null);
+                setRetryToken((token) => token + 1);
+              }}
+              className="ml-auto rounded-md border border-destructive/30 px-2 py-0.5 text-xs text-destructive hover:bg-destructive/10"
+              title="Retry loading the diagram renderer"
+            >
+              Retry
+            </button>
+          )}
         </div>
         <pre className="p-3 text-xs text-destructive/80 overflow-x-auto">{error}</pre>
         <pre className="p-3 text-xs text-muted-foreground bg-muted/30 border-t border-border/30 overflow-x-auto">

package/components/Settings.tsx

@@ -4,6 +4,7 @@ import type { AnnotateAgentTerminalSide } from '@plannotator/core/agent-terminal
 import type { Origin } from '@plannotator/core/agents';
 import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
 import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType } from '../config';
+import { setWebMcpToolsEnabled, useWebMcpToolsEnabled } from '../webmcp/preference';
 import { loadDiffFont } from '../utils/diffFonts';
 import { TaterSpritePullup } from './TaterSpritePullup';
 import { getIdentity, regenerateIdentity, setCustomIdentity, isIdentityEditable } from '../utils/identity';
@@ -107,6 +108,10 @@ interface SettingsProps {
    *  from a Hidden position, but offering it where no terminal can ever run
    *  would just be a dead control. */
   agentTerminalAvailable?: boolean;
+  /** The browser exposes WebMCP (`document.modelContext`), so the "Agent
+   *  tools" opt-out is worth showing. Default false: a browser without the
+   *  API gets no row at all (the provider registers nothing there). */
+  webmcpAvailable?: boolean;
 }
 
 // --- Review-mode Display tab (diff display options) ---
@@ -848,7 +853,8 @@ const CommentsTab: React.FC = () => {
   );
 };
 
-export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false }) => {
+export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
+  const webmcpTools = useWebMcpToolsEnabled();
   const [showDialog, setShowDialog] = useState(false);
   const settingsWasOpenRef = useRef(false);
   const [themePreview, setThemePreview] = useState(false);
@@ -1282,6 +1288,39 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                       </div>
                     </div>
 
+                    {/* Agent tools (WebMCP). Shown only when the browser
+                        exposes document.modelContext; off unregisters the
+                        tools for this browser. Cookie-only and idle at its
+                        default: no cookie exists until the user opts out. */}
+                    {webmcpAvailable && (
+                      <>
+                        <div className="border-t border-border" />
+                        <div className="flex items-center justify-between" data-webmcp-setting="true">
+                          <div>
+                            <div className="text-sm font-medium">Agent tools</div>
+                            <div className="text-xs text-muted-foreground">
+                              Let your browser's agent read this document and leave comments. Approving and sending feedback stay yours.
+                            </div>
+                          </div>
+                          <button
+                            role="switch"
+                            aria-checked={webmcpTools}
+                            aria-label="Agent tools"
+                            onClick={() => setWebMcpToolsEnabled(!webmcpTools)}
+                            className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors ${
+                              webmcpTools ? 'bg-primary' : 'bg-muted'
+                            }`}
+                          >
+                            <span
+                              className={`inline-block h-4 w-4 transform rounded-full bg-white shadow-sm transition-transform ${
+                                webmcpTools ? 'translate-x-6' : 'translate-x-1'
+                              }`}
+                            />
+                          </button>
+                        </div>
+                      </>
+                    )}
+
                     {/* Permission Mode (Claude Code only) */}
                     {origin === 'claude-code' && mode === 'plan' && (
                       <>

package/components/blocks/MathBlock.tsx

@@ -1,26 +1,38 @@
 import React, { useMemo } from 'react';
-import katex from 'katex';
 import type { Block } from '../../types';
+import { normalizeMathTex, renderMathToHtml } from '../../utils/math';
+import { useMathRenderer } from '../../hooks/useMathRenderer';
+
+// Kept as re-exports: InlineMarkdown and older consumers import them from here.
+export { normalizeMathTex, renderMathToHtml };
 
 type MathBlockProps = {
   block: Block;
 };
 
-export const normalizeMathTex = (tex: string): string => tex.trim();
-
-export const renderMathToHtml = (tex: string, displayMode: boolean): string => (
-  katex.renderToString(tex, {
-    displayMode,
-    throwOnError: false,
-    strict: 'warn',
-    trust: false,
-    output: 'html',
-  })
-);
-
 export const MathBlock: React.FC<MathBlockProps> = ({ block }) => {
   const tex = normalizeMathTex(block.content);
-  const html = useMemo(() => renderMathToHtml(tex, true), [tex]);
+  const renderer = useMathRenderer();
+  const html = useMemo(() => renderMathToHtml(tex, true, renderer), [tex, renderer]);
+
+  // The wrapper (class names, data-* anchors, aria-label) is identical in both
+  // branches: block targeting and math-annotation restore key on these
+  // attributes, so a placeholder must be addressable exactly like the typeset
+  // block. The placeholder's child is a React text node, never markup.
+  if (html === null) {
+    return (
+      <div
+        className="math-block math-annotatable my-5 overflow-x-auto py-2 text-foreground"
+        data-block-id={block.id}
+        data-block-type="math"
+        data-math-tex={tex}
+        data-math-display="true"
+        aria-label={tex}
+      >
+        {tex}
+      </div>
+    );
+  }
 
   return (
     <div

package/components/html-viewer/HtmlViewer.tsx

@@ -17,6 +17,7 @@ import type { Annotation, EditorMode, ImageAttachment, InputMethod } from "../..
 import { AnnotationType } from "../../types";
 import { copyTextPreservingFocus } from "../../utils/clipboard";
 import { getIdentity } from "../../utils/identity";
+import { THUMBS_UP_LABEL } from "../../utils/quickLabels";
 import {
   createVimHudCommand,
   getVimHudPhase,
@@ -37,6 +38,7 @@ import {
   type ComposerYieldState,
 } from "./composerYield";
 import { buildSyncNumbering } from "./annotationNumbering";
+import { mergeUnanchoredIds } from "./unanchored";
 import {
   MAX_PAGE_URL_LENGTH,
   rejectsLiveMessage,
@@ -202,8 +204,21 @@ export interface HtmlViewerProps {
   /** Reports the full set of annotation ids with no live representation on
    *  the page (fail-closed anchors hide markers rather than guess). Called
    *  with the complete current set whenever it changes, including back to
-   *  empty on recovery. Fires in readOnly mode too. */
+   *  empty on recovery. Fires in readOnly mode too. Complete over the
+   *  `annotations` prop: page rows with nothing to restore by (no quoted
+   *  text, no element anchor) are reported even though the bridge never
+   *  sees them, and an id this viewer minted for a local comment that the
+   *  host swapped out of `annotations` for its own id is not reported. */
   onUnanchoredChange?: (ids: string[]) => void;
+  /** Product cap on additional (shift-click) targets per comment, 0..16.
+   *  Enforced at the trust boundary, on submit and on restore, and carried
+   *  to the bridge so the in-page toggle stops at the same number. Default
+   *  16 (the package cap); absent leaves every message unchanged. */
+  maxAdditionalTargets?: number;
+  /** scrollIntoView behavior when a selected annotation is scrolled into
+   *  view inside the page. Default 'smooth'; pass 'auto' to carry the
+   *  parent's reduced-motion preference across the iframe boundary. */
+  scrollBehavior?: 'smooth' | 'auto';
   /** Accessible iframe title. */
   title?: string;
 }
@@ -245,6 +260,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onAskAI,
       readOnly = false,
       onUnanchoredChange,
+      maxAdditionalTargets,
+      scrollBehavior,
       title = "HTML Plan Viewer",
     },
     ref,
@@ -358,6 +375,63 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       [handleYieldPointer],
     );
 
+    // Unanchored union: the bridge reports ids with no live representation,
+    // completed here with what the bridge cannot see (textless page rows it
+    // was never asked to restore) and minus locally minted ids the host
+    // swapped out of `annotations`. Bridge reports deliver as they arrive
+    // (pass-through timing); a prop-side change delivers only when the union
+    // actually changes, so a viewer with nothing to complete delivers exactly
+    // the bridge list, exactly when the bridge posts it.
+    const onUnanchoredChangeRef = useRef(onUnanchoredChange);
+    onUnanchoredChangeRef.current = onUnanchoredChange;
+    const annotationsRef = useRef(annotations);
+    annotationsRef.current = annotations;
+    const bridgeUnanchoredRef = useRef<readonly string[]>([]);
+    const lastDeliveredUnanchoredRef = useRef("[]");
+    const createdIdsRef = useRef<ReadonlySet<string>>(new Set());
+    // The bridge's first report for the current document is the one that
+    // follows the restore batch (the parent asks for it with
+    // report-unanchored, and the bridge answers after its next complete
+    // pass, empty set included). Nothing is delivered before it: a host
+    // that acknowledges "the first report after a reload" must get the
+    // post-restore set, never a prop-side set computed at mount.
+    const bridgeReportedRef = useRef(false);
+    // An in-place document swap (rawHtml or src changes on one instance):
+    // the old document may still emit through the same contentWindow before
+    // the new one is ready. From the swap until the next ready, bridge
+    // reports belong to the old document and are dropped, and the
+    // last-delivered key is reset so the new document's first answer is
+    // delivered even when it equals the old one. First mount is not a swap.
+    const awaitingReadyRef = useRef(false);
+    const documentIdentityRef = useRef<{ rawHtml: string; src: string | undefined } | null>(null);
+    const previousIdentity = documentIdentityRef.current;
+    if (previousIdentity && (previousIdentity.rawHtml !== rawHtml || previousIdentity.src !== src)) {
+      awaitingReadyRef.current = true;
+      bridgeReportedRef.current = false;
+      lastDeliveredUnanchoredRef.current = "[]";
+      bridgeUnanchoredRef.current = [];
+    }
+    documentIdentityRef.current = { rawHtml, src };
+    const deliverUnanchored = useCallback((ids: string[], onlyIfChanged: boolean) => {
+      const key = JSON.stringify(ids);
+      if (onlyIfChanged && key === lastDeliveredUnanchoredRef.current) return;
+      lastDeliveredUnanchoredRef.current = key;
+      onUnanchoredChangeRef.current?.(ids);
+    }, []);
+    const handleBridgeUnanchored = useCallback((ids: string[]) => {
+      if (awaitingReadyRef.current) return;
+      bridgeUnanchoredRef.current = ids;
+      bridgeReportedRef.current = true;
+      deliverUnanchored(
+        mergeUnanchoredIds({
+          bridgeIds: ids,
+          annotations: annotationsRef.current,
+          createdIds: createdIdsRef.current,
+        }),
+        false,
+      );
+    }, [deliverUnanchored]);
+
     const hook = useHtmlAnnotation({
       iframeRef,
       enabled: !readOnly,
@@ -370,8 +444,23 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       live: liveSession,
       onPageChange,
       onBridgePointer: handleBridgePointer,
-      onUnanchoredChange,
+      onUnanchoredChange: handleBridgeUnanchored,
+      maxAdditionalTargets,
+      scrollBehavior,
     });
+    createdIdsRef.current = hook.createdAnnotationIds;
+
+    useEffect(() => {
+      if (!bridgeReportedRef.current) return;
+      deliverUnanchored(
+        mergeUnanchoredIds({
+          bridgeIds: bridgeUnanchoredRef.current,
+          annotations,
+          createdIds: hook.createdAnnotationIds,
+        }),
+        true,
+      );
+    }, [annotations, hook.createdAnnotationIds, deliverUnanchored]);
 
     const multiSelectActive = !readOnly && !!hook.commentPopover && hook.draftTargets.length > 0;
 
@@ -547,6 +636,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       if (restorable.length > 0) {
         hook.applyAnnotations(restorable);
       }
+      // A fresh document: the bridge starts from an empty set and would stay
+      // silent when everything restores. Ask for one complete report after
+      // this restore batch (posted after it, so the answering pass sees it),
+      // which becomes this document's first delivery, empty set included.
+      awaitingReadyRef.current = false;
+      bridgeReportedRef.current = false;
+      postToBridge({ type: `${PREFIX}report-unanchored` });
     }, [iframeReadyVersion]); // eslint-disable-line react-hooks/exhaustive-deps
 
     // Live page navigation with a ready iframe: explicitly clear the previous
@@ -569,6 +665,11 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         type: `${PREFIX}sync-annotations`,
         annotations: buildSyncNumbering(annotations),
       });
+      // A new page is a new restore batch: report its complete set once, and
+      // deliver nothing computed against the previous page's report until
+      // that answer arrives.
+      bridgeReportedRef.current = false;
+      postToBridge({ type: `${PREFIX}report-unanchored` });
     }, [currentPageUrl, iframeReadyVersion]); // eslint-disable-line react-hooks/exhaustive-deps
 
     // Placed-marker numbering is parent-authoritative and matches the
@@ -877,10 +978,15 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               positionMode="center-above"
               element={hook.toolbarState.element}
               copyText={hook.toolbarState.selectionText}
-              // HTML/live surfaces are comment-only: no Delete, no quick
-              // labels (onQuickLabel deliberately not passed). The markdown
-              // surface keeps the full toolbar.
+              // HTML/live surfaces are comment-only: no Delete, no label
+              // picker, no Alt+digit labels (commentOnly). Exactly ONE label
+              // affordance is restored: the hardcoded 👍 "Looks good". The
+              // wrapper filters by id as defense in depth, so no present or
+              // future toolbar path can emit an arbitrary label here.
               commentOnly
+              onQuickLabel={(label) => {
+                if (label.id === THUMBS_UP_LABEL.id) hook.handleQuickLabel(label);
+              }}
               onAnnotate={hook.handleAnnotate}
               onRequestComment={hook.handleRequestComment}
               onClose={hook.handleToolbarClose}
@@ -898,6 +1004,10 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               isGlobal={false}
               draftKey={`html:${hook.commentPopover.draftKey}`}
               onSubmit={hook.handleCommentSubmit}
+              // Pinpoint clicks open this composer directly, so it carries
+              // the surface's one-click "Looks good" (the global composer
+              // does not: a document-wide thumbs-up is not a thing).
+              onQuickLookGood={hook.handleCommentLooksGood}
               onClose={hook.handleCommentClose}
               skillReferences
               onAskAI={onAskAI}