@plannotator/ui 0.39.0 → 0.41.0

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

@@ -60,6 +60,18 @@ body[data-plannotator-pinpoint-cursor],
 body[data-plannotator-pinpoint-cursor] * {
   cursor: crosshair !important;
 }
+/* Armed pinpoint over an EMBEDDED local document: the embed is one element
+ * from the outer page's point of view, and the bridge is never injected into a
+ * nested frame, so a click inside it would simply vanish into another document.
+ * Making frames transparent to the pointer while armed is what lets that click
+ * pin the <iframe>/<embed>/<object> itself. Interact (Esc, the header pen or
+ * Mod+Shift+A) restores native interaction inside the embed — which is also
+ * the only state a link inside it can be followed from.
+ * Live-app sessions never set this attribute: they annotate a real app whose
+ * own nested frames belong to it. */
+body[data-plannotator-frame-inert] :is(iframe, frame, embed, object) {
+  pointer-events: none !important;
+}
 @media (prefers-reduced-motion: reduce) {
   [data-plannotator-pinpoint-box].pn-pin-enter {
     animation: none;
@@ -381,8 +393,10 @@ export const BRIDGE_SCRIPT = `(function() {
     if (!document.body) return;
     if (annotateModeActive && currentInputMethod === 'pinpoint') {
       document.body.setAttribute('data-plannotator-pinpoint-cursor', '');
+      if (!LIVE) document.body.setAttribute('data-plannotator-frame-inert', '');
     } else {
       document.body.removeAttribute('data-plannotator-pinpoint-cursor');
+      document.body.removeAttribute('data-plannotator-frame-inert');
     }
   }
   var pinpointHover = null;
@@ -690,6 +704,13 @@ export const BRIDGE_SCRIPT = `(function() {
       scrollToAnnotation(e.data.id, e.data.behavior === 'auto' ? 'auto' : 'smooth');
     }
 
+    else if (type === PREFIX + 'scroll-to-fragment') {
+      // A linked document opened from an in-page link carried a #fragment.
+      // The srcdoc document has no URL of its own, so the parent cannot set
+      // one: it replays the fragment here once the new document is ready.
+      scrollToLocalFragment(typeof e.data.fragment === 'string' ? e.data.fragment : '');
+    }
+
     else if (type === PREFIX + 'focus-mark') {
       focusAnnotationRecord(typeof e.data.id === 'string' ? e.data.id : null, false);
     }
@@ -905,11 +926,34 @@ export const BRIDGE_SCRIPT = `(function() {
       var svgGroup = node.closest('g');
       if (svgGroup) node = svgGroup;
     }
+    node = preferInertFrameAt(node, x, y);
     node = promoteTinyTarget(node);
     if (node === document.body || node === document.documentElement) return null;
     return node;
   }
 
+  // While frames are pointer-transparent (armed pinpoint, srcdoc sessions),
+  // hit-testing passes THROUGH an embedded document to the container painted
+  // behind it — so a click on an embed would pin its wrapper div. The embed is
+  // what the reviewer is pointing at and what the anchor must name, so a point
+  // inside a frame's own rect resolves to that frame. Bounded to the frames
+  // inside the element already resolved, so it costs nothing on ordinary pages.
+  var FRAME_SELECTOR = 'iframe,frame,embed,object';
+  function framesArePointerInert() {
+    return !LIVE && annotateModeActive && currentInputMethod === 'pinpoint';
+  }
+  function preferInertFrameAt(node, x, y) {
+    if (!framesArePointerInert() || !node.querySelectorAll) return node;
+    if (node.matches && node.matches(FRAME_SELECTOR)) return node;
+    var frames = node.querySelectorAll(FRAME_SELECTOR);
+    for (var i = 0; i < frames.length && i < 64; i++) {
+      var r = frames[i].getBoundingClientRect();
+      if (r.width <= 0 || r.height <= 0) continue;
+      if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return frames[i];
+    }
+    return node;
+  }
+
   // Last-position reuse: a pointer that moved under 2px within 16ms resolves
   // to the cached element instead of re-hit-testing. The scroll reconcile
   // invalidates this cache — same point, different element after a scroll.
@@ -2741,8 +2785,9 @@ export const BRIDGE_SCRIPT = `(function() {
   // Constraints (the "smart" part is that they adapt to the element):
   // - attributes are an ALLOWLIST (a page cannot add a key); no form values,
   //   no on* handlers, no style, no script/style/template contents ever;
-  // - absolute http(s) URLs lose their query and fragment (tokens live
-  //   there), data: URIs keep only their media-type prefix;
+  // - href/src URLs lose their query and fragment (tokens live there),
+  //   relative ones included, and data: URIs keep only their media-type
+  //   prefix;
   // - the outline tries two levels of children, falls back to one, then to a
   //   per-tag count, whichever first fits CTX_MAX_OUTLINE, so a click on a
   //   whole <main> costs the same bytes as a click on a chip;
@@ -2792,7 +2837,10 @@ export const BRIDGE_SCRIPT = `(function() {
   }
 
   // URL attribute values: keep what locates the element in source, drop
-  // what identifies the user. Relative URLs are route state and stay whole.
+  // what identifies the user. The path survives in every form; the query and
+  // the fragment never do — a relative URL carries the same per-visit state an
+  // absolute one does (session ids, and the implicit-flow tokens that live in
+  // the fragment specifically), so it is scrubbed the same way.
   function ctxScrubUrl(value) {
     var v = String(value).trim();
     if (/^javascript:/i.test(v)) return null;
@@ -2806,6 +2854,8 @@ export const BRIDGE_SCRIPT = `(function() {
         return u.origin + u.pathname + (u.search || u.hash ? '?…' : '');
       } catch (ex) { return ctxTruncate(v, CTX_MAX_ATTR_VALUE); }
     }
+    var mark = v.search(/[?#]/);
+    if (mark >= 0) return v.slice(0, mark) + '?…';
     return v;
   }
 
@@ -3504,6 +3554,74 @@ export const BRIDGE_SCRIPT = `(function() {
     return 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
+  // to http://localhost:<port>/02-detail.html, the server's catch-all answers
+  // with the app itself, and the whole editor renders inside the annotated
+  // frame. An in-page #section link is a cross-document navigation for the
+  // same reason.
+  //
+  // 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.
+  //
+  // Live app sessions are excluded outright: they navigate a real origin
+  // through the proxy, which is the whole point of that surface.
+  function scrollToLocalFragment(rawId) {
+    var id = typeof rawId === 'string' ? rawId : '';
+    try { id = decodeURIComponent(id); } catch (ex) {}
+    if (!id) {
+      try { window.scrollTo({ top: 0, behavior: 'smooth' }); } catch (ex) { window.scrollTo(0, 0); }
+      return true;
+    }
+    var target = null;
+    try { target = document.getElementById(id); } catch (ex) {}
+    if (!target) {
+      var named = document.getElementsByName(id);
+      if (named && named.length) target = named[0];
+    }
+    if (!target) return false;
+    try { target.scrollIntoView({ behavior: 'smooth', block: 'start' }); }
+    catch (ex) { target.scrollIntoView(); }
+    return true;
+  }
+
+  function navigableLinkHref(node) {
+    var el = node && node.nodeType === 1 ? node : node && node.parentElement;
+    if (!el || !el.closest) return '';
+    var link = el.closest('a,area');
+    if (!link) return '';
+    var raw = link.getAttribute('href');
+    // SVG anchors may only carry xlink:href.
+    if (typeof raw !== 'string') raw = link.getAttribute('xlink:href');
+    return typeof raw === 'string' ? raw.trim() : '';
+  }
+
+  if (!LIVE) {
+    document.addEventListener('click', function(e) {
+      if (e.defaultPrevented || e.button !== 0) return;
+      if (isViewerOverlayNode(e.target)) return; // markers own their clicks
+      var raw = navigableLinkHref(e.target);
+      if (!raw) return;
+      // The page's own scripting, not a navigation: leave it alone.
+      if (/^javascript:/i.test(raw)) 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;
+      postToParent({ type: PREFIX + 'link-click', href: raw.slice(0, 2048) });
+    }, true);
+  }
+
   document.addEventListener('click', function(e) {
     if (!annotateModeActive || currentInputMethod !== 'pinpoint') return;
     // Real placed markers (and any other viewer overlay) own their clicks —
@@ -3579,15 +3697,21 @@ export const BRIDGE_SCRIPT = `(function() {
     }
   });
 
-  // Mod+Shift+A toggles Interact/Annotate from inside the iframe (the parent
-  // registers the same chord, but focus usually lives in here on live apps).
-  // Capture phase so the page cannot swallow the reserved chord; the parent
-  // answers with set-annotate-mode.
+  // The two reserved header chords, mirrored from inside the iframe (the
+  // parent registers both, but focus usually lives in here on live apps):
+  // Mod+Shift+A toggles Interact/Annotate, Mod+Shift+X shows/hides the
+  // floating tools over the page. Capture phase so the page cannot swallow
+  // them; the parent owns both states and answers annotate with
+  // set-annotate-mode. Disarming tears down any pending draft through that
+  // same set-annotate-mode(false) handler, exactly as Esc does.
   document.addEventListener('keydown', function(e) {
     if (!(e.metaKey || e.ctrlKey) || !e.shiftKey || e.altKey) return;
-    if (e.key !== 'a' && e.key !== 'A') return;
+    var message = null;
+    if (e.key === 'a' || e.key === 'A') message = 'annotate-toggle';
+    else if (e.key === 'x' || e.key === 'X') message = 'tools-toggle';
+    if (!message) return;
     e.preventDefault();
-    postToParent({ type: PREFIX + 'annotate-toggle' });
+    postToParent({ type: PREFIX + message });
   }, true);
 
   // Author opt-in: a plain click on any element tagged [data-annotate] pops the

package/components/html-viewer/useHtmlAnnotation.ts

@@ -9,6 +9,11 @@ import type {
   UseAnnotationHighlighterReturn,
 } from "../../hooks/useAnnotationHighlighter";
 import { BRIDGE_PROTOCOL_VERSION } from "./bridge-script";
+import {
+  parseHtmlElementContext,
+  MAX_ELEMENT_CONTEXT_BYTES,
+  MAX_PAGE_URL_LENGTH,
+} from "@plannotator/core/html-anchor";
 
 const PREFIX = "plannotator-bridge-";
 
@@ -123,7 +128,8 @@ type BridgeMessage =
   | { type: `${typeof PREFIX}mark-click`; id: string }
   | { type: `${typeof PREFIX}unanchored`; ids: string[] }
   | { type: `${typeof PREFIX}resize`; height: number }
-  | { type: `${typeof PREFIX}page-change`; pageUrl: string };
+  | { type: `${typeof PREFIX}page-change`; pageUrl: string }
+  | { type: `${typeof PREFIX}link-click`; href: string };
 
 /** Live proxied-app session credentials: the proxy origin messages must come
  * from, and the per-session token every message must echo. */
@@ -132,8 +138,10 @@ export interface HtmlLiveSession {
   token: string;
 }
 
-/** Cap for live-mode page identity strings (mirrors the bridge's slice). */
-export const MAX_PAGE_URL_LENGTH = 2048;
+/** Cap for a link href relayed out of the framed document. */
+const MAX_LINK_HREF_LENGTH = 2048;
+/** Control characters never appear in a real href; they are how structure gets smuggled. */
+const LINK_CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
 
 /** True when a live-session message event fails the origin or token check.
  * Exported for protocol tests. */
@@ -182,6 +190,12 @@ export interface UseHtmlAnnotationOptions {
    *  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;
+  /** A link the framed document swallowed rather than navigating to. The raw
+   *  href, already bounded and screened; the host resolves it (see
+   *  `resolveHtmlLinkIntent`). Delivered in readOnly mode too — navigating is
+   *  a read action — and never fired in live sessions, which navigate the
+   *  proxied app for real. */
+  onLinkClick?: (href: string) => void;
   /** scrollIntoView behavior for scroll-to (selecting an annotation).
    *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
   scrollBehavior?: 'smooth' | 'auto';
@@ -314,154 +328,14 @@ function parseTargetLabel(value: unknown): string | undefined {
     : collapsed;
 }
 
-// Element-context caps. The bridge builds the context under the same numbers,
-// but this side is the authoritative one: every scalar is re-collapsed (a
-// hostile page can embed newlines that would become markdown structure in the
-// exported feedback), every list re-capped, unknown keys dropped, and the
-// serialized whole bounded. A malformed context is DROPPED, never fatal to
-// the annotation it rides on (the same additive rule as the anchor point).
-export const MAX_ELEMENT_CONTEXT_BYTES = 2048;
-const MAX_CONTEXT_TAG_LENGTH = 32;
-const MAX_CONTEXT_ID_LENGTH = 100;
-const MAX_CONTEXT_CLASSES = 9; // 8 + the "+N more" marker
-const MAX_CONTEXT_CLASS_LENGTH = 48;
-const MAX_CONTEXT_PATH_LENGTH = 512;
-const MAX_CONTEXT_ROLE_LENGTH = 32;
-const MAX_CONTEXT_NAME_LENGTH = 120;
-const MAX_CONTEXT_ATTRS = 10;
-const MAX_CONTEXT_ATTR_NAME_LENGTH = 40;
-const MAX_CONTEXT_ATTR_VALUE_LENGTH = 120;
-const MAX_CONTEXT_TEXT_LENGTH = 300;
-const MAX_CONTEXT_OUTLINE_LENGTH = 600;
-const MAX_CONTEXT_OUTLINE_LINES = 40;
-const MAX_CONTEXT_LANDMARK_LENGTH = 80;
-const MAX_CONTEXT_HEADING_LENGTH = 130;
-const MAX_CONTEXT_COMPONENT_LENGTH = 100;
-const MAX_CONTEXT_PAGE_TITLE_LENGTH = 200;
-/** Attribute names the context may carry (mirrors CONTEXT_ATTRS in the bridge). */
-const CONTEXT_ATTR_ALLOWLIST = new Set([
-  "href", "src", "alt", "title", "type", "name", "role", "placeholder", "for", "target", "rel",
-  "aria-label", "aria-labelledby", "aria-describedby", "aria-current", "aria-expanded", "aria-hidden", "aria-controls",
-  "data-annotate", "data-testid", "data-test", "data-test-id", "data-cy", "data-qa", "data-component", "data-id",
-]);
-
-function capAt(text: string, max: number): string {
-  let cut = max;
-  const last = text.charCodeAt(cut - 1);
-  if (last >= 0xd800 && last <= 0xdbff) cut -= 1;
-  return text.slice(0, cut);
-}
-
-/** Collapse control characters and whitespace runs, then cap. */
-function collapseContextScalar(value: unknown, max: number): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const collapsed = value.replace(/[\x00-\x1f\x7f]+/g, " ").replace(/\s+/g, " ").trim();
-  if (!collapsed) return undefined;
-  return collapsed.length > max ? capAt(collapsed, max) : collapsed;
-}
-
-/** The outline keeps its line breaks (it is fenced on export) but nothing
- *  else: control characters go, each line is whitespace-collapsed, and a
- *  backtick run that could close the export's fence is defused. */
-function collapseContextOutline(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const lines = value
-    .replace(/[\x00-\x09\x0b-\x1f\x7f]+/g, " ")
-    .replace(/`{3,}/g, "'''")
-    .split("\n")
-    .map((line) => {
-      // Keep the skeleton's indentation (capped), collapse everything else.
-      const indent = (/^ */.exec(line)?.[0] ?? "").slice(0, 12);
-      return indent + line.slice(indent.length).replace(/\s+/g, " ").trim();
-    })
-    .filter((line) => line.trim().length > 0)
-    .slice(0, MAX_CONTEXT_OUTLINE_LINES);
-  const joined = lines.join("\n").trim();
-  if (!joined) return undefined;
-  return joined.length > MAX_CONTEXT_OUTLINE_LENGTH ? capAt(joined, MAX_CONTEXT_OUTLINE_LENGTH) : joined;
-}
-
-function contextBytes(value: unknown): number {
-  return new TextEncoder().encode(JSON.stringify(value)).length;
-}
-
-/** Validate a bridge-posted element context. Exported for protocol tests. */
-export function parseHtmlElementContext(value: unknown): HtmlElementContext | undefined {
-  if (!isRecord(value)) return undefined;
-  const tag = collapseContextScalar(value.tag, MAX_CONTEXT_TAG_LENGTH);
-  if (!tag) return undefined;
-  const context: HtmlElementContext = { tag: tag.toLowerCase() };
-  const id = collapseContextScalar(value.id, MAX_CONTEXT_ID_LENGTH);
-  if (id) context.id = id;
-  if (Array.isArray(value.classes)) {
-    const classes: string[] = [];
-    for (const entry of value.classes) {
-      if (classes.length >= MAX_CONTEXT_CLASSES) break;
-      const cls = collapseContextScalar(entry, MAX_CONTEXT_CLASS_LENGTH);
-      if (cls) classes.push(cls);
-    }
-    if (classes.length) context.classes = classes;
-  }
-  const path = collapseContextScalar(value.path, MAX_CONTEXT_PATH_LENGTH);
-  if (path) context.path = path;
-  const role = collapseContextScalar(value.role, MAX_CONTEXT_ROLE_LENGTH);
-  if (role) context.role = role;
-  const name = collapseContextScalar(value.name, MAX_CONTEXT_NAME_LENGTH);
-  if (name) context.name = name;
-  if (Array.isArray(value.attrs)) {
-    const attrs: Array<[string, string]> = [];
-    for (const entry of value.attrs) {
-      if (attrs.length >= MAX_CONTEXT_ATTRS) break;
-      if (!Array.isArray(entry) || entry.length !== 2) continue;
-      const attrName = collapseContextScalar(entry[0], MAX_CONTEXT_ATTR_NAME_LENGTH);
-      if (!attrName || !CONTEXT_ATTR_ALLOWLIST.has(attrName.toLowerCase())) continue;
-      if (typeof entry[1] !== "string") continue;
-      attrs.push([attrName.toLowerCase(), collapseContextScalar(entry[1], MAX_CONTEXT_ATTR_VALUE_LENGTH) ?? ""]);
-    }
-    if (attrs.length) context.attrs = attrs;
-  }
-  const text = collapseContextScalar(value.text, MAX_CONTEXT_TEXT_LENGTH);
-  if (text) context.text = text;
-  const outline = collapseContextOutline(value.outline);
-  if (outline) context.outline = outline;
-  if (typeof value.children === "number" && Number.isFinite(value.children) && value.children >= 0) {
-    context.children = Math.min(100000, Math.floor(value.children));
-  }
-  if (isRecord(value.rect)) {
-    const rect = value.rect;
-    const nums = ["x", "y", "w", "h", "vw", "vh"].map((key) => {
-      const n = rect[key];
-      return typeof n === "number" && Number.isFinite(n) ? Math.round(Math.max(-1e6, Math.min(1e6, n))) : null;
-    });
-    if (nums.every((n) => n !== null)) {
-      const [x, y, w, h, vw, vh] = nums as number[];
-      context.rect = { x: x!, y: y!, w: w!, h: h!, vw: vw!, vh: vh! };
-    }
-  }
-  const landmark = collapseContextScalar(value.landmark, MAX_CONTEXT_LANDMARK_LENGTH);
-  if (landmark) context.landmark = landmark;
-  const heading = collapseContextScalar(value.heading, MAX_CONTEXT_HEADING_LENGTH);
-  if (heading) context.heading = heading;
-  const component = collapseContextScalar(value.component, MAX_CONTEXT_COMPONENT_LENGTH);
-  if (component) context.component = component;
-  if (isRecord(value.page)) {
-    const url = collapseContextScalar(value.page.url, MAX_PAGE_URL_LENGTH);
-    if (url) {
-      context.page = { url };
-      const title = collapseContextScalar(value.page.title, MAX_CONTEXT_PAGE_TITLE_LENGTH);
-      if (title) context.page.title = title;
-    }
-  }
-  // Serialized bound, re-enforced here: shed the expendable fields in the
-  // bridge's order until the whole fits (validated per-field caps make this
-  // unreachable for an honest bridge; a forged message cannot exceed it).
-  const shedOrder: Array<keyof HtmlElementContext> = ["outline", "text", "attrs", "classes", "path", "heading", "landmark", "component"];
-  for (const field of shedOrder) {
-    if (contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES) break;
-    delete context[field];
-  }
-  return contextBytes(context) <= MAX_ELEMENT_CONTEXT_BYTES ? context : undefined;
-}
+// Re-exported so `components/html-viewer` stays the one import site a host
+// needs for the parent trust boundary; the definitions live in
+// `@plannotator/core/html-anchor`, never mirrored here.
+export {
+  parseHtmlElementContext,
+  MAX_ELEMENT_CONTEXT_BYTES,
+  MAX_PAGE_URL_LENGTH,
+};
 
 function parseBridgeRect(value: unknown): BridgeRect | null {
   if (!isRecord(value)) return null;
@@ -548,6 +422,16 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
       return typeof value.height === "number" && Number.isFinite(value.height)
         ? { type: value.type, height: value.height }
         : null;
+    case `${PREFIX}link-click`: {
+      // The raw href of a link the framed document just swallowed. It is
+      // page-controlled text, so it is bounded and screened here — the trust
+      // boundary — before the host resolves it into a path or a URL.
+      if (typeof value.href !== "string") return null;
+      const href = value.href.trim();
+      if (!href || href.length > MAX_LINK_HREF_LENGTH) return null;
+      if (LINK_CONTROL_CHARS.test(href)) return null;
+      return { type: value.type, href };
+    }
     case `${PREFIX}page-change`:
       // Live-mode SPA navigation report. Bounded like every bridge string.
       return typeof value.pageUrl === "string"
@@ -576,6 +460,7 @@ export function useHtmlAnnotation({
   onResize,
   live,
   onPageChange,
+  onLinkClick,
   onBridgePointer,
   onUnanchoredChange,
   maxAdditionalTargets,
@@ -649,6 +534,8 @@ export function useHtmlAnnotation({
   liveRef.current = live ?? null;
   const onPageChangeRef = useRef(onPageChange);
   onPageChangeRef.current = onPageChange;
+  const onLinkClickRef = useRef(onLinkClick);
+  onLinkClickRef.current = onLinkClick;
   // 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));
@@ -761,6 +648,8 @@ export function useHtmlAnnotation({
         && type !== `${PREFIX}resize`
         // Page identity is navigation state, not an annotation mutation.
         && type !== `${PREFIX}page-change`
+        // Following a link is a read action; a read-only document still navigates.
+        && type !== `${PREFIX}link-click`
       ) {
         return;
       }
@@ -927,6 +816,10 @@ export function useHtmlAnnotation({
       if (type === `${PREFIX}page-change`) {
         onPageChangeRef.current?.(message.pageUrl);
       }
+
+      if (type === `${PREFIX}link-click`) {
+        onLinkClickRef.current?.(message.href);
+      }
     }
 
     window.addEventListener("message", handler);