@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/flow/assistant/ConversationShell.test.tsx

@@ -0,0 +1,202 @@
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { TympanProvider } from '../../index'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { setViewportWidth } from '../../../test/media'
+import { AssistantConversation } from './AssistantConversation'
+import { ConversationShell } from './ConversationShell'
+import { groupThreadsByDay } from './threadDays'
+import type { ThreadSummary } from './ThreadHistory'
+import type { AssistantSession, Utterance } from './useAssistantSession'
+
+function fakeSession(over: Partial<AssistantSession> = {}): AssistantSession {
+  return {
+    utterances: [],
+    phase: 'idle',
+    working: false,
+    loadingHistory: false,
+    threadId: null,
+    draft: '',
+    setDraft: vi.fn(),
+    ask: vi.fn(),
+    halt: vi.fn(),
+    askAgain: vi.fn(),
+    canAskAgain: false,
+    setLoadingHistory: vi.fn(),
+    reset: vi.fn(),
+    restore: vi.fn(),
+    ...over,
+  }
+}
+
+/** A chat whose composer text lives in React state, like the real hook. */
+function LiveChat({ send, busy = false }: { send: (t?: string) => void; busy?: boolean }) {
+  const [input, setInput] = useState('')
+  return <AssistantConversation session={fakeSession({ draft: input, setDraft: setInput, ask: send, working: busy })} />
+}
+
+const graphMessage = (toolCallId: string): Utterance => ({
+  key: `m-${toolCallId}`,
+  speaker: 'assistant',
+  phase: 'settled',
+  blocks: [{ kind: 'toolCall', callId: toolCallId, tool: 'create_flow', phase: 'ok', result: { flowId: 'flow-12345678', graph: { nodes: [], connectors: [] } } }],
+})
+
+const now = new Date('2026-09-26T12:00:00')
+const day = (n: number) => new Date(now.getTime() - n * 86_400_000).toISOString()
+const conversations: ThreadSummary[] = [
+  { id: 'c1', title: 'Budget', updatedAt: day(0), agents: ['coder', 'reviewer', 'counter', 'writer'] },
+  { id: 'c2', title: 'Stage counts', updatedAt: day(1) },
+  { id: 'c3', title: 'Sources', updatedAt: day(3) },
+  { id: 'c4', title: 'Old plan', updatedAt: day(30) },
+]
+
+describe('AssistantConversation', () => {
+  it('is a polite log and sends with Enter, inserting a line break with Shift+Enter', async () => {
+    const send = vi.fn()
+    const { container } = render(<LiveChat send={send} />)
+    expect(container.querySelector('[role="log"]')).toHaveAttribute('aria-live', 'polite')
+    const box = screen.getByRole('textbox', { name: 'Message to the assistant' })
+    await userEvent.type(box, 'one{Shift>}{Enter}{/Shift}two')
+    expect(send).not.toHaveBeenCalled()
+    expect(box).toHaveValue('one\ntwo')
+    await userEvent.keyboard('{Enter}')
+    expect(send).toHaveBeenCalledTimes(1)
+    await expectNoAxeViolations(container)
+  })
+
+  it('keeps the composer editable while busy and offers stop instead of send', async () => {
+    const stop = vi.fn()
+    render(<AssistantConversation session={fakeSession({ working: true, halt: stop, phase: 'receiving' })} />)
+    expect(screen.getByRole('textbox')).not.toBeDisabled()
+    expect(screen.queryByRole('button', { name: 'Send' })).toBeNull()
+    await userEvent.click(screen.getByRole('button', { name: 'Stop' }))
+    expect(stop).toHaveBeenCalled()
+  })
+
+  it('shows a failed turn with its message and a retry action, announced assertively', async () => {
+    const retry = vi.fn()
+    render(<AssistantConversation session={fakeSession({ canAskAgain: true, askAgain: retry, utterances: [{ key: 'a', speaker: 'assistant', phase: 'broken', blocks: [], problem: 'quota exceeded' }] })} />)
+    expect(screen.getByRole('alert')).toHaveTextContent('quota exceeded')
+    await userEvent.click(screen.getByRole('button', { name: 'Try again' }))
+    expect(retry).toHaveBeenCalled()
+  })
+
+  it('sends a starter prompt from the empty state', async () => {
+    const send = vi.fn()
+    render(<AssistantConversation session={fakeSession({ ask: send })} suggestions={['Quantos casos no estágio 4?']} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Quantos casos no estágio 4?' }))
+    expect(send).toHaveBeenCalledWith('Quantos casos no estágio 4?')
+  })
+
+  it('works right to left: bubbles align by logical side and Enter still sends', async () => {
+    const send = vi.fn()
+    const { container } = render(
+      <TympanProvider locale="ar">
+        <div dir="rtl">
+          <AssistantConversation session={fakeSession({ ask: send, draft: 'مرحبا', utterances: [{ key: 'u', speaker: 'person', phase: 'settled', blocks: [{ kind: 'prose', body: 'سؤال' }] }] })} />
+        </div>
+      </TympanProvider>,
+    )
+    expect(container.querySelector('[data-speaker="person"]')).toHaveAttribute('data-align', 'end')
+    screen.getByRole('textbox').focus()
+    await userEvent.keyboard('{Enter}')
+    expect(send).toHaveBeenCalled()
+  })
+
+  it('uses the built-in Portuguese strings', () => {
+    render(
+      <TympanProvider locale="pt-BR">
+        <AssistantConversation session={fakeSession()} />
+      </TympanProvider>,
+    )
+    expect(screen.getByRole('textbox', { name: 'Mensagem para o assistente' })).toBeInTheDocument()
+  })
+
+  it('stops the typing indicator and skeleton under reduced motion and keeps bubble borders in forced colours', () => {
+    const css = cssOf('flow/assistant/assistant.css')
+    expect(mediaBlock(css, /\(prefers-reduced-motion: reduce\)/)).toMatch(/animation:\s*none/)
+    expect(mediaBlock(css, /\(forced-colors: active\)/)).toMatch(/CanvasText/)
+  })
+})
+
+describe('ConversationShell', () => {
+  it('groups by today, yesterday, last 7 days and older, in that order', () => {
+    expect(groupThreadsByDay(conversations, now).map((g) => g.bucket)).toEqual(['today', 'yesterday', 'lastWeek', 'older'])
+  })
+
+  it('puts an unparsable date in older', () => {
+    const groups = groupThreadsByDay([{ id: 'x', title: 'x', updatedAt: 'not a date' }], now)
+    expect(groups).toEqual([{ bucket: 'older', threads: [{ id: 'x', title: 'x', updatedAt: 'not a date' }] }])
+  })
+
+  it('shows the no-results message when filtering by favourites with none', async () => {
+    render(<ConversationShell session={fakeSession()} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} starred={{ ids: [], onChange: vi.fn() }} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Favourites only' }))
+    expect(screen.getByText('No conversation matches this filter.')).toBeInTheDocument()
+  })
+
+  it('names the conversation in the delete confirmation and deletes on confirm', async () => {
+    const confirm = vi.fn(async () => true)
+    const onDelete = vi.fn()
+    render(<ConversationShell session={fakeSession()} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={onDelete} onStartThread={vi.fn()} confirm={confirm} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Delete Budget' }))
+    expect(confirm).toHaveBeenCalledWith(expect.objectContaining({ title: 'Delete “Budget”?' }))
+    expect(onDelete).toHaveBeenCalledWith('c1')
+  })
+
+  it('opens the canvas for a graph result, keeps it closed once closed, and reopens from the composer', async () => {
+    const chat = fakeSession({ utterances: [graphMessage('t1')] })
+    const { rerender } = render(<ConversationShell session={chat} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} renderCanvas={() => <p>canvas body</p>} />)
+    const panel = screen.getByRole('complementary', { name: 'Live canvas' })
+    expect(within(panel).getByText('canvas body')).toBeInTheDocument()
+    await userEvent.click(screen.getByRole('button', { name: 'Close canvas' }))
+    expect(screen.queryByRole('complementary', { name: 'Live canvas' })).toBeNull()
+    rerender(<ConversationShell session={fakeSession({ utterances: [graphMessage('t1')] })} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} renderCanvas={() => <p>canvas body</p>} />)
+    expect(screen.queryByRole('complementary', { name: 'Live canvas' })).toBeNull()
+    await userEvent.click(screen.getByRole('button', { name: 'Open canvas' }))
+    expect(screen.getByRole('complementary', { name: 'Live canvas' })).toBeInTheDocument()
+    rerender(<ConversationShell session={fakeSession({ utterances: [graphMessage('t1'), graphMessage('t2')] })} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} renderCanvas={() => <p>canvas body</p>} />)
+    expect(screen.getByRole('complementary', { name: 'Live canvas' })).toBeInTheDocument()
+  })
+
+  it('reaches the history through a drawer on a narrow viewport', async () => {
+    setViewportWidth(375)
+    render(<ConversationShell session={fakeSession()} threads={conversations} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} />)
+    expect(screen.queryByRole('navigation', { name: 'Conversation history' })).toBeNull()
+    await userEvent.click(screen.getByRole('button', { name: 'Conversations' }))
+    expect(await screen.findByRole('navigation', { name: 'Conversation history' })).toBeInTheDocument()
+  })
+
+  it('marks the active row, keeps row actions visible, wraps long Japanese titles without cutting them, and passes axe', async () => {
+    const long = '段階別の件数と凍結版の比較に関する長い会話のタイトルです'
+    const { container } = render(
+      <TympanProvider locale="ja">
+        <ConversationShell session={fakeSession({ threadId: 'j1' })} threads={[{ id: 'j1', title: long, updatedAt: day(0) }]} onOpenThread={vi.fn()} onRemoveThread={vi.fn()} onStartThread={vi.fn()} />
+      </TympanProvider>,
+    )
+    const row = container.querySelector('.ty-convo-row__main')!
+    expect(row).toHaveAttribute('aria-current', 'page')
+    expect(row).toHaveAttribute('title', long)
+    expect(row.querySelector('.ty-convo-row__title')).toHaveTextContent(long)
+    expect(cssOf('flow/assistant/assistant.css')).toMatch(/\.ty-convo-row__title\s*\{[^}]*line-clamp/)
+    await expectNoAxeViolations(container)
+  })
+
+  it('works right to left with the history as a navigation landmark', async () => {
+    const onSelect = vi.fn()
+    render(
+      <TympanProvider locale="ar">
+        <div dir="rtl">
+          <ConversationShell session={fakeSession()} threads={[{ id: 'a1', title: 'عدد الحالات', updatedAt: day(0) }]} onOpenThread={onSelect} onRemoveThread={vi.fn()} onStartThread={vi.fn()} />
+        </div>
+      </TympanProvider>,
+    )
+    const nav = screen.getByRole('navigation')
+    await userEvent.click(within(nav).getByText('عدد الحالات'))
+    expect(onSelect).toHaveBeenCalledWith('a1')
+  })
+})

