chore: update readme

Author: Zhang-JiahangH

CHANGELOG.md

@@ -4,6 +4,13 @@ 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.
 
+## [Unreleased]
+
+### Docs
+
+- Reorganized root README files for clearer scanning (quick overview + positioning block), clarified the purpose of `docs/positioning.md`, and aligned `packages/react/README.md` so npm package docs reflect the same positioning updates.
+
+
 ## [0.1.5] - 2026-04-08
 
 ### Added

README.md

@@ -1,11 +1,30 @@
 # react-virtualized-diff
 
+Built for large files: a virtualized React diff component.
+
+## At a Glance
+
+- ⚡ **Focus:** fast diff rendering for very large files (10k+ lines).
+- 🧩 **Best for:** embedded PR/MR review pages, long-list diff UIs, and internal review tools.
+- 🧭 **Positioning details:** [docs/positioning.md](./docs/positioning.md).
+
+## Positioning
+
+Target scenarios: very large files, long-list scrolling experiences, and embedded code review pages (PR/MR diff views) where stable first paint and smooth scrolling are critical.
+
+| Option | Performance (large files) | Bundle size | Customizability | React ecosystem integration cost |
+| --- | --- | --- | --- | --- |
+| `react-virtualized-diff` | High (virtualized rendering for 10k+ lines) | Small-to-medium (focused diff capability) | High (style slots, render hooks, interaction callbacks) | Low (native React API, TypeScript-friendly) |
+| Traditional non-virtualized diff components | Medium-to-low (often degrades on big files) | Medium | Medium (limited extension points) | Low (quick to adopt, but needs extra optimization for large files) |
+| In-house diff + virtualization | Depends on implementation (can be high) | Uncertain (often grows with business logic) | High (fully controllable) | High (build + maintenance overhead) |
+
 High-performance React code/text diff viewer for **large text/code files** with virtualized rendering.
 
 - 📦 npm: [`react-virtualized-diff`](https://www.npmjs.com/package/react-virtualized-diff)
 - 🌐 Live Demo: https://www.zhangjiahang.com/react-virtualized-diff
 - 📊 Benchmark report: [benchmark-results/results.md](./benchmark-results/results.md)
 - 🇨🇳 中文文档: [README.zh-CN.md](./README.zh-CN.md)
+- 🧭 Positioning doc: [docs/positioning.md](./docs/positioning.md)
 
 ## Quick Demo View
 ![20260408-024125](https://github.com/user-attachments/assets/5345cbe4-04b1-4cfd-bcba-a68fcd7e82aa)

README.zh-CN.md

@@ -1,11 +1,30 @@
 # react-virtualized-diff
 
+为大文件而生的 React 虚拟化 diff 组件。
+
+## 快速了解
+
+- ⚡ **核心目标：** 面向 `10k+` 行大文件，保持渲染与滚动流畅。
+- 🧩 **典型场景：** PR/MR 代码审查页嵌入、长列表 diff 页面、内部审查系统。
+- 🧭 **定位细节：** [docs/positioning.md](./docs/positioning.md)。
+
+## 产品定位
+
+目标场景：超大文件（如 10k+ 行）、长列表滚动场景，以及代码审查页面（PR/MR Diff）嵌入，重点解决首屏渲染与滚动流畅度问题。
+
+| 方案 | 性能（大文件） | 包体积 | 可定制性 | React 生态集成成本 |
+| --- | --- | --- | --- | --- |
+| `react-virtualized-diff` | 高（虚拟化渲染，适合 10k+ 行） | 中等偏小（聚焦 diff 核心能力） | 高（样式槽位、渲染器、交互回调） | 低（原生 React 组件 + TypeScript 友好） |
+| 传统非虚拟化 diff 组件 | 中-低（大文件容易卡顿） | 中等 | 中（扩展点有限） | 低（接入快，但大文件需额外优化） |
+| 自研 diff + 列表虚拟化方案 | 取决于实现（理论可高） | 不确定（常随业务膨胀） | 高（完全可控） | 高（开发与维护成本高） |
+
 面向**大体量文本/代码文件**的高性能 React Diff 组件（虚拟滚动渲染）。
 
 - 📦 npm：[`react-virtualized-diff`](https://www.npmjs.com/package/react-virtualized-diff)
 - 🌐 在线 Demo：https://www.zhangjiahang.com/react-virtualized-diff
 - 📊 Benchmark 报告：[benchmark-results/results.md](./benchmark-results/results.md)
 - 🇬🇧 English README：[README.md](./README.md)
+- 🧭 定位文档：[docs/positioning.md](./docs/positioning.md)
 
 ## 示例
 ![20260408-024125](https://github.com/user-attachments/assets/5345cbe4-04b1-4cfd-bcba-a68fcd7e82aa)

docs/positioning.md

@@ -0,0 +1,27 @@
+# Positioning
+
+`docs/positioning.md` 是项目的“定位说明文档”，用于统一回答“这个库是给谁用的、适合放在哪些业务场景、与同类方案如何区分”。
+
+## 标准宣传语
+
+为大文件而生的 React 虚拟化 diff 组件。
+
+## 目标用户画像
+
+### 1) 代码托管平台（Code Hosting Platform）
+
+- 典型形态：Git 服务、Merge Request / Pull Request 审查页面。
+- 核心诉求：在超大变更集下保持流畅滚动、快速跳转与可读性。
+- 集成关注点：与现有评论系统、行号交互、权限体系和主题系统兼容。
+
+### 2) 内部审查系统（Internal Review System）
+
+- 典型形态：企业内部代码审查、配置变更审计、文本比对后台。
+- 核心诉求：稳定性优先、可定制 UI、可嵌入业务流程（审批、留痕、追踪）。
+- 集成关注点：与组织内 React 技术栈、设计系统、埋点与监控对齐。
+
+### 3) IDE 插件前端（IDE Plugin Frontend）
+
+- 典型形态：WebView / 内嵌面板中的文件 diff 预览。
+- 核心诉求：受限容器中仍能维持性能，支持暗色主题与紧凑布局。
+- 集成关注点：轻量依赖、可控渲染开销、便于与编辑器事件联动。

packages/react/README.md

@@ -2,6 +2,20 @@
 
 High-performance React diff viewer with virtualization for large text/code files.
 
+## At a glance
+
+- Built for large files (`10k+` lines) and long diff lists.
+- Designed for embedded code review UIs (PR/MR pages), internal review systems, and IDE plugin frontends.
+- Positioning & personas: https://github.com/Zhang-JiahangH/react-virtualized-diff/blob/main/docs/positioning.md
+
+## Positioning
+
+| Option | Performance (large files) | Bundle size | Customizability | React integration cost |
+| --- | --- | --- | --- | --- |
+| `react-virtualized-diff` | High (virtualized rendering) | Small-to-medium | High | Low |
+| Traditional non-virtualized diff components | Medium-to-low | Medium | Medium | Low |
+| In-house diff + virtualization | Depends on implementation | Uncertain | High | High |
+
 - Demo: https://www.zhangjiahang.com/react-virtualized-diff
 - Changelog: https://github.com/Zhang-JiahangH/react-virtualized-diff/blob/main/CHANGELOG.md
 - Benchmark: https://github.com/Zhang-JiahangH/react-virtualized-diff/blob/main/benchmark-results/results.md