@easyops-cn/a2ui-react 0.0.0 → 0.0.1

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-A2UI React Renderer Library (`@easyops-cn/a2ui-react`) - A React implementation for rendering A2UI protocol. This is a library package (not an application) that downstream developers consume.
+A2UI React Renderer (`@easyops-cn/a2ui-react`) - A React implementation for rendering A2UI protocol. This is a library package (not an application) that downstream developers consume.
 
 ## Monorepo Structure
 
@@ -43,11 +43,15 @@ npm run build -w playground  # Build playground
 
 ## Library Usage (Downstream API)
 
-The primary entry point is `A2UIRender` component:
+The primary entry point is `A2UIRenderer` component:
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
-;<A2UIRender messages={messages} onAction={handleAction} />
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
+;<A2UIRenderer messages={messages} onAction={handleAction} />
 ```
 
 Custom components can override defaults or add new ones via `components` prop (Map<string, React.ComponentType>).
@@ -58,7 +62,7 @@ Custom components use hooks: `useDispatchAction`, `useDataBinding`, `useFormBind
 
 ```javascript
 import { v0_8 } from '@easyops-cn/a2ui-react'       // Main namespace export
-import { ... } from '@easyops-cn/a2ui-react/0.8'    // Core module (A2UIRender, hooks, types)
+import { ... } from '@easyops-cn/a2ui-react/0.8'    // Core module (A2UIRenderer, hooks, types)
 ```
 
 ## Architecture

package/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for your interest in contributing to `@easyops-cn/a2ui-react`!
 
 ## Project Overview
 
-A2UI React Renderer Library - A React implementation for rendering A2UI protocol. This is a library package that downstream developers consume.
+A2UI React Renderer - A React implementation for rendering A2UI protocol. This is a library package that downstream developers consume.
 
 ## Monorepo Structure
 

package/README.md

