@plannotator/ui 0.52.1 → 0.53.1

package/utils/pasteInsert.ts

@@ -0,0 +1,234 @@
+/**
+ * Plain-text paste into our own text fields, inserted by the page.
+ *
+ * Works around a Chrome 155 to 156 bug on macOS, and runs only there
+ * (`chromiumPasteBugAffected`). Remove after Chrome 157 is the stable channel
+ * (it ships the fix).
+ *
+ * Chrome 155 added a check after the `paste` event (Chromium CL 8217390,
+ * commit 4f9d868279, "Ensure default paste behavior doesn't leak changed
+ * clipboard content"): the browser's own insertion is skipped when the
+ * clipboard's sequence token changed while the event ran. On macOS an older
+ * race in ClipboardMac can give the same NSPasteboard changeCount a second
+ * token when a paste starts right after an app wrote the pasteboard and
+ * posted a synthetic ⌘V. Dictation apps (Hex) and text expanders do exactly
+ * that. The `paste` event still carries the right `text/plain`, but
+ * `beforeinput` arrives with empty data and nothing is inserted: the first
+ * dictation after a page load lands, later ones vanish. Fixed in Chromium
+ * main (CL 8503629, commit fc5529f522, crbug 568453825), not before 157.
+ *
+ * So, for a paste into a plain-text field we own (a textarea or a text-like
+ * input) that nothing else handled, that carries no files and has text, the
+ * page cancels the browser's insertion and inserts the text itself with
+ * `execCommand('insertText')` (keeps undo, fires `input`, so React's onChange
+ * runs), else `setRangeText` plus an `input` event. That is what the browser
+ * would have done. It is gated to the affected engine: Safari's execCommand
+ * merges the insertion with the typing before it in the undo stack, so
+ * everywhere else the browser's own paste is kept. Only trusted (real) paste
+ * events are acted on.
+ *
+ * Left native: a paste that a handler already cancelled (image paste to
+ * attach), one that carries files (paste-to-attach keeps working; the
+ * browser inserts the text beside them), an empty one, a field that is
+ * read-only or disabled, one that is not focused, one mid IME composition,
+ * contenteditable and code editors (CodeMirror, Pierre's editor, the agent
+ * terminal's helper textarea), and a field marked `data-native-paste`.
+ */
+
+/** Input types the page can insert into with a caret (email and number have no selection API). */
+const TEXT_INPUT_TYPES = new Set(['text', 'search', 'url', 'tel', 'password']);
+
+/** Editors that read the paste themselves through a hidden textarea or own their own model. */
+const NATIVE_PASTE = '[data-native-paste], .xterm, .cm-editor, .monaco-editor';
+
+export type PlainTextField = HTMLTextAreaElement | HTMLInputElement;
+
+export interface PasteInsertion {
+  field: PlainTextField;
+  text: string;
+  start: number;
+  end: number;
+}
+
+type PasteLike = Pick<ClipboardEvent, 'defaultPrevented' | 'clipboardData' | 'target'> & {
+  composedPath?: () => EventTarget[];
+};
+
+function plainTextField(target: EventTarget | null | undefined): PlainTextField | null {
+  if (!target || typeof (target as Node).nodeType !== 'number') return null;
+  const el = target as Element;
+  const view = el.ownerDocument?.defaultView;
+  if (!view) return null;
+  if (el instanceof view.HTMLTextAreaElement) return el;
+  if (el instanceof view.HTMLInputElement && TEXT_INPUT_TYPES.has(el.type)) return el;
+  return null;
+}
+
+function carriesFiles(data: DataTransfer): boolean {
+  if ((data.files?.length ?? 0) > 0) return true;
+  for (const item of Array.from(data.items ?? [])) {
+    if (item.kind === 'file') return true;
+  }
+  return false;
+}
+
+function focused(field: PlainTextField): boolean {
+  const root = field.getRootNode() as Document | ShadowRoot;
+  return 'activeElement' in root && root.activeElement === field;
+}
+
+/** Cut to `room` UTF-16 units without splitting a surrogate pair. */
+function truncate(text: string, room: number): string {
+  if (text.length <= room) return text;
+  let cut = room;
+  const last = text.charCodeAt(cut - 1);
+  if (cut > 0 && last >= 0xd800 && last <= 0xdbff) cut -= 1;
+  return text.slice(0, cut);
+}
+
+/**
+ * What the page should insert for this paste, or null to leave it to the
+ * browser. Pure apart from reading the event and the field.
+ */
+export function plainTextPasteInsertion(event: PasteLike, composing = false): PasteInsertion | null {
+  if (event.defaultPrevented || composing) return null;
+  const data = event.clipboardData;
+  if (!data) return null;
+  const path = event.composedPath?.() ?? [];
+  const field = plainTextField(path[0] ?? event.target);
+  if (!field) return null;
+  if (field.readOnly || field.disabled) return null;
+  if (field.closest(NATIVE_PASTE)) return null;
+  if (!focused(field)) return null;
+  if (carriesFiles(data)) return null;
+  let text = data.getData('text/plain');
+  if (!text) return null;
+  // What Chrome does with line breaks: a textarea keeps each as \n, a one-line input turns each into a space.
+  text = text.replace(/\r\n?/g, '\n');
+  if (field.tagName !== 'TEXTAREA') text = text.replace(/\n/g, ' ');
+  if (!text) return null;
+  const start = field.selectionStart;
+  const end = field.selectionEnd;
+  if (start === null || end === null) return null;
+  if (field.maxLength >= 0) {
+    const room = field.maxLength - (field.value.length - (end - start));
+    if (room <= 0) return null; // the browser inserts nothing either
+    text = truncate(text, room);
+    if (!text) return null;
+  }
+  return { field, text, start, end };
+}
+
+/** Insert as typing would: an undo step and an `input` event. */
+export function insertPastedText({ field, text, start, end }: PasteInsertion): void {
+  const doc = field.ownerDocument;
+  let inserted = false;
+  try {
+    inserted = typeof doc.execCommand === 'function' && doc.execCommand('insertText', false, text) === true;
+  } catch {
+    inserted = false;
+  }
+  if (inserted) return;
+  field.setRangeText(text, start, end, 'end');
+  const caret = start + text.length;
+  field.setSelectionRange(caret, caret); // some engines put the caret elsewhere after setRangeText
+  const view = doc.defaultView;
+  const event =
+    view && typeof view.InputEvent === 'function'
+      ? new view.InputEvent('input', { bubbles: true, inputType: 'insertFromPaste', data: text })
+      : new Event('input', { bubbles: true });
+  field.dispatchEvent(event);
+}
+
+/** What the gate reads off `navigator` (User-Agent Client Hints are Chromium-only). */
+export interface PasteEngineNavigator {
+  userAgent?: string;
+  platform?: string;
+  userAgentData?: { brands?: ReadonlyArray<{ brand: string; version: string }>; platform?: string } | null;
+}
+
+/** The Chromium majors with the bug: 155 added the check, 157 ships the fix. */
+const AFFECTED_CHROMIUM = new Set([155, 156]);
+
+/**
+ * Only Chromium 155 and 156 on macOS have the bug, so only they get the
+ * workaround: it turns itself off when 157 arrives, and Safari, Firefox and
+ * older Chromium (VS Code's webview) keep the browser's own paste. Safari
+ * matters most: there `execCommand('insertText')` merges with the typing
+ * before it, so one ⌘Z after a paste would also erase what was typed.
+ * Chrome, Edge, Brave, Arc and other Chromium browsers are told by the
+ * "Chromium" brand of User-Agent Client Hints, else by `Chrome/<major>` in
+ * the UA string (Safari and Firefox carry no `Chrome/`; Chrome on iOS is
+ * WebKit and says `CriOS/`).
+ */
+export function chromiumPasteBugAffected(nav: PasteEngineNavigator | undefined | null): boolean {
+  if (!nav) return false;
+  const ua = nav.userAgent ?? '';
+  const data = nav.userAgentData ?? null;
+  let major = Number.NaN;
+  const brand = data?.brands?.find((b) => b.brand === 'Chromium');
+  if (brand) major = Number.parseInt(brand.version, 10);
+  if (Number.isNaN(major)) {
+    const match = /Chrome\/(\d+)/.exec(ua);
+    if (match) major = Number.parseInt(match[1]!, 10);
+  }
+  if (!AFFECTED_CHROMIUM.has(major)) return false;
+  // Client hints name the platform when present; else navigator.platform or the UA string.
+  if (data?.platform) return /^mac/i.test(data.platform);
+  return /^mac/i.test(nav.platform ?? '') || /Macintosh|Mac OS X/.test(ua);
+}
+
+/**
+ * Tests (the e2e simulation, in a Chromium that is not 155 or 156) set this
+ * to `true` on the window to turn the workaround on whatever the engine.
+ */
+export const FORCE_PLAIN_TEXT_PASTE_FLAG = '__plannotatorForcePlainTextPaste';
+
+export interface PlainTextPasteOptions {
+  /** Whether the workaround runs. Default: the engine gate, or the window's force flag. */
+  enabled?: boolean;
+  /** Act on script-dispatched (untrusted) paste events too; for tests. Default false. */
+  allowUntrusted?: boolean;
+}
+
+/**
+ * Install on a window; returns the uninstall. Listens in the bubble phase on
+ * the window, so every handler on the page (React's, the image-paste ones)
+ * runs first and can claim the paste. Does nothing outside the affected
+ * engine (`chromiumPasteBugAffected`).
+ */
+export function installPlainTextPaste(win: Window = window, options: PlainTextPasteOptions = {}): () => void {
+  const doc = win.document;
+  const engine = chromiumPasteBugAffected(win.navigator as unknown as PasteEngineNavigator);
+  const forced = () => (win as unknown as Record<string, unknown>)[FORCE_PLAIN_TEXT_PASTE_FLAG] === true;
+  const enabled = () => options.enabled ?? (engine || forced());
+  let composing = false;
+  const onCompositionStart = () => {
+    composing = true;
+  };
+  // Also on focus moving and the window losing focus: a compositionend that never arrives must not
+  // leave the workaround off until reload.
+  const onCompositionEnd = () => {
+    composing = false;
+  };
+  const onPaste = (event: ClipboardEvent) => {
+    if (!enabled()) return;
+    if (!event.isTrusted && !options.allowUntrusted) return; // a script's paste event inserts nothing
+    const insertion = plainTextPasteInsertion(event, composing);
+    if (!insertion) return;
+    event.preventDefault();
+    insertPastedText(insertion);
+  };
+  doc.addEventListener('compositionstart', onCompositionStart, true);
+  doc.addEventListener('compositionend', onCompositionEnd, true);
+  doc.addEventListener('focusin', onCompositionEnd, true);
+  win.addEventListener('blur', onCompositionEnd);
+  win.addEventListener('paste', onPaste);
+  return () => {
+    doc.removeEventListener('compositionstart', onCompositionStart, true);
+    doc.removeEventListener('compositionend', onCompositionEnd, true);
+    doc.removeEventListener('focusin', onCompositionEnd, true);
+    win.removeEventListener('blur', onCompositionEnd);
+    win.removeEventListener('paste', onPaste);
+  };
+}