package/src/flow/assistant/ConversationShell.tsx

@@ -0,0 +1,160 @@
+// ConversationShell: the assistant's full-screen workspace, assembled from
+// three regions: the thread history (inline start), the dialogue (centre) and
+// the live canvas (inline end) when the assistant produced or opened a flow.
+// Below the small breakpoint the history lives in a drawer; below the medium
+// one the canvas does.
+
+import { useMemo, useReducer, useRef, type ReactNode } from 'react'
+import { History } from 'lucide-react'
+import { Button, Drawer, useMediaQuery } from '../../index'
+import { useConfirm, type ConfirmFn } from '../internal/confirm'
+import { fill, useFlowLocale, useLabels } from '../internal/labels'
+import { AssistantConversation, assistantLabels, type AssistantLabels } from './AssistantConversation'
+import { LiveCanvasPanel } from './LiveCanvasPanel'
+import { deviceStarStore, ThreadHistory, type StarredThreads, type ThreadSummary } from './ThreadHistory'
+import { newestFlowArtifact, type AssistantSession, type FlowArtifact } from './useAssistantSession'
+
+export interface ConversationShellProps {
+  session: AssistantSession
+  threads: ThreadSummary[]
+  onOpenThread: (id: string) => void
+  onRemoveThread: (id: string) => Promise<void> | void
+  onStartThread: () => void
+  labels?: Partial<AssistantLabels>
+  suggestions?: string[]
+  /** Mounts the real editor for a flow artifact; a read-only preview otherwise. */
+  renderCanvas?: (artifact: FlowArtifact) => ReactNode
+  banner?: ReactNode
+  appMark?: ReactNode
+  starred?: StarredThreads
+  /** Time zone of the day groups (the device's by default). */
+  timeZone?: string
+  /** Confirmation service (the nearest ConfirmProvider by default). */
+  confirm?: ConfirmFn
+  locale?: string
+  currency?: string
+  className?: string
+}
+
+interface Workspace {
+  starredOnly: boolean
+  historyDrawer: boolean
+  localStars: string[]
+  /** Artifact the person closed; a newer one opens the canvas again. */
+  dismissed: string | null
+}
+
+type WorkspaceMove = { set: Partial<Workspace> }
+
+const workspaceReducer = (w: Workspace, m: WorkspaceMove): Workspace => ({ ...w, ...m.set })
+
+export function ConversationShell(props: ConversationShellProps) {
+  const { session, threads, timeZone, currency } = props
+  const l = useLabels(assistantLabels, props.labels)
+  const fromProvider = useFlowLocale().locale
+  const locale = props.locale ?? fromProvider
+  const contextConfirm = useConfirm()
+  const confirm = props.confirm ?? contextConfirm
+  const historyBeside = useMediaQuery('(min-width: 640px)', true)
+  const canvasBeside = useMediaQuery('(min-width: 768px)', true)
+  const rootRef = useRef<HTMLDivElement>(null)
+  const [w, move] = useReducer(workspaceReducer, undefined, (): Workspace => ({ starredOnly: false, historyDrawer: false, localStars: props.starred ? [] : deviceStarStore.load(), dismissed: null }))
+  const set = (patch: Partial<Workspace>) => move({ set: patch })
+
+  const starredIds = props.starred?.ids ?? w.localStars
+  const star = (id: string, on: boolean) => {
+    const next = on ? [...starredIds, id] : starredIds.filter((x) => x !== id)
+    if (props.starred) {
+      props.starred.onChange(next)
+      return
+    }
+    set({ localStars: next })
+    deviceStarStore.save(next)
+  }
+
+  const artifact = useMemo(() => newestFlowArtifact(session.utterances), [session.utterances])
+  const canvasOpen = !!artifact && w.dismissed !== artifact.callId
+  const closeCanvas = () => {
+    if (artifact) set({ dismissed: artifact.callId })
+    requestAnimationFrame(() => rootRef.current?.querySelector<HTMLElement>('[data-ty-composer]')?.focus())
+  }
+
+  const remove = async (t: ThreadSummary) => {
+    const ok = await confirm({ title: fill(l.deleteTitle, { title: t.title }, locale), message: l.deleteMessage, confirmLabel: l.confirmDelete, cancelLabel: l.cancel, tone: 'danger' })
+    if (ok) await props.onRemoveThread(t.id)
+  }
+
+  const history = (
+    <ThreadHistory
+      threads={threads}
+      currentId={session.threadId}
+      starred={starredIds}
+      starredOnly={w.starredOnly}
+      {...(timeZone ? { zone: timeZone } : {})}
+      labels={l}
+      locale={locale}
+      onStarredOnly={(on) => set({ starredOnly: on })}
+      onStar={star}
+      onOpen={(id) => {
+        props.onOpenThread(id)
+        set({ historyDrawer: false })
+      }}
+      onRemove={(t) => void remove(t)}
+      onStart={props.onStartThread}
+    />
+  )
+
+  const regions: Array<{ key: string; node: ReactNode }> = [
+    {
+      key: 'history',
+      node: historyBeside ? (
+        history
+      ) : (
+        <Drawer open={w.historyDrawer} onOpenChange={(open) => set({ historyDrawer: open })} title={l.history} placement="bottom">
+          {history}
+        </Drawer>
+      ),
+    },
+    {
+      key: 'centre',
+      node: (
+        <div className="ty-convo-shell__centre">
+          {historyBeside ? null : (
+            <div className="ty-convo-shell__bar">
+              <Button variant="secondary" size="compact" leadingIcon={<History />} onPress={() => set({ historyDrawer: true })}>
+                {l.openHistory}
+              </Button>
+            </div>
+          )}
+          {props.banner ? <div className="ty-convo-shell__banner">{props.banner}</div> : null}
+          <AssistantConversation
+            session={session}
+            labels={l}
+            variant="full"
+            {...(props.suggestions ? { suggestions: props.suggestions } : {})}
+            {...(props.appMark ? { appMark: props.appMark } : {})}
+            canOpenCanvas={!!artifact && !canvasOpen}
+            onOpenCanvas={() => set({ dismissed: null })}
+            locale={locale}
+            {...(currency ? { currency } : {})}
+          />
+        </div>
+      ),
+    },
+    {
+      key: 'canvas',
+      node: artifact && canvasOpen ? <LiveCanvasPanel artifact={artifact} docked={canvasBeside} labels={l} locale={locale} {...(props.renderCanvas ? { render: props.renderCanvas } : {})} onClose={closeCanvas} /> : null,
+    },
+  ]
+
+  return (
+    <div ref={rootRef} className={['ty-convo-shell', props.className].filter(Boolean).join(' ')} data-canvas={canvasOpen && canvasBeside ? 'open' : undefined}>
+      {regions.map((r) => (r.node ? <RegionSlot key={r.key}>{r.node}</RegionSlot> : null))}
+    </div>
+  )
+}
+
+/** Keeps each region's element as a direct child of the shell grid. */
+function RegionSlot({ children }: { children: ReactNode }) {
+  return <>{children}</>
+}

