@plannotator/ui 0.30.0 → 0.32.0

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,
@@ -29,7 +30,6 @@ import {
   type CommentAskAIHandler,
   type CommentTargetChip,
 } from "../CommentPopover";
-import { FloatingQuickLabelPicker } from "../FloatingQuickLabelPicker";
 import { VimKeyHud } from "../VimKeyHud";
 import type { ViewerHandle } from "../Viewer";
 import {
@@ -38,7 +38,13 @@ import {
   type ComposerYieldState,
 } from "./composerYield";
 import { buildSyncNumbering } from "./annotationNumbering";
-import { useHtmlAnnotation } from "./useHtmlAnnotation";
+import { mergeUnanchoredIds } from "./unanchored";
+import {
+  MAX_PAGE_URL_LENGTH,
+  rejectsLiveMessage,
+  useHtmlAnnotation,
+  type HtmlLiveSession,
+} from "./useHtmlAnnotation";
 import {
   THEME_TOKENS,
   buildSrcdocInjection,
@@ -138,6 +144,17 @@ function parseVimBridgeCopy(value: unknown): string | null {
 /** Inputs for the sandboxed raw-HTML viewer and its parent-side annotation UI. */
 export interface HtmlViewerProps {
   rawHtml: string;
+  /** Live proxied-app mode: render `src` (no sandbox, no srcdoc) instead of
+   *  rawHtml. The caller must also set `fullViewport` and `liveSession`. */
+  src?: string;
+  /** Live session credentials paired with `src`: proxy origin + per-session
+   *  token, validated on every inbound message and stamped on every post. */
+  liveSession?: HtmlLiveSession;
+  /** Current page (pathname + search) in a live multi-page session. Restore
+   *  filters annotations to this page; changing it re-applies the filter. */
+  currentPageUrl?: string;
+  /** Live-mode page navigation reports (ready pageUrl + page-change). */
+  onPageChange?: (pageUrl: string) => void;
   annotations: Annotation[];
   onAddAnnotation: (ann: Annotation) => void;
   onSelectAnnotation: (id: string | null) => void;
@@ -145,6 +162,18 @@ export interface HtmlViewerProps {
   mode: EditorMode;
   /** Input method: 'drag' = text selection, 'pinpoint' = click an element. */
   inputMethod: InputMethod;
+  /** Interact/Annotate toggle for HTML and live-app surfaces. While false
+   *  the bridge keeps clicks native (no pinpoint capture, no hover outline)
+   *  and clicks/forms/navigation reach the page untouched. Text
+   *  drag-selection commenting stays live in BOTH modes, and committed
+   *  markers stay visible and clickable in BOTH modes. Default true (armed)
+   *  on both surface kinds. */
+  annotateModeActive?: boolean;
+  /** Esc final rung (bridge-side or the parent-side listener here): the user
+   *  asked to leave Annotate for Interact. The host owns the mode state. */
+  onAnnotateModeExit?: () => void;
+  /** Mod+Shift+A pressed while focus lived inside the iframe. */
+  onAnnotateModeToggle?: () => void;
   /** Opt-in Vim-style keyboard selection. Default false for compatibility. */
   vimModeEnabled?: boolean;
   /** Replace the iframe-local compact badge with the shared live key HUD. */
@@ -175,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;
 }
@@ -189,12 +231,19 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
   (
     {
       rawHtml,
+      src,
+      liveSession,
+      currentPageUrl,
+      onPageChange,
       annotations,
       onAddAnnotation,
       onSelectAnnotation,
       selectedAnnotationId,
       mode,
       inputMethod,
+      annotateModeActive = true,
+      onAnnotateModeExit,
+      onAnnotateModeToggle,
       vimModeEnabled = false,
       vimHudEnabled = false,
       vimHudKeyPanelEnabled = true,
@@ -211,6 +260,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onAskAI,
       readOnly = false,
       onUnanchoredChange,
+      maxAdditionalTargets,
+      scrollBehavior,
       title = "HTML Plan Viewer",
     },
     ref,
@@ -233,11 +284,44 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       contextText: string;
     } | null>(null);
 
+    // Live proxied-app mode: the iframe navigates a real origin, so the
+    // srcdoc pipeline is skipped entirely and its messages carry credentials.
+    const liveMode = !!src;
+    const liveSessionRef = useRef<HtmlLiveSession | null>(liveSession ?? null);
+    liveSessionRef.current = liveSession ?? null;
+    const onPageChangeRef = useRef(onPageChange);
+    onPageChangeRef.current = onPageChange;
+    const onAnnotateModeExitRef = useRef(onAnnotateModeExit);
+    onAnnotateModeExitRef.current = onAnnotateModeExit;
+    const onAnnotateModeToggleRef = useRef(onAnnotateModeToggle);
+    onAnnotateModeToggleRef.current = onAnnotateModeToggle;
+
+    /** Single choke point for direct-to-bridge posts: live sessions get the
+     *  token + concrete targetOrigin, srcdoc keeps "*" and no token. */
+    const postToBridge = useCallback((msg: Record<string, unknown>) => {
+      const win = iframeRef.current?.contentWindow;
+      if (!win) return;
+      const live = liveSessionRef.current;
+      if (live) {
+        // Browsers silently drop posts whose targetOrigin does not match the
+        // receiving window (mid-navigation frames); some DOM environments
+        // throw instead, so align with the browser semantics explicitly.
+        try {
+          win.postMessage({ ...msg, token: live.token }, live.origin);
+        } catch {
+          // Dropped, matching browser behavior for unmatched target origins.
+        }
+      } else {
+        win.postMessage(msg, "*");
+      }
+    }, []);
+
     // 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]);
+    const hostTheme = useMemo(() => !liveMode && hasHostThemeOptIn(rawHtml), [liveMode, rawHtml]);
 
     const srcdoc = useMemo(() => {
+      if (liveMode) return undefined; // src mode: the proxy injects the bridge
       const injection = buildSrcdocInjection({
         tokens: readThemeTokens(),
         isLight: isLightTheme(),
@@ -245,11 +329,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         diffActive: !!diffActive,
       });
       return injectIntoHead(rawHtml, injection);
-    }, [rawHtml, hostTheme, diffActive]);
+    }, [liveMode, rawHtml, hostTheme, diffActive]);
 
     const handleResize = useCallback((height: number) => {
+      if (liveMode) return; // live surfaces are full-viewport; height is ignored
       setIframeHeight(height);
-    }, []);
+    }, [liveMode]);
 
     // Composer yield while shift-selecting (multi-target drafts): fade the
     // composer as the pointer approaches, click-through when over it. Pointer
