@plannotator/ui 0.38.2 → 0.40.0

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,5 +1,5 @@
 import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
-import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type ImageAttachment } from "../../types";
+import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type HtmlElementContext, type ImageAttachment } from "../../types";
 import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
@@ -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-";
 
@@ -83,6 +88,8 @@ interface BridgeSelectionMessage {
   targetKey?: string;
   /** Semantic label from the pinpoint hover cascade (chips + export). */
   targetLabel?: string;
+  /** Agent-facing element description (pinpoint clicks) — validated, size-capped. */
+  context?: HtmlElementContext;
 }
 
 /** One draft target in an in-flight multi-select comment. Index 0 is primary. */
@@ -91,6 +98,7 @@ export interface HtmlDraftTarget {
   label?: string;
   text: string;
   anchor: HtmlElementAnchor | null;
+  context?: HtmlElementContext;
 }
 
 interface BridgeMultiTargetAddedMessage {
@@ -99,6 +107,7 @@ interface BridgeMultiTargetAddedMessage {
   label?: string;
   text: string;
   anchor?: HtmlElementAnchor;
+  context?: HtmlElementContext;
 }
 
 interface BridgeRect {
@@ -119,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. */
@@ -128,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. */
@@ -178,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';
@@ -310,6 +328,15 @@ function parseTargetLabel(value: unknown): string | undefined {
     : collapsed;
 }
 
+// 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;
   const { top, left, width, height } = value;
@@ -338,6 +365,7 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
         pinpoint: value.pinpoint === true,
         targetKey: parseTargetKey(value.targetKey) ?? undefined,
         targetLabel: parseTargetLabel(value.targetLabel),
+        context: parseHtmlElementContext(value.context),
       };
     }
     case `${PREFIX}multi-target-added`: {
@@ -349,6 +377,7 @@ export function parseBridgeMessage(value: unknown): BridgeMessage | null {
         label: parseTargetLabel(value.label),
         text: capSelectionText(value.text),
         anchor: parseHtmlElementAnchor(value.anchor) ?? undefined,
+        context: parseHtmlElementContext(value.context),
       };
     }
     case `${PREFIX}multi-target-removed`: {
@@ -393,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"
@@ -421,6 +460,7 @@ export function useHtmlAnnotation({
   onResize,
   live,
   onPageChange,
+  onLinkClick,
   onBridgePointer,
   onUnanchoredChange,
   maxAdditionalTargets,
@@ -455,6 +495,7 @@ export function useHtmlAnnotation({
   // Element anchor for the pending pinpoint selection — committed onto the
   // annotation so restoration can resolve the exact element again.
   const pendingAnchorRef = useRef<HtmlElementAnchor | null>(null);
+  const pendingContextRef = useRef<HtmlElementContext | null>(null);
   const draftTargetsRef = useRef<HtmlDraftTarget[]>(draftTargets);
   draftTargetsRef.current = draftTargets;
   const onBridgePointerRef = useRef(onBridgePointer);
@@ -493,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));
@@ -534,6 +577,7 @@ export function useHtmlAnnotation({
         setCommentPopover(null);
         pendingTextRef.current = "";
         pendingAnchorRef.current = null;
+        pendingContextRef.current = null;
         return;
       }
       if (index === 0) {
@@ -542,6 +586,7 @@ export function useHtmlAnnotation({
         const next = remaining[0]!;
         pendingTextRef.current = next.text;
         pendingAnchorRef.current = next.anchor;
+        pendingContextRef.current = next.context ?? null;
         setCommentPopover((prev) =>
           prev ? { ...prev, contextText: next.text, selectedText: next.text } : prev,
         );
@@ -603,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;
       }
@@ -610,6 +657,7 @@ export function useHtmlAnnotation({
       if (type === `${PREFIX}selection`) {
         pendingTextRef.current = message.text;
         pendingAnchorRef.current = message.anchor ?? null;
+        pendingContextRef.current = message.context ?? null;
         setDraftTargets([]); // a new selection always starts a fresh draft
         const anchor = positionAnchor(message.rect);
         if (!anchor) return;
@@ -654,6 +702,7 @@ export function useHtmlAnnotation({
                 label: message.targetLabel,
                 text: message.text,
                 anchor: message.anchor ?? null,
+                context: message.context,
               },
             ]);
             post({
@@ -689,6 +738,7 @@ export function useHtmlAnnotation({
               label: message.label,
               text: message.text,
               anchor: message.anchor ?? null,
+              context: message.context,
             },
           ]);
           setComposerFocusToken((t) => t + 1);
@@ -711,6 +761,7 @@ export function useHtmlAnnotation({
         if (!commentPopoverRef.current && !quickLabelPickerRef.current) {
           pendingTextRef.current = "";
           pendingAnchorRef.current = null;
+          pendingContextRef.current = null;
         }
       }
 
@@ -765,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);
@@ -826,11 +881,13 @@ export function useHtmlAnnotation({
         author: getIdentity(),
         createdA: Date.now(),
         htmlAnchor: pendingAnchorRef.current ?? undefined,
+        elementContext: pendingContextRef.current ?? undefined,
       });
 
       setToolbarState(null);
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
+      pendingContextRef.current = null;
     },
     [post],
   );
@@ -869,6 +926,7 @@ export function useHtmlAnnotation({
               label: t.label,
               text: t.text,
               anchor: t.anchor ?? undefined,
+              ...(t.context ? { context: t.context } : {}),
             }))
           : undefined;
 
@@ -887,6 +945,7 @@ export function useHtmlAnnotation({
         createdA: Date.now(),
         images,
         htmlAnchor: pendingAnchorRef.current ?? undefined,
+        elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,
       });
 
@@ -894,6 +953,7 @@ export function useHtmlAnnotation({
       setDraftTargets([]);
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
+      pendingContextRef.current = null;
     },
     [post],
   );
@@ -915,6 +975,7 @@ export function useHtmlAnnotation({
             label: t.label,
             text: t.text,
             anchor: t.anchor ?? undefined,
+            ...(t.context ? { context: t.context } : {}),
           }))
         : undefined;
 
@@ -934,6 +995,7 @@ export function useHtmlAnnotation({
       author: getIdentity(),
       createdA: Date.now(),
       htmlAnchor: pendingAnchorRef.current ?? undefined,
+      elementContext: pendingContextRef.current ?? undefined,
       htmlAdditionalTargets: additionalTargets,
     });
 
@@ -941,6 +1003,7 @@ export function useHtmlAnnotation({
     setDraftTargets([]);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const handleCommentClose = useCallback(() => {
@@ -949,6 +1012,7 @@ export function useHtmlAnnotation({
     setDraftTargets([]);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const removeDraftTarget = useCallback(
@@ -971,6 +1035,7 @@ export function useHtmlAnnotation({
     setToolbarState(null);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const applyQuickLabel = useCallback(
@@ -994,10 +1059,12 @@ export function useHtmlAnnotation({
         author: getIdentity(),
         createdA: Date.now(),
         htmlAnchor: pendingAnchorRef.current ?? undefined,
+        elementContext: pendingContextRef.current ?? undefined,
       });
       clearState();
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
+      pendingContextRef.current = null;
     },
     [post],
   );