@plannotator/ui 0.52.1 → 0.53.1

package/components/html-viewer/bridge-script.asset.js

@@ -225,6 +225,8 @@
   // marker buttons keep their own clicks. BOTH surface kinds start ARMED —
   // Esc (or the header pen) drops to Interact.
   var annotateModeActive = true;
+  // A native host decides link navigations itself (HtmlViewer hostNavigates).
+  var hostNavigates = false;
   function updatePinpointCursor() {
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
@@ -530,6 +532,21 @@
       flashMultiTarget(typeof e.data.key === 'string' ? e.data.key : '');
     }
 
+    else if (type === PREFIX + 'step-pin') {
+      // A host's Parent or Child (a phone's comment sheet): move the pinned
+      // draft to the element around it, or back in. Re-pins through
+      // annotateElement, so the parent sees an ordinary pinpoint selection.
+      stepPin(e.data.direction === 'child' ? 'child' : 'parent');
+    }
+
+    else if (type === PREFIX + 'reveal-pin') {
+      // A host whose own panel covers the page's lower part (a phone's comment
+      // sheet) shrank the frame: bring the pinned draft back into view.
+      if (pendingPinEl && pendingPinEl.isConnected) {
+        try { pendingPinEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch (ex) {}
+      }
+    }
+
     else if (type === PREFIX + 'scroll-to') {
       // Selecting an annotation scrolls its first resolved target into view
       // and flashes the overlay focus highlight over EVERY rect of EVERY
@@ -573,6 +590,10 @@
       if (vimEnabled) updateVimUi();
     }
 
+    else if (type === PREFIX + 'set-host-navigates') {
+      hostNavigates = e.data.active === true;
+    }
+
     else if (type === PREFIX + 'set-annotate-mode') {
       var nextAnnotateActive = e.data.active === true;
       if (nextAnnotateActive !== annotateModeActive) {
@@ -1100,6 +1121,14 @@
   // changes); shared by mousemove and the scroll/resize reconcile pass.
   // Per-event hit-testing only — never builds the semantic graph.
   function updatePinpointHover(x, y, fallbackNode) {
+    // A link a plain click follows shows no pin outline unless Cmd/Ctrl is
+    // held: the outline always matches what a click there will do.
+    if (!pinModifierHeld && !pendingPinEl && (followableLinkAt(fallbackNode) || followableLinkAt(deepElementFromPoint(x, y)))) {
+      pinpointHover = null;
+      hidePinpointBox();
+      hidePinpointLabel();
+      return;
+    }
     var el = pinpointLeafAt(x, y, fallbackNode);
     // The 25px marker bubble owns clicks over it (they select its comment),
     // so hover must advertise the MARKER's own identity — no annotate box,
@@ -1130,9 +1159,36 @@
     positionPinpointLabel(el, pinpointHoverLabel(el));
   }
 
+  // Cmd or Ctrl held (the pin modifier): a link under the pointer shows the
+  // pin outline and the crosshair instead of the follow pointer. Read from
+  // the key itself (as the token-hover gate does) and from every pointer
+  // move, so a key pressed with focus outside this frame still counts.
+  var pinModifierHeld = false;
+  function setPinModifier(held) {
+    if (held === pinModifierHeld) return;
+    pinModifierHeld = held;
+    if (document.body) {
+      if (held) document.body.setAttribute('data-plannotator-pin-modifier', '');
+      else document.body.removeAttribute('data-plannotator-pin-modifier');
+    }
+    if (annotateModeActive && currentInputMethod === 'pinpoint' && lastPointer && !(vimEnabled && vimPhase !== 'inactive')) {
+      updatePinpointHover(lastPointer.x, lastPointer.y, lastPointerNode || pinpointHover);
+    }
+  }
+  document.addEventListener('keydown', function(e) {
+    if (e.key === 'Meta' || e.key === 'Control') setPinModifier(true);
+  }, true);
+  document.addEventListener('keyup', function(e) {
+    if (e.key === 'Meta' || e.key === 'Control') setPinModifier(e.metaKey || e.ctrlKey);
+  }, true);
+  window.addEventListener('blur', function() { setPinModifier(false); });
+
   var lastPointer = null;
+  var lastPointerNode = null;
   document.addEventListener('mousemove', function(e) {
     lastPointer = { x: e.clientX, y: e.clientY };
+    lastPointerNode = e.target && e.target.nodeType === 1 ? e.target : null;
+    if (!!(e.metaKey || e.ctrlKey) !== pinModifierHeld) setPinModifier(!!(e.metaKey || e.ctrlKey));
     updateDragYield(e);
     if (!annotateModeActive) return; // Interact mode: no hover affordances
     if (currentInputMethod !== 'pinpoint') {
@@ -3524,6 +3580,41 @@
     });
   }
 
+  // Parent and Child for a pinned draft. The trail holds the elements stepped
+  // out of, so Child goes back the way Parent came; past it, Child takes the
+  // first element child. A new pin by click starts a new trail.
+  var pinStepTrail = [];
+  var steppingPin = false;
+  function stepPin(direction) {
+    if (!pendingPinEl || !pendingPinEl.isConnected) return;
+    var from = pendingPinEl;
+    var next = null;
+    if (direction === 'parent') {
+      var up = from.parentElement;
+      if (up && up !== document.body && up !== document.documentElement) next = up;
+    } else {
+      var back = pinStepTrail[pinStepTrail.length - 1];
+      if (back && back.isConnected && from.contains(back)) next = back;
+      else {
+        for (var child = from.firstElementChild; child; child = child.nextElementSibling) {
+          if (isViewerOverlayNode(child)) continue;
+          if (/^(SCRIPT|STYLE|TEMPLATE|NOSCRIPT)$/.test(child.tagName)) continue;
+          next = child;
+          break;
+        }
+      }
+    }
+    if (!next) return;
+    var trail = pinStepTrail.slice();
+    if (direction === 'parent') trail.push(from);
+    else if (trail[trail.length - 1] === next) trail.pop();
+    else trail = [];
+    steppingPin = true;
+    try { annotateElement(next, undefined, pendingPinViaPinpoint, null); }
+    finally { steppingPin = false; }
+    pinStepTrail = trail;
+  }
+
   // Pin an element: select its text if possible (so a <mark> can wrap it), else
   // post its text + box directly so the toolbar still anchors (e.g. an SVG node,
   // whose <text> doesn't select like HTML text). Either way the element stays
@@ -3531,6 +3622,7 @@
   // rides along so the annotation can restore to this exact element later.
   function annotateElement(el, modeOverride, viaPinpoint, clickPoint) {
     if (!el) return false;
+    if (!steppingPin) pinStepTrail = [];
     pinpointHover = null;
     hidePinpointLabel();
     clearMultiTargets(); // a new primary starts a fresh draft
@@ -3606,6 +3698,230 @@
     return true;
   }
 
+  // --- Touch: a tap on a link follows it, press-and-hold pins it ---
+  // The owner's amendment to html-link-click (2026-10-20): on a phone there is
+  // no Cmd/Ctrl, so while armed a TAP on a link follows it (the click handlers
+  // below take it as a plain click) and a PRESS-AND-HOLD of HOLD_PIN_MS opens
+  // a comment on it, pinned exactly as a Cmd-click pins it. Every surface
+  // alike: srcdoc pages (annotate, plan review's HTML, the Inbox) and live apps.
+  // A finger that moves past HOLD_SLOP_PX (a scroll), a second finger, or a
+  // scroll cancels the hold. The release of a hold that pinned never follows
+  // the link and never reaches the page: its pointerup and touchend are
+  // stopped at the window (registered before a live app's own listeners),
+  // touchend is cancelled so no click is synthesized, and a click that still
+  // arrives is swallowed once. That swallow ends at the next touch, mouse
+  // press or key, so it never eats an unrelated click.
+  // While a hold is in progress, link text is not selectable (the CSS above),
+  // so the platform's long-press starts no native selection under the finger;
+  // Android's contextmenu, its long-press signal, fires the hold at once.
+  var HOLD_PIN_MS = 500;
+  var HOLD_SLOP_PX = 10;
+  var HOLD_SWALLOW_MAX_MS = 10000; // a release never seen (an app stopped touchend)
+  var linkHold = null; // { timer, x, y, id, target }
+  // After a hold pinned: { pointerId, released, until } until its release's
+  // click (if any) is swallowed or the next gesture starts.
+  var heldGesture = null;
+  var lastTouchPointerId = null;
+  function holdArmed() {
+    return annotateModeActive && currentInputMethod === 'pinpoint' && !(vimEnabled && vimPhase !== 'inactive');
+  }
+  function setLinkHoldStyle(on) {
+    if (!document.body) return;
+    if (on) document.body.setAttribute('data-plannotator-link-hold', '');
+    else document.body.removeAttribute('data-plannotator-link-hold');
+  }
+  function cancelLinkHold() {
+    if (!linkHold) return;
+    clearTimeout(linkHold.timer);
+    linkHold = null;
+    setLinkHoldStyle(false);
+  }
+  function fireLinkHold() {
+    var hold = linkHold;
+    if (!hold) return false;
+    clearTimeout(hold.timer);
+    linkHold = null;
+    if (!holdArmed() || !hold.target.isConnected) {
+      setLinkHoldStyle(false);
+      return false;
+    }
+    var el = resolvePinpointTargetAt(hold.x, hold.y, hold.target);
+    if (!el) {
+      setLinkHoldStyle(false);
+      return false;
+    }
+    heldGesture = { pointerId: lastTouchPointerId, released: false, pointerUpSeen: false, pointerEnded: false, touchEnded: false, target: hold.target, touchId: hold.id, x: hold.x, y: hold.y, until: Date.now() + HOLD_SWALLOW_MAX_MS };
+    // The same pin a Cmd-click makes: the link's own words as a text range.
+    // Selection is back on for that, then off again until the finger lifts.
+    setLinkHoldStyle(false);
+    try { window.getSelection().removeAllRanges(); } catch (ex) {}
+    annotateElement(el, undefined, true, { x: hold.x, y: hold.y });
+    setLinkHoldStyle(true);
+    return true;
+  }
+  function endHeldGesture() {
+    heldGesture = null;
+  }
+  function touchById(list, id) {
+    for (var i = 0; list && i < list.length; i++) if (list[i].identifier === id) return list[i];
+    return null;
+  }
+  // The release of a hold is stopped, so the page never sees it end: a press
+  // library (React Aria's usePress, Motion's whileTap, dnd-kit) would keep the
+  // press open. In its place the page gets a pointercancel and a touchcancel
+  // on the element the finger went down on, which end a press without
+  // activating it. The bridge's own listeners ignore those two.
+  var bridgeSynthetic = typeof WeakSet === 'function' ? new WeakSet() : null;
+  function isBridgeSynthetic(e) {
+    return !!(bridgeSynthetic && bridgeSynthetic.has(e));
+  }
+  function dispatchSynthetic(target, event) {
+    if (bridgeSynthetic) bridgeSynthetic.add(event);
+    try { target.dispatchEvent(event); } catch (ex) {}
+  }
+  function sendPointerCancel(g, pointerId) {
+    if (g.pointerEnded || pointerId === null || pointerId === undefined) return;
+    g.pointerEnded = true;
+    var target = g.target && g.target.isConnected ? g.target : document.body;
+    if (!target) return;
+    var init = { bubbles: true, cancelable: false, composed: true, pointerId: pointerId, pointerType: 'touch', isPrimary: true, clientX: g.x, clientY: g.y };
+    var event = null;
+    try { if (typeof PointerEvent === 'function') event = new PointerEvent('pointercancel', init); } catch (ex) {}
+    if (!event) {
+      event = new Event('pointercancel', { bubbles: true, cancelable: false, composed: true });
+      try {
+        Object.defineProperty(event, 'pointerId', { value: pointerId });
+        Object.defineProperty(event, 'pointerType', { value: 'touch' });
+        Object.defineProperty(event, 'isPrimary', { value: true });
+      } catch (ex) {}
+    }
+    dispatchSynthetic(target, event);
+  }
+  function sendTouchCancel(g) {
+    if (g.touchEnded) return;
+    g.touchEnded = true;
+    var target = g.target && g.target.isConnected ? g.target : document.body;
+    if (!target) return;
+    var event = null;
+    try {
+      if (typeof TouchEvent === 'function' && typeof Touch === 'function') {
+        var t = new Touch({ identifier: g.touchId, target: target, clientX: g.x, clientY: g.y });
+        event = new TouchEvent('touchcancel', { bubbles: true, cancelable: false, composed: true, touches: [], targetTouches: [], changedTouches: [t] });
+      }
+    } catch (ex) { event = null; }
+    if (!event) {
+      event = new Event('touchcancel', { bubbles: true, cancelable: false, composed: true });
+      var point = { identifier: g.touchId, target: target, clientX: g.x, clientY: g.y };
+      try {
+        Object.defineProperty(event, 'touches', { value: [] });
+        Object.defineProperty(event, 'targetTouches', { value: [] });
+        Object.defineProperty(event, 'changedTouches', { value: [point] });
+      } catch (ex) {}
+    }
+    dispatchSynthetic(target, event);
+  }
+  // Pointer events come before touch events; the touch's pointerId names the
+  // release's pointerup.
+  window.addEventListener('pointerdown', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    if (e.pointerType === 'touch') {
+      lastTouchPointerId = e.pointerId;
+      if (heldGesture && heldGesture.released) endHeldGesture();
+      return;
+    }
+    // A mouse or pen press: whatever click comes next is its own.
+    endHeldGesture();
+  }, true);
+  window.addEventListener('keydown', function() { if (heldGesture && heldGesture.released) endHeldGesture(); }, true);
+  function heldPointer(e) {
+    if (!heldGesture || e.pointerType !== 'touch') return false;
+    return heldGesture.pointerId === null || e.pointerId === heldGesture.pointerId;
+  }
+  window.addEventListener('pointerup', function(e) {
+    if (isBridgeSynthetic(e) || !heldPointer(e) || heldGesture.pointerUpSeen) return;
+    heldGesture.pointerUpSeen = true;
+    e.stopImmediatePropagation();
+    sendPointerCancel(heldGesture, e.pointerId);
+  }, true);
+  // The browser ended the held pointer itself (it took the touch): nothing to stand in for.
+  window.addEventListener('pointercancel', function(e) {
+    if (isBridgeSynthetic(e) || !heldPointer(e)) return;
+    heldGesture.pointerUpSeen = true;
+    heldGesture.pointerEnded = true;
+  }, true);
+  window.addEventListener('touchend', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    if (heldGesture && !heldGesture.released) {
+      // The release of the hold that pinned: no click, no navigation, and
+      // the page's own touchend never runs on it; it gets cancels instead.
+      if (e.cancelable) e.preventDefault();
+      e.stopImmediatePropagation();
+      var g = heldGesture;
+      g.released = true;
+      g.until = Date.now() + 800;
+      setLinkHoldStyle(false);
+      // Engines that send touchend before pointerup: the pointer ends here
+      // (its own pointerup, when it comes, is still stopped).
+      sendPointerCancel(g, g.pointerId);
+      sendTouchCancel(g);
+      return;
+    }
+    cancelLinkHold(); // a tap: the click that follows it follows the link
+  }, { capture: true, passive: false });
+  window.addEventListener('touchcancel', function(e) {
+    if (isBridgeSynthetic(e)) return;
+    cancelLinkHold();
+    setLinkHoldStyle(false);
+    if (heldGesture) {
+      heldGesture.released = true;
+      heldGesture.touchEnded = true;
+      heldGesture.until = Date.now() + 800;
+    }
+  }, true);
+  document.addEventListener('touchstart', function(e) {
+    if (document.body && !document.body.hasAttribute('data-plannotator-touch')) {
+      document.body.setAttribute('data-plannotator-touch', '');
+    }
+    cancelLinkHold();
+    // A new touch: whatever click comes next is its own, even if the last
+    // hold's release was never seen.
+    endHeldGesture();
+    setLinkHoldStyle(false);
+    if (!holdArmed() || !e.touches || e.touches.length !== 1) return;
+    if (isViewerOverlayNode(e.target) || !followableLinkAt(e.target)) return;
+    var t = e.touches[0];
+    linkHold = { x: t.clientX, y: t.clientY, id: t.identifier, target: e.target, timer: 0 };
+    linkHold.timer = setTimeout(fireLinkHold, HOLD_PIN_MS);
+    setLinkHoldStyle(true);
+  }, { capture: true, passive: true });
+  document.addEventListener('touchmove', function(e) {
+    if (!linkHold) return;
+    var t = touchById(e.touches, linkHold.id);
+    if (!t || e.touches.length !== 1 || Math.abs(t.clientX - linkHold.x) > HOLD_SLOP_PX || Math.abs(t.clientY - linkHold.y) > HOLD_SLOP_PX) {
+      cancelLinkHold();
+    }
+  }, { capture: true, passive: true });
+  window.addEventListener('scroll', cancelLinkHold, true);
+  document.addEventListener('contextmenu', function(e) {
+    if (linkHold) {
+      e.preventDefault();
+      fireLinkHold();
+      return;
+    }
+    if (heldGesture && Date.now() < heldGesture.until) e.preventDefault();
+  }, true);
+  // On the window, before every other click handler of the bridge and a live
+  // app's own, so the release of a hold reaches neither the link handler nor
+  // the pinpoint one, nor the page (a live app would navigate).
+  window.addEventListener('click', function(e) {
+    if (!heldGesture) return;
+    var swallow = Date.now() < heldGesture.until;
+    endHeldGesture();
+    if (!swallow) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+  }, true);
+
   // --- Local-site link navigation (srcdoc sessions only) ---
   // A srcdoc document has no URL of its own: its base URL is the PARENT page's,
   // which is the Plannotator server. So a plain link to 02-detail.html resolves
@@ -3617,8 +3933,14 @@
   // The frame therefore never navigates itself. In-page fragments scroll here;
   // everything else is handed to the parent, which owns resolution against the
   // current document's directory and is the trust boundary for the href.
-  // Registered BEFORE the pinpoint handler and never stopping propagation, so
-  // an armed click still pins the link element exactly as it always did.
+  // Registered BEFORE the pinpoint handler and never stopping propagation.
+  //
+  // One rule while armed (the owner's ruling, html-link-click, 2026-10-20):
+  // a plain click on a link FOLLOWS it, exactly as in Interact; a click with
+  // the platform modifier (Cmd on macOS, Ctrl elsewhere: either is taken)
+  // PINS it for a comment through the pinpoint handler below, as does a
+  // shift-click that adds it to an open multi-select draft. A drag that ended
+  // on the link owns its click: it neither follows nor pins.
   //
   // Live app sessions are excluded outright: they navigate a real origin
   // through the proxy, which is the whole point of that surface.
@@ -3641,6 +3963,25 @@
     return true;
   }
 
