@plannotator/ui 0.53.1 → 0.55.0

package/components/blocks/QuestionBlock.tsx

@@ -14,6 +14,8 @@ import {
 import { InlineMarkdown } from '../InlineMarkdown';
 import { QuestionContext } from './QuestionContext';
 import { HostTitle } from '../HostTitle';
+import { UNAVAILABLE_IMAGE_CLASS, useImageResolver } from '../ImageResolverContext';
+import { getImageSrc } from '../ImageThumbnail';
 
 /**
  * A `:::question` block rendered as an answer card (the approved "Card"
@@ -46,6 +48,20 @@ import { HostTitle } from '../HostTitle';
  * host supplies a state), open its own decision
  * card from the tag's words (`onOpenDecision`), and hide the card's own
  * status tag to draw its own (`statusTag: 'none'`).
+ *
+ * The optional contract lines (approval "inbox-decision-mode"): `Stakes:` is
+ * a short emphasised line under the prompt, `Shows:` a chip that opens the
+ * picture (through `onImageClick`) or the file (an ordinary link), `Why:` a
+ * line under the choices ("Why <recommended>: …"), and `Reversible: no` a
+ * "Can't be undone" tag in the eyebrow. The card adds no confirm step.
+ *
+ * Picture choices (`choice.image`) draw as a grid of tiles: the picture and
+ * the label pick (a real radio or checkbox in each tile), a separate zoom
+ * button opens the picture (`onImageClick`), the label and description sit
+ * under it. When no picture can be shown (the host's image resolver says
+ * `unavailable`, every picture failed to load, or `pictureChoices={false}`)
+ * the choices are the ordinary text rows. The recommended answer that is
+ * none of the choices, and Other, stay text rows.
  */
 
 /** Pointer travel (px) above which a press on a choice row is a drag. */
@@ -57,6 +73,10 @@ const DOUBLE_CLICK_REVERT_MS = 800;
 
 const now = (): number => (typeof performance !== 'undefined' ? performance.now() : Date.now());
 
+/** The double-click guard's name for the recommended row (never a label: it
+ *  holds a character no choice label can). */
+const SUGGESTION_ROW = '\u0000suggestion';
+
 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
@@ -70,7 +90,7 @@ const cx = (...parts: Array<string | false | null | undefined>) => parts.filter(
  *  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 }) => (
+const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open' | 'warn'; children: React.ReactNode; className?: string; style?: React.CSSProperties }> = ({ tone, children, className, style }) => (
   <span
     className={cx(
       PILL,
@@ -78,10 +98,12 @@ const Tag: React.FC<{ tone: 'rec' | 'ok' | 'skip' | 'open'; children: React.Reac
       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',
+      tone === 'warn' && 'border-transparent bg-warning/15 text-warning',
       className,
     )}
     style={style}
     data-pinpoint-ignore=""
+    data-question-tag={tone}
   >
     {children}
   </span>
@@ -99,6 +121,20 @@ const DiamondGlyph = () => (
   </svg>
 );
 
+const ZoomGlyph = () => (
+  <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
+    <circle cx="11" cy="11" r="7" />
+    <path d="m20 20-3.5-3.5M11 8v6M8 11h6" strokeLinecap="round" />
+  </svg>
+);
+
+const PictureGlyph = () => (
+  <svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true" className="shrink-0">
+    <rect x="3" y="4" width="18" height="16" rx="2" />
+    <path d="m3 16 5-5 4 4 3-3 6 6" strokeLinejoin="round" />
+  </svg>
+);
+
 /** 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
@@ -115,6 +151,36 @@ const DECISION_OFF_STYLE: React.CSSProperties = {
   outlineOffset: '-1px',
 };
 
+/**
+ * The footer in a narrow column. The card is a size container
+ * (`@container/qcard`: the card's own width, never the viewport's, because
+ * the card sits in columns of every width), and the footer row wraps whole
+ * buttons:
+ * - No button's words ever wrap inside it (`whitespace-nowrap`): the row
+ *   wraps between buttons instead, and only when they do not fit on one
+ *   row, so Add note and Skip stay together and Accept recommended moves
+ *   down whole, still at the row's end (`ml-auto`).
+ * - Under 10rem inside the card (a card under about 190 px), where a button
+ *   may be wider than the card, Accept recommended and the save bar take a
+ *   row of their own and their words end in an ellipsis rather than leave
+ *   the card (`FOOT_FIT`; the name stays whole). The words stay one text
+ *   node: a split one moved the glyphs of a wide card by a fraction of a
+ *   pixel.
+ * - On a touch screen each button's hit area is at least 44 x 44 px: an
+ *   invisible `before:` box centred on it, as the header's decision tag
+ *   does, so the drawn button does not change. (An ellipsised button clips
+ *   that box to itself.) A box reaches up to 11 px past its button, so a
+ *   wrapped footer's rows sit 20 px apart on a touch screen
+ *   (`pointer-coarse:gap-y-5`, the footer row): with the 4 px of `gap-1`,
+ *   Accept recommended's box, later in the page, covered the bottom of Skip
+ *   and Add note above it, and a tap on Skip answered the question. One row
+ *   has no row gap, so a footer that fits is unchanged.
+ * A footer that fits on one row draws exactly as before, on any pointer.
+ */
+const FOOT_BUTTON = "whitespace-nowrap pointer-coarse:relative pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-full pointer-coarse:before:min-w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-['']";
+const FOOT_FIT = '@max-[10rem]/qcard:max-w-full @max-[10rem]/qcard:overflow-hidden @max-[10rem]/qcard:text-ellipsis';
+const FOOT_OWN_ROW = '@max-[10rem]/qcard:basis-full';
+
 /** Two answers say the same thing (identity and line ignored). */
 const sameAnswer = (a: QuestionAnswer | null | undefined, b: QuestionAnswer | null | undefined): boolean => {
   const norm = (x: QuestionAnswer | null | undefined) =>
@@ -197,8 +263,38 @@ export interface QuestionBlockProps {
   githubRepo?: string;
   repoHost?: string;
   onNavigateAnchor?: (hash: string) => void;
+  /** Draw picture choices (`choice.image`) as picture tiles (default true).
+   *  False: every choice is a text row, as on a host that shows no images. */
+  pictureChoices?: boolean;
+  /** A small label over a picture tile's picture, top left ("Mockup · VS
+   *  Code"), from the host; null or absent: none. Display only: never the
+   *  answer, never read by the parser. Default absent, so every card draws as
+   *  before (the Plannotator Inbox's onboarding tour labels its pictures). */
+  pictureBadge?: (choice: { label: string; image: { alt: string; src: string } }) => string | null;
+  /** The zoom button on a picture tile, told which question and which choice
+   *  (its index in the question's choices) as well as the picture: a host can
+   *  open a gallery of that question's choices (the Plannotator Inbox's option
+   *  sets). Absent: the zoom calls `onImageClick(url, alt)` as before. */
+  onZoomChoice?: (key: string, index: number, url: string, alt: string) => void;
 }
 
+/** The picture tile's label (`pictureBadge`): a small dark chip over the picture's top-left corner. */
+const PICTURE_BADGE_STYLE: React.CSSProperties = {
+  position: 'absolute',
+  left: 6,
+  top: 6,
+  zIndex: 1,
+  pointerEvents: 'none',
+  borderRadius: 4,
+  background: 'rgb(0 0 0 / 0.6)',
+  color: 'white',
+  padding: '0 6px',
+  fontSize: 10.5,
+  fontWeight: 600,
+  lineHeight: '18px',
+  letterSpacing: '0.02em',
+};
+
 /** 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;
@@ -228,8 +324,39 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   githubRepo,
   repoHost,
   onNavigateAnchor,
+  pictureChoices = true,
+  pictureBadge,
+  onZoomChoice,
 }) => {
   const { question, number } = indexed;
+  const resolveImage = useImageResolver();
+  // The URL a picture loads from, exactly as an inline markdown image of the
+  // same src would (the host's resolver first), or null when the host says
+  // it cannot be shown.
+  const pictureSrc = (src: string): string | null => {
+    const resolved = resolveImage ? resolveImage(src) : null;
+    if (resolved?.kind === 'unavailable') return null;
+    if (resolved?.kind === 'src') return resolved.src;
+    return /^(https?:\/\/|data:|blob:)/i.test(src) ? src : getImageSrc(src, imageBaseDir);
+  };
+  // The host's reason a picture is not shown (its resolver's `unavailable`
+  // title), drawn on the placeholder exactly as an inline image's, so a host
+  // that holds remote images counts and loads these too (code review's PR
+  // Markdown preview: "N remote images held · Load remote images").
+  const pictureHeldTitle = (src: string): string | null => {
+    const resolved = resolveImage ? resolveImage(src) : null;
+    return resolved?.kind === 'unavailable' ? resolved.title : null;
+  };
+  const heldPlaceholder = (src: string, alt: string) => {
+    const title = pictureHeldTitle(src);
+    return title === null ? null : (
+      <span className={UNAVAILABLE_IMAGE_CLASS} title={title} data-image-unavailable="">{alt || 'Image'}</span>
+    );
+  };
+  // Pictures that failed to load (by the URL tried): a tile shows its alt
+  // text instead, and with none left the choices are text rows.
+  const [failedPictures, setFailedPictures] = useState<ReadonlySet<string>>(() => new Set());
+  const markPictureFailed = (url: string) => setFailedPictures((prev) => (prev.has(url) ? prev : new Set([...prev, url])));
   // 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.
@@ -275,6 +402,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     }
   };
   const cancel = () => {
+    replacedOtherRef.current = null;
     setDraft(null);
     setNotePinned(null);
   };
@@ -283,6 +411,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const uid = useId().replace(/:/g, '');
   const promptId = `q-prompt-${uid}`;
   const contextId = `q-context-${uid}`;
+  const stakesId = `q-stakes-${uid}`;
   const suggestId = `q-suggest-${uid}`;
   const noteLabelId = `q-note-${uid}`;
   // null = follow the answer (open while a note exists); a click pins it.
@@ -291,10 +420,21 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   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
+  // Accept recommended goes 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);
+  // Who set the "Other…" answer while this card was open: the recommended
+  // row (its pick, or Accept recommended) or the Other field. null: neither
+  // (an answer the host stored): an Other answer that is exactly the agent's
+  // text then reads as the row, unless the Other field has focus. Typing
+  // never turns into the row, so "Yes, but slower" stays in the field when
+  // the recommendation is "Yes".
+  const [otherBy, setOtherBy] = useState<'row' | 'field' | null>(null);
+  const [otherFocused, setOtherFocused] = useState(false);
+  // Pick any: the reviewer's own Other text the recommended row replaced when
+  // ticked, put back when it is unticked (the answer has one Other field).
+  const replacedOtherRef = useRef<string | null>(null);
 
   const inline = (text: string) => (
     <InlineMarkdown
@@ -322,9 +462,9 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   // 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.
+  // choice, and a pick-any question recommending only its own answer (the
+  // recommended row after the choices: Accept would clear the ticks for it,
+  // and the row is one click anyway) offer it no more.
   const offerAccept = !readOnly && hasRecommendation && !settled && (
     !answered
     || (question.kind === 'multi'
@@ -361,7 +501,37 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     }
   };
 
+  // The agent's recommended answer that is none of its choices
+  // (`suggestedText` on a pick question): one more answer row, after the
+  // choices and before "Other…". Picking it stores exactly what Accept
+  // recommended stores, the text as the "Other…" answer, so no label,
+  // index, key or host check of picked labels changes.
+  const pickSuggestion = (checked: boolean) => {
+    const text = question.suggestedText;
+    if (!text) return;
+    lastPickRef.current = { label: SUGGESTION_ROW, before: answer, at: now() };
+    const { skipped: _s, other: _o, ...rest } = base;
+    if (question.kind === 'multi') {
+      if (checked) {
+        if (!suggestionPicked) replacedOtherRef.current = storedOther.trim() ? storedOther : null;
+        setOtherBy('row');
+        commit({ ...rest, selected, other: text });
+      } else {
+        const back = replacedOtherRef.current;
+        replacedOtherRef.current = null;
+        setOtherBy(back ? 'field' : null);
+        commit({ ...rest, selected, ...(back ? { other: back } : {}) });
+      }
+    } else if (checked) {
+      replacedOtherRef.current = null;
+      setOtherBy('row');
+      commit({ ...rest, selected: [], other: text });
+    }
+  };
+
   const setOther = (value: string) => {
+    setOtherBy('field');
+    replacedOtherRef.current = null;
     const { skipped: _s, other: _o, ...rest } = base;
     const keepSelected = question.kind === 'multi' ? selected : value.trim() ? [] : rest.selected;
     commit({ ...rest, selected: keepSelected, ...(value ? { other: value } : {}) });
@@ -378,6 +548,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   };
 
   const toggleSkip = () => {
+    replacedOtherRef.current = null;
     if (base.skipped) {
       const { skipped: _s, ...rest } = base;
       commit(rest);
@@ -390,6 +561,8 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   const acceptRecommended = () => {
     const next = recommendedQuestionAnswer(indexed, base);
     if (!next) return;
+    replacedOtherRef.current = null;
+    if (next.other) setOtherBy('row');
     focusAfterAcceptRef.current = true;
     commit(next);
   };
@@ -450,8 +623,25 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     : `Question${question.kind === 'multi' ? ' · pick any' : ''}`;
   const groupName = `question-${uid}`;
   const inputType = question.kind === 'multi' ? 'checkbox' : 'radio';
-  const other = answer?.other ?? '';
+  const storedOther = answer?.other ?? '';
+  // The recommended row holds the "Other…" answer when it is the agent's
+  // text; the Other field is then empty (typing there replaces it).
+  const suggestionRow = question.kind !== 'text' && !!question.suggestedText;
+  const suggestionPicked = suggestionRow
+    && storedOther.trim() !== ''
+    && storedOther.trim() === question.suggestedText!.trim()
+    && (otherBy === 'row' || (otherBy === null && !otherFocused));
+  const other = suggestionPicked ? '' : storedOther;
   const otherOn = other.trim() !== '';
+  // Picture choices: each choice's picture URL (null: none, or not shown).
+  const pictures = question.choices.map((c) => (c.image ? pictureSrc(c.image.src) : null));
+  const showTiles = pictureChoices
+    && question.kind !== 'text'
+    && pictures.some((url) => url !== null && !failedPictures.has(url));
+  const recommendedLabels = question.choices.filter((c) => c.recommended).map((c) => c.label);
+  const showsUrl = question.shows?.kind === 'image' ? pictureSrc(question.shows.src) : null;
+  // A `Shows:` picture that failed to load is its label, as a picture tile's is.
+  const showsSrc = showsUrl !== null && !failedPictures.has(showsUrl) ? showsUrl : null;
 
   // A `Decision: when answered` question the host may switch off, or (with
   // `decisionScope: 'any'`) any other question once the host supplies a
@@ -468,27 +658,16 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     ? (recordingOn ? 'on' : 'off')
     : undefined;
 
-  const describedBy = [question.context ? contextId : null, question.suggestedText && !answered ? suggestId : null]
+  const describedBy = [question.stakes ? stakesId : null, question.context ? contextId : null, question.kind === 'text' && 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>
-      )}
+  // A text question's recommended answer: shown above the field with the
+  // same Recommended tag a choice carries; the footer's Accept recommended
+  // fills it in. (A pick question's is a row of its own, below.)
+  const suggestedLine = question.kind === 'text' && question.suggestedText && !answered && (
+    <div id={suggestId} className="mt-2 text-[12.5px] text-muted-foreground" data-question-suggested="">
+      <Tag tone="rec">Recommended</Tag> {inline(question.suggestedText)}
     </div>
   );
 
@@ -497,6 +676,8 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
       ref={cardRef}
       className={cx(
         'question-block my-5 min-w-0 rounded-[10px] border px-3.5 pb-2.5 pt-3',
+        // A size container: the card's own width lays out its footer (FOOT_BUTTON).
+        '@container/qcard',
         // Native radios/checkboxes follow the theme's mode. ThemeProvider marks
         // light mode with `.light` on the root; a host without theme classes
         // keeps the page's own color-scheme.
@@ -569,6 +750,14 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
           ) : (
             <><Tag tone="rec" style={DECISION_OFF_STYLE}><DiamondGlyph />Records a decision</Tag>{' '}</>
           ))}
+          {question.reversible && (
+            <><HostTitle title={question.reversible.why ? `Can't be undone: ${question.reversible.why}` : "Can't be undone"}>
+              <span className="inline-flex" data-question-irreversible="">
+                <Tag tone="warn">Can&rsquo;t be undone</Tag>
+                {question.reversible.why && <span className="sr-only">: {question.reversible.why}</span>}
+              </span>
+            </HostTitle>{' '}</>
+          )}
           {statusTag !== 'none' && hostStatus && <Tag tone={hostStatus.tone ?? 'open'}>{hostStatus.label}</Tag>}
           {statusTag !== 'none' && !hostStatus && (
             <>
@@ -584,6 +773,43 @@ 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>
+      {question.stakes && (
+        <p id={stakesId} className="m-0 mt-1 text-[13px] font-medium leading-[1.45] text-foreground/90" data-question-part="stakes">
+          {inline(question.stakes)}
+        </p>
+      )}
+      {question.shows && (
+        <div className="mt-1.5 flex flex-wrap items-center gap-1.5 text-[12.5px]" data-question-shows="">
+          <span className="annotation-exclude select-none text-muted-foreground" data-pinpoint-ignore="">Shows</span>
+          {question.shows.kind === 'image' ? (
+            showsSrc && onImageClick ? (
+              <button
+                type="button"
+                onClick={() => onImageClick(showsSrc, question.shows!.label || 'Picture')}
+                className="inline-flex min-w-0 max-w-full items-center gap-1.5 rounded-md border border-border/80 bg-background/60 py-0.5 pl-0.5 pr-2 text-foreground hover:bg-muted/50 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary"
+                data-question-shows-open=""
+              >
+                <img
+                  src={showsSrc}
+                  alt=""
+                  draggable={false}
+                  className="h-6 w-8 shrink-0 rounded-[4px] object-cover"
+                  data-question-picture=""
+                  data-zoomable=""
+                  data-image-src={question.shows.src}
+                  onError={() => markPictureFailed(showsSrc)}
+                />
+                <span className="truncate">{question.shows.label || 'Picture'}</span>
+              </button>
+            ) : (
+              heldPlaceholder(question.shows.src, question.shows.label)
+                ?? <span className="inline-flex items-center gap-1 text-foreground"><PictureGlyph />{question.shows.label || question.shows.src}</span>
+            )
+          ) : (
+            <span className="min-w-0 text-foreground">{inline(`[${question.shows.label}](${question.shows.src})`)}</span>
+          )}
+        </div>
+      )}
       {renderBelowPrompt?.(indexed)}
       {(question.decision || (decisionCapable && recordingOn)) && (
         <div
@@ -643,49 +869,106 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
         </>
       ) : (
         <>
-          {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>
+            {showTiles ? (
+              <QuestionPictureTiles
+                choices={question.choices}
+                urls={question.choices.map((_c, index) => {
+                  const url = pictures[index];
+                  return url !== null && url !== undefined && !failedPictures.has(url) ? url : null;
+                })}
+                selected={selected}
+                inputType={inputType}
+                name={groupName}
+                readOnly={readOnly}
+                onPick={pick}
+                onZoom={
+                  onZoomChoice
+                    ? (url, alt, index) => onZoomChoice(question.key, index, url, alt)
+                    : onImageClick
+                }
+                onPictureError={markPictureFailed}
+                heldTitle={pictureHeldTitle}
+                renderText={inline}
+                labelProps={(label) => ({ onPointerDown: onRowPointerDown, onClickCapture: (event) => onRowClick(event, label) })}
+                pictureBadge={pictureBadge}
+              />
+            ) : (
+              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',
                     )}
-                    {choice.recommended && <> <Tag tone="rec">Recommended</Tag></>}
-                  </span>
-                </label>
-              );
-            })}
+                    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"
+                      data-question-control=""
+                      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.image && pictureChoices && pictureHeldTitle(choice.image.src) !== null && <> {heldPlaceholder(choice.image.src, choice.image.alt || choice.label)}</>}
+                      {choice.description && (
+                        <span className="text-muted-foreground"> — {inline(choice.description)}</span>
+                      )}
+                      {choice.recommended && <> <Tag tone="rec">Recommended</Tag></>}
+                    </span>
+                  </label>
+                );
+              })
+            )}
+            {suggestionRow && (
+              // The agent's recommended answer that is none of its choices:
+              // drawn exactly as a choice (the same control, row and tag), so
+              // the card reads as one list of answers.
+              <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',
+                  suggestionPicked && 'bg-primary/12 hover:bg-primary/12',
+                )}
+                data-question-option=""
+                data-question-suggested=""
+                onPointerDown={onRowPointerDown}
+                onClickCapture={(event) => onRowClick(event, SUGGESTION_ROW)}
+              >
+                <input
+                  type={inputType}
+                  name={groupName}
+                  checked={suggestionPicked}
+                  onChange={(e) => pickSuggestion(e.target.checked)}
+                  className="mt-[3px] h-[15px] w-[15px] shrink-0 cursor-pointer accent-primary disabled:cursor-default"
+                  data-question-control=""
+                  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(question.suggestedText!)}</span>
+                  {' '}<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"
+                  data-question-control=""
                   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',
@@ -698,6 +981,13 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
                   type="text"
                   value={other}
                   onChange={(e) => setOther(e.target.value)}
+                  onFocus={() => {
+                    // A stored answer that reads as the row stays the row
+                    // while the reviewer types here (typing replaces it).
+                    if (otherBy === null && suggestionPicked) setOtherBy('row');
+                    setOtherFocused(true);
+                  }}
+                  onBlur={() => setOtherFocused(false)}
                   disabled={readOnly}
                   placeholder={readOnly ? '' : 'Other…'}
                   aria-label={number > 0 ? `Other answer to question ${number}` : 'Other answer'}
@@ -709,6 +999,15 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
         </>
       )}
 
+      {question.why && (
+        <p className="m-0 mt-2 text-[12.5px] leading-[1.45] text-muted-foreground" data-question-part="why">
+          <span className="font-semibold text-foreground/85">
+            {recommendedLabels.length > 0 ? <>Why {recommendedLabels.map((label, i) => <React.Fragment key={label}>{i > 0 ? ', ' : ''}{inline(label)}</React.Fragment>)}:</> : 'Why:'}
+          </span>{' '}
+          {inline(question.why)}
+        </p>
+      )}
+
       {noteOpen && (!readOnly || !!answer?.note?.trim()) && (
         <div className="mt-2">
           <p id={noteLabelId} className="annotation-exclude select-none mb-1 ml-0.5 text-[10.5px] font-semibold uppercase tracking-[0.07em] text-muted-foreground">
@@ -728,7 +1027,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
 
       {(!readOnly || hasHostFooter) && (
         <div
-          className="annotation-exclude select-none mt-2 flex items-center gap-1 border-t border-border/55 pt-1.5"
+          className="annotation-exclude select-none mt-2 flex flex-wrap items-center gap-1 pointer-coarse:gap-y-5 border-t border-border/55 pt-1.5"
           data-pinpoint-ignore=""
         >
           {!readOnly && (
@@ -737,6 +1036,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
               onClick={toggleNote}
               aria-expanded={noteOpen}
               className={cx(
+                FOOT_BUTTON,
                 'rounded-[5px] px-[7px] py-[3px] text-xs hover:bg-muted hover:text-foreground',
                 noteOpen ? 'text-foreground' : 'text-muted-foreground',
               )}
@@ -751,6 +1051,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
               onClick={toggleSkip}
               aria-pressed={skipped}
               className={cx(
+                FOOT_BUTTON,
                 'rounded-[5px] px-[7px] py-[3px] text-xs hover:bg-muted hover:text-foreground',
                 skipped ? 'text-foreground' : 'text-muted-foreground',
               )}
@@ -765,18 +1066,18 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
               <button
                 type="button"
                 onClick={acceptRecommended}
-                className="ml-auto rounded-md border border-primary/45 bg-primary/10 px-2.5 py-[3px] text-[12.5px] font-medium text-primary hover:bg-primary/20 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+                className={cx(FOOT_BUTTON, FOOT_FIT, FOOT_OWN_ROW, 'ml-auto rtl:ml-0 rtl:mr-auto rounded-md border border-primary/45 bg-primary/10 px-2.5 py-[3px] text-[12.5px] font-medium text-primary hover:bg-primary/20 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary')}
               >
                 Accept recommended
               </button>
             )
           ) : (
-            <div className="ml-auto flex items-center gap-1">
+            <div className={cx(FOOT_OWN_ROW, 'ml-auto rtl:ml-0 rtl:mr-auto flex min-w-0 flex-wrap items-center justify-end gap-1')}>
               {offerAccept && (
                 <button
                   type="button"
                   onClick={acceptRecommended}
-                  className="rounded-md border border-primary/45 bg-primary/10 px-2.5 py-[3px] text-[12.5px] font-medium text-primary hover:bg-primary/20 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
+                  className={cx(FOOT_BUTTON, FOOT_FIT, 'rounded-md border border-primary/45 bg-primary/10 px-2.5 py-[3px] text-[12.5px] font-medium text-primary hover:bg-primary/20 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary')}
                 >
                   Accept recommended
                 </button>
@@ -788,7 +1089,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
                     type="button"
                     onClick={cancel}
                     disabled={saving}
-                    className="rounded-[5px] px-[7px] py-[3px] text-xs text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-60"
+                    className={cx(FOOT_BUTTON, FOOT_FIT, 'rounded-[5px] px-[7px] py-[3px] text-xs text-muted-foreground hover:bg-muted hover:text-foreground disabled:opacity-60')}
                   >
                     Cancel
                   </button>
@@ -797,7 +1098,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
                     onClick={save}
                     disabled={saving}
                     aria-busy={saving || undefined}
-                    className="rounded-md bg-primary px-2.5 py-[3px] text-[12.5px] font-medium text-primary-foreground hover:bg-primary/90 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:opacity-60"
+                    className={cx(FOOT_BUTTON, FOOT_FIT, 'rounded-md bg-primary px-2.5 py-[3px] text-[12.5px] font-medium text-primary-foreground hover:bg-primary/90 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary disabled:opacity-60')}
                   >
                     {(typeof saveLabel === 'function' ? saveLabel(question) : saveLabel) || 'Save answer'}
                   </button>
@@ -810,3 +1111,172 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
     </fieldset>
   );
 };
+
+/** One choice a picture tile draws (a parsed question's choice, or the Inbox wire's). */
+export interface QuestionPictureTileChoice {
+  label: string;
+  description?: string | null;
+  recommended?: boolean;
+  image?: { alt: string; src: string } | null;
+}
+
+export interface QuestionPictureTilesProps {
+  choices: readonly QuestionPictureTileChoice[];
+  /** The URL each choice's picture loads from, in choice order; null (no picture shown) draws its alt text. */
+  urls: readonly (string | null)[];
+  selected: readonly string[];
+  inputType: 'radio' | 'checkbox';
+  /** The radio group's name. */
+  name: string;
+  readOnly?: boolean;
+  /** The tile's radio or checkbox changed (the picture and the label pick through it). */
+  onPick: (label: string, checked: boolean) => void;
+  /** The separate zoom button (absent: no zoom button). Never picks. `index`: the choice's place in `choices`. */
+  onZoom?: (url: string, alt: string, index: number) => void;
+  onPictureError?: (url: string) => void;
+  /** The host's reason a picture is held (its image resolver's `unavailable` title). */
+  heldTitle?: (src: string) => string | null;
+  /** How a label or description is drawn (the card's inline markdown). */
+  renderText: (text: string) => React.ReactNode;
+  /** A host's own props on each tile's label (the card's drag guard). */
+  labelProps?: (label: string) => React.LabelHTMLAttributes<HTMLLabelElement>;
+  /** A host's own props on each tile's input (decision mode answers on a click, or Enter). */
+  inputProps?: (label: string) => React.InputHTMLAttributes<HTMLInputElement>;
+  /** What sits under a choice's words (default: its Recommended tag). */
+  renderBadges?: (choice: QuestionPictureTileChoice, index: number) => React.ReactNode;
+  /** A small label over a tile's picture, top left (the card's `pictureBadge`); null or absent draws none. */
+  pictureBadge?: (choice: { label: string; image: { alt: string; src: string } }) => string | null;
+}
+
+/**
+ * Picture choices as tiles (approval "inbox-decision-mode", agent contract
+ * lines): each tile is a native `<label>` holding the picture and a real radio
+ * or checkbox, so the picture, the label and the keyboard pick; a separate
+ * zoom button, outside the label, opens the picture and never picks. The
+ * question card draws these, and so does the Inbox's decision mode (its own
+ * size through `[data-question-tile*]` hooks), so the two never drift.
+ */
+export const QuestionPictureTiles: React.FC<QuestionPictureTilesProps> = ({
+  choices,
+  urls,
+  selected,
+  inputType,
+  name,
+  readOnly = false,
+  onPick,
+  onZoom,
+  onPictureError,
+  heldTitle,
+  renderText,
+  labelProps,
+  inputProps,
+  renderBadges,
+  pictureBadge,
+}) => (
+  <div
+    className="mb-1 grid grid-cols-[repeat(auto-fill,minmax(150px,1fr))] gap-2"
+    data-question-tiles=""
+  >
+    {choices.map((choice, index) => {
+      const checked = selected.includes(choice.label);
+      const shown = urls[index] ?? null;
+      // The alt text names the picture; one that only repeats the label is decorative.
+      const alt = choice.image ? (choice.image.alt || choice.label) : '';
+      const decorative = !!choice.image && alt.trim() === choice.label.trim();
+      const host = labelProps?.(choice.label);
+      const input = inputProps?.(choice.label);
+      return (
+        <div
+          key={choice.label}
+          className={cx(
+            'relative flex min-w-0 flex-col overflow-hidden rounded-[9px] border transition-colors has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-primary',
+            checked ? 'border-primary/70 bg-primary/10' : 'border-border/80 bg-background/40',
+            !readOnly && !checked && 'hover:border-foreground/30',
+          )}
+          data-question-tile=""
+          data-question-tile-checked={checked ? '' : undefined}
+          data-question-tile-recommended={choice.recommended ? '' : undefined}
+        >
+          <label
+            {...host}
+            className={cx('flex min-w-0 flex-1 flex-col', readOnly ? 'cursor-default' : 'cursor-pointer')}
+            data-question-option=""
+          >
+            {choice.image && (
+              <span
+                className="annotation-exclude select-none block aspect-[4/3] w-full overflow-hidden border-b border-border/60 bg-muted/35"
+                // Inline, not a utility class: the badge's position needs it, and no new class reaches the guides.show viewer's CSS.
+                style={{ position: 'relative' }}
+                data-pinpoint-ignore=""
+                data-question-tile-picture=""
+              >
+                {(() => {
+                  const badge = pictureBadge?.({ label: choice.label, image: choice.image });
+                  return badge ? (
+                    <span style={PICTURE_BADGE_STYLE} data-question-picture-badge="">
+                      {badge}
+                    </span>
+                  ) : null;
+                })()}
+                {shown ? (
+                  <img
+                    src={shown}
+                    alt={decorative ? '' : alt}
+                    draggable={false}
+                    loading="lazy"
+                    className="h-full w-full object-contain"
+                    data-question-picture=""
+                    data-zoomable=""
+                    data-image-src={choice.image.src}
+                    onError={() => onPictureError?.(shown)}
+                  />
+                ) : (
+                  <span
+                    className="grid h-full place-items-center px-2 text-center text-xs text-muted-foreground"
+                    title={heldTitle?.(choice.image.src) ?? undefined}
+                    data-image-unavailable=""
+                  >
+                    {alt}
+                  </span>
+                )}
+              </span>
+            )}
+            <span className="flex w-full min-w-0 items-start gap-2 px-2.5 py-2" data-question-tile-caption="">
+              <input
+                {...input}
+                type={inputType}
+                name={name}
+                checked={checked}
+                onChange={(e) => onPick(choice.label, e.target.checked)}
+                className="mt-[3px] h-[15px] w-[15px] shrink-0 cursor-pointer accent-primary disabled:cursor-default"
+                data-question-control=""
+                disabled={readOnly}
+              />
+              <span className="min-w-0 flex-1 select-text text-[13px] leading-[1.4] text-foreground" data-question-part="choice">
+                <span className="font-[550]" data-question-tile-label="">{renderText(choice.label)}</span>
+                {choice.description && (
+                  <span className="block text-muted-foreground" data-question-tile-description="">{renderText(choice.description)}</span>
+                )}
+                {renderBadges
+                  ? renderBadges(choice, index)
+                  : choice.recommended && <span className="mt-1 block"><Tag tone="rec">Recommended</Tag></span>}
+              </span>
+            </span>
+          </label>
+          {shown && onZoom && (
+            <button
+              type="button"
+              onClick={() => onZoom(shown, alt, index)}
+              aria-label={`Zoom: ${alt}`}
+              className="annotation-exclude absolute right-1.5 top-1.5 grid h-7 w-7 place-items-center rounded-md bg-background/85 text-foreground shadow-sm ring-1 ring-border/70 before:absolute before:-inset-2 before:content-[''] hover:bg-background focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary"
+              data-pinpoint-ignore=""
+              data-question-zoom=""
+            >
+              <ZoomGlyph />
+            </button>
+          )}
+        </div>
+      );
+    })}
+  </div>
+);