@plannotator/ui 0.50.0 → 0.52.0

package/components/ai/SessionAskNotice.tsx

@@ -3,7 +3,7 @@ import type { AIResponse } from '../../types';
 import { SESSION_ASK_ERROR_CODES } from '../../utils/aiProvider';
 
 /** What the reviewer chose on an "Ask this session" answer that could not run. */
-export type SessionAskAction = 'wait' | 'interrupt' | 'fallback';
+export type SessionAskAction = 'wait' | 'interrupt';
 
 /**
  * In-progress line for a question waiting on a busy session. Renders nothing
@@ -33,20 +33,20 @@ const buttonClass =
   'px-2 py-1 rounded-md text-[10px] font-medium transition-colors';
 
 /**
- * Follow-up actions under an "Ask this session" error:
+ * Follow-up under an "Ask this session" error:
  * - the session is busy: ask when it finishes, or interrupt it and ask now;
- * - the session is gone or blocked: ask a separate AI instead.
- * Renders nothing for other errors or when the host passes no handler.
+ * - the session is gone or blocked: a plain note. Ask AI has no other provider
+ *   while a session is attached, so there is nothing to switch to.
+ * Busy actions render only when the host passes a handler.
  */
 export const SessionAskActions: React.FC<{
   response: AIResponse;
   onAction?: (action: SessionAskAction) => void;
-  /** Label of the provider the fallback would use; null hides the fallback. */
-  fallbackLabel?: string | null;
-}> = ({ response, onAction, fallbackLabel }) => {
-  if (!onAction || !response.errorCode) return null;
+}> = ({ response, onAction }) => {
+  if (!response.errorCode) return null;
 
   if (response.errorCode === SESSION_ASK_ERROR_CODES.agentBusy) {
+    if (!onAction) return null;
     return (
       <div className="flex flex-wrap gap-1.5 mt-2" data-session-ask-actions="busy">
         <button
@@ -68,22 +68,34 @@ export const SessionAskActions: React.FC<{
     );
   }
 
-  if (
-    (response.errorCode === SESSION_ASK_ERROR_CODES.gone || response.errorCode === SESSION_ASK_ERROR_CODES.blocked) &&
-    fallbackLabel
-  ) {
+  if (response.errorCode === SESSION_ASK_ERROR_CODES.gone || response.errorCode === SESSION_ASK_ERROR_CODES.blocked) {
+    const gone = response.errorCode === SESSION_ASK_ERROR_CODES.gone;
     return (
-      <div className="flex flex-wrap gap-1.5 mt-2" data-session-ask-actions="fallback">
-        <button
-          type="button"
-          onClick={() => onAction('fallback')}
-          className={`${buttonClass} bg-muted text-foreground hover:bg-muted/80`}
-        >
-          Ask a separate AI instead ({fallbackLabel})
-        </button>
-      </div>
+      <p
+        className="mt-1.5 text-[11px] text-muted-foreground"
+        data-session-ask-unreachable={gone ? 'gone' : 'blocked'}
+      >
+        {gone
+          ? 'Ask AI answers only from the session that opened Plannotator, and that session is gone, so Ask AI can\'t reach it.'
+          : 'Ask AI answers only from the session that opened Plannotator, and that session is waiting on this decision, so Ask AI can\'t reach it until you decide.'}
+      </p>
     );
   }
 
   return null;
 };
+
+/**
+ * A muted note under an "Ask this session" answer that stopped early because
+ * the person typed into the session while it answered (the rest of that turn
+ * went to their prompt). The partial answer above it stands. Renders nothing
+ * for any other response.
+ */
+export const SessionAskNote: React.FC<{ response: Pick<AIResponse, 'notice'> }> = ({ response }) => {
+  if (!response.notice) return null;
+  return (
+    <p className="mt-1.5 text-[11px] text-muted-foreground" data-session-ask-note="taken-over">
+      {response.notice}
+    </p>
+  );
+};

package/components/blocks/QuestionBlock.tsx

@@ -1,5 +1,6 @@
-import React, { useId, useRef, useState } from 'react';
+import React, { useId, useMemo, useRef, useState } from 'react';
 import {
+  canonicalQuestionAnswer,
   emptyQuestionAnswer,
   isQuestionAnswerEmpty,
   questionStatus,
@@ -9,7 +10,7 @@ import {
   type QuestionAnswer,
 } from '@plannotator/core/question-block';
 import { InlineMarkdown } from '../InlineMarkdown';
-import { renderProseBody } from './proseBody';
+import { QuestionContext } from './QuestionContext';
 
 /**
  * A `:::question` block rendered as an answer card (the approved "Card"
@@ -35,7 +36,10 @@ import { renderProseBody } from './proseBody';
  *
  * A host can add its own actions at the right of the footer
  * (`renderFooter`), and a question carrying `Decision: when answered` or a
- * `Decision: [statement](url)` link shows that beside the prompt.
+ * `Decision: [statement](url)` link shows that beside the prompt. A host can
+ * also let the reviewer switch a `Decision: when answered` question's
+ * recording off and on (`decisionRecording` + `onToggleDecisionRecording`),
+ * and hide the card's own status tag to draw its own (`statusTag: 'none'`).
  */
 
 /** Pointer travel (px) above which a press on a choice row is a drag. */
@@ -49,7 +53,7 @@ const now = (): number => (typeof performance !== 'undefined' ? performance.now(
 
 const cx = (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' ');
 
-const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.ReactNode; className?: string }> = ({ tone, children, className }) => (
+const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.ReactNode; className?: string; style?: React.CSSProperties }> = ({ tone, children, className, style }) => (
   <span
     className={cx(
       'annotation-exclude select-none inline-flex items-center gap-1 whitespace-nowrap rounded px-1.5 py-px align-[1px] text-[10.5px] font-semibold tracking-[0.03em]',
@@ -59,6 +63,7 @@ const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.Reac
       tone === 'open' && 'border border-dashed border-border text-muted-foreground',
       className,
     )}
+    style={style}
     data-pinpoint-ignore=""
   >
     {children}
@@ -77,6 +82,19 @@ const DiamondGlyph = () => (
   </svg>
 );
 
+/** Draws a decision tag in its "off" state: the same words, dimmed, with a
+ *  dotted outline instead of the tinted fill. Dimmed means the theme's
+ *  muted-foreground, not opacity: 60% opacity on primary text dropped the
+ *  default light theme under 3:1, while muted-foreground is the token every
+ *  theme already tunes for secondary text. Inline so it adds no utility
+ *  classes to the shared stylesheet and wins over the tag's `text-primary`. */
+const DECISION_OFF_STYLE: React.CSSProperties = {
+  background: 'transparent',
+  color: 'var(--muted-foreground)',
+  outline: '1px dotted currentColor',
+  outlineOffset: '-1px',
+};
+
 /** Two answers say the same thing (identity and line ignored). */
 const sameAnswer = (a: QuestionAnswer | null | undefined, b: QuestionAnswer | null | undefined): boolean => {
   const norm = (x: QuestionAnswer | null | undefined) =>
@@ -109,6 +127,21 @@ export interface QuestionBlockProps {
    *  saved answer (never the unsaved draft). Rendered in read-only cards too;
    *  return null for nothing. */
   renderFooter?: (question: IndexedQuestion, answer: QuestionAnswer | undefined) => React.ReactNode;
+  /** Whether answering a `Decision: when answered` question records a
+   *  decision (default true). False draws the "Records a decision" tag dimmed
+   *  with a dotted outline and hides the "Answering this records a decision"
+   *  row. Has no effect on a question whose decision is already recorded
+   *  (`Decision: [statement](url)`) or that carries no decision line. */
+  decisionRecording?: boolean;
+  /** Makes the "Records a decision" tag a toggle button (`aria-pressed`):
+   *  a click calls this with the question's key and the next state. The host
+   *  stores it and passes it back as `decisionRecording`. Not offered in a
+   *  read-only card (no answer handler), which draws the tag as it stands. */
+  onToggleDecisionRecording?: (key: string, next: boolean) => void;
+  /** `'none'` hides the card's own status tag (Open / Answered / Settled /
+   *  Skipped) so the host can draw its own; the decision tags stay. Default
+   *  `'card'`. */
+  statusTag?: 'card' | 'none';
   onOpenLinkedDoc?: (path: string) => void;
   onOpenCodeFile?: (path: string) => void;
   imageBaseDir?: string;
@@ -122,11 +155,14 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   blockId,
   indexed,
   total,
-  answer: savedAnswer,
+  answer: storedAnswer,
   onAnswer: onLiveAnswer,
   onSaveAnswer,
   saveLabel,
   renderFooter,
+  decisionRecording,
+  onToggleDecisionRecording,
+  statusTag = 'card',
   onOpenLinkedDoc,
   onOpenCodeFile,
   imageBaseDir,
@@ -136,6 +172,13 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   onNavigateAnchor,
 }) => {
   const { question, number } = indexed;
+  // An answer saved under an older label of a choice (0.28.1 read a wrapped
+  // plain bullet's first line as its label) shows that choice picked; the
+  // next edit stores the current label.
+  const savedAnswer = useMemo(
+    () => (storedAnswer ? canonicalQuestionAnswer(question, storedAnswer) : storedAnswer),
+    [question, storedAnswer],
+  );
   const saveMode = !!onSaveAnswer;
   // Save mode: the unsaved draft (null = the reviewer emptied it). Absent
   // means the card shows the host's answer.
@@ -312,6 +355,17 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const other = answer?.other ?? '';
   const otherOn = other.trim() !== '';
 
+  // A `Decision: when answered` question the host may switch off. A recorded
+  // decision (`question.decision`) is never affected.
+  const decisionCapable = !question.decision && !!question.decisionOnAnswer;
+  const recordingOn = decisionRecording ?? true;
+  const decisionToggleable = decisionCapable && !readOnly && !!onToggleDecisionRecording;
+  // Present only when the host speaks to recording, so a card without these
+  // props carries exactly the attributes it always did.
+  const recordingAttr = decisionCapable && (decisionRecording !== undefined || !!onToggleDecisionRecording)
+    ? (recordingOn ? 'on' : 'off')
+    : undefined;
+
   const describedBy = [question.context ? contextId : null, question.kind === 'text' && question.suggestedText && !answered ? suggestId : null]
     .filter(Boolean)
     .join(' ') || undefined;
@@ -336,23 +390,44 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
       aria-describedby={describedBy}
       aria-disabled={readOnly || undefined}
       data-question-decision={question.decision ? 'recorded' : question.decisionOnAnswer ? 'on-answer' : undefined}
+      data-question-decision-recording={recordingAttr}
     >
       <div className="annotation-exclude select-none mb-1.5 flex items-center gap-2" data-pinpoint-ignore="">
         <span className="text-[10.5px] font-semibold uppercase tracking-[0.08em] text-muted-foreground">{eyebrow}</span>
         <span className="ml-auto">
           {question.decision && <><Tag tone="rec"><DiamondGlyph />Decision</Tag>{' '}</>}
-          {!question.decision && question.decisionOnAnswer && <><Tag tone="rec"><DiamondGlyph />Records a decision</Tag>{' '}</>}
-          {status === 'answered' && <Tag tone="ok"><CheckGlyph />Answered</Tag>}
-          {status === 'settled' && <Tag tone="ok"><CheckGlyph />Settled</Tag>}
-          {status === 'skipped' && <Tag tone="skip">Skipped</Tag>}
-          {status === 'open' && <Tag tone="open">Open</Tag>}
+          {decisionCapable && (decisionToggleable ? (
+            // Focus shows as a ring, not an outline: the dotted outline is
+            // what draws the off state.
+            <><button
+              type="button"
+              aria-pressed={recordingOn}
+              onClick={() => onToggleDecisionRecording!(question.key, !recordingOn)}
+              className="annotation-exclude select-none inline-flex cursor-pointer items-center gap-1 whitespace-nowrap rounded px-1.5 py-px align-[1px] text-[10.5px] font-semibold tracking-[0.03em] bg-primary/15 text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+              style={recordingOn ? undefined : DECISION_OFF_STYLE}
+              data-pinpoint-ignore=""
+              data-question-decision-toggle=""
+            ><DiamondGlyph />Records a decision</button>{' '}</>
+          ) : recordingOn ? (
+            <><Tag tone="rec"><DiamondGlyph />Records a decision</Tag>{' '}</>
+          ) : (
+            <><Tag tone="rec" style={DECISION_OFF_STYLE}><DiamondGlyph />Records a decision</Tag>{' '}</>
+          ))}
+          {statusTag !== 'none' && (
+            <>
+              {status === 'answered' && <Tag tone="ok"><CheckGlyph />Answered</Tag>}
+              {status === 'settled' && <Tag tone="ok"><CheckGlyph />Settled</Tag>}
+              {status === 'skipped' && <Tag tone="skip">Skipped</Tag>}
+              {status === 'open' && <Tag tone="open">Open</Tag>}
+            </>
+          )}
         </span>
       </div>
 
-      <p id={promptId} className="m-0 text-[15px] font-semibold leading-[1.45] text-foreground">
+      <p id={promptId} className="m-0 text-[15px] font-semibold leading-[1.45] text-foreground" data-question-part="prompt">
         {inline(question.prompt)}
       </p>
-      {(question.decision || question.decisionOnAnswer) && (
+      {(question.decision || (question.decisionOnAnswer && recordingOn)) && (
         <div
           className="annotation-exclude mt-2 mb-0.5 flex items-center gap-2 rounded-lg bg-primary/8 px-[9px] py-1.5 text-[12.5px] leading-[18px] text-foreground [&>svg]:text-primary"
           data-pinpoint-ignore=""
@@ -378,20 +453,17 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
         </div>
       )}
       {question.context && (
-        <div id={contextId} className="mt-1 text-[13px] leading-normal text-muted-foreground">
-          {renderProseBody({
-            body: question.context,
-            paragraphClassName: 'text-[13px] leading-normal',
-            listClassName: 'text-[13px] leading-normal',
-            imageBaseDir,
-            onImageClick,
-            onOpenLinkedDoc,
-            onOpenCodeFile,
-            onNavigateAnchor,
-            githubRepo,
-            repoHost,
-          })}
-        </div>
+        <QuestionContext
+          id={contextId}
+          markdown={question.context}
+          imageBaseDir={imageBaseDir}
+          onImageClick={onImageClick}
+          onOpenLinkedDoc={onOpenLinkedDoc}
+          onOpenCodeFile={onOpenCodeFile}
+          onNavigateAnchor={onNavigateAnchor}
+          githubRepo={githubRepo}
+          repoHost={repoHost}
+        />
       )}
 
       {question.kind === 'text' ? (
@@ -454,7 +526,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
                   className="mt-[3px] h-[15px] w-[15px] shrink-0 cursor-pointer accent-primary disabled:cursor-default"
                   disabled={readOnly}
                 />
-                <span className="min-w-0 flex-1 select-text text-[13.5px] leading-[1.45] text-foreground">
+                <span className="min-w-0 flex-1 select-text text-[13.5px] leading-[1.45] text-foreground" data-question-part="choice">
                   <span className="font-[550]">{inline(choice.label)}</span>
                   {choice.description && (
                     <span className="text-muted-foreground"> — {inline(choice.description)}</span>

package/components/blocks/QuestionContext.tsx

@@ -0,0 +1,81 @@
+import React, { useMemo } from 'react';
+import type { Block } from '../../types';
+import { computeListIndices, groupBlocks, parseMarkdownToBlocks } from '../../utils/parser';
+// BlockRenderer renders QuestionBlock, which renders this: a cycle that only
+// meets at render time, after both modules have loaded.
+import { BlockRenderer } from '../BlockRenderer';
+
+/**
+ * The document renderers at the card's scale and tone. A stylesheet rather
+ * than Tailwind arbitrary variants on purpose: those would add utilities to
+ * every bundle whose Tailwind scans `packages/ui/components` (the guides.show
+ * viewer among them, which never renders a question card), and a host gets
+ * these rules without any Tailwind setup. Unlayered, so it outranks the
+ * renderers' utility classes.
+ */
+const QUESTION_CONTEXT_CSS = `
+.question-context > * { margin-top: 0.5rem; margin-bottom: 0.5rem; }
+.question-context > :first-child { margin-top: 0; }
+.question-context > :last-child { margin-bottom: 0; }
+.question-context p, .question-context .text-sm { font-size: 13px; line-height: 1.5; }
+.question-context p, .question-context [data-question-context-list] span { color: inherit; }
+.question-context h1, .question-context h2, .question-context h3 { margin: 0.75rem 0 0.25rem; font-size: 14px; }
+.question-context h3 { font-size: 13.5px; }
+`;
+
+/**
+ * A question card's context, rendered as the document renders markdown: the
+ * same block parser and the same block renderers, so a table, a list, a code
+ * fence, a quote or an image in the context looks the way it does in the
+ * document instead of collapsing into one paragraph.
+ *
+ * The blocks belong to the card: they carry no `data-block-id` of their own,
+ * so a selection or pinpoint inside them resolves to the card (and its
+ * `data-question-part="context"` part), never to a block id that also names a
+ * real document block. The card sets the scale: muted 13px prose, tight
+ * spacing.
+ */
+export const QuestionContext: React.FC<{
+  id: string;
+  markdown: string;
+  imageBaseDir?: string;
+  onImageClick?: (src: string, alt: string) => void;
+  onOpenLinkedDoc?: (path: string) => void;
+  onOpenCodeFile?: (path: string) => void;
+  onNavigateAnchor?: (hash: string) => void;
+  githubRepo?: string;
+  repoHost?: string;
+}> = ({ id, markdown, ...inlineProps }) => {
+  const groups = useMemo((): Array<{ list: Block[]; indices: (number | null)[] } | { block: Block }> => {
+    // Ids leave after grouping (grouping keys on them); undefined makes the
+    // renderers omit `data-block-id`.
+    const anonymous = (block: Block): Block => ({ ...block, id: undefined as unknown as string });
+    return groupBlocks(parseMarkdownToBlocks(markdown, { frontmatter: false })).map((group) =>
+      group.type === 'list-group'
+        ? { list: group.blocks.map(anonymous), indices: computeListIndices(group.blocks) }
+        : { block: anonymous(group.block) },
+    );
+  }, [markdown]);
+
+  return (
+    <div
+      id={id}
+      className="question-context mt-1 text-[13px] leading-normal text-muted-foreground"
+      data-question-part="context"
+    >
+      {/* React hoists this into <head> once for every card. */}
+      <style href="plannotator-question-context" precedence="default">{QUESTION_CONTEXT_CSS}</style>
+      {groups.map((group, i) =>
+        'list' in group ? (
+          <div key={`l-${i}`} data-question-context-list="">
+            {group.list.map((block, j) => (
+              <BlockRenderer key={j} block={block} orderedIndex={group.indices[j]} {...inlineProps} />
+            ))}
+          </div>
+        ) : (
+          <BlockRenderer key={`b-${i}`} block={group.block} {...inlineProps} />
+        ),
+      )}
+    </div>
+  );
+};

package/components/diagram/DiagramComposer.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
 import { diagramTargetName, diagramTargetText } from '@plannotator/core/diagram-anchor';
 import { cn } from '../../lib/utils';
 import type { ScreenRect } from '../../utils/diagram-projection';
+import { SparklesIcon } from '../SparklesIcon';
 import { Button } from '../ui/button';
 import type { DiagramComposerDraft } from './useDiagramComments';
 
@@ -12,6 +13,12 @@ import type { DiagramComposerDraft } from './useDiagramComments';
  * ruling; the markdown composer shows no hint either). It lives here
  * because the markdown composer is bound to web-highlighter's selection and
  * the html composer to the sandbox bridge; neither reaches an app-owned svg.
+ *
+ * With `onAskAI` it also offers the markdown composer's "Ask AI": the typed
+ * text is asked as a question about the part instead of saved as a comment.
+ * Disabled until there is text, never bound to a key (Enter stays Comment,
+ * as Mod+Enter stays Save in the markdown composer), and the composer closes
+ * once the host accepts the question.
  */
 
 /** The composer's width; it sits to the right of the ring and flips left
@@ -28,6 +35,7 @@ export function DiagramComposer({
   disabledReason,
   onSubmit,
   onCancel,
+  onAskAI,
 }: {
   draft: DiagramComposerDraft;
   anchorRect: ScreenRect;
@@ -41,12 +49,23 @@ export function DiagramComposer({
   disabledReason?: string;
   onSubmit: (body: string) => void;
   onCancel: () => void;
+  /** Ask the typed text as a question about this part. Resolves true when
+   * the host took it (the composer then closes), false to keep the draft.
+   * Absent: no Ask AI button. */
+  onAskAI?: (question: string) => Promise<boolean>;
 }) {
   const [text, setText] = useState('');
+  const [asking, setAsking] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
   useEffect(() => {
     textareaRef.current?.focus();
   }, []);
+  // A refused question hands the keyboard back to the textarea, once it is
+  // enabled again (it is disabled while the question is pending).
+  const [refocus, setRefocus] = useState(0);
+  useEffect(() => {
+    if (refocus > 0) textareaRef.current?.focus();
+  }, [refocus]);
 
   const target = draft.primary.target;
   const unsavedPart = draft.sourceLine === null && sourceDirty;
@@ -54,6 +73,25 @@ export function DiagramComposer({
   const rightFits = anchorRect.left + anchorRect.width + 12 + COMPOSER_WIDTH_PX <= hostWidth;
   const left = rightFits ? anchorRect.left + anchorRect.width + 12 : Math.max(0, anchorRect.left - COMPOSER_WIDTH_PX - 12);
 
+  const canAskAI = onAskAI !== undefined && !asking && !submitting && text.trim() !== '';
+  const askAI = async () => {
+    const question = text.trim();
+    if (onAskAI === undefined || question === '' || asking) {
+      textareaRef.current?.focus();
+      return;
+    }
+    setAsking(true);
+    let accepted = false;
+    try {
+      accepted = await onAskAI(question);
+    } catch (error) {
+      console.error('Ask AI action failed:', error);
+    } finally {
+      setAsking(false);
+    }
+    if (!accepted) setRefocus((n) => n + 1);
+  };
+
   const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
     if (event.key === 'Escape') {
       // Ours: the canvas and whatever holds it (a popout) must not also
@@ -65,7 +103,7 @@ export function DiagramComposer({
     }
     if (event.key === 'Enter' && !event.shiftKey && !event.nativeEvent.isComposing) {
       event.preventDefault();
-      if (canWrite && text.trim() !== '') onSubmit(text);
+      if (canWrite && !asking && text.trim() !== '') onSubmit(text);
     }
   };
 
@@ -100,7 +138,7 @@ export function DiagramComposer({
             onKeyDown={onKeyDown}
             placeholder="Add a comment..."
             rows={3}
-            disabled={submitting}
+            disabled={submitting || asking}
             className={cn(
               'w-full resize-none rounded-md border border-input bg-background px-2 py-1.5 text-xs text-foreground placeholder:text-muted-foreground',
               'outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50',
@@ -112,10 +150,23 @@ export function DiagramComposer({
             </p>
           )}
           <div className="flex items-center justify-end gap-1">
+            {onAskAI !== undefined && (
+              <button
+                type="button"
+                data-diagram-ask-ai=""
+                onClick={() => void askAI()}
+                disabled={!canAskAI}
+                className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-primary disabled:cursor-not-allowed disabled:opacity-50"
+                title={canAskAI ? 'Ask AI this question' : 'Type a question to ask AI'}
+              >
+                <SparklesIcon className="h-3 w-3" />
+                Ask AI
+              </button>
+            )}
             <Button type="button" variant="ghost" size="xs" onClick={onCancel}>
               Cancel
             </Button>
-            <Button type="button" size="xs" disabled={!canWrite || submitting || text.trim() === ''} onClick={() => onSubmit(text)}>
+            <Button type="button" size="xs" disabled={!canWrite || submitting || asking || text.trim() === ''} onClick={() => onSubmit(text)}>
               Comment
             </Button>
           </div>

package/components/diagram/DiagramViewer.tsx

@@ -1,5 +1,5 @@
 import { lazy, Suspense, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
-import type { DiagramKind } from '@plannotator/core/diagram-anchor';
+import { buildDiagramAnchorValue, type DiagramAnchor, type DiagramKind, type DiagramTarget } from '@plannotator/core/diagram-anchor';
 import { cn } from '../../lib/utils';
 import { diagramFamilyOf } from '../../utils/diagram-anchor';
 import { diagramFinder, type DiagramTheme } from '../../utils/diagram-render';
@@ -33,6 +33,16 @@ const DiagramSourcePane = lazy(async () => ({ default: (await import('./DiagramS
  * Never `null` here — that would collapse the row back onto the canvas. */
 const PANE_CLASS = 'order-last min-h-0 shrink-0 basis-2/5 border-t border-border md:order-first md:w-80 md:basis-auto md:border-r md:border-t-0';
 
+/** A question typed in the composer, asked about the part instead of saved
+ * as a comment. The anchor is the one a comment there would carry (its
+ * `sourceLine` already in document lines). Resolve false (or throw) to keep
+ * the draft open; anything else closes it. */
+export type DiagramAskAI = (
+  question: string,
+  anchor: DiagramAnchor,
+  additionalTargets: readonly DiagramTarget[],
+) => boolean | void | Promise<boolean | void>;
+
 export interface DiagramViewerProps {
   readonly kind: DiagramKind;
   /** The diagram text. With `onSave` this is the saved baseline the pane's
@@ -42,6 +52,8 @@ export interface DiagramViewerProps {
   readonly comments: readonly DiagramComment[];
   /** A comment composed on a part. Absent: clicks open nothing. */
   readonly onCreateComment?: DiagramCreateComment;
+  /** Ask AI from the composer. Absent: the composer offers no Ask AI. */
+  readonly onAskAI?: DiagramAskAI;
   /** Save the pane's text. Absent: there is no Source pane. */
   readonly onSave?: (source: string) => Promise<SaveResult>;
   /** With `onSave`: show the pane read-only (no edit access). */
@@ -92,6 +104,7 @@ export function DiagramViewer({
   theme,
   comments,
   onCreateComment,
+  onAskAI,
   onSave,
   readOnlySource = false,
   sourceOpen = false,
@@ -177,6 +190,21 @@ export function DiagramViewer({
     if (!sourceOpen) cancelComposer();
   }, [cancelComposer, sourceOpen]);
 
+  // Ask AI asks about the part the draft is on; the host's handler decides
+  // whether the question was taken, and a taken question closes the draft
+  // exactly as the markdown composer closes.
+  const composerDraft = commentsState.composer;
+  const askFromComposer = useMemo(() => {
+    if (onAskAI === undefined || composerDraft === null || onCreateComment === undefined) return undefined;
+    return async (question: string): Promise<boolean> => {
+      const anchor = buildDiagramAnchorValue(composerDraft.primary.target, composerDraft.sourceLine);
+      const accepted = await onAskAI(question, anchor, composerDraft.additional.map((extra) => extra.target));
+      if (accepted === false) return false;
+      cancelComposer();
+      return true;
+    };
+  }, [cancelComposer, composerDraft, onAskAI, onCreateComment]);
+
   const overlay = useCallback(
     (handle: DiagramCanvasHandle) => (
       <DiagramOverlay
@@ -199,12 +227,13 @@ export function DiagramViewer({
               disabledReason={commentingDisabledReason}
               onSubmit={(text) => void commentsState.submit(text)}
               onCancel={commentsState.cancel}
+              onAskAI={askFromComposer}
             />
           )
         }
       />
     ),
-    [commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
+    [askFromComposer, commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
   );
 
   const showFallback = render.svgNode === null;

package/components/diagram/index.ts

@@ -6,7 +6,7 @@
  * `graphviz`, `mermaid`, `diagram-anchor`, `diagram-anchor-graphviz`,
  * `diagram-projection`).
  */
-export { DiagramViewer, type DiagramViewerProps } from './DiagramViewer';
+export { DiagramViewer, type DiagramAskAI, type DiagramViewerProps } from './DiagramViewer';
 export { DiagramPopout } from './DiagramPopout';
 export { DiagramPending, DiagramInlineSource, DiagramBlockPending } from './DiagramPending';
 export { isDiagramControlEvent, DIAGRAM_CONTROL_SELECTOR } from './diagramControls';

package/components/html-viewer/HtmlViewer.tsx

@@ -17,6 +17,7 @@ import {
 import type { Annotation, EditorMode, ImageAttachment, InputMethod } from "../../types";
 import { AnnotationType } from "../../types";
 import { copyTextPreservingFocus } from "../../utils/clipboard";
+import { elementIdentityForAskAI } from "../../utils/parser";
 import { getIdentity } from "../../utils/identity";
 import { THUMBS_UP_LABEL } from "../../utils/quickLabels";
 import {
@@ -674,6 +675,13 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       }));
     }, [hook.draftTargets]);
 
+    // Ask AI from a pinpoint draft: which element(s) the question is about,
+    // in the identity lines the feedback export prints (no outline).
+    const askAIElementDetail = useMemo(
+      () => elementIdentityForAskAI(hook.draftTargets) || undefined,
+      [hook.draftTargets],
+    );
+
     useEffect(() => {
       function handler(e: MessageEvent<unknown>) {
         if (e.source !== iframeRef.current?.contentWindow) return;
@@ -1244,9 +1252,10 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
               draftKey={`html:${hook.commentPopover.draftKey}`}
               onSubmit={hook.handleCommentSubmit}
               mentionSource={mentionSource}
-              // Pinpoint clicks open this composer directly, so it carries
-              // the surface's one-click "Looks good" (the global composer
-              // does not: a document-wide thumbs-up is not a thing).
+              // A pinpoint click opens this composer directly (never the
+              // selection toolbar), so it carries the surface's one-click 👍.
+              // It also shows when the composer opens from a text selection's
+              // Comment button: a harmless duplicate of the toolbar 👍.
               onQuickLookGood={hook.handleCommentLooksGood}
               onClose={hook.handleCommentClose}
               skillReferences
@@ -1255,6 +1264,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 kind: "selection",
                 label: "Selected HTML",
                 text: hook.commentPopover.selectedText ?? hook.commentPopover.contextText,
+                ...(askAIElementDetail ? { detail: askAIElementDetail } : {}),
               }}
               targetChips={targetChips}
               onRemoveTargetChip={targetChips ? hook.removeDraftTarget : undefined}