+  // While armed, whether a click on a link pins it instead of following it:
+  // the platform modifier (Cmd or Ctrl), a shift-click adding to an open
+  // multi-select draft, or the trailing click of a drag that selected text.
+  function armedClickPins(e) {
+    if (e.metaKey || e.ctrlKey || dragEndedClick) return true;
+    return !!(e.shiftKey && pendingPinEl && multiSelectArmed && pendingSelection);
+  }
+
+  // A link with a real destination: one a plain click follows while armed.
+  // No href, "", "#" and javascript: go nowhere, so a click on them pins
+  // the element as on any other (agents' mocks use <a href="#"> for buttons).
+  function isFollowableHref(raw) {
+    return !!raw && raw !== '#' && !/^javascript:/i.test(raw);
+  }
+
+  function followableLinkAt(node) {
+    return !!node && isFollowableHref(navigableLinkHref(node));
+  }
+
   function navigableLinkHref(node) {
     var el = node && node.nodeType === 1 ? node : node && node.parentElement;
     if (!el || !el.closest) return '';
@@ -3660,16 +4001,30 @@
       if (!raw) return;
       // The page's own scripting, not a navigation: leave it alone.
       if (/^javascript:/i.test(raw)) return;
+      // Armed and pinning (a link that goes nowhere, the modifier, or a
+      // drag's trailing click): the frame never navigates, and the pinpoint
+      // handler below takes the click.
+      if (annotateModeActive && currentInputMethod === 'pinpoint' && (!isFollowableHref(raw) || armedClickPins(e))) {
+        e.preventDefault();
+        return;
+      }
       if (raw.charAt(0) === '#') {
         e.preventDefault();
         scrollToLocalFragment(raw.slice(1));
         return;
       }
       e.preventDefault();
-      // Armed pinpoint: the click belongs to annotation, and the capture-phase
-      // pinpoint handler below is about to pin this element. Navigation is
-      // already suppressed above, which is all this surface owes the click.
-      if (annotateModeActive && currentInputMethod === 'pinpoint') return;
+      // Only a person's click follows a link: a page's own script calling
+      // a.click() never navigates the viewer or pushes the host's history.
+      if (!e.isTrusted) return;
+      // A native host decides links itself: a person's tap opens the link as a
+      // new window, which the host's web view hands to its own delegate (the
+      // frame never navigates; the host page's CSP would refuse it anyway).
+      if (hostNavigates) {
+        var target = (e.target && e.target.closest) ? e.target.closest('a,area') : null;
+        try { window.open(target && target.href ? target.href : raw, '_blank', 'noopener'); } catch (ex) {}
+        return;
+      }
       postToParent({ type: PREFIX + 'link-click', href: raw.slice(0, 2048) });
     }, true);
   }
