@codexview/react 0.3.0 → 0.3.1

package/docs/api.md

@@ -69,21 +69,39 @@ Returns `null` when `status === 'idle'`.
 <ReasoningBlock item={reasoningItem} defaultOpen?={boolean} smoothStream?={boolean} />
 ```
 
+### `<ToolGroup>` _(since 0.3.0)_
+
+```tsx
+<ToolGroup items={consecutiveToolItems} defaultOpen?={boolean}>
+  {/* pre-rendered children, one per item, in order */}
+</ToolGroup>
+```
+
+`<CodexTranscript>` wires this in automatically: each turn's items are partitioned via [`partitionForGrouping`](#partitionforgroupingitems--slice) and consecutive `tool_call` / `exec` / `search` / `patch` / `todo_list` / `raw` items are wrapped in one `<ToolGroup>`. Messages, reasoning, and errors act as break points (errors stay prominent).
+
+| Prop | Default | Notes |
+|------|---------|-------|
+| `items` | required | The grouped items, used to compute the summary title. |
+| `children` | required | Pre-rendered child blocks, one per `items[i]`, in order. |
+| `defaultOpen` | `false` | Group starts collapsed. Always opens while any contained item is `pending` / `running`, regardless of this prop. |
+
+Title is auto-generated from the item-kind counts, e.g. `更新待办、执行 9 个命令、调用 4 个工具`. Override by passing your own component via `<CodexTranscript components={{ ToolGroup: MyGroup }} />`.
+
 ### `<ToolCallBlock>`
 
 ```tsx
-<ToolCallBlock item={toolCallItem} />
+<ToolCallBlock item={toolCallItem} defaultOpen?={boolean} />
 ```
 
-Renders args inline; result inline if small, collapsed in `<details>` if long (`>500` chars, `>4` lines, or `>3` JSON depth).
+Renders args inline; result inline if small, collapsed in `<details>` if long (`>500` chars, `>4` lines, or `>3` JSON depth). Defaults to collapsed; auto-opens while `pending` / `running`. Header is single-line ellipsized when closed (since 0.2.3).
 
 ### `<ExecBlock>`
 
 ```tsx
-<ExecBlock item={execItem} />
+<ExecBlock item={execItem} defaultOpen?={boolean} />
 ```
 
-Shimmer bar shown while `status === 'running'`. stdout/stderr collapsed beyond size threshold.
+Shimmer bar shown while `status === 'running'`. stdout/stderr collapsed beyond size threshold. Closed header is single-line ellipsized — long absolute paths in `$ ...` commands no longer wrap; opening restores wrap (since 0.2.3).
 
 ### `<SearchBlock>`
 
@@ -145,12 +163,32 @@ Pure reducer. Use directly to drive your own state container.
 
 Returns `'idle' | 'working' | 'completed' | 'stopped' | 'failed'`.
 
+### `partitionForGrouping(items) => Slice[]` _(since 0.3.0)_
+
+Splits a flat `ItemView[]` into slices for `<ToolGroup>` rendering.
+
+```ts
+type Slice =
+  | { kind: 'single'; item: ItemView }       // render as before
+  | { kind: 'group';  items: ItemView[] };    // wrap children in <ToolGroup>
+```
+
+Consecutive groupable kinds (`tool_call`, `exec`, `search`, `patch`, `todo_list`, `raw`) collapse into one `group` slice; non-groupable kinds (`user_message`, `assistant_text`, `reasoning`, `error`) become `single` slices and act as break points.
+
+### `summarizeToolGroup(items) => string` _(since 0.3.0)_
+
+Returns the human-readable Chinese summary used as a `<ToolGroup>` title — e.g. `更新待办、执行 2 个命令、修改 1 个文件`. Each kind appears once with its count; order is fixed for stable phrasing.
+
+### `isGroupableKind(kind) => boolean` _(since 0.3.0)_
+
+Returns `true` for the six kinds that get aggregated into a `<ToolGroup>`.
+
 ### `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.).
+`ChatStreamEvent`, `ChatStreamEventType`, `TokenUsage`, `SearchResult`, `PatchFile`, `TranscriptModel`, `TurnView`, `ItemView`, `ItemKind`, `ItemStatus`, `TranscriptStatus`, `CodexTranscriptComponents`, `UseCodexTranscriptOptions`, `UseSmoothStreamOptions`, `ToolGroupProps`, `ToolGroupSlice`, plus per-component prop types (`StatusBarProps`, etc.).
 
 See [docs/events.md](events.md) for the full `ChatStreamEvent` shape.

