feat(ui): shared UI foundation (utilities, source/research primitives, markdown upgrade)

frontends/ui/package.json

@@ -24,15 +24,23 @@
     "@nvidia/foundations-react-core": "^0.600.0",
     "@react-pdf/renderer": "^4.3.2",
     "@tailwindcss/postcss": "^4.1.18",
+    "clsx": "^2.1.1",
     "http-proxy": "^1.18.1",
+    "katex": "^0.17.0",
     "marked": "^16.4.2",
+    "mermaid": "^11.16.0",
+    "motion": "^12.42.2",
     "next": "^16.2.6",
     "next-auth": "^4.24.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
     "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "tailwind-merge": "^3.6.0",
     "typescript": "5.9.3",
+    "unist-util-visit": "^5.1.0",
     "zod": "^3.24.2",
     "zustand": "^5.0.0"
   },

frontends/ui/src/app/globals.css

@@ -312,3 +312,130 @@ body {
 *::-webkit-scrollbar-thumb:hover {
   background-color: var(--background-color-accent-gray-hover);
 }
+
+/* =============================================================================
+   Shared chat-UI primitives (agent trace, answer prose, source cards).
+   Additive tokens + component classes referenced by shared/components.
+   ============================================================================= */
+:root {
+  --radius-card: 0.8rem;
+  --ease-premium: cubic-bezier(0.22, 1, 0.36, 1);
+  --color-agent-danger: #e5484d;
+  --text-answer: 0.975rem;
+  --text-answer-line-height: 1.65;
+  --spacing-section: 1.75rem;
+}
+
+/* ---- Answer prose: generous reading scale for the final answer -------------- */
+.answer-prose {
+  font-size: var(--text-answer);
+  line-height: var(--text-answer-line-height);
+  color: var(--text-color-primary);
+}
+.answer-prose h2 {
+  font-size: 1.375rem;
+  font-weight: 600;
+  margin-top: var(--spacing-section);
+  margin-bottom: 0.5rem;
+}
+.answer-prose h3 {
+  font-size: 1.125rem;
+  font-weight: 600;
+  margin-top: 1.25rem;
+  margin-bottom: 0.4rem;
+}
+.answer-prose p {
+  margin: 0.75rem 0;
+}
+.answer-prose ul,
+.answer-prose ol {
+  margin: 0.5rem 0 0.85rem;
+  padding-left: 1.25rem;
+}
+.answer-prose li {
+  margin: 0.2rem 0;
+}
+
+/* ---- Status atom: one visual language for every agent-trace node ------------ */
+@keyframes dot-breathe {
+  0%,
+  100% {
+    box-shadow: 0 0 0 2px color-mix(in srgb, var(--color-brand) 32%, transparent);
+  }
+  50% {
+    box-shadow: 0 0 0 6px color-mix(in srgb, var(--color-brand) 6%, transparent);
+  }
+}
+.status-dot {
+  position: relative;
+  display: grid;
+  place-items: center;
+  height: 0.625rem;
+  width: 0.625rem;
+  border-radius: 999px;
+  flex-shrink: 0;
+}
+.status-dot-xs {
+  height: 0.5rem;
+  width: 0.5rem;
+}
+.status-dot-running {
+  background-color: var(--color-brand);
+  animation: dot-breathe 1.9s var(--ease-premium) infinite;
+}
+.status-dot-done {
+  background-color: var(--color-green-500);
+}
+.status-dot-pending {
+  background-color: transparent;
+  border: 1px solid color-mix(in srgb, var(--border-color-base) 72%, transparent);
+}
+.status-dot-waiting {
+  background-color: var(--color-brand);
+  animation: dot-breathe 2.4s ease-in-out infinite;
+}
+.status-dot-interrupted {
+  background-color: var(--color-agent-danger);
+}
+.status-dot-error {
+  background-color: var(--color-agent-danger);
+}
+
+/* ---- Shared tool-call row (inline trace + research panel) -------------------- */
+/* Fixed-width dot column so the status dot centers on the trace rail. The height
+   matches the label's first line box (font-size x line-height) so the dot
+   centers on the first line of every row regardless of run-state or size. */
+.tool-call-row-dot {
+  width: 1.25rem;
+  height: calc(0.875rem * 1.3);
+}
+.tool-call-row-label {
+  letter-spacing: -0.005em;
+  line-height: 1.3;
+}
+.tool-call-row-args {
+  color: var(--text-color-secondary);
+  font-size: 0.8125rem;
+  line-height: 1.35;
+}
+
+/* ---- KaTeX display math inside rendered markdown ---------------------------- */
+.markdown-content .katex-display {
+  margin: 0.35rem 0 0.6rem;
+  padding: 0.55rem 0.7rem;
+  overflow-x: auto;
+  overflow-y: hidden;
+  background: var(--background-color-surface-raised);
+  border: 1px solid var(--border-color-base);
+  border-radius: var(--radius-card);
+}
+.markdown-content .katex {
+  font-size: 1.02em;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .status-dot-running,
+  .status-dot-waiting {
+    animation: none;
+  }
+}

frontends/ui/src/shared/components/Actions/CopyButton.spec.tsx

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { CopyButton } from './CopyButton'
+
+const writeText = vi.fn().mockResolvedValue(undefined)
+
+describe('CopyButton', () => {
+  beforeEach(() => {
+    writeText.mockClear()
+    Object.defineProperty(navigator, 'clipboard', { value: { writeText }, configurable: true })
+  })
+
+  test('copies the provided text and confirms with a checkmark', async () => {
+    render(<CopyButton text="There are 11,463 users." />)
+    fireEvent.click(screen.getByRole('button', { name: 'Copy' }))
+    expect(writeText).toHaveBeenCalledWith('There are 11,463 users.')
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Copied' })).toBeInTheDocument())
+  })
+
+  test('renders a custom label', () => {
+    render(<CopyButton text="x" label="Copy answer" />)
+    expect(screen.getByRole('button', { name: 'Copy answer' })).toBeInTheDocument()
+  })
+
+  test('does not throw when the clipboard API rejects', async () => {
+    writeText.mockRejectedValueOnce(new Error('blocked'))
+    render(<CopyButton text="x" />)
+    fireEvent.click(screen.getByRole('button', { name: 'Copy' }))
+    await waitFor(() => expect(writeText).toHaveBeenCalled())
+    expect(screen.getByRole('button', { name: 'Copy' })).toBeInTheDocument()
+  })
+})

frontends/ui/src/shared/components/Actions/CopyButton.tsx

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+'use client'
+
+import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
+import { Button } from '@/adapters/ui'
+import { Check, Copy } from '@/adapters/ui/icons'
+
+interface CopyButtonProps {
+  text: string
+  label?: string
+}
+
+const RESET_MS = 1500
+
+/**
+ * Tertiary icon button that copies `text` to the clipboard and briefly swaps to a
+ * check to confirm. Silently no-ops when the clipboard API is unavailable
+ * (e.g. an insecure context) so the answer surface never errors.
+ */
+export function CopyButton({ text, label = 'Copy' }: CopyButtonProps): ReactNode {
+  const [copied, setCopied] = useState(false)
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (resetTimer.current != null) clearTimeout(resetTimer.current)
+    },
+    [],
+  )
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(text)
+      setCopied(true)
+      if (resetTimer.current != null) clearTimeout(resetTimer.current)
+      resetTimer.current = setTimeout(() => setCopied(false), RESET_MS)
+    } catch {
+      setCopied(false)
+    }
+  }, [text])
+
+  return (
+    <Button
+      kind="tertiary"
+      size="tiny"
+      onClick={handleCopy}
+      aria-label={copied ? 'Copied' : label}
+      title={copied ? 'Copied' : label}
+    >
+      {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+    </Button>
+  )
+}

