@plannotator/ui 0.38.2 → 0.39.0

package/types.ts

@@ -82,6 +82,7 @@ export interface Annotation {
   pageUrl?: string; // set only by live app annotate sessions: the page (pathname + search) the annotation was made on; restore filters to the current page and export groups by page
   inReplyTo?: string; // id of the annotation this one replies to; a reply inherits its parent's anchor, renders indented under it in the panel, and exports grouped under it. Additive: annotations without it render and export exactly as before.
   htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
+  elementContext?: HtmlElementContext; // raw-HTML / live-app pinpoint: bounded agent-facing description of the primary element (never used by restore)
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections
   startMeta?: AnnotationTextMeta;
@@ -124,6 +125,50 @@ export interface HtmlAnnotationTarget {
   text: string;
   /** Element anchor for restoration; absent when the bridge failed closed. */
   anchor?: HtmlElementAnchor;
+  /** Agent-facing element description (smaller budget than the primary's). */
+  context?: HtmlElementContext;
+}
+
+/**
+ * A bounded, agent-facing description of a pinpointed element, captured by the
+ * bridge at annotation time (only it can see the DOM). Purely descriptive:
+ * restore never reads it (that is `HtmlElementAnchor`'s job). It exists so the
+ * exported feedback can tell an agent working in the app's SOURCE which
+ * element the comment is about — identity (what it is), location (where it
+ * sits), and hooks (what to grep for) — without dumping the page. Every field
+ * is page-controlled and re-validated at the parent trust boundary
+ * (`parseHtmlElementContext`). Additive: annotations without one export
+ * exactly as before, and share links never carry it.
+ */
+export interface HtmlElementContext {
+  tag: string;
+  id?: string;
+  /** Author classes, generated/hashed ones skipped; may end in "+N more". */
+  classes?: string[];
+  /** Ancestor path, e.g. `body > div#root > header.site-header > nav#site-nav`. */
+  path?: string;
+  /** Explicit `role` or the tag's implicit ARIA role. */
+  role?: string;
+  /** Accessible name: aria-label, aria-labelledby, alt, title, <label for>, own short text. */
+  name?: string;
+  /** Allowlisted attributes in a fixed order (href/src scrubbed of query and fragment). */
+  attrs?: Array<[string, string]>;
+  /** Rendered text (innerText), whitespace-collapsed, word-boundary truncated. */
+  text?: string;
+  /** Collapsed HTML skeleton: opening tag with allowlisted attributes, then children as bare tags. */
+  outline?: string;
+  /** Number of element children (after skipping script/style/template and viewer overlays). */
+  children?: number;
+  /** Viewport-relative bounding box plus the viewport it was seen at. */
+  rect?: { x: number; y: number; w: number; h: number; vw: number; vh: number };
+  /** Nearest enclosing landmark/region, e.g. `header.site-header "Primary"`. */
+  landmark?: string;
+  /** Nearest preceding heading, e.g. `h2 "Usage"`. */
+  heading?: string;
+  /** Nearest author component marker, e.g. `data-component=AppNav`. */
+  component?: string;
+  /** Live-app sessions only: the route the element was seen on and the page title. */
+  page?: { url: string; title?: string };
 }
 
 export type AlertKind = 'note' | 'tip' | 'warning' | 'caution' | 'important';

package/utils/decisionSpec.ts

@@ -35,7 +35,6 @@ export interface DecisionPrimary {
   title: string;            // tooltip / aria description
   tone: Exclude<DecisionTone, 'destructive'>;
   icon?: 'check' | 'send';
-  count?: number;           // rendered as the inline pill; omitted when 0
   /**
    * Platform self-approval (PR6, §3.4): rendered dimmed but NOT disabled.
    * The reason surfaces through the shared Tooltip + aria-describedby (the
@@ -87,7 +86,7 @@ export interface DecisionSpecInput {
   app: 'annotate' | 'review';
   /** Annotate: `gate`. Review: always true — review's primary decision IS approval. */
   gate: boolean;
-  /** The count rendered in the pill and interpolated into labels. */
+  /** The annotation count interpolated into the menu's discard and note copy (never the primary label). */
   count: number;
   /**
    * Whether there is anything to send. Deliberately separate from `count`:
@@ -327,7 +326,6 @@ function buildFeedbackSpec(input: DecisionSpecInput, approvalFlow: boolean): Dec
       title: 'Send your feedback to the agent',
       tone: 'primary',
       icon: 'send',
-      count: count > 0 ? count : undefined,
     },
     items,
   };
@@ -395,7 +393,6 @@ function buildPlatformSpec(input: DecisionSpecInput, platform: DecisionPlatformI
       title: `Post review to ${platform.label}`,
       tone: 'primary',
       icon: 'send',
-      count: count > 0 ? count : undefined,
     },
     items: [
       {

package/utils/parser.ts

@@ -1099,6 +1099,88 @@ const blockEndLine = (block: Block): number => {
 
 /** Resolve the source-line label for a single annotation.
  *  Returns null for global comments, diff-view annotations, or missing blocks. */
+/** Defense in depth for page-controlled strings in agent-read feedback:
+ *  collapse whitespace (no injected markdown structure) and defuse any
+ *  backtick run that could close an inline code span or a fence. */
+const safeInline = (value: unknown, max = 200): string => {
+  const collapsed = typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
+  const defused = collapsed.replace(/`+/g, "'");
+  return defused.length > max ? `${defused.slice(0, max)}…` : defused;
+};
+
+/** The synthesized quote the bridge posts for a text-less element
+ *  (`[element: Navigation]`): a placeholder, not something the agent can use. */
+const isElementPlaceholderQuote = (text: unknown): boolean =>
+  typeof text === 'string' && /^\[element: [^\]]*\]$/.test(text.trim());
+
+/** The heading line for a COMMENT entry. When the quote is the bridge's
+ *  text-less placeholder and the annotation carries element context, name the
+ *  element instead (`Feedback on the <nav> element — "Primary"`); every other
+ *  annotation keeps the quote line exactly as before. */
+const commentHeadingLine = (ann: any): string => {
+  const context = ann?.elementContext;
+  if (context && typeof context.tag === 'string' && isElementPlaceholderQuote(ann.originalText)) {
+    const tag = safeInline(context.tag, 32);
+    const name = context.name ? safeInline(context.name, 120) : '';
+    return `Feedback on the <${tag}> element${name ? ` — "${name}"` : ''}`;
+  }
+  return `Feedback on: "${ann.originalText}"`;
+};
+
+export interface ElementContextExportOptions {
+  /** Emit the live-app route line. The grouped export already prints a
+   *  `## Page:` heading, so it passes false; a single copied entry passes true. */
+  includeRoute?: boolean;
+}
+
+/** The agent-facing element block for a raw-HTML / live-app pinpoint: a
+ *  fenced HTML skeleton (the one markdown construct whose interior cannot
+ *  become structure) plus the identity lines an agent greps for. Emits
+ *  nothing when the annotation carries no context, keeping every other
+ *  annotation's output byte-identical. */
+export const elementContextExportBlock = (ann: any, opts: ElementContextExportOptions = {}): string => {
+  const context = ann?.elementContext;
+  if (!context || typeof context !== 'object' || typeof context.tag !== 'string') return '';
+  let block = '';
+  if (typeof context.outline === 'string' && context.outline.trim()) {
+    // Fence at 4 backticks; the boundary already defuses 3+ runs inside the
+    // outline, and a 4-run here cannot be closed by anything the page wrote.
+    const outline = context.outline.replace(/`{3,}/g, "'''").trim();
+    block += `\n\`\`\`\`html\n${outline}\n\`\`\`\`\n`;
+  } else {
+    block += '\n';
+  }
+  const selector = ann?.htmlAnchor?.selector;
+  if (typeof selector === 'string' && selector) block += `- **selector** \`${safeInline(selector, 300)}\`\n`;
+  if (context.path) block += `- **path** \`${safeInline(context.path, 512)}\`\n`;
+  const identity: string[] = [];
+  if (context.role) identity.push(`**role** ${safeInline(context.role, 32)}`);
+  if (context.name) identity.push(`**name** "${safeInline(context.name, 120)}"`);
+  if (context.component) identity.push(`**component** \`${safeInline(context.component, 100)}\``);
+  if (identity.length) block += `- ${identity.join(' · ')}\n`;
+  if (Array.isArray(context.attrs) && context.attrs.length) {
+    const attrs = context.attrs
+      .filter((pair: unknown) => Array.isArray(pair) && pair.length === 2)
+      .map((pair: [string, string]) => `${safeInline(pair[0], 40)}="${safeInline(pair[1], 120)}"`)
+      .join(' ');
+    if (attrs) block += `- **attrs** \`${attrs.replace(/`/g, "'")}\`\n`;
+  }
+  if (context.text) block += `- **text** "${safeInline(context.text, 300)}"\n`;
+  if (opts.includeRoute && context.page && context.page.url) {
+    const title = context.page.title ? ` — "${safeInline(context.page.title, 200)}"` : '';
+    block += `- **route** \`${safeInline(context.page.url, 2048)}\`${title}\n`;
+  }
+  const r = context.rect;
+  if (r && ['x', 'y', 'w', 'h', 'vw', 'vh'].every((k) => typeof r[k] === 'number' && Number.isFinite(r[k]))) {
+    block += `- **box** ${r.x},${r.y} ${r.w}×${r.h} (viewport ${r.vw}×${r.vh})\n`;
+  }
+  const near: string[] = [];
+  if (context.landmark) near.push(safeInline(context.landmark, 80));
+  if (context.heading) near.push(`heading ${safeInline(context.heading, 130)}`);
+  if (near.length) block += `- **near** ${near.join(' · ')}\n`;
+  return block;
+};
+
 /** Multi-target raw-HTML comments: list every ADDITIONAL element the one
  *  comment covers (the primary target is already quoted as `originalText`),
  *  labeled with the semantic hover label plus a short excerpt so the agent
@@ -1120,11 +1202,56 @@ const additionalTargetsExportBlock = (ann: any): string => {
     const raw = typeof target?.text === 'string' ? target.text : '';
     const excerpt = raw.replace(/\s+/g, ' ').trim();
     const clipped = excerpt.length > 120 ? `${excerpt.slice(0, 120)}…` : excerpt;
-    block += `- ${label}"${clipped}"\n`;
+    // Element identity for the agent, one line per extra target: the
+    // selector and the path (a full context block per target would swamp
+    // the comment; the rest of the context stays persisted, not exported).
+    const locators: string[] = [];
+    const selector = target?.anchor?.selector;
+    if (typeof selector === 'string' && selector) locators.push(`\`${safeInline(selector, 300)}\``);
+    const path = target?.context?.path;
+    if (typeof path === 'string' && path) locators.push(`\`${safeInline(path, 512)}\``);
+    block += `- ${label}"${clipped}"${locators.length ? ` — ${locators.join(' · ')}` : ''}\n`;
   });
   return block;
 };
 
+/**
+ * One annotation rendered as a standalone feedback entry (no number, no
+ * document heading), for hosts that surface a single annotation to an agent.
+ * The body is the same shape the full export emits for the entry, including
+ * the element block, so a standalone entry never drifts from what Send
+ * Feedback delivers; the live-app route line is included here because the
+ * standalone entry has no `## Page:` heading above it. Plannotator's own
+ * panel chrome does not use it.
+ */
+export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOptions = { includeRoute: true }): string => {
+  let output = '';
+  switch (ann?.type) {
+    case 'DELETION':
+      output += `Remove this\n\`\`\`\n${ann.originalText}\n\`\`\`\n`;
+      break;
+    case 'GLOBAL_COMMENT':
+      output += `General feedback\n> ${ann.text}\n`;
+      break;
+    default:
+      if (ann?.isQuickLabel) {
+        output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
+        if (ann.quickLabelTip) output += `> ${ann.quickLabelTip}\n`;
+      } else {
+        output += `${commentHeadingLine(ann)}\n> ${ann?.text ?? ''}\n`;
+      }
+  }
+  output += elementContextExportBlock(ann, opts);
+  output += additionalTargetsExportBlock(ann);
+  if (Array.isArray(ann?.images) && ann.images.length > 0) {
+    output += `**Attached images:**\n`;
+    ann.images.forEach((img: ImageAttachment) => {
+      output += `- [${img.name}] \`${img.path}\`\n`;
+    });
+  }
+  return output;
+};
+
 const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   if (!ann.blockId || ann.type === 'GLOBAL_COMMENT') return null;
   if (typeof ann.blockId === 'string' && ann.blockId.startsWith('diff-block-')) return null;
@@ -1292,12 +1419,12 @@ export const exportAnnotations = (
 
       case 'COMMENT':
         if (ann.isQuickLabel) {
-          output += `[${ann.text}] Feedback on: "${ann.originalText}"\n`;
+          output += `[${ann.text}] ${commentHeadingLine(ann)}\n`;
           if (ann.quickLabelTip) {
             output += `> ${ann.quickLabelTip}\n`;
           }
         } else {
-          output += `Feedback on: "${ann.originalText}"\n`;
+          output += `${commentHeadingLine(ann)}\n`;
           output += `> ${ann.text}\n`;
         }
         break;
@@ -1308,6 +1435,9 @@ export const exportAnnotations = (
         break;
     }
 
+    // Raw-HTML / live-app pinpoints describe their element for the agent
+    // (the grouped export's `## Page:` heading already carries the route).
+    output += elementContextExportBlock(ann, { includeRoute: false });
     // Multi-target raw-HTML comments list every additional covered element.
     output += additionalTargetsExportBlock(ann);
 
@@ -1408,7 +1538,7 @@ export const exportLinkedDocAnnotations = (
           break;
 
         case 'COMMENT':
-          output += `Feedback on: "${ann.originalText}"\n`;
+          output += `${commentHeadingLine(ann)}\n`;
           output += `> ${ann.text}\n`;
           break;
 
@@ -1418,6 +1548,7 @@ export const exportLinkedDocAnnotations = (
           break;
       }
 
+      output += elementContextExportBlock(ann, { includeRoute: false });
       // Multi-target raw-HTML comments list every additional covered element.
       output += additionalTargetsExportBlock(ann);