@plannotator/ui 0.49.0 → 0.51.0

package/components/Viewer.tsx

@@ -1,6 +1,7 @@
 import { generateId } from '../utils/generateId';
 import React, { useRef, useState, useEffect, useLayoutEffect, useMemo, forwardRef, useImperativeHandle, useCallback, lazy, Suspense } from 'react';
 import { createPortal } from 'react-dom';
+import { ImageLightbox } from './ImageLightbox';
 import { AnnotationType, type Block, type Annotation, type EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
 import { applyHighlight, codeBlockClassName, onCodeHighlightSwap } from '../utils/codeHighlight';
 import { paintCodeBlockMark } from '../utils/codeBlockMark';
@@ -1433,6 +1434,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 onAddAnnotation={readOnly ? undefined : onAddAnnotation}
                 readOnly={readOnly}
                 onRestoreReport={onRestoreReport}
+                onAskAI={readOnly ? undefined : onAskAI}
+                askAISourcePath={linkedDocInfo?.filepath ?? sourceInfo}
               />
             </Suspense>
           ) : group.block.type === 'code' && isGraphvizLanguage(group.block.language) ? (
@@ -1445,6 +1448,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                 onAddAnnotation={readOnly ? undefined : onAddAnnotation}
                 readOnly={readOnly}
                 onRestoreReport={onRestoreReport}
+                onAskAI={readOnly ? undefined : onAskAI}
+                askAISourcePath={linkedDocInfo?.filepath ?? sourceInfo}
               />
             </Suspense>
           ) : group.block.type === 'table' ? (
@@ -1780,31 +1785,3 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     </CodePathValidationContext.Provider>
   );
 });
-
-/** Simple lightbox overlay for enlarged image viewing. */
-const ImageLightbox: React.FC<{ src: string; alt: string; onClose: () => void }> = ({ src, alt, onClose }) => {
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose();
-    };
-    window.addEventListener('keydown', handleKeyDown);
-    return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [onClose]);
-
-  return (
-    <div
-      className="fixed inset-0 z-[200] flex flex-col items-center justify-center bg-black/80 backdrop-blur-sm cursor-zoom-out"
-      onClick={onClose}
-    >
-      <img
-        src={src}
-        alt={alt}
-        className="max-w-[90vw] max-h-[85vh] object-contain rounded-lg shadow-2xl"
-        onClick={(e) => e.stopPropagation()}
-      />
-      {alt && (
-        <div className="mt-3 text-sm text-white/70 max-w-[90vw] text-center truncate">{alt}</div>
-      )}
-    </div>
-  );
-};

package/components/ai/AIProviderBar.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { getProviderMeta } from '../ProviderIcons';
-import { type AIProviderOption } from '../../utils/aiProvider';
+import { findSessionBridge, type AIProviderOption } from '../../utils/aiProvider';
 import { ModelSourceHint, modelSourceToolForProvider } from '../ModelSourceHint';
 
 interface AIProviderBarProps {
@@ -30,6 +30,23 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
     );
   }
 
+  // "Ask this session": the session that opened Plannotator is the only thing
+  // Ask AI talks to, so there is no provider or model to choose. Show its label.
+  const sessionBridge = findSessionBridge(providers);
+  if (sessionBridge) {
+    const bridgeMeta = getProviderMeta(sessionBridge.name, sessionBridge.label);
+    const BridgeIcon = bridgeMeta.icon;
+    return (
+      <div
+        className="border-t border-border/50 px-2 py-1.5 flex items-center gap-1.5 text-[11px] text-muted-foreground"
+        data-ai-provider-session-bridge
+      >
+        <BridgeIcon className="w-3.5 h-3.5 flex-shrink-0" />
+        <span className="min-w-0 truncate text-foreground">{bridgeMeta.label}</span>
+      </div>
+    );
+  }
+
   const currentProvider = providers.find(p => p.id === selectedProviderId) ?? providers[0];
   const effectiveProviderId = currentProvider?.id ?? '';
   const models = currentProvider?.models ?? [];
@@ -37,7 +54,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
   const effectiveModel = selectedModel ?? defaultModel?.id ?? '';
   const currentModel = models.find(m => m.id === effectiveModel) ?? defaultModel;
   const reasoningEfforts = currentModel?.reasoningEfforts ?? [];
-  const meta = getProviderMeta(currentProvider?.name ?? 'AI');
+  const meta = getProviderMeta(currentProvider?.name ?? 'AI', currentProvider?.label);
   const Icon = meta.icon;
   // Show only when the selected model actually reports reasoning efforts.
   const showReasoningEffort = !!onReasoningEffortChange && reasoningEfforts.length > 0;