frontends/ui/src/shared/components/CollapsibleBlock/CollapsibleBlock.spec.tsx

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { useState } from 'react'
+import { fireEvent, render, screen } from '@/test-utils'
+import { describe, expect, test } from 'vitest'
+import { CollapsibleBlock } from './CollapsibleBlock'
+
+function Harness({ initialOpen = false }: { initialOpen?: boolean }) {
+  const [open, setOpen] = useState(initialOpen)
+  return (
+    <CollapsibleBlock title="Trace" open={open} onOpenChange={setOpen}>
+      <p>Body content</p>
+    </CollapsibleBlock>
+  )
+}
+
+describe('CollapsibleBlock', () => {
+  test('hides the body and reflects a collapsed state when closed', () => {
+    render(<Harness />)
+    const toggle = screen.getByRole('button', { name: 'Trace' })
+    expect(toggle).toHaveAttribute('aria-expanded', 'false')
+    expect(screen.queryByText('Body content')).not.toBeInTheDocument()
+  })
+
+  test('toggles the body open and reveals it via the header button', () => {
+    render(<Harness />)
+    const toggle = screen.getByRole('button', { name: 'Trace' })
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute('aria-expanded', 'true')
+    expect(screen.getByText('Body content')).toBeInTheDocument()
+  })
+
+  test('wires aria-controls to the disclosed region id', () => {
+    render(<Harness initialOpen />)
+    const toggle = screen.getByRole('button', { name: 'Trace' })
+    const regionId = toggle.getAttribute('aria-controls')
+    expect(regionId).toBeTruthy()
+    const region = document.getElementById(regionId as string)
+    expect(region).not.toBeNull()
+    expect(region).toHaveTextContent('Body content')
+  })
+
+  test('renders static without a toggle when not collapsible', () => {
+    render(
+      <CollapsibleBlock title="Static" open collapsible={false}>
+        <p>Always visible</p>
+      </CollapsibleBlock>,
+    )
+    expect(screen.queryByRole('button')).not.toBeInTheDocument()
+    expect(screen.getByText('Always visible')).toBeInTheDocument()
+  })
+})

