@codexview/react 0.1.1

package/dist/types/model.d.ts

@@ -0,0 +1,75 @@
+import { PatchFile, SearchResult, TodoEntry, TokenUsage } from './events.js';
+/** Item-level lifecycle status (5 states per spec §5.1). */
+export type ItemStatus = 'pending' | 'running' | 'completed' | 'failed' | 'stopped';
+/** Discriminated kind of a rendered item. */
+export type ItemKind = 'user_message' | 'reasoning' | 'assistant_text' | 'tool_call' | 'exec' | 'search' | 'patch' | 'todo_list' | 'error' | 'raw';
+interface ItemViewBase {
+    id: string;
+    kind: ItemKind;
+    status: ItemStatus;
+    startedAt: number;
+    updatedAt: number;
+}
+export type ItemView = (ItemViewBase & {
+    kind: 'user_message';
+    text: string;
+}) | (ItemViewBase & {
+    kind: 'reasoning';
+    text: string;
+}) | (ItemViewBase & {
+    kind: 'assistant_text';
+    text: string;
+}) | (ItemViewBase & {
+    kind: 'tool_call';
+    name: string;
+    server?: string;
+    args: unknown;
+    result?: unknown;
+    error?: string;
+}) | (ItemViewBase & {
+    kind: 'exec';
+    command: string;
+    exit?: number;
+    stdout?: string;
+    stderr?: string;
+    durationMs?: number;
+}) | (ItemViewBase & {
+    kind: 'search';
+    query: string;
+    results?: SearchResult[];
+}) | (ItemViewBase & {
+    kind: 'patch';
+    files: PatchFile[];
+    ok?: boolean;
+}) | (ItemViewBase & {
+    kind: 'todo_list';
+    items: TodoEntry[];
+}) | (ItemViewBase & {
+    kind: 'error';
+    message: string;
+}) | (ItemViewBase & {
+    kind: 'raw';
+    payload: unknown;
+});
+export interface TurnView {
+    turnId: string;
+    startedAt: number;
+    completedAt?: number;
+    status: 'running' | 'completed' | 'failed' | 'aborted';
+    items: ItemView[];
+    usage?: TokenUsage;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export interface TranscriptModel {
+    threadId?: string;
+    turns: TurnView[];
+    lastEventAt: number;
+}
+/** Empty initial model. Always safe to start reducing from here. */
+export declare const EMPTY_MODEL: TranscriptModel;
+/** Session-level status (5 states per spec §5.3). */
+export type TranscriptStatus = 'idle' | 'working' | 'completed' | 'stopped' | 'failed';
+export {};

package/docs/api.md

@@ -0,0 +1,156 @@
+# API Reference
+
+All exports from `codexview`. Import via `import { ... } from 'codexview'`.
+
+## Components
+
+### `<CodexTranscript>`
+
+Top-level transcript renderer.
+
+```tsx
+<CodexTranscript
+  events={events}
+  status?={status}
+  error?={{ message, details? }}
+  className?={string}
+  maxItems?={number}
+  emptyState?={ReactNode}
+  onItemClick?={(id) => void}
+  components?={Partial<CodexTranscriptComponents>}
+  disableSmoothStream?={boolean}
+  onInternalError?={(err, event?) => void}
+/>
+```
+
+| Prop | Default | Notes |
+|------|---------|-------|
+| `events` | required | Append-only is most efficient; full replace also works. Reference equality skips re-reduce. |
+| `status` | inferred | When provided, fully replaces `inferStatus(model)`. |
+| `error` | undefined | Shown inside `StatusBar` when status is `failed` or `stopped`. |
+| `className` | undefined | Appended to `.codexview-root` class list. |
+| `maxItems` | unlimited | Trims oldest items, shows "已省略最早的 X 条" hint at the top. |
+| `emptyState` | `'暂无对话'` | Rendered when `events` is empty. |
+| `onItemClick` | undefined | Receives `item.id` of the clicked item. |
+| `components` | builtin | Replace any subcomponent (e.g. `{ ToolCallBlock: MyTool }`). |
+| `disableSmoothStream` | `false` | Disables the typewriter effect for `assistant_text` and `reasoning`. |
+| `onInternalError` | undefined | Called when reducer or item render throws; component falls back without crashing. |
+
+#### Minimal example
+
+```tsx
+const events = useAtomValue(streamingAtomFamily(sessionId));
+return <CodexTranscript events={events.list} />;
+```
+
+### `<StatusBar>`
+
+```tsx
+<StatusBar status={status} label?={string} error?={{ message, details? }} />
+```
+
+Returns `null` when `status === 'idle'`.
+
+### `<TurnContainer>`
+
+```tsx
+<TurnContainer turn={turn}>{children}</TurnContainer>
+```
+
+### `<MessageBubble>`
+
+```tsx
+<MessageBubble item={userOrAssistantItem} smoothStream?={boolean} />
+```
+
+### `<ReasoningBlock>`
+
+```tsx
+<ReasoningBlock item={reasoningItem} defaultOpen?={boolean} smoothStream?={boolean} />
+```
+
+### `<ToolCallBlock>`
+
+```tsx
+<ToolCallBlock item={toolCallItem} />
+```
+
+Renders args inline; result inline if small, collapsed in `<details>` if long (`>500` chars, `>4` lines, or `>3` JSON depth).
+
+### `<ExecBlock>`
+
+```tsx
+<ExecBlock item={execItem} />
+```
+
+Shimmer bar shown while `status === 'running'`. stdout/stderr collapsed beyond size threshold.
+
+### `<SearchBlock>`
+
+```tsx
+<SearchBlock item={searchItem} initialVisible?={number} />
+```
+
+Shows first 3 results by default; "展开剩余 N 条" reveals the rest.
+
+### `<PatchBlock>`
+
+```tsx
+<PatchBlock item={patchItem} />
+```
+
+Each file is collapsed; expanding shows diff with git-style coloring.
+
+### `<RawEventBlock>`
+
+```tsx
+<RawEventBlock item={rawItem} />
+```
+
+Used as fallback for unknown event types.
+
+### `<ItemErrorBoundary>`
+
+```tsx
+<ItemErrorBoundary fallback?={ReactNode} onError?={(err, info) => void}>
+  {children}
+</ItemErrorBoundary>
+```
+
+## Hooks
+
+### `useCodexTranscript(events, options?)`
+
+```ts
+const { model, status } = useCodexTranscript(events, { status?, onInternalError? });
+```
+
+Internally caches the last reduced model and uses prefix detection for incremental reduction.
+
+### `useSmoothStream(text, options?)`
+
+```ts
+const display = useSmoothStream(fullText, { enabled?, charsPerFrame?, minDelayMs? });
+```
+
+Returns the substring revealed so far. Resets when input shrinks. Returns full text immediately if `enabled === false` or `prefers-reduced-motion: reduce`.
+
+## Pure functions
+
+### `reduceTranscript(prev, event) => next`
+
+Pure reducer. Use directly to drive your own state container.
+
+### `inferStatus(model) => TranscriptStatus`
+
+Returns `'idle' | 'working' | 'completed' | 'stopped' | 'failed'`.
+
+### `EMPTY_MODEL`
+
+Frozen initial `TranscriptModel`. Always safe to start reducing from this.
+
+## Types
+
+`ChatStreamEvent`, `ChatStreamEventType`, `TokenUsage`, `SearchResult`, `PatchFile`, `TranscriptModel`, `TurnView`, `ItemView`, `ItemKind`, `ItemStatus`, `TranscriptStatus`, `CodexTranscriptComponents`, `UseCodexTranscriptOptions`, `UseSmoothStreamOptions`, plus per-component prop types (`StatusBarProps`, etc.).
+
+See [docs/events.md](events.md) for the full `ChatStreamEvent` shape.

package/docs/changelog.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.1] — 2026-05-15
+
+### Added
+
+- New item kinds aligned with the official [OpenAI Codex SDK](https://github.com/openai/codex/tree/main/sdk/typescript):
+  - `todo_list` — plan / TODO list with completion tracking; new `<TodoListBlock>` component
+  - `error` — non-fatal item-level error (distinct from `turn_failed`); new `<ErrorBlock>` component
+- `<Markdown>` component (powered by `react-markdown` + `remark-gfm`): tables, task lists, autolinks, inline code, fenced code blocks, blockquotes
+- Markdown rendering integrated into `MessageBubble`, `ReasoningBlock`, and `ToolCallBlock` (string-typed results auto-detected as Markdown)
+- New event types: `todo_list`, `error_item`
+- New exported types: `TodoEntry`, `MarkdownProps`, `TodoListBlockProps`, `ErrorBlockProps`
+
+### Changed
+
+- All tool-related blocks (`ToolCallBlock`, `ExecBlock`, `SearchBlock`, `PatchBlock`) are now collapsed by default. They auto-open while their status is `pending` or `running`. New `defaultOpen` prop available on each.
+- `MessageBubble` and `ReasoningBlock` accept a `markdown` prop (default `true`) to render text as Markdown. Streaming partial text falls back to plain text until completion to avoid janky partial-Markdown rendering.
+
+### Dependencies
+
+- Added: `react-markdown` `^10.1.0`, `remark-gfm` `^4.0.1`
+
+## [0.1.0] — 2026-05-15
+
+### Added
+
+- `<CodexTranscript>` main component (consumes `ChatStreamEvent[]`)
+- Subcomponents: `StatusBar`, `TurnContainer`, `MessageBubble`, `ReasoningBlock`, `ToolCallBlock`, `ExecBlock`, `SearchBlock`, `PatchBlock`, `RawEventBlock`, `ItemErrorBoundary`
+- Hooks: `useCodexTranscript`, `useSmoothStream`
+- Pure functions: `reduceTranscript`, `inferStatus`, `EMPTY_MODEL`
+- 8 supported event item kinds + raw fallback for unknown types
+- 5-state item status machine, 4-state turn status machine, 5-state session status
+- CSS Modules styling with overridable CSS variables
+- `lucide-react` icon system as peerDependency
+- `prefers-reduced-motion` honored by all animations
+- 6 fixtures + replay integration tests
+- Docs: API reference, event contract, styling, agentweb integration guide

package/docs/events.md

@@ -0,0 +1,65 @@
+# Event contract
+
+CodexView consumes a discriminated union `ChatStreamEvent`. The host (e.g. agentweb backend) is expected to emit events that match these shapes. Unknown event types are not errors — they fall through to `kind: 'raw'` and render via `RawEventBlock`.
+
+All events carry `at: number` (epoch ms).
+
+## Lifecycle
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `thread_started` | `threadId` | sets `model.threadId` |
+| `turn_started` | `turnId` | appends new `TurnView { status: 'running' }` |
+| `turn_completed` | `turnId`, optional `usage` | turn → `completed`; flips unfinished items → `completed` |
+| `turn_failed` | `turnId`, `error: { message, code? }` | turn → `failed`; flips unfinished items → `failed` |
+| `turn_aborted` | `turnId`, optional `reason` | turn → `aborted`; flips unfinished items → `stopped` |
+
+## Messages
+
+| Type | Required fields | ItemView produced |
+|------|-----------------|-------------------|
+| `user_message` | `turnId`, `itemId`, `text` | `kind: 'user_message'`, status `completed` |
+| `agent_message` | `turnId`, `itemId`, `text`, `partial` | `kind: 'assistant_text'`; same `itemId` updates in place; `partial: false` flips to `completed` |
+| `reasoning` | same as `agent_message` | `kind: 'reasoning'`; **never merged** with assistant_text |
+
+## Tool calls (paired by `callId`)
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `function_call` | `turnId`, `callId`, `name`, `args` | appends `tool_call`, status `pending` |
+| `function_call_output` | `turnId`, `callId`, optional `output` or `error` | finds matching `tool_call`, sets `result` or `error`, flips status |
+| `mcp_tool_call` | `turnId`, `callId`, `server`, `name`, `args` | same as `function_call` plus `server` |
+| `mcp_tool_call_output` | `turnId`, `callId`, optional `output` or `error` | same as `function_call_output` |
+
+## Shell exec
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `exec_command_begin` | `turnId`, `callId`, `command` | appends `exec`, status `running` |
+| `exec_command_end` | `turnId`, `callId`, `exit`, `stdout`, `stderr`, `durationMs` | finds matching `exec`, fills outputs, status `completed` if `exit === 0` else `failed` |
+
+## Web search
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `web_search_call` | `turnId`, `callId`, `query` | appends `search`, status `pending` |
+| `web_search_end` | `turnId`, `callId`, `results: SearchResult[]` | finds matching `search`, fills results, status `completed` |
+
+## Patch apply
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `patch_apply_end` | `turnId`, `callId`, `files: PatchFile[]`, `ok: boolean` | appends `patch`, status `completed` if `ok` else `failed` |
+
+## Fallback
+
+| Type | Required fields | Reducer effect |
+|------|-----------------|----------------|
+| `raw` | optional `turnId`, `payload: unknown` | if `turnId` present, appends `raw` ItemView; else only updates `lastEventAt` |
+
+## Invariants
+
+1. Reducer never throws on any input.
+2. Bulk `events.reduce(reduceTranscript, EMPTY_MODEL)` equals incremental reduce of the same series.
+3. Reducer is a pure function — no global state, no I/O.
+4. Unknown payload `type` is preserved verbatim in the produced `raw` ItemView.

package/docs/integration-agentweb.md

@@ -0,0 +1,112 @@
+# Integrating CodexView into agentweb
+
+This is a drop-in replacement for `frontend/src/codex/components/MessageBubble.tsx`, `StreamingBubble.tsx`, and `ToolUseBlock.tsx`. The agentweb backend (`backend/src/codex/eventMap.ts`) produces a normalized event stream that is conceptually equivalent to `ChatStreamEvent`, but uses different field names.
+
+## Adapter required
+
+The agentweb backend's `NormalizedEvent` and CodexView's `ChatStreamEvent` are conceptually equivalent but use different field names (e.g., agentweb uses `kind: 'text_delta'`, CodexView uses `type: 'agent_message'`). A small adapter function in agentweb (`frontend/src/codex/adapters/codexview.ts`) is needed to map between them. The Step 3 code example below is illustrative — replace `adapter(stream)` with the adapter-produced array and `stream.connected` with whatever connection-state field your `streamingAtomFamily` actually exposes.
+
+## Step 1 — install (development)
+
+From the agentweb repo root:
+
+```bash
+pnpm --filter frontend add file:../CodexView
+pnpm --filter frontend add lucide-react
+```
+
+(Once `codexview` is published to a registry, replace `file:../CodexView` with the version range.)
+
+## Step 2 — load styles + bridge tokens
+
+In `frontend/src/main.tsx` (or another global entry):
+
+```ts
+import 'codexview/styles.css';
+```
+
+In `frontend/src/codex/styles/tokens.css` (append):
+
+```css
+.aw-codex-transcript {
+  --cv-bg-user-bubble: var(--aw-bg-bubble-user);
+  --cv-bg-assistant-bubble: var(--aw-bg-bubble-bot);
+  --cv-text: var(--aw-text-primary);
+  --cv-axis-color: var(--aw-border-subtle);
+  --cv-bg-raised: var(--aw-bg-raised);
+}
+```
+
+(Match the variable list in `docs/styling.md` against agentweb's tokens.)
+
+## Step 3 — replace ChatThread internals
+
+`frontend/src/codex/components/ChatThread.tsx`:
+
+```tsx
+import { useAtomValue } from 'jotai';
+import { CodexTranscript } from 'codexview';
+import { streamingAtomFamily } from '../atoms/streaming';
+import { adaptStreamEvents } from '../adapters/codexview'; // adapter required — see "Adapter required" section above
+
+export function ChatThread({ sessionId }: { sessionId: string }) {
+  const stream = useAtomValue(streamingAtomFamily(sessionId));
+  return (
+    <CodexTranscript
+      events={adaptStreamEvents(stream)} // replace with adapter-produced ChatStreamEvent[]
+      status={stream.connected ? undefined : 'stopped'} // replace stream.connected with actual field name
+      className="aw-codex-transcript"
+    />
+  );
+}
+```
+
+The adapter maps agentweb's `NormalizedEvent` (with `kind` field) to CodexView's `ChatStreamEvent` (with `type` field). Adjust all property names to match the actual `streamingAtomFamily` shape.
+
+## Step 4 — clean up + handle approval
+
+Delete from `frontend/src/codex/components/`:
+
+- `MessageBubble.tsx`
+- `StreamingBubble.tsx`
+- `ToolUseBlock.tsx`
+
+**Keep** approval logic. CodexView v0.1 deliberately does **not** ship an approval-bubble component (see spec §11). If `StreamingBubble.tsx` carried that responsibility, extract the approval portion into a standalone `ApprovalBubble.tsx` component within agentweb and render it next to `<CodexTranscript>` (e.g. as a sibling overlay), feeding it the same approval events.
+
+## Verify
+
+```bash
+pnpm --filter frontend test
+pnpm --filter frontend dev
+```
+
+In the browser:
+
+1. Start a Codex session.
+2. Confirm streaming text appears with smooth typewriter effect.
+3. Trigger a tool call — confirm collapsible result.
+4. Trigger an exec — confirm shimmer while running.
+5. Disconnect the network — confirm StatusBar shows "已停止" once you set `status="stopped"`.
+
+## Rollback
+
+```bash
+git revert <integration-commit-sha>
+```
+
+Backend `ChatStreamEvent` shape and SSE endpoints do not change, so revert is purely frontend.
+
+## Type-safety guard
+
+Add to `frontend/src/codex/types/eventCheck.ts`:
+
+```ts
+import type { ChatStreamEvent as CV } from 'codexview';
+import type { ChatStreamEvent as AW } from '../../../../backend/src/codex/eventMap';
+
+// Will fail to compile if shapes drift.
+type _AssertEqual<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : never;
+type _Check = _AssertEqual<CV, AW>;
+```
+
+When the agentweb backend adds an event type, this assertion fails until codexview is updated.

package/docs/styling.md

@@ -0,0 +1,81 @@
+# Styling
+
+CodexView ships its own styles (`codexview/styles.css`) plus a `.codexview-root` reset to isolate from host CSS. All visual tokens are CSS variables you can override.
+
+## Loading
+
+```ts
+import 'codexview/styles.css';
+```
+
+## Variable reference
+
+Set these on `.codexview-root` (or any ancestor) to theme.
+
+### Layout
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `--cv-font-family` | system-ui stack | |
+| `--cv-font-mono` | ui-monospace stack | |
+| `--cv-font-size` | `14px` | base text size |
+| `--cv-line-height` | `1.55` | |
+| `--cv-radius` | `12px` | bubble radius |
+| `--cv-radius-sm` | `8px` | block radius |
+| `--cv-spacing-xs/-sm/-md/-lg` | 4/8/12/16 px | spacing scale |
+
+### Colors
+
+| Variable | Default (light) | Notes |
+|----------|-----------------|-------|
+| `--cv-text` | `#1f2328` | primary text |
+| `--cv-text-muted` | `#6e7781` | reasoning, captions |
+| `--cv-text-inverse` | `#ffffff` | text on user bubble |
+| `--cv-bg` | `#ffffff` | transcript background |
+| `--cv-bg-raised` | `#f6f8fa` | StatusBar, tool block surface |
+| `--cv-bg-user-bubble` | `#2f6feb` | user bubble |
+| `--cv-bg-assistant-bubble` | `#f6f8fa` | assistant bubble |
+| `--cv-bg-code` | `#0d1117` | exec / code background |
+| `--cv-fg-code` | `#e6edf3` | code foreground |
+| `--cv-border` | `#d0d7de` | dividers |
+| `--cv-axis-color` | `#d0d7de` | turn timeline axis |
+| `--cv-shimmer-color` | `rgba(31,35,40,0.08)` | exec shimmer |
+
+### Status colors
+
+| Variable | Default | Status |
+|----------|---------|--------|
+| `--cv-status-pending` | `#6e7781` | gray |
+| `--cv-status-running` | `#2f6feb` | blue |
+| `--cv-status-completed` | `#1a7f37` | green |
+| `--cv-status-failed` | `#cf222e` | red |
+| `--cv-status-stopped` | `#6e7781` | gray |
+
+### Diff colors
+
+| Variable | Default |
+|----------|---------|
+| `--cv-diff-add-bg` | `#ddf4e4` |
+| `--cv-diff-del-bg` | `#ffebe9` |
+
+## Dark theme example
+
+```css
+.dark .codexview-root {
+  --cv-text: #e6edf3;
+  --cv-text-muted: #8b949e;
+  --cv-bg: #0d1117;
+  --cv-bg-raised: #161b22;
+  --cv-bg-assistant-bubble: #161b22;
+  --cv-bg-user-bubble: #1f6feb;
+  --cv-border: #30363d;
+  --cv-axis-color: #30363d;
+  --cv-shimmer-color: rgba(255,255,255,0.05);
+  --cv-bg-code: #010409;
+  --cv-fg-code: #c9d1d9;
+}
+```
+
+## Reduced motion
+
+All animations (pulse, shimmer, blink caret, smooth stream) honor `prefers-reduced-motion: reduce` and degrade to static states automatically.