@plannotator/ui 0.50.0 → 0.52.0

package/components/AskSessionAnnouncementDialog.tsx

@@ -0,0 +1,329 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { ExternalLink, Pause, Play } from 'lucide-react';
+import { prefersReducedMotion, XMark } from './TerminalToolsAnnouncementDialog';
+import type { AskSessionAgent } from '../utils/askSessionAnnouncement';
+
+/**
+ * One-time announcement for "Ask this session": Ask AI is answered by the
+ * agent session that opened Plannotator (Claude Code, Pi, OpenCode), and
+ * reviews no longer hold that session. Video first, like the terminal-tools
+ * announcement it follows: real footage of a real Claude Code session and the
+ * real review app fills the top of the panel, over one headline, two short
+ * sentences and one action row. Same shell (portal, z-[100], hand-rolled
+ * Escape + Tab wrap + focus restore, backdrop dismiss, capture-phase keydown
+ * that swallows Mod+Enter).
+ *
+ * LAST in each app's first-run dialog chain; the Apps gate rendering through
+ * askSessionAnnouncementEligible and useFirstRunAnnouncementWindow.
+ *
+ * The footage is hosted on plannotator.ai (`apps/marketing/public/assets/`),
+ * not inlined, so the dialog has to look right without it: the poster stays up
+ * while the video buffers, and if the media cannot load the frame keeps its
+ * place and offers the X post instead.
+ */
+
+/** The feature's docs page (goes live with the 0.28.0 release that ships this dialog). */
+export const ASK_SESSION_DOCS_URL = 'https://docs.plannotator.ai/open-source/workflows/ask-this-session';
+
+/** The X post the footage was cut for. */
+export const ASK_SESSION_WATCH_URL = 'https://x.com/plannotator/status/2106875215170899992';
+
+/** Same look as the terminal-tools announcement's outbound actions. */
+const OUTBOUND_ACTION_CLASS =
+  'inline-flex min-h-9 items-center gap-2 rounded-lg border border-border bg-surface-0/40 px-3 text-sm font-medium text-foreground outline-none transition-colors motion-reduce:transition-none hover:bg-surface-1/70 focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-card';
+
+/** Where the marketing deploy publishes `apps/marketing/public/assets/`. */
+const MEDIA_BASE_URL = 'https://plannotator.ai/assets';
+
+export const ASK_SESSION_DEMO = {
+  mp4: `${MEDIA_BASE_URL}/ask-this-session-demo.mp4`,
+  webm: `${MEDIA_BASE_URL}/ask-this-session-demo.webm`,
+  poster: `${MEDIA_BASE_URL}/ask-this-session-poster.jpg`,
+  description:
+    'A code review opened from Claude Code: two lines are selected and asked about in Plannotator, the question arrives in the Claude Code session, and its answer streams back into the Ask AI panel. Then a comment is sent and arrives in Claude Code as a message.',
+} as const;
+
+/** The footage is 1280x800. */
+const DEMO_ASPECT = 1280 / 800;
+
+interface AgentCopy {
+  readonly name: string;
+  /** How the session stays free. OpenCode's plan review still holds the session. */
+  readonly freeLine: string;
+}
+
+const AGENT_COPY: Record<AskSessionAgent, AgentCopy> = {
+  'claude-code': {
+    name: 'Claude Code',
+    freeLine: 'Claude Code stays free while you review, and your decision arrives as a message.',
+  },
+  pi: {
+    name: 'Pi',
+    freeLine: 'Pi stays free while you review, and your decision arrives as a message.',
+  },
+  opencode: {
+    name: 'OpenCode',
+    freeLine: 'Code review and annotate no longer hold the session, and your feedback arrives as a message.',
+  },
+};
+
+interface AskSessionAnnouncementDialogProps {
+  readonly isOpen: boolean;
+  /**
+   * The host whose session is connected to this Plannotator session
+   * (connectedAskSessionAgent); names the agent in the copy. The Apps only
+   * open the dialog while one is connected.
+   */
+  readonly agent: AskSessionAgent;
+  /** Marks the announcement seen and closes it. Also wired to Escape and the backdrop. */
+  readonly onDismiss: () => void;
+  /** Test seam. Defaults to the media query. */
+  readonly reducedMotion?: boolean;
+}
+
+/**
+ * The footage. Muted, looping, inline; autoplays unless the reader asked for
+ * reduced motion, in which case the poster waits behind a play button.
+ */
+function DemoPlayer({ reducedMotion }: { readonly reducedMotion: boolean }) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [playing, setPlaying] = useState(!reducedMotion);
+  const [failed, setFailed] = useState(false);
+
+  const toggle = useCallback(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    if (video.paused) {
+      // Autoplay policies can reject play(); the button simply stays put.
+      void video.play().catch(() => {});
+    } else {
+      video.pause();
+    }
+  }, []);
+
+  return (
+    <div
+      className="group relative w-full overflow-hidden bg-muted"
+      style={{ aspectRatio: String(DEMO_ASPECT) }}
+    >
+      <video
+        ref={videoRef}
+        data-ask-session-demo
+        poster={ASK_SESSION_DEMO.poster}
+        muted
+        playsInline
+        loop
+        autoPlay={!reducedMotion}
+        preload="auto"
+        aria-label={ASK_SESSION_DEMO.description}
+        onPlay={() => setPlaying(true)}
+        onPause={() => setPlaying(false)}
+        onCanPlayThrough={(event) => setPlaying(!event.currentTarget.paused)}
+        onClick={toggle}
+        className="absolute inset-0 h-full w-full object-cover"
+      >
+        <source src={ASK_SESSION_DEMO.mp4} type="video/mp4" />
+        {/* The last source is the one whose error means nothing could load. */}
+        <source src={ASK_SESSION_DEMO.webm} type="video/webm" onError={() => setFailed(true)} />
+      </video>
+
+      {failed ? (
+        <div
+          data-ask-session-demo-unavailable
+          className="absolute inset-0 grid place-items-center bg-background/70 backdrop-blur-sm"
+        >
+          <a
+            href={ASK_SESSION_WATCH_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-10 items-center gap-2 rounded-lg border border-border bg-card px-4 text-sm font-medium text-foreground outline-none hover:bg-surface-1 focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+          >
+            <XMark className="size-3.5" />
+            Watch on X
+          </a>
+        </div>
+      ) : (
+        <button
+          type="button"
+          onClick={toggle}
+          aria-label={playing ? 'Pause demo' : 'Play demo'}
+          data-ask-session-playback={playing ? 'pause' : 'play'}
+          className={
+            playing
+              ? 'absolute bottom-3 left-3 grid size-9 place-items-center rounded-full border border-border/60 bg-background/70 text-foreground opacity-0 outline-none backdrop-blur-sm transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-primary'
+              : 'absolute left-1/2 top-1/2 grid size-16 -translate-x-1/2 -translate-y-1/2 place-items-center rounded-full border border-border/60 bg-background/80 text-foreground shadow-lg outline-none backdrop-blur-sm transition-transform motion-reduce:transition-none hover:scale-105 focus-visible:ring-2 focus-visible:ring-primary'
+          }
+        >
+          {playing ? (
+            <Pause className="size-4" aria-hidden="true" />
+          ) : (
+            <Play className="ml-0.5 size-6 fill-current" aria-hidden="true" />
+          )}
+        </button>
+      )}
+    </div>
+  );
+}
+
+export function AskSessionAnnouncementDialog({
+  isOpen,
+  agent,
+  onDismiss,
+  reducedMotion,
+}: AskSessionAnnouncementDialogProps) {
+  const dismissRef = useRef<HTMLButtonElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const onDismissRef = useRef(onDismiss);
+  const [motionPreference] = useState(() => reducedMotion ?? prefersReducedMotion());
+  const reduced = reducedMotion ?? motionPreference;
+  const copy = AGENT_COPY[agent];
+
+  useEffect(() => {
+    onDismissRef.current = onDismiss;
+  }, [onDismiss]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    previousFocusRef.current = document.activeElement instanceof HTMLElement
+      ? document.activeElement
+      : null;
+    dismissRef.current?.focus();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopPropagation();
+        onDismissRef.current();
+        return;
+      }
+      // Both apps submit their decision on Mod+Enter from a window-level
+      // handler. This listener runs on the capture phase, so swallowing the
+      // chord here stops a keystroke aimed at the announcement from approving
+      // a plan or posting a review behind it.
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
+      if (event.key !== 'Tab') return;
+
+      const dialog = document.querySelector<HTMLElement>('[data-ask-session-announcement-dialog]');
+      const focusable = Array.from(
+        dialog?.querySelectorAll<HTMLElement>('button:not([disabled]), [href], [tabindex]:not([tabindex="-1"])')
+          ?? [],
+      ).filter((element) => element.getAttribute('tabindex') !== '-1');
+      if (focusable.length === 0) return;
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown, true);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown, true);
+      previousFocusRef.current?.focus();
+      previousFocusRef.current = null;
+    };
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[100] flex items-center justify-center bg-background/90 p-4 backdrop-blur-sm"
+      // The dialog collects no decision, so closing it from the backdrop loses nothing.
+      onMouseDown={(event) => {
+        if (event.target === event.currentTarget) onDismissRef.current();
+      }}
+    >
+      <div
+        data-ask-session-announcement-dialog
+        data-ask-session-agent={agent}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="ask-session-announcement-title"
+        aria-describedby="ask-session-announcement-description"
+        // Width follows the viewport height as well as its width: the footage
+        // keeps its aspect ratio, so on a short window the panel narrows until
+        // video plus footer fit instead of scrolling the video out of view.
+        // The 12rem is the footer's height, with the wrap at narrow widths.
+        style={{ width: `min(1120px, 100%, calc((100dvh - 2rem - 12rem) * ${DEMO_ASPECT}))` }}
+        className="flex max-h-[calc(100dvh-2rem)] min-w-0 flex-col overflow-hidden rounded-xl border border-border bg-card shadow-2xl"
+      >
+        <div className="shrink-0 border-b border-border">
+          <DemoPlayer reducedMotion={reduced} />
+        </div>
+
+        <div className="min-h-0 overflow-y-auto px-5 py-5 sm:px-7 sm:py-6">
+          <h2
+            id="ask-session-announcement-title"
+            className="text-balance text-xl font-semibold tracking-tight sm:text-2xl"
+          >
+            Ask {copy.name}, right from Plannotator
+          </h2>
+          <p
+            id="ask-session-announcement-description"
+            className="mt-1 text-pretty text-sm leading-relaxed text-muted-foreground"
+          >
+            Ask AI now goes to the {copy.name} session that opened Plannotator, and the answer
+            streams back here. {copy.freeLine}
+          </p>
+
+          <div className="mt-5 flex flex-wrap items-center gap-x-4 gap-y-3">
+            <p
+              data-ask-session-status="connected"
+              className="inline-flex min-w-0 items-center gap-2 text-sm text-foreground"
+            >
+              <span className="size-2 shrink-0 rounded-full bg-success" aria-hidden="true" />
+              This session is connected. Open Ask AI to try it.
+            </p>
+            {/* The actions wrap as one group, so a narrow panel puts them on their
+                own row under the status line instead of splitting them. */}
+            <div className="ml-auto flex flex-wrap items-center justify-end gap-2">
+              {/* Like the terminal-tools announcement's outbound links: opening
+                  either one does not dismiss the announcement or spend its cookie. */}
+              <a
+                href={ASK_SESSION_WATCH_URL}
+                target="_blank"
+                rel="noopener noreferrer"
+                data-ask-session-watch
+                className={OUTBOUND_ACTION_CLASS}
+              >
+                <XMark className="size-3.5" />
+                Watch on X
+              </a>
+              <a
+                href={ASK_SESSION_DOCS_URL}
+                target="_blank"
+                rel="noopener noreferrer"
+                data-ask-session-learn-more
+                className={OUTBOUND_ACTION_CLASS}
+              >
+                Learn more
+                <ExternalLink className="size-3.5" aria-hidden="true" />
+              </a>
+              <button
+                ref={dismissRef}
+                type="button"
+                onClick={onDismiss}
+                className="min-h-9 rounded-lg bg-primary px-5 text-sm font-medium text-primary-foreground outline-none transition-opacity motion-reduce:transition-none hover:opacity-90 focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-card"
+              >
+                Got it
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}

