@plannotator/ui 0.49.0 → 0.51.0

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.
  */

package/utils/syntaxTheme.ts

@@ -73,11 +73,44 @@ export function resolveSyntaxTheme(colorTheme: string, mode: 'dark' | 'light'):
   return { dark: map.dark || DEFAULT_SYNTAX_THEME.dark, light: map.light || DEFAULT_SYNTAX_THEME.light };
 }
 
+/**
+ * Host override for the fence theme (`configurePlannotatorUI({ fenceTheme })`).
+ * Return a Shiki theme name to use it, or `undefined` to fall through to the
+ * default resolution below. A name Shiki does not know renders the block as
+ * plain text, exactly like an unknown fence language.
+ */
+export type FenceThemeResolver = (colorTheme: string, mode: 'light' | 'dark') => string | undefined;
+
+let fenceThemeResolver: FenceThemeResolver | null = null;
+
+/** Install (or with `null`, remove) the host's fence theme override. */
+export function setFenceThemeResolver(resolver: FenceThemeResolver | null): void {
+  fenceThemeResolver = resolver;
+}
+
+export function resetFenceThemeResolver(): void {
+  fenceThemeResolver = null;
+}
+
 /**
  * The single concrete Shiki theme name for the palette currently on screen.
  * Markdown fences render one mode at a time, so unlike the diff pane (which
  * hands Pierre a dark/light pair and lets CSS pick) they want a resolved name.
+ *
+ * Every fence-style consumer resolves through here (`useFenceTheme`: Viewer
+ * fences, `CodeBlock`, the code-file hover preview, the plan diff view, code
+ * review's suggestion snippets), so a host override applies to all of them.
+ * The diff pane's dark/light pair (`resolveSyntaxTheme`) is not affected.
  */
 export function resolveFenceTheme(colorTheme: string, mode: 'dark' | 'light'): string {
+  if (fenceThemeResolver) {
+    let override: string | undefined;
+    try {
+      override = fenceThemeResolver(colorTheme, mode);
+    } catch {
+      override = undefined; // a throwing host resolver must not break rendering
+    }
+    if (typeof override === 'string' && override) return override;
+  }
   return resolveSyntaxTheme(colorTheme, mode)?.[mode] ?? DEFAULT_SYNTAX_THEME[mode];
 }