@flamingo-stack/openframe-frontend-core 0.0.518 → 0.0.519

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.518",
+  "version": "0.0.519",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/chat-protocol/__tests__/__snapshots__/nats-decoder-golden.test.ts.snap

@@ -112,6 +112,36 @@ exports[`decodeNatsChunk — golden corpus > maps the full recorded corpus to no
     "status": "rejected",
     "type": "approval-resolved",
   },
+  "ask": {
+    "options": [
+      {
+        "description": "How scripting works and how to set it up",
+        "label": "Find documentation",
+      },
+      {
+        "description": "List, edit or run the scripts in your workspace",
+        "label": "Your scripts",
+      },
+    ],
+    "question": "What do you want to work on?",
+    "text": "Do you want the OpenFrame docs on scripts, or the scripts in your own workspace?",
+    "type": "ask",
+  },
+  "ask_blank_question": null,
+  "ask_missing_question": null,
+  "ask_no_options": null,
+  "ask_options_not_array": null,
+  "ask_unusable_option_rows": null,
+  "ask_without_intro": {
+    "options": [
+      {
+        "description": undefined,
+        "label": "Docs",
+      },
+    ],
+    "question": "Which one?",
+    "type": "ask",
+  },
   "context_compaction_end": {
     "phase": "end",
     "summary": "Compacted 34 messages",

package/src/chat-protocol/__tests__/nats-decoder-golden.test.ts

@@ -29,6 +29,29 @@ const CORPUS: Record<string, unknown> = {
   guide_empty_string: { type: 'GUIDE', text: '' },
   guide_missing_text: { type: 'GUIDE' },
 
+  // ASK — the guide-routing clarification card. `text` is the intro sentence
+  // riding the same chunk; a card without a question or without usable options
+  // is dropped (nothing the user could answer).
+  ask: {
+    type: 'ASK',
+    text: 'Do you want the OpenFrame docs on scripts, or the scripts in your own workspace?',
+    question: 'What do you want to work on?',
+    options: [
+      { label: 'Find documentation', description: 'How scripting works and how to set it up' },
+      { label: 'Your scripts', description: 'List, edit or run the scripts in your workspace' },
+    ],
+  },
+  ask_without_intro: { type: 'ASK', question: 'Which one?', options: [{ label: 'Docs' }] },
+  ask_missing_question: { type: 'ASK', options: [{ label: 'Docs' }] },
+  ask_blank_question: { type: 'ASK', question: '   ', options: [{ label: 'Docs' }] },
+  ask_no_options: { type: 'ASK', question: 'Which one?', options: [] },
+  ask_options_not_array: { type: 'ASK', question: 'Which one?', options: 'Docs' },
+  ask_unusable_option_rows: {
+    type: 'ASK',
+    question: 'Which one?',
+    options: [{ label: '   ' }, { description: 'no label' }, null, 'Docs'],
+  },
+
   ai_metadata_full: {
     type: 'AI_METADATA',
     modelDisplayName: 'Claude Sonnet',

package/src/chat-protocol/events.ts

@@ -15,6 +15,11 @@ import type {
   DecisionResolvedFrame,
   UsageTelemetry,
 } from './frames'
+// The ask card's option shape is the SEGMENT's shape — the decoder hands the
+// rows straight to the accumulator, so restating them here would be two
+// declarations of one wire contract. Type-only import from a React-free
+// module; `nats-decoder.ts` already depends on the same file for MESSAGE_TYPE.
+import type { AskOptionData } from '../components/chat/types/message.types'
 
 /** Optional envelope on every event. `seq` carries the transport's
  *  stream sequence (JetStream `streamSeq` on NATS; unused on SSE). */
@@ -65,6 +70,20 @@ export interface GuideDeltaEvent extends ChatStreamEventBase {
   text: string
 }
 
+/** Clarification card (NATS `ASK` chunk) — the assistant asking which reading
+ *  of an ambiguous question to answer. NOT a delta: the chunk carries the
+ *  finished card, so consumers push it whole instead of coalescing. `text` is
+ *  the intro sentence the same chunk rides along with; consumers render it as
+ *  ordinary answer text BEFORE the card. NATS-only — the SSE frame grammar has
+ *  no ask frame — but it lives in the shared union because the reducer is
+ *  transport-agnostic. */
+export interface AskEvent extends ChatStreamEventBase {
+  type: 'ask'
+  text?: string
+  question: string
+  options: AskOptionData[]
+}
+
 export interface StatusEvent extends ChatStreamEventBase {
   type: 'status'
   phase: 'thinking'
@@ -241,6 +260,7 @@ export type ChatStreamEvent =
   | TextDeltaEvent
   | ThinkingDeltaEvent
   | GuideDeltaEvent
+  | AskEvent
   | StatusEvent
   | ToolExecutionEvent
   | ApprovalRequestEvent

package/src/chat-protocol/nats-decoder.ts

@@ -17,6 +17,7 @@
  */
 
 import { MESSAGE_TYPE } from '../components/chat/types/message.types'
+import type { AskOptionData } from '../components/chat/types/message.types'
 import type { ApprovalToolCall, ChatStreamEvent } from './events'
 
 /** Minimal structural view of a NATS chunk (see `ChunkData` in
@@ -45,6 +46,20 @@ function normalizeToolCalls(raw: unknown): ApprovalToolCall[] {
     }))
 }
 
+/** Coerce the wire's ask `options[]` into the card's row shape. Rows without a
+ *  usable `label` are dropped: the label is what gets SENT when the row is
+ *  picked, so a blank one would post an empty reply. */
+export function normalizeAskOptions(raw: unknown): AskOptionData[] {
+  if (!Array.isArray(raw)) return []
+  return raw
+    .filter((item): item is Record<string, any> => !!item && typeof item === 'object')
+    .map((item) => ({
+      label: typeof item.label === 'string' ? item.label.trim() : '',
+      description: typeof item.description === 'string' ? item.description : undefined,
+    }))
+    .filter((option) => option.label.length > 0)
+}
+
 /**
  * Parse one raw NATS chunk into a normalized event. Returns `null` for
  * unknown/malformed chunks — an unrecognized `type`, a missing required
@@ -101,6 +116,23 @@ export function decodeNatsChunk(chunk: unknown): ChatStreamEvent | null {
       }
       return null
 
+    // An ask card is only an ask card with something to pick: a question and at
+    // least one option. Anything less is dropped rather than rendered as an
+    // empty card the user can't answer — the backend already falls back to a
+    // complete hardcoded card when the model returns a partial one.
+    case MESSAGE_TYPE.ASK: {
+      const question = typeof data.question === 'string' ? data.question.trim() : ''
+      const options = normalizeAskOptions(data.options)
+      if (!question || options.length === 0) return null
+      return {
+        type: 'ask',
+        ...(typeof data.text === 'string' && data.text ? { text: data.text } : {}),
+        question,
+        options,
+        ...seq,
+      }
+    }
+
     case MESSAGE_TYPE.EXECUTING_TOOL:
       return {
         type: 'tool-execution',

package/src/components/chat/__tests__/ask-display.test.tsx

@@ -0,0 +1,101 @@
+/**
+ * `AskDisplay` — the guide-routing clarification card.
+ *
+ * Pins the two contracts a host depends on: the picked option's label reaches
+ * `onSelect` VERBATIM (the backend resolves the user's reply against the labels
+ * it offered, so a reworded send breaks routing), and the card is inert without
+ * a handler (replayed history / observer surfaces must not offer a button that
+ * would post into someone else's dialog).
+ */
+
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { AskDisplay } from '../ask-display'
+import type { AskSegment } from '../types/message.types'
+
+const card = (question: string): AskSegment => ({
+  type: 'ask',
+  question,
+  options: [
+    { label: 'Find documentation', description: 'How the feature works and how to set it up' },
+    { label: 'Work with workspace data' },
+  ],
+})
+
+describe('AskDisplay', () => {
+  it('renders the question, numbered options and their descriptions', () => {
+    render(<AskDisplay cards={[card('What do you want to work on?')]} />)
+
+    expect(screen.getByText('What do you want to work on?')).toBeInTheDocument()
+    expect(screen.getByText('1.')).toBeInTheDocument()
+    expect(screen.getByText('Find documentation')).toBeInTheDocument()
+    expect(screen.getByText('How the feature works and how to set it up')).toBeInTheDocument()
+    expect(screen.getByText('2.')).toBeInTheDocument()
+    expect(screen.getByText('Work with workspace data')).toBeInTheDocument()
+  })
+
+  it('sends the picked option label verbatim', () => {
+    const onSelect = vi.fn()
+    render(<AskDisplay cards={[card('Which one?')]} onSelect={onSelect} />)
+
+    fireEvent.click(screen.getByText('Find documentation'))
+
+    expect(onSelect).toHaveBeenCalledWith('Find documentation')
+  })
+
+  it('renders locked without a handler: options disabled and veiled', () => {
+    const { container } = render(<AskDisplay cards={[card('Which one?')]} />)
+
+    // Kept as buttons on purpose — assistive tech should hear "dimmed button",
+    // not read the options as prose that was never actionable.
+    const options = screen.getAllByRole('button')
+    expect(options).toHaveLength(2)
+    for (const option of options) expect(option).toBeDisabled()
+
+    // The veil carries the visible lock: it dims the block, owns the pointer
+    // (not-allowed cursor anywhere over it) and explains itself on hover.
+    const veil = container.querySelector('[title]')
+    expect(veil).toBeTruthy()
+    expect(veil?.className).toContain('cursor-not-allowed')
+  })
+
+  it('tells assistive tech WHY the options are disabled', () => {
+    const { container, rerender } = render(<AskDisplay cards={[card('Which one?')]} />)
+
+    // The veil is decorative (aria-hidden), so its `title` never reaches a
+    // screen reader — the group's description is what does.
+    const describedBy = screen.getByRole('group').getAttribute('aria-describedby')
+    expect(describedBy).toBeTruthy()
+    expect(container.querySelector(`#${CSS.escape(describedBy!)}`)?.textContent).toBe(
+      'This question was already answered',
+    )
+
+    // An answerable card describes nothing — there is no lock to explain.
+    rerender(<AskDisplay cards={[card('Which one?')]} onSelect={vi.fn()} />)
+    expect(screen.getByRole('group')).not.toHaveAttribute('aria-describedby')
+  })
+
+  it('hides the pager for a single card', () => {
+    render(<AskDisplay cards={[card('Which one?')]} onSelect={vi.fn()} />)
+
+    expect(screen.queryByText(/of 1/)).not.toBeInTheDocument()
+    expect(screen.queryByLabelText('Next question')).not.toBeInTheDocument()
+  })
+
+  it('pages through a run of cards, one question at a time', () => {
+    render(<AskDisplay cards={[card('First?'), card('Second?')]} onSelect={vi.fn()} />)
+
+    expect(screen.getByText('1 of 2')).toBeInTheDocument()
+    expect(screen.getByText('First?')).toBeInTheDocument()
+    expect(screen.queryByText('Second?')).not.toBeInTheDocument()
+    // At the first page there is nowhere back to go.
+    expect(screen.getByLabelText('Previous question')).toBeDisabled()
+
+    fireEvent.click(screen.getByLabelText('Next question'))
+
+    expect(screen.getByText('2 of 2')).toBeInTheDocument()
+    expect(screen.getByText('Second?')).toBeInTheDocument()
+    expect(screen.getByLabelText('Next question')).toBeDisabled()
+  })
+})