package/components/BlockRenderer.tsx

@@ -51,7 +51,13 @@ export const BlockRenderer: React.FC<{
   saveQuestionAnswerLabel?: QuestionBlockProps['saveLabel'];
   /** Host actions in a question card's footer (see `QuestionBlock`). */
   renderQuestionFooter?: QuestionBlockProps['renderFooter'];
-}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter }) => {
+  /** Whether answering this question records a decision (see `QuestionBlock`). */
+  questionDecisionRecording?: QuestionBlockProps['decisionRecording'];
+  /** Makes the "Records a decision" tag a toggle (see `QuestionBlock`). */
+  onToggleQuestionDecisionRecording?: QuestionBlockProps['onToggleDecisionRecording'];
+  /** `'none'` hides the card's own status tag (see `QuestionBlock`). */
+  questionStatusTag?: QuestionBlockProps['statusTag'];
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter, questionDecisionRecording, onToggleQuestionDecisionRecording, questionStatusTag }) => {
   switch (block.type) {
     case 'heading': {
       const Tag = `h${block.level || 1}` as React.ElementType;
@@ -178,6 +184,9 @@ export const BlockRenderer: React.FC<{
               onSaveAnswer={onSaveQuestionAnswer}
               saveLabel={saveQuestionAnswerLabel}
               renderFooter={renderQuestionFooter}
+              decisionRecording={questionDecisionRecording}
+              onToggleDecisionRecording={onToggleQuestionDecisionRecording}
+              statusTag={questionStatusTag}
               onOpenLinkedDoc={onOpenLinkedDoc}
               onOpenCodeFile={onOpenCodeFile}
               imageBaseDir={imageBaseDir}

package/components/CommentPopover.tsx

@@ -2,7 +2,6 @@ import React, { useState, useEffect, useMemo, useRef, useCallback, useId } from
 import { createPortal } from 'react-dom';
 import type { ImageAttachment } from '../types';
 import { AttachmentsButton } from './AttachmentsButton';
-import { submitHint } from '../utils/platform';
 import { useDraggable } from '../hooks/useDraggable';
 import { SparklesIcon } from './SparklesIcon';
 import { hasUnsavedCommentContent } from '../utils/commentContent';
@@ -30,6 +29,13 @@ export interface CommentAskAIContext {
   label?: string;
   text?: string;
   sourcePath?: string;
+  /** Agent-facing identity of the selected element(s), for a pinpoint on a
+   *  raw-HTML or live-app surface. Rides with the question; not displayed. */
+  detail?: string;
+  /** 1-based source lines of a markdown text selection (see
+   *  `AIQuestion.scope.lineStart`). Rides with the question; not displayed. */
+  lineStart?: number;
+  lineEnd?: number;
 }
 
 export type CommentAskAIHandler = (
@@ -68,11 +74,14 @@ interface CommentPopoverProps {
    */
   onSubmit: (text: string, images?: ImageAttachment[], mentions?: readonly string[]) => void;
   /**
-   * One-click "Looks good" action (comment-only HTML/live surfaces, where
-   * pinpoint clicks open this composer directly and never see the selection
-   * toolbar's 👍). Renders a thumbs-up button in the footer; disabled once
-   * the user has typed or attached anything, so a click can never discard a
-   * draft. The parent owns annotation creation and closing.
+   * One-click 👍 "Looks good" (comment-only HTML / live-app surfaces, where a
+   * pinpoint click opens this composer directly and never shows the selection
+   * toolbar's 👍). Renders an emoji-only button beside Save, named "Looks
+   * good" for assistive tech and in its tooltip; disabled once anything is
+   * typed or attached so a click can never discard a draft. It takes no
+   * keyboard shortcut: Enter / Mod+Enter still Save. Like Save, a click
+   * clears the `draftKey` draft and returns focus to the opener. The parent
+   * owns annotation creation and closing. Absent renders nothing.
    */
   onQuickLookGood?: () => void;
   /** Optional live draft observer for submit paths outside the popover. */
@@ -590,18 +599,33 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   const canAskAI = !!onAskAI && !askAIDisabled && text.trim().length > 0;
   const showsSkillMenu = skillAc.menu !== null;
 
-  // Shared by both footers. Disabled once anything is typed or attached so a
-  // click can never discard a draft; with content present, Save is the path.
+  // Shared by both footers, sits beside Save. Emoji-only like the selection
+  // toolbar's 👍 (same hover tint). Disabled once anything is typed or
+  // attached so a click can never discard a draft; with content, Save is the
+  // path. A plain click handler only: Enter / Mod+Enter stay on Save.
+  // The grey-out is an inline filter, not a Tailwind filter utility: this
+  // file is scanned into the pinned guides.show viewer CSS, and every class
+  // below already exists there, so the 👍 adds nothing to that bundle.
+  const handleQuickLookGood = () => {
+    if (!onQuickLookGood || hasUnsavedContent) return;
+    if (draftKey) draftStore.delete(draftKey);
+    onQuickLookGood();
+    restoreOpeningFocus();
+  };
   const quickLookGoodButton = onQuickLookGood ? (
     <button
       type="button"
-      onClick={onQuickLookGood}
+      onClick={handleQuickLookGood}
       disabled={hasUnsavedContent}
-      className="inline-flex items-center gap-1 px-2 py-1.5 text-xs font-medium rounded-md text-muted-foreground hover:text-foreground hover:bg-green-500/10 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
-      title={hasUnsavedContent ? 'Clear the comment to use Looks good' : 'Add "Looks good" without typing'}
+      aria-label="Looks good"
+      title={hasUnsavedContent ? 'Looks good (clear the comment to use it)' : 'Looks good'}
+      data-quick-look-good="true"
+      data-pn-touch-target="true"
+      data-pn-touch-target-icon="true"
+      style={hasUnsavedContent ? { filter: 'grayscale(1)' } : undefined}
+      className="inline-flex h-7 w-7 items-center justify-center rounded-md text-sm leading-none hover:bg-green-500/10 outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:opacity-40 disabled:cursor-not-allowed disabled:hover:bg-transparent transition-colors"
     >
       <span aria-hidden="true">👍</span>
-      Looks good
     </button>
   ) : null;
 
@@ -723,9 +747,6 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               >
                 {isGlobal ? 'Add' : 'Save'}
               </button>
-              {!coarsePointer && (
-                <span className="text-[10px] text-muted-foreground">{submitHint}</span>
-              )}
               {quickLookGoodButton}
               {onAskAI && (
                 <button
@@ -879,9 +900,6 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           >
             {isGlobal ? 'Add' : 'Save'}
           </button>
-          {!coarsePointer && (
-            <span className="text-[10px] text-muted-foreground">{submitHint}</span>
-          )}
           {quickLookGoodButton}
           {onAskAI && (
             <button

package/components/CompletionOverlay.tsx

@@ -25,7 +25,10 @@ const ChatBubbleIcon = () => (
 // ---------------------------------------------------------------------------
 
 interface CompletionOverlayProps {
-  submitted: 'approved' | 'denied' | 'feedback' | 'exited' | null | false;
+  /** `done`: the session finished with nothing sent (an annotate Done with
+   *  no feedback). Neutral styling. `done` and `exited` (Close) send nothing,
+   *  so neither shows the "response has been sent" line. */
+  submitted: 'approved' | 'denied' | 'feedback' | 'done' | 'exited' | null | false;
   title: string;
   subtitle: string;
   agentLabel: string;
@@ -43,16 +46,20 @@ export function CompletionOverlay({ submitted, title, subtitle, agentLabel, link
   if (!submitted) return null;
 
   const isApproved = submitted === 'approved';
+  const isDone = submitted === 'done';
+  const sentNothing = isDone || submitted === 'exited';
 
   return (
-    <div className="fixed inset-0 z-[100] bg-background flex items-center justify-center">
+    <div className="fixed inset-0 z-[100] bg-background flex items-center justify-center" data-completion-state={submitted}>
       <div className="text-center space-y-6 max-w-md px-8">
         <div
           className={`mx-auto w-16 h-16 rounded-full flex items-center justify-center ${
-            isApproved ? 'bg-success/20 text-success' : 'bg-accent/20 text-accent'
+            isApproved ? 'bg-success/20 text-success'
+            : isDone ? 'bg-muted text-muted-foreground'
+            : 'bg-accent/20 text-accent'
           }`}
         >
-          {isApproved ? <CheckIcon /> : <ChatBubbleIcon />}
+          {isApproved || isDone ? <CheckIcon /> : <ChatBubbleIcon />}
         </div>
 
         <div className="space-y-2">
@@ -109,7 +116,7 @@ export function CompletionOverlay({ submitted, title, subtitle, agentLabel, link
                   </label>
                   <p className="text-xs text-muted-foreground/60">You can change the delay in Settings.</p>
                 </>
-              ) : (
+              ) : sentNothing ? null : (
                 <p className="text-xs text-muted-foreground/60">Your response has been sent.</p>
               )}
             </>

package/components/DecisionControl.tsx

@@ -7,7 +7,6 @@ import { ActionMenuDivider, ActionMenuItem } from './ActionMenu';
 import { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog';
 import { useDismissablePopover } from '../hooks/useDismissablePopover';
 import { useCompactTouchLayout } from '../hooks/useIsMobile';
-import { submitHint } from '../utils/platform';
 import { cn } from '../lib/utils';
 import type {
   DecisionActionId,
@@ -228,8 +227,7 @@ export const DecisionNoteDialog: React.FC<{
           disabled={disabled}
           autoFocus={!isCompactTouchLayout}
         />
-        <div className="mt-3 flex items-center justify-between gap-2">
-          <span className="text-[11px] leading-snug text-muted-foreground">{submitHint}</span>
+        <div className="mt-3 flex items-center justify-end gap-2">
           <Button
             variant={toneButtonVariant(composer.tone)}
             size="xs"
@@ -571,10 +569,7 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
                 onCancel={backToMenu}
                 placeholder={activeItem.composer.placeholder}
               />
-              <div className="mt-2 flex items-center justify-between gap-2 px-0.5">
-                <span className="text-[11px] leading-snug text-muted-foreground">
-                  {submitHint} send · Esc back, note kept
-                </span>
+              <div className="mt-2 flex items-center justify-end gap-2 px-0.5">
                 <Button
                   variant={toneButtonVariant(activeItem.composer.tone)}
                   size="xs"

package/components/DiagramBlock.tsx

@@ -9,7 +9,9 @@ import { getIdentity } from '../utils/identity';
 import { createRuntimeRetryEpoch } from '../utils/runtimeRetry';
 import { DiagramAnchorClaims, DiagramAnchorClaimsContext } from './diagram/anchorClaims';
 import { DiagramPending, DiagramInlineSource } from './diagram/DiagramPending';
-import { DiagramViewer } from './diagram/DiagramViewer';
+import { DiagramViewer, type DiagramAskAI } from './diagram/DiagramViewer';
+import type { CommentAskAIHandler } from './CommentPopover';
+import { diagramAskAIContext } from '../utils/diagramAskAI';
 import { svgContentSize } from './diagram/svgContentSize';
 import type { DiagramComment, DiagramCreateComment } from './diagram/useDiagramComments';
 import type { DiagramRenderState } from './diagram/useDiagramRender';
@@ -77,6 +79,13 @@ export interface DiagramBlockProps {
    * `attempted`, the ones whose part is gone as `unanchored`, so the host's
    * panel shows the same "Unanchored" chip a text comment gets. */
   onRestoreReport?: (report: AnnotationRestoreReport) => void;
+  /** The document's Ask AI handler (the one the markdown composer takes).
+   * With it the diagram composer offers "Ask AI", and the question carries
+   * the part's identity and the bounded diagram source as `detail`. Absent:
+   * no Ask AI, exactly as before. */
+  onAskAI?: CommentAskAIHandler;
+  /** The document's path, sent with an Ask AI question (`sourcePath`). */
+  askAISourcePath?: string;
 }
 
 const NO_ANNOTATIONS: readonly Annotation[] = [];
@@ -90,6 +99,8 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
   onAddAnnotation,
   readOnly = false,
   onRestoreReport,
+  onAskAI,
+  askAISourcePath,
 }) => {
   const label = LABELS[kind];
   const rootRef = useRef<HTMLDivElement | null>(null);
@@ -208,6 +219,37 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
     };
   }, [block.id, onAddAnnotation, readOnly]);
 
+  // A fence's offset is its own opening line; a whole-file diagram source
+  // overrides it with 0 (see Block.diagramSourceLineOffset).
+  const sourceLineOffset = block.diagramSourceLineOffset ?? block.startLine;
+
+  const handleAskAI = useMemo<DiagramAskAI | undefined>(() => {
+    if (readOnly || onAskAI === undefined) return undefined;
+    return (question, anchor, additionalTargets) =>
+      onAskAI(
+        question,
+        diagramAskAIContext({
+          kind,
+          anchor,
+          additionalTargets,
+          source: block.content,
+          sourceLineOffset,
+          sourcePath: askAISourcePath,
+        }),
+      );
+  }, [askAISourcePath, block.content, kind, onAskAI, readOnly, sourceLineOffset]);
+
+  // The popout covers the panel the answer streams into, so a question
+  // asked there closes it once the host takes the question.
+  const handlePopoutAskAI = useMemo<DiagramAskAI | undefined>(() => {
+    if (handleAskAI === undefined) return undefined;
+    return async (question, anchor, additionalTargets) => {
+      const accepted = await handleAskAI(question, anchor, additionalTargets);
+      if (accepted !== false) setIsExpanded(false);
+      return accepted;
+    };
+  }, [handleAskAI]);
+
   const [resolution, setResolution] = useState<ReadonlyMap<string, boolean> | null>(null);
   const svgReady = renderState?.svgNode != null;
   const renderFailed = renderState !== null && renderState.error !== null && !svgReady;
@@ -292,9 +334,7 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
     onCreateComment: handleCreate,
     selectedCommentId,
     onSelectComment: onSelectAnnotation,
-    // A fence's offset is its own opening line; a whole-file diagram source
-    // overrides it with 0 (see Block.diagramSourceLineOffset).
-    sourceLineOffset: block.diagramSourceLineOffset ?? block.startLine,
+    sourceLineOffset,
     retryToken,
   };
 
@@ -355,6 +395,7 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
             <DiagramViewer
               {...viewerProps}
               renderId={`${kind}-${block.id}`}
+              onAskAI={handleAskAI}
               onResolutionChange={setResolution}
               onRenderState={setRenderState}
               renderFallback={renderFallback}
@@ -370,6 +411,7 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
             onClose={() => setIsExpanded(false)}
             title={`${label} diagram`}
             renderId={`${kind}-${block.id}-popout`}
+            onAskAI={handlePopoutAskAI}
             dataAttributes={{ 'data-block-id': block.id }}
           />
         </Suspense>

package/components/DocBadges.tsx

@@ -23,7 +23,9 @@ import { OpenInAppButton } from './OpenInAppButton';
 
 export interface LinkedDocBadgeInfo {
   filepath: string;
-  onBack: () => void;
+  /** Leave the document. Optional for `folder-file`: absent shows no Close
+   *  (a file of a review of several files, which the switcher moves between). */
+  onBack?: () => void;
   label?: string;
   backLabel?: string;
   variant?: 'breadcrumb' | 'folder-file';
@@ -198,13 +200,15 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
       {!isRow && linkedDocInfo && (
         linkedDocInfo.variant === 'folder-file' ? (
           <div className="flex items-center gap-2">
-            <button
-              type="button"
-              onClick={linkedDocInfo.onBack}
-              className="rounded-sm text-[9px] font-medium text-primary transition-colors hover:text-primary/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
-            >
-              Close
-            </button>
+            {linkedDocInfo.onBack && (
+              <button
+                type="button"
+                onClick={linkedDocInfo.onBack}
+                className="rounded-sm text-[9px] font-medium text-primary transition-colors hover:text-primary/80 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+              >
+                Close
+              </button>
+            )}
             <span
               className="truncate rounded bg-muted/50 px-1.5 py-0.5 text-[9px] text-muted-foreground max-w-[220px]"
               title={linkedDocInfo.filepath}