frontends/ui/src/shared/components/CollapsibleBlock/CollapsibleBlock.tsx

@@ -0,0 +1,96 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * CollapsibleBlock
+ *
+ * The shared header + body disclosure used by agent surfaces (thinking trace,
+ * plan/approval blocks). A header button toggles an AnimatePresence height /
+ * opacity body so every block opens and closes with the same motion and reads
+ * uniform regardless of which surface renders it. Controlled: the parent owns
+ * the `open` state and is notified via `onOpenChange`.
+ */
+
+'use client'
+
+import type { FC, ReactNode } from 'react'
+import { useId } from 'react'
+import { AnimatePresence, motion } from 'motion/react'
+import { Flex, AnimatedChevron } from '@/adapters/ui'
+import { useReducedMotion } from '@/hooks/use-reduced-motion'
+
+export interface CollapsibleBlockProps {
+  /** Leading glyph rendered before the title (status atom, source icon, etc.). */
+  icon?: ReactNode
+  /** Primary header label. */
+  title: ReactNode
+  /** Trailing header content (counts, durations, the collapse affordance). */
+  meta?: ReactNode
+  /** Controlled open state. */
+  open: boolean
+  /** Notified when the header toggles (only when `collapsible`). */
+  onOpenChange?: (open: boolean) => void
+  /** When false the block renders static (no toggle, body always shown). */
+  collapsible?: boolean
+  children: ReactNode
+}
+
+export const CollapsibleBlock: FC<CollapsibleBlockProps> = ({
+  icon,
+  title,
+  meta,
+  open,
+  onOpenChange,
+  collapsible = true,
+  children,
+}) => {
+  const regionId = useId()
+  const prefersReducedMotion = useReducedMotion()
+  const header = (
+    <>
+      <Flex align="center" gap="2" className="min-w-0">
+        {icon != null && <span className="grid h-7 w-7 shrink-0 place-items-center">{icon}</span>}
+        {title}
+      </Flex>
+      {(meta != null || collapsible) && (
+        <Flex align="center" gap="1" className="shrink-0">
+          {meta}
+          {collapsible && <AnimatedChevron />}
+        </Flex>
+      )}
+    </>
+  )
+
+  return (
+    <div className="w-full py-1">
+      {collapsible ? (
+        <button
+          type="button"
+          onClick={() => onOpenChange?.(!open)}
+          aria-expanded={open}
+          aria-controls={regionId}
+          className="group flex w-full items-center justify-between rounded-[var(--radius-card)] py-1.5 text-left transition-colors"
+        >
+          {header}
+        </button>
+      ) : (
+        <div className="flex w-full items-center justify-between py-1.5">{header}</div>
+      )}
+
+      <AnimatePresence initial={false}>
+        {(open || !collapsible) && (
+          <motion.div
+            id={regionId}
+            initial={{ height: 0, opacity: 0 }}
+            animate={{ height: 'auto', opacity: 1 }}
+            exit={{ height: 0, opacity: 0 }}
+            transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
+            className="overflow-hidden"
+          >
+            {children}
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  )
+}