package/src/components/chat/__tests__/chat-message-list-ask.test.tsx

@@ -0,0 +1,100 @@
+/**
+ * Ask cards go stale once answered.
+ *
+ * The clarification card belongs to ONE turn: as soon as the user replies —
+ * by picking an option or by typing their own answer — the question is settled
+ * and re-clicking it would send a stale label into a conversation that already
+ * moved on. `ChatMessageList` therefore hands `onAskSelect` only to messages
+ * that no user message follows, which also locks every card in replayed
+ * history (each one is followed by the reply it produced).
+ */
+
+import { render } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { Message } from '../types/message.types'
+
+// The library hands back CALLBACK refs and the list invokes them on attach —
+// object refs would throw "scrollRef is not a function" during layout effects.
+const noopRef = () => {}
+vi.mock('use-stick-to-bottom', () => ({
+  useStickToBottom: () => ({
+    scrollRef: noopRef,
+    contentRef: noopRef,
+    scrollToBottom: vi.fn(),
+    stopScroll: vi.fn(),
+    isAtBottom: true,
+  }),
+}))
+
+/** Records the `onAskSelect` each row received, keyed by message id. */
+const askHandlers = new Map<string, unknown>()
+vi.mock('../chat-message-enhanced', async () => {
+  const { forwardRef } = await import('react')
+  return {
+    ChatMessageEnhanced: forwardRef<
+      HTMLDivElement,
+      { name?: string; content: unknown; onAskSelect?: (label: string) => void }
+    >(({ name, onAskSelect }, ref) => {
+      askHandlers.set(name ?? '', onAskSelect)
+      return <div ref={ref} />
+    }),
+  }
+})
+
+import { ChatMessageList } from '../chat-message-list'
+
+class ObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+vi.stubGlobal('IntersectionObserver', ObserverStub)
+vi.stubGlobal('ResizeObserver', ObserverStub)
+
+const askMessage = (id: string): Message => ({
+  id,
+  name: id,
+  role: 'assistant',
+  content: [{ type: 'ask', question: 'What would you like to do with tickets?', options: [{ label: 'Ticket features' }] }],
+})
+
+const userMessage = (id: string): Message => ({ id, name: id, role: 'user', content: 'Ticket features' })
+
+describe('ChatMessageList — ask cards lock after a reply', () => {
+  beforeEach(() => askHandlers.clear())
+
+  it('keeps the trailing card interactive while nothing follows it', () => {
+    const onAskSelect = vi.fn()
+    render(<ChatMessageList messages={[userMessage('u1'), askMessage('a1')]} onAskSelect={onAskSelect} />)
+
+    expect(askHandlers.get('a1')).toBe(onAskSelect)
+  })
+
+  it('locks a card once the user has replied after it', () => {
+    const onAskSelect = vi.fn()
+    render(
+      <ChatMessageList
+        messages={[askMessage('a1'), userMessage('u1'), { id: 'a2', name: 'a2', role: 'assistant', content: 'answer' }]}
+        onAskSelect={onAskSelect}
+      />,
+    )
+
+    expect(askHandlers.get('a1')).toBeUndefined()
+    // The turn AFTER the reply is live again — a fresh card there is clickable.
+    expect(askHandlers.get('a2')).toBe(onAskSelect)
+  })
+
+  it('locks every card in replayed history', () => {
+    const onAskSelect = vi.fn()
+    render(
+      <ChatMessageList
+        messages={[askMessage('a1'), userMessage('u1'), askMessage('a2'), userMessage('u2')]}
+        onAskSelect={onAskSelect}
+      />,
+    )
+
+    expect(askHandlers.get('a1')).toBeUndefined()
+    expect(askHandlers.get('a2')).toBeUndefined()
+  })
+})

