@plannotator/ui 0.50.0 → 0.51.0

package/utils/diagramAskAI.ts

@@ -0,0 +1,161 @@
+import {
+  diagramAnchorLocationLine,
+  diagramTargetName,
+  diagramTargetText,
+  type DiagramAnchor,
+  type DiagramKind,
+  type DiagramTarget,
+} from '@plannotator/core/diagram-anchor';
+import type { CommentAskAIContext } from '../components/CommentPopover';
+
+/**
+ * Ask AI from a diagram comment: the question rides the same
+ * `CommentAskAIContext` the markdown and html composers send, so the host's
+ * one Ask AI path (an SDK provider, "Ask this session", the agent terminal)
+ * carries it unchanged. `text` is the part's label (what the chat shows under
+ * the question); `detail` is the agent-facing identity, which
+ * `buildDefaultPrompt` puts on the USER message before the question, never in
+ * the system prompt:
+ *
+ *   Diagram node Approve? (D), line 7          <- the export's location line
+ *   Diagram type: Mermaid (flowchart)
+ *   Diagram source, document lines 6–9:
+ *   ````mermaid
+ *   …
+ *   ````
+ *
+ * The source is bounded (a window around the part when the diagram is long),
+ * so a huge whole-file diagram never floods a turn.
+ */
+
+const ENGINE_LABELS: Record<DiagramKind, string> = { mermaid: 'Mermaid', graphviz: 'Graphviz' };
+const FENCE_LANGUAGE: Record<DiagramKind, string> = { mermaid: 'mermaid', graphviz: 'dot' };
+
+/** Most diagram source lines a question carries. */
+export const MAX_ASK_AI_DIAGRAM_SOURCE_LINES = 40;
+/** Most diagram source characters a question carries. */
+export const MAX_ASK_AI_DIAGRAM_SOURCE_CHARS = 4000;
+
+export interface DiagramAskAIInput {
+  readonly kind: DiagramKind;
+  /** The part the question is about; `sourceLine` names DOCUMENT lines. */
+  readonly anchor: DiagramAnchor;
+  /** Shift-click targets the draft also covers (absent or empty for most). */
+  readonly additionalTargets?: readonly DiagramTarget[];
+  /** The diagram text (the fence body, or the whole file). */
+  readonly source: string;
+  /** Lines to add to a diagram line to name the document line: the fence's
+   * opening line for a fence, 0 when the document is the diagram. */
+  readonly sourceLineOffset: number;
+  /** The document the diagram lives in, as the other composers send it. */
+  readonly sourcePath?: string;
+}
+
+/** A fence that no backtick run in the source can close early. */
+function fenceFor(source: string): string {
+  let longest = 0;
+  for (const run of source.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+  return '`'.repeat(Math.max(4, longest + 1));
+}
+
+/** A line longer than the whole budget is cut, with a visible marker. */
+const TRUNCATION_MARKER = '…';
+
+/**
+ * The bounded slice of the source a question carries, grown outward from the
+ * part's line (the top of the diagram when the part has no line), one line
+ * below then one above, until the line cap or the character cap stops a
+ * side. The part's own line is always in it; a part line longer than the
+ * whole character budget is cut with a visible marker, so the slice never
+ * exceeds MAX_ASK_AI_DIAGRAM_SOURCE_CHARS (newlines included). Returns
+ * 1-based DIAGRAM lines and the text to quote.
+ */
+function sourceWindow(
+  lines: readonly string[],
+  anchor: DiagramAnchor,
+  offset: number,
+): { first: number; last: number; body: string; excerpt: boolean } | null {
+  let wholeFirst = 1;
+  let wholeLast = lines.length;
+  while (wholeLast > 0 && (lines[wholeLast - 1] ?? '').trim() === '') wholeLast -= 1;
+  while (wholeFirst <= wholeLast && (lines[wholeFirst - 1] ?? '').trim() === '') wholeFirst += 1;
+  if (wholeLast === 0 || wholeFirst > wholeLast) return null;
+
+  const partLine = anchor.kind !== 'diagram' && anchor.sourceLine !== null ? anchor.sourceLine[0] - offset : null;
+  const center = partLine !== null && partLine >= wholeFirst && partLine <= wholeLast ? partLine : wholeFirst;
+
+  let centerText = lines[center - 1] ?? '';
+  let truncated = false;
+  if (centerText.length > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) {
+    centerText = centerText.slice(0, MAX_ASK_AI_DIAGRAM_SOURCE_CHARS - TRUNCATION_MARKER.length) + TRUNCATION_MARKER;
+    truncated = true;
+  }
+  let chars = centerText.length;
+  let count = 1;
+  let first = center;
+  let last = center;
+  let growDown = true;
+  let growUp = true;
+  while ((growDown || growUp) && count < MAX_ASK_AI_DIAGRAM_SOURCE_LINES) {
+    if (growDown) {
+      const next = last + 1;
+      const cost = (lines[next - 1] ?? '').length + 1;
+      if (next > wholeLast || chars + cost > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) growDown = false;
+      else {
+        last = next;
+        chars += cost;
+        count += 1;
+      }
+    }
+    if (growUp && count < MAX_ASK_AI_DIAGRAM_SOURCE_LINES) {
+      const next = first - 1;
+      const cost = (lines[next - 1] ?? '').length + 1;
+      if (next < wholeFirst || chars + cost > MAX_ASK_AI_DIAGRAM_SOURCE_CHARS) growUp = false;
+      else {
+        first = next;
+        chars += cost;
+        count += 1;
+      }
+    }
+  }
+  const body = [...lines.slice(first - 1, center - 1), centerText, ...lines.slice(center, last)].join('\n');
+  return { first, last, body, excerpt: truncated || first > wholeFirst || last < wholeLast };
+}
+
+/** The agent-facing identity of a diagram part (the `detail` Ask AI sends). */
+export function diagramIdentityForAskAI(input: DiagramAskAIInput): string {
+  const { kind, anchor, source, sourceLineOffset } = input;
+  const out: string[] = [diagramAnchorLocationLine(anchor)];
+  for (const extra of input.additionalTargets ?? []) {
+    const text = diagramTargetText(extra);
+    out.push(`Also: ${diagramTargetName(extra)}${text !== '' && text !== extra.id ? ` "${text}"` : ''}`);
+  }
+  out.push(`Diagram type: ${ENGINE_LABELS[kind]} (${anchor.family})`);
+
+  const lines = source.split('\n');
+  const window = sourceWindow(lines, anchor, sourceLineOffset);
+  if (window !== null) {
+    const body = window.body;
+    const docFirst = window.first + sourceLineOffset;
+    const docLast = window.last + sourceLineOffset;
+    const range = docLast > docFirst ? `lines ${docFirst}–${docLast}` : `line ${docFirst}`;
+    const partial = window.excerpt ? ' (excerpt)' : '';
+    const fence = fenceFor(body);
+    out.push(`Diagram source${partial}, document ${range}:`);
+    out.push(`${fence}${FENCE_LANGUAGE[kind]}\n${body}\n${fence}`);
+  }
+  return out.join('\n');
+}
+
+/** The Ask AI context for a question asked from a diagram comment. */
+export function diagramAskAIContext(input: DiagramAskAIInput): CommentAskAIContext {
+  const { kind, anchor } = input;
+  const engine = ENGINE_LABELS[kind];
+  return {
+    kind: 'selection',
+    label: anchor.kind === 'diagram' ? `${engine} diagram` : `${engine} diagram ${diagramTargetName(anchor)}`,
+    text: diagramTargetText(anchor),
+    ...(input.sourcePath !== undefined ? { sourcePath: input.sourcePath } : {}),
+    detail: diagramIdentityForAskAI(input),
+  };
+}

package/utils/parser.ts

@@ -778,11 +778,34 @@ const commentHeadingLine = (ann: any): string => {
   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}"` : ''}`;
+    const file = elementSourceFileName(context);
+    return `Feedback on the <${tag}> element${name ? ` — "${name}"` : ''}${file && file !== name ? ` (${file})` : ''}`;
   }
   return `Feedback on: "${ann.originalText}"`;
 };
 
