@plannotator/ui 0.31.0 → 0.33.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,
@@ -37,8 +38,11 @@ import {
   type ComposerYieldState,
 } from "./composerYield";
 import { buildSyncNumbering } from "./annotationNumbering";
+import { mergeUnanchoredIds } from "./unanchored";
 import {
   MAX_PAGE_URL_LENGTH,
+  checkBridgeProtocolVersion,
+  formatBridgeProtocolWarning,
   rejectsLiveMessage,
   useHtmlAnnotation,
   type HtmlLiveSession,
@@ -49,6 +53,7 @@ import {
   buildThemeTokenPayload,
   hasHostThemeOptIn,
   injectIntoHead,
+  resolveBridgeScriptUrl,
 } from "./srcdoc";
 
 const PREFIX = "plannotator-bridge-";
@@ -129,6 +134,38 @@ function parseVimBridgeHelp(value: unknown): boolean | null {
 
 const MAX_VIM_COPY_TEXT_LENGTH = 2 * 1024 * 1024;
 
+/** Default wait for the bridge's `ready` on the `bridgeScriptUrl` path. */
+export const DEFAULT_BRIDGE_READY_TIMEOUT_MS = 5000;
+
+/**
+ * Why the bridge could not be established on the `bridgeScriptUrl` path.
+ * Never produced on the inline path (the bridge and the parent are one
+ * bundle there, and no ready timer runs).
+ */
+export type BridgeUnavailableInfo =
+  | {
+      kind: "timeout";
+      url: string;
+      /** The wait that elapsed without a `ready`. */
+      timeoutMs: number;
+    }
+  | {
+      kind: "version-mismatch";
+      url: string;
+      expectedVersion: number;
+      /** Absent when the ready carried no stamp (a pre-stamp asset). */
+      reportedVersion?: number;
+    };
+
+/** User-facing message for the in-surface error banner. */
+export function formatBridgeUnavailableMessage(info: BridgeUnavailableInfo): string {
+  if (info.kind === "timeout") {
+    return `Annotation tools did not load: the bridge script at ${info.url} sent no ready signal within ${info.timeoutMs} ms. The page is shown without annotation. Check that the URL is reachable and that your Content Security Policy allows script-src for that origin.`;
+  }
+  const reported = info.reportedVersion === undefined ? "no version" : `version ${info.reportedVersion}`;
+  return `Annotation tools may not work: this viewer expects bridge protocol version ${info.expectedVersion}, but the script at ${info.url} reported ${reported}. Serve the bridge-script asset from the same @plannotator/ui version as the viewer.`;
+}
+
 function parseVimBridgeCopy(value: unknown): string | null {
   return isRecord(value)
     && value.type === `${PREFIX}vim-copy`
@@ -202,10 +239,51 @@ 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;
+  /**
+   * Opt-in: load the annotation bridge into the srcdoc document through a
+   * classic `<script src>` from this URL (the package's generated
+   * `components/html-viewer/bridge-script.asset.js`, served by the host)
+   * instead of inlining the 185 KB script into every document. Absent (the
+   * default, and Plannotator's only path): inline, unchanged. The tag lands
+   * where the inline script does, at the end of `<head>`, before the body.
+   * The URL is resolved against THIS document's base (`document.baseURI`)
+   * before it is written, never against the framed page, so a page's own
+   * `<base href>` cannot redirect it. The srcdoc frame is an opaque origin,
+   * so the script needs no CORS and no `crossorigin` attribute is set; a CSP
+   * header on the host page is inherited by the frame and must allow
+   * `script-src` for the asset origin, and the asset must not be served with
+   * `Cross-Origin-Resource-Policy: same-origin`. Ignored in live (`src`)
+   * mode, where the proxy injects the bridge.
+   */
+  bridgeScriptUrl?: string;
+  /**
+   * How long to wait for the bridge's `ready` after each document load on
+   * the `bridgeScriptUrl` path before the surface shows an error state.
+   * Default 5000 ms. No timer runs on the inline path.
+   */
+  bridgeReadyTimeoutMs?: number;
+  /** The bridge could not be established on the `bridgeScriptUrl` path (no
+   *  ready within the timeout, or a protocol version mismatch). The surface
+   *  shows its own banner as well; this lets the host react (telemetry, a
+   *  retry affordance). Never called on the inline path. */
+  onBridgeUnavailable?: (info: BridgeUnavailableInfo) => void;
 }
 
 /**
@@ -245,7 +323,12 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       onAskAI,
       readOnly = false,
       onUnanchoredChange,
+      maxAdditionalTargets,
+      scrollBehavior,
       title = "HTML Plan Viewer",
+      bridgeScriptUrl,
+      bridgeReadyTimeoutMs = DEFAULT_BRIDGE_READY_TIMEOUT_MS,
+      onBridgeUnavailable,
     },
     ref,
   ) => {
@@ -303,6 +386,18 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     // themselves); arbitrary HTML renders untouched, like a standalone tab.
     const hostTheme = useMemo(() => !liveMode && hasHostThemeOptIn(rawHtml), [liveMode, rawHtml]);
 
+    // The URL path is srcdoc-only: live mode has the proxy inject the bridge.
+    // Resolved against THIS document's base before it is written into the
+    // srcdoc, so a framed page's own <base href> can never re-anchor it.
+    const bridgeUrl = useMemo(
+      () => (!liveMode && bridgeScriptUrl
+        ? resolveBridgeScriptUrl(bridgeScriptUrl, document.baseURI)
+        : undefined),
+      [liveMode, bridgeScriptUrl],
+    );
+    const bridgeUrlRef = useRef(bridgeUrl);
+    bridgeUrlRef.current = bridgeUrl;
+
     const srcdoc = useMemo(() => {
       if (liveMode) return undefined; // src mode: the proxy injects the bridge
       const injection = buildSrcdocInjection({
@@ -310,9 +405,46 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         isLight: isLightTheme(),
         hostTheme,
         diffActive: !!diffActive,
+        bridgeScriptUrl: bridgeUrl,
       });
       return injectIntoHead(rawHtml, injection);
-    }, [liveMode, rawHtml, hostTheme, diffActive]);
+    }, [liveMode, rawHtml, hostTheme, diffActive, bridgeUrl]);
+
+    // Error state for the bridgeScriptUrl path only: the inline path never
+    // sets it (no timer, and a version mismatch there can only be a forged
+    // message, which is warned about and otherwise ignored).
+    const [bridgeError, setBridgeError] = useState<BridgeUnavailableInfo | null>(null);
+    // A version-mismatch banner is dismissible (the older bridge keeps
+    // working); reset whenever the error itself changes.
+    const [bridgeErrorDismissed, setBridgeErrorDismissed] = useState(false);
+    const readyTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const onBridgeUnavailableRef = useRef(onBridgeUnavailable);
+    onBridgeUnavailableRef.current = onBridgeUnavailable;
+    // The timeout is read through a ref at arming time: the timer is armed
+    // once per document load (URL or srcdoc change), never re-armed by a
+    // later prop change, so a host adjusting bridgeReadyTimeoutMs after the
+    // bridge is ready can never produce a false timeout.
+    const bridgeReadyTimeoutMsRef = useRef(bridgeReadyTimeoutMs);
+    bridgeReadyTimeoutMsRef.current = bridgeReadyTimeoutMs;
+    useEffect(() => {
+      if (!bridgeUrl || srcdoc === undefined) return;
+      setBridgeError(null);
+      setBridgeErrorDismissed(false);
+      const url = bridgeUrl;
+      const timeoutMs = bridgeReadyTimeoutMsRef.current;
+      readyTimerRef.current = setTimeout(() => {
+        readyTimerRef.current = null;
+        setBridgeError({ kind: "timeout", url, timeoutMs });
+      }, timeoutMs);
+      return () => {
+        if (readyTimerRef.current !== null) clearTimeout(readyTimerRef.current);
+        readyTimerRef.current = null;
+      };
+    }, [bridgeUrl, srcdoc]);
+    useEffect(() => {
+      setBridgeErrorDismissed(false);
+      if (bridgeError) onBridgeUnavailableRef.current?.(bridgeError);
+    }, [bridgeError]);
 
     const handleResize = useCallback((height: number) => {
       if (liveMode) return; // live surfaces are full-viewport; height is ignored
@@ -358,6 +490,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 +559,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;
 
@@ -427,6 +631,33 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
         const live = liveSessionRef.current;
         if (live && rejectsLiveMessage(live, e.origin, e.data)) return;
         if (isBridgeReadyMessage(e.data)) {
+          // Protocol stamp: one console warning on drift, naming both
+          // versions. The ready is still honored (an older bridge answers
+          // every message shape it knows); on the bridgeScriptUrl path the
+          // surface additionally shows its error banner, because there the
+          // drift is a real deployment state (a cached asset from a previous
+          // package version) rather than a forged message.
+          const verdict = checkBridgeProtocolVersion(e.data);
+          const url = bridgeUrlRef.current;
+          if (!verdict.ok) {
+            console.warn(formatBridgeProtocolWarning(verdict, url));
+          }
+          if (url) {
+            if (readyTimerRef.current !== null) {
+              clearTimeout(readyTimerRef.current);
+              readyTimerRef.current = null;
+            }
+            setBridgeError(
+              verdict.ok
+                ? null
+                : {
+                    kind: "version-mismatch",
+                    url,
+                    expectedVersion: verdict.expected,
+                    reportedVersion: verdict.reported,
+                  },
+            );
+          }
           setIframeReadyVersion((version) => version + 1);
           setVimBridgePhase("inactive");
           setVimHudCommand(null);
@@ -547,6 +778,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 +807,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
@@ -815,6 +1058,37 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 {actionButtons}
               </div>
             )}
+            {/* bridgeScriptUrl path only: the bridge did not come up (no
+                ready within the timeout, or a stale asset's version). Floated
+                over the top of the iframe so it never changes the layout the
+                page renders in; the page itself stays visible. */}
+            {bridgeError && !bridgeErrorDismissed && (
+              <div
+                role="alert"
+                data-print-hide
+                data-bridge-error={bridgeError.kind}
+                className="absolute inset-x-0 top-0 z-20 border-b border-destructive/40 bg-destructive/10 px-3 py-2 text-xs text-destructive backdrop-blur-sm"
+                style={{ display: "flex", alignItems: "flex-start", gap: 8 }}
+              >
+                <span style={{ flex: 1 }}>{formatBridgeUnavailableMessage(bridgeError)}</span>
+                {/* Only the mismatch state is dismissible: the older bridge
+                    still works there. A timeout leaves a dead surface, so
+                    that banner stays. Inline styles on purpose: hosts that
+                    build the guides.show viewer scan this file for utility
+                    classes, and this banner must not grow that stylesheet. */}
+                {bridgeError.kind === "version-mismatch" && (
+                  <button
+                    type="button"
+                    data-bridge-error-dismiss
+                    aria-label="Dismiss"
+                    style={{ flexShrink: 0, borderRadius: 4, padding: "2px 6px", fontWeight: 500, cursor: "pointer", background: "transparent", border: "1px solid currentColor", color: "inherit" }}
+                    onClick={() => setBridgeErrorDismissed(true)}
+                  >
+                    Dismiss
+                  </button>
+                )}
+              </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. */}
@@ -877,10 +1151,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 +1177,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}