@plannotator/ui 0.52.1 → 0.53.0

package/components/blocks/QuestionBlock.tsx

@@ -1,16 +1,19 @@
-import React, { useId, useMemo, useRef, useState } from 'react';
+import React, { useEffect, useId, useMemo, useRef, useState } from 'react';
 import {
   canonicalQuestionAnswer,
   emptyQuestionAnswer,
   isQuestionAnswerEmpty,
+  isRecommendedQuestionAnswer,
   questionStatus,
   recommendedQuestionAnswer,
   type IndexedQuestion,
   type ParsedQuestion,
   type QuestionAnswer,
+  type QuestionStatus,
 } from '@plannotator/core/question-block';
 import { InlineMarkdown } from '../InlineMarkdown';
 import { QuestionContext } from './QuestionContext';
+import { HostTitle } from '../HostTitle';
 
 /**
  * A `:::question` block rendered as an answer card (the approved "Card"
@@ -56,14 +59,25 @@ const now = (): number => (typeof performance !== 'undefined' ? performance.now(
 
 const cx = (...parts: Array<string | false | null | undefined>) => parts.filter(Boolean).join(' ');
 
+/** The box every pill in the eyebrow shares (the status tags, the decision
+ *  tags, the toggle and the split tag): one height, one line-height, and a
+ *  1px border on all of them (transparent unless the tone draws it), so the
+ *  dashed "Open" tag is no taller than the rest. The pill group itself is a
+ *  flex row centred on its axis, so no pill rides its own baseline (the split
+ *  tag's baseline came from its icon-only switch, which lifted it).
+ *  `align-[1px]` does nothing inside that flex row; it stays because it is
+ *  the only use of the class, and dropping it would change the stylesheet
+ *  the guides.show viewer pins (a deploy for no visible change). */
+const PILL = 'annotation-exclude select-none inline-flex h-[18px] items-center gap-1 whitespace-nowrap rounded border px-1.5 align-[1px] text-[10.5px] font-semibold leading-4 tracking-[0.03em]';
+
 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]',
-      tone === 'rec' && 'bg-primary/15 text-primary',
-      tone === 'ok' && 'bg-success/15 text-success',
-      tone === 'skip' && 'bg-muted text-muted-foreground',
-      tone === 'open' && 'border border-dashed border-border text-muted-foreground',
+      PILL,
+      tone === 'rec' && 'border-transparent bg-primary/15 text-primary',
+      tone === 'ok' && 'border-transparent bg-success/15 text-success',
+      tone === 'skip' && 'border-transparent bg-muted text-muted-foreground',
+      tone === 'open' && 'border-dashed border-border text-muted-foreground',
       className,
     )}
     style={style}