package/utils/planDiffEngine.ts

@@ -43,6 +43,17 @@ export interface PlanDiffBlock {
   inlineTokens?: InlineDiffToken[];
   /** Structural wrap metadata paired with inlineTokens. */
   inlineWrap?: InlineDiffWrap;
+  /**
+   * Source line range of this block in the OLD text: 1-based, inclusive,
+   * trimmed of leading and trailing blank lines. Absent when the block has
+   * no non-blank old line (added blocks, or an all-blank chunk). Filled by
+   * `computePlanDiff`; plan review ignores it.
+   */
+  oldStart?: number;
+  oldEnd?: number;
+  /** Same as `oldStart`/`oldEnd`, in the NEW text (absent on removed blocks). */
+  newStart?: number;
+  newEnd?: number;
 }
 
 export interface PlanDiffStats {
@@ -63,6 +74,35 @@ function countLines(text: string): number {
   return lines.length;
 }
 
+/**
+ * The trimmed line range a chunk occupies when its first line is `start`
+ * (1-based): leading and trailing blank lines are not counted. Empty when the
+ * chunk has no non-blank line.
+ */
+function trimmedLineRange(
+  value: string,
+  start: number
+): { start?: number; end?: number } {
+  const lines = value.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  let first = 0;
+  while (first < lines.length && lines[first].trim() === "") first++;
+  if (first >= lines.length) return {};
+  let last = lines.length - 1;
+  while (last > first && lines[last].trim() === "") last--;
+  return { start: start + first, end: start + last };
+}
+
+function oldRange(value: string, start: number): Pick<PlanDiffBlock, "oldStart" | "oldEnd"> {
+  const r = trimmedLineRange(value, start);
+  return r.start === undefined ? {} : { oldStart: r.start, oldEnd: r.end };
+}
+
+function newRange(value: string, start: number): Pick<PlanDiffBlock, "newStart" | "newEnd"> {
+  const r = trimmedLineRange(value, start);
+  return r.start === undefined ? {} : { newStart: r.start, newEnd: r.end };
+}
+
 const INLINE_DIFFABLE_TYPES = new Set<Block["type"]>([
   "paragraph",
   "heading",
@@ -213,6 +253,34 @@ function substituteFencedBlocks(
   });
 }
 
+// A quote (a run of `>` lines) that holds a code fence is one block in the
+// rendered plan, and each diff chunk renders as its own quote. Diffed line
+// by line, an edit inside the quoted fence split it into chunks holding half
+// a fence each, so one chunk opened a fence it never closed and rendered the
+// prose after it as code. The whole run is therefore one atomic unit, like
+// an unquoted fence. Quotes without a fence keep line-level diffing. Runs
+// after substituteFencedBlocks, so a `>` line inside an unquoted fence is
+// already behind its sentinel and never starts a run.
+const QUOTE_RUN_PATTERN = /^[ \t]*>[^\n]*(?:\n[ \t]*>[^\n]*)*/gm;
+const QUOTED_FENCE_LINE = /^[ \t]*(?:>[ \t]?)+[ \t]*`{3,}/m;
+
+function substituteQuotedFenceRuns(
+  text: string,
+  fenceMap: Map<string, string>,
+  fenceToId: Map<string, number>
+): string {
+  return text.replace(QUOTE_RUN_PATTERN, (match) => {
+    if (!QUOTED_FENCE_LINE.test(match)) return match;
+    let id = fenceToId.get(match);
+    if (id === undefined) {
+      id = fenceToId.size;
+      fenceMap.set(fenceSentinelFor(id), match);
+      fenceToId.set(match, id);
+    }
+    return fenceSentinelFor(id);
+  });
+}
+
 function restoreFencedBlocks(
   value: string,
   fenceMap: Map<string, string>
@@ -530,8 +598,16 @@ export function computePlanDiff(
   // FENCE_BLOCK_PATTERN for the failure this prevents.
   const fenceMap = new Map<string, string>();
   const fenceToId = new Map<string, number>();
-  const substOld = substituteFencedBlocks(oldText, fenceMap, fenceToId);
-  const substNew = substituteFencedBlocks(newText, fenceMap, fenceToId);
+  const substOld = substituteQuotedFenceRuns(
+    substituteFencedBlocks(oldText, fenceMap, fenceToId),
+    fenceMap,
+    fenceToId,
+  );
+  const substNew = substituteQuotedFenceRuns(
+    substituteFencedBlocks(newText, fenceMap, fenceToId),
+    fenceMap,
+    fenceToId,
+  );
 
   const rawChanges: Change[] = diffLines(substOld, substNew);
   // Restore the fenced-block content on each change value before the
@@ -544,6 +620,10 @@ export function computePlanDiff(
 
   const blocks: PlanDiffBlock[] = [];
   const stats: PlanDiffStats = { additions: 0, deletions: 0, modifications: 0 };
+  // First line (1-based) of the next chunk on each side; the restored chunk
+  // values hold the real source lines, so counting them keeps both in step.
+  let oldLine = 1;
+  let newLine = 1;
 
   for (let i = 0; i < changes.length; i++) {
     const change = changes[i];
@@ -558,7 +638,11 @@ export function computePlanDiff(
         oldContent: change.value,
         lines: countLines(next.value),
         ...(inline ? { inlineTokens: inline.tokens, inlineWrap: inline.wrap } : {}),
+        ...oldRange(change.value, oldLine),
+        ...newRange(next.value, newLine),
       });
+      oldLine += countLines(change.value);
+      newLine += countLines(next.value);
       stats.modifications++;
       stats.additions += countLines(next.value);
       stats.deletions += countLines(change.value);
@@ -568,23 +652,209 @@ export function computePlanDiff(
         type: "added",
         content: change.value,
         lines: countLines(change.value),
+        ...newRange(change.value, newLine),
       });
+      newLine += countLines(change.value);
       stats.additions += countLines(change.value);
     } else if (change.removed) {
       blocks.push({
         type: "removed",
         content: change.value,
         lines: countLines(change.value),
+        ...oldRange(change.value, oldLine),
       });
+      oldLine += countLines(change.value);
       stats.deletions += countLines(change.value);
     } else {
       blocks.push({
         type: "unchanged",
         content: change.value,
         lines: countLines(change.value),
+        ...oldRange(change.value, oldLine),
+        ...newRange(change.value, newLine),
       });
+      oldLine += countLines(change.value);
+      newLine += countLines(change.value);
     }
   }
 
   return { blocks, stats };
 }
+
+// --- Folding unchanged runs (code review's rendered Markdown diff) ---------
+
+/** A run of unchanged sections hidden behind one row. */
+export interface PlanDiffFold {
+  kind: "fold";
+  /** Stable for the same diff: `fold-<block index>-<first hidden piece>`. */
+  key: string;
+  /** The hidden sections, each an 'unchanged' block with its own ranges. */
+  pieces: PlanDiffBlock[];
+  /** How many sections are hidden (`pieces.length`). */
+  sectionCount: number;
+  /** Plain text of the hidden headings, at most three. */
+  headings: string[];
+  oldStart?: number;
+  oldEnd?: number;
+  newStart?: number;
+  newEnd?: number;
+}
+
+export type PlanDiffSegment =
+  | { kind: "block"; block: PlanDiffBlock; index: number }
+  | PlanDiffFold;
+
+const MAX_FOLD_HEADINGS = 3;
+
+/** Heading text without inline markdown markers. */
+function plainHeadingText(text: string): string {
+  return text
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+interface UnchangedPiece {
+  piece: PlanDiffBlock;
+  heading?: string;
+}
+
+/**
+ * Split an unchanged chunk into one piece per markdown block: each piece is
+ * the exact source text from its block's first line up to the next block's
+ * (blank lines stay with the piece before them; anything before the first
+ * block, such as frontmatter, stays with the first piece). Concatenating the
+ * pieces gives the chunk back byte for byte.
+ */
+function splitUnchangedChunk(block: PlanDiffBlock): UnchangedPiece[] {
+  const content = block.content;
+  const parsed = parseMarkdownToBlocks(content);
+  if (parsed.length <= 1) {
+    const only = parsed[0];
+    return [only?.type === "heading" ? { piece: block, heading: plainHeadingText(only.content) } : { piece: block }];
+  }
+
+  // Character offset of the start of each 1-based line.
+  const lineOffsets: number[] = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") lineOffsets.push(i + 1);
+  }
+  const lineCount = countLines(content);
+  const starts = Array.from(
+    new Set(parsed.map((b) => b.startLine).filter((line) => line >= 1 && line <= lineCount))
+  ).sort((a, b) => a - b);
+  if (starts.length === 0) return [{ piece: block }];
+  starts[0] = 1;
+
+  // The chunk's untrimmed first line on each side (its ranges are trimmed).
+  const contentLines = content.split("\n");
+  let leadingBlank = 0;
+  while (leadingBlank < contentLines.length && contentLines[leadingBlank].trim() === "") leadingBlank++;
+  const oldBase = block.oldStart !== undefined ? block.oldStart - leadingBlank : undefined;
+  const newBase = block.newStart !== undefined ? block.newStart - leadingBlank : undefined;
+
+  const headingByStart = new Map<number, string>();
+  for (const b of parsed) {
+    if (b.type === "heading" && !headingByStart.has(b.startLine)) {
+      headingByStart.set(b.startLine, plainHeadingText(b.content));
+    }
+  }
+
+  return starts.map((startLine, i) => {
+    const nextStart = starts[i + 1];
+    const from = lineOffsets[startLine - 1] ?? content.length;
+    const to = nextStart !== undefined ? lineOffsets[nextStart - 1] ?? content.length : content.length;
+    const pieceContent = content.slice(from, to);
+    const piece: PlanDiffBlock = {
+      type: "unchanged",
+      content: pieceContent,
+      lines: countLines(pieceContent),
+      ...(oldBase !== undefined ? oldRange(pieceContent, oldBase + startLine - 1) : {}),
+      ...(newBase !== undefined ? newRange(pieceContent, newBase + startLine - 1) : {}),
+    };
+    // A heading piece begins at the heading itself (i > 0), or the first
+    // piece's parsed block is the heading.
+    const heading = headingByStart.get(i === 0 ? parsed[0].startLine : startLine);
+    return heading !== undefined ? { piece, heading } : { piece };
+  });
+}
+
+/** The span of several pieces' ranges on each side. */
+function spanOf(pieces: PlanDiffBlock[]): Pick<PlanDiffBlock, "oldStart" | "oldEnd" | "newStart" | "newEnd"> {
+  const withOld = pieces.filter((p) => p.oldStart !== undefined);
+  const withNew = pieces.filter((p) => p.newStart !== undefined);
+  return {
+    ...(withOld.length > 0
+      ? { oldStart: withOld[0].oldStart, oldEnd: withOld[withOld.length - 1].oldEnd }
+      : {}),
+    ...(withNew.length > 0
+      ? { newStart: withNew[0].newStart, newEnd: withNew[withNew.length - 1].newEnd }
+      : {}),
+  };
+}
+
+/** Consecutive pieces as one unchanged block (kept together so list numbering stays continuous). */
+function joinPieces(pieces: PlanDiffBlock[]): PlanDiffBlock {
+  if (pieces.length === 1) return pieces[0];
+  const content = pieces.map((p) => p.content).join("");
+  return { type: "unchanged", content, lines: countLines(content), ...spanOf(pieces) };
+}
+
+/**
+ * Fold long runs of unchanged sections behind one row, the way a code diff
+ * folds unmodified lines. Changed blocks pass through. Each unchanged block
+ * keeps `context` sections next to each neighbouring change visible (none
+ * toward the start or end of the document) and folds the rest when at least
+ * `minHidden` would be hidden; otherwise it is shown whole, untouched.
+ *
+ * Pure: the same blocks always give the same segments and fold keys.
+ */
+export function foldUnchangedPlanDiff(
+  blocks: PlanDiffBlock[],
+  options: { context?: number; minHidden?: number } = {}
+): PlanDiffSegment[] {
+  const context = Math.max(0, options.context ?? 1);
+  const minHidden = Math.max(1, options.minHidden ?? 2);
+  const segments: PlanDiffSegment[] = [];
+
+  blocks.forEach((block, index) => {
+    if (block.type !== "unchanged") {
+      segments.push({ kind: "block", block, index });
+      return;
+    }
+    const pieces = splitUnchangedChunk(block);
+    const head = index > 0 ? Math.min(context, pieces.length) : 0;
+    const tail = index < blocks.length - 1 ? Math.min(context, pieces.length - head) : 0;
+    const hidden = pieces.length - head - tail;
+    if (hidden < minHidden) {
+      segments.push({ kind: "block", block, index });
+      return;
+    }
+    if (head > 0) {
+      segments.push({ kind: "block", block: joinPieces(pieces.slice(0, head).map((p) => p.piece)), index });
+    }
+    const folded = pieces.slice(head, head + hidden);
+    const foldPieces = folded.map((p) => p.piece);
+    segments.push({
+      kind: "fold",
+      key: `fold-${index}-${head}`,
+      pieces: foldPieces,
+      sectionCount: foldPieces.length,
+      headings: folded
+        .map((p) => p.heading)
+        .filter((h): h is string => !!h)
+        .slice(0, MAX_FOLD_HEADINGS),
+      ...spanOf(foldPieces),
+    });
+    if (tail > 0) {
+      segments.push({
+        kind: "block",
+        block: joinPieces(pieces.slice(head + hidden).map((p) => p.piece)),
+        index,
+      });
+    }
+  });
+
+  return segments;
+}

package/utils/skillCatalog.ts

@@ -81,6 +81,18 @@ async function requestCatalog(): Promise<SkillCatalogEntry[]> {
   }
 }
 
+// Whether a fetched catalog is registered for the per-comment feedback export
+// (skillReferenceExportBlock). Default on: Plannotator's exporters list each
+// comment's references. A host that composes ONE block per message itself
+// (the Plannotator Inbox) turns it off, so a comment's `$name` stays plain
+// text in its export instead of carrying a second "Skills referenced" list.
+let exportRegistration = true;
+
+export function setSkillCatalogExportRegistration(on: boolean): void {
+  exportRegistration = on;
+  if (!on) setSkillCatalogForExport([]);
+}
+
 let cached: { at: number; skills: SkillCatalogEntry[] } | null = null;
 let inflight: Promise<SkillCatalogEntry[]> | null = null;
 // Bumped by resetSkillCatalogCache. A request that resolves after a reset (or
@@ -111,7 +123,7 @@ export function fetchSkillCatalog(): Promise<SkillCatalogEntry[]> {
     } else {
       cached = { at: Date.now(), skills: cached.skills };
     }
-    setSkillCatalogForExport(cached.skills);
+    if (exportRegistration) setSkillCatalogForExport(cached.skills);
     return cached.skills;
   });
   inflight = promise;
@@ -176,7 +188,8 @@ export function resetSkillContentTransport(): void {
   contentTransport = defaultContentTransport;
 }
 
-function normalizeSkillContent(raw: unknown): SkillExportContent | null {
+/** A raw `{ content, truncated, dir, path }` record as an export content, or null when any part is missing. */
+export function normalizeSkillContent(raw: unknown): SkillExportContent | null {
   if (!raw || typeof raw !== 'object') return null;
   const { content, truncated, dir, path } = raw as Record<string, unknown>;
   if (typeof content !== 'string' || !content) return null;