@@ -3688,7 +4043,12 @@
     // and mousedown clears a prior pin's leftover selection, so stale
     // selection state never blocks the next plain re-pin click. One-shot:
     // only the drag's own trailing click is suppressed.
-    if (dragEndedClick) { dragEndedClick = false; return; }
+    if (dragEndedClick) {
+      dragEndedClick = false;
+      // Never a navigation either (a live app's link would otherwise follow).
+      if (navigableLinkHref(e.target)) e.preventDefault();
+      return;
+    }
     // Shift-click while an ARMED pinpoint draft is open: toggle the element
     // in/out of the SAME draft comment instead of replacing the selection.
     // Unarmed drafts (modes the parent does not mirror, e.g. quickLabel)
@@ -3702,6 +4062,9 @@
       if (multiEl) toggleMultiTarget(multiEl, { x: e.clientX, y: e.clientY });
       return;
     }
+    // A plain click on a link follows it (the link handler above posted it;
+    // in a live app the browser navigates for real). The modifier pins it.
+    if (isFollowableHref(navigableLinkHref(e.target)) && !armedClickPins(e)) return;
     // Click what the hover box shows: the currently hovered element is the
     // target the user aimed at. Fall back to a fresh hit-test at the click
     // point (e.g. a click with no preceding mousemove).
