@startsimpli/ui 0.4.42 → 0.4.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.42",
+  "version": "0.4.44",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -20,6 +20,7 @@
     "./email-editor": "./src/components/email-editor/index.ts",
     "./workflows": "./src/components/workflows/index.ts",
     "./workflows/styles": "./src/components/workflows/workflows.css",
+    "./terminal/styles": "./src/components/terminal/xterm.css",
     "./tailwind": "./tailwind.preset.js"
   },
   "files": [
@@ -35,8 +36,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "0.5.41",
-    "@startsimpli/auth": "0.4.29"
+    "@startsimpli/auth": "0.4.29",
+    "@startsimpli/api": "0.5.42"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -51,8 +52,10 @@
   },
   "dependencies": {
     "@hello-pangea/dnd": "^18.0.1",
+    "@xterm/addon-fit": "^0.10.0",
     "@xyflow/react": "^12.10.2",
     "dagre": "^0.8.5",
+    "xterm": "^5.3.0",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
@@ -79,7 +82,8 @@
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^2.6.1",
     "tailwindcss-animate": "^1.0.7",
-    "xlsx": "^0.18.5"
+    "xlsx": "^0.18.5",
+    "@startsimpli/realtime": "0.0.1"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/src/catalog/catalog.ts

@@ -135,4 +135,33 @@ export const UI_CATALOG: CatalogEntry[] = [
     dataNeeds: 'A messages/thread type.',
     source: { export: 'ChatThread', from: '@startsimpli/ui' },
   },
+  {
+    id: 'session-list',
+    category: 'view',
+    title: 'Agent sessions list',
+    description:
+      "A presentational grid/table of agent-run sessions (name, status, branch, project) — cards or a project-grouped table. Use for a coding/agent workspace's session index. Status is injected per row (no per-row queries).",
+    dataNeeds: 'A session/run type mapped to the SessionSummary view-model.',
+    source: { export: 'SessionList', from: '@startsimpli/ui' },
+  },
+  {
+    id: 'agent-terminal',
+    category: 'component',
+    title: 'Agent terminal',
+    description:
+      'A live xterm.js terminal you drive imperatively (the parent owns the transport and pumps output in). Use for a session/agent surface that streams a PTY. Import styles from @startsimpli/ui/terminal/styles.',
+    dataNeeds: 'A streaming agent/PTY transport (not schema data).',
+    heavy: true,
+    source: { export: 'Terminal', from: '@startsimpli/ui' },
+  },
+  {
+    id: 'agent-session-console',
+    category: 'component',
+    title: 'Agent session console',
+    description:
+      'The full live session surface: a terminal + a steer-the-agent conversation timeline + a diff tab, driven by @startsimpli/realtime over a websocket. Use for the session-detail page of an agent/coding workspace.',
+    dataNeeds: 'A realtime agent-session websocket URL (not schema data).',
+    heavy: true,
+    source: { export: 'AgentSessionConsole', from: '@startsimpli/ui' },
+  },
 ];

package/src/components/__tests__/conversation-timeline.test.tsx

