@plannotator/ui 0.38.2 → 0.40.0

package/utils/parser.ts

@@ -1099,6 +1099,92 @@ 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;
+  /** Print the identity lines WITHOUT the fenced outline, for model turns where
+   *  the 600-char outline is the expensive part. Default true. */
+  includeOutline?: 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 '';
+  const includeOutline = opts.includeOutline ?? true;
+  let block = '';
+  if (includeOutline && 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 +1206,67 @@ 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).
+    //
+    // Gated on the target carrying element context, which is what makes the
+    // element-context work additive in the literal sense it claims: a target
+    // captured before it existed (or restored from an older draft) has an
+    // anchor but no context, and exports byte-identically to before.
+    const locators: string[] = [];
+    if (target?.context && typeof target.context === 'object') {
+      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`;
+      }
+  }
+  const resolvedOpts: ElementContextExportOptions = {
+    includeRoute: opts.includeRoute ?? true,
+    ...(opts.includeOutline !== undefined ? { includeOutline: opts.includeOutline } : {}),
+  };
+  output += elementContextExportBlock(ann, resolvedOpts);
+  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 +1434,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 +1450,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 +1553,7 @@ export const exportLinkedDocAnnotations = (
           break;
 
         case 'COMMENT':
-          output += `Feedback on: "${ann.originalText}"\n`;
+          output += `${commentHeadingLine(ann)}\n`;
           output += `> ${ann.text}\n`;
           break;
 
@@ -1418,6 +1563,7 @@ export const exportLinkedDocAnnotations = (
           break;
       }
 
+      output += elementContextExportBlock(ann, { includeRoute: false });
       // Multi-target raw-HTML comments list every additional covered element.
       output += additionalTargetsExportBlock(ann);
 

package/utils/terminalToolsAnnouncement.ts

@@ -0,0 +1,76 @@
+/**
+ * One-time gate for the terminal-tools announcement (Plannotator TUI and
+ * Herdr Annotate). Cookie-backed like the other announcement gates, so a
+ * dismissal survives Plannotator's random localhost ports, and shared by the
+ * plan editor, the annotate surfaces and the code review editor: dismissing it
+ * anywhere retires it everywhere.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-announce-tui-herdr-seen';
+// Bump to re-announce after a meaningful revision.
+const CURRENT_VERSION = '1';
+
+export function needsTerminalToolsAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+export function markTerminalToolsAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}
+
+export interface TerminalToolsAnnouncementGateState {
+  /**
+   * Latched at mount from needsTerminalToolsAnnouncement(). Latched rather than
+   * read per render so a dismissal cannot unmount the dialog before its own
+   * click handler finishes.
+   */
+  readonly announcementPending: boolean;
+  /** The app has not finished loading its initial payload. */
+  readonly isLoading: boolean;
+  /**
+   * The session has no author to address: archive browsing, a read-only shared
+   * plan, and any session with no Plannotator server behind it (the share
+   * portal's root and its demo plan included — those are not "shared
+   * sessions", so the host must fold that in). Telling a viewer about a CLI
+   * they did not open is noise, and the cookie is deliberately NOT consumed,
+   * so the next authoring session still shows it.
+   */
+  readonly readOnlySession: boolean;
+  /**
+   * Plannotator's compact touch shell. The panel is desktop-shaped (install
+   * commands to copy, four outbound links) and a phone is not where anyone
+   * installs a terminal tool. Also deferred rather than consumed.
+   */
+  readonly compact: boolean;
+  /**
+   * Any other first-run dialog is on screen. The chain dialogs never stack.
+   */
+  readonly otherFirstRunDialogVisible: boolean;
+}
+
+/**
+ * Chain gate for the announcement. It is LAST in each app's first-run dialog
+ * chain, after every dialog that asks the user to decide something (code
+ * review: guide intro, look-and-feel, review setup, edit mode, token hover
+ * cards; plan and annotate: look-and-feel, goal setup, permission mode).
+ *
+ * Last rather than first because none of those dialogs consume this cookie:
+ * a session that is busy asking questions defers the announcement to the next
+ * load instead of burning it. That also puts it in front of the right reader.
+ * Someone opening Plannotator for the first time is still learning this app;
+ * the people who should hear that it now runs in a terminal are the ones who
+ * already answered every setup question, and they see it on their next load.
+ */
+export function terminalToolsAnnouncementCanShow(
+  state: TerminalToolsAnnouncementGateState,
+): boolean {
+  return (
+    state.announcementPending &&
+    !state.isLoading &&
+    !state.readOnlySession &&
+    !state.compact &&
+    !state.otherFirstRunDialogVisible
+  );
+}