package/src/flow/assistant/LiveCanvasPanel.tsx

@@ -0,0 +1,52 @@
+// The live canvas beside the dialogue: the newest flow the assistant built or
+// opened. A complementary landmark on wide screens, a full-screen drawer on
+// narrow ones. The body is the host's editor mount, or a read-only preview.
+
+import type { ReactNode } from 'react'
+import { X } from 'lucide-react'
+import { Button, Drawer } from '../../index'
+import { FlowPreview } from '../editor/FlowPreview'
+import { fill } from '../internal/labels'
+import type { FlowConnector, FlowNode } from '../model/types'
+import type { AssistantLabels } from './AssistantConversation'
+import type { FlowArtifact } from './useAssistantSession'
+
+function previewGraph(graph: Record<string, unknown>): { nodes: FlowNode[]; connectors: FlowConnector[] } {
+  const nodes = Array.isArray(graph.nodes) ? (graph.nodes as FlowNode[]) : []
+  const connectors = Array.isArray(graph.connectors) ? (graph.connectors as FlowConnector[]) : Array.isArray(graph.edges) ? (graph.edges as FlowConnector[]) : []
+  return { nodes, connectors }
+}
+
+export interface LiveCanvasPanelProps {
+  artifact: FlowArtifact
+  docked: boolean
+  labels: AssistantLabels
+  locale: string
+  render?: (artifact: FlowArtifact) => ReactNode
+  onClose: () => void
+}
+
+export function LiveCanvasPanel({ artifact, docked, labels: l, locale, render, onClose }: LiveCanvasPanelProps) {
+  const body = <div className="ty-convo-canvas__body">{render ? render(artifact) : <FlowPreview graph={previewGraph(artifact.graph)} />}</div>
+  if (!docked) {
+    return (
+      <Drawer open onOpenChange={(open) => (open ? undefined : onClose())} title={l.liveCanvas} placement="bottom" maxHeight="100dvh">
+        {body}
+      </Drawer>
+    )
+  }
+  return (
+    <aside className="ty-convo-canvas" aria-label={l.liveCanvas}>
+      <header className="ty-convo-canvas__header">
+        <h2 className="ty-convo-canvas__title">{l.liveCanvas}</h2>
+        {artifact.flowId ? (
+          <code className="ty-convo-canvas__id" title={artifact.flowId}>
+            {fill(l.flowId, { id: artifact.flowId.slice(0, 8) }, locale)}
+          </code>
+        ) : null}
+        <Button variant="quiet" size="compact" shape="circle" iconOnly accessibleLabel={l.closeCanvas} leadingIcon={<X />} onPress={onClose} />
+      </header>
+      {body}
+    </aside>
+  )
+}

