@plannotator/ui 0.50.0 → 0.51.0

package/components/Settings.tsx

@@ -7,6 +7,12 @@ import type { TokenHoverDelay } from '@plannotator/core/token-hover';
 import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType, setReviewAutoViewed } from '../config';
 import { setWebMcpToolsEnabled, useWebMcpToolsEnabled } from '../webmcp/preference';
 import { DIAGRAM_SHADOW_OPTIONS } from '../utils/diagramShadow';
+import {
+  agentToolAppliesWhen,
+  agentToolCostNote,
+  agentToolHostName,
+  type AgentToolSetting,
+} from '../utils/agentToolSetting';
 import { loadDiffFont } from '../utils/diffFonts';
 import { TaterSpritePullup } from './TaterSpritePullup';
 import { getIdentity, regenerateIdentity, setCustomIdentity, isIdentityEditable } from '../utils/identity';
@@ -106,6 +112,14 @@ interface SettingsProps {
    *  `env` is PLANNOTATOR_AUTO_UPDATE when it overrides the config file.
    *  Hosts that omit it get no toggle. */
   autoUpdateSetting?: { env?: boolean };
+  /** The `plannotator` agent tool switch, as the server reports it
+   *  (parseAgentToolSetting of serverConfig: present only when the session's
+   *  host registers the tool). Shown only together with onAgentToolChange;
+   *  hosts that omit them get no row. */
+  agentToolSetting?: AgentToolSetting;
+  /** Saves the agent tool switch (saveAgentToolSetting); rejects with a
+   *  readable Error, which the row shows. */
+  onAgentToolChange?: (enabled: boolean) => Promise<void>;
   /** Current session is a local git review where since-base ISN'T offered
    *  (base ref unresolvable) — the Git tab shows a note that the Git-status
    *  preference can't take effect in THIS repo. */
@@ -269,6 +283,53 @@ function ToggleSwitch({ checked, onChange, label, description, disabled = false
   );
 }
 
+/**
+ * The `plannotator` agent tool switch. The value is the one the NEXT session
+ * uses (the tool list is part of the model's prompt, so a running session
+ * never changes it). Writes go straight to POST /api/config and wait for the
+ * answer, so a failed save is reported and the switch stays where it was.
+ */
+function AgentToolSettingRow({ setting, onChange }: {
+  readonly setting: AgentToolSetting;
+  readonly onChange: (enabled: boolean) => Promise<void>;
+}) {
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const locked = setting.env !== undefined;
+  const change = async (next: boolean) => {
+    if (saving || locked) return;
+    setSaving(true);
+    setError(null);
+    try {
+      await onChange(next);
+    } catch (e) {
+      setError(e instanceof Error && e.message ? e.message : 'Could not save the setting.');
+    } finally {
+      setSaving(false);
+    }
+  };
+  return (
+    <div data-agent-tool-setting={setting.host} aria-busy={saving}>
+      <ToggleSwitch
+        checked={setting.enabled}
+        onChange={(next) => void change(next)}
+        disabled={locked}
+        label="Let the agent open reviews (plannotator tool)"
+        description={
+          locked
+            ? `Set by PLANNOTATOR_AGENT_TOOL in your environment, so it is ${setting.enabled ? 'on' : 'off'} here.`
+            : `${agentToolHostName(setting.host)} can open reviews itself and keep working. ${agentToolCostNote(setting.host)} Applies from ${agentToolAppliesWhen(setting.host)}.`
+        }
+      />
+      {error && (
+        <p role="alert" data-agent-tool-setting-error className="mt-1 text-xs text-destructive">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+
 interface VimSettingsTabProps {
   readonly vimModeEnabled: boolean;
   readonly vimHudEnabled: boolean;
@@ -941,7 +1002,7 @@ const CommentsTab: React.FC = () => {
   );
 };
 
-export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, autoUpdateSetting, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
+export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange, onIdentityChange, origin, mode = 'plan', annotateParity = false, onUIPreferencesChange, externalOpen, onExternalClose, aiProviders = [], gitUser, autoUpdateSetting, agentToolSetting, onAgentToolChange, sinceBaseUnavailable, isCompactTouchLayout = false, onDetectObsidianVaults, agentTerminalAvailable = false, webmcpAvailable = false }) => {
   const webmcpTools = useWebMcpToolsEnabled();
   const autoUpdate = useConfigValue('autoUpdate');
   const [showDialog, setShowDialog] = useState(false);
@@ -1403,6 +1464,17 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
                       </>
                     )}
 
+                    {/* The `plannotator` agent tool switch: only where the
+                        server reports a tool host (Claude Code mod, Pi,
+                        OpenCode 2). Writes agentTool to config.json; applies
+                        to the next session. */}
+                    {agentToolSetting && onAgentToolChange && (
+                      <>
+                        <div className="border-t border-border" />
+                        <AgentToolSettingRow setting={agentToolSetting} onChange={onAgentToolChange} />
+                      </>
+                    )}
+
                     {/* Agent tools (WebMCP). Shown only when the browser
                         exposes document.modelContext; off unregisters the
                         tools for this browser. Cookie-only and idle at its

package/components/TerminalToolsAnnouncementDialog.tsx

@@ -107,7 +107,7 @@ function GitHubMark({ className }: { readonly className?: string }) {
   );
 }
 
-function XMark({ className }: { readonly className?: string }) {
+export function XMark({ className }: { readonly className?: string }) {
   return (
     <svg viewBox="0 0 24 24" className={className} aria-hidden="true" focusable="false">
       <path

package/components/Viewer.tsx

@@ -1434,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) ? (
@@ -1446,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' ? (

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 ?? [];

package/components/ai/DocumentAIChatPanel.tsx

@@ -5,7 +5,7 @@ import { formatRelativeTime, renderChatMarkdown } from '../../utils/aiChatFormat
 import { OverlayScrollArea } from '../OverlayScrollArea';
 import { SparklesIcon } from '../SparklesIcon';
 import { AIProviderBar } from './AIProviderBar';
-import { SessionAskActions, SessionAskStatus, sessionAskErrorTone, type SessionAskAction } from './SessionAskNotice';
+import { SessionAskActions, SessionAskNote, SessionAskStatus, sessionAskErrorTone, type SessionAskAction } from './SessionAskNotice';
 import { submitHint } from '../../utils/platform';
 
 interface DocumentAIChatPanelProps {
@@ -20,10 +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/gone/blocked answer. */
+  /** "Ask this session": the reviewer's choice on a busy answer. */
   onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
-  /** Label of the provider "Ask a separate AI instead" would use; null hides it. */
-  sessionAskFallbackLabel?: string | null;
 }
 
 function truncate(text: string, max = 180): string {
@@ -70,7 +68,6 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
   aiConfig,
   onAIConfigChange,
   onSessionAskAction,
-  sessionAskFallbackLabel,
 }) => {
   const scrollRef = useRef<HTMLDivElement>(null);
   const [generalInput, setGeneralInput] = useState('');
@@ -120,7 +117,6 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
               key={entry.question.id}
               entry={entry}
               onSessionAskAction={onSessionAskAction}
-              sessionAskFallbackLabel={sessionAskFallbackLabel}
             />
           ))}
         </div>
