@plannotator/ui 0.53.1 → 0.55.0

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

@@ -460,6 +460,10 @@ export const BRIDGE_SCRIPT = `(function() {
   // --- Selection ---
   var pendingSelection = null;
   var pendingRange = null; // live range for the pending selection (scroll tracking)
+  // The pending text selection's own text, uncapped: what plain-text Copy
+  // writes. Range.toString() would lose the rendered line breaks between
+  // blocks and keep the source indentation.
+  var pendingCopyText = '';
   var pendingPinEl = null; // element pinned by a pinpoint click (outline + scroll tracking)
   var pendingPinAnchor = null; // serialized anchor for the pending pin
   var pendingPinKey = null; // target key for the primary pinpoint target (multi-select)
@@ -571,7 +575,8 @@ export const BRIDGE_SCRIPT = `(function() {
     }
     skipNextClear = false; // a real text selection happened
     var range = sel.getRangeAt(0);
-    var text = capSelectionText(sel.toString().trim());
+    var fullText = sel.toString().trim();
+    var text = capSelectionText(fullText);
     if (!text) return false;
 
     // A draft now owns the surface: kill the click-to-select hover
@@ -580,6 +585,7 @@ export const BRIDGE_SCRIPT = `(function() {
 
     var rect = range.getBoundingClientRect();
     pendingRange = range;
+    pendingCopyText = fullText;
     pendingSelection = {
       text: text,
       startContainerPath: getNodePath(range.startContainer),
@@ -597,6 +603,13 @@ export const BRIDGE_SCRIPT = `(function() {
       targetKey: (extras && extras.targetKey) || undefined,
       targetLabel: (extras && extras.targetLabel) || undefined,
       context: (extras && extras.context) || undefined,
+      // This bridge answers rich-copy-request for a text selection (the
+      // toolbar's rich-text Copy). Optional and additive: an older bridge
+      // omits it and Copy stays plain text, so no protocol version bump.
+      richCopy: (extras && extras.pinpoint) ? undefined : true,
+      // The quote above was cut to MAX_SELECTION_TEXT: a plain-text copy made
+      // from it alone (no answer to rich-copy-request) says so.
+      textCut: text.length < fullText.length ? true : undefined,
       rect: { top: rect.top, left: rect.left, width: rect.width, height: rect.height }
     });
     renderAnnotationOverlay(); // draft selection highlight (overlay-projected)
@@ -645,6 +658,46 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!e.data || !e.data.type) return;
     var type = e.data.type;
 
