diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..b392bec
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic Versioning.
+
+## [0.1.1] - 2026-04-06
+
+### Added
+
+- Side-by-side diff rendering for text content
+- Virtualized rendering via `react-virtuoso` for large files
+- Context-line based collapsed unchanged sections
+- TypeScript package exports for ESM/CJS + typings
+- Demo app using Vite + React
+
+### Docs
+
+- Comprehensive root README (English)
+- Chinese README (`README.zh-CN.md`)
+- Package-level README for npm consumers (`packages/react/README.md`)
+- Roadmap and broader TODO plan for project growth
+
+## [0.1.0] - 2026-04-06
+
+### Added
+
+- Initial public package structure
+- Core diff viewer component foundation
diff --git a/README.md b/README.md
index 2da9a4f..2373359 100644
--- a/README.md
+++ b/README.md
@@ -1,39 +1,67 @@
 # virtualized-diff-viewer
 
-A high-performance React diff viewer built for large files.
+A high-performance, virtualized React diff viewer designed for **very large text files** and smooth developer experience.
+
+> Package name on npm: **`react-virtualized-diff`**
+
+[中文文档（Chinese README）](./README.zh-CN.md)
+
+---
+
+## Why this project
+
+Most diff viewers are good for small files but become slow when input grows to tens of thousands of lines.
+
+`virtualized-diff-viewer` focuses on:
+
+- **Performance first** rendering with virtualization
+- **Readable side-by-side UI** for code/text review
+- **Configurable context lines** around changes
+- **TypeScript support** for reliable integration
+- **Simple React API** for quick adoption
 
 ---
 
-## ✨ Features
+## Features
 
-- Side-by-side diff view
-- Virtualized rendering for large files
-- Collapsed unchanged blocks
-- Configurable context lines
-- TypeScript support
+- ✅ Side-by-side diff layout
+- ✅ Virtualized row rendering (good for large files)
+- ✅ Collapsed unchanged blocks with configurable context
+- ✅ Lightweight integration in React apps
+- ✅ TypeScript declarations out of the box
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
+# pnpm
 pnpm add react-virtualized-diff
+
+# npm
+npm install react-virtualized-diff
+
+# yarn
+yarn add react-virtualized-diff
 ```
 
 ---
 
-## 🚀 Usage
+## Quick start
 
 ```tsx
 import { DiffViewer } from 'react-virtualized-diff';
 
