@codexview/react 0.1.1

package/README.md

@@ -0,0 +1,56 @@
+# codexview
+
+React components for rendering OpenAI Codex CLI chat streams. Designed for agentweb but framework-agnostic for any host that produces compatible `ChatStreamEvent` sequences.
+
+## Install
+
+```bash
+pnpm add codexview lucide-react react react-dom
+```
+
+Import the stylesheet once in your app entrypoint:
+
+```ts
+import 'codexview/styles.css';
+```
+
+## 60-second quick start
+
+```tsx
+import { CodexTranscript, type ChatStreamEvent } from 'codexview';
+import 'codexview/styles.css';
+
+const events: ChatStreamEvent[] = [
+  { type: 'thread_started', threadId: 'T', at: Date.now() },
+  { type: 'turn_started', turnId: 'A', at: Date.now() },
+  { type: 'user_message', turnId: 'A', itemId: 'u1', text: 'Hello!', at: Date.now() },
+  { type: 'agent_message', turnId: 'A', itemId: 'a1', text: 'Hi.', partial: false, at: Date.now() },
+  { type: 'turn_completed', turnId: 'A', at: Date.now() },
+];
+
+export function App() {
+  return <CodexTranscript events={events} />;
+}
+```
+
+`events` is a plain array. Append new events as they arrive (typically via SSE) and pass the same array reference back; CodexView reduces incrementally.
+
+## Status
+
+Session-level status (`idle | working | completed | stopped | failed`) is inferred automatically. Override via the `status` prop (e.g. when SSE drops, set `status="stopped"`).
+
+## Customizing
+
+- Swap any block via `components` prop: `<CodexTranscript components={{ ToolCallBlock: MyToolUI }} />`
+- Theme via CSS variables — see [docs/styling.md](docs/styling.md) for the full list.
+
+## More docs
+
+- [docs/api.md](docs/api.md) — every public API
+- [docs/events.md](docs/events.md) — `ChatStreamEvent` contract
+- [docs/styling.md](docs/styling.md) — CSS variables
+- [docs/integration-agentweb.md](docs/integration-agentweb.md) — drop-in for agentweb
+
+## License
+
+MIT.

package/dist/components/CodexTranscript.d.ts

@@ -0,0 +1,41 @@
+import { ComponentType, ReactNode } from 'react';
+import { ChatStreamEvent } from '../types/events.js';
+import { TranscriptStatus } from '../types/model.js';
+import { MessageBubbleProps } from './MessageBubble.js';
+import { ReasoningBlockProps } from './ReasoningBlock.js';
+import { ToolCallBlockProps } from './ToolCallBlock.js';
+import { ExecBlockProps } from './ExecBlock.js';
+import { SearchBlockProps } from './SearchBlock.js';
+import { PatchBlockProps } from './PatchBlock.js';
+import { TodoListBlockProps } from './TodoListBlock.js';
+import { ErrorBlockProps } from './ErrorBlock.js';
+import { RawEventBlockProps } from './RawEventBlock.js';
+import { StatusBarProps } from './StatusBar.js';
+export interface CodexTranscriptComponents {
+    StatusBar: ComponentType<StatusBarProps>;
+    MessageBubble: ComponentType<MessageBubbleProps>;
+    ReasoningBlock: ComponentType<ReasoningBlockProps>;
+    ToolCallBlock: ComponentType<ToolCallBlockProps>;
+    ExecBlock: ComponentType<ExecBlockProps>;
+    SearchBlock: ComponentType<SearchBlockProps>;
+    PatchBlock: ComponentType<PatchBlockProps>;
+    TodoListBlock: ComponentType<TodoListBlockProps>;
+    ErrorBlock: ComponentType<ErrorBlockProps>;
+    RawEventBlock: ComponentType<RawEventBlockProps>;
+}
+export interface CodexTranscriptProps {
+    events: ChatStreamEvent[];
+    status?: TranscriptStatus;
+    error?: {
+        message: string;
+        details?: string;
+    };
+    className?: string;
+    maxItems?: number;
+    emptyState?: ReactNode;
+    onItemClick?: (itemId: string) => void;
+    components?: Partial<CodexTranscriptComponents>;
+    disableSmoothStream?: boolean;
+    onInternalError?: (err: unknown, event?: ChatStreamEvent) => void;
+}
+export declare function CodexTranscript(props: CodexTranscriptProps): JSX.Element;

package/dist/components/ErrorBlock.d.ts

@@ -0,0 +1,7 @@
+import { ItemView } from '../types/model.js';
+export interface ErrorBlockProps {
+    item: Extract<ItemView, {
+        kind: 'error';
+    }>;
+}
+export declare function ErrorBlock({ item }: ErrorBlockProps): JSX.Element;

package/dist/components/ExecBlock.d.ts

@@ -0,0 +1,9 @@
+import { ItemView } from '../types/model.js';
+export interface ExecBlockProps {
+    item: Extract<ItemView, {
+        kind: 'exec';
+    }>;
+    /** Open by default? Defaults to false (collapsed). */
+    defaultOpen?: boolean;
+}
+export declare function ExecBlock({ item, defaultOpen }: ExecBlockProps): JSX.Element;