@@ -1,6 +1,4 @@
-# A2UI React Renderer Library
-
-https://easyops-cn.github.io/a2ui-react/
+# A2UI React Renderer
 
 A React renderer library for [A2UI](https://a2ui.org) protocol.
 
@@ -8,6 +6,8 @@ Supports all components in A2UI standard catalog out of the box. Built with [sha
 
 Currently A2UI protocol v0.8 is fully supported. Work on v0.9 is in progress.
 
+[Docs](https://easyops-cn.github.io/a2ui-react/) | [Playground](https://easyops-cn.github.io/a2ui-react/playground/)
+
 ## Installation
 
 ```sh
@@ -22,11 +22,11 @@ First, use the `@source` directive to tell Tailwind to scan the library code for
 @source "../node_modules/@easyops-cn/a2ui-react";
 ```
 
-Next, use the `A2UIRender` component to render A2UI messages:
+Next, use the `A2UIRenderer` component to render A2UI messages:
 
 ```tsx
 import {
-  A2UIRender,
+  A2UIRenderer,
   type A2UIMessage,
   type A2UIAction,
 } from '@easyops-cn/a2ui-react/0.8'
@@ -38,7 +38,7 @@ function App() {
     console.log('Action received:', action)
   }
 
-  return <A2UIRender messages={messages} onAction={handleAction} />
+  return <A2UIRenderer messages={messages} onAction={handleAction} />
 }
 ```
 
@@ -47,7 +47,11 @@ function App() {
 You can override default components or add new custom components via the `components` prop, which takes a `Map<string, React.ComponentType>`.
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
 
 const ComponentsMap = new Map<string, React.ComponentType<any>>([
   // Override default Button component with a custom one
@@ -59,7 +63,7 @@ const ComponentsMap = new Map<string, React.ComponentType<any>>([
 
 function App() {
   return (
-    <A2UIRender
+    <A2UIRenderer
       components={ComponentsMap}
       messages={messages}
       onAction={handleAction}

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@easyops-cn/a2ui-react",
-  "version": "0.0.0",
-  "description": "A2UI React Renderer Library",
+  "version": "0.0.1",
+  "description": "A2UI React Renderer",
+  "homepage": "https://easyops-cn.github.io/a2ui-react/",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:easyops-cn/a2ui-react.git"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/playground/src/components/Header.tsx

@@ -14,6 +14,7 @@ export function Header({ title, children }: HeaderProps) {
       <div className="header-right">
         <nav className="header-nav">
           <a href="/a2ui-react/">Docs</a>
+          <a href="/a2ui-react/api/">API Reference</a>
           <a href="/a2ui-react/playground/" className="active">
             Playground
           </a>

package/playground/src/components/Preview.tsx

@@ -1,6 +1,6 @@
 import { Component, type ReactNode } from 'react'
 import {
-  A2UIRender,
+  A2UIRenderer,
   type A2UIMessage,
   type A2UIAction,
 } from '@easyops-cn/a2ui-react/0.8'
@@ -72,7 +72,7 @@ export function Preview({ messages, error, onAction }: PreviewProps) {
 
   return (
     <ErrorBoundary>
-      <A2UIRender messages={messages} onAction={onAction} />
+      <A2UIRenderer messages={messages} onAction={onAction} />
     </ErrorBoundary>
   )
 }

package/specs/001-a2ui-renderer/checklists/requirements.md

@@ -34,7 +34,7 @@
 - All items pass validation
 - Specification is ready for `/speckit.clarify` or `/speckit.plan`
 - The spec covers all usage patterns shown in README.md:
-  - Basic rendering with A2UIRender component
+  - Basic rendering with A2UIRenderer component
   - Action handling via onAction callback
   - Custom component overrides via ComponentsMap
   - Custom component creation with hooks (useDispatchAction, useDataBinding, useFormBinding)

package/specs/001-a2ui-renderer/plan.md

@@ -5,9 +5,9 @@
 
 ## Summary
 
-Implement the A2UIRender component and public API exports for the A2UI React renderer library. The library already has substantial infrastructure implemented (contexts, hooks, component registry, default components). The remaining work focuses on:
+Implement the A2UIRenderer component and public API exports for the A2UI React renderer library. The library already has substantial infrastructure implemented (contexts, hooks, component registry, default components). The remaining work focuses on:
 
-1. Creating the main `A2UIRender` component that matches the README.md API
+1. Creating the main `A2UIRenderer` component that matches the README.md API
 2. Setting up the versioned export path (`@easyops-cn/a2ui-react/0.8`)
 3. Adding development-mode placeholder for unknown components
 4. Ensuring all public types and hooks are properly exported
@@ -65,7 +65,7 @@ The constitution template is not yet customized for this project. Proceeding wit
 
 | Component/Module          | Status     | Required For                                |
 | ------------------------- | ---------- | ------------------------------------------- |
-| **A2UIRender**            | ❌ Missing | Main entry component per README.md          |
+| **A2UIRenderer**          | ❌ Missing | Main entry component per README.md          |
 | **index.ts exports**      | ❌ Missing | Versioned path `@easyops-cn/a2ui-react/0.8` |
 | **Dev-mode placeholder**  | ❌ Missing | Unknown component handling per spec         |
 | **ComponentsMap support** | ❌ Missing | Custom component override per README.md     |
@@ -91,8 +91,8 @@ src/
 ├── index.ts                    # Root export (existing)
 └── 0.8/
     ├── index.ts                 # NEW: Versioned public API exports
-    ├── A2UIRender.tsx          # NEW: Main render component
-    ├── A2UIRender.test.tsx     # NEW: Tests for A2UIRender
+    ├── A2UIRenderer.tsx          # NEW: Main render component
+    ├── A2UIRenderer.test.tsx     # NEW: Tests for A2UIRenderer
     ├── contexts/               # Existing: Context providers
     │   ├── A2UIProvider.tsx
     │   ├── ActionContext.tsx

package/specs/001-a2ui-renderer/quickstart.md

@@ -14,7 +14,11 @@ pnpm add @easyops-cn/a2ui-react
 ## Basic Usage
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
 
 function App() {
   const messages: A2UIMessage[] = [
@@ -26,7 +30,7 @@ function App() {
     // Handle the action (e.g., send to server)
   }
 
-  return <A2UIRender messages={messages} onAction={handleAction} />
+  return <A2UIRenderer messages={messages} onAction={handleAction} />
 }
 ```
 
@@ -36,7 +40,7 @@ Override default components or add new ones:
 
 ```tsx
 import {
-  A2UIRender,
+  A2UIRenderer,
   useDispatchAction,
   ComponentRenderer,
 } from '@easyops-cn/a2ui-react/0.8'
@@ -63,7 +67,7 @@ const ComponentsMap = new Map([['Button', CustomButton]])
 
 function App() {
   return (
-    <A2UIRender
+    <A2UIRenderer
       components={ComponentsMap}
       messages={messages}
       onAction={handleAction}
@@ -99,7 +103,7 @@ function InputComponent({ surfaceId, value }) {
 
 ## API Reference
 
-### A2UIRender Props
+### A2UIRenderer Props
 
 | Prop         | Type                           | Required | Description                           |
 | ------------ | ------------------------------ | -------- | ------------------------------------- |
@@ -127,7 +131,7 @@ function InputComponent({ surfaceId, value }) {
 ## Message Flow
 
 ```
-Server                          Client (A2UIRender)
+Server                          Client (A2UIRenderer)
   │                                    │
   │──── beginRendering ───────────────►│ Initialize surface
   │                                    │

package/specs/001-a2ui-renderer/research.md

@@ -5,18 +5,18 @@
 
 ## Overview
 
-This document captures research findings for implementing the A2UIRender component and public API exports.
+This document captures research findings for implementing the A2UIRenderer component and public API exports.
 
-## Decision 1: A2UIRender Component Architecture
+## Decision 1: A2UIRenderer Component Architecture
 
-**Decision**: Compose A2UIRender as a thin wrapper around existing infrastructure
+**Decision**: Compose A2UIRenderer as a thin wrapper around existing infrastructure
 
 **Rationale**:
 
 - The existing `A2UIProvider` already combines all necessary context providers
 - The existing `useA2UIMessageHandler` hook handles message processing
 - The existing `ComponentRenderer` handles component routing
-- A2UIRender only needs to:
+- A2UIRenderer only needs to:
   1. Accept `messages`, `onAction`, and optional `components` props
   2. Wrap children in A2UIProvider
   3. Process messages and render surfaces
@@ -41,7 +41,7 @@ This document captures research findings for implementing the A2UIRender compone
 
 - Global registry mutation: Rejected - not React-friendly, causes side effects
 - Prop drilling: Rejected - would require changes to all container components
-- Module-level configuration: Rejected - not compatible with multiple A2UIRender instances
+- Module-level configuration: Rejected - not compatible with multiple A2UIRenderer instances
 
 ## Decision 3: Unknown Component Handling
 
@@ -85,7 +85,7 @@ This document captures research findings for implementing the A2UIRender compone
 - Messages can create multiple surfaces
 - Each surface has its own `root` component ID
 - SurfaceContext already maintains `Map<string, Surface>`
-- A2UIRender should render all active surfaces
+- A2UIRenderer should render all active surfaces
 
 **Alternatives considered**:
 
@@ -123,7 +123,7 @@ function useDispatchAction(): (
 
 - `A2UIMessage` - ✅ exists in types/index.ts
 - `A2UIAction` - ❌ needs alias (currently `ActionPayload`)
-- `A2UIRender` - ❌ needs implementation
+- `A2UIRenderer` - ❌ needs implementation
 - `ComponentRenderer` - ✅ exists
 - `useDispatchAction` - ✅ exists
 - `useDataBinding` - ✅ exists
@@ -134,7 +134,11 @@ function useDispatchAction(): (
 The README.md shows:
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
 ```
 
 Current types use `ActionPayload` instead of `A2UIAction`. The index.ts should export `ActionPayload as A2UIAction` for API consistency.

package/specs/001-a2ui-renderer/spec.md

@@ -16,17 +16,17 @@
 
 ### User Story 1 - Basic Message Rendering (Priority: P1)
 
-As a developer, I want to render A2UI messages using the A2UIRender component so that I can display dynamic UI content from A2UI protocol messages.
+As a developer, I want to render A2UI messages using the A2UIRenderer component so that I can display dynamic UI content from A2UI protocol messages.
 
 **Why this priority**: This is the core functionality - without basic rendering, no other features can work. It enables the fundamental use case of displaying A2UI messages.
 
-**Independent Test**: Can be fully tested by passing an array of A2UIMessage objects to A2UIRender and verifying the UI renders correctly. Delivers immediate value by enabling basic A2UI integration.
+**Independent Test**: Can be fully tested by passing an array of A2UIMessage objects to A2UIRenderer and verifying the UI renders correctly. Delivers immediate value by enabling basic A2UI integration.
 
 **Acceptance Scenarios**:
 
-1. **Given** an empty messages array, **When** A2UIRender is rendered, **Then** no UI components are displayed
-2. **Given** a messages array with valid A2UIMessage objects, **When** A2UIRender is rendered, **Then** all message components are displayed in order
-3. **Given** a messages array with nested components, **When** A2UIRender is rendered, **Then** nested components are rendered correctly within their parent containers
+1. **Given** an empty messages array, **When** A2UIRenderer is rendered, **Then** no UI components are displayed
+2. **Given** a messages array with valid A2UIMessage objects, **When** A2UIRenderer is rendered, **Then** all message components are displayed in order
+3. **Given** a messages array with nested components, **When** A2UIRenderer is rendered, **Then** nested components are rendered correctly within their parent containers
 
 ---
 
@@ -56,9 +56,9 @@ As a developer, I want to override default components with custom implementation
 
 **Acceptance Scenarios**:
 
-1. **Given** a ComponentsMap with a custom Button component, **When** A2UIRender renders a Button, **Then** the custom Button component is used instead of the default
-2. **Given** a ComponentsMap with multiple custom components, **When** A2UIRender renders those component types, **Then** each custom component is used appropriately
-3. **Given** a ComponentsMap that does not override a component type, **When** A2UIRender renders that component type, **Then** the default component is used
+1. **Given** a ComponentsMap with a custom Button component, **When** A2UIRenderer renders a Button, **Then** the custom Button component is used instead of the default
+2. **Given** a ComponentsMap with multiple custom components, **When** A2UIRenderer renders those component types, **Then** each custom component is used appropriately
+3. **Given** a ComponentsMap that does not override a component type, **When** A2UIRenderer renders that component type, **Then** the default component is used
 
 ---
 
@@ -72,7 +72,7 @@ As a developer, I want to add new custom component types that don't exist in the
 
 **Acceptance Scenarios**:
 
-1. **Given** a ComponentsMap with a new component type "Switch", **When** A2UIRender encounters a Switch component in messages, **Then** the custom Switch component is rendered
+1. **Given** a ComponentsMap with a new component type "Switch", **When** A2UIRenderer encounters a Switch component in messages, **Then** the custom Switch component is rendered
 2. **Given** a custom component using useDispatchAction hook, **When** the component dispatches an action, **Then** the action flows through the onAction callback correctly
 
 ---
@@ -120,12 +120,12 @@ As a developer, I want to use form binding hooks in custom components so that I
 
 ### Functional Requirements
 
-- **FR-001**: System MUST export A2UIRender component that accepts messages and onAction props
+- **FR-001**: System MUST export A2UIRenderer component that accepts messages and onAction props
 - **FR-002**: System MUST export A2UIMessage type for defining message structures
 - **FR-003**: System MUST export A2UIAction type for defining action payloads
-- **FR-004**: A2UIRender MUST render all components defined in the messages array
-- **FR-005**: A2UIRender MUST invoke onAction callback when user interactions trigger actions
-- **FR-006**: A2UIRender MUST accept an optional components prop (ComponentsMap) for custom component overrides
+- **FR-004**: A2UIRenderer MUST render all components defined in the messages array
+- **FR-005**: A2UIRenderer MUST invoke onAction callback when user interactions trigger actions
+- **FR-006**: A2UIRenderer MUST accept an optional components prop (ComponentsMap) for custom component overrides
 - **FR-007**: System MUST export useDispatchAction hook for custom components to dispatch actions
 - **FR-008**: System MUST export ComponentRenderer component for rendering child components within custom components
 - **FR-009**: System MUST export useDataBinding hook for reading data from the A2UI context

package/specs/001-a2ui-renderer/tasks.md

@@ -16,7 +16,7 @@
 ## Path Conventions
 
 - **Single library project**: `src/0.8/` at repository root
-- Tests co-located with source files (e.g., `A2UIRender.test.tsx`)
+- Tests co-located with source files (e.g., `A2UIRenderer.test.tsx`)
 
 ---
 
@@ -46,30 +46,30 @@
 - [x] T011 Add dev-mode placeholder component for unknown types in src/0.8/components/UnknownComponent.tsx
 - [x] T012 Update ComponentRenderer to render UnknownComponent in dev mode, skip in production
 
-**Checkpoint**: Foundation ready - A2UIRender component can now be implemented
+**Checkpoint**: Foundation ready - A2UIRenderer component can now be implemented
 
 ---
 
 ## Phase 3: User Story 1 - Basic Message Rendering (Priority: P1) 🎯 MVP
 
-**Goal**: Render A2UI messages using the A2UIRender component
+**Goal**: Render A2UI messages using the A2UIRenderer component
 
-**Independent Test**: Pass an array of A2UIMessage objects to A2UIRender and verify the UI renders correctly
+**Independent Test**: Pass an array of A2UIMessage objects to A2UIRenderer and verify the UI renders correctly
 
 ### Tests for User Story 1
 
-- [x] T013 [P] [US1] Create test file src/0.8/A2UIRender.test.tsx with test setup
+- [x] T013 [P] [US1] Create test file src/0.8/A2UIRenderer.test.tsx with test setup
 - [x] T014 [P] [US1] Add test: renders nothing for empty messages array
 - [x] T015 [P] [US1] Add test: renders components from valid A2UIMessage objects
 - [x] T016 [P] [US1] Add test: renders nested components correctly
 
 ### Implementation for User Story 1
 
-- [x] T017 [US1] Create A2UIRender component in src/0.8/A2UIRender.tsx
+- [x] T017 [US1] Create A2UIRenderer component in src/0.8/A2UIRenderer.tsx
 - [x] T018 [US1] Implement messages prop handling with useA2UIMessageHandler
 - [x] T019 [US1] Implement surface rendering loop (render all surfaces from context)
 - [x] T020 [US1] Add null/undefined messages handling (graceful empty render)
-- [x] T021 [US1] Export A2UIRender from src/0.8/index.ts
+- [x] T021 [US1] Export A2UIRenderer from src/0.8/index.ts
 
 **Checkpoint**: User Story 1 complete - basic rendering works independently
 
@@ -89,8 +89,8 @@
 
 ### Implementation for User Story 2
 
-- [x] T025 [US2] Add onAction prop to A2UIRender component in src/0.8/A2UIRender.tsx
-- [x] T026 [US2] Pass onAction to A2UIProvider in A2UIRender
+- [x] T025 [US2] Add onAction prop to A2UIRenderer component in src/0.8/A2UIRenderer.tsx
+- [x] T026 [US2] Pass onAction to A2UIProvider in A2UIRenderer
 - [x] T027 [US2] Add test: no error when action dispatched without onAction callback
 
 **Checkpoint**: User Stories 1 AND 2 complete - rendering and actions work
@@ -111,7 +111,7 @@
 
 ### Implementation for User Story 3
 
-- [x] T031 [US3] Add components prop (ComponentsMap) to A2UIRender in src/0.8/A2UIRender.tsx
+- [x] T031 [US3] Add components prop (ComponentsMap) to A2UIRenderer in src/0.8/A2UIRenderer.tsx
 - [x] T032 [US3] Wrap rendering with ComponentsMapProvider passing custom components
 - [x] T033 [US3] Merge custom components with defaults in ComponentsMapContext
 
@@ -199,7 +199,7 @@
 - **Setup (Phase 1)**: No dependencies - can start immediately
 - **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS user stories 3-4
 - **User Story 1 (Phase 3)**: Depends on Setup (Phase 1) only
-- **User Story 2 (Phase 4)**: Depends on User Story 1 (needs A2UIRender component)
+- **User Story 2 (Phase 4)**: Depends on User Story 1 (needs A2UIRenderer component)
 - **User Story 3 (Phase 5)**: Depends on Foundational (Phase 2) for ComponentsMapContext
 - **User Story 4 (Phase 6)**: Depends on User Story 3 (extends ComponentsMap support)
 - **User Story 5 (Phase 7)**: Depends on Setup (Phase 1) - hooks already exist

package/specs/002-playground/contracts/components.md

@@ -115,6 +115,6 @@ type ThemeToggleHandler = () => void
 ### Action Dispatch Event
 
 ```typescript
-// Triggered when A2UIRender dispatches an action
+// Triggered when A2UIRenderer dispatches an action
 type ActionHandler = (action: A2UIAction) => void
 ```

package/specs/002-playground/data-model.md

@@ -72,7 +72,7 @@ JSON.parse() attempted
 │ parsedMessages = result             │ parsedMessages = null
 │ parseError = null                   │ parseError = error.message
 │   ↓                                 │   ↓
-│ A2UIRender receives messages        │ ErrorDisplay shown
+│ A2UIRenderer receives messages        │ ErrorDisplay shown
 └─────────────────────────────────────┘
 ```
 
@@ -124,7 +124,7 @@ UI re-renders with new theme
                    │ renders
                    ▼
             ┌─────────────┐
-            │  A2UIRender │
+            │  A2UIRenderer │
             └─────────────┘
 ```
 

package/specs/002-playground/plan.md

@@ -49,7 +49,7 @@ playground/
 │   │   ├── Header.tsx           # Header with title and theme toggle
 │   │   ├── ThemeToggle.tsx      # Sun/moon theme switch component
 │   │   ├── JsonEditor.tsx       # CodeMirror-based JSON editor
-│   │   ├── Preview.tsx          # A2UIRender wrapper with error boundary
+│   │   ├── Preview.tsx          # A2UIRenderer wrapper with error boundary
 │   │   ├── ExampleSelector.tsx  # Dropdown for example selection
 │   │   └── ErrorDisplay.tsx     # Error state display component
 │   ├── data/

package/specs/002-playground/quickstart.md

@@ -44,7 +44,7 @@ playground/src/
 │   ├── Header.tsx       # App header with title and theme toggle
 │   ├── ThemeToggle.tsx  # Sun/moon theme switch
 │   ├── JsonEditor.tsx   # CodeMirror JSON editor
-│   ├── Preview.tsx      # A2UIRender wrapper
+│   ├── Preview.tsx      # A2UIRenderer wrapper
 │   ├── ExampleSelector.tsx  # Example dropdown
 │   └── ErrorDisplay.tsx # Error state component
 ├── data/
@@ -87,14 +87,14 @@ import { json } from '@codemirror/lang-json'
 />
 ```
 
-### A2UIRender Integration
+### A2UIRenderer Integration
 
 ```typescript
-import { A2UIRender, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
+import { A2UIRenderer, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
 
 // Parse JSON and render
 const messages: A2UIMessage[] = JSON.parse(jsonContent)
-<A2UIRender messages={messages} onAction={handleAction} />
+<A2UIRenderer messages={messages} onAction={handleAction} />
 ```
 
 ### Error Boundary Pattern

package/specs/002-playground/research.md

@@ -69,10 +69,10 @@ Import from workspace dependency `@easyops-cn/a2ui-react/0.8`
 ### Integration Pattern
 
 ```typescript
-import { A2UIRender, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
+import { A2UIRenderer, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
 
 // Parse JSON string to A2UIMessage[]
-// Pass to A2UIRender component
+// Pass to A2UIRenderer component
 // Handle parse errors gracefully
 ```
 
@@ -111,7 +111,7 @@ Use React Error Boundary for preview panel with graceful fallback
 ### Implementation Pattern
 
 ```typescript
-// ErrorBoundary wraps A2UIRender
+// ErrorBoundary wraps A2UIRenderer
 // Catches render errors, displays ErrorDisplay component
 // JSON parse errors handled separately before render
 ```

package/specs/002-playground/tasks.md

@@ -66,7 +66,7 @@ playground/
 ### Implementation for User Story 1
 
 - [x] T011 [P] [US1] Create JsonEditor component with CodeMirror integration in playground/src/components/JsonEditor.tsx
-- [x] T012 [P] [US1] Create Preview component wrapping A2UIRender with error boundary in playground/src/components/Preview.tsx
+- [x] T012 [P] [US1] Create Preview component wrapping A2UIRenderer with error boundary in playground/src/components/Preview.tsx
 - [x] T013 [US1] Create split-panel layout in playground/src/App.tsx with editor (left) and preview (right)
 - [x] T014 [US1] Add layout styles for split-panel (50/50) in playground/src/App.css
 - [x] T015 [US1] Implement JSON parsing with error handling in App.tsx (parse on change, update preview or show error)

package/src/0.8/{A2UIRender.test.tsx → A2UIRenderer.test.tsx}

@@ -1,13 +1,13 @@
 /**
- * A2UIRender Tests
+ * A2UIRenderer Tests
  *
- * Tests for the main A2UIRender component.
+ * Tests for the main A2UIRenderer component.
  */
 
 import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { A2UIRender, type ComponentsMap } from './A2UIRender'
+import { A2UIRenderer, type ComponentsMap } from './A2UIRenderer'
 import type { A2UIMessage, BaseComponentProps, Action } from './types'
 import { useDispatchAction } from './hooks/useDispatchAction'
 import { useDataBinding, useFormBinding } from './hooks/useDataBinding'
@@ -79,20 +79,20 @@ function createTestMessages(options: {
   return messages
 }
 
-describe('A2UIRender', () => {
+describe('A2UIRenderer', () => {
   describe('Phase 3: User Story 1 - Basic Message Rendering', () => {
     it('T014: renders nothing for empty messages array', () => {
-      const { container } = render(<A2UIRender messages={[]} />)
+      const { container } = render(<A2UIRenderer messages={[]} />)
       expect(container.firstChild).toBeNull()
     })
 
     it('T014b: renders nothing for null/undefined messages', () => {
       // @ts-expect-error - testing null handling
-      const { container: c1 } = render(<A2UIRender messages={null} />)
+      const { container: c1 } = render(<A2UIRenderer messages={null} />)
       expect(c1.firstChild).toBeNull()
 
       // @ts-expect-error - testing undefined handling
-      const { container: c2 } = render(<A2UIRender messages={undefined} />)
+      const { container: c2 } = render(<A2UIRenderer messages={undefined} />)
       expect(c2.firstChild).toBeNull()
     })
 
@@ -109,7 +109,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} />)
+      render(<A2UIRenderer messages={messages} />)
 
       expect(screen.getByText('Hello World')).toBeInTheDocument()
     })
@@ -137,7 +137,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} />)
+      render(<A2UIRenderer messages={messages} />)
 
       expect(screen.getByText('First')).toBeInTheDocument()
       expect(screen.getByText('Second')).toBeInTheDocument()
@@ -173,7 +173,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} />)
+      render(<A2UIRenderer messages={messages} />)
 
       expect(screen.getByText('Surface 1')).toBeInTheDocument()
       expect(screen.getByText('Surface 2')).toBeInTheDocument()
@@ -205,7 +205,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} onAction={onAction} />)
+      render(<A2UIRenderer messages={messages} onAction={onAction} />)
 
       const button = screen.getByRole('button')
       await user.click(button)
@@ -242,7 +242,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} onAction={onAction} />)
+      render(<A2UIRenderer messages={messages} onAction={onAction} />)
 
       const button = screen.getByRole('button')
       await user.click(button)
@@ -299,7 +299,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} onAction={onAction} />)
+      render(<A2UIRenderer messages={messages} onAction={onAction} />)
 
       const buttons = screen.getAllByRole('button')
       await user.click(buttons[0])
@@ -347,7 +347,7 @@ describe('A2UIRender', () => {
       })
 
       // No onAction prop
-      render(<A2UIRender messages={messages} />)
+      render(<A2UIRenderer messages={messages} />)
 
       const button = screen.getByRole('button')
 
@@ -395,7 +395,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-button')).toBeInTheDocument()
       expect(screen.getByText('Hello')).toBeInTheDocument()
@@ -437,7 +437,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-button')).toBeInTheDocument()
       expect(screen.getByTestId('custom-text')).toBeInTheDocument()
@@ -471,7 +471,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       // Custom button
       expect(screen.getByTestId('custom-button')).toBeInTheDocument()
@@ -509,7 +509,7 @@ describe('A2UIRender', () => {
         ],
       })
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-switch')).toBeInTheDocument()
       expect(screen.getByText('Enable feature')).toBeInTheDocument()
@@ -557,7 +557,7 @@ describe('A2UIRender', () => {
       })
 
       render(
-        <A2UIRender
+        <A2UIRenderer
           messages={messages}
           onAction={onAction}
           components={customComponents}
@@ -615,7 +615,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-display')).toHaveTextContent(
         'Hello from data model'
@@ -656,7 +656,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-display')).toHaveTextContent(
         'fallback value'
@@ -700,7 +700,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-input')).toHaveValue('john_doe')
     })
@@ -745,7 +745,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       const input = screen.getByTestId('custom-input')
       await user.type(input, 'new_value')
@@ -785,7 +785,7 @@ describe('A2UIRender', () => {
         },
       ]
 
-      render(<A2UIRender messages={messages} components={customComponents} />)
+      render(<A2UIRenderer messages={messages} components={customComponents} />)
 
       expect(screen.getByTestId('custom-input')).toHaveValue('default_value')
     })

package/src/0.8/{A2UIRender.tsx → A2UIRenderer.tsx}

@@ -1,19 +1,19 @@
 /**
- * A2UIRender - Main entry component for rendering A2UI messages.
+ * A2UIRenderer - Main entry component for rendering A2UI messages.
  *
  * This component processes A2UI messages and renders the resulting UI.
  * It supports custom component overrides via the components prop.
  *
  * @example
  * ```tsx
- * import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+ * import { A2UIRenderer, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
  *
  * function App() {
  *   const messages: A2UIMessage[] = [...]
  *   const handleAction = (action: A2UIAction) => {
  *     console.log('Action:', action)
  *   }
- *   return <A2UIRender messages={messages} onAction={handleAction} />
+ *   return <A2UIRenderer messages={messages} onAction={handleAction} />
  * }
  * ```
  */
@@ -38,7 +38,7 @@ export type ComponentsMap = Map<
 >
 
 /**
- * Props for A2UIRender component.
+ * Props for A2UIRenderer component.
  */
 export interface A2UIRenderProps {
   /** Array of A2UI messages to render */
@@ -105,21 +105,21 @@ function A2UIRenderInner({ messages }: { messages: A2UIMessage[] }) {
  * @example
  * ```tsx
  * // Basic usage
- * <A2UIRender messages={messages} onAction={handleAction} />
+ * <A2UIRenderer messages={messages} onAction={handleAction} />
  *
  * // With custom components
  * const customComponents = new Map([
  *   ['Button', CustomButton],
  *   ['Switch', CustomSwitch],
  * ])
- * <A2UIRender
+ * <A2UIRenderer
  *   messages={messages}
  *   onAction={handleAction}
  *   components={customComponents}
  * />
  * ```
  */
-export function A2UIRender({
+export function A2UIRenderer({
   messages,
   onAction,
   components,
@@ -139,4 +139,4 @@ export function A2UIRender({
   )
 }
 
-A2UIRender.displayName = 'A2UI.Render'
+A2UIRenderer.displayName = 'A2UI.Render'

package/src/0.8/index.ts

@@ -6,14 +6,14 @@
  *
  * @example
  * ```tsx
- * import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+ * import { A2UIRenderer, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
  *
  * function App() {
  *   const messages: A2UIMessage[] = [...]
  *   const handleAction = (action: A2UIAction) => {
  *     console.log('Action:', action)
  *   }
- *   return <A2UIRender messages={messages} onAction={handleAction} />
+ *   return <A2UIRenderer messages={messages} onAction={handleAction} />
  * }
  * ```
  */
@@ -29,7 +29,7 @@ export type {
 
 // ============ Components ============
 
-export { A2UIRender } from './A2UIRender'
+export { A2UIRenderer } from './A2UIRenderer'
 export { ComponentRenderer } from './components/ComponentRenderer'
 
 // ============ Hooks ============

package/website/content/api.md

@@ -0,0 +1,108 @@
+# API Reference
+
+## Core
+
+```typescript
+/**
+ * Main entry component for rendering A2UI messages.
+ * @param messages - Array of A2UI messages to render
+ * @param onAction - Callback when an action is dispatched
+ * @param components - Custom component overrides
+ */
+function A2UIRenderer(props: {
+  messages: A2UIMessage[]
+  onAction?: (action: A2UIAction) => void
+  components?: Map<string, React.ComponentType<any>>
+}): React.ReactElement
+
+/**
+ * A2UI message from server to client.
+ * Only one of the fields should be set per message.
+ */
+interface A2UIMessage {
+  beginRendering?: BeginRenderingPayload
+  surfaceUpdate?: SurfaceUpdatePayload
+  dataModelUpdate?: DataModelUpdatePayload
+  deleteSurface?: DeleteSurfacePayload
+}
+
+/**
+ * Resolved action payload sent to the action handler.
+ */
+interface A2UIAction {
+  surfaceId: string
+  name: string
+  context: Record<string, unknown>
+  sourceComponentId: string
+}
+```
+
+## Hooks
+
+```typescript
+/**
+ * Returns a function to dispatch actions from custom components.
+ */
+function useDispatchAction(): (
+  surfaceId: string,
+  componentId: string,
+  action: Action
+) => void
+
+/**
+ * Resolves a ValueSource to its actual value.
+ * @param surfaceId - The surface ID for data model lookup
+ * @param source - The value source (literal or path reference)
+ * @param defaultValue - Default value if source is undefined or path not found
+ */
+function useDataBinding<T = unknown>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): T
+
+/**
+ * Hook for two-way data binding in form components.
+ * @param surfaceId - The surface ID
+ * @param source - The value source (must be a path reference for setting)
+ * @param defaultValue - Default value if not found
+ * @returns Tuple of [value, setValue]
+ */
+function useFormBinding<T = unknown>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): [T, (value: T) => void]
+```
+
+## Others
+
+```typescript
+/**
+ * Renders a component by ID from the component registry.
+ * @param surfaceId - The surface ID
+ * @param componentId - The component ID to render
+ */
+function ComponentRenderer(props: {
+  surfaceId: string
+  componentId: string
+}): React.ReactElement
+
+/**
+ * Represents a value source - either a literal value or a reference to a data model path.
+ */
+type ValueSource =
+  | { literalString: string }
+  | { literalNumber: number }
+  | { literalBoolean: boolean }
+  | { literalArray: string[] }
+  | { path: string }
+
+/**
+ * Action definition (attached to Button components).
+ */
+interface Action {
+  name: string
+  context?: ActionContextItem[]
+}
+```

package/website/content/index.md

@@ -18,11 +18,11 @@ First, use the `@source` directive to tell Tailwind to scan the library code for
 @source "../node_modules/@easyops-cn/a2ui-react";
 ```
 
-Next, use the `A2UIRender` component to render A2UI messages:
+Next, use the `A2UIRenderer` component to render A2UI messages:
 
 ```tsx
 import {
-  A2UIRender,
+  A2UIRenderer,
   type A2UIMessage,
   type A2UIAction,
 } from '@easyops-cn/a2ui-react/0.8'
@@ -34,7 +34,7 @@ function App() {
     console.log('Action received:', action)
   }
 
-  return <A2UIRender messages={messages} onAction={handleAction} />
+  return <A2UIRenderer messages={messages} onAction={handleAction} />
 }
 ```
 
@@ -43,7 +43,11 @@ function App() {
 You can override default components or add new custom components via the `components` prop, which takes a `Map<string, React.ComponentType>`.
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
 
 const ComponentsMap = new Map<string, React.ComponentType<any>>([
   // Override default Button component with a custom one
@@ -55,7 +59,7 @@ const ComponentsMap = new Map<string, React.ComponentType<any>>([
 
 function App() {
   return (
-    <A2UIRender
+    <A2UIRenderer
       components={ComponentsMap}
       messages={messages}
       onAction={handleAction}

package/website/serve.json

@@ -1,6 +1,8 @@
 {
   "rewrites": [
     { "source": "a2ui-react/assets/:path*", "destination": "/assets/:path*" },
+    { "source": "a2ui-react/api/:path*", "destination": "/api/:path*" },
+    { "source": "a2ui-react/api/**", "destination": "/api/index.html" },
     { "source": "a2ui-react/**", "destination": "/index.html" }
   ]
 }

package/website/src/components/Header.jsx

@@ -1,7 +1,7 @@
 import { useSiteContext } from 'plain-blog/SiteContext'
 
-export default function Header() {
-  const { baseUrl, site } = useSiteContext()
+export default function Header(props) {
+  const { baseUrl, site, url } = useSiteContext()
 
   return (
     <header>
@@ -10,9 +10,15 @@ export default function Header() {
       </h1>
       <div className="header-right">
         <nav className="header-nav">
-          <a href={baseUrl} className="active">
+          <a href={baseUrl} className={url === baseUrl ? 'active' : ''}>
             Docs
           </a>
+          <a
+            href={`${baseUrl}api/`}
+            className={url === `${baseUrl}api/` ? 'active' : ''}
+          >
+            API Reference
+          </a>
           <a href={`${baseUrl}playground/`}>Playground</a>
           <a
             href="https://github.com/easyops-cn/a2ui-react"