@@ -53,7 +70,7 @@ export const AIProviderBar: React.FC<AIProviderBarProps> = ({
         aria-label="AI provider"
       >
         {providers.map(provider => {
-          const providerMeta = getProviderMeta(provider.name);
+          const providerMeta = getProviderMeta(provider.name, provider.label);
           return (
             <option key={provider.id} value={provider.id}>
               {providerMeta.label}

package/components/ai/DocumentAIChatPanel.tsx

@@ -5,6 +5,7 @@ import { formatRelativeTime, renderChatMarkdown } from '../../utils/aiChatFormat
 import { OverlayScrollArea } from '../OverlayScrollArea';
 import { SparklesIcon } from '../SparklesIcon';
 import { AIProviderBar } from './AIProviderBar';
+import { SessionAskActions, SessionAskNote, SessionAskStatus, sessionAskErrorTone, type SessionAskAction } from './SessionAskNotice';
 import { submitHint } from '../../utils/platform';
 
 interface DocumentAIChatPanelProps {
@@ -19,6 +20,8 @@ interface DocumentAIChatPanelProps {
   aiProviders?: AIProviderOption[];
   aiConfig?: { providerId: string | null; model: string | null; reasoningEffort?: string | null };
   onAIConfigChange?: (config: { providerId?: string | null; model?: string | null; reasoningEffort?: string | null }) => void;
+  /** "Ask this session": the reviewer's choice on a busy answer. */
+  onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
 }
 
 function truncate(text: string, max = 180): string {
@@ -64,6 +67,7 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
   aiProviders = [],
   aiConfig,
   onAIConfigChange,
+  onSessionAskAction,
 }) => {
   const scrollRef = useRef<HTMLDivElement>(null);
   const [generalInput, setGeneralInput] = useState('');
@@ -109,7 +113,11 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
           )}
 
           {messages.map(entry => (
-            <DocumentQAPair key={entry.question.id} entry={entry} />
+            <DocumentQAPair
+              key={entry.question.id}
+              entry={entry}
+              onSessionAskAction={onSessionAskAction}
+            />
           ))}
         </div>
       </OverlayScrollArea>
@@ -152,7 +160,10 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
   );
 };
 
-const DocumentQAPair = memo<{ entry: AIChatEntry }>(({ entry }) => {
+const DocumentQAPair = memo<{
+  entry: AIChatEntry;
+  onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
+}>(({ entry, onSessionAskAction }) => {
   const { question, response } = entry;
   const renderedResponse = useMemo(
     () => response.text ? renderChatMarkdown(response.text) : null,
@@ -190,17 +201,26 @@ const DocumentQAPair = memo<{ entry: AIChatEntry }>(({ entry }) => {
 
       <div className="group relative p-2.5 rounded-lg border border-border/50 bg-popover/50 hover:bg-muted/30 transition-colors">
         {response.error ? (
-          <p className="text-xs text-destructive">{response.error}</p>
+          <>
+            <p className={`text-xs ${sessionAskErrorTone(response)}`}>{response.error}</p>
+            <SessionAskActions
+              response={response}
+              onAction={onSessionAskAction ? (action) => onSessionAskAction(question.id, action) : undefined}
+            />
+          </>
         ) : response.text ? (
           <div className="text-xs">
             {renderedResponse}
             {response.isStreaming && <span className="ai-streaming-cursor inline-block ml-0.5" />}
           </div>
+        ) : response.status ? (
+          <SessionAskStatus response={response} />
         ) : response.isStreaming ? (
           <span className="text-xs text-muted-foreground">
             <span className="ai-streaming-cursor" /> Thinking...
           </span>
         ) : null}
+        {!response.error && <SessionAskNote response={response} />}
       </div>
     </div>
   );

package/components/ai/SessionAskNotice.tsx

@@ -0,0 +1,101 @@
+import React from 'react';
+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';
+
+/**
+ * In-progress line for a question waiting on a busy session. Renders nothing
+ * for any other response, so providers without a bridge are unaffected.
+ */
+export const SessionAskStatus: React.FC<{ response: AIResponse }> = ({ response }) => {
+  if (!response.status) return null;
+  return (
+    <span className="text-xs text-muted-foreground" data-session-ask-status={response.status}>
+      <span className="ai-streaming-cursor" />{' '}
+      {response.status === 'waiting'
+        ? 'Waiting for the session to finish its current turn…'
+        : 'Interrupting the session…'}
+    </span>
+  );
+};
+
+/**
+ * Colour for an answer's error line: a busy session is a choice, not a
+ * failure, so it reads muted; every other error keeps the destructive tone.
+ */
+export function sessionAskErrorTone(response: Pick<AIResponse, 'errorCode'>): string {
+  return response.errorCode === SESSION_ASK_ERROR_CODES.agentBusy ? 'text-muted-foreground' : 'text-destructive';
+}
+
+const buttonClass =
+  'px-2 py-1 rounded-md text-[10px] font-medium transition-colors';
+
+/**
+ * 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: 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;
+}> = ({ 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
+          type="button"
+          onClick={() => onAction('wait')}
+          className={`${buttonClass} bg-primary text-primary-foreground hover:opacity-90`}
+        >
+          Ask when it finishes
+        </button>
+        <button
+          type="button"
+          onClick={() => onAction('interrupt')}
+          className={`${buttonClass} bg-muted text-foreground hover:bg-muted/80`}
+          title="Stops the session's current work, then asks your question"
+        >
+          Interrupt and ask now
+        </button>
+      </div>
+    );
+  }
+
+  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 (
+      <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"
@@ -122,7 +123,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   blockId,
   indexed,
   total,
-  answer: savedAnswer,
+  answer: storedAnswer,
   onAnswer: onLiveAnswer,
   onSaveAnswer,
   saveLabel,
@@ -136,6 +137,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.
@@ -349,7 +357,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
         </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) && (
@@ -378,20 +386,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 +459,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';