package/src/flow/assistant/MarkdownView.tsx

@@ -0,0 +1,162 @@
+// MarkdownView: a small, safe reader for the Markdown a language model writes
+// (paragraphs, headings, lists, fenced code, quotes, inline code, strong,
+// emphasis, links). Output is React elements only: no HTML string is ever
+// injected, and links are kept only for http(s), mailto and app-relative paths.
+
+import { Fragment, type ReactNode } from 'react'
+
+type Block =
+  | { kind: 'heading'; level: number; text: string }
+  | { kind: 'paragraph'; text: string }
+  | { kind: 'list'; ordered: boolean; items: string[] }
+  | { kind: 'code'; lang: string; text: string }
+  | { kind: 'quote'; text: string }
+
+const SAFE_HREF = /^(https?:\/\/|mailto:|\/(?!\/))/i
+
+/** Splits Markdown into blocks, line by line. */
+export function markdownBlocks(source: string): Block[] {
+  const lines = source.replace(/\r\n?/g, '\n').split('\n')
+  const blocks: Block[] = []
+  let para: string[] = []
+  const flush = () => {
+    if (para.length) blocks.push({ kind: 'paragraph', text: para.join(' ') })
+    para = []
+  }
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const fence = /^\s*```(\w*)\s*$/.exec(line)
+    if (fence) {
+      flush()
+      const body: string[] = []
+      i++
+      while (i < lines.length && !/^\s*```\s*$/.test(lines[i]!)) body.push(lines[i++]!)
+      blocks.push({ kind: 'code', lang: fence[1] ?? '', text: body.join('\n') })
+      continue
+    }
+    if (!line.trim()) {
+      flush()
+      continue
+    }
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+    if (heading) {
+      flush()
+      blocks.push({ kind: 'heading', level: heading[1]!.length, text: heading[2]!.trim() })
+      continue
+    }
+    const bullet = /^\s*(?:[-*+]|(\d+)[.)])\s+(.*)$/.exec(line)
+    if (bullet) {
+      flush()
+      const ordered = bullet[1] !== undefined
+      const prev = blocks[blocks.length - 1]
+      if (prev && prev.kind === 'list' && prev.ordered === ordered) prev.items.push(bullet[2]!)
+      else blocks.push({ kind: 'list', ordered, items: [bullet[2]!] })
+      continue
+    }
+    const quote = /^\s*>\s?(.*)$/.exec(line)
+    if (quote) {
+      flush()
+      const prev = blocks[blocks.length - 1]
+      if (prev && prev.kind === 'quote') prev.text += ` ${quote[1]}`
+      else blocks.push({ kind: 'quote', text: quote[1] ?? '' })
+      continue
+    }
+    para.push(line.trim())
+  }
+  flush()
+  return blocks
+}
+
+const INLINE = /(`[^`]+`)|(\*\*[^*]+\*\*|__[^_]+__)|(\*[^*\s][^*]*\*|_[^_\s][^_]*_)|(\[[^\]]+\]\([^)\s]+\))/
+
+/** Inline spans: code, strong, emphasis and safe links. */
+export function renderInline(text: string, keyPrefix = 'i'): ReactNode[] {
+  const out: ReactNode[] = []
+  let rest = text
+  let n = 0
+  while (rest) {
+    const m = INLINE.exec(rest)
+    if (!m) {
+      out.push(rest)
+      break
+    }
+    if (m.index > 0) out.push(rest.slice(0, m.index))
+    const token = m[0]
+    const key = `${keyPrefix}-${n++}`
+    if (m[1]) out.push(<code key={key}>{token.slice(1, -1)}</code>)
+    else if (m[2]) out.push(<strong key={key}>{renderInline(token.slice(2, -2), key)}</strong>)
+    else if (m[3]) out.push(<em key={key}>{renderInline(token.slice(1, -1), key)}</em>)
+    else {
+      const link = /^\[([^\]]+)\]\(([^)\s]+)\)$/.exec(token)!
+      const href = link[2]!
+      out.push(
+        SAFE_HREF.test(href) ? (
+          <a key={key} href={href} {...(/^https?:/i.test(href) ? { target: '_blank', rel: 'noreferrer noopener' } : {})}>
+            {renderInline(link[1]!, key)}
+          </a>
+        ) : (
+          <Fragment key={key}>{link[1]}</Fragment>
+        ),
+      )
+    }
+    rest = rest.slice(m.index + token.length)
+  }
+  return out
+}
+
+export interface MarkdownViewProps {
+  source: string
+  /** Level of a top-level "#" heading; deeper headings follow, capped at 6. */
+  baseHeadingLevel?: 2 | 3 | 4
+  className?: string
+}
+
+export function MarkdownView({ source, baseHeadingLevel = 3, className }: MarkdownViewProps) {
+  const blocks = markdownBlocks(source)
+  return (
+    <div className={['ty-flow-markdown', className].filter(Boolean).join(' ')}>
+      {blocks.map((b, i) => {
+        const key = `b${i}`
+        switch (b.kind) {
+          case 'heading': {
+            const level = Math.min(6, baseHeadingLevel + b.level - 1)
+            const H = `h${level}` as 'h2'
+            return (
+              <H key={key} className="ty-flow-markdown__heading">
+                {renderInline(b.text, key)}
+              </H>
+            )
+          }
+          case 'list': {
+            const L = b.ordered ? 'ol' : 'ul'
+            return (
+              <L key={key} className="ty-flow-markdown__list">
+                {b.items.map((item, j) => (
+                  <li key={j}>{renderInline(item, `${key}-${j}`)}</li>
+                ))}
+              </L>
+            )
+          }
+          case 'code':
+            return (
+              <pre key={key} className="ty-flow-markdown__code" tabIndex={0} data-lang={b.lang || undefined}>
+                <code>{b.text}</code>
+              </pre>
+            )
+          case 'quote':
+            return (
+              <blockquote key={key} className="ty-flow-markdown__quote">
+                {renderInline(b.text, key)}
+              </blockquote>
+            )
+          default:
+            return (
+              <p key={key} className="ty-flow-markdown__paragraph">
+                {renderInline(b.text, key)}
+              </p>
+            )
+        }
+      })}
+    </div>
+  )
+}