@@ -3729,12 +4092,36 @@
     window.getSelection().removeAllRanges();
     renderAnnotationOverlay();
   }
+  // An Escape in Interact that the page did not use (no handler cancelled it
+  // or stopped it on its way up, focus not in one of its text fields) is
+  // offered to the host as page-escape, after every handler had its turn: the
+  // Inbox leaves full screen with it. The page still got the key first.
+  var escapeReachedWindow = null;
+  window.addEventListener('keydown', function(e) {
+    if (e.key === 'Escape') escapeReachedWindow = e;
+  });
+  function offerUnusedEscape(e) {
+    if (e.repeat || e.isComposing || e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return;
+    var t = e.target;
+    if (t && t.nodeType === 1) {
+      var tag = t.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable) return;
+      if (t.closest && t.closest('[contenteditable]:not([contenteditable="false"])')) return;
+    }
+    // The page's own dialog closes on this Escape (the browser's default, not a handler).
+    if (document.querySelector('dialog[open]')) return;
+    setTimeout(function() {
+      if (escapeReachedWindow !== e || e.defaultPrevented) return;
+      postToParent({ type: PREFIX + 'page-escape' });
+    }, 0);
+  }
   document.addEventListener('keydown', function(e) {
     if (e.key !== 'Escape' || vimEnabled) return;
     if (!annotateModeActive) {
       // Interact mode: Esc belongs to the page — except an open drag-comment
       // draft (drag-selection stays live in Interact) still closes first.
       if (pendingSelection) closePendingDraft();
+      else offerUnusedEscape(e);
       return;
     }
     if (pendingSelection) {
@@ -3766,6 +4153,25 @@
     postToParent({ type: PREFIX + message });
   }, true);
 
+  // A plain ] or [ while armed (Annotate): the host may step to its next or
+  // previous file (the Inbox steps through a thread's attachments). Never in
+  // Interact (the page owns its keys), never while the page's focus is in a
+  // text field, with a modifier, on auto-repeat or mid-composition. The page
+  // still receives the key; a host without a step handler ignores the
+  // message. Capture phase, like the chords above.
+  document.addEventListener('keydown', function(e) {
+    if (e.key !== ']' && e.key !== '[') return;
+    if (!annotateModeActive || vimEnabled) return;
+    if (e.metaKey || e.ctrlKey || e.altKey || e.repeat || e.isComposing) return;
+    var t = e.target;
+    if (t && t.nodeType === 1) {
+      var tag = t.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || t.isContentEditable) return;
+      if (t.closest && t.closest('[contenteditable]:not([contenteditable="false"])')) return;
+    }
+    postToParent({ type: PREFIX + 'step', dir: e.key === ']' ? 1 : -1 });
+  }, true);
+
   // Author opt-in: a plain click on any element tagged [data-annotate] pops the
   // toolbar — no pinpoint mode. Lets an HTML doc (e.g. a flow graph) wire its own
   // nodes to Plannotator's toolbar. Bubble phase so the page's own click handlers

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