package/docs/changelog.md

@@ -2,6 +2,51 @@
 
 All notable changes documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.3.1] — 2026-05-18
+
+### Documentation
+
+- `docs/styling.md` token defaults updated to match the new warm-paper light palette (`#faf6ef` / `#3a342c` / `#e8c5b3` / `#2c2620`).
+- `docs/api.md` adds the `<ToolGroup>` reference and the new public exports (`partitionForGrouping`, `summarizeToolGroup`, `isGroupableKind`, `ToolGroupProps`, `ToolGroupSlice`).
+- README highlights the turn-level tool aggregation behavior introduced in 0.3.0.
+
+### Notes
+
+- No code changes; doc-only release synchronized with the 0.3.0 binary.
+
+## [0.3.0] — 2026-05-18
+
+### Added
+
+- New `<ToolGroup>` component aggregates consecutive tool-like items inside a turn (`tool_call`, `exec`, `search`, `patch`, `todo_list`, `raw`) into a single collapsible block. Title is computed from the item-kind counts in Chinese (e.g. `更新待办、执行 9 个命令、调用 4 个工具`).
+- Items that act as natural break points — `user_message`, `assistant_text`, `reasoning`, `error` — remain rendered standalone. Errors stay prominent.
+- Each item inside a group keeps its own `<details>`, so a reader can drill into one call without expanding the whole turn. Groups auto-expand while any contained item is `pending` / `running`.
+- Exports: `ToolGroup`, `ToolGroupProps`, `ToolGroupSlice`, `partitionForGrouping`, `summarizeToolGroup`, `isGroupableKind`.
+- `ToolGroup` added to `CodexTranscriptComponents` — consumers can replace it.
+
+### Changed
+
+- `CodexTranscript` now partitions each turn's items via `partitionForGrouping()` before rendering. Single (non-tool) items render exactly as before; consecutive tool items render inside a `<ToolGroup>`.
+
+## [0.2.3] — 2026-05-18
+
+### Changed
+
+- Collapsed `<ExecBlock>` and `<ToolCallBlock>` header rows now constrain their command / title text to one line with `text-overflow: ellipsis`. Long absolute paths in shell commands and long mcp-style tool names no longer let "collapsed" rows wrap into two or three lines. Opening the block restores wrap so the full text is visible.
+
+## [0.2.2] — 2026-05-18
+
+### Changed
+
+- Softer user bubble: `--cv-bg-user-bubble` lightened from terracotta `#b8694a` to peach `#e8c5b3`, with `MessageBubble` switching user-bubble text to `--cv-text` (deep ink brown) for an "ink on warm paper" look. Contrast remains ≥ 7.5:1 (AAA).
+- Collapsed-state visuals for `<ToolCallBlock>`, `<ExecBlock>`, `<TodoListBlock>`, `<RawEventBlock>` are now transparent — only a status-colored left-border and title row are visible. Expanding restores the filled panel (border + raised background). Consecutive tool calls now read as a clean outline rather than stacked color blocks.
+
+## [0.2.1] — 2026-05-18
+
+### Changed
+
+- New default light palette ("warm paper"): ivory page background, deep ink-brown text, terracotta user-bubble accent, sage / vermillion status colors, warm-ink (not cold-black) code blocks. All defaults driven via existing `--cv-*` tokens — no component changes, no new token names. Consumers who relied on the exact previous defaults (`#ffffff` / `#1f2328` / `#2f6feb` / `#0d1117`) can pin them back with a `<style>` block.
+
 ## [0.2.0] — 2026-05-17
 
 ### Changed

package/docs/integration-agentweb.md