+/** The file a media element shows, so two nameless images read differently in a heading:
+ *  `team.jpg` for `https://cdn.test/img/team.jpg?…`, `data:image/png` for an
+ *  inline image. Empty when the context carries no source.
+ *
+ *  `sourceName` is the bridge's own resolution (the one the composer quote
+ *  uses: src, a lazy data-src, srcset, <picture>/<source>, poster), so the
+ *  heading and the quote can never name different files. Contexts captured
+ *  before that field existed fall back to the scrubbed `src` attribute. */
+const elementSourceFileName = (context: any): string => {
+  if (typeof context?.sourceName === 'string' && context.sourceName.trim()) {
+    return safeInline(context.sourceName, 60);
+  }
+  const attrs = Array.isArray(context?.attrs) ? context.attrs : [];
+  const pair = attrs.find((p: unknown) => Array.isArray(p) && p[0] === 'src' && typeof p[1] === 'string');
+  if (!pair) return '';
+  const value: string = pair[1].trim();
+  if (/^data:/i.test(value)) return safeInline(`data:${value.slice(5).split(/[;,]/)[0] || 'unknown'}`, 60);
+  const path = value.replace(/\?…$/, '').replace(/\/+$/, '');
+  const name = path.slice(path.lastIndexOf('/') + 1);
+  return safeInline(name || path, 60);
+};
+
 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. */