package/src/components/chat/ask-display.tsx

@@ -0,0 +1,151 @@
+"use client"
+
+import { forwardRef, useEffect, useId, useState } from "react"
+
+import { cn } from "../../utils/cn"
+import { Chevron02LeftIcon, Chevron02RightIcon } from "../icons-v2-generated"
+import type { AskDisplayProps } from "./types"
+
+/** Why the card is locked. Surfaced twice on purpose: as the veil's `title`
+ *  (mouse) and as the group's `aria-describedby` text (keyboard / screen
+ *  reader) — a disabled control that doesn't say why reads as a bug. */
+const LOCKED_HINT = "This question was already answered"
+
+/**
+ * `ASK` segment — the assistant asking WHICH reading of an ambiguous question it
+ * should answer, as a card of numbered options instead of prose bullets
+ * (Figma 1:13775).
+ *
+ * Picking a row sends its `label` verbatim as the user's next message: the
+ * backend's guide classifier resolves that reply against the labels it offered,
+ * so the row text IS the protocol.
+ *
+ * Without `onSelect` the card renders LOCKED — dimmed under a veil, rows
+ * `disabled`, not-allowed cursor. That is the normal end state: `ChatMessageList`
+ * withholds the handler as soon as any user message follows the card, because
+ * the question it asked has been answered and re-clicking it would send a stale
+ * label into a conversation that moved on. Same state on observer surfaces,
+ * where a click would post into someone else's dialog.
+ *
+ * A run of consecutive `ask` segments is one card with a pager ("1 of 2"), so a
+ * turn that asks twice reads as a single block. With one card the pager is
+ * absent entirely — there is nothing to page through.
+ */
+const AskDisplay = forwardRef<HTMLDivElement, AskDisplayProps>(
+  ({ className, cards, onSelect, ...props }, ref) => {
+    const [index, setIndex] = useState(0)
+    const lockedHintId = useId()
+
+    // A shrinking run (segments replaced mid-stream) must not strand the pager
+    // past the end — clamp instead of rendering an undefined card.
+    useEffect(() => {
+      setIndex((current) => (current < cards.length ? current : Math.max(0, cards.length - 1)))
+    }, [cards.length])
+
+    const active = cards[Math.min(index, cards.length - 1)]
+    if (!active) return null
+
+    const showPager = cards.length > 1
+    const isInteractive = !!onSelect
+
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-label={active.question}
+        // A disabled control must say WHY. The veil's `title` is a mouse-only
+        // affordance, so the same sentence is also carried as group description
+        // text — that is what a screen-reader user hears on entering the card,
+        // instead of two silently "dimmed" buttons.
+        aria-describedby={isInteractive ? undefined : lockedHintId}
+        className={cn(
+          "flex flex-col gap-[var(--spacing-system-s)] rounded-md border border-ods-border bg-ods-bg p-[var(--spacing-system-s)]",
+          className
+        )}
+        {...props}
+      >
+        <div className="flex items-center gap-[var(--spacing-system-m)]">
+          <p className="min-w-0 flex-1 break-words text-h4 text-ods-text-primary">{active.question}</p>
+          {showPager && (
+            <div className="flex shrink-0 items-center gap-[var(--spacing-system-xxs)]">
+              <button
+                type="button"
+                aria-label="Previous question"
+                disabled={index === 0}
+                onClick={() => setIndex((current) => Math.max(0, current - 1))}
+                className="text-ods-text-secondary transition-colors hover:text-ods-text-primary disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:text-ods-text-secondary"
+              >
+                <Chevron02LeftIcon size={16} />
+              </button>
+              <span className="whitespace-nowrap text-h6 text-ods-text-secondary">
+                {index + 1} of {cards.length}
+              </span>
+              <button
+                type="button"
+                aria-label="Next question"
+                disabled={index === cards.length - 1}
+                onClick={() => setIndex((current) => Math.min(cards.length - 1, current + 1))}
+                className="text-ods-text-secondary transition-colors hover:text-ods-text-primary disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:text-ods-text-secondary"
+              >
+                <Chevron02RightIcon size={16} />
+              </button>
+            </div>
+          )}
+        </div>
+
+        {/* Locked state = the rows' own `disabled` (assistive tech hears
+            "dimmed button", focus skips them, clicks can't fire) PLUS a veil
+            over the whole block. The veil is what makes it READ as locked: it
+            greys the answers down to caption weight without touching their
+            markup, and — sitting above the rows — it owns the pointer, so the
+            not-allowed cursor and the "why" tooltip show anywhere over the
+            list, not just on a row. The pager stays live above it: paging is
+            reading, not answering. */}
+        <div className="relative">
+          <div className="flex flex-col overflow-hidden rounded-md border border-ods-border">
+            {/* Rows carry the divider on their TOP edge except the first, so the
+                list never ends on a hanging border (the design's trailing rule
+                belongs to the custom-answer input, which this card does not have). */}
+            {active.options.map((option, optionIndex) => (
+              <button
+                key={`${option.label}-${optionIndex}`}
+                type="button"
+                disabled={!isInteractive}
+                onClick={() => onSelect?.(option.label)}
+                className={cn(
+                  "flex w-full items-start gap-[var(--spacing-system-s)] bg-ods-card p-[var(--spacing-system-s)] text-left transition-colors",
+                  optionIndex > 0 && "border-t border-ods-border",
+                  "hover:bg-ods-bg-hover disabled:cursor-not-allowed disabled:hover:bg-ods-card"
+                )}
+              >
+                <span className="shrink-0 text-h4 text-ods-text-secondary">{optionIndex + 1}.</span>
+                <span className="flex min-w-0 flex-1 flex-col">
+                  <span className="break-words text-h4 text-ods-text-primary">{option.label}</span>
+                  {option.description && (
+                    <span className="break-words text-h6 text-ods-text-secondary">{option.description}</span>
+                  )}
+                </span>
+              </button>
+            ))}
+          </div>
+          {!isInteractive && (
+            <>
+              <span id={lockedHintId} className="sr-only">
+                {LOCKED_HINT}
+              </span>
+              <div
+                aria-hidden="true"
+                title={LOCKED_HINT}
+                className="absolute inset-0 cursor-not-allowed rounded-md bg-ods-bg/40"
+              />
+            </>
+          )}
+        </div>
+      </div>
+    )
+  }
+)
+
+AskDisplay.displayName = "AskDisplay"
+
+export { AskDisplay }