@@ -1,31 +1,51 @@
-# Integrating CodexView into agentweb
+# 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.
+This guide shows how to replace AgentWeb's hand-rolled chat transcript UI
+(`MessageBubble.tsx`, `StreamingBubble.tsx`, `ToolUseBlock.tsx`) with
+[`@codexview/react`](https://www.npmjs.com/package/@codexview/react)'s
+`<CodexTranscript>`. It targets `@codexview/react@0.2.x` and the current
+AgentWeb data model.
 
-## Adapter required
+## What you'll wire up
 
-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.
+CodexView consumes a `ChatStreamEvent[]` (one normalized event stream).
+AgentWeb stores chat history in two places:
 
-## Step 1 — install (development)
+- **persisted** — `ChatMessage[]` rows in your database, holding committed
+  user / assistant messages, tool calls, and token usage.
+- **live** — `streamingAtomFamily(sessionId)`, holding partial assistant
+  text, in-flight tool calls, stream errors, and disconnected / gave-up
+  flags.
 
-From the agentweb repo root:
+Neither source is `ChatStreamEvent[]` on its own. You need a bridge that
+merges them and synthesizes lifecycle events (`thread_started`,
+`turn_started`, `turn_completed`, `turn_failed`, `turn_aborted`).
+
+`@codexview/adapters` ships that bridge as `adaptAgentWebTranscript()` —
+described in [Step 3](#step-3--bridge-history--live-stream) below.
+
+## Step 1 — install
+
+From the AgentWeb repo root:
 
 ```bash
-pnpm --filter frontend add file:../CodexView
-pnpm --filter frontend add lucide-react
+pnpm --filter frontend add @codexview/react @codexview/adapters lucide-react
 ```
 
-(Once `codexview` is published to a registry, replace `file:../CodexView` with the version range.)
+`lucide-react` is a peer of `@codexview/react`. Both `@codexview/*`
+packages are ESM-only and require Node ≥ 20 for builds and tests.
 
 ## Step 2 — load styles + bridge tokens
 
 In `frontend/src/main.tsx` (or another global entry):
 
 ```ts
-import 'codexview/styles.css';
+import '@codexview/react/styles.css';
 ```
 
-In `frontend/src/codex/styles/tokens.css` (append):
+In `frontend/src/codex/styles/tokens.css` (append), map AgentWeb's design
+tokens onto CodexView's CSS variables so the transcript inherits the
+host theme:
 
 ```css
 .aw-codex-transcript {
@@ -37,43 +57,140 @@ In `frontend/src/codex/styles/tokens.css` (append):
 }
 ```
 
-(Match the variable list in `docs/styling.md` against agentweb's tokens.)
+The full variable list is in [`docs/styling.md`](./styling.md).
 
-## Step 3 — replace ChatThread internals
+## Step 3 — bridge history + live stream
 
-`frontend/src/codex/components/ChatThread.tsx`:
+Use `adaptAgentWebTranscript` to fold both sources into `ChatStreamEvent[]`
+plus a `TranscriptStatus`:
 
 ```tsx
+// frontend/src/codex/components/ChatThread.tsx
 import { useAtomValue } from 'jotai';
-import { CodexTranscript } from 'codexview';
+import { CodexTranscript } from '@codexview/react';
+import { adaptAgentWebTranscript } from '@codexview/adapters/agentweb-transcript';
+import { useChatMessages } from '../hooks/useChatMessages';
 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));
+  const messages = useChatMessages(sessionId);             // ChatMessage[]
+  const streaming = useAtomValue(streamingAtomFamily(sessionId));
+
+  const { events, status, error } = adaptAgentWebTranscript({
+    sessionId,
+    messages,
+    streaming,
+  });
+
   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"
-    />
+    <>
+      <CodexTranscript
+        events={events}
+        status={status}
+        className="aw-codex-transcript"
+      />
+      {error && <StreamErrorOverlay message={error.message} />}
+    </>
   );
 }
 ```
 
-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.
+### Input shape
+
+`adaptAgentWebTranscript` is dependency-free — it accepts structural
+input types so AgentWeb doesn't need to expose internal types upstream.
+Map your row / state shapes onto these fields:
+
+```ts
+interface AgentWebMessage {
+  id: string;
+  turnId: string;                    // groups user/assistant rows of one exchange
+  role: 'user' | 'assistant';
+  text?: string;
+  toolCalls?: AgentWebToolCall[];
+  usage?: { input?: number; cachedInput?: number; output?: number };
+  at?: number;                       // ms epoch
+}
 
-## Step 4 — clean up + handle approval
+interface AgentWebToolCall {
+  callId: string;
+  name: string;                      // `run_command` → exec_command_*
+  args?: unknown;                    // for run_command: { command: string }
+  output?: unknown;
+  error?: string;
+  completed?: boolean;               // false for in-flight live calls
+  // run_command extras
+  exit?: number;
+  stdout?: string;
+  stderr?: string;
+  durationMs?: number;
+}
 
-Delete from `frontend/src/codex/components/`:
+interface AgentWebStreamingState {
+  turnId?: string;
+  partialText?: string;
+  partialItemId?: string;            // stable React key for the live row
+  toolCalls?: AgentWebToolCall[];
+  status?: 'streaming' | 'completed' | 'failed' | 'disconnected' | 'gaveUp';
+  error?: string;
+  usage?: { input?: number; cachedInput?: number; output?: number };
+  at?: number;
+}
+```
+
+If your `streamingAtomFamily` exposes different field names (e.g.
+`connectionState` instead of `status`), normalize inline at the call
+site — the adapter is intentionally narrow.
+
+### What the adapter handles
+
+- emits `thread_started` for `sessionId` and synthesizes `turn_started`
+  / `turn_completed` boundaries around each `turnId` group;
+- preserves `turnId` across persisted user message → live partial
+  assistant text → final persisted assistant row, so all three render
+  in one turn;
+- maps `run_command` calls to `exec_command_begin` + `exec_command_end`,
+  everything else to `function_call` + `function_call_output`;
+- maps `{ input, cachedInput, output }` to CodexView's `TokenUsage`,
+  aggregating across multiple assistant rows in one turn;
+- converts stream lifecycle into events + status:
+  - `streaming` → no terminal event, `status: 'working'`
+  - `completed` → `turn_completed`, `status: 'completed'`
+  - `failed` → `turn_failed` + `status: 'failed'` + `error.message`
+  - `disconnected` / `gaveUp` → `turn_aborted` + `status: 'stopped'`
+- leaves in-flight tool calls (`completed: false`) open — only the
+  `_begin` half is emitted, so the call renders with a running
+  indicator until the next adapter call sees `completed: true`.
+
+## Step 4 — replace transcript rendering, keep host overlays
+
+CodexView v0.2 deliberately does **not** ship approval, reconnect, or
+gave-up bubbles — those stay AgentWeb-owned and render next to
+`<CodexTranscript>`, not inside it.
+
+Replace **transcript rendering** by removing the imports / renders of:
 
 - `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.
+…wherever they sit inside the chat transcript. Do **not** delete the
+files unconditionally — if `StreamingBubble.tsx` also rendered the
+approval prompt or "you've been disconnected" banner, extract that
+portion into a sibling component (e.g. `ApprovalOverlay.tsx`,
+`StreamErrorOverlay.tsx`) and render it next to `<CodexTranscript>`.
+
+The status returned by the adapter is the contract for those overlays:
 
-## Verify
+| `status`     | What to render                                                       |
+| ------------ | -------------------------------------------------------------------- |
+| `working`    | (nothing — `<CodexTranscript>` shows a running turn)                 |
+| `completed`  | (nothing)                                                            |
+| `stopped`    | "Disconnected" / "Gave up" banner with a retry / new-turn affordance |
+| `failed`     | Error overlay using `error.message`                                  |
+| `idle`       | (nothing — empty thread)                                             |
+
+## Step 5 — verify
 
 ```bash
 pnpm --filter frontend test
@@ -82,31 +199,66 @@ 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>
-```
+1. Start a Codex session — confirm the user message + streamed assistant
+   reply render under one `TurnContainer`.
+2. Confirm partial assistant text appears with a smooth typewriter
+   effect and re-flows when the final persisted row arrives (the
+   adapter dedupes by `itemId` if you pass a stable `partialItemId`).
+3. Trigger a tool call — confirm the collapsible result.
+4. Trigger a `run_command` — confirm the shimmer while running.
+5. Disconnect the network — confirm the `<StatusBar>` shows "已停止"
+   and your `StreamErrorOverlay` renders.
 
-Backend `ChatStreamEvent` shape and SSE endpoints do not change, so revert is purely frontend.
+## Step 6 — adapter contract test (optional but recommended)
 
-## Type-safety guard
-
-Add to `frontend/src/codex/types/eventCheck.ts`:
+Instead of the old compile-time `_AssertEqual` between AgentWeb and
+CodexView types, test the adapter directly. This catches drift in
+either repo without forcing the two type definitions to match
+character-for-character:
 
 ```ts
-import type { ChatStreamEvent as CV } from 'codexview';
-import type { ChatStreamEvent as AW } from '../../../../backend/src/codex/eventMap';
+// frontend/src/codex/adapters/codexview.test.ts
+import { describe, it, expect } from 'vitest';
+import { adaptAgentWebTranscript } from '@codexview/adapters/agentweb-transcript';
+
+describe('AgentWeb → CodexView adapter contract', () => {
+  it('renders a two-message turn into a single turn boundary', () => {
+    const { events, status } = adaptAgentWebTranscript({
+      sessionId: 's1',
+      messages: [
+        { id: 'u1', turnId: 't1', role: 'user', text: 'hi' },
+        { id: 'a1', turnId: 't1', role: 'assistant', text: 'hello' },
+      ],
+      now: 1_700_000_000_000,
+    });
+
+    expect(events.map((e) => e.type)).toEqual([
+      'thread_started',
+      'turn_started',
+      'user_message',
+      'agent_message',
+      'turn_completed',
+    ]);
+    expect(status).toBe('completed');
+  });
+
+  it('surfaces a disconnected stream as stopped + turn_aborted', () => {
+    const { events, status } = adaptAgentWebTranscript({
+      sessionId: 's1',
+      messages: [{ id: 'u1', turnId: 't1', role: 'user', text: 'hi' }],
+      streaming: { turnId: 't1', status: 'disconnected' },
+    });
+
+    expect(status).toBe('stopped');
+    expect(events.some((e) => e.type === 'turn_aborted')).toBe(true);
+  });
+});
+```
+
+## Rollback
 
-// 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>;
+```bash
+git revert <integration-commit-sha>
 ```
 
-When the agentweb backend adds an event type, this assertion fails until codexview is updated.
+Backend SSE endpoints don't change — revert is purely frontend.

package/docs/styling.md

@@ -26,37 +26,67 @@ Set these on `.codexview-root` (or any ancestor) to theme.
 
 ### Colors
 
+Defaults are the "warm paper" light palette (since 0.2.1): ivory page, deep ink-brown text, peach user-bubble accent, warm-ink code blocks. Override any of these to retheme.
+
 | 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 |
+| `--cv-text` | `#3a342c` | primary text (deep ink brown) |
+| `--cv-text-muted` | `#8a7e6b` | reasoning, captions (warm taupe) |
+| `--cv-text-inverse` | `#faf6ef` | text on dark surfaces |
+| `--cv-bg` | `#faf6ef` | transcript background (ivory) |
+| `--cv-bg-raised` | `#f1eadb` | StatusBar, expanded tool block surface |
+| `--cv-bg-user-bubble` | `#e8c5b3` | user bubble (peach; text uses `--cv-text`) |
+| `--cv-bg-assistant-bubble` | `#f1eadb` | assistant bubble |
+| `--cv-bg-code` | `#2c2620` | exec / code background (warm ink) |
+| `--cv-fg-code` | `#ede4d3` | code foreground (cream) |
+| `--cv-border` | `#d9ceb6` | dividers (warm hairline) |
+| `--cv-axis-color` | `#d9ceb6` | turn timeline axis |
+| `--cv-shimmer-color` | `rgba(58,52,44,0.08)` | exec shimmer (warm tint) |
 
 ### 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 |
+| `--cv-status-pending` | `#8a7e6b` | warm taupe |
+| `--cv-status-running` | `#5b7c99` | muted slate-blue |
+| `--cv-status-completed` | `#6b8e4e` | sage olive |
+| `--cv-status-failed` | `#b04a3a` | vermillion |
+| `--cv-status-stopped` | `#8a7e6b` | warm taupe |
 
 ### Diff colors
 
 | Variable | Default |
 |----------|---------|
-| `--cv-diff-add-bg` | `#ddf4e4` |
-| `--cv-diff-del-bg` | `#ffebe9` |
+| `--cv-diff-add-bg` | `#e6ecd5` (pale moss) |
+| `--cv-diff-del-bg` | `#f3dcd0` (pale rose) |
+
+## Restoring the pre-0.2.1 cool palette
+
+Drop these overrides if you preferred the original GitHub-style cool palette:
+
+```css
+.codexview-root {
+  --cv-text: #1f2328;
+  --cv-text-muted: #6e7781;
+  --cv-text-inverse: #ffffff;
+  --cv-bg: #ffffff;
+  --cv-bg-raised: #f6f8fa;
+  --cv-bg-user-bubble: #2f6feb;
+  --cv-bg-assistant-bubble: #f6f8fa;
+  --cv-bg-code: #0d1117;
+  --cv-fg-code: #e6edf3;
+  --cv-border: #d0d7de;
+  --cv-axis-color: #d0d7de;
+  --cv-shimmer-color: rgba(31,35,40,0.08);
+  --cv-status-running: #2f6feb;
+  --cv-status-completed: #1a7f37;
+  --cv-status-failed: #cf222e;
+  --cv-diff-add-bg: #ddf4e4;
+  --cv-diff-del-bg: #ffebe9;
+}
+```
+
+You'll also want to override `MessageBubble`'s user-bubble color back to `var(--cv-text-inverse)` via a component swap or a more targeted style, since 0.2.2 switched user-bubble text to `--cv-text`.
 
 ## Dark theme example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexview/react",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },