@plannotator/ui 0.31.0 → 0.33.0

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

@@ -0,0 +1,9 @@
+// @generated by scripts/build-bridge-assets.ts from ./bridge-script.ts. DO NOT EDIT.
+// Alias target for hosts on the HtmlViewer `bridgeScriptUrl` path: the same
+// annotation CSS, protocol version and live bootstrap as ./bridge-script, with
+// the inline bridge literal stubbed out so a bundler drops it from the viewer
+// chunk. Rendering an HtmlViewer WITHOUT bridgeScriptUrl under this alias throws.
+export const ANNOTATION_HIGHLIGHT_CSS = "\n/* Committed annotation visuals (highlight rectangles + numbered placed\n * markers) render inside a shadow-rooted fixed overlay host — see OVERLAY_CSS\n * in the bridge script. Nothing annotation-related is ever wrapped into or\n * styled onto the author's own elements. */\n/* Vim pinpoint target tint. The MOUSE pinpoint path no longer mutates author\n * elements — it draws the dedicated overlay box below — but keyboard (vim)\n * navigation keeps this class-based visual. */\n.plannotator-pinpoint-hover {\n  background-color: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.12) !important;\n  border-radius: 3px;\n  cursor: pointer !important;\n}\n/* SVG groups can't render a CSS background, so use a soft glow instead. */\n.plannotator-pinpoint-hover:is(g, svg) {\n  filter: drop-shadow(0 0 4px oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.55));\n}\n/* Mouse pinpoint hover: a fixed-position outline box sized to the hovered\n * element's rect. Never a class/style write on the page's own elements. */\n[data-plannotator-pinpoint-box] {\n  position: fixed;\n  z-index: 2147483643;\n  pointer-events: none;\n  display: none;\n  box-sizing: border-box;\n  border: 2px solid oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.85);\n  border-radius: 5px;\n  background: oklch(from var(--pn-focus-highlight, #4493f8) l c h / 0.06);\n}\n[data-plannotator-pinpoint-box].pn-pin-enter {\n  animation: pn-pinpoint-in 0.12s ease-out;\n}\n[data-plannotator-pinpoint-box][data-pinned] {\n  border-color: var(--pn-accent, #d97757);\n  background: oklch(from var(--pn-accent, #d97757) l c h / 0.08);\n}\n@keyframes pn-pinpoint-in {\n  from { opacity: 0; transform: scale(0.985); }\n  to { opacity: 1; transform: scale(1); }\n}\n/* Pinpoint mode affordance: crosshair everywhere. Placed markers live in the\n * shadow overlay and keep their own pointer cursor there. */\nbody[data-plannotator-pinpoint-cursor],\nbody[data-plannotator-pinpoint-cursor] * {\n  cursor: crosshair !important;\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-pinpoint-box].pn-pin-enter {\n    animation: none;\n  }\n}\n@media print {\n  /* Viewer overlays are review chrome, not page content: never bake pinpoint\n     boxes/labels or vim UI into a printed page. The outer app chrome is\n     print-hidden by print.css, but this CSS lives inside the iframe's own\n     document and must carry its own rule. The annotation overlay host carries\n     its own print rule inside its shadow root. */\n  [data-plannotator-pinpoint-box],\n  [data-plannotator-pinpoint-label],\n  [data-plannotator-vim-ui],\n  [data-plannotator-vim-cursor] {\n    display: none !important;\n  }\n}\n/* Print-parity layer: committed highlight rects re-projected into an\n * absolute-positioned light-DOM layer built on beforeprint and torn down on\n * afterprint (the fixed overlay cannot paginate). Guarded here so it can\n * never flash on screen even if an afterprint teardown is missed. */\n@media screen {\n  [data-plannotator-print-layer] {\n    display: none !important;\n  }\n}\nbody[data-plannotator-vim-focus-owner]:focus {\n  outline: none !important;\n}\n[data-plannotator-vim-cursor] {\n  position: fixed;\n  z-index: 2147483646;\n  width: 2px;\n  min-height: 1em;\n  border-radius: 2px;\n  background: var(--pn-focus-highlight, #4493f8);\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] {\n  position: fixed;\n  z-index: 2147483645;\n  inset: 0;\n  overflow: visible;\n  pointer-events: none;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill],\n[data-plannotator-vim-reticle] [data-vim-reticle-corner],\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  position: absolute;\n  top: 0;\n  left: 0;\n  will-change: transform;\n  transition: transform 90ms cubic-bezier(.22,1,.36,1);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-fill] {\n  width: 100px;\n  height: 100px;\n  transform-origin: 0 0;\n  border-radius: 8px;\n  background: rgba(167,139,250,.045);\n  box-shadow:\n    inset 0 0 0 1px rgba(196,181,253,.16),\n    0 0 42px rgba(139,92,246,.12);\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner] {\n  width: 28px;\n  height: 28px;\n  border-color: #c4b5fd;\n  filter:\n    drop-shadow(0 0 6px rgba(167,139,250,.92))\n    drop-shadow(0 0 18px rgba(124,58,237,.42));\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-left\"] {\n  border-top: 3px solid;\n  border-left: 3px solid;\n  border-top-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"top-right\"] {\n  border-top: 3px solid;\n  border-right: 3px solid;\n  border-top-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-left\"] {\n  border-bottom: 3px solid;\n  border-left: 3px solid;\n  border-bottom-left-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-corner=\"bottom-right\"] {\n  border-right: 3px solid;\n  border-bottom: 3px solid;\n  border-bottom-right-radius: 8px;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label] {\n  z-index: 1;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 118px;\n  height: 30px;\n  max-width: min(280px, calc(100vw - 24px));\n  padding: 0 11px;\n  overflow: hidden;\n  border: 1px solid rgba(216,206,255,.42);\n  border-radius: 9px;\n  color: #f6f2ff;\n  background: rgba(18,14,28,.84);\n  box-shadow:\n    0 10px 28px rgba(0,0,0,.42),\n    0 0 20px rgba(139,92,246,.18);\n  backdrop-filter: blur(10px);\n  font: 700 10px/1 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .13em;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n[data-plannotator-vim-reticle] [data-vim-reticle-label]::before {\n  width: 7px;\n  height: 7px;\n  flex: 0 0 auto;\n  border-radius: 999px;\n  background: #c4b5fd;\n  box-shadow: 0 0 12px rgba(167,139,250,.94);\n  content: \"\";\n}\n@media (prefers-reduced-motion: reduce) {\n  [data-plannotator-vim-reticle] [data-vim-reticle-fill],\n  [data-plannotator-vim-reticle] [data-vim-reticle-corner],\n  [data-plannotator-vim-reticle] [data-vim-reticle-label] {\n    transition: none;\n  }\n}\n[data-plannotator-vim-badge] {\n  position: fixed;\n  z-index: 2147483647;\n  left: 50%;\n  bottom: 12px;\n  transform: translateX(-50%);\n  padding: 4px 9px;\n  border: 1px solid color-mix(in srgb, var(--pn-focus-highlight, #4493f8) 35%, transparent);\n  border-radius: 6px;\n  background: color-mix(in srgb, var(--pn-background, #111) 94%, transparent);\n  color: var(--pn-focus-highlight, #4493f8);\n  box-shadow: 0 4px 18px rgba(0,0,0,.25);\n  font: 700 10px/1.2 ui-monospace, SFMono-Regular, Menlo, monospace;\n  letter-spacing: .04em;\n  pointer-events: none;\n}\n";
+export const BRIDGE_PROTOCOL_VERSION = 1;
+export const BRIDGE_SCRIPT = "";
+export const LIVE_BRIDGE_BOOTSTRAP = "(function() {\n  var config = window.__plannotatorLiveConfig;\n  if (!config || typeof config.css !== 'string') return;\n  try {\n    var style = document.createElement('style');\n    style.setAttribute('data-plannotator-live-css', '');\n    style.appendChild(document.createTextNode(config.css));\n    (document.head || document.documentElement).appendChild(style);\n  } catch (ex) {}\n})();";

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

