@plannotator/ui 0.38.2 → 0.39.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 {
@@ -83,6 +83,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 +93,7 @@ export interface HtmlDraftTarget {
   label?: string;
   text: string;
   anchor: HtmlElementAnchor | null;
+  context?: HtmlElementContext;
 }
 
 interface BridgeMultiTargetAddedMessage {
@@ -99,6 +102,7 @@ interface BridgeMultiTargetAddedMessage {
   label?: string;
   text: string;
   anchor?: HtmlElementAnchor;
+  context?: HtmlElementContext;
 }
 
 interface BridgeRect {
@@ -310,6 +314,155 @@ 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;
+}
+
 function parseBridgeRect(value: unknown): BridgeRect | null {
   if (!isRecord(value)) return null;
   const { top, left, width, height } = value;
@@ -338,6 +491,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 +503,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`: {
@@ -455,6 +610,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);
@@ -534,6 +690,7 @@ export function useHtmlAnnotation({
         setCommentPopover(null);
         pendingTextRef.current = "";
         pendingAnchorRef.current = null;
+        pendingContextRef.current = null;
         return;
       }
       if (index === 0) {
@@ -542,6 +699,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,
         );
@@ -610,6 +768,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 +813,7 @@ export function useHtmlAnnotation({
                 label: message.targetLabel,
                 text: message.text,
                 anchor: message.anchor ?? null,
+                context: message.context,
               },
             ]);
             post({
@@ -689,6 +849,7 @@ export function useHtmlAnnotation({
               label: message.label,
               text: message.text,
               anchor: message.anchor ?? null,
+              context: message.context,
             },
           ]);
           setComposerFocusToken((t) => t + 1);
@@ -711,6 +872,7 @@ export function useHtmlAnnotation({
         if (!commentPopoverRef.current && !quickLabelPickerRef.current) {
           pendingTextRef.current = "";
           pendingAnchorRef.current = null;
+          pendingContextRef.current = null;
         }
       }
 
@@ -826,11 +988,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 +1033,7 @@ export function useHtmlAnnotation({
               label: t.label,
               text: t.text,
               anchor: t.anchor ?? undefined,
+              ...(t.context ? { context: t.context } : {}),
             }))
           : undefined;
 
@@ -887,6 +1052,7 @@ export function useHtmlAnnotation({
         createdA: Date.now(),
         images,
         htmlAnchor: pendingAnchorRef.current ?? undefined,
+        elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,
       });
 
@@ -894,6 +1060,7 @@ export function useHtmlAnnotation({
       setDraftTargets([]);
       pendingTextRef.current = "";
       pendingAnchorRef.current = null;
+      pendingContextRef.current = null;
     },
     [post],
   );
@@ -915,6 +1082,7 @@ export function useHtmlAnnotation({
             label: t.label,
             text: t.text,
             anchor: t.anchor ?? undefined,
+            ...(t.context ? { context: t.context } : {}),
           }))
         : undefined;
 
@@ -934,6 +1102,7 @@ export function useHtmlAnnotation({
       author: getIdentity(),
       createdA: Date.now(),
       htmlAnchor: pendingAnchorRef.current ?? undefined,
+      elementContext: pendingContextRef.current ?? undefined,
       htmlAdditionalTargets: additionalTargets,
     });
 
@@ -941,6 +1110,7 @@ export function useHtmlAnnotation({
     setDraftTargets([]);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const handleCommentClose = useCallback(() => {
@@ -949,6 +1119,7 @@ export function useHtmlAnnotation({
     setDraftTargets([]);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const removeDraftTarget = useCallback(
@@ -971,6 +1142,7 @@ export function useHtmlAnnotation({
     setToolbarState(null);
     pendingTextRef.current = "";
     pendingAnchorRef.current = null;
+    pendingContextRef.current = null;
   }, [post]);
 
   const applyQuickLabel = useCallback(
@@ -994,10 +1166,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],
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.38.2",
+  "version": "0.39.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",