+    // Copy (rich text) was pressed in the parent: build the pending text
+    // range's markup now (never on selection). A throw or an oversized range
+    // answers without markup, so the parent copies plain text.
+    if (type === PREFIX + 'rich-copy-request') {
+      // Text and markup are each capped at 256 KiB: past it the text is cut
+      // (never at half a surrogate pair) and marked, and the markup is not
+      // built at all (too large for rich text).
+      var copyHtml = '';
+      var copyText = '';
+      var copyTruncated = false;
+      var copyTooLarge = false;
+      try {
+        if (pendingRange && pendingSelection && pendingSelection.startContainerPath) {
+          copyText = pendingCopyText || pendingRange.toString();
+          if (copyText.length > 262144) {
+            var copyCut = 262144;
+            var copyLast = copyText.charCodeAt(copyCut - 1);
+            if (copyLast >= 0xd800 && copyLast <= 0xdbff) copyCut -= 1;
+            copyText = copyText.slice(0, copyCut);
+            copyTruncated = true;
+            copyTooLarge = true;
+          } else {
+            copyHtml = htmlForRange(pendingRange);
+            if (copyHtml.length > 262144) copyTooLarge = true;
+          }
+        }
+      } catch (err) {
+        copyHtml = '';
+      }
+      postToParent({
+        type: PREFIX + 'rich-copy',
+        id: typeof e.data.id === 'string' ? e.data.id : '',
+        html: copyTooLarge ? '' : copyHtml,
+        text: copyText,
+        truncated: copyTruncated,
+        tooLarge: copyTooLarge
+      });
+      return;
+    }
+
     if (type === PREFIX + 'create-mark') {
       var id = e.data.id;
       var annType = e.data.annotationType || 'comment';
@@ -1362,6 +1415,10 @@ export const BRIDGE_SCRIPT = `(function() {
     return pinpointBoxEl;
   }
   function positionPinpointBox(el) {
+    if (pendingPinHidden(el)) {
+      if (pinpointBoxEl) pinpointBoxEl.style.display = 'none';
+      return;
+    }
     var r = el.getBoundingClientRect();
     var box = getPinpointBoxEl();
     box.style.display = 'block';
@@ -1515,6 +1572,8 @@ export const BRIDGE_SCRIPT = `(function() {
       if (annotateModeActive && currentInputMethod !== 'pinpoint' && lastPointer && !pendingPinEl && !pendingSelection) {
         setHoverHighlight(committedHighlightIdAtCached(lastPointer.x, lastPointer.y));
       }
+      // Before the boxes: it may re-find a replaced target they then follow.
+      reconcilePendingPinVisibility();
       positionMultiTargetBoxes();
       if (pendingPinEl && pendingPinEl.isConnected) {
         positionPinpointBox(pendingPinEl);
@@ -3507,7 +3566,91 @@ export const BRIDGE_SCRIPT = `(function() {
     }
   }
 
+  // A draft's composer hides with its target and keeps the draft: a slide the
+  // page hid (display:none, visibility:hidden, no box) is not a scroll-out.
+  // Offscreen targets stay visible to support roaming multi-select. A target
+  // the page REPLACED with a new element (a framework re-render, a live-app
+  // route change) is found again through its anchor, the way restore re-finds
+  // committed targets; one that cannot be found keeps the composer visible,
+  // so a draft is never left where nobody can reach it.
+  var pendingPinVisible = true;
+  var pendingPinSearchGen = 0;
+  function pendingPinHidden(el) {
+    if (!el || !el.isConnected) return false;
+    if (targetStyleHidden(el)) return true;
+    var rect = el.getBoundingClientRect();
+    return layoutActive() && !rect.width && !rect.height;
+  }
+
+  function refindPendingTarget(anchor, taken) {
+    var found = resolveAnchorElement(anchor);
+    if (!found || isViewerOverlayNode(found)) return null;
+    for (var i = 0; i < taken.length; i++) if (taken[i] === found) return null;
+    return found;
+  }
+
+  // Re-find detached draft targets, once per DOM generation each. Returns
+  // whether the primary moved to a new element.
+  function refreshPendingTargets() {
+    var taken = [pendingPinEl];
+    for (var t = 0; t < pendingMultiTargets.length; t++) taken.push(pendingMultiTargets[t].el);
+    var moved = false;
+    if (pendingPinEl && !pendingPinEl.isConnected && pendingPinAnchor && pendingPinSearchGen !== domGeneration) {
+      pendingPinSearchGen = domGeneration;
+      var found = refindPendingTarget(pendingPinAnchor, taken);
+      if (found) {
+        pendingPinEl = found;
+        // The text range belonged to the replaced element: commit as an
+        // element pin on the new one (as a promoted primary does).
+        if (pendingRange && !rangeAlive(pendingRange)) pendingRange = null;
+        if (pendingSelection && pendingSelection.startContainerPath) {
+          pendingSelection = { element: true, text: pendingSelection.text };
+        }
+        moved = true;
+      }
+    }
+    for (var i = 0; i < pendingMultiTargets.length; i++) {
+      var entry = pendingMultiTargets[i];
+      if (!entry.el || entry.el.isConnected || !entry.anchor || entry.searchGen === domGeneration) continue;
+      entry.searchGen = domGeneration;
+      var next = refindPendingTarget(entry.anchor, taken);
+      if (next) { entry.el = next; taken.push(next); }
+    }
+    return moved;
+  }
+
+  // Re-anchor the parent's composer on the pin (it cannot see the page).
+  function postPendingPinRect() {
+    if (!pendingSelection || !pendingPinEl || !pendingPinEl.isConnected) return;
+    var tracked = pendingRange && rangeAlive(pendingRange) ? pendingRange : pendingPinEl;
+    var r = tracked.getBoundingClientRect();
+    postToParent({
+      type: PREFIX + 'selection-rect',
+      rect: { top: r.top, left: r.left, width: r.width, height: r.height }
+    });
+  }
+
+  function reconcilePendingPinVisibility() {
+    if (!pendingPinEl) return;
+    var moved = refreshPendingTargets();
+    var visible = !pendingPinHidden(pendingPinEl);
+    for (var i = 0; !visible && i < pendingMultiTargets.length; i++) {
+      visible = !pendingPinHidden(pendingMultiTargets[i].el);
+    }
+    // A detached primary has no geometry: never leave its outline behind.
+    if (!pendingPinEl.isConnected && pinpointBoxEl) pinpointBoxEl.style.display = 'none';
+    var shown = visible && !pendingPinVisible;
+    if (visible !== pendingPinVisible) {
+      pendingPinVisible = visible;
+      postToParent({ type: PREFIX + 'pin-visibility', visible: visible });
+      if (!visible && pinpointBoxEl) pinpointBoxEl.style.display = 'none';
+    }
+    if (visible && (moved || shown)) postPendingPinRect();
+  }
+
   function clearPendingPin() {
+    pendingPinVisible = true;
+    pendingPinSearchGen = 0;
     pendingPinEl = null;
     pendingPinContext = null;
     pendingPinAnchor = null;
@@ -3563,6 +3706,7 @@ export const BRIDGE_SCRIPT = `(function() {
   }
 
   function positionBoxToEl(box, el) {
+    if (pendingPinHidden(el)) { box.style.display = 'none'; return; }
     var r = el.getBoundingClientRect();
     box.style.display = 'block';
     box.style.left = r.left + 'px';
@@ -3694,6 +3838,7 @@ export const BRIDGE_SCRIPT = `(function() {
    */
   function removeMultiTargetByKey(key, echo) {
     if (!key) return;
+    schedulePinpointReconcile();
     if (key === pendingPinKey) {
       if (!pendingMultiTargets.length) {
         // Last target gone — the draft is cancelled.
@@ -3710,6 +3855,7 @@ export const BRIDGE_SCRIPT = `(function() {
       var next = pendingMultiTargets.shift();
       destroyMultiTargetBox(next.box);
       pendingPinEl = next.el;
+      pendingPinSearchGen = 0;
       pendingPinAnchor = next.anchor;
       pendingPinKey = next.key;
       pendingPinLabel = next.label;
@@ -3777,6 +3923,7 @@ export const BRIDGE_SCRIPT = `(function() {
     var key = makeTargetKey();
     var box = createMultiTargetBox(el);
     pendingMultiTargets.push({ key: key, el: el, anchor: anchor, label: label, text: text, point: point, context: context, box: box });
+    schedulePinpointReconcile();
     postToParent({
       type: PREFIX + 'multi-target-added',
       key: key,
@@ -3911,6 +4058,8 @@ export const BRIDGE_SCRIPT = `(function() {
     multiSelectArmed = false;
     multiSelectMax = MAX_MULTI_TARGETS;
     pendingPinEl = el;
+    pendingPinVisible = true;
+    pendingPinSearchGen = 0;
     pendingPinAnchor = buildElementAnchor(el);
     pendingPinKey = makeTargetKey();
     pendingPinLabel = pinpointHoverLabel(el);
@@ -5312,6 +5461,29 @@ export const BRIDGE_SCRIPT = `(function() {
     if (document.body) document.body.removeAttribute('data-plannotator-vim-focus-owner');
   }
 
+  // Selected markup for the parent's rich-text Copy button, built only when
+  // the button is pressed (rich-copy-request). Keeps the enclosing formatting
+  // that cloneContents omits for text endpoints (the same semantic ancestors
+  // selectionRangeToHtml keeps) and absolutizes links.
+  function htmlForRange(range) {
+    var holder = document.createElement('div');
+    var fragment = range.cloneContents();
+    var ancestor = range.commonAncestorContainer.nodeType === 1
+      ? range.commonAncestorContainer : range.commonAncestorContainer.parentElement;
+    while (ancestor && ancestor !== document.body) {
+      if (ancestor.matches('a,b,blockquote,code,del,em,h1,h2,h3,h4,h5,h6,i,li,ol,p,pre,s,strong,sub,sup,table,tbody,td,tfoot,th,thead,tr,u,ul')) {
+        var wrapper = ancestor.cloneNode(false);
+        while (fragment.firstChild) wrapper.appendChild(fragment.firstChild);
+        fragment.appendChild(wrapper);
+      }
+      ancestor = ancestor.parentElement;
+    }
+    holder.appendChild(fragment);
+    var links = holder.querySelectorAll('a[href]');
+    for (var i = 0; i < links.length; i++) links[i].setAttribute('href', links[i].href);
+    return holder.innerHTML;
+  }
+
   function copyVimText(text) {
     if (!text) return;
     postToParent({

package/components/html-viewer/useHtmlAnnotation.ts

@@ -9,6 +9,12 @@ import type {
   UseAnnotationHighlighterReturn,
 } from "../../hooks/useAnnotationHighlighter";
 import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
+import {
+  MAX_RICH_CLIPBOARD_HTML_LENGTH,
+  MAX_RICH_CLIPBOARD_OUTPUT_LENGTH,
+  sanitizeRichHtml,
+  type RichCopySource,
+} from "../../utils/richClipboard";
 import {
   parseHtmlElementContext,
   MAX_ELEMENT_CONTEXT_BYTES,
@@ -90,8 +96,27 @@ interface BridgeSelectionMessage {
   targetLabel?: string;
   /** Agent-facing element description (pinpoint clicks) — validated, size-capped. */
   context?: HtmlElementContext;
+  /** The bridge answers `rich-copy-request` for this text selection. */
+  richCopy?: boolean;
+  /** `text` was cut to MAX_SELECTION_TEXT_LENGTH (the page's selection is longer). */
+  textCut?: boolean;
 }
 
+/** The bridge's answer to `rich-copy-request`: the pending range's markup
+ *  (sanitized again here) and its text up to 256 KiB (`truncated` past it),
+ *  or too large for rich text. */
+interface BridgeRichCopyMessage {
+  type: `${typeof PREFIX}rich-copy`;
+  id: string;
+  html: string;
+  text: string;
+  truncated: boolean;
+  tooLarge: boolean;
+}
+
+/** How long the rich-text Copy waits for the bridge before copying the quote as plain text. */
+export const RICH_COPY_TIMEOUT_MS = 1500;
+
 /** One draft target in an in-flight multi-select comment. Index 0 is primary. */
 export interface HtmlDraftTarget {
   key: string;
@@ -119,10 +144,12 @@ interface BridgeRect {
 
 type BridgeMessage =
   | BridgeSelectionMessage
+  | BridgeRichCopyMessage
   | BridgeMultiTargetAddedMessage
   | { type: `${typeof PREFIX}multi-target-removed`; key: string }
   | { type: `${typeof PREFIX}pointer`; x: number; y: number; shift: boolean }
   | { type: `${typeof PREFIX}selection-clear` }
+  | { type: `${typeof PREFIX}pin-visibility`; visible: boolean }
   | { type: `${typeof PREFIX}selection-rect`; rect: BridgeRect }
   | { type: `${typeof PREFIX}keytype`; key: string }
   | { type: `${typeof PREFIX}mark-click`; id: string }
@@ -363,6 +390,8 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
       return {
         type: value.type,
         text: capSelectionText(value.text),
+        ...(value.richCopy === true ? { richCopy: true } : {}),
+        ...(value.textCut === true ? { textCut: true } : {}),
         rect,
         modeOverride: parseEditorMode(value.modeOverride),
         anchor: parseHtmlElementAnchor(value.anchor) ?? undefined,
@@ -395,6 +424,24 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
         : null;
     case `${PREFIX}selection-clear`:
       return { type: value.type };
+    case `${PREFIX}rich-copy`: {
+      // Oversized or malformed markup reads as none (plain text is copied).
+      if (typeof value.id !== "string" || value.id.length === 0 || value.id.length > 64) return null;
+      const text = typeof value.text === "string" && value.text.length <= MAX_RICH_CLIPBOARD_HTML_LENGTH
+        ? value.text : "";
+      const html = typeof value.html === "string" && value.html.length <= MAX_RICH_CLIPBOARD_HTML_LENGTH
+        ? value.html : "";
+      return {
+        type: value.type,
+        id: value.id,
+        html,
+        text,
+        truncated: value.truncated === true,
+        tooLarge: value.tooLarge === true,
+      };
+    }
+    case `${PREFIX}pin-visibility`:
+      return typeof value.visible === 'boolean' ? { type: value.type, visible: value.visible } : null;
     case `${PREFIX}selection-rect`: {
       const rect = parseBridgeRect(value.rect);
       return rect ? { type: value.type, rect } : null;
@@ -474,6 +521,12 @@ export function useHtmlAnnotation({
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
 > & {
+  /** Whether any pinned draft target is still displayed by the page. Always
+   *  true while no composer is open. */
+  pinVisible: boolean;
+  /** False once this draft's composer was hidden with its target: shown
+   *  again, it must not take focus from where the person is. */
+  composerAutoFocus: boolean;
   /** In-flight multi-select targets (index 0 = primary); empty outside pinpoint drafts. */
   draftTargets: HtmlDraftTarget[];
   /** Remove one draft target (chip X). Removing the last cancels the draft. */
@@ -495,6 +548,17 @@ export function useHtmlAnnotation({
   const [quickLabelPicker, setQuickLabelPicker] = useState<QuickLabelPickerState | null>(null);
   const [draftTargets, setDraftTargets] = useState<HtmlDraftTarget[]>([]);
   const [composerFocusToken, setComposerFocusToken] = useState(0);
+  const [pinVisible, setPinVisible] = useState(true);
+  const [composerWasHidden, setComposerWasHidden] = useState(false);
+  const pinVisibleRef = useRef(pinVisible);
+  pinVisibleRef.current = pinVisible;
+  // Visibility belongs to one draft: whatever closes the composer (save, 👍,
+  // close, Escape, a cancelled multi-select, disabling) resets it.
+  useEffect(() => {
+    if (commentPopover) return;
+    setPinVisible(true);
+    setComposerWasHidden(false);
+  }, [commentPopover]);
 
   const pendingTextRef = useRef<string>("");
   // Element anchor for the pending pinpoint selection — committed onto the
@@ -553,6 +617,9 @@ export function useHtmlAnnotation({
   hostCapRef.current = maxAdditionalTargets !== undefined;
 
   const anchorRef = useRef<HTMLDivElement | null>(null);
+  /** Rich-text Copy requests waiting for the bridge's markup, by id. An
+   *  answer with an id not in here (unsolicited, or after its timeout) is ignored. */
+  const richCopyRequestsRef = useRef(new Map<string, (answer: BridgeRichCopyMessage) => void>());
 
   /** Post into the iframe with the live token + targetOrigin when a live
    *  session is active; srcdoc posts keep targetOrigin "*" and no token. */
@@ -665,7 +732,22 @@ export function useHtmlAnnotation({
         return;
       }
 
+      if (type === `${PREFIX}rich-copy`) {
+        const answer = richCopyRequestsRef.current.get(message.id);
+        if (!answer) return;
+        richCopyRequestsRef.current.delete(message.id);
+        answer(message);
+        return;
+      }
+
+      if (type === `${PREFIX}pin-visibility`) {
+        setPinVisible(message.visible);
+        if (!message.visible && commentPopoverRef.current) setComposerWasHidden(true);
+      }
+
       if (type === `${PREFIX}selection`) {
+        setPinVisible(true);
+        setComposerWasHidden(false);
         pendingTextRef.current = message.text;
         pendingAnchorRef.current = message.anchor ?? null;
         pendingContextRef.current = message.context ?? null;
@@ -760,6 +842,35 @@ export function useHtmlAnnotation({
             element: anchor,
             source: null,
             selectionText: message.text,
+            // The markup is built only when Copy is pressed: ask
+            // the bridge for the pending range's HTML and wait a moment.
+            ...(message.richCopy ? {
+              getRichCopy: () => new Promise<RichCopySource>((resolve) => {
+                const id = `rc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+                const requests = richCopyRequestsRef.current;
+                // Without an answer only the quote is here: plain text, marked
+                // as cut when the bridge cut it.
+                const quote = { html: "", text: message.text, truncated: message.textCut === true };
+                requests.set(id, (answer) => {
+                  const text = answer.text || quote.text;
+                  const truncated = answer.text ? answer.truncated : quote.truncated;
+                  if (answer.tooLarge) {
+                    resolve({ tooLarge: true, text, truncated });
+                    return;
+                  }
+                  const html = answer.html ? sanitizeRichHtml(answer.html) : null;
+                  if (html && html.length > MAX_RICH_CLIPBOARD_OUTPUT_LENGTH) {
+                    resolve({ tooLarge: true, text, truncated });
+                    return;
+                  }
+                  resolve({ html: html ?? "", text, truncated });
+                });
+                window.setTimeout(() => {
+                  if (requests.delete(id)) resolve(quote);
+                }, RICH_COPY_TIMEOUT_MS);
+                post({ type: `${PREFIX}rich-copy-request`, id });
+              }),
+            } : {}),
           });
         }
       }
@@ -803,6 +914,18 @@ export function useHtmlAnnotation({
           onHostDraftRef.current(null);
         }
         setToolbarState(null);
+        // The bridge closed the draft (its Escape rung) while the composer was
+        // hidden with its target: close the hidden composer too, or nothing on
+        // screen could ever close it. Its text stays in the draft store.
+        if (commentPopoverRef.current && !pinVisibleRef.current) {
+          post({ type: `${PREFIX}cancel-selection` });
+          setCommentPopover(null);
+          setDraftTargets([]);
+          pendingTextRef.current = "";
+          pendingAnchorRef.current = null;
+          pendingContextRef.current = null;
+          return;
+        }
         // Keep the captured text alive while a comment/quick-label is open: the user
         // is composing, and the selection collapsing or scrolling out of view must
         // not drop the annotation on submit. It's overwritten on the next selection.
@@ -1157,6 +1280,8 @@ export function useHtmlAnnotation({
 
   return {
     toolbarState,
+    pinVisible: pinVisible || !commentPopover,
+    composerAutoFocus: !composerWasHidden,
     commentPopover,
     quickLabelPicker,
     handleAnnotate,