@@ -167,8 +163,7 @@ export const DocumentAIChatPanel: React.FC<DocumentAIChatPanelProps> = ({
 const DocumentQAPair = memo<{
   entry: AIChatEntry;
   onSessionAskAction?: (questionId: string, action: SessionAskAction) => void;
-  sessionAskFallbackLabel?: string | null;
-}>(({ entry, onSessionAskAction, sessionAskFallbackLabel }) => {
+}>(({ entry, onSessionAskAction }) => {
   const { question, response } = entry;
   const renderedResponse = useMemo(
     () => response.text ? renderChatMarkdown(response.text) : null,
@@ -210,7 +205,6 @@ const DocumentQAPair = memo<{
             <p className={`text-xs ${sessionAskErrorTone(response)}`}>{response.error}</p>
             <SessionAskActions
               response={response}
-              fallbackLabel={sessionAskFallbackLabel}
               onAction={onSessionAskAction ? (action) => onSessionAskAction(question.id, action) : undefined}
             />
           </>
@@ -226,6 +220,7 @@ const DocumentQAPair = memo<{
             <span className="ai-streaming-cursor" /> Thinking...
           </span>
         ) : null}
+        {!response.error && <SessionAskNote response={response} />}
       </div>
     </div>
   );

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"
@@ -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>