package/src/components/chat/chat-message-enhanced.tsx

@@ -12,6 +12,7 @@ import { ErrorMessageDisplay } from "./error-message-display"
 import { ContextCompactionDisplay } from "./context-compaction-display"
 import { ThinkingDisplay } from "./thinking-display"
 import { GuideDisplay } from "./guide-display"
+import { AskDisplay } from "./ask-display"
 import { SimpleMarkdownRenderer } from "../ui/markdown/simple-markdown-renderer"
 import type { ChatRef } from "./chat-ref.types"
 import { remarkCardLinks } from "./remark-card-links"
@@ -19,7 +20,7 @@ import { remarkStripCitations } from "./remark-strip-citations"
 import { remarkMentionChips } from "./remark-mention-chips"
 import { BlockCard, type BlockCardProps } from "./entity-cards/block-card"
 import { ChatContextChipStrip } from "./chat-context-picker"
-import type { MessageSegment, MessageContent, ChatMessageEnhancedProps } from "./types"
+import type { AskSegment, MessageSegment, MessageContent, ChatMessageEnhancedProps } from "./types"
 
 /** Inline `@marker:id` mention token in the message body (sibling of the
  *  `[card://]` grammar) — used to filter out items rendered inline from the
@@ -55,8 +56,32 @@ function normalizeContent(content: MessageContent): MessageSegment[] {
   return content
 }
 
+/**
+ * A RUN of consecutive `ask` segments is one paged card, not a stack of
+ * near-identical ones. Returns the run keyed by the index of its FIRST segment;
+ * the render draws the card there and skips every later index of the same run
+ * (an `ask` index missing from this map is a tail member).
+ */
+function groupAskRuns(segments: MessageSegment[]): Map<number, AskSegment[]> {
+  const runs = new Map<number, AskSegment[]>()
+  let headIndex = -1
+  segments.forEach((segment, index) => {
+    if (segment.type !== 'ask') {
+      headIndex = -1
+      return
+    }
+    if (headIndex === -1) {
+      headIndex = index
+      runs.set(index, [segment])
+      return
+    }
+    runs.get(headIndex)?.push(segment)
+  })
+  return runs
+}
+
 const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>(
-  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, approvalVariant, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderContextItem, renderMention, renderEntityCard, NavLinkAnchor, ...props }, ref) => {
+  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, approvalVariant, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderContextItem, renderMention, renderEntityCard, onAskSelect, NavLinkAnchor, ...props }, ref) => {
     const isUser = role === 'user'
     const isError = role === 'error'
     const authorType = authorTypeProp ?? (isUser ? 'user' : assistantType === 'mingo' ? 'mingo' : 'fae')
@@ -78,6 +103,8 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
 
     const segments = useMemo(() => normalizeContent(content), [content])
 
+    const askRuns = useMemo(() => groupAskRuns(segments), [segments])
+
     // Inline `@marker:id` mentions: the composer commits these tokens when the
     // user picks context via the `@`-flow, and the ASSISTANT routinely echoes
     // the same `@device:machineId` token back in its reply. The lib detects the
@@ -657,6 +684,12 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
                       {renderSegmentBody(index, segment.text, segmentIsStreaming)}
                     </GuideDisplay>
                   )