package/dist/components/ItemErrorBoundary.d.ts

@@ -0,0 +1,16 @@
+import { Component, ErrorInfo, ReactNode } from 'react';
+export interface ItemErrorBoundaryProps {
+    fallback?: ReactNode;
+    onError?: (err: unknown, info: ErrorInfo) => void;
+    children: ReactNode;
+}
+interface State {
+    hasError: boolean;
+}
+export declare class ItemErrorBoundary extends Component<ItemErrorBoundaryProps, State> {
+    state: State;
+    static getDerivedStateFromError(): State;
+    componentDidCatch(err: unknown, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

package/dist/components/Markdown.d.ts

@@ -0,0 +1,20 @@
+export interface MarkdownProps {
+    /** Plain text or Markdown source. Treated as Markdown by default. */
+    children: string;
+    /** Skip parsing — render as plain pre-wrapped text. */
+    asPlain?: boolean;
+    className?: string;
+}
+/**
+ * Lightweight Markdown renderer wired with GFM (tables, strikethrough, task
+ * lists, autolinks). Code blocks render with monospace + dark background.
+ * Intentionally bare: no syntax highlighting (keeps the bundle small) and no
+ * raw HTML allowed (XSS-safe by default).
+ *
+ * Inline `::action{params}` directives (a Codex Web/IDE convention emitted by
+ * the model after successful side-effects) are extracted out of the Markdown
+ * stream and rendered as compact badges.
+ */
+declare function MarkdownInner({ children, asPlain, className }: MarkdownProps): JSX.Element;
+export declare const Markdown: import('react').MemoExoticComponent<typeof MarkdownInner>;
+export {};

package/dist/components/MessageBubble.d.ts

@@ -0,0 +1,10 @@
+import { ItemView } from '../types/model.js';
+export interface MessageBubbleProps {
+    item: Extract<ItemView, {
+        kind: 'user_message' | 'assistant_text';
+    }>;
+    smoothStream?: boolean;
+    /** When true (default), parse text as Markdown. */
+    markdown?: boolean;
+}
+export declare function MessageBubble({ item, smoothStream, markdown }: MessageBubbleProps): JSX.Element;

package/dist/components/PatchBlock.d.ts

@@ -0,0 +1,9 @@
+import { ItemView } from '../types/model.js';
+export interface PatchBlockProps {
+    item: Extract<ItemView, {
+        kind: 'patch';
+    }>;
+    /** Open by default? Defaults to false (collapsed). */
+    defaultOpen?: boolean;
+}
+export declare function PatchBlock({ item, defaultOpen }: PatchBlockProps): JSX.Element;

package/dist/components/RawEventBlock.d.ts

@@ -0,0 +1,7 @@
+import { ItemView } from '../types/model.js';
+export interface RawEventBlockProps {
+    item: Extract<ItemView, {
+        kind: 'raw';
+    }>;
+}
+export declare function RawEventBlock({ item }: RawEventBlockProps): JSX.Element;

package/dist/components/ReasoningBlock.d.ts

@@ -0,0 +1,11 @@
+import { ItemView } from '../types/model.js';
+export interface ReasoningBlockProps {
+    item: Extract<ItemView, {
+        kind: 'reasoning';
+    }>;
+    defaultOpen?: boolean;
+    smoothStream?: boolean;
+    /** Render body as Markdown. Defaults to true. */
+    markdown?: boolean;
+}
+export declare function ReasoningBlock({ item, defaultOpen, smoothStream, markdown }: ReasoningBlockProps): JSX.Element;

package/dist/components/SearchBlock.d.ts

@@ -0,0 +1,10 @@
+import { ItemView } from '../types/model.js';
+export interface SearchBlockProps {
+    item: Extract<ItemView, {
+        kind: 'search';
+    }>;
+    initialVisible?: number;
+    /** Open by default? Defaults to false (collapsed). */
+    defaultOpen?: boolean;
+}
+export declare function SearchBlock({ item, initialVisible, defaultOpen }: SearchBlockProps): JSX.Element;

package/dist/components/StatusBar.d.ts

@@ -0,0 +1,10 @@
+import { TranscriptStatus } from '../types/model.js';
+export interface StatusBarProps {
+    status: TranscriptStatus;
+    label?: string;
+    error?: {
+        message: string;
+        details?: string;
+    };
+}
+export declare function StatusBar({ status, label, error }: StatusBarProps): JSX.Element | null;

package/dist/components/TodoListBlock.d.ts

@@ -0,0 +1,9 @@
+import { ItemView } from '../types/model.js';
+export interface TodoListBlockProps {
+    item: Extract<ItemView, {
+        kind: 'todo_list';
+    }>;
+    /** Initial open/collapsed state. Defaults to collapsed. */
+    defaultOpen?: boolean;
+}
+export declare function TodoListBlock({ item, defaultOpen }: TodoListBlockProps): JSX.Element;

package/dist/components/ToolCallBlock.d.ts

@@ -0,0 +1,9 @@
+import { ItemView } from '../types/model.js';
+export interface ToolCallBlockProps {
+    item: Extract<ItemView, {
+        kind: 'tool_call';
+    }>;
+    /** Whether the block is open by default. Defaults to false (collapsed). */
+    defaultOpen?: boolean;
+}
+export declare function ToolCallBlock({ item, defaultOpen }: ToolCallBlockProps): JSX.Element;

package/dist/components/TurnContainer.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+import { TurnView } from '../types/model.js';
+export interface TurnContainerProps {
+    turn: TurnView;
+    children: ReactNode;
+}
+export declare function TurnContainer({ turn, children }: TurnContainerProps): JSX.Element;

package/dist/components/_shared.d.ts

@@ -0,0 +1,2 @@
+export declare function shouldCollapseValue(value: unknown): boolean;
+export declare function safeStringify(value: unknown): string;

package/dist/components/icons.d.ts

@@ -0,0 +1,16 @@
+export declare const ICONS: {
+    readonly tool: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly exec: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly patch: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly search: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly web: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly message: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly reasoning: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly ok: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly fail: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly stop: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly warn: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly expand: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+    readonly collapse: import('react').ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & import('react').RefAttributes<SVGSVGElement>>;
+};
+export type IconKey = keyof typeof ICONS;

package/dist/hooks/useCodexTranscript.d.ts

@@ -0,0 +1,10 @@
+import { ChatStreamEvent } from '../types/events.js';
+import { TranscriptModel, TranscriptStatus } from '../types/model.js';
+export interface UseCodexTranscriptOptions {
+    status?: TranscriptStatus;
+    onInternalError?: (err: unknown, event?: ChatStreamEvent) => void;
+}
+export declare function useCodexTranscript(events: ChatStreamEvent[], options?: UseCodexTranscriptOptions): {
+    model: TranscriptModel;
+    status: TranscriptStatus;
+};

package/dist/hooks/useSmoothStream.d.ts

@@ -0,0 +1,7 @@
+export interface UseSmoothStreamOptions {
+    enabled?: boolean;
+    /** When > 0, override automatic chars-per-frame calculation. */
+    charsPerFrame?: number;
+    minDelayMs?: number;
+}
+export declare function useSmoothStream(fullText: string, options?: UseSmoothStreamOptions): string;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export type { ChatStreamEvent, ChatStreamEventType, TokenUsage, SearchResult, PatchFile, TodoEntry } from './types/events.js';
+export type { TranscriptModel, TurnView, ItemView, ItemKind, ItemStatus, TranscriptStatus } from './types/model.js';
+export { EMPTY_MODEL } from './types/model.js';
+export { reduceTranscript } from './reducer/transcript.js';
+export { inferStatus } from './reducer/status.js';
+export { useCodexTranscript } from './hooks/useCodexTranscript.js';
+export type { UseCodexTranscriptOptions } from './hooks/useCodexTranscript.js';
+export { useSmoothStream } from './hooks/useSmoothStream.js';
+export type { UseSmoothStreamOptions } from './hooks/useSmoothStream.js';
+export { CodexTranscript } from './components/CodexTranscript.js';
+export type { CodexTranscriptProps, CodexTranscriptComponents } from './components/CodexTranscript.js';
+export { StatusBar } from './components/StatusBar.js';
+export type { StatusBarProps } from './components/StatusBar.js';
+export { TurnContainer } from './components/TurnContainer.js';
+export type { TurnContainerProps } from './components/TurnContainer.js';
+export { MessageBubble } from './components/MessageBubble.js';
+export type { MessageBubbleProps } from './components/MessageBubble.js';
+export { ReasoningBlock } from './components/ReasoningBlock.js';
+export type { ReasoningBlockProps } from './components/ReasoningBlock.js';
+export { ToolCallBlock } from './components/ToolCallBlock.js';
+export type { ToolCallBlockProps } from './components/ToolCallBlock.js';
+export { ExecBlock } from './components/ExecBlock.js';
+export type { ExecBlockProps } from './components/ExecBlock.js';
+export { SearchBlock } from './components/SearchBlock.js';
+export type { SearchBlockProps } from './components/SearchBlock.js';
+export { PatchBlock } from './components/PatchBlock.js';
+export type { PatchBlockProps } from './components/PatchBlock.js';
+export { TodoListBlock } from './components/TodoListBlock.js';
+export type { TodoListBlockProps } from './components/TodoListBlock.js';
+export { ErrorBlock } from './components/ErrorBlock.js';
+export type { ErrorBlockProps } from './components/ErrorBlock.js';
+export { RawEventBlock } from './components/RawEventBlock.js';
+export type { RawEventBlockProps } from './components/RawEventBlock.js';
+export { ItemErrorBoundary } from './components/ItemErrorBoundary.js';
+export type { ItemErrorBoundaryProps } from './components/ItemErrorBoundary.js';
+export { Markdown } from './components/Markdown.js';
+export type { MarkdownProps } from './components/Markdown.js';
+export declare const VERSION = "0.1.1";