@@ -0,0 +1,56 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { ConversationTimeline } from '../session/ConversationTimeline'
+import type { ChatMessageData } from '../chat/types'
+
+beforeAll(() => {
+  Element.prototype.scrollIntoView = jest.fn()
+})
+
+const entries: ChatMessageData[] = [
+  { id: '1', role: 'assistant', content: 'Started the task' },
+  { id: '2', role: 'tool', kind: 'tool', toolName: 'bash', content: 'npm test' },
+  { id: '3', role: 'user', content: 'Focus on the billing page' },
+]
+
+describe('ConversationTimeline', () => {
+  it('renders the timeline entries', () => {
+    render(<ConversationTimeline entries={entries} />)
+    expect(screen.getByText('Started the task')).toBeInTheDocument()
+    expect(screen.getByText('npm test')).toBeInTheDocument()
+    expect(screen.getByText('Focus on the billing page')).toBeInTheDocument()
+  })
+
+  it('renders header title, status label, and a progress bar', () => {
+    render(<ConversationTimeline entries={entries} title="Session goal" statusLabel="Connected" progressPercent={42} />)
+    expect(screen.getByText('Session goal')).toBeInTheDocument()
+    expect(screen.getByText('Connected')).toBeInTheDocument()
+    const bar = screen.getByRole('progressbar')
+    expect(bar).toHaveAttribute('aria-valuenow', '42')
+  })
+
+  it('sends composed text via onSend', () => {
+    const onSend = jest.fn()
+    render(<ConversationTimeline entries={entries} onSend={onSend} />)
+    const textarea = screen.getByRole('textbox')
+    fireEvent.change(textarea, { target: { value: 'steer left' } })
+    fireEvent.keyDown(textarea, { key: 'Enter' })
+    expect(onSend).toHaveBeenCalledWith('steer left')
+  })
+
+  it('does not render a composer when onSend is omitted', () => {
+    render(<ConversationTimeline entries={entries} />)
+    expect(screen.queryByRole('textbox')).not.toBeInTheDocument()
+  })
+
+  it('renders a "Load earlier messages" control when hasMore', () => {
+    const onLoadMore = jest.fn()
+    render(<ConversationTimeline entries={entries} hasMore onLoadMore={onLoadMore} />)
+    fireEvent.click(screen.getByRole('button', { name: /load earlier messages/i }))
+    expect(onLoadMore).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows the working indicator when isLoading', () => {
+    render(<ConversationTimeline entries={entries} isLoading />)
+    expect(screen.getByTestId('chat-working-indicator')).toBeInTheDocument()
+  })
+})

package/src/components/__tests__/diff-viewer.test.tsx