-function Example() {
+const oldText = `line 1\nline 2\nline 3`;
+const newText = `line 1\nline 2 changed\nline 3\nline 4`;
+
+export function Example() {
   return (
     <DiffViewer
       original={oldText}
       modified={newText}
       contextLines={2}
-      height={500}
+      height={480}
     />
   );
 }
@@ -41,37 +69,76 @@ function Example() {
 
 ---
 
-## 🧠 Why this project?
+## API (current)
+
+### `DiffViewer` props
+
+- `original: string` – original text content
+- `modified: string` – modified text content
+- `contextLines?: number` – unchanged lines to keep around changes (default behavior from component)
+- `height?: number | string` – viewport height for virtualization container
+
+> Tip: for best performance with huge files, keep rendering area constrained with a fixed `height`.
 
-Most React diff viewers work well for small files but struggle with large inputs.
+---
 
-This project focuses on:
+## Monorepo structure
 
-- Rendering large diffs efficiently
-- Reducing unnecessary DOM nodes
-- Keeping interaction smooth even with 100k+ lines
+```text
+apps/demo/       # Vite demo app
+packages/react/  # npm package: react-virtualized-diff
+```
 
 ---
 
-## 🛠 Development
+## Local development
 
 ```bash
 pnpm install
-pnpm dev
-pnpm build
+pnpm dev       # run demo app
+pnpm build     # build workspace packages
 ```
 
 ---
 
-## 📊 Roadmap
+## npm package README support
+
+To ensure npm users always see correct documentation:
+
+- Package-level README is maintained at `packages/react/README.md`
+- `packages/react/package.json` includes README in publish files
+- Root README links to the package docs and Chinese docs
+
+---
+
+## Release log
+
+See [CHANGELOG.md](./CHANGELOG.md) for tracked releases and supported capabilities.
+
+---
+
+## Future plan
+
+### Near-term roadmap
+
+- [ ] Optional syntax highlighting (performance-aware)
+- [ ] More comprehensive live demo scenarios (big files, mixed edits)
+- [ ] Public hosted demo site for quick evaluation
+- [ ] Better customization hooks (line renderers, gutters)
+
+### Additional TODOs to make this project more popular
 
-- [ ] Syntax highlighting (optional, performance-aware)
-- [ ] Custom render hooks
-- [ ] Worker-based diff computation
-- [ ] Benchmark suite
+- [ ] Detailed benchmark report vs common diff viewers
+- [ ] Keyboard navigation + accessibility improvements
+- [ ] Dark/light theme presets and design tokens
+- [ ] SSR usage guide (Next.js / Remix examples)
+- [ ] More real-world examples (JSON, logs, markdown, code)
+- [ ] CI release automation + semantic versioning workflow
+- [ ] Contribution guide and issue templates
+- [ ] International docs beyond English/Chinese
 
 ---
 
-## 📄 License
+## License
 
-MIT License
+MIT
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..505477d
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,141 @@
+# virtualized-diff-viewer
+
+一个面向**超大文本文件**场景的高性能 React 差异对比组件（虚拟滚动渲染）。
+
+> npm 包名：**`react-virtualized-diff`**
+
+[English README](./README.md)
+
+---
+
+## 项目定位
+
+很多 diff 组件在小文件场景表现不错，但面对数万行甚至十万行文本时，渲染和交互会明显变慢。
+
+`virtualized-diff-viewer` 的目标是：
+
+- **性能优先**：通过虚拟列表减少 DOM 压力
+- **可读性优先**：清晰的左右对比视图
+- **可配置性**：支持上下文折叠行数配置
+- **工程可用性**：TypeScript 友好、接入简单
+
+---
+
+## 功能特性
+
+- ✅ 左右并排差异视图
+- ✅ 虚拟化渲染（适合大文件）
+- ✅ 未变化区块折叠 + 上下文行
+- ✅ React 项目快速接入
+- ✅ 开箱即用 TypeScript 类型定义
+
+---
+
+## 安装
+
+```bash
+# pnpm
+pnpm add react-virtualized-diff
+
+# npm
+npm install react-virtualized-diff
+
+# yarn
+yarn add react-virtualized-diff
+```
+
+---
+
+## 快速开始
+
+```tsx
+import { DiffViewer } from 'react-virtualized-diff';
+
+const oldText = `line 1\nline 2\nline 3`;
+const newText = `line 1\nline 2 changed\nline 3\nline 4`;
+
+export function Example() {
+  return (
+    <DiffViewer
+      original={oldText}
+      modified={newText}
+      contextLines={2}
+      height={480}
+    />
+  );
+}
+```
+
+---
+
+## 当前 API
+
+### `DiffViewer` 属性
+
+- `original: string`：原始文本
+- `modified: string`：修改后文本
+- `contextLines?: number`：变化块周围保留的上下文行数
+- `height?: number | string`：组件容器高度（建议固定高度以获得更好性能）
+
+---
+
+## 仓库结构
+
+```text
+apps/demo/       # Vite 演示项目
+packages/react/  # npm 包：react-virtualized-diff
+```
+
+---
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm dev
+pnpm build
+```
+
+---
+
+## npm 包 README 支持说明
+
+为确保 npm 页面文档可用：
+
+- 在 `packages/react/README.md` 维护包级说明
+- 在 `packages/react/package.json` 发布文件中包含 README
+- 根目录 README 与中文文档互相链接
+
+---
+
+## 版本发布记录
+
+详见 [CHANGELOG.md](./CHANGELOG.md)。
+
+---
+
+## 后续规划
+
+### 近期路线
+
+- [ ] 可选语法高亮（性能优先设计）
+- [ ] 更完整的在线 Demo 场景（超大文件、复杂编辑）
+- [ ] 托管在线示例站点，方便快速体验
+- [ ] 更强的自定义能力（行渲染、gutter 等）
+
+### 可提升项目影响力的 TODO
+
+- [ ] 与主流 diff 组件的基准测试报告
+- [ ] 键盘导航与无障碍增强
+- [ ] 深色/浅色主题预设
+- [ ] SSR 集成文档（Next.js / Remix）
+- [ ] 更多真实场景示例（JSON、日志、Markdown、代码）
+- [ ] CI 自动发布与语义化版本流程
+- [ ] 完善贡献指南与 issue 模板
+- [ ] 扩展多语言文档
+
+---
+
+## 许可证
+
+MIT
diff --git a/packages/react/LICENSE b/packages/react/LICENSE
new file mode 100644
index 0000000..01a3930
--- /dev/null
+++ b/packages/react/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiahang Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/react/README.md b/packages/react/README.md
new file mode 100644
index 0000000..b084444
--- /dev/null
+++ b/packages/react/README.md
@@ -0,0 +1,32 @@
+# react-virtualized-diff
+
+React virtualized diff viewer for large text/code files.
+
+> This package is part of the `virtualized-diff-viewer` monorepo.
+
+## Install
+
+```bash
+npm install react-virtualized-diff
+```
+
+## Usage
+
+```tsx
+import { DiffViewer } from 'react-virtualized-diff';
+
+<DiffViewer original={oldText} modified={newText} contextLines={2} height={500} />;
+```
+
+## Props
+
+- `original: string`
+- `modified: string`
+- `contextLines?: number`
+- `height?: number | string`
+
+## Links
+
+- Repository README: `../../README.md`
+- Chinese README: `../../README.zh-CN.md`
+- Changelog: `../../CHANGELOG.md`
diff --git a/packages/react/package.json b/packages/react/package.json
index 55aa73f..ca5ccce 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -12,7 +12,11 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "sideEffects": false,
   "peerDependencies": {
     "react": ">=18",