@@ -3,7 +3,7 @@
 // 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/* Armed pinpoint over an EMBEDDED local document: the embed is one element\n * from the outer page's point of view, and the bridge is never injected into a\n * nested frame, so a click inside it would simply vanish into another document.\n * Making frames transparent to the pointer while armed is what lets that click\n * pin the <iframe>/<embed>/<object> itself. Interact (Esc, the header pen or\n * Mod+Shift+A) restores native interaction inside the embed — which is also\n * the only state a link inside it can be followed from.\n * Live-app sessions never set this attribute: they annotate a real app whose\n * own nested frames belong to it. */\nbody[data-plannotator-frame-inert] :is(iframe, frame, embed, object) {\n  pointer-events: none !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 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/* A plain click on a link with a real destination follows it while armed\n * (Cmd/Ctrl-click pins it), so such a link keeps the pointer that says so,\n * until the modifier is held. A link that goes nowhere (no href, \"\", \"#\",\n * javascript:) is not followed and keeps the crosshair. SVG links may carry\n * only xlink:href, hence the any-namespace attribute. */\nbody[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) :is(a, area)[href]:not([href=\"\"]):not([href=\"#\"]):not([href^=\"javascript:\" i]),\nbody[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) :is(a, area)[href]:not([href=\"\"]):not([href=\"#\"]):not([href^=\"javascript:\" i]) *,\nbody[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) svg a:not([href])[*|href]:not([*|href=\"\"]):not([*|href=\"#\"]):not([*|href^=\"javascript:\" i]),\nbody[data-plannotator-pinpoint-cursor]:not([data-plannotator-pin-modifier]) svg a:not([href])[*|href]:not([*|href=\"\"]):not([*|href=\"#\"]):not([*|href^=\"javascript:\" i]) * {\n  cursor: pointer !important;\n}\n/* Touch, armed: a tap on a link follows it and a press-and-hold pins it for\n * a comment. iOS's link callout would take that hold, so it is off on links\n * while armed, once a touch is seen (data-plannotator-touch) or on screens\n * without hover. The callout is all: link text stays selectable, so a drag\n * across a link (a trackpad, a touchscreen laptop) still quotes its words.\n * Only while a hold on a link is in progress (data-plannotator-link-hold,\n * from its touchstart to its release) is selection off too, so the platform's\n * long-press does not start a native text selection under the finger. */\nbody[data-plannotator-pinpoint-cursor][data-plannotator-touch] :is(a, area),\nbody[data-plannotator-pinpoint-cursor][data-plannotator-touch] :is(a, area) *,\nbody[data-plannotator-pinpoint-cursor][data-plannotator-touch] svg a,\nbody[data-plannotator-pinpoint-cursor][data-plannotator-touch] svg a * {\n  -webkit-touch-callout: none !important;\n}\n@media (hover: none) {\n  body[data-plannotator-pinpoint-cursor] :is(a, area),\n  body[data-plannotator-pinpoint-cursor] :is(a, area) *,\n  body[data-plannotator-pinpoint-cursor] svg a,\n  body[data-plannotator-pinpoint-cursor] svg a * {\n    -webkit-touch-callout: none !important;\n  }\n}\nbody[data-plannotator-link-hold] :is(a, area),\nbody[data-plannotator-link-hold] :is(a, area) *,\nbody[data-plannotator-link-hold] svg a,\nbody[data-plannotator-link-hold] svg a * {\n  -webkit-touch-callout: none !important;\n  -webkit-user-select: none !important;\n  user-select: none !important;\n}\n/* Armed pinpoint over an EMBEDDED local document: the embed is one element\n * from the outer page's point of view, and the bridge is never injected into a\n * nested frame, so a click inside it would simply vanish into another document.\n * Making frames transparent to the pointer while armed is what lets that click\n * pin the <iframe>/<embed>/<object> itself. Interact (Esc, the header pen or\n * Mod+Shift+A) restores native interaction inside the embed — which is also\n * the only state a link inside it can be followed from.\n * Live-app sessions never set this attribute: they annotate a real app whose\n * own nested frames belong to it. */\nbody[data-plannotator-frame-inert] :is(iframe, frame, embed, object) {\n  pointer-events: none !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})();";