@@ -0,0 +1,101 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { DiffViewer, parseDiffFiles, diffLineClass } from '../diff/DiffViewer'
+
+const SAMPLE_DIFF = `diff --git a/src/foo.ts b/src/foo.ts
+index 1234567..89abcde 100644
+--- a/src/foo.ts
++++ b/src/foo.ts
+@@ -1,3 +1,3 @@
+ const a = 1
+-const b = 2
++const b = 3
+diff --git a/src/bar.ts b/src/bar.ts
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/src/bar.ts
+@@ -0,0 +1,2 @@
++export const bar = 'baz'
++export default bar
+`
+
+describe('parseDiffFiles', () => {
+  it('splits a unified diff into one block per file with the b/ path', () => {
+    const files = parseDiffFiles(SAMPLE_DIFF)
+    expect(files).toHaveLength(2)
+    expect(files[0].filePath).toBe('src/foo.ts')
+    expect(files[1].filePath).toBe('src/bar.ts')
+    // the block carries its own lines (including the hunk header)
+    expect(files[0].lines.some((l) => l.startsWith('@@'))).toBe(true)
+  })
+
+  it('returns an empty array for empty / whitespace input', () => {
+    expect(parseDiffFiles('')).toEqual([])
+    expect(parseDiffFiles('   \n  ')).toEqual([])
+  })
+})
+
+describe('diffLineClass', () => {
+  it('colourises added / removed / hunk / context lines', () => {
+    expect(diffLineClass('+added')).toContain('emerald')
+    expect(diffLineClass('-removed')).toContain('red')
+    expect(diffLineClass('@@ -1 +1 @@')).toContain('cyan')
+    expect(diffLineClass(' context')).toContain('muted-foreground')
+  })
+})
+
+describe('DiffViewer', () => {
+  it('renders per-file blocks and colourised +/-/@@ lines', () => {
+    render(<DiffViewer diff={SAMPLE_DIFF} baseRef="main" />)
+    // both file headers render
+    expect(screen.getByText('src/foo.ts')).toBeInTheDocument()
+    expect(screen.getByText('src/bar.ts')).toBeInTheDocument()
+    // an added line is present and coloured; metadata lines are hidden
+    expect(screen.getByText('+const b = 3')).toHaveClass('bg-emerald-500/10')
+    expect(screen.getByText('-const b = 2')).toHaveClass('bg-red-500/10')
+    expect(screen.queryByText(/^index 1234567/)).not.toBeInTheDocument()
+    // base ref shown in header
+    expect(screen.getByText('main')).toBeInTheDocument()
+  })
+
+  it('renders a summary line with staged/unstaged counts', () => {
+    render(<DiffViewer diff={SAMPLE_DIFF} summary={{ totalFiles: 2, staged: 1, unstaged: 1 }} />)
+    const summary = screen.getByTestId('diff-viewer-summary')
+    expect(summary).toHaveTextContent('2 files changed')
+    expect(summary).toHaveTextContent('1 staged')
+    expect(summary).toHaveTextContent('1 unstaged')
+  })
+
+  it('shows the empty state (with custom label) when the diff is empty', () => {
+    render(<DiffViewer diff="" emptyLabel="Nothing to review" />)
+    expect(screen.getByTestId('diff-viewer-empty')).toBeInTheDocument()
+    expect(screen.getByText('Nothing to review')).toBeInTheDocument()
+  })
+
+  it('shows a loading state', () => {
+    render(<DiffViewer diff="" isLoading />)
+    expect(screen.getByTestId('diff-viewer-loading')).toBeInTheDocument()
+  })
+
+  it('shows an error state and fires onRefresh from Try again', () => {
+    const onRefresh = jest.fn()
+    render(<DiffViewer diff="" error="boom" onRefresh={onRefresh} />)
+    expect(screen.getByTestId('diff-viewer-error')).toBeInTheDocument()
+    expect(screen.getByText('boom')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: /try again/i }))
+    expect(onRefresh).toHaveBeenCalledTimes(1)
+  })
+
+  it('fires onRefresh from the header refresh button', () => {
+    const onRefresh = jest.fn()
+    render(<DiffViewer diff={SAMPLE_DIFF} onRefresh={onRefresh} />)
+    fireEvent.click(screen.getByRole('button', { name: /refresh diff/i }))
+    expect(onRefresh).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders a collapsible working-tree status block', () => {
+    render(<DiffViewer diff={SAMPLE_DIFF} status="?? untracked.ts" />)
+    expect(screen.getByText('Working tree status')).toBeInTheDocument()
+    expect(screen.getByText('?? untracked.ts')).toBeInTheDocument()
+  })
+})

package/src/components/__tests__/session-components.test.tsx