@@ -290,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,
@@ -299,9 +441,26 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       selectedAnnotationId,
       mode,
       onResize: handleResize,
+      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;
 
@@ -353,11 +512,36 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useEffect(() => {
       function handler(e: MessageEvent<unknown>) {
         if (e.source !== iframeRef.current?.contentWindow) return;
+        // Live sessions verify origin + token before reading anything.
+        const live = liveSessionRef.current;
+        if (live && rejectsLiveMessage(live, e.origin, e.data)) return;
         if (isBridgeReadyMessage(e.data)) {
           setIframeReadyVersion((version) => version + 1);
           setVimBridgePhase("inactive");
           setVimHudCommand(null);
           setVimHelpOpen(false);
+          // Live ready carries the page identity (validated like page-change)
+          // so reloads and cross-page navigations re-anchor the restore filter.
+          if (live && isRecord(e.data)) {
+            const pageUrl = e.data.pageUrl;
+            if (
+              typeof pageUrl === "string"
+              && pageUrl.length > 0
+              && pageUrl.length <= MAX_PAGE_URL_LENGTH
+            ) {
+              onPageChangeRef.current?.(pageUrl);
+            }
+          }
+          return;
+        }
+        // Interact/Annotate mode messages ride the same authenticated path:
+        // live sessions already rejected wrong-origin/tokenless data above.
+        if (isRecord(e.data) && e.data.type === `${PREFIX}annotate-exit`) {
+          onAnnotateModeExitRef.current?.();
+          return;
+        }
+        if (isRecord(e.data) && e.data.type === `${PREFIX}annotate-toggle`) {
+          onAnnotateModeToggleRef.current?.();
           return;
         }
         const vimCopy = parseVimBridgeCopy(e.data);
@@ -408,9 +592,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
 
     const handleVimHelpOpenChange = useCallback((open: boolean) => {
       setVimHelpOpen(open);
-      iframeRef.current?.contentWindow?.postMessage(
+      postToBridge(
         { type: `${PREFIX}set-vim-help`, open },
-        "*",
       );
     }, []);
 
@@ -425,9 +608,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       if (document.activeElement === iframe) return false;
       iframe.focus({ preventScroll: true });
       if (document.activeElement !== iframe) return false;
-      iframe.contentWindow?.postMessage(
+      postToBridge(
         { type: `${PREFIX}focus-vim` },
-        "*",
       );
       return true;
     }, [readOnly, vimModeEnabled]);
@@ -438,13 +620,58 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       focusDocument: focusVimDocument,
     });
 
+    // Restore filter for live multi-page sessions: only annotations made on
+    // the current page (or without page identity) are pushed for restoration.
+    // Numbering (sync-annotations) still ships the FULL list: numbers are
+    // parent-authoritative and global across pages, matching export.
+    const forCurrentPage = useCallback(
+      (anns: Annotation[]) =>
+        anns.filter((a) => !a.pageUrl || a.pageUrl === currentPageUrl),
+      [currentPageUrl],
+    );
+
     useEffect(() => {
       if (iframeReadyVersion === 0) return;
-      if (annotations.length > 0) {
-        hook.applyAnnotations(annotations);
+      const restorable = forCurrentPage(annotations);
+      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
+    // page's marks, then re-apply the filtered set. Relying on dead anchors to
+    // hide pins would risk cross-page text-search false matches and waste
+    // reconcile budget.
+    const lastAppliedPageRef = useRef<string | undefined>(currentPageUrl);
+    useEffect(() => {
+      if (lastAppliedPageRef.current === currentPageUrl) return;
+      lastAppliedPageRef.current = currentPageUrl;
+      if (iframeReadyVersion === 0) return;
+      postToBridge({ type: `${PREFIX}clear-marks` });
+      const restorable = forCurrentPage(annotations);
+      if (restorable.length > 0) {
+        hook.applyAnnotations(restorable);
+      }
+      // clear-marks drops the bridge's synced numbering; re-establish it so
+      // restored markers keep their export-matching global numbers.
+      postToBridge({
+        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
     // numbers exportAnnotations writes into the submitted feedback: the full
     // list INCLUDING globals is numbered by ARRAY position (the export's
@@ -454,9 +681,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     // order is only a pre-sync fallback.
     useEffect(() => {
       if (iframeReadyVersion === 0) return;
-      iframeRef.current?.contentWindow?.postMessage(
+      postToBridge(
         { type: `${PREFIX}sync-annotations`, annotations: buildSyncNumbering(annotations) },
-        "*",
       );
     }, [iframeReadyVersion, annotations]);
 
@@ -464,31 +690,67 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     // ready (fresh iframe) and whenever the user switches it in the toolstrip.
     useEffect(() => {
       if (iframeReadyVersion === 0) return;
-      iframeRef.current?.contentWindow?.postMessage(
+      postToBridge(
         { type: `${PREFIX}set-input-method`, method: inputMethod },
-        "*",
       );
     }, [iframeReadyVersion, inputMethod]);
 
+    // Tell the bridge whether Annotate is armed. Same re-post pattern as
+    // set-input-method, so the mode survives live page changes / HMR reloads
+    // and bridge re-injection without ever reloading the iframe.
+    useEffect(() => {
+      if (iframeReadyVersion === 0) return;
+      postToBridge(
+        { type: `${PREFIX}set-annotate-mode`, active: annotateModeActive },
+      );
+    }, [iframeReadyVersion, annotateModeActive]);
+
+    // Parent-side Esc rung: with focus outside the iframe the bridge never
+    // sees the keydown. Any open composer/toolbar/picker still closes first —
+    // their state is read from this render's closure, so an Esc that closed
+    // one this same keydown is not double-consumed here.
+    useEffect(() => {
+      if (readOnly || !annotateModeActive || !onAnnotateModeExit) return;
+      const overlayOpen =
+        !!hook.toolbarState || !!hook.commentPopover || !!hook.quickLabelPicker || !!globalCommentPopover;
+      const onKeyDown = (e: KeyboardEvent) => {
+        if (e.key !== 'Escape' || e.defaultPrevented) return;
+        if (overlayOpen) return;
+        // A text field or dialog owns its own Escape.
+        const target = e.target as HTMLElement | null;
+        if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable)) return;
+        if (document.querySelector('[data-plannotator-confirm-dialog="true"]')) return;
+        onAnnotateModeExit();
+      };
+      window.addEventListener('keydown', onKeyDown);
+      return () => window.removeEventListener('keydown', onKeyDown);
+    }, [
+      readOnly,
+      annotateModeActive,
+      onAnnotateModeExit,
+      hook.toolbarState,
+      hook.commentPopover,
+      hook.quickLabelPicker,
+      globalCommentPopover,
+    ]);
+
     useEffect(() => {
       if (iframeReadyVersion === 0) return;
       const iframe = iframeRef.current;
-      iframe?.contentWindow?.postMessage(
+      postToBridge(
         {
           type: `${PREFIX}set-vim-mode`,
           enabled: !readOnly && vimModeEnabled,
           hudEnabled: vimHudEnabled,
           mode,
         },
-        "*",
       );
       if (!readOnly && vimModeEnabled && iframe && iframe === document.activeElement) {
         // The initial parent focus can land before the sandbox bridge is ready.
         // Reassert it after configuration so raw HTML enters BLOCK immediately,
         // matching the Markdown surface instead of waiting for the first key.
-        iframe.contentWindow?.postMessage(
+        postToBridge(
           { type: `${PREFIX}focus-vim` },
-          "*",
         );
       }
     }, [iframeReadyVersion, mode, readOnly, vimHudEnabled, vimModeEnabled]);
@@ -506,9 +768,8 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         && (document.activeElement === document.body || document.activeElement === null)
       ) {
         iframeRef.current?.focus({ preventScroll: true });
-        iframeRef.current?.contentWindow?.postMessage(
+        postToBridge(
           { type: `${PREFIX}focus-vim` },
-          "*",
         );
       }
     }, [hook.commentPopover, hook.quickLabelPicker, hook.toolbarState, readOnly, vimModeEnabled]);
@@ -516,14 +777,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useEffect(() => {
       if (iframeReadyVersion === 0) return;
       function sendTheme() {
-        iframeRef.current?.contentWindow?.postMessage(
+        postToBridge(
           {
             type: `${PREFIX}theme`,
             tokens: buildThemeTokenPayload(readThemeTokens(), hostTheme),
             isLight: isLightTheme(),
             hostTheme,
           },
-          "*",
         );
       }
       sendTheme();
@@ -538,7 +798,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     useImperativeHandle(ref, () => ({
       removeHighlight: hook.removeHighlight,
       clearAllHighlights: hook.clearAllHighlights,
-      applySharedAnnotations: hook.applyAnnotations,
+      // Shared/draft restores respect the live page filter too.
+      applySharedAnnotations: (anns: Annotation[]) =>
+        hook.applyAnnotations(forCurrentPage(anns)),
     }));
 
     const handleGlobalCommentSubmit = useCallback(
@@ -629,6 +891,20 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
             data-print-region="article"
             className={fullViewport ? "relative overflow-hidden w-full flex-1" : "relative bg-card rounded-xl shadow-xl overflow-hidden w-full"}
           >
+            {/* Armed affordance: a subtle accent ring floats over the iframe
+                while Annotate is armed (hosts that wire the toggle only).
+                Overlaid + pointer-transparent, so it never shifts layout and
+                never eats a click; an inset shadow on the article itself
+                would paint UNDER the covering iframe. */}
+            {!readOnly && annotateModeActive && (onAnnotateModeExit || onAnnotateModeToggle) && (
+              <div
+                aria-hidden
+                data-print-hide
+                data-annotate-armed-ring
+                className="pointer-events-none absolute inset-0 z-10"
+                style={{ boxShadow: "inset 0 0 0 2px color-mix(in srgb, var(--primary) 45%, transparent)" }}
+              />
+            )}
             {/* Full-viewport mode has no card chrome, so float the same controls
                 over the top-right of the iframe (with a backdrop so they read over
                 any HTML). The selection toolbar is portaled separately. */}
@@ -640,10 +916,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 {actionButtons}
               </div>
             )}
+            {/* Live proxied-app mode navigates a real loopback origin: no
+                sandbox (the user's own app needs cookies, storage, and
+                same-origin XHR) and no srcdoc. Srcdoc mode is unchanged. */}
             <iframe
               ref={iframeRef}
-              srcDoc={srcdoc}
-              sandbox="allow-scripts"
+              {...(src ? { src } : { srcDoc: srcdoc, sandbox: "allow-scripts" })}
               style={{
                 width: "100%",
                 height: fullViewport ? "100%" : `${iframeHeight}px`,
@@ -700,9 +978,17 @@ 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 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}
-              onQuickLabel={hook.handleQuickLabel}
               onClose={hook.handleToolbarClose}
             />,
             document.body,
@@ -716,7 +1002,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               contextText={hook.commentPopover.contextText}
               initialText={hook.commentPopover.initialText}
               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}
@@ -735,18 +1026,6 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
             document.body,
           )}
 
-        {/* Quick label picker portal */}
-        {!readOnly && hook.quickLabelPicker &&
-          createPortal(
-            <FloatingQuickLabelPicker
-              anchorEl={hook.quickLabelPicker.anchorEl}
-              cursorHint={hook.quickLabelPicker.cursorHint}
-              onSelect={hook.handleFloatingQuickLabel}
-              onDismiss={hook.handleQuickLabelPickerDismiss}
-            />,
-            document.body,
-          )}
-
         {/* Global comment popover portal */}
         {!readOnly && globalCommentPopover &&
           createPortal(