@plannotator/ui 0.47.0 → 0.50.0

package/utils/parser.ts

@@ -2,8 +2,32 @@ import type { Block, Annotation, CodeAnnotation, EditorAnnotation, ImageAttachme
 import { planDenyFeedback } from '@plannotator/core/feedback-templates';
 import { resolveReplyParents } from '@plannotator/core/annotation-threads';
 import { diagramAnchorLocationLine, parseDiagramAnchor } from '@plannotator/core/diagram-anchor';
+import {
+  formatQuestionAnswerLines,
+  formatQuestionAnswersSection,
+  indexQuestionBlocks,
+  parseQuestionAnswer,
+  questionExportItems,
+  type QuestionAnswer,
+  type QuestionExportItem,
+} from '@plannotator/core/question-block';
+import {
+  DIRECTIVE_OPEN_RE,
+  HTML_BLOCK_TAGS,
+  codeFenceCloseIndex,
+  directiveCloseIndex,
+  htmlBlockEndAt,
+  resolveReferenceLinks,
+  scanDisplayMath,
+  splitFrontmatter,
+  type TagCloseIndex,
+} from '@plannotator/core/markdown-structure';
 import { skillReferenceExportBlock } from './skillReferences';
 
+// The structural helpers moved to `@plannotator/core/markdown-structure` so
+// `findQuestionBlocks` (core) splits a document exactly as this parser does.
+export { HTML_BLOCK_TAGS, resolveReferenceLinks };
+
 /**
  * Parsed YAML frontmatter value: scalar string, array, or nested map.
  */
@@ -128,30 +152,11 @@ function parseKeyValue(str: string): { key: string; value: string } | null {
  * line references stay accurate).
  */
 export function extractFrontmatter(markdown: string): { frontmatter: Frontmatter | null; content: string; contentStartLine: number } {
-  const trimmed = markdown.trimStart();
-  if (!trimmed.startsWith('---')) {
+  const { raw: frontmatterRaw, content: afterFrontmatter, contentStartLine } = splitFrontmatter(markdown);
+  if (frontmatterRaw === null) {
     return { frontmatter: null, content: markdown, contentStartLine: 1 };
   }
 
-  // Find the closing ---
-  const endIndex = trimmed.indexOf('\n---', 3);
-  if (endIndex === -1) {
-    return { frontmatter: null, content: markdown, contentStartLine: 1 };
-  }
-
-  // Extract frontmatter content (between the --- delimiters)
-  const frontmatterRaw = trimmed.slice(4, endIndex).trim();
-  const rawAfterFrontmatter = trimmed.slice(endIndex + 4);
-  const afterFrontmatter = rawAfterFrontmatter.trimStart();
-
-  // Compute the 1-based line where content begins in the original file.
-  // Account for: leading whitespace trimmed from original, the frontmatter
-  // block itself, and any blank lines between closing --- and first content.
-  const leadingChars = markdown.length - trimmed.length;
-  const consumedInTrimmed = endIndex + 4 + (rawAfterFrontmatter.length - afterFrontmatter.length);
-  const consumedTotal = leadingChars + consumedInTrimmed;
-  const contentStartLine = (markdown.slice(0, consumedTotal).match(/\n/g) || []).length + 1;
-
   // Parse simple YAML (key: value pairs, indentation-aware)
   const frontmatter: Frontmatter = {};
   const mapStack: { indent: number; map: { [key: string]: FrontmatterValue } }[] = [
@@ -280,32 +285,6 @@ export function extractFrontmatter(markdown: string): { frontmatter: Frontmatter
   return { frontmatter, content: afterFrontmatter, contentStartLine };
 }
 
-/**
- * Tag names that trigger a raw HTML block per CommonMark §4.6, Type 6.
- * A line starting with `<tag` or `</tag` (where `tag` is in this set) opens
- * an HTML block that continues verbatim until a blank line or EOF.
- *
- * Inline-only tags (`kbd`, `sub`, `sup`, `mark`, etc.) are NOT here — a line
- * that happens to start with one of those still goes through the paragraph
- * path and renders as escaped text, matching prior behavior.
- */
-export const HTML_BLOCK_TAGS: ReadonlySet<string> = new Set([
-  'details', 'summary',
-  'div', 'section', 'article', 'aside', 'header', 'footer',
-  'blockquote', 'pre',
-  'table', 'thead', 'tbody', 'tr', 'td', 'th',
-  'ul', 'ol', 'li', 'p',
-  // Media: GitHub embeds screenshots/videos as raw HTML on their own line.
-  'img', 'video', 'picture',
-]);
-
-/** Void elements — no closing tag, so the block is a single line (don't scan
- *  ahead for a `</tag>` that will never come). */
-const VOID_HTML_TAGS: ReadonlySet<string> = new Set([
-  'img', 'br', 'hr', 'source', 'input', 'wbr', 'area', 'col', 'embed',
-]);
-
-const HTML_BLOCK_OPEN_RE = /^<\/?([a-zA-Z][a-zA-Z0-9]*)(?:\s|>|\/|$)/;
 
 export interface ParseMarkdownOptions {
   /**
@@ -317,339 +296,6 @@ export interface ParseMarkdownOptions {
   frontmatter?: boolean;
 }
 
-// CommonMark bounds a link label to 999 characters. Reusing that bound here
-// also caps the worst-case backtracking cost of the bracket-matching groups
-// below to a constant per starting position, turning a document with a very
-// long run of unmatched `[` characters (a real hazard within the 2MB annotate
-// cap) into a linear scan instead of a quadratic one. A label longer than
-// this is a deliberate, documented degradation: it is neither collected as a
-// definition nor resolved as a reference, so it is simply left untouched
-// rather than partially or incorrectly rewritten.
-const MAX_REF_LABEL_CHARS = 999;
-// Same reasoning applied to the inline-code-span alternative: bounding how far
-// a lazy scan for a closing backtick run can travel keeps a line with many
-// stray, unterminated backticks linear too. 5000 is far beyond any realistic
-// inline code span, so legitimate spans are unaffected.
-const MAX_CODE_SPAN_CHARS = 5000;
-// Defense-in-depth cap on the number of definitions collected from a single
-// document. A pathological document could otherwise grow the map without
-// bound; this keeps that growth bounded even though ordinary documents never
-// approach it.
-const MAX_TRACKED_DEFINITIONS = 20_000;
-
-// A link reference definition: `[label]: destination "optional title"`, with up
-// to three leading spaces. The destination is a bare token or an <...> form; any
-// trailing text must be a quoted or parenthesized title, otherwise the line is
-// ordinary prose (so `[Reminder]: call the bank` is NOT a definition). Matches
-// the CommonMark shape closely enough for the simplified parser. `\r?` before
-// the end anchor tolerates a CRLF source (lines are split on `\n` only, so a
-// CRLF line keeps its trailing `\r`).
-const REFERENCE_DEFINITION_RE = new RegExp(
-  `^ {0,3}\\[([^\\]]{1,${MAX_REF_LABEL_CHARS}})\\]:[ \\t]*(?:<([^>]*)>|(\\S+))[ \\t]*(?:"[^"]*"|'[^']*'|\\([^)]*\\))?[ \\t]*\\r?$`,
-);
-
-// One left-to-right pass over a line. The first alternative matches a whole
-// inline code span (balanced backtick run) so its contents are skipped; the
-// second matches a reference link/image: optional `!`, the bracketed text, then
-// an optional second bracket for the full (`[label]`) or collapsed (`[]`) forms.
-// A bare `[text]` is the shortcut form, resolved only when it names a definition
-// and is not actually an inline link. Groups: 1 code ticks, 2 `!`, 3 text,
-// 4 second bracket, 5 label.
-const REFERENCE_LINK_RE = new RegExp(
-  `(\`+)[^\\n]{0,${MAX_CODE_SPAN_CHARS}}?\\1|(!?)\\[([^\\]]{1,${MAX_REF_LABEL_CHARS}})\\](\\[([^\\]]{0,${MAX_REF_LABEL_CHARS}})\\])?`,
-  'g',
-);
-
-// CommonMark label matching is case-insensitive and collapses internal runs of
-// whitespace.
-const normalizeRefLabel = (label: string): string =>
-  label.trim().replace(/\s+/g, ' ').toLowerCase();
-
-/**
- * One pass over the lines that marks every line the block parser (below) will
- * render as code or raw HTML — fenced code blocks and HTML blocks — so link
- * reference definitions and references inside them are left completely
- * untouched. This reuses the exact same conditions the block parser itself
- * uses (not a looser approximation), so the two can never disagree about
- * where code/HTML starts and ends:
- *
- * - Fences: `trimmed.startsWith('```')` after a full `.trim()` — the block
- *   parser has no minimum-indent exemption, so ANY indentation (a fence
- *   nested inside a list item, or simply indented 4+ spaces) still opens a
- *   code block, and this must too. Only backtick fences are recognized —
- *   the block parser has no `~~~` support, so this doesn't either (a `~~~`
- *   line is ordinary text to both).
- * - Raw HTML blocks: the same `HTML_BLOCK_OPEN_RE`/`HTML_BLOCK_TAGS`/
- *   `VOID_HTML_TAGS` the block parser uses, with the same three extents
- *   (blank-line termination for a leading close tag, single-line for void
- *   tags, balanced-depth scanning otherwise) — so a definition sitting
- *   inside `<details>…</details>` or `<pre>…</pre>` is protected exactly as
- *   far as the block parser's own HTML block extends.
- */
-/**
- * Per-tag-name index backing `findHtmlBlockEnd`. `augmented` is the running
- * open-tag-count-minus-close-tag-count prefix sum for this tag name, with a
- * virtual baseline of 0 prepended at index 0 — so `augmented[k]` is the sum
- * through line `k-1` (the depth baseline a block opening at line `k` must
- * return to) and `augmented[k+1]` is the sum through line `k`.
- * `nextAtOrBelow[m]` is the classic "next element at or below this one"
- * index over `augmented`: the smallest `m' > m` with `augmented[m'] <=
- * augmented[m]`, or -1 if none exists.
- */
-interface TagCloseIndex {
-  augmented: number[];
-  nextAtOrBelow: number[];
-}
-
-/**
- * Builds a `TagCloseIndex` for one tag name in a single O(N) pass (plus a
- * classic O(N) monotonic-stack pass for `nextAtOrBelow` — each index is
- * pushed and popped at most once, so the two passes together are linear in
- * the document's line count, independent of how many opening/closing tags
- * it contains).
- */
-function buildTagCloseIndex(lines: string[], tagName: string): TagCloseIndex {
-  const openRe = new RegExp(`<${tagName}(?:\\s|>|/|$)`, 'gi');
-  const closeRe = new RegExp(`</${tagName}\\s*>`, 'gi');
-  const n = lines.length;
-  const augmented = new Array<number>(n + 1);
-  augmented[0] = 0;
-  let running = 0;
-  for (let k = 0; k < n; k++) {
-    running += (lines[k].match(openRe) || []).length;
-    running -= (lines[k].match(closeRe) || []).length;
-    augmented[k + 1] = running;
-  }
-  const nextAtOrBelow = new Array<number>(n + 1).fill(-1);
-  const stack: number[] = [];
-  for (let m = n; m >= 0; m--) {
-    while (stack.length && augmented[stack[stack.length - 1]] > augmented[m]) stack.pop();
-    nextAtOrBelow[m] = stack.length ? stack[stack.length - 1] : -1;
-    stack.push(m);
-  }
-  return { augmented, nextAtOrBelow };
-}
-
-/**
- * Shared helper computing the last line index of a balanced open/close-tag
- * HTML block that opens at `startIndex` with the given already-computed
- * `depth` (the opening line's own open-tag count minus close-tag count).
- * Used by both `markProtectedLines` (the resolver's protection pass) and
- * `parseMarkdownToBlocks` (the block parser) so the two can never disagree
- * about a multi-line HTML block's extent, and so a fix here lives in exactly
- * one place instead of two copies drifting apart.
- *
- * History: naively scanning line-by-line from `startIndex` until depth
- * returns to zero (or giving up at end-of-document) is O(N^2) for a
- * document with many consecutive unclosed openers (e.g. thousands of bare
- * `<div>` lines), since every one of them re-scans to EOF. A first fix
- * added an O(1) "does a close exist anywhere" pre-check plus a fixed
- * line-count cap on the residual scan — but that cap silently truncated
- * VALID blocks longer than it, and removing the cap alone reopened a
- * closely related O(N^2) case: N unclosed openers followed by a SINGLE
- * trailing close still all pass the "a close exists somewhere" pre-check,
- * so every one of them still scans forward (mostly to EOF) before giving up.
- *
- * Fixed properly here with a per-tag-name prefix-sum index
- * (`buildTagCloseIndex`, O(N), built once per tag name and cached per
- * document — see `closeCache`): finding "the exact line where a block
- * starting at `startIndex` closes, if ever" is exactly the classic "next
- * smaller-or-equal element" query against that prefix sum, which the index
- * answers in O(1). No scanning happens per opener at all — not for a block
- * that never closes, not for one that closes after any number of
- * intervening lines, however many. This is provably linear overall (a
- * document with T distinct protected tag names costs O(T * N) to index,
- * and T is bounded by the small, fixed `HTML_BLOCK_TAGS` set) and can never
- * truncate a valid block, because it always finds the block's real end
- * (however far away) rather than giving up at a fixed distance.
- *
- * Returns `startIndex` unchanged when the block never closes: depth <= 0,
- * or the running depth never returns to exactly zero anywhere in the rest
- * of the document (whether because no close exists at all, or one exists
- * but is insufficient to bring the count back to exactly the opener's own
- * baseline — e.g. an unbalanced/self-closing tag).
- */
-function findHtmlBlockEnd(
-  lines: string[],
-  startIndex: number,
-  tagName: string,
-  depth: number,
-  closeCache: Map<string, TagCloseIndex>,
-): number {
-  if (depth <= 0) return startIndex;
-  let index = closeCache.get(tagName);
-  if (!index) {
-    index = buildTagCloseIndex(lines, tagName);
-    closeCache.set(tagName, index);
-  }
-  const { augmented, nextAtOrBelow } = index;
-  const m = nextAtOrBelow[startIndex];
-  if (m === -1) return startIndex;
-  return augmented[m] === augmented[startIndex] ? m - 1 : startIndex;
-}
-
-const markProtectedLines = (lines: string[]): boolean[] => {
-  const isProtected = new Array<boolean>(lines.length).fill(false);
-  let fenceLen = 0; // 0 = not currently inside a fence
-  const closeCache = new Map<string, TagCloseIndex>();
-  for (let i = 0; i < lines.length; i++) {
-    if (fenceLen > 0) {
-      isProtected[i] = true;
-      if (new RegExp('^\\s*`{' + fenceLen + ',}').test(lines[i])) fenceLen = 0;
-      continue;
-    }
-    const trimmed = lines[i].trim();
-    if (trimmed.startsWith('```')) {
-      fenceLen = trimmed.match(/^`+/)![0].length;
-      isProtected[i] = true;
-      continue;
-    }
-    const htmlTagMatch = trimmed.match(HTML_BLOCK_OPEN_RE);
-    if (htmlTagMatch && HTML_BLOCK_TAGS.has(htmlTagMatch[1].toLowerCase())) {
-      const tagName = htmlTagMatch[1].toLowerCase();
-      const isCloseTag = trimmed.startsWith('</');
-      isProtected[i] = true;
-      if (isCloseTag) {
-        while (i + 1 < lines.length && lines[i + 1].trim() !== '') {
-          i++;
-          isProtected[i] = true;
-        }
-      } else if (VOID_HTML_TAGS.has(tagName)) {
-        while (!lines[i].includes('>') && i + 1 < lines.length && lines[i + 1].trim() !== '') {
-          i++;
-          isProtected[i] = true;
-        }
-      } else {
-        const openRe = new RegExp(`<${tagName}(?:\\s|>|/|$)`, 'gi');
-        const closeRe = new RegExp(`</${tagName}\\s*>`, 'gi');
-        const depth = (lines[i].match(openRe) || []).length - (lines[i].match(closeRe) || []).length;
-        const end = findHtmlBlockEnd(lines, i, tagName, depth, closeCache);
-        if (end > i) {
-          for (let idx = i + 1; idx <= end; idx++) isProtected[idx] = true;
-          i = end;
-        }
-      }
-    }
-  }
-  return isProtected;
-};
-
-/** Resolve reference links/images in one non-code, non-HTML line. A single
- * left-to-right pass: an inline code span is matched as a whole and returned
- * verbatim, so a reference-looking pattern inside backticks is never
- * rewritten; only bracketed references outside code are resolved. Every label
- * that actually resolves against a definition is recorded into `usedLabels`,
- * so the caller can tell a genuinely consumed definition from an unused one. */
-const resolveRefsInLine = (
-  line: string,
-  defs: Map<string, string>,
-  usedLabels: Set<string>,
-): string => {
-  if (!line.includes('[')) return line;
-  return line.replace(
-    REFERENCE_LINK_RE,
-    (match, codeTicks, bang, text, secondBracket, label, offset: number, whole: string) => {
-      if (codeTicks !== undefined) return match; // inline code span: keep verbatim
-      let refLabel: string;
-      if (secondBracket === undefined) {
-        // Shortcut `[text]`: not a link when an inline `(...)` destination
-        // follows (that is an inline link the existing renderer already draws).
-        if (whole[offset + match.length] === '(') return match;
-        // Nor when it is a task-list checkbox marker at the start of a list
-        // item (`- [x]`); the checkbox parser owns that `[x]`, and resolving it
-        // against a stray `x`/`X` definition would clobber the item.
-        if (/^[ xX]$/.test(text) && /^\s*(?:[-*+]|\d+[.)])\s+$/.test(whole.slice(0, offset))) {
-          return match;
-        }
-        refLabel = text;
-      } else {
-        refLabel = label === '' ? text : label;
-      }
-      const normalized = normalizeRefLabel(refLabel);
-      const dest = defs.get(normalized);
-      // An unknown reference stays literal, matching CommonMark and avoiding
-      // false links for bracketed prose like `[TODO]` or array indices.
-      if (!dest) return match;
-      usedLabels.add(normalized);
-      return `${bang}[${text}](${dest})`;
-    },
-  );
-};
-
-/**
- * Resolve CommonMark link reference definitions and reference links into inline
- * `[text](url)` links, so the shared inline renderer draws them instead of
- * showing raw `[text][id]` and `[id]: url` text (issue #923). Definitions and
- * references inside fenced code blocks, raw HTML blocks, and inline code spans
- * are left untouched. A definition-shaped line is only ever blanked when its
- * label was actually consumed by a resolved reference outside a protected
- * region — an unused definition, or one referenced only from inside code/HTML,
- * stays visible exactly as written. Blanked lines keep block start-line
- * numbers accurate (and their own CRLF ending, so line endings round-trip).
- * GFM footnote definitions (`[^label]: ...`) are never treated as link
- * definitions. No-op (returns the input) when the document defines no
- * (non-footnote) references.
- */
-export const resolveReferenceLinks = (markdown: string): string => {
-  if (!markdown.includes('[')) return markdown;
-  const lines = markdown.split('\n');
-  const isProtected = markProtectedLines(lines);
-  const defs = new Map<string, string>();
-  // The normalized label a definition-shaped line defines, or null if the
-  // line isn't a definition (or is a footnote definition, which is never
-  // collected/blanked).
-  const defLabelByLine = new Array<string | null>(lines.length).fill(null);
-  // A definition cannot interrupt a paragraph (CommonMark 4.7): a line matching
-  // the definition shape is only a definition when it can start a block, i.e.
-  // the previous line is the document start, blank, a protected code/HTML
-  // line (each is its own block), or itself a definition. Otherwise the line
-  // is paragraph continuation text and must be left untouched, or a bare
-  // `[word]: token` under a sentence would be silently deleted.
-  let canStartDefinition = true;
-  for (let i = 0; i < lines.length; i++) {
-    if (isProtected[i]) {
-      canStartDefinition = true;
-      continue;
-    }
-    const blank = lines[i].trim() === '';
-    const match = canStartDefinition && !blank ? lines[i].match(REFERENCE_DEFINITION_RE) : null;
-    if (match) {
-      const rawLabel = match[1];
-      // GFM footnote definition ([^label]: ...) — not a link reference
-      // definition. Leave it out of `defs` entirely so it can never be
-      // collected, blanked, or accidentally satisfy a footnote reference's
-      // lookup; it stays block-starting like any other definition line.
-      if (!rawLabel.startsWith('^') && defs.size < MAX_TRACKED_DEFINITIONS) {
-        const label = normalizeRefLabel(rawLabel);
-        const dest = match[2] !== undefined ? match[2] : match[3];
-        // First definition wins, per CommonMark.
-        if (label && dest && !defs.has(label)) defs.set(label, dest);
-        defLabelByLine[i] = label;
-      }
-      // A run of definitions stays eligible; canStartDefinition remains true.
-    } else {
-      // Blank keeps a new block startable; any other non-definition line starts
-      // (or continues) a paragraph, so a following definition-shaped line is text.
-      canStartDefinition = blank;
-    }
-  }
-  if (defs.size === 0) return markdown;
-  const usedLabels = new Set<string>();
-  // Resolve references first; definition-shaped lines are passed through
-  // unresolved (never fed to resolveRefsInLine) so a definition's own
-  // `[label]` can never be mistaken for a reference to itself.
-  const resolved = lines.map((line, i) =>
-    isProtected[i] || defLabelByLine[i] !== null ? line : resolveRefsInLine(line, defs, usedLabels),
-  );
-  return resolved
-    .map((line, i) => {
-      const label = defLabelByLine[i];
-      if (label === null || !usedLabels.has(label)) return line;
-      // Blank in place, preserving this line's own CRLF ending if it had one.
-      return line.endsWith('\r') ? '\r' : '';
-    })
-    .join('\n');
-};
 
 /**
  * The block list for a whole-file diagram source (`plannotator annotate
@@ -861,22 +507,17 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
       continue;
     }
     
-    // Code blocks (naive)
+    // Code blocks (naive). Count backticks in the opening fence to support
+    // nested fences (e.g. ```` wrapping ```); the extent is shared with core.
     if (trimmed.startsWith('```')) {
       flush();
       const codeStartLine = currentLineNum;
-      // Count backticks in opening fence to support nested fences (e.g. ```` wrapping ```)
       const fenceLen = trimmed.match(/^`+/)?.[0].length ?? 3;
-      const closingFence = new RegExp('^\\s*`{' + fenceLen + ',}');
       // Extract language from fence (e.g., ```rust → "rust")
       const language = trimmed.slice(fenceLen).trim() || undefined;
-      // Fast forward until end of code block
-      let codeContent = [];
-      i++; // Skip start fence
-      while(i < lines.length && !closingFence.test(lines[i])) {
-        codeContent.push(lines[i]);
-        i++;
-      }
+      const close = codeFenceCloseIndex(lines, i);
+      const codeContent = lines.slice(i + 1, close);
+      i = close;
       blocks.push({
         id: `block-${currentId++}`,
         type: 'code',
@@ -888,127 +529,32 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
       continue;
     }
 
-    // Display math: $$ ... $$ — only when a closing $$ actually exists. An
-    // unclosed $$ (a stray delimiter or informal money like "$$100k for infra")
-    // must NOT swallow the rest of the document: scan ahead without committing,
-    // and if there's no close, fall through and treat the line as ordinary text.
-    if (trimmed.startsWith('$$')) {
-      const mathStartLine = currentLineNum;
-      const afterOpen = trimmed.slice(2);
-      const mathLines: string[] = [];
-      let remainder = '';
-      let closed = false;
-      let closeLine = i;
-      // Find the closing $$ anywhere on the opening line (not just at its end),
-      // so `$$x$$.` or `$$x$$ trailing` close correctly instead of running on.
-      const inlineClose = afterOpen.indexOf('$$');
-      if (inlineClose !== -1) {
-        const body = afterOpen.slice(0, inlineClose).trim();
-        if (body) mathLines.push(body);
-        remainder = afterOpen.slice(inlineClose + 2).trim();
-        closed = true;
-      } else {
-        const scanned: string[] = afterOpen.trim() ? [afterOpen.trim()] : [];
-        let j = i;
-        while (j + 1 < lines.length) {
-          j++;
-          // A blank line ends the search: real $$…$$ has no blank line before its
-          // close, so a blank means this opener was never closed. Stopping here
-          // also prevents matching a stray $$ far below (e.g. inside a later code
-          // fence) and swallowing everything in between.
-          if (lines[j].trim() === '') break;
-          const closeAt = lines[j].indexOf('$$');
-          if (closeAt !== -1) {
-            const before = lines[j].slice(0, closeAt);
-            if (before.trim()) scanned.push(before);
-            remainder = lines[j].slice(closeAt + 2).trim();
-            closed = true;
-            closeLine = j;
-            break;
-          }
-          scanned.push(lines[j]);
-        }
-        if (closed) for (const s of scanned) mathLines.push(s);
-      }
-
-      if (closed) {
-        flush();
-        i = closeLine;
-        blocks.push({
-          id: `block-${currentId++}`,
-          type: 'math',
-          content: mathLines.join('\n'),
-          order: currentId,
-          startLine: mathStartLine,
-          sourceLineCount: i + contentStartLine - mathStartLine + 1,
-        });
-        // Trailing text after the closing $$ isn't math — reprocess it as its own
-        // line so it renders normally instead of being swallowed into the block.
-        if (remainder) {
-          lines[i] = remainder;
-          i--;
-        }
-        continue;
-      }
-      // No closing $$ found — not display math; fall through to normal handling.
-    }
-
-    // Display math: \[ ... \] — same unclosed-guard as $$ above: only treat as
-    // math when the closing \] exists, so a stray `\[deprecated\]`-style line or
-    // an unclosed `\[` doesn't swallow the rest of the document.
-    if (trimmed.startsWith('\\[')) {
+    // Display math: $$ ... $$ or \[ ... \] — only when the close actually
+    // exists. An unclosed opener (a stray delimiter, informal money like
+    // "$$100k for infra", a `\[deprecated\]`-style line) must NOT swallow the
+    // rest of the document: scanDisplayMath scans ahead without committing
+    // and answers null, and the line falls through as ordinary text.
+    const mathDelimiter = trimmed.startsWith('$$') ? '$$' : trimmed.startsWith('\\[') ? '\\[' : null;
+    const math = mathDelimiter ? scanDisplayMath(lines, i, mathDelimiter) : null;
+    if (math) {
+      flush();
       const mathStartLine = currentLineNum;
-      const afterOpen = trimmed.slice(2);
-      const mathLines: string[] = [];
-      let remainder = '';
-      let closed = false;
-      let closeLine = i;
-      const inlineClose = afterOpen.indexOf('\\]');
-      if (inlineClose !== -1) {
-        const body = afterOpen.slice(0, inlineClose).trim();
-        if (body) mathLines.push(body);
-        remainder = afterOpen.slice(inlineClose + 2).trim();
-        closed = true;
-      } else {
-        const scanned: string[] = afterOpen.trim() ? [afterOpen.trim()] : [];
-        let j = i;
-        while (j + 1 < lines.length) {
-          j++;
-          // Blank line ends the search (see the $$ branch): unclosed \[ must not
-          // swallow later blocks or match a stray \] inside a later code fence.
-          if (lines[j].trim() === '') break;
-          const closeAt = lines[j].indexOf('\\]');
-          if (closeAt !== -1) {
-            const before = lines[j].slice(0, closeAt);
-            if (before.trim()) scanned.push(before);
-            remainder = lines[j].slice(closeAt + 2).trim();
-            closed = true;
-            closeLine = j;
-            break;
-          }
-          scanned.push(lines[j]);
-        }
-        if (closed) for (const s of scanned) mathLines.push(s);
-      }
-
-      if (closed) {
-        flush();
-        i = closeLine;
-        blocks.push({
-          id: `block-${currentId++}`,
-          type: 'math',
-          content: mathLines.join('\n'),
-          order: currentId,
-          startLine: mathStartLine,
-          sourceLineCount: i + contentStartLine - mathStartLine + 1,
-        });
-        if (remainder) {
-          lines[i] = remainder;
-          i--;
-        }
-        continue;
+      i = math.closeLine;
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'math',
+        content: math.body.join('\n'),
+        order: currentId,
+        startLine: mathStartLine,
+        sourceLineCount: i + contentStartLine - mathStartLine + 1,
+      });
+      // Trailing text after the close isn't math — reprocess it as its own
+      // line so it renders normally instead of being swallowed into the block.
+      if (math.remainder) {
+        lines[i] = math.remainder;
+        i--;
       }
-      // No closing \] found — not display math; fall through to normal handling.
+      continue;
     }
 
     // Tables (lines starting with |)
@@ -1039,27 +585,17 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
       continue;
     }
 
-    // Raw HTML blocks. A line starting with a known block-level HTML tag
-    // opens an HTML block. For opening tags we accumulate until the matching
-    // close tag is balanced (so `<details>…blank line…</details>` renders as
-    // one unit, matching GitHub's flavored behavior rather than strict
-    // CommonMark §4.6 Type 6 blank-line termination). For a line that starts
-    // with a close tag, we fall back to blank-line termination. Content is
-    // sanitized at render time, not here.
     // Directive container: `:::kind` opens, `:::` closes. Inline kind is
     // restricted to simple identifiers (letters, digits, hyphens). Body is
     // accumulated verbatim and rendered with inline markdown.
-    const directiveOpen = trimmed.match(/^:::\s*([a-zA-Z][a-zA-Z0-9-]*)\s*$/);
+    const directiveOpen = trimmed.match(DIRECTIVE_OPEN_RE);
     if (directiveOpen) {
       flush();
       const directiveStartLine = currentLineNum;
       const kind = directiveOpen[1].toLowerCase();
-      const bodyLines: string[] = [];
-      while (i + 1 < lines.length) {
-        i++;
-        if (lines[i].trim() === ':::') break;
-        bodyLines.push(lines[i]);
-      }
+      const close = directiveCloseIndex(lines, i);
+      const bodyLines = lines.slice(i + 1, close);
+      i = close;
       blocks.push({
         id: `block-${currentId++}`,
         type: 'directive',
@@ -1071,43 +607,19 @@ export const parseMarkdownToBlocks = (markdown: string, options?: ParseMarkdownO
       continue;
     }
 
-    const htmlTagMatch = trimmed.match(HTML_BLOCK_OPEN_RE);
-    if (htmlTagMatch && HTML_BLOCK_TAGS.has(htmlTagMatch[1].toLowerCase())) {
+    // Raw HTML blocks. A line starting with a known block-level HTML tag
+    // opens an HTML block. For opening tags we accumulate until the matching
+    // close tag is balanced (so `<details>…blank line…</details>` renders as
+    // one unit, matching GitHub's flavored behavior rather than strict
+    // CommonMark §4.6 Type 6 blank-line termination). For a line that starts
+    // with a close tag, we fall back to blank-line termination. Content is
+    // sanitized at render time, not here.
+    const htmlEnd = htmlBlockEndAt(lines, i, htmlCloseCache);
+    if (htmlEnd !== -1) {
       flush();
       const htmlStartLine = currentLineNum;
-      const tagName = htmlTagMatch[1].toLowerCase();
-      const isCloseTag = trimmed.startsWith('</');
-      const htmlLines: string[] = [line];
-
-      if (isCloseTag) {
-        while (i + 1 < lines.length && lines[i + 1].trim() !== '') {
-          i++;
-          htmlLines.push(lines[i]);
-        }
-      } else if (VOID_HTML_TAGS.has(tagName)) {
-        // Void element (e.g. <img>): no closing tag, but attributes can wrap across
-        // lines. Consume until the line that actually closes the tag with `>` so a
-        // multi-line <img> isn't truncated to a bare `<img` fragment.
-        while (!lines[i].includes('>') && i + 1 < lines.length && lines[i + 1].trim() !== '') {
-          i++;
-          htmlLines.push(lines[i]);
-        }
-      } else {
-        const openRe = new RegExp(`<${tagName}(?:\\s|>|/|$)`, 'gi');
-        const closeRe = new RegExp(`</${tagName}\\s*>`, 'gi');
-        const depth = (line.match(openRe) || []).length - (line.match(closeRe) || []).length;
-        // Scan ahead for the matching close tag via the shared, bounded/
-        // linear helper (see its doc comment for why a naive per-opener scan
-        // is quadratic). If none is ever found — a self-closing <video/>, or
-        // an unclosed <picture>/<div> — do NOT swallow the rest of the
-        // document into this block; keep it to the opening line.
-        const end = findHtmlBlockEnd(lines, i, tagName, depth, htmlCloseCache);
-        if (end > i) {
-          for (let k = i + 1; k <= end; k++) htmlLines.push(lines[k]);
-          i = end;
-        }
-      }
-
+      const htmlLines = lines.slice(i, htmlEnd + 1);
+      i = htmlEnd;
       blocks.push({
         id: `block-${currentId++}`,
         type: 'html',
@@ -1380,6 +892,11 @@ const additionalTargetsExportBlock = (ann: any): string => {
  * panel chrome does not use it.
  */
 export const exportAnnotationEntry = (ann: any, opts: ElementContextExportOptions = { includeRoute: true }): string => {
+  // An answer to a `:::question` block: the question and the answer lines.
+  const answer = ann?.questionAnswer == null ? null : parseQuestionAnswer(ann.questionAnswer);
+  if (answer) {
+    return `Answer to the question "${safeInline(answer.prompt, 400)}"\n${formatQuestionAnswerLines(answer)}`;
+  }
   let output = '';
   switch (ann?.type) {
     case 'DELETION':
@@ -1431,15 +948,47 @@ const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   return `lines ${block.startLine}–${end}`;
 };
 
+/** Separate valid question answers from ordinary feedback. A row whose
+ *  `questionAnswer` fails validation stays ordinary feedback (its one-line
+ *  text still reads), so nothing is ever dropped. */
+const splitQuestionAnswers = (list: any[]): { answers: QuestionAnswer[]; annotations: any[] } => {
+  const answers: QuestionAnswer[] = [];
+  const annotations: any[] = [];
+  for (const ann of list) {
+    const answer = ann?.questionAnswer == null ? null : parseQuestionAnswer(ann.questionAnswer);
+    if (answer) answers.push(answer);
+    else annotations.push(ann);
+  }
+  return { answers, annotations };
+};
+
+/** Export items when a document's blocks are unknown: the answers' own
+ *  prompts and lines, numbered in answer order. */
+const questionItemsFromAnswers = (answers: QuestionAnswer[]): QuestionExportItem[] =>
+  answers.map((a, i) => ({
+    key: a.key,
+    number: i + 1,
+    prompt: a.prompt,
+    ...(a.sourceLine ? { line: a.sourceLine } : {}),
+    recommendedLabels: [],
+    settled: false,
+  }));
+
 export const exportAnnotations = (
   blocks: Block[],
-  annotations: any[],
+  allAnnotations: any[],
   globalAttachments: ImageAttachment[] = [],
   title: string = 'Plan Feedback',
   subject: string = 'plan',
   opts: ExportAnnotationsOptions = {},
 ): string => {
-  if (annotations.length === 0 && globalAttachments.length === 0) {
+  // 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.';
   }
 
@@ -1461,6 +1010,8 @@ export const exportAnnotations = (
     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`;
@@ -1673,11 +1224,20 @@ export const exportLinkedDocAnnotations = (
   // One injection per export, across all linked documents.
   const injectedSkills = new Set<string>();
 
-  for (const [filepath, { annotations, globalAttachments, blocks: docBlocks, isConverted }] of docAnnotations) {
-    if (annotations.length === 0 && globalAttachments.length === 0) continue;
+  for (const [filepath, { annotations: docAnnotationList, globalAttachments, blocks: docBlocks, markdown: docMarkdown, isConverted }] of docAnnotations) {
+    if (docAnnotationList.length === 0 && globalAttachments.length === 0) continue;
+    const { answers, annotations } = splitQuestionAnswers(docAnnotationList);
 
     output += `## ${filepath}${isConverted ? ' (converted from HTML — line numbers refer to converted markdown)' : ''}\n\n`;
 
+    if (answers.length > 0) {
+      const questionBlocks = docBlocks ?? (docMarkdown !== undefined ? parseMarkdownToBlocks(docMarkdown) : null);
+      const items = questionBlocks
+        ? questionExportItems(indexQuestionBlocks(questionBlocks))
+        : questionItemsFromAnswers(answers);
+      output += formatQuestionAnswersSection(items, answers, { headingLevel: 3 });
+    }
+
     if (globalAttachments.length > 0) {
       output += `### Reference Images\n`;
       output += `Please review these reference images (use the Read tool to view):\n`;
@@ -1693,7 +1253,9 @@ export const exportLinkedDocAnnotations = (
       return a.startOffset - b.startOffset;
     });
 
-    output += `I've reviewed this document and have ${annotations.length} piece${annotations.length !== 1 ? 's' : ''} of feedback:\n\n`;
+    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}. `;