@@ -0,0 +1,184 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { SessionCard, formatRelative } from '../session/SessionCard'
+import { SessionList } from '../session/SessionList'
+import { SessionStatusBadge } from '../session/SessionStatusBadge'
+import { resolveSessionStatus, mapSocketStatus } from '../session/status'
+import type { SessionSummary } from '../session/types'
+
+const base: SessionSummary = {
+  id: 's1',
+  number: 7,
+  name: 'Add billing page',
+  isActive: true,
+  projectName: 'raise-simpli',
+  agentName: 'Claude',
+  branch: 'feat/billing',
+  createdAt: '2026-07-01T00:00:00.000Z',
+}
+
+// ---------------------------------------------------------------------------
+// status helpers (pure)
+// ---------------------------------------------------------------------------
+
+describe('resolveSessionStatus', () => {
+  it('prefers an explicit status kind + label', () => {
+    const r = resolveSessionStatus({ status: 'error', statusLabel: 'Crashed', isActive: false })
+    expect(r.kind).toBe('error')
+    expect(r.label).toBe('Crashed')
+    expect(r.className).toContain('red')
+  })
+
+  it('derives active/idle from isActive when status is absent', () => {
+    expect(resolveSessionStatus({ isActive: true }).kind).toBe('active')
+    expect(resolveSessionStatus({ isActive: false }).kind).toBe('idle')
+  })
+
+  it('supplies a default label per kind', () => {
+    expect(resolveSessionStatus({ status: 'success', isActive: false }).label).toBe('Success')
+  })
+})
+
+describe('mapSocketStatus', () => {
+  it('maps agent socket status onto the terminal status', () => {
+    expect(mapSocketStatus('open')).toBe('connected')
+    expect(mapSocketStatus('connecting')).toBe('connecting')
+    expect(mapSocketStatus('reconnecting')).toBe('connecting')
+    expect(mapSocketStatus('idle')).toBe('disconnected')
+    expect(mapSocketStatus('closed')).toBe('disconnected')
+  })
+})
+
+describe('formatRelative', () => {
+  it('formats a valid timestamp and passes an unparseable one through', () => {
+    expect(formatRelative('2026-07-01T00:00:00.000Z')).toMatch(/ago|in /)
+    expect(formatRelative('not-a-date')).toBe('not-a-date')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// SessionStatusBadge
+// ---------------------------------------------------------------------------
+
+describe('SessionStatusBadge', () => {
+  it('renders the resolved status label and tags the kind', () => {
+    render(<SessionStatusBadge status="warning" />)
+    const badge = screen.getByRole('status')
+    expect(badge).toHaveAttribute('data-status', 'warning')
+    expect(badge).toHaveTextContent('Needs review')
+  })
+
+  it('falls back to isActive when no status is given', () => {
+    render(<SessionStatusBadge isActive />)
+    expect(screen.getByRole('status')).toHaveAttribute('data-status', 'active')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// SessionCard
+// ---------------------------------------------------------------------------
+
+describe('SessionCard', () => {
+  it('renders name, branch, project, agent, number, and status', () => {
+    render(<SessionCard session={base} />)
+    expect(screen.getByText('Add billing page')).toBeInTheDocument()
+    expect(screen.getByText('feat/billing')).toBeInTheDocument()
+    expect(screen.getByText('raise-simpli')).toBeInTheDocument()
+    expect(screen.getByText('Claude')).toBeInTheDocument()
+    expect(screen.getByText('007')).toBeInTheDocument() // zero-padded number
+    expect(screen.getByRole('status')).toHaveTextContent('Active')
+  })
+
+  it('renders the title as a link when href is provided', () => {
+    render(<SessionCard session={base} href={(id) => `/sessions/${id}`} />)
+    const link = screen.getByRole('link', { name: 'Add billing page' })
+    expect(link).toHaveAttribute('href', '/sessions/s1')
+  })
+
+  it('calls onOpen when clicked (no href)', () => {
+    const onOpen = jest.fn()
+    render(<SessionCard session={base} onOpen={onOpen} />)
+    fireEvent.click(screen.getByTestId('session-card'))
+    expect(onOpen).toHaveBeenCalledWith('s1')
+  })
+
+  it('calls onOpenTerminal from the Terminal action without bubbling to the card', () => {
+    const onOpen = jest.fn()
+    const onOpenTerminal = jest.fn()
+    render(<SessionCard session={base} onOpen={onOpen} onOpenTerminal={onOpenTerminal} />)
+    fireEvent.click(screen.getByRole('button', { name: /terminal/i }))
+    expect(onOpenTerminal).toHaveBeenCalledWith('s1')
+    expect(onOpen).not.toHaveBeenCalled()
+  })
+
+  it('shows an unread dot when hasUnread', () => {
+    render(<SessionCard session={{ ...base, hasUnread: true }} />)
+    expect(screen.getByTestId('session-card-unread')).toBeInTheDocument()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// SessionList
+// ---------------------------------------------------------------------------
+
+const sessions: SessionSummary[] = [
+  base,
+  { id: 's2', name: 'Fix auth bug', isActive: false, status: 'success', projectName: 'auth-web', branch: 'fix/auth', createdAt: '2026-07-02T00:00:00.000Z' },
+  { id: 's3', name: 'Draft README', isActive: false, status: 'idle', projectName: 'raise-simpli', createdAt: '2026-07-03T00:00:00.000Z' },
+]
+
+describe('SessionList', () => {
+  it('renders a card grid by default', () => {
+    render(<SessionList sessions={sessions} />)
+    expect(screen.getAllByTestId('session-card')).toHaveLength(3)
+    expect(screen.getByText('Fix auth bug')).toBeInTheDocument()
+  })
+
+  it('renders a flat table layout', () => {
+    render(<SessionList sessions={sessions} layout="table" />)
+    expect(screen.getAllByTestId('session-row')).toHaveLength(3)
+  })
+
+  it('groups rows by project when groupByProject in table layout', () => {
+    render(<SessionList sessions={sessions} layout="table" groupByProject />)
+    // two project groups: raise-simpli (2) + auth-web (1)
+    expect(screen.getByText('raise-simpli')).toBeInTheDocument()
+    expect(screen.getByText('auth-web')).toBeInTheDocument()
+    expect(screen.getByText('2 sessions')).toBeInTheDocument()
+    expect(screen.getByText('1 session')).toBeInTheDocument()
+  })
+
+  it('collapses / expands a project group on header click', () => {
+    render(<SessionList sessions={sessions} layout="table" groupByProject />)
+    expect(screen.getAllByTestId('session-row')).toHaveLength(3)
+    // collapse the raise-simpli group (its header carries the "2 sessions" count)
+    fireEvent.click(screen.getByText('raise-simpli'))
+    expect(screen.getAllByTestId('session-row')).toHaveLength(1)
+  })
+
+  it('fires onSessionClick from a row', () => {
+    const onSessionClick = jest.fn()
+    render(<SessionList sessions={sessions} layout="table" onSessionClick={onSessionClick} />)
+    fireEvent.click(screen.getByText('Fix auth bug'))
+    expect(onSessionClick).toHaveBeenCalledWith(expect.objectContaining({ id: 's2' }))
+  })
+
+  it('renders loading skeletons', () => {
+    const { container } = render(<SessionList sessions={[]} isLoading skeletonCount={4} />)
+    expect(container.querySelectorAll('.animate-pulse').length).toBeGreaterThan(0)
+  })
+
+  it('renders an error state', () => {
+    render(<SessionList sessions={[]} error="nope" />)
+    expect(screen.getByTestId('session-list-error')).toHaveTextContent('nope')
+  })
+
+  it('renders an empty state with a custom label', () => {
+    render(<SessionList sessions={[]} emptyLabel="No runs yet" />)
+    expect(screen.getByTestId('session-list-empty')).toHaveTextContent('No runs yet')
+  })
+
+  it('renders injected filters above the list', () => {
+    render(<SessionList sessions={sessions} renderFilters={<div>my-filters</div>} />)
+    expect(screen.getByText('my-filters')).toBeInTheDocument()
+  })
+})

package/src/components/diff/DiffViewer.tsx

@@ -0,0 +1,235 @@
+'use client'
+
+import * as React from 'react'
+import { FileText, GitBranch, Loader2, RefreshCw } from 'lucide-react'
+import { cn } from '../../lib/utils'
+
+export interface DiffSummary {
+  totalFiles: number
+  staged?: number
+  unstaged?: number
+}
+
+export interface DiffViewerProps {
+  /** A raw unified diff (concatenated `git diff` output). */
+  diff: string
+  /** The ref/branch the diff is computed against (shown in the header). */
+  baseRef?: string
+  /** Optional counts summary rendered next to the base ref. */
+  summary?: DiffSummary
+  /** Raw `git status` text, shown in a collapsible "Working tree status" block. */
+  status?: string
+  isLoading?: boolean
+  error?: string | null
+  onRefresh?: () => void
+  /** Message shown when the diff is empty. Default "No changes yet". */
+  emptyLabel?: string
+  className?: string
+}
+
+export interface ParsedDiffFile {
+  filePath: string
+  /** All lines of the file's diff block, including headers. */
+  lines: string[]
+}
+
+/**
+ * Split a raw unified diff into per-file blocks. Ported from dev-hq's GitDiffViewer:
+ * split on `diff --git`, derive the file path from the `b/…` side of the header.
+ * Pure + exported so it can be unit-tested without rendering.
+ */
+export function parseDiffFiles(diff: string): ParsedDiffFile[] {
+  if (!diff || !diff.trim()) return []
+  return diff
+    .split(/(?=diff --git)/g)
+    .filter((block) => block.trim().length > 0)
+    .map((block) => {
+      const lines = block.split('\n')
+      const header = lines.find((l) => l.startsWith('diff --git'))
+      const filePath = header?.match(/ b\/(.+)$/)?.[1] ?? header?.match(/b\/(.+)$/)?.[1] ?? 'unknown'
+      return { filePath, lines }
+    })
+}
+
+/** Tailwind-token class for a single diff line based on its leading character. */
+export function diffLineClass(line: string): string {
+  if (line.startsWith('@@')) return 'text-cyan-600 dark:text-cyan-400 bg-cyan-500/10 font-semibold'
+  if (line.startsWith('+')) return 'text-emerald-600 dark:text-emerald-400 bg-emerald-500/10'
+  if (line.startsWith('-')) return 'text-red-600 dark:text-red-400 bg-red-500/10'
+  return 'text-muted-foreground'
+}
+
+/** Metadata lines that carry no visual value in the rendered diff. */
+function isMetadataLine(line: string): boolean {
+  return (
+    line.startsWith('diff --git') ||
+    line.startsWith('index ') ||
+    line.startsWith('--- ') ||
+    line.startsWith('+++ ') ||
+    line.startsWith('new file mode') ||
+    line.startsWith('deleted file mode') ||
+    line.startsWith('similarity index') ||
+    line.startsWith('rename from') ||
+    line.startsWith('rename to')
+  )
+}
+
+/**
+ * A presentational unified-diff viewer. It does NO fetching — pass `diff` plus
+ * loading/error flags and an `onRefresh` callback; the parent owns the data.
+ * Colourised with tailwind tokens (works in light + dark).
+ */
+export function DiffViewer({
+  diff,
+  baseRef,
+  summary,
+  status,
+  isLoading = false,
+  error = null,
+  onRefresh,
+  emptyLabel = 'No changes yet',
+  className,
+}: DiffViewerProps) {
+  const files = React.useMemo(() => parseDiffFiles(diff), [diff])
+
+  if (isLoading) {
+    return (
+      <div
+        data-testid="diff-viewer-loading"
+        className={cn('flex min-h-[300px] items-center justify-center bg-card', className)}
+      >
+        <div className="flex flex-col items-center gap-3 text-muted-foreground">
+          <Loader2 className="h-8 w-8 animate-spin" aria-hidden="true" />
+          <p className="text-sm">Loading diff…</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div
+        data-testid="diff-viewer-error"
+        className={cn('flex min-h-[300px] items-center justify-center bg-card', className)}
+      >
+        <div className="max-w-md text-center">
+          <h3 className="mb-2 text-base font-semibold text-foreground">Failed to load diff</h3>
+          <p className="mb-4 text-sm text-muted-foreground">{error}</p>
+          {onRefresh && (
+            <button
+              type="button"
+              onClick={onRefresh}
+              className="inline-flex items-center gap-2 rounded-lg border border-border px-4 py-2 text-sm text-foreground transition-colors hover:bg-accent"
+            >
+              <RefreshCw className="h-4 w-4" aria-hidden="true" />
+              Try again
+            </button>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  if (files.length === 0) {
+    return (
+      <div
+        data-testid="diff-viewer-empty"
+        className={cn('flex min-h-[300px] items-center justify-center bg-card', className)}
+      >
+        <div className="max-w-md text-center">
+          <FileText className="mx-auto mb-4 h-12 w-12 text-muted-foreground" aria-hidden="true" />
+          <h3 className="mb-2 text-base font-semibold text-foreground">{emptyLabel}</h3>
+          {baseRef && (
+            <p className="mb-4 text-sm text-muted-foreground">
+              No changes compared to{' '}
+              <code className="rounded bg-muted px-1.5 py-0.5 text-foreground">{baseRef}</code>
+            </p>
+          )}
+          {onRefresh && (
+            <button
+              type="button"
+              onClick={onRefresh}
+              className="inline-flex items-center gap-2 rounded-lg border border-border px-4 py-2 text-sm text-foreground transition-colors hover:bg-accent"
+            >
+              <RefreshCw className="h-4 w-4" aria-hidden="true" />
+              Refresh
+            </button>
+          )}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className={cn('flex h-full flex-col bg-card', className)}>
+      <div className="flex flex-shrink-0 items-center justify-between border-b border-border bg-muted/40 px-4 py-3">
+        <div className="flex flex-wrap items-center gap-4">
+          {baseRef && (
+            <div className="flex items-center gap-2 text-sm">
+              <GitBranch className="h-4 w-4 text-muted-foreground" aria-hidden="true" />
+              <span className="text-muted-foreground">Base:</span>
+              <code className="rounded bg-muted px-1.5 py-0.5 text-foreground">{baseRef}</code>
+            </div>
+          )}
+          {summary && (
+            <div className="text-sm text-muted-foreground" data-testid="diff-viewer-summary">
+              {summary.totalFiles} {summary.totalFiles === 1 ? 'file' : 'files'} changed
+              {summary.staged != null && summary.staged > 0 && (
+                <span className="ml-2 text-emerald-600 dark:text-emerald-400">({summary.staged} staged)</span>
+              )}
+              {summary.unstaged != null && summary.unstaged > 0 && (
+                <span className="ml-2 text-amber-600 dark:text-amber-400">({summary.unstaged} unstaged)</span>
+              )}
+            </div>
+          )}
+        </div>
+        {onRefresh && (
+          <button
+            type="button"
+            onClick={onRefresh}
+            title="Refresh diff"
+            aria-label="Refresh diff"
+            className="inline-flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+          >
+            <RefreshCw className="h-4 w-4" aria-hidden="true" />
+          </button>
+        )}
+      </div>
+
+      {status && (
+        <div className="flex-shrink-0 border-b border-border bg-muted/20 px-4 py-2">
+          <details className="cursor-pointer">
+            <summary className="select-none text-sm text-muted-foreground transition-colors hover:text-foreground">
+              Working tree status
+            </summary>
+            <pre className="mt-2 overflow-x-auto font-mono text-xs text-muted-foreground">{status}</pre>
+          </details>
+        </div>
+      )}
+
+      <div className="flex-1 space-y-4 overflow-auto p-4">
+        {files.map((file, fileIndex) => (
+          <div
+            key={`${file.filePath}-${fileIndex}`}
+            data-testid="diff-file"
+            className="overflow-hidden rounded-lg border border-border"
+          >
+            <div className="flex items-center gap-2 border-b border-border bg-muted/40 px-4 py-2">
+              <FileText className="h-4 w-4 text-muted-foreground" aria-hidden="true" />
+              <span className="font-mono text-sm text-foreground">{file.filePath}</span>
+            </div>
+            <pre className="overflow-x-auto p-4 font-mono text-sm">
+              {file.lines.map((line, index) =>
+                isMetadataLine(line) ? null : (
+                  <div key={index} className={diffLineClass(line)}>
+                    {line || ' '}
+                  </div>
+                ),
+              )}
+            </pre>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/components/diff/index.ts

@@ -0,0 +1,2 @@
+export { DiffViewer, parseDiffFiles, diffLineClass } from './DiffViewer'
+export type { DiffViewerProps, DiffSummary, ParsedDiffFile } from './DiffViewer'