@@ -210,6 +210,18 @@ body[data-plannotator-vim-focus-owner]:focus {
 }
 `;
 
+/**
+ * Bridge protocol version. Stamped on the bridge's `ready` message
+ * (`protocolVersion`) and compared by the parent (HtmlViewer) against this
+ * same constant. Bump it whenever a message shape changes in a way an older
+ * bridge or an older parent would misread. The inline srcdoc path and the
+ * live proxy always ship the bridge from the same bundle as the parent, so
+ * they match by construction; the check exists for hosts that serve the
+ * generated `bridge-script.asset.js` separately (`bridgeScriptUrl`), where a
+ * cached asset from a previous package version can outlive the parent code.
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1;
+
 export const BRIDGE_SCRIPT = `(function() {
   var PREFIX = 'plannotator-bridge-';
 
@@ -339,6 +351,17 @@ export const BRIDGE_SCRIPT = `(function() {
   var pendingMultiTargets = []; // { key, el, anchor, label, text, box }
   var multiTargetSeq = 0;
   var MAX_MULTI_TARGETS = 16;
+  // Per-draft cap on additional targets: the parent may lower it on
+  // arm-multi-select ({ max }) to its product cap so the toggle stops where
+  // the saved annotation would. Never above MAX_MULTI_TARGETS; reset with
+  // the arm on every draft.
+  var multiSelectMax = MAX_MULTI_TARGETS;
+  function clampMultiSelectMax(value) {
+    if (typeof value !== 'number' || !isFinite(value)) return MAX_MULTI_TARGETS;
+    var whole = Math.floor(value);
+    if (whole < 0) return 0;
+    return whole > MAX_MULTI_TARGETS ? MAX_MULTI_TARGETS : whole;
+  }
   // Live mode clamps the INPUT METHOD to pinpoint (click = element). Text
   // drag-selection is a separate, always-on channel — see the mouseup handler
   // — so the clamp only decides what a plain click does, never whether text
@@ -637,6 +660,10 @@ export const BRIDGE_SCRIPT = `(function() {
         && e.data.key === pendingPinKey
       ) {
         multiSelectArmed = true;
+        // Optional product cap for THIS draft; absent keeps the bridge's own.
+        multiSelectMax = e.data.max === undefined
+          ? MAX_MULTI_TARGETS
+          : clampMultiSelectMax(e.data.max);
       }
     }
 
@@ -655,14 +682,25 @@ export const BRIDGE_SCRIPT = `(function() {
       // Selecting an annotation scrolls its first resolved target into view
       // and flashes the overlay focus highlight over EVERY rect of EVERY
       // target — never a class write on page elements, and never only the
-      // first fragment of a multi-paragraph selection.
-      scrollToAnnotation(e.data.id);
+      // first fragment of a multi-paragraph selection. The optional
+      // behavior lets the parent pass its reduced-motion preference across
+      // the boundary; absent means smooth, as before.
+      scrollToAnnotation(e.data.id, e.data.behavior === 'auto' ? 'auto' : 'smooth');
     }
 
     else if (type === PREFIX + 'focus-mark') {
       focusAnnotationRecord(typeof e.data.id === 'string' ? e.data.id : null, false);
     }
 
+    else if (type === PREFIX + 'report-unanchored') {
+      // The parent posted its restore batch and wants the complete set once
+      // the next complete overlay pass has run, even if the set is unchanged
+      // (empty included). Messages are processed in order, so the pass this
+      // schedules sees every find-and-mark posted before this request.
+      unanchoredReportRequested = true;
+      schedulePinpointReconcile();
+    }
+
     else if (type === PREFIX + 'set-input-method') {
       // Live mode clamps the input method to pinpoint (what a plain click
       // does); text drag-selection commenting stays live regardless.
@@ -1488,6 +1526,10 @@ export const BRIDGE_SCRIPT = `(function() {
   // whose records are removed and therefore invisible to the per-pass scan.
   var lastUnanchoredKey = '[]';
   var restoreFailedIds = new Set();
+  // Set by report-unanchored: the parent asks for the complete set after
+  // its restore batch, so the next COMPLETE pass emits even when the set
+  // did not change (an all-restored document reports its empty set once).
+  var unanchoredReportRequested = false;
   function emitUnanchored(deadRecordIds) {
     var seen = new Set();
     var combined = [];
@@ -1506,7 +1548,8 @@ export const BRIDGE_SCRIPT = `(function() {
     combined.sort();
     if (combined.length > 512) combined = combined.slice(0, 512);
     var key = JSON.stringify(combined);
-    if (key === lastUnanchoredKey) return;
+    if (key === lastUnanchoredKey && !unanchoredReportRequested) return;
+    unanchoredReportRequested = false;
     lastUnanchoredKey = key;
     // postToParent, not a raw '*' post: live sessions stamp the session
     // token and post only to the listed editor origins, and the parent
@@ -2495,7 +2538,7 @@ export const BRIDGE_SCRIPT = `(function() {
     }
   }
 
-  function scrollToAnnotation(id) {
+  function scrollToAnnotation(id, behavior) {
     var record = findAnnRecord(id);
     if (!record) return;
     beginDeadSearchPass(Infinity); // user-initiated one-shot: never budget-starved
@@ -2511,7 +2554,7 @@ export const BRIDGE_SCRIPT = `(function() {
       }
     }
     if (scrollEl) {
-      try { scrollEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (ex) {}
+      try { scrollEl.scrollIntoView({ behavior: behavior || 'smooth', block: 'center' }); } catch (ex) {}
     }
     focusAnnotationRecord(id, true);
   }
@@ -2693,6 +2736,7 @@ export const BRIDGE_SCRIPT = `(function() {
     pendingPinPoint = null;
     pendingPinViaPinpoint = false;
     multiSelectArmed = false;
+    multiSelectMax = MAX_MULTI_TARGETS;
     hidePinpointBox();
   }
 
@@ -2857,8 +2901,9 @@ export const BRIDGE_SCRIPT = `(function() {
         }
       }
     }
-    // Cap at the source: never grow the draft past the parent-side DTO cap.
-    if (pendingMultiTargets.length >= MAX_MULTI_TARGETS) return;
+    // Cap at the source: never grow the draft past the parent-side DTO cap
+    // (or the lower product cap the parent armed this draft with).
+    if (pendingMultiTargets.length >= multiSelectMax) return;
     var point = normalizePointInElement(el, clickPoint);
     if (anchor && point) anchor.point = point;
     var label = pinpointHoverLabel(el);
@@ -2961,6 +3006,7 @@ export const BRIDGE_SCRIPT = `(function() {
     // drafts (comment -> quick label) leaves a stale arm and the bridge
     // accumulates pins the saved annotation will not carry.
     multiSelectArmed = false;
+    multiSelectMax = MAX_MULTI_TARGETS;
     pendingPinEl = el;
     pendingPinAnchor = buildElementAnchor(el);
     pendingPinKey = makeTargetKey();
@@ -4538,7 +4584,7 @@ export const BRIDGE_SCRIPT = `(function() {
     // pinpoint: show the cursor affordance immediately instead of waiting for
     // the parent's first set-input-method/set-annotate-mode round trip.
     updatePinpointCursor();
-    var readyMsg = { type: PREFIX + 'ready' };
+    var readyMsg = { type: PREFIX + 'ready', protocolVersion: ${BRIDGE_PROTOCOL_VERSION} };
     if (LIVE) readyMsg.pageUrl = currentPageUrl();
     postToParent(readyMsg);
   }

package/components/html-viewer/hostThreads.ts

@@ -0,0 +1,37 @@
+/**
+ * Host-side helpers for the raw-HTML viewer, re-exported from
+ * `@plannotator/core/html-anchor` with the package's `Annotation` type.
+ *
+ * `projectHostThreads` turns a host's stored rows into the `annotations`
+ * prop (output order == marker numbering); `buildPersistedHtmlAnchor` trims a
+ * composed comment's anchor to a bounded record the host can persist. Both
+ * are pure and dependency-free (they live in `@plannotator/core`).
+ */
+import {
+  projectHostThreads as projectHostThreadsCore,
+  type HostThread,
+  type ProjectHostThreadsOptions,
+} from "@plannotator/core/html-anchor";
+import type { Annotation } from "../../types";
+
+export {
+  buildPersistedHtmlAnchor,
+  type BuildPersistedHtmlAnchorOptions,
+  type HostThread,
+  type PersistedHtmlAnchor,
+  type PersistedHtmlAnchorResult,
+  type ProjectHostThreadsOptions,
+} from "@plannotator/core/html-anchor";
+
+/**
+ * Project stored host rows onto the viewer's `annotations` prop, in the
+ * host's order (which becomes the marker numbering). See the core function
+ * for the projection rules; the `type` literals it emits are the string
+ * values of `AnnotationType`, so the cast below is representation-exact.
+ */
+export function projectHostThreads(
+  threads: readonly HostThread[],
+  options?: ProjectHostThreadsOptions,
+): Annotation[] {
+  return projectHostThreadsCore(threads, options) as unknown as Annotation[];
+}

package/components/html-viewer/index.ts

@@ -1 +1,22 @@
-export { HtmlViewer, type HtmlViewerProps } from "./HtmlViewer";
+export {
+  DEFAULT_BRIDGE_READY_TIMEOUT_MS,
+  HtmlViewer,
+  formatBridgeUnavailableMessage,
+  type BridgeUnavailableInfo,
+  type HtmlViewerProps,
+} from "./HtmlViewer";
+export { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
+export {
+  checkBridgeProtocolVersion,
+  formatBridgeProtocolWarning,
+  type BridgeProtocolVerdict,
+} from "./useHtmlAnnotation";
+export {
+  buildPersistedHtmlAnchor,
+  projectHostThreads,
+  type BuildPersistedHtmlAnchorOptions,
+  type HostThread,
+  type PersistedHtmlAnchor,
+  type PersistedHtmlAnchorResult,
+  type ProjectHostThreadsOptions,
+} from "./hostThreads";

package/components/html-viewer/srcdoc.ts

@@ -96,6 +96,68 @@ export interface SrcdocInjectionOptions {
   hostTheme: boolean;
   /** The version-diff view is showing (rawHtml is htmlDiff output). */
   diffActive: boolean;
+  /**
+   * Load the bridge through a classic `<script src>` from this URL instead of
+   * inlining `BRIDGE_SCRIPT`. Absent or empty: inline, exactly as before. The
+   * tag takes the inline script's place, so placement is identical on both
+   * paths: at the end of `<head>`, before the body (head scripts of the page
+   * run first, body scripts after the bridge). No `crossorigin` attribute is
+   * set: the srcdoc frame is an opaque origin, and a classic script needs no
+   * CORS to execute. Callers must pass an ABSOLUTE URL (see
+   * {@link resolveBridgeScriptUrl}): the framed page may carry its own
+   * `<base href>`, which precedes the injected tag and would re-anchor a
+   * relative URL onto an attacker-chosen origin.
+   */
+  bridgeScriptUrl?: string;
+}
+
+/**
+ * Resolve a host-supplied bridge URL against the PARENT document (its
+ * `document.baseURI`), never against the framed page. The injection lands at
+ * the end of the page's `<head>`, after any `<base href>` the page declares,
+ * so a relative URL written into the srcdoc would resolve against that base:
+ * a hostile document could point the viewer at an attacker-served bridge and
+ * defeat the version check. Resolving here pins the URL before it is written.
+ * An unparsable input is returned unchanged (nothing loads, the ready timeout
+ * reports it) rather than throwing during render.
+ */
+export function resolveBridgeScriptUrl(bridgeScriptUrl: string, parentBaseUrl: string): string {
+  try {
+    return new URL(bridgeScriptUrl, parentBaseUrl).href;
+  } catch {
+    return bridgeScriptUrl;
+  }
+}
+
+/** Escape a string for a double-quoted HTML attribute value. */
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * The bridge `<script>` element, the ONE injection point for both delivery
+ * paths. Inline is the default and Plannotator's only path; the URL form is
+ * the opt-in for hosts that serve the generated `bridge-script.asset.js`.
+ */
+export function buildBridgeScriptTag(bridgeScriptUrl?: string): string {
+  if (bridgeScriptUrl) {
+    return `<script src="${escapeAttribute(bridgeScriptUrl)}"></script>`;
+  }
+  if (!BRIDGE_SCRIPT) {
+    // Only reachable when a host aliased `./bridge-script` to the generated
+    // `bridge-script.lite` module (which stubs the inline literal) and then
+    // rendered an HtmlViewer without `bridgeScriptUrl`: an empty inline
+    // script would be a silently dead surface, so fail loudly instead.
+    throw new Error(
+      "@plannotator/ui HtmlViewer: the inline bridge script is stubbed out "
+        + "(bridge-script.lite alias) but no bridgeScriptUrl was passed.",
+    );
+  }
+  return `<script>${BRIDGE_SCRIPT}</script>`;
 }
 
 /** The `<style>` + `<script>` block spliced into the document's head. */
@@ -104,6 +166,7 @@ export function buildSrcdocInjection({
   isLight,
   hostTheme,
   diffActive,
+  bridgeScriptUrl,
 }: SrcdocInjectionOptions): string {
   const payload = buildThemeTokenPayload(tokens, hostTheme);
   let themeCSS = ":root {\n";
@@ -117,7 +180,7 @@ export function buildSrcdocInjection({
     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>`;
+  return `<style>${themeCSS}${ANNOTATION_HIGHLIGHT_CSS}${diffCSS}</style>${buildBridgeScriptTag(bridgeScriptUrl)}`;
 }
 
 /**
@@ -126,6 +189,12 @@ export function buildSrcdocInjection({
  * script and disables annotation entirely. The iframe `sandbox` attribute is
  * the security boundary for the annotate surface; the page's CSP was written
  * for its standalone context, so it is removed before injection.
+ *
+ * The package itself never adds a CSP `<meta>` to the srcdoc document (the
+ * injection is one `<style>` and one `<script>`), so nothing here blocks a
+ * `<script src>` on the URL path. A CSP delivered as an HTTP header on the
+ * HOST page is inherited by the srcdoc document, and the host must allow
+ * `script-src` for the origin the asset is served from.
  */
 const META_CSP_RE =
   /<meta\s[^>]*http-equiv\s*=\s*["']?\s*content-security-policy\s*["']?[^>]*\/?>/gi;

package/components/html-viewer/unanchored.ts

@@ -0,0 +1,47 @@
+import { AnnotationType, type Annotation } from "../../types";
+
+/**
+ * A page-anchored row the viewer can never post to the bridge: nothing to
+ * find it by (no quoted text, no element anchor, no additional target
+ * anchor). Document-level comments are excluded on purpose: a
+ * GLOBAL_COMMENT has no page location by design and is not "unanchored".
+ */
+export function isTextlessPageAnnotation(annotation: Annotation): boolean {
+  if (annotation.type === AnnotationType.GLOBAL_COMMENT) return false;
+  if (annotation.originalText) return false;
+  if (annotation.htmlAnchor) return false;
+  return !(annotation.htmlAdditionalTargets ?? []).some((target) => !!target.anchor);
+}
+
+/**
+ * The host-facing unanchored set: the bridge's report (ids with no live
+ * representation on the page) completed with what the bridge cannot see.
+ *
+ * - Textless page rows are added: they were never posted, so the bridge
+ *   cannot report them, yet they have no marker and no highlight.
+ * - An id this viewer minted for a locally created comment (`create-mark`)
+ *   that the host never carried in `annotations`, or has since swapped out
+ *   for its own id, is dropped: the host holds no card for it, so naming it
+ *   would be noise. Every other bridge id passes through untouched, so a
+ *   host that paints through the imperative handle keeps today's delivery.
+ *
+ * Sorted and deduplicated like the bridge's own emission. With no textless
+ * rows and no swapped-out minted ids the result is exactly the bridge list.
+ */
+export function mergeUnanchoredIds(input: {
+  bridgeIds: readonly string[];
+  annotations: readonly Annotation[];
+  createdIds: ReadonlySet<string>;
+}): string[] {
+  const known = new Set<string>();
+  for (const annotation of input.annotations) known.add(annotation.id);
+  const out = new Set<string>();
+  for (const id of input.bridgeIds) {
+    if (input.createdIds.has(id) && !known.has(id)) continue;
+    out.add(id);
+  }
+  for (const annotation of input.annotations) {
+    if (isTextlessPageAnnotation(annotation)) out.add(annotation.id);
+  }
+  return [...out].sort();
+}

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
 import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type ImageAttachment } from "../../types";
-import type { QuickLabel } from "../../utils/quickLabels";
+import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
   ToolbarState,
@@ -8,9 +8,46 @@ import type {
   QuickLabelPickerState,
   UseAnnotationHighlighterReturn,
 } from "../../hooks/useAnnotationHighlighter";
+import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
 
 const PREFIX = "plannotator-bridge-";
 
+/** Outcome of comparing a bridge `ready` message's stamp with this parent. */
+export interface BridgeProtocolVerdict {
+  ok: boolean;
+  /** The version this parent bundle speaks (`BRIDGE_PROTOCOL_VERSION`). */
+  expected: number;
+  /** The version the bridge reported; `undefined` when the ready carried none
+   *  (a bridge asset built before the stamp existed, or a forged message). */
+  reported: number | undefined;
+}
+
+/**
+ * Compare a `ready` message against the parent's protocol version. A missing
+ * stamp counts as a mismatch: the only way it can be absent is a bridge asset
+ * older than the parent (or a page forging the message), which is exactly
+ * the drift this check exists to name.
+ */
+export function checkBridgeProtocolVersion(data: unknown): BridgeProtocolVerdict {
+  const raw = isRecord(data) ? data.protocolVersion : undefined;
+  const reported = typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+  return {
+    ok: reported === BRIDGE_PROTOCOL_VERSION,
+    expected: BRIDGE_PROTOCOL_VERSION,
+    reported,
+  };
+}
+
+/** The one console warning a mismatch produces; names both versions. */
+export function formatBridgeProtocolWarning(
+  verdict: BridgeProtocolVerdict,
+  bridgeScriptUrl?: string,
+): string {
+  const reported = verdict.reported === undefined ? "none" : String(verdict.reported);
+  const source = bridgeScriptUrl ? `the bridge script at ${bridgeScriptUrl}` : "the bridge script";
+  return `[plannotator] HTML bridge protocol version mismatch: this viewer expects ${verdict.expected}, ${source} reported ${reported}. Serve the bridge-script asset from the same @plannotator/ui version as the viewer.`;
+}
+
 // Collision-proof annotation ids. `Date.now()` alone repeats within a millisecond,
 // so two quick annotations could share a data-bind-id and clobber each other.
 let htmlAnnSeq = 0;
@@ -18,6 +55,13 @@ function nextHtmlAnnId(): string {
   return `html-ann-${Date.now().toString(36)}-${(htmlAnnSeq++).toString(36)}`;
 }
 
+/** Ids minted by this module for locally created annotations (create-mark).
+ * Module-scoped like the sequence above: a host that swaps a local id for
+ * its own server id keeps the local mark until it removes it, and the
+ * unanchored union needs to recognise such ids whichever viewer instance
+ * minted them. Bounded: only ids from this page load, one entry per create. */
+const mintedHtmlAnnIds = new Set<string>();
+
 function htmlCommentDraftKey(
   text: string,
   anchor?: HtmlElementAnchor | null,
@@ -129,6 +173,20 @@ export interface UseHtmlAnnotationOptions {
    *  empty on recovery. Delivered in readOnly mode too: view-only surfaces
    *  are exactly where silently missing markers would go unnoticed. */
   onUnanchoredChange?: (ids: string[]) => void;
+  /** Product cap on additional (shift-click) targets per comment, 0..16.
+   *  Applied at the trust boundary, on submit, on restore, and carried to
+   *  the bridge on arm-multi-select so the in-page toggle stops at the
+   *  same number. Absent: the package's 16, and the arm message is unchanged. */
+  maxAdditionalTargets?: number;
+  /** scrollIntoView behavior for scroll-to (selecting an annotation).
+   *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
+  scrollBehavior?: 'smooth' | 'auto';
+}
+
+/** Clamp a host cap into the package's bound; anything unusable is the default. */
+export function resolveMaxAdditionalTargets(value: number | undefined): number {
+  if (value === undefined || !Number.isFinite(value)) return MAX_ADDITIONAL_TARGETS;
+  return Math.max(0, Math.min(MAX_ADDITIONAL_TARGETS, Math.floor(value)));
 }
 
 function postToIframe(
@@ -365,6 +423,8 @@ export function useHtmlAnnotation({
   onPageChange,
   onBridgePointer,
   onUnanchoredChange,
+  maxAdditionalTargets,
+  scrollBehavior,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -377,6 +437,13 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
+  /** Composer one-click "Looks good": submits the hardcoded positive label
+   *  with the same anchor and multi-select targets a typed comment would carry. */
+  handleCommentLooksGood: () => void;
+  /** Ids this module minted for locally created annotations (create-mark),
+   *  for the unanchored union: a minted id the host never listed is a
+   *  swapped-out local mark, not a host row. Read-only, stable identity. */
+  createdAnnotationIds: ReadonlySet<string>;
 } {
   const [toolbarState, setToolbarState] = useState<ToolbarState | null>(null);
   const [commentPopover, setCommentPopover] = useState<CommentPopoverState | null>(null);
@@ -417,6 +484,12 @@ export function useHtmlAnnotation({
   liveRef.current = live ?? null;
   const onPageChangeRef = useRef(onPageChange);
   onPageChangeRef.current = onPageChange;
+  // The effective cap and whether the host set one: only an explicit cap
+  // rides on arm-multi-select, so an unconfigured viewer posts today's message.
+  const maxTargetsRef = useRef(resolveMaxAdditionalTargets(maxAdditionalTargets));
+  maxTargetsRef.current = resolveMaxAdditionalTargets(maxAdditionalTargets);
+  const hostCapRef = useRef(maxAdditionalTargets !== undefined);
+  hostCapRef.current = maxAdditionalTargets !== undefined;
 
   const anchorRef = useRef<HTMLDivElement | null>(null);
 
@@ -577,6 +650,7 @@ export function useHtmlAnnotation({
             post({
               type: `${PREFIX}arm-multi-select`,
               key: message.targetKey,
+              ...(hostCapRef.current ? { max: maxTargetsRef.current } : {}),
             });
           }
         } else {
@@ -596,7 +670,7 @@ export function useHtmlAnnotation({
         if (
           commentPopoverRef.current
           && targets.length > 0
-          && targets.length < 1 + MAX_ADDITIONAL_TARGETS
+          && targets.length < 1 + maxTargetsRef.current
           && !targets.some((t) => t.key === message.key)
         ) {
           setDraftTargets([
@@ -712,6 +786,9 @@ export function useHtmlAnnotation({
       post({
         type: `${PREFIX}scroll-to`,
         id: selectedAnnotationId,
+        // Only an explicit host preference rides along; the default message
+        // is unchanged and the bridge scrolls smoothly as before.
+        ...(scrollBehavior ? { behavior: scrollBehavior } : {}),
       });
     } else {
       post({
@@ -719,7 +796,7 @@ export function useHtmlAnnotation({
         id: null,
       });
     }
-  }, [selectedAnnotationId, post]);
+  }, [selectedAnnotationId, post, scrollBehavior]);
 
   const handleAnnotate = useCallback(
     (type: AnnotationType) => {
@@ -728,6 +805,7 @@ export function useHtmlAnnotation({
       if (!text || type !== AnnotationType.DELETION) return;
 
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "deletion" });
       onAddRef.current?.({
         id,
@@ -778,7 +856,7 @@ export function useHtmlAnnotation({
       const targets = draftTargetsRef.current;
       const additionalTargets: HtmlAnnotationTarget[] | undefined =
         targets.length > 1
-          ? targets.slice(1, 1 + MAX_ADDITIONAL_TARGETS).map((t) => ({
+          ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
               label: t.label,
               text: t.text,
               anchor: t.anchor ?? undefined,
@@ -786,6 +864,7 @@ export function useHtmlAnnotation({
           : undefined;
 
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -810,6 +889,51 @@ export function useHtmlAnnotation({
     [post],
   );
 
+  // The composer's one-click "Looks good" (the restored thumbs-up for
+  // comment-only surfaces, where pinpoint clicks land straight in the
+  // composer and never see the selection toolbar). Mirrors
+  // handleCommentSubmit — same anchor, same multi-select targets — but
+  // emits the hardcoded positive label instead of typed prose.
+  const handleCommentLooksGood = useCallback(() => {
+    if (!enabledRef.current) return;
+    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
+    if (!text) return;
+
+    const targets = draftTargetsRef.current;
+    const additionalTargets: HtmlAnnotationTarget[] | undefined =
+      targets.length > 1
+        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
+            label: t.label,
+            text: t.text,
+            anchor: t.anchor ?? undefined,
+          }))
+        : undefined;
+
+    const id = nextHtmlAnnId();
+    mintedHtmlAnnIds.add(id);
+    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
+    onAddRef.current?.({
+      id,
+      blockId: "",
+      startOffset: 0,
+      endOffset: 0,
+      type: AnnotationType.COMMENT,
+      text: THUMBS_UP_LABEL.text,
+      originalText: text,
+      isQuickLabel: true,
+      quickLabelTip: THUMBS_UP_LABEL.tip,
+      author: getIdentity(),
+      createdA: Date.now(),
+      htmlAnchor: pendingAnchorRef.current ?? undefined,
+      htmlAdditionalTargets: additionalTargets,
+    });
+
+    setCommentPopover(null);
+    setDraftTargets([]);
+    pendingTextRef.current = "";
+    pendingAnchorRef.current = null;
+  }, [post]);
+
   const handleCommentClose = useCallback(() => {
     post({ type: `${PREFIX}cancel-selection` });
     setCommentPopover(null);
@@ -846,6 +970,7 @@ export function useHtmlAnnotation({
       const text = pendingTextRef.current;
       if (!text) return;
       const id = nextHtmlAnnId();
+      mintedHtmlAnnIds.add(id);
       post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
       onAddRef.current?.({
         id,
@@ -906,7 +1031,7 @@ export function useHtmlAnnotation({
         const additionalAnchors = (ann.htmlAdditionalTargets ?? [])
           .map((t) => t.anchor)
           .filter((a): a is HtmlElementAnchor => !!a)
-          .slice(0, MAX_ADDITIONAL_TARGETS);
+          .slice(0, maxTargetsRef.current);
         post({
           type: `${PREFIX}find-and-mark`,
           id: ann.id,
@@ -931,6 +1056,7 @@ export function useHtmlAnnotation({
     handleToolbarClose,
     handleRequestComment,
     handleCommentSubmit,
+    handleCommentLooksGood,
     handleCommentClose,
     handleFloatingQuickLabel,
     handleQuickLabelPickerDismiss,
@@ -941,5 +1067,6 @@ export function useHtmlAnnotation({
     removeDraftTarget,
     flashDraftTarget,
     composerFocusToken,
+    createdAnnotationIds: mintedHtmlAnnIds,
   };
 }