@@ -882,6 +905,66 @@ const additionalTargetsExportBlock = (ann: any): string => {
   return block;
 };
 
+/** A URL with its query and fragment replaced by `?…`, the way the bridge
+ *  scrubs captured `href`/`src` values (tokens live in both). */
+const scrubUrlQuery = (url: string): string => {
+  const mark = url.search(/[?#]/);
+  return mark < 0 ? url : `${url.slice(0, mark)}?…`;
+};
+
+/** Ask AI sends no query strings: the live-app route line drops its query
+ *  (the persisted context keeps it, since that is the page that was reviewed). */
+const withoutRouteQuery = (context: unknown): unknown => {
+  const page = (context as any)?.page;
+  if (!page || typeof page.url !== 'string') return context;
+  return { ...(context as object), page: { ...page, url: scrubUrlQuery(page.url) } };
+};
+
+/** The anchor's `href`/`src` selector rung carries the raw attribute value,
+ *  query included (it must, to stay a working selector); Ask AI gets the
+ *  value with the query scrubbed instead. */
+const withoutSelectorQuery = (anchor: AskAIElementTarget['anchor']): AskAIElementTarget['anchor'] => {
+  if (!anchor || typeof anchor.selector !== 'string') return anchor;
+  const selector = anchor.selector.replace(
+    /(\[(?:href|src)=")((?:[^"\\]|\\.)*)(")/g,
+    (_m, open: string, value: string, close: string) => `${open}${scrubUrlQuery(value)}${close}`,
+  );
+  return { ...anchor, selector };
+};
+
+/** One pinpointed element as the Ask AI composer holds it (a draft target). */
+export interface AskAIElementTarget {
+  text?: string;
+  anchor?: { selector?: string } | null;
+  context?: unknown;
+}
+
+/**
+ * The element identity behind an Ask AI question asked from a raw-HTML or
+ * live-app pinpoint: the same identity lines the feedback export prints
+ * (`elementContextExportBlock`), without the fenced outline (the costly part
+ * of a model turn). One entry per pinpointed element, numbered when the
+ * question covers several. Empty when no target carries element context, so
+ * a plain text selection asks exactly what it asked before.
+ */
+export const elementIdentityForAskAI = (targets: readonly AskAIElementTarget[] | null | undefined): string => {
+  if (!Array.isArray(targets)) return '';
+  const blocks = targets
+    .map((target) => ({
+      text: typeof target?.text === 'string' ? safeInline(target.text, 200) : '',
+      lines: elementContextExportBlock(
+        { elementContext: withoutRouteQuery(target?.context), htmlAnchor: withoutSelectorQuery(target?.anchor) },
+        { includeOutline: false, includeRoute: true },
+      ).trim(),
+    }))
+    .filter((block) => block.lines);
+  if (blocks.length === 0) return '';
+  if (blocks.length === 1) return blocks[0].lines;
+  return blocks
+    .map((block, i) => `Element ${i + 1}${block.text ? `: "${block.text}"` : ''}\n${block.lines}`)
+    .join('\n\n');
+};
+
 /**
  * One annotation rendered as a standalone feedback entry (no number, no
  * document heading), for hosts that surface a single annotation to an agent.
@@ -974,57 +1057,81 @@ const questionItemsFromAnswers = (answers: QuestionAnswer[]): QuestionExportItem
     settled: false,
   }));
 
-export const exportAnnotations = (
-  blocks: Block[],
-  allAnnotations: any[],
-  globalAttachments: ImageAttachment[] = [],
-  title: string = 'Plan Feedback',
-  subject: string = 'plan',
-  opts: ExportAnnotationsOptions = {},
-): string => {
-  // Answers to `:::question` blocks are printed first, in their own section,
-  // and never counted as numbered feedback.
-  const { answers, annotations } = splitQuestionAnswers(allAnnotations);
-  const answersSection = answers.length > 0
-    ? formatQuestionAnswersSection(questionExportItems(indexQuestionBlocks(blocks)), answers, { headingLevel: 2 })
-    : '';
-  if (annotations.length === 0 && globalAttachments.length === 0 && !answersSection) {
-    return 'No changes detected.';
-  }
+/** The diff-block index of a comment made in the plan/version diff view
+ *  (`blockId` `diff-block-N`), or null for every other annotation. */
+const diffBlockIndex = (ann: any): number | null => {
+  const match = typeof ann?.blockId === 'string' ? /^diff-block-(\d+)$/.exec(ann.blockId) : null;
+  return match ? Number(match[1]) : null;
+};
 
-  // Sort annotations by block and offset
-  const sortedAnns = [...annotations].sort((a, b) => {
-    const blockA = blocks.findIndex(blk => blk.id === a.blockId);
-    const blockB = blocks.findIndex(blk => blk.id === b.blockId);
-    if (blockA !== blockB) return blockA - blockB;
+/**
+ * Sort annotations in DOCUMENT order: by the block's position in `blocks`,
+ * then by offset. Without blocks (a linked document whose text is unknown)
+ * block ids compare numerically, so block-10 never precedes block-2.
+ *
+ * Comments made in the version diff view (`diff-block-N`) cannot be placed in
+ * the document: N indexes the diff against whichever base was selected, and
+ * nothing in the annotation maps it back to a block. They go together AFTER
+ * every other comment, in diff order (which is itself document order, since
+ * the diff walks the document). A list with no diff comments sorts exactly as
+ * before.
+ */
+const sortAnnotationsInDocumentOrder = (annotations: any[], blocks: Block[] | undefined): any[] => {
+  const order = new Map<string, number>();
+  blocks?.forEach((blk, index) => order.set(blk.id, index));
+  return [...annotations].sort((a, b) => {
+    const diffA = diffBlockIndex(a);
+    const diffB = diffBlockIndex(b);
+    if (diffA !== null || diffB !== null) {
+      if (diffA === null) return -1;
+      if (diffB === null) return 1;
+      if (diffA !== diffB) return diffA - diffB;
+      return a.startOffset - b.startOffset;
+    }
+    if (a.blockId !== b.blockId) {
+      // Two ids missing from `blocks` share position -1; fall through to the
+      // offset so the main document keeps its pre-#1696 order.
+      const byBlock = blocks
+        ? (order.get(a.blockId) ?? -1) - (order.get(b.blockId) ?? -1)
+        : String(a.blockId ?? '').localeCompare(String(b.blockId ?? ''), undefined, { numeric: true });
+      if (byBlock) return byBlock;
+    }
     return a.startOffset - b.startOffset;
   });
+};
 
-  // One injection per export: a human-only skill referenced by several
-  // comments has its instructions injected once (see skillReferenceExportBlock).
-  const injectedSkills = new Set<string>();
-
-  let output = `# ${title}\n\n`;
-
-  if (opts.sourceConverted) {
-    output += `> Note: Line numbers below refer to the converted markdown, not the original HTML/URL source.\n\n`;
-  }
-
-  output += answersSection;
-
-  // Add global reference images section if any
-  if (globalAttachments.length > 0) {
-    output += `## Reference Images\n`;
-    output += `Please review these reference images (use the Read tool to view):\n`;
-    globalAttachments.forEach((img, idx) => {
-      output += `${idx + 1}. [${img.name}] \`${img.path}\`\n`;
-    });
-    output += `\n`;
+/** `Label Summary` heading (at `level`) tallying quick labels, or '' when none. */
+const labelSummaryBlock = (sortedAnns: any[], level: number): string => {
+  const labeledAnns = sortedAnns.filter((a: any) => a.isQuickLabel && a.text);
+  if (labeledAnns.length === 0) return '';
+  const grouped = new Map<string, number>();
+  labeledAnns.forEach((a: any) => {
+    grouped.set(a.text, (grouped.get(a.text) || 0) + 1);
+  });
+  let output = `${'#'.repeat(level)} Label Summary\n\n`;
+  for (const [text, count] of grouped) {
+    output += `- **${text}**: ${count}\n`;
   }
+  output += '\n';
+  return output;
+};
 
-  if (annotations.length > 0) {
-    output += `I've reviewed this ${subject} and have ${annotations.length} piece${annotations.length > 1 ? 's' : ''} of feedback:\n\n`;
-  }
+/**
+ * The numbered feedback entries of ONE document, shared by the root export
+ * (`exportAnnotations`, entries at `##`) and every linked/folder document
+ * (`exportLinkedDocAnnotations`, entries at `###` under the file heading), so
+ * a document's comments read the same whichever section carries them: line
+ * labels, `[In diff content]`, quick labels with their tip, element context,
+ * skill references, images, and threaded replies.
+ */
+const renderAnnotationEntries = (
+  sortedAnns: any[],
+  blocks: Block[] | undefined,
+  opts: { subject: string; level: number; injectedSkills: Set<string> },
+): string => {
+  const { subject, injectedSkills } = opts;
+  const hashes = (n: number) => '#'.repeat(n);
+  let output = '';
 
   // Live app sessions stamp annotations with the page they were made on.
   // When any exported annotation carries a pageUrl, entries are grouped under
@@ -1036,7 +1143,7 @@ export const exportAnnotations = (
   // number of its position in the ungrouped order, matching the on-page
   // marker numbering, so grouped sections may show non-contiguous numbers.
   // With no pageUrl anywhere the output is byte-identical to the ungrouped
-  // export (`## N.` entries, no page headers).
+  // export (entries at `level`, no page headers).
   const hasPageGroups = sortedAnns.some(
     (a: any) => typeof a.pageUrl === 'string' && a.pageUrl.length > 0,
   );
@@ -1117,16 +1224,16 @@ export const exportAnnotations = (
   let lastEmittedPage: string | null = null;
   emitOrder.forEach((ann) => {
     if (hasPageGroups && ann.pageUrl && ann.pageUrl !== lastEmittedPage) {
-      output += `## Page: ${ann.pageUrl}\n\n`;
+      output += `${hashes(opts.level)} Page: ${ann.pageUrl}\n\n`;
       lastEmittedPage = ann.pageUrl;
     }
-    output += `${hasPageGroups ? '###' : '##'} ${annotationNumbers.get(ann)}. `;
+    output += `${hashes(hasPageGroups ? opts.level + 1 : opts.level)} ${annotationNumbers.get(ann)}. `;
 
     // Add diff context label if annotation was created in diff view
     if (ann.diffContext) {
       output += `[In diff content] `;
     } else {
-      const lineLabel = lineLabelForAnnotation(blocks, ann);
+      const lineLabel = blocks ? lineLabelForAnnotation(blocks, ann) : null;
       if (lineLabel) output += `(${lineLabel}) `;
     }
 
@@ -1188,23 +1295,62 @@ export const exportAnnotations = (
     output += '\n';
   });
 
-  output += `---\n`;
+  return output;
+};
 
-  // Quick Label Summary
-  const labeledAnns = sortedAnns.filter((a: any) => a.isQuickLabel && a.text);
-  if (labeledAnns.length > 0) {
-    const grouped = new Map<string, number>();
-    labeledAnns.forEach((a: any) => {
-      grouped.set(a.text, (grouped.get(a.text) || 0) + 1);
+export const exportAnnotations = (
+  blocks: Block[],
+  allAnnotations: any[],
+  globalAttachments: ImageAttachment[] = [],
+  title: string = 'Plan Feedback',
+  subject: string = 'plan',
+  opts: ExportAnnotationsOptions = {},
+): string => {
+  // Answers to `:::question` blocks are printed first, in their own section,
+  // and never counted as numbered feedback.
+  const { answers, annotations } = splitQuestionAnswers(allAnnotations);
+  const answersSection = answers.length > 0
+    ? formatQuestionAnswersSection(questionExportItems(indexQuestionBlocks(blocks)), answers, { headingLevel: 2 })
+    : '';
+  if (annotations.length === 0 && globalAttachments.length === 0 && !answersSection) {
+    return 'No changes detected.';
+  }
+
+  const sortedAnns = sortAnnotationsInDocumentOrder(annotations, blocks);
+
+  // One injection per export: a human-only skill referenced by several
+  // comments has its instructions injected once (see skillReferenceExportBlock).
+  const injectedSkills = new Set<string>();
+
+  let output = `# ${title}\n\n`;
+
+  if (opts.sourceConverted) {
+    output += `> Note: Line numbers below refer to the converted markdown, not the original HTML/URL source.\n\n`;
+  }
+
+  output += answersSection;
+
+  // Add global reference images section if any
+  if (globalAttachments.length > 0) {
+    output += `## Reference Images\n`;
+    output += `Please review these reference images (use the Read tool to view):\n`;
+    globalAttachments.forEach((img, idx) => {
+      output += `${idx + 1}. [${img.name}] \`${img.path}\`\n`;
     });
+    output += `\n`;
+  }
 
-    output += `\n## Label Summary\n\n`;
-    for (const [text, count] of grouped) {
-      output += `- **${text}**: ${count}\n`;
-    }
-    output += '\n';
+  if (annotations.length > 0) {
+    output += `I've reviewed this ${subject} and have ${annotations.length} piece${annotations.length > 1 ? 's' : ''} of feedback:\n\n`;
   }
 
+  output += renderAnnotationEntries(sortedAnns, blocks, { subject, level: 2, injectedSkills });
+
+  output += `---\n`;
+
+  const summary = labelSummaryBlock(sortedAnns, 2);
+  if (summary) output += `\n${summary}`;
+
   return output;
 };
 
@@ -1216,10 +1362,33 @@ export interface LinkedDocAnnotationEntry {
   isConverted?: boolean;
 }
 
+/** Section heading for exportLinkedDocAnnotations. The default describes
+ *  documents a plan links to; a folder session's documents are not that. */
+export interface LinkedDocExportHeading {
+  title: string;
+  intro: string;
+}
+
+export const LINKED_DOC_EXPORT_HEADING: LinkedDocExportHeading = {
+  title: 'Linked Document Feedback',
+  intro: 'The following feedback is on documents referenced in the plan.',
+};
+
+export const FOLDER_DOC_EXPORT_HEADING: LinkedDocExportHeading = {
+  title: 'Folder Document Feedback',
+  intro: 'The following feedback is on files in the reviewed folder, grouped by file.',
+};
+
+export const BUNDLE_DOC_EXPORT_HEADING: LinkedDocExportHeading = {
+  title: 'File Feedback',
+  intro: 'The following feedback is on the files under review, one section per file, in the order they were given for review.',
+};
+
 export const exportLinkedDocAnnotations = (
-  docAnnotations: Map<string, LinkedDocAnnotationEntry>
+  docAnnotations: Map<string, LinkedDocAnnotationEntry>,
+  heading: LinkedDocExportHeading = LINKED_DOC_EXPORT_HEADING,
 ): string => {
-  let output = `\n# Linked Document Feedback\n\nThe following feedback is on documents referenced in the plan.\n\n`;
+  let output = `\n# ${heading.title}\n\n${heading.intro}\n\n`;
 
   // One injection per export, across all linked documents.
   const injectedSkills = new Set<string>();
@@ -1247,57 +1416,14 @@ export const exportLinkedDocAnnotations = (
       output += `\n`;
     }
 
-    // Sort annotations by block and offset
-    const sortedAnns = [...annotations].sort((a, b) => {
-      if (a.blockId !== b.blockId) return a.blockId.localeCompare(b.blockId);
-      return a.startOffset - b.startOffset;
-    });
+    const sortedAnns = sortAnnotationsInDocumentOrder(annotations, docBlocks);
 
     if (annotations.length > 0 || answers.length === 0) {
       output += `I've reviewed this document and have ${annotations.length} piece${annotations.length !== 1 ? 's' : ''} of feedback:\n\n`;
     }
 
-    sortedAnns.forEach((ann, index) => {
-      output += `### ${index + 1}. `;
-
-      const lineLabel = docBlocks ? lineLabelForAnnotation(docBlocks, ann) : null;
-      if (lineLabel) output += `(${lineLabel}) `;
-
-      switch (ann.type) {
-        case 'DELETION':
-          output += `Remove this\n`;
-          output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`;
-          output += `> I don't want this in the document.\n`;
-          break;
-
-        case 'COMMENT':
-          output += `${commentHeadingLine(ann)}\n`;
-          output += diagramLocationExportLine(ann);
-          output += `> ${ann.text}\n`;
-          break;
-
-        case 'GLOBAL_COMMENT':
-          output += `General feedback about the document\n`;
-          output += `> ${ann.text}\n`;
-          break;
-      }
-
-      output += elementContextExportBlock(ann, { includeRoute: false });
-      // Multi-target raw-HTML comments list every additional covered element.
-      output += additionalTargetsExportBlock(ann);
-
-      // External (tool-sourced) comments list skills but never inject.
-      output += skillReferenceExportBlock(ann.text, injectedSkills, { external: !!ann.source });
-
-      if (ann.images && ann.images.length > 0) {
-        output += `**Attached images:**\n`;
-        ann.images.forEach((img: ImageAttachment) => {
-          output += `- [${img.name}] \`${img.path}\`\n`;
-        });
-      }
-
-      output += '\n';
-    });
+    output += renderAnnotationEntries(sortedAnns, docBlocks, { subject: 'document', level: 3, injectedSkills });
+    output += labelSummaryBlock(sortedAnns, 3);
   }
 
   output += `---\n`;

package/utils/questionAnswers.ts

@@ -8,6 +8,7 @@
  */
 import {
   buildQuestionAnswerAnnotation,
+  canonicalQuestionAnswer,
   indexQuestionBlocks,
   isQuestionAnswerEmpty,
   isQuestionAnswered,
@@ -144,7 +145,8 @@ export const buildQuestionPanelRows = (
   const seen = new Set<string>();
   for (const { blockId, number, line, question } of index) {
     seen.add(question.key);
-    const answer = answers.get(question.key);
+    const stored = answers.get(question.key);
+    const answer = stored && canonicalQuestionAnswer(question, stored);
     const status = questionStatus(question, answer);
     const settledLabels = question.choices.filter((c) => c.settled).map((c) => oneLine(c.label));
     const answerText = status === 'answered' && answer

package/utils/quickLabels.ts

@@ -32,8 +32,8 @@ export const LABEL_COLOR_MAP: Record<string, { bg: string; text: string; darkTex
 };
 
 /**
- * The hardcoded one-click positive label behind the toolbar's 👍 button and
- * the composer's "Looks good" action. Deliberately NOT part of the
+ * The hardcoded one-click positive label behind the 👍 "Looks good" buttons
+ * (the selection toolbar's and the HTML pinpoint composer's). Deliberately NOT part of the
  * configurable set: it is the ONLY label comment-only surfaces (HTML /
  * live-app) may emit — their restricted handlers filter on this id.
  */