@@ -85,15 +99,18 @@ 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`. */
+/** Draws a decision tag in its "off" state: the same words with a dotted
+ *  outline instead of the tinted fill, faded. The theme's muted-foreground
+ *  alone is exactly the "Open" tag's color beside it, so the off tag read as
+ *  barely dimmer than an on one. Text, icon and outline (all `currentColor`)
+ *  are muted-foreground mixed 55% with transparent: the look of
+ *  `opacity: 0.55` on the tag, without `opacity`, which would also fade the
+ *  keyboard focus ring (a `ring-primary` box-shadow on the tag's buttons)
+ *  that must stay at full strength. 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)',
+  color: 'color-mix(in oklab, var(--muted-foreground) 55%, transparent)',
   outline: '1px dotted currentColor',
   outlineOffset: '-1px',
 };
@@ -164,6 +181,15 @@ export interface QuestionBlockProps {
    *  Skipped) so the host can draw its own; the decision tags stay. Default
    *  `'card'`. */
   statusTag?: 'card' | 'none';
+  /** The host's own words for the card's status tag, per question (ui seam;
+   *  the Plannotator Inbox says "Not sent" for a pick it has saved but not
+   *  sent, where the card would say "Answered"). Return undefined for the
+   *  card's own tag. Absent: today's tags. Ignored with `statusTag: 'none'`. */
+  statusLabel?: (question: IndexedQuestion, status: QuestionStatus) => QuestionStatusLabel | undefined;
+  /** Host content drawn right under the prompt (a host note such as "Replaces
+   *  <an earlier question>"), given the question. Return null for none.
+   *  Absent: nothing is drawn there (today's card). */
+  renderBelowPrompt?: (question: IndexedQuestion) => React.ReactNode;
   onOpenLinkedDoc?: (path: string) => void;
   onOpenCodeFile?: (path: string) => void;
   imageBaseDir?: string;
@@ -173,6 +199,12 @@ export interface QuestionBlockProps {
   onNavigateAnchor?: (hash: string) => void;
 }
 
+/** A host's status tag (`statusLabel`): its words, and the tone of one of the card's own tags (default `open`). */
+export interface QuestionStatusLabel {
+  label: string;
+  tone?: 'ok' | 'open' | 'skip';
+}
+
 export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   blockId,
   indexed,
@@ -187,6 +219,8 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   onToggleDecisionRecording,
   onOpenDecision,
   statusTag = 'card',
+  statusLabel,
+  renderBelowPrompt,
   onOpenLinkedDoc,
   onOpenCodeFile,
   imageBaseDir,
@@ -256,6 +290,10 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const noteOpen = notePinned ?? !!answer?.note?.trim();
   const pressRef = useRef<{ x: number; y: number; touch: boolean } | null>(null);
   const noteRef = useRef<HTMLTextAreaElement>(null);
+  const cardRef = useRef<HTMLFieldSetElement>(null);
+  // Accept recommended (and Use) go away once clicked: focus moves to what
+  // the click filled in, never to the page.
+  const focusAfterAcceptRef = useRef(false);
   const lastPickRef = useRef<{ label: string; before: QuestionAnswer | undefined; at: number } | null>(null);
 
   const inline = (text: string) => (
@@ -274,11 +312,30 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   // A note alone does not change a settled choice: the [x] stays drawn (and
   // the status stays Settled) until the reviewer picks, fills Other or skips.
   const status = questionStatus(question, answer);
+  const hostStatus = statusTag === 'none' ? undefined : statusLabel?.(indexed, status);
   const answered = status === 'answered';
   const skipped = status === 'skipped';
   const settled = status === 'settled';
   const settledLabels = question.choices.filter((c) => c.settled).map((c) => c.label);
   const hasRecommendation = question.choices.some((c) => c.recommended) || !!question.suggestedText;
+  // "Accept recommended" stays offered on a pick-any question whose
+  // recommendation names choices until the answer is exactly those choices:
+  // ticking one box must not take away the one click that ticks the rest. A
+  // pick-one or text question answered any way, a question with a settled
+  // choice, and a pick-any question recommending only a suggestion (whose
+  // Suggested line goes once the card is answered, so Accept would clear the
+  // ticks for something no longer shown) offer it no more.
+  const offerAccept = !readOnly && hasRecommendation && !settled && (
+    !answered
+    || (question.kind === 'multi'
+      && question.choices.some((c) => c.recommended)
+      && !question.choices.some((c) => c.settled)
+      && !isRecommendedQuestionAnswer(
+        answer!,
+        question.choices.filter((c) => c.recommended).map((c) => c.label),
+        question.suggestedText,
+      ))
+  );
   const selected = answered || skipped ? answer!.selected : settledLabels;
   const base = answer ?? emptyQuestionAnswer(indexed);
 
@@ -332,8 +389,25 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
 
   const acceptRecommended = () => {
     const next = recommendedQuestionAnswer(indexed, base);
-    if (next) commit(next);
+    if (!next) return;
+    focusAfterAcceptRef.current = true;
+    commit(next);
   };
+  // Runs after the render that drew the accepted answer (and once more at
+  // most, should the host not redraw it): the first checked choice, else the
+  // field holding the suggestion.
+  useEffect(() => {
+    if (!focusAfterAcceptRef.current) return;
+    focusAfterAcceptRef.current = false;
+    const card = cardRef.current;
+    if (!card) return;
+    // Focus still on something in the card (the button was not removed): leave it.
+    const active = document.activeElement;
+    if (active && active !== document.body && card.contains(active)) return;
+    const target = card.querySelector<HTMLElement>('input:checked:not(:disabled)')
+      ?? card.querySelector<HTMLElement>('textarea:not(:disabled), input[type="text"]:not(:disabled)');
+    target?.focus({ preventScroll: true });
+  });
 
   const toggleNote = () => {
     const opening = !noteOpen;
@@ -394,12 +468,33 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     ? (recordingOn ? 'on' : 'off')
     : undefined;
 
-  const describedBy = [question.context ? contextId : null, question.kind === 'text' && question.suggestedText && !answered ? suggestId : null]
+  const describedBy = [question.context ? contextId : null, question.suggestedText && !answered ? suggestId : null]
     .filter(Boolean)
     .join(' ') || undefined;
 
+  // The suggestion the agent wrote that is not one of the choices (a choice
+  // question's `Recommended:` naming none of them; a text question's whole
+  // suggestion): "Accept recommended" fills it in, so the card shows it.
+  const suggestedLine = question.suggestedText && !answered && (
+    <div id={suggestId} className="mt-2 flex items-start gap-2 text-[12.5px] text-muted-foreground" data-question-suggested="">
+      <span className="min-w-0 flex-1">
+        <Tag tone="rec">Suggested</Tag> {inline(question.suggestedText)}
+      </span>
+      {!readOnly && (
+        <button
+          type="button"
+          onClick={acceptRecommended}
+          className="shrink-0 rounded-md bg-primary/15 px-2.5 py-[3px] text-xs font-medium text-primary hover:bg-primary/25 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+        >
+          Use
+        </button>
+      )}
+    </div>
+  );
+
   return (
     <fieldset
+      ref={cardRef}
       className={cx(
         'question-block my-5 min-w-0 rounded-[10px] border px-3.5 pb-2.5 pt-3',
         // Native radios/checkboxes follow the theme's mode. ThemeProvider marks
@@ -422,7 +517,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     >
       <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">
+        <span className="ml-auto inline-flex items-center gap-1">
           {question.decision && <><Tag tone="rec"><DiamondGlyph />Decision</Tag>{' '}</>}
           {decisionCapable && (decisionOpenable ? (
             // Two targets in one tag: the diamond switches recording, the
@@ -435,27 +530,26 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
             // meet the spacing exception: nothing else to click within 12 px
             // of their centre line.
             <><span
-              className="annotation-exclude select-none inline-flex items-stretch whitespace-nowrap rounded align-[1px] text-[10.5px] font-semibold tracking-[0.03em] bg-primary/15 text-primary"
+              className="annotation-exclude select-none inline-flex h-[18px] items-stretch whitespace-nowrap rounded border border-transparent text-[10.5px] font-semibold leading-4 tracking-[0.03em] bg-primary/15 text-primary"
               style={recordingOn ? undefined : DECISION_OFF_STYLE}
               data-pinpoint-ignore=""
               data-question-decision-tag=""
             >{decisionToggleable ? (
-              <button
+              <HostTitle title="Record as a decision"><button
                 type="button"
                 aria-pressed={recordingOn}
                 aria-label="Record as a decision"
-                title="Record as a decision"
                 onClick={() => onToggleDecisionRecording!(question.key, !recordingOn)}
                 className="relative inline-flex cursor-pointer items-center rounded pl-1.5 pr-0.5 before:absolute before:-inset-1.5 before:content-[''] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
                 data-question-decision-toggle=""
-              ><DiamondGlyph /></button>
+              ><DiamondGlyph /></button></HostTitle>
             ) : (
               <span className="inline-flex items-center pl-1.5 pr-0.5"><DiamondGlyph /></span>
             )}<button
               type="button"
               aria-haspopup="dialog"
               onClick={(event) => onOpenDecision!(question.key, event.currentTarget)}
-              className="relative cursor-pointer rounded py-px pl-0.5 pr-1.5 hover:underline underline-offset-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+              className="relative cursor-pointer rounded pl-0.5 pr-1.5 hover:underline underline-offset-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
               data-question-decision-open=""
             >Records a decision</button></span>{' '}</>
           ) : decisionToggleable ? (
@@ -465,7 +559,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
               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"
+              className={cx(PILL, 'cursor-pointer border-transparent 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=""
@@ -475,7 +569,8 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
           ) : (
             <><Tag tone="rec" style={DECISION_OFF_STYLE}><DiamondGlyph />Records a decision</Tag>{' '}</>
           ))}
-          {statusTag !== 'none' && (
+          {statusTag !== 'none' && hostStatus && <Tag tone={hostStatus.tone ?? 'open'}>{hostStatus.label}</Tag>}
+          {statusTag !== 'none' && !hostStatus && (
             <>
               {status === 'answered' && <Tag tone="ok"><CheckGlyph />Answered</Tag>}
               {status === 'settled' && <Tag tone="ok"><CheckGlyph />Settled</Tag>}
@@ -489,6 +584,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
       <p id={promptId} className="m-0 text-[15px] font-semibold leading-[1.45] text-foreground" data-question-part="prompt">
         {inline(question.prompt)}
       </p>
+      {renderBelowPrompt?.(indexed)}
       {(question.decision || (decisionCapable && 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"
@@ -530,22 +626,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
 
       {question.kind === 'text' ? (
         <>
-          {question.suggestedText && !answered && (
-            <div id={suggestId} className="mt-2 flex items-start gap-2 text-[12.5px] text-muted-foreground">
-              <span className="min-w-0 flex-1">
-                <Tag tone="rec">Suggested</Tag> {inline(question.suggestedText)}
-              </span>
-              {!readOnly && (
-                <button
-                  type="button"
-                  onClick={acceptRecommended}
-                  className="shrink-0 rounded-md bg-primary/15 px-2.5 py-[3px] text-xs font-medium text-primary hover:bg-primary/25 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
-                >
-                  Use
-                </button>
-              )}
-            </div>
-          )}
+          {suggestedLine}
           <textarea
             className={cx(
               // annotation-exclude: typed text is not document text, so a
@@ -561,65 +642,71 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
           />
         </>
       ) : (
-        <div
-          className={cx('mt-2.5 grid gap-0.5', skipped && 'opacity-55')}
-          role={inputType === 'radio' ? 'radiogroup' : 'group'}
-          aria-labelledby={promptId}
-        >
-          {question.choices.map((choice) => {
-            const checked = selected.includes(choice.label);
-            return (
-              <label
-                key={choice.label}
-                className={cx(
-                  'flex items-start gap-2.5 rounded-[7px] px-[9px] py-1.5 transition-colors',
-                  readOnly ? 'cursor-default' : 'cursor-pointer hover:bg-muted/45',
-                  checked && 'bg-primary/12 hover:bg-primary/12',
-                )}
-                data-question-option=""
-                onPointerDown={onRowPointerDown}
-                onClickCapture={(event) => onRowClick(event, choice.label)}
-              >
+        <>
+          {suggestedLine}
+          <div
+            className={cx('mt-2.5 grid gap-0.5', skipped && 'opacity-55')}
+            role={inputType === 'radio' ? 'radiogroup' : 'group'}
+            aria-labelledby={promptId}
+          >
+            {question.choices.map((choice) => {
+              const checked = selected.includes(choice.label);
+              return (
+                <label
+                  key={choice.label}
+                  className={cx(
+                    'flex items-start gap-2.5 rounded-[7px] px-[9px] py-1.5 transition-colors',
+                    readOnly ? 'cursor-default' : 'cursor-pointer hover:bg-muted/45',
+                    checked && 'bg-primary/12 hover:bg-primary/12',
+                  )}
+                  data-question-option=""
+                  onPointerDown={onRowPointerDown}
+                  onClickCapture={(event) => onRowClick(event, choice.label)}
+                >
+                  <input
+                    type={inputType}
+                    name={groupName}
+                    checked={checked}
+                    onChange={(e) => pick(choice.label, e.target.checked)}
+                    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" data-question-part="choice">
+                    <span className="font-[550]">{inline(choice.label)}</span>
+                    {choice.description && (
+                      <span className="text-muted-foreground"> — {inline(choice.description)}</span>
+                    )}
+                    {choice.recommended && <> <Tag tone="rec">Recommended</Tag></>}
+                  </span>
+                </label>
+              );
+            })}
+            {/* A read-only card with no Other answer has nothing to show there (it drew a bare "+"). */}
+            {(!readOnly || otherOn) && (
+              <div className="flex items-center gap-2.5 rounded-[7px] px-[9px] py-[5px]">
+                <span
+                  aria-hidden="true"
+                  className={cx(
+                    'annotation-exclude select-none grid h-[15px] w-[15px] shrink-0 place-items-center border-[1.5px] text-[11px] leading-none',
+                    question.kind === 'multi' ? 'rounded-[3px]' : 'rounded-full',
+                    otherOn ? 'border-solid border-primary bg-primary text-primary-foreground' : 'border-dashed border-border text-muted-foreground',
+                  )}
+                >
+                  {otherOn ? <CheckGlyph /> : '+'}
+                </span>
                 <input
-                  type={inputType}
-                  name={groupName}
-                  checked={checked}
-                  onChange={(e) => pick(choice.label, e.target.checked)}
-                  className="mt-[3px] h-[15px] w-[15px] shrink-0 cursor-pointer accent-primary disabled:cursor-default"
+                  type="text"
+                  value={other}
+                  onChange={(e) => setOther(e.target.value)}
                   disabled={readOnly}
+                  placeholder={readOnly ? '' : 'Other…'}
+                  aria-label={number > 0 ? `Other answer to question ${number}` : 'Other answer'}
+                  className="annotation-exclude min-w-0 flex-1 border-0 border-b border-transparent bg-transparent py-[3px] text-[13.5px] text-foreground outline-none placeholder:text-muted-foreground/70 focus:border-ring"
                 />
-                <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>
-                  )}
-                  {choice.recommended && <> <Tag tone="rec">Recommended</Tag></>}
-                </span>
-              </label>
-            );
-          })}
-          <div className="flex items-center gap-2.5 rounded-[7px] px-[9px] py-[5px]">
-            <span
-              aria-hidden="true"
-              className={cx(
-                'annotation-exclude select-none grid h-[15px] w-[15px] shrink-0 place-items-center border-[1.5px] text-[11px] leading-none',
-                question.kind === 'multi' ? 'rounded-[3px]' : 'rounded-full',
-                otherOn ? 'border-solid border-primary bg-primary text-primary-foreground' : 'border-dashed border-border text-muted-foreground',
-              )}
-            >
-              {otherOn ? <CheckGlyph /> : '+'}
-            </span>
-            <input
-              type="text"
-              value={other}
-              onChange={(e) => setOther(e.target.value)}
-              disabled={readOnly}
-              placeholder={readOnly ? '' : 'Other…'}
-              aria-label={number > 0 ? `Other answer to question ${number}` : 'Other answer'}
-              className="annotation-exclude min-w-0 flex-1 border-0 border-b border-transparent bg-transparent py-[3px] text-[13.5px] text-foreground outline-none placeholder:text-muted-foreground/70 focus:border-ring"
-            />
+              </div>
+            )}
           </div>
-        </div>
+        </>
       )}
 
       {noteOpen && (!readOnly || !!answer?.note?.trim()) && (
@@ -674,7 +761,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
           {/* Plannotator's own footer (no host actions, no save bar) keeps the
               Accept button as the one right-aligned item. */}
           {!hasHostFooter && !dirty ? (
-            !readOnly && !answered && !settled && hasRecommendation && (
+            offerAccept && (
               <button
                 type="button"
                 onClick={acceptRecommended}
@@ -685,7 +772,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
             )
           ) : (
             <div className="ml-auto flex items-center gap-1">
-              {!readOnly && !answered && !settled && hasRecommendation && (
+              {offerAccept && (
                 <button
                   type="button"
                   onClick={acceptRecommended}

package/components/diagram/DiagramViewer.tsx

@@ -1,4 +1,4 @@
-import { lazy, Suspense, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { lazy, Suspense, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { buildDiagramAnchorValue, type DiagramAnchor, type DiagramKind, type DiagramTarget } from '@plannotator/core/diagram-anchor';
 import { cn } from '../../lib/utils';
 import { diagramFamilyOf } from '../../utils/diagram-anchor';
@@ -43,6 +43,14 @@ export type DiagramAskAI = (
   additionalTargets: readonly DiagramTarget[],
 ) => boolean | void | Promise<boolean | void>;
 
+/** A part chosen for a comment the host composes (`onHostDraft`). */
+export interface DiagramHostDraft {
+  /** The anchor a comment there carries (its `sourceLine` in document lines). */
+  readonly anchor: DiagramAnchor;
+  /** Drop the draft: the part's ring goes. A draft already replaced ignores it. */
+  readonly cancel: () => void;
+}
+
 export interface DiagramViewerProps {
   readonly kind: DiagramKind;
   /** The diagram text. With `onSave` this is the saved baseline the pane's
@@ -52,6 +60,11 @@ export interface DiagramViewerProps {
   readonly comments: readonly DiagramComment[];
   /** A comment composed on a part. Absent: clicks open nothing. */
   readonly onCreateComment?: DiagramCreateComment;
+  /** Opt-in host capability: the composer handed to the host. A click on a
+   * part reports it here (null when the draft closes) and no composer is
+   * drawn; the host saves the comment and passes it back in `comments`.
+   * Absent: unchanged. */
+  readonly onHostDraft?: (draft: DiagramHostDraft | null) => void;
   /** 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. */
@@ -104,6 +117,7 @@ export function DiagramViewer({
   theme,
   comments,
   onCreateComment,
+  onHostDraft,
   onAskAI,
   onSave,
   readOnlySource = false,
@@ -142,7 +156,7 @@ export function DiagramViewer({
   const [svgRoot, setSvgRoot] = useState<SVGSVGElement | null>(null);
   const onSvgRoot = useCallback((root: SVGSVGElement | null) => setSvgRoot(root), []);
 
-  const canCreate = onCreateComment !== undefined || commentingDisabledReason !== undefined;
+  const canCreate = onCreateComment !== undefined || commentingDisabledReason !== undefined || onHostDraft !== undefined;
   const commentsState = useDiagramComments({
     finder,
     svgRoot,
@@ -190,6 +204,29 @@ export function DiagramViewer({
     if (!sourceOpen) cancelComposer();
   }, [cancelComposer, sourceOpen]);
 
+  // The composer handed to the host: the draft's part goes out, and the
+  // host's cancel closes it only while it is still the open one.
+  const onHostDraftRef = useRef(onHostDraft);
+  onHostDraftRef.current = onHostDraft;
+  const openComposer = commentsState.composer;
+  const openComposerRef = useRef(openComposer);
+  openComposerRef.current = openComposer;
+  const hostComposes = onHostDraft !== undefined;
+  useEffect(() => {
+    const report = onHostDraftRef.current;
+    if (!report) return;
+    if (openComposer === null) {
+      report(null);
+      return;
+    }
+    report({
+      anchor: buildDiagramAnchorValue(openComposer.primary.target, openComposer.sourceLine),
+      cancel: () => {
+        if (openComposerRef.current === openComposer) cancelComposer();
+      },
+    });
+  }, [cancelComposer, hostComposes, openComposer]);
+
   // 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.
@@ -215,7 +252,7 @@ export function DiagramViewer({
         selectedCommentId={selectedCommentId}
         onSelectComment={onSelectComment}
         renderComposer={(anchorRect) =>
-          commentsState.composer === null ? null : (
+          commentsState.composer === null || hostComposes ? null : (
             <DiagramComposer
               key={`${commentsState.composer.primary.target.id ?? ''}:${commentsState.composer.primary.target.from ?? ''}:${commentsState.composer.primary.target.to ?? ''}`}
               draft={commentsState.composer}
@@ -233,7 +270,7 @@ export function DiagramViewer({
         }
       />
     ),
-    [askFromComposer, commentingDisabledReason, commentsState, onSelectComment, selectedCommentId, sourceDirty],
+    [askFromComposer, commentingDisabledReason, commentsState, hostComposes, 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 DiagramAskAI, type DiagramViewerProps } from './DiagramViewer';
+export { DiagramViewer, type DiagramAskAI, type DiagramHostDraft, type DiagramViewerProps } from './DiagramViewer';
 export { DiagramPopout } from './DiagramPopout';
 export { DiagramPending, DiagramInlineSource, DiagramBlockPending } from './DiagramPending';
 export { isDiagramControlEvent, DIAGRAM_CONTROL_SELECTOR } from './diagramControls';