@plannotator/ui 0.50.0 → 0.52.0

package/utils/blockTargeting.ts

@@ -17,6 +17,10 @@ const SKIP_SELECTORS = [
 ].join(',');
 
 const INLINE_TARGET_SELECTOR = 'strong,em,a,code:not(.pn-code)';
+/** A `:::question` card (`QuestionBlock`): one block whose text is in parts. */
+const QUESTION_CARD_SELECTOR = 'fieldset.question-block';
+/** The card's text parts: the prompt, the context, and each choice's text. */
+const QUESTION_PART_SELECTOR = '[data-question-part]';
 const TABLE_EDGE_ZONE = 22;
 
 /** The semantic kind of a document target. */
@@ -133,10 +137,22 @@ function groupLabel(group: HTMLElement): string {
 }
 
 function listContentElement(block: HTMLElement): HTMLElement | null {
+  // A question card also starts with a `select-none` child (its eyebrow), so
+  // without this its second child, the prompt, stood in for the whole card:
+  // every pinpoint hover or click inside it resolved to the prompt.
+  if (block.matches(QUESTION_CARD_SELECTOR)) return null;
   if (!block.querySelector('.select-none')) return null;
   return block.children[1] instanceof HTMLElement ? block.children[1] : null;
 }
 
+function questionPartLabel(part: HTMLElement): string {
+  const text = truncate(part.textContent?.trim() ?? '', 30);
+  const kind = part.dataset.questionPart;
+  if (kind === 'choice') return `choice: "${text}"`;
+  if (kind === 'context') return `context: "${text}"`;
+  return `question: "${text}"`;
+}
+
 function addInlineTargets(
   targets: SemanticTarget[],
   byElement: Map<HTMLElement, SemanticTarget>,
@@ -199,6 +215,38 @@ export function buildSemanticTargetGraph(container: HTMLElement): SemanticTarget
 
     const group = block.closest<HTMLElement>('[data-pinpoint-group]');
     const parentKey = group ? groupTargets.get(group)?.key ?? null : null;
+
+    // First: a card's context can hold a table, a code fence or a formula,
+    // and the card is still one question block made of its parts.
+    if (block.matches(QUESTION_CARD_SELECTOR)) {
+      const prompt = block.querySelector<HTMLElement>('[data-question-part="prompt"]');
+      const cardTarget: SemanticTarget = {
+        key: `${blockId}:block`,
+        blockId,
+        element: block,
+        label: prompt ? questionPartLabel(prompt) : 'question',
+        kind: 'block',
+        parentKey,
+      };
+      targets.push(cardTarget);
+      byElement.set(block, cardTarget);
+      blockKeys.push(cardTarget.key);
+      block.querySelectorAll<HTMLElement>(QUESTION_PART_SELECTOR).forEach((part, index) => {
+        const partTarget: SemanticTarget = {
+          key: `${blockId}:part:${index}`,
+          blockId,
+          element: part,
+          label: questionPartLabel(part),
+          kind: 'inline',
+          parentKey: cardTarget.key,
+        };
+        targets.push(partTarget);
+        byElement.set(part, partTarget);
+        addInlineTargets(targets, byElement, blockId, partTarget, part, partTarget.key);
+      });
+      continue;
+    }
+
     const codeElement = block.querySelector<HTMLElement>('pre > code.pn-code');
     const mathElement = block.matches('.math-annotatable,[data-math-tex]')
       ? block
@@ -455,8 +503,11 @@ export function resolveSemanticTargetAtPoint(
   if (!block || !graph.container.contains(block) || block.tagName === 'HR') return null;
   const blockTarget = targetForBlock(graph, block);
   if (!blockTarget) return null;
+  // A question card's code fences and tables live in its context part; the
+  // part lookup below resolves them.
+  const card = block.matches(QUESTION_CARD_SELECTOR);
 
-  const code = block.querySelector<HTMLElement>('pre > code.pn-code');
+  const code = card ? null : block.querySelector<HTMLElement>('pre > code.pn-code');
   if (
     code
     && (pointerTarget === code || code.contains(pointerTarget) || pointerTarget.closest('pre'))
@@ -464,7 +515,7 @@ export function resolveSemanticTargetAtPoint(
     return blockTarget;
   }
 
-  const table = block.querySelector<HTMLTableElement>('table');
+  const table = card ? null : block.querySelector<HTMLTableElement>('table');
   if (table && pointer) {
     const rect = table.getBoundingClientRect();
     const nearHorizontalEdge = pointer.clientX - rect.left < TABLE_EDGE_ZONE
@@ -484,6 +535,14 @@ export function resolveSemanticTargetAtPoint(
     if (inlineTarget) return inlineTarget;
   }
 
+  // Inside a question card: the part under the pointer. A choice row's
+  // padding and marker belong to that choice's text.
+  const part = pointerTarget.closest<HTMLElement>(QUESTION_PART_SELECTOR)
+    ?? pointerTarget.closest<HTMLElement>('[data-question-option]')?.querySelector<HTMLElement>(QUESTION_PART_SELECTOR);
+  if (part && block.contains(part)) {
+    return graph.byElement.get(part) ?? blockTarget;
+  }
+
   const cell = pointerTarget.closest<HTMLTableCellElement>('td,th');
   if (cell && block.contains(cell)) {
     return graph.byElement.get(cell) ?? blockTarget;

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),
+  };
+}