+                } else if (segment.type === 'ask') {
+                  // Only the run's head draws — the tail segments are pages of
+                  // the card already rendered above them.
+                  const run = askRuns.get(index)
+                  if (!run) return null
+                  return <AskDisplay key={index} cards={run} onSelect={onAskSelect} />
                 } else if (segment.type === 'tool_execution') {
                   return (
                     <ToolExecutionDisplay
@@ -767,6 +800,10 @@ const MemoizedChatMessageEnhanced = memo(ChatMessageEnhanced, (prevProps, nextPr
     // equality holds across streaming chunks.
     prevProps.renderMention === nextProps.renderMention &&
     prevProps.renderEntityCard === nextProps.renderEntityCard &&
+    // Same stability contract as the renderers above: hosts pass a `useCallback`
+    // (EmbeddableChat passes its memoized `handleSend`), so this holds across
+    // streaming chunks instead of re-rendering every ask card per chunk.
+    prevProps.onAskSelect === nextProps.onAskSelect &&
     prevProps.NavLinkAnchor === nextProps.NavLinkAnchor
   )
 })

package/src/components/chat/chat-message-list.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { useRef, useState, useCallback, useEffect, useLayoutEffect, useImperativeHandle, forwardRef } from "react"
+import { useRef, useState, useCallback, useEffect, useLayoutEffect, useImperativeHandle, useMemo, forwardRef } from "react"
 import { useStickToBottom } from "use-stick-to-bottom"
 import { cn } from "../../utils/cn"
 import { ChatMessageEnhanced } from "./chat-message-enhanced"
@@ -129,6 +129,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       resolveContextIcon,
       renderContextItem,
       renderMention,
+      onAskSelect,
       NavLinkAnchor,
       ...props
     },
@@ -148,6 +149,21 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
         initial: false,
       })
 
+    // ---- Ask cards go stale once answered ------------------------------
+    // A clarification card asks about the turn it belongs to. The moment the
+    // user says ANYTHING after it — clicking an option, or typing their own
+    // reply in the composer — the question is answered and the card is
+    // history: clicking it again would send a stale label into a conversation
+    // that already moved on. So the handler reaches only messages that no user
+    // message follows, which also locks every card in replayed history for
+    // free (each one is followed by the reply it produced).
+    const lastUserMessageIndex = useMemo(() => {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user') return i
+      }
+      return -1
+    }, [messages])
+
     // ---- Overlay guard: don't move the ground under an open menu -------
     // A ⋯ menu inside a bubble stays anchored to its trigger. While a reply
     // streams in, the follow-the-bottom scroll carries that trigger upward and
@@ -984,6 +1000,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
                     renderContextItem={renderContextItem}
                     renderMention={renderMention}
                     renderEntityCard={renderEntityCard}
+                    onAskSelect={index > lastUserMessageIndex ? onAskSelect : undefined}
                     NavLinkAnchor={NavLinkAnchor}
                   />
                 )