kindy-editor 3.2.2 → 3.2.3

package/docs/public-events.md

@@ -110,6 +110,108 @@ includes `newlyMentionedUserIds`, and tombstoning emits
 `review.comment.deleted`. See [Review comments and @mentions](./review-comments.md)
 for the integration and notification flow.
 
+## Document change events: Raw vs Semantic layer
+
+Kindy Editor divides content changes into two distinct tiers:
+
+```text
+User Input / Keystrokes
+         │
+         ▼
+[ RAW LAYER ]  document.change.applied (keystroke mutations, internal / collab / debug)
+         │
+         ▼
+   ChangeAggregator (Session Buffer, IME, continuous typing merge, no-op filter)
+         │
+         ├────── CommitPolicy (idle debounce ~1s, blur, save, block jump, enter)
+         │
+         ▼
+[ SEMANTIC LAYER ] document.change.committed (clean diffs for CRM, Audit, AI, Outbox)
+```
+
+### 1. Raw layer: `document.change.applied`
+Fires immediately on every editor mutation (keystrokes, backspace, paste, undo/redo).
+Best used for: internal extensions, presence sync, local undo history, or low-level operation debugging.
+
+Payload (`DocumentChangeEventData`):
+```ts
+interface DocumentChangeEventData {
+  origin: "typing" | "command" | "paste" | "undo" | "redo";
+  operationCount: number;
+  affectedBlockIds: string[];
+  operations?: Op[];            // Present when detail !== "metadata"
+  textDiffs?: TextDiffSummary[]; // Discrete changes computed against pre-mutation shadow state
+  selectionBefore?: DocSelection | null;
+  selectionAfter?: DocSelection | null;
+  change?: Change;
+}
+```
+
+### 2. Semantic layer: `document.change.committed`
+Fires only when a logical editing session finishes across a commit boundary (idle debounce, blur, save, block switch).
+Best used for: **external integrations (CRM, Audit Log, AI processors, Webhook sinks, Notifications)**.
+
+Payload (`DocumentChangeCommittedData`):
+```ts
+interface DocumentChangeCommittedData {
+  transactionId: string;
+  changeGroupId: string;         // Stable group id tying all transactions in this session
+  beforeVersion: number;         // Document baseline version before session began
+  afterVersion: number;          // Document version after session completed
+  origin: "typing" | "command" | "paste" | "undo" | "redo";
+  textDiffs: TextDiffSummary[];   // Clean, aggregated text diffs (no-ops stripped)
+  intent?: string;
+  affectedBlockIds?: string[];
+}
+```
+
+### `TextDiffSummary` structure
+```ts
+interface TextDiffSummary {
+  action: "insert" | "delete" | "replace";
+  blockId: string;
+  offset: number;
+  fromText: string;
+  toText: string;
+}
+```
+
+### How specific scenarios are handled:
+
+1. **Continuous Typing Session (Gõ liên tục):**
+   - User types characters one by one.
+   - Raw `document.change.applied` events fire on each keystroke for immediate UI responsiveness.
+   - `ChangeAggregator` buffers the keystrokes without spamming downstream sinks.
+   - When the user stops typing for ~1000ms (idle) or clicks outside (blur), a single `document.change.committed` is emitted with the consolidated change (e.g., `action: "insert"`, `fromText: ""`, `toText: "Đà Nẵng"`).
+
+2. **Selected Range Replacement (Bôi đen ghi đè):**
+   - User selects `"Hà Nội"` and types `"Đà Nẵng"`.
+   - The editor runs `deleteRange` followed by `insertText`.
+   - Shadow state evaluation and `mergeRelatedChanges` combine them into:
+     `{ action: "replace", blockId: "p-5", offset: 13, fromText: "Hà Nội", toText: "Đà Nẵng" }`.
+
+3. **Multiple Independent Edits in One Transaction / Session (Nhiều sửa đổi độc lập):**
+   - E.g. Editing `"50"` -> `"75"` at offset 5 and `"30"` -> `"45"` at offset 25.
+   - `textDiffs` contains two separate items, preserving exact offsets without string concatenation corruption:
+     ```json
+     [
+       { "action": "replace", "blockId": "p-5", "offset": 5, "fromText": "50", "toText": "75" },
+       { "action": "replace", "blockId": "p-5", "offset": 25, "fromText": "30", "toText": "45" }
+     ]
+     ```
+
+4. **No-op Edits (Gõ rồi xóa về nguyên bản):**
+   - User types `" thêm"` and immediately backspaces it back to original text.
+   - When session boundary triggers, `ChangeAggregator` compares baseline vs current text.
+   - Since text is identical, **no event is emitted**, preventing dirty garbage data from reaching downstream databases.
+
+5. **Batch Commands & Paste (Dán hoặc chạy command):**
+   - Paste, cut, or formatting commands commit immediately (`CommitBoundaryReason = "explicit"`).
+   - Any prior typing session is automatically flushed before the new action begins.
+
+6. **Cursor Jump / Block Switch (Chuyển khối hoặc nhảy chuột):**
+   - If user edits block `p-1`, then clicks block `p-2` or moves caret far away, `CommitPolicy` detects a boundary (`"selection-jump"` / `"block-switch"`), flushes block `p-1`'s session, and opens a new session for `p-2`.
+
 ## What each layer owns
 
 The editor library owns content changes, review operations, editor state,

package/docs/track-changes-events.md

@@ -0,0 +1,551 @@
+# Document Change Tracking & Semantic Events
+
+Kindy Editor cung cấp hệ thống theo dõi thay đổi (Change Tracking & Audit) được thiết kế theo **mô hình 2 tầng (Two-Tier Event Architecture)**:
+1. **Tầng Kỹ thuật (Raw Layer)**: Phản ánh chi tiết từng thao tác mutation, phục vụ nội bộ editor và real-time collaboration.
+2. **Tầng Ngữ nghĩa (Semantic Layer)**: Tập hợp phiên chỉnh sửa, làm sạch dữ liệu, loại bỏ thao tác vô hiệu (no-op) và cung cấp diffs chính xác (`fromText` ➔ `toText`) cho các hệ thống tích hợp bên ngoài (CRM, Audit Log, AI, Notification).
+
+---
+
+## 1. Tổng quan Kiến trúc 2 tầng (Two-Tier Architecture)
+
+```text
+User Typing / Backspace / Paste / Command
+                   │
+                   ▼
+  commitCore (Chụp snapshot blockTextBefore trước khi runOps)
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    RAW LAYER (Kỹ thuật)                     │
+│               document.change.applied                       │
+│  - Phát sinh: Ngay lập tức sau mỗi mutation / keystroke     │
+│  - Mục đích: Collab caret sync, Undo/Redo, Debug, Plugin   │
+│  - Payload: { ops, affectedBlockIds, textDiffs }            │
+└─────────────────────────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 Change Session Aggregator                   │
+│  - Lưu baseline snapshot khi phiên bắt đầu                  │
+│  - Gom các ký tự gõ liên tiếp thành chuỗi hoàn chỉnh        │
+│  - Gom delete + insert cùng vị trí thành replace            │
+│  - Lọc bỏ thao tác no-op (gõ rồi xoá về nguyên bản)        │
+└─────────────────────────────────────────────────────────────┘
+                   │
+                   ├───── CommitPolicy (Idle ~1s, Blur, Save, Jump)
+                   ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  SEMANTIC LAYER (Ngữ nghĩa)                 │
+│               document.change.committed                     │
+│  - Phát sinh: KHI PHIÊN CHỈNH SỬA KẾT THÚC                  │
+│  - Mục đích: Hệ thống ngoài, CRM, Audit DB, AI, Webhook     │
+│  - Payload: { changeGroupId, versions, origin, textDiffs }  │
+└─────────────────────────────────────────────────────────────┘
+                   │
+                   ▼
+          createHttpEventSink (Filter eventTypes)
+                   │
+                   ▼
+       Hệ thống nhận (Integration / Backend)
+```
+
+---
+
+## 2. Cấu trúc Contract & Schema Dữ liệu
+
+### 2.1. Cấu trúc `TextDiffSummary`
+Mỗi thay đổi văn bản độc lập được chuẩn hoá thành một object trong mảng `textDiffs`:
+
+```ts
+export interface TextDiffSummary {
+  /** Hành động: chèn mới, xoá, hoặc thay thế */
+  action: "insert" | "delete" | "replace";
+  /** ID của khối đoạn văn hoặc cell chứa thay đổi */
+  blockId: string;
+  /** Vị trí bắt đầu thay đổi trong block */
+  offset: number;
+  /** Nội dung text trước khi sửa */
+  fromText: string;
+  /** Nội dung text sau khi sửa */
+  toText: string;
+}
+```
+
+### 2.2. Payload của `document.change.committed` (`event.data`)
+Đây là event chính dành cho downstream integration:
+
+```ts
+export interface DocumentChangeCommittedData {
+  /** Transaction id cuối cùng của phiên */
+  transactionId: string;
+  /** ID định danh phiên chỉnh sửa (gộp toàn bộ keystrokes trong session) */
+  changeGroupId: string;
+  /** Phiên bản tài liệu TRƯỚC khi phiên bắt đầu */
+  beforeVersion: number;
+  /** Phiên bản tài liệu SAU khi phiên kết thúc */
+  afterVersion: number;
+  /** Nguồn gốc thao tác */
+  origin: "typing" | "command" | "paste" | "undo" | "redo";
+  /** Danh sách các thay đổi text sạch sẽ */
+  textDiffs: TextDiffSummary[];
+  /** Ý định thao tác (nếu có từ command layer) */
+  intent?: string;
+  /** Danh sách các block IDs bị ảnh hưởng */
+  affectedBlockIds?: string[];
+}
+```
+
+### 2.3. Envelope chuẩn của sự kiện
+Mọi sự kiện đều nằm trong envelope đồng nhất:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "id": "evt_0199c4b2-8411",
+  "type": "document.change.committed",
+  "occurredAt": "2026-10-06T15:50:30.000Z",
+  "source": "local",
+  "actor": {
+    "id": "u-42",
+    "firstName": "An",
+    "lastName": "Nguyễn"
+  },
+  "document": {
+    "id": "contract-2026",
+    "baseVersion": 105,
+    "version": 108
+  },
+  "transaction": {
+    "id": "tx-889",
+    "status": "committed"
+  },
+  "data": {
+    "transactionId": "tx-889",
+    "changeGroupId": "chg-176239",
+    "beforeVersion": 105,
+    "afterVersion": 108,
+    "origin": "typing",
+    "textDiffs": [
+      {
+        "action": "replace",
+        "blockId": "p-5",
+        "offset": 24,
+        "fromText": "Hà Nội",
+        "toText": "Đà Nẵng"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 3. Cơ chế Xử lý & Thuật toán
+
+### 3.1. Shadow State Simulation (Chống lệch offset)
+Khi một transaction chứa nhiều ops liên tiếp:
+1. `deleteRange(1, 2)` trên `"abcdef"` biến văn bản thành `"acdef"`.
+2. `deleteRange(2, 3)` tiếp theo đang thao tác trên `"acdef"` (ký tự `"d"`), chứ không phải trên chuỗi gốc `"abcdef"` (ký tự `"c"`).
+
+`computeTextDiffs()` áp dụng tuần tự từng op lên một **in-memory shadow state**:
+- Snapshot ban đầu được chụp trước khi gọi `runOps()`.
+- Mỗi op tính toán `fromText` trực tiếp từ trạng thái hiện tại của shadow state và cập nhật shadow state cho op kế tiếp.
+- Đảm bảo trích xuất chính xác 100% `fromText` ngay cả khi có hàng chục ops trong 1 transaction.
+
+### 3.2. Merge Related Changes (Gộp thao tác thông minh)
+- **Delete + Insert tại cùng offset**: Tự động chuyển đổi thành `action: "replace"` (`"Hà Nội"` ➔ `"Đà Nẵng"`).
+- **Gõ tiến liên tục (Continuous typing)**: Tự động gom các ký tự liền kề thành 1 text hoàn chỉnh.
+- **Backspace lùi liên tục**: Tự động gom thành 1 lệnh delete với span mở rộng.
+- **Nhiều vị trí độc lập**: Nếu thay đổi ở các offset khác nhau hoặc các block khác nhau, giữ nguyên thành các item tách biệt trong `textDiffs` (không bao giờ gộp chuỗi sai lệch).
+
+### 3.3. Zero Dirty Data (Lọc bỏ No-op)
+Nếu người dùng gõ thêm nội dung rồi nhấn Backspace xoá hết về trạng thái ban đầu:
+- Khi phiên commit, `ChangeAggregator` so sánh baseline snapshot ban đầu và snapshot hiện tại.
+- Kết quả diff là rỗng (`[]`).
+- **Không phát bất kỳ event nào ra ngoài**, ngăn ngừa hoàn toàn rác dữ liệu ở downstream.
+
+---
+
+## 4. Ranh giới Commit (Commit Policy Boundaries)
+
+Sự kiện `document.change.committed` được kích hoạt khi nào?
+
+Không chỉ dựa vào debounce đơn thuần, hệ thống áp dụng nhiều ranh giới tự nhiên của người dùng:
+
+| Ranh giới | Điều kiện kích hoạt | Ý nghĩa |
+|---|---|---|
+| **Idle Debounce** | Người dùng dừng gõ ~800–1200ms (mặc định 1000ms) | Hoàn thành một cụm ý hoặc câu |
+| **Blur** | Editor mất focus ra ngoài container | Người dùng chuyển sang trường khác hoặc tab khác |
+| **Save / Export** | Người dùng bấm Lưu (Ctrl+S) hoặc Export | Chốt trạng thái tài liệu để ghi nhận |
+| **Selection Jump** | Caret nhảy cóc cách xa vị trí đang gõ (> 2 ký tự) | Người dùng chuyển sự chú ý sang vị trí khác |
+| **Block Switch** | Chuyển sang paragraph hoặc block khác | Hoàn thành đoạn hiện tại |
+| **Origin Switch** | Chuyển đổi giữa Typing, Paste, Command | Kết thúc luồng gõ trước khi nhận dữ liệu mới |
+| **Destroy** | Đóng editor instance | Thu dọn và flush toàn bộ session chưa gửi |
+
+---
+
+## 5. Hướng dẫn Tích hợp Từng Trường hợp Cụ thể
+
+### Trường hợp 1: Người dùng gõ phím liên tục
+- **Thao tác**: Người dùng gõ `"H"`, `"à"`, `" "`, `"N"`, `"ộ"`, `"i"`.
+- **Hành vi**:
+  - Tầng RAW: Phát 6 sự kiện `document.change.applied`.
+  - Tầng SEMANTIC: Đợi người dùng dừng gõ 1000ms, phát duy nhất 1 sự kiện `document.change.committed`:
+    ```json
+    {
+      "action": "insert",
+      "blockId": "p-1",
+      "offset": 0,
+      "fromText": "",
+      "toText": "Hà Nội"
+    }
+    ```
+
+### Trường hợp 2: Gõ rồi xoá về nguyên bản (No-op)
+- **Thao tác**: Văn bản gốc là `"Việt Nam"`. Người dùng gõ `" quê hương"`, rồi backspace xoá hết về `"Việt Nam"`.
+- **Hành vi**:
+  - Khi idle timer kích hoạt, `ChangeAggregator` thấy `initialText === currentText`.
+  - **Không phát event `document.change.committed`**.
+
+### Trường hợp 3: Bôi đen thay thế
+- **Thao tác**: Người dùng bôi đen chữ `"50 triệu"` và gõ `"75 triệu"`.
+- **Hành vi**:
+  - Tự động nhận diện `delete` + `insert` tại cùng offset:
+    ```json
+    {
+      "action": "replace",
+      "blockId": "p-1",
+      "offset": 10,
+      "fromText": "50 triệu",
+      "toText": "75 triệu"
+    }
+    ```
+
+### Trường hợp 4: Nhiều chỉnh sửa độc lập trong cùng một thao tác
+- **Thao tác**: Lệnh Replace-All đổi `"50"` thành `"75"` ở offset 5 và `"30"` thành `"45"` ở offset 25.
+- **Hành vi**: Mảng `textDiffs` chứa 2 phần tử độc lập:
+  ```json
+  [
+    { "action": "replace", "blockId": "p-5", "offset": 5, "fromText": "50", "toText": "75" },
+    { "action": "replace", "blockId": "p-5", "offset": 25, "fromText": "30", "toText": "45" }
+  ]
+  ```
+
+### Trường hợp 5: Nhảy chuột hoặc click ra ngoài
+- **Thao tác**: Người dùng đang gõ dở ở đoạn 1 thì click chuột sang đoạn 2 hoặc click ra ngoài editor.
+- **Hành vi**: `CommitPolicy` lập tức flush phiên của đoạn 1 mà không cần chờ hết 1000ms idle timer.
+
+---
+
+## 6. Code Mẫu Tích hợp Toàn diện
+
+### 6.1. Phía Client (Browser)
+
+Sử dụng `createHttpEventSink` với tuỳ chọn lọc `eventTypes` để chỉ chuyển tiếp các sự kiện sạch:
+
+```ts
+import { KindyEditor, createHttpEventSink } from "kindy-editor";
+
+// 1. Khởi tạo HTTP Sink chỉ nhận Semantic Events
+const sink = createHttpEventSink({
+  endpoint: "https://api.yourcompany.com/v1/editor/events",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAuthToken()}`,
+  }),
+  // QUAN TRỌNG: Chỉ gửi event sạch, loại bỏ spam keystroke
+  eventTypes: [
+    "document.change.committed",
+    "document.export.completed",
+    "review.comment.added",
+    "review.comment.deleted",
+  ],
+  batchSize: 25,
+  flushIntervalMs: 1000,
+});
+
+// 2. Khởi tạo Editor
+const editor = new KindyEditor({
+  container: document.getElementById("editor-container")!,
+  user: { id: "usr-01", firstName: "Văn", lastName: "Trần" },
+  events: { sink },
+});
+
+// 3. Đảm bảo flush dữ liệu khi người dùng đóng trang
+window.addEventListener("pagehide", () => void sink.flush());
+```
+
+### 6.2. Phía Server Consumer (Node.js / Express / NestJS)
+
+Consumer cần đảm bảo tính Idempotency và xử lý đúng thứ tự phiên bản:
+
+```ts
+app.post("/v1/editor/events", async (req, res) => {
+  const { events } = req.body;
+
+  for (const event of events) {
+    if (event.type === "document.change.committed") {
+      const { id, document, actor, occurredAt, data } = event;
+      const { changeGroupId, afterVersion, origin, textDiffs } = data;
+
+      // 1. Chống duplicate delivery dựa trên event.id
+      if (await db.processedEvents.exists(id)) {
+        continue;
+      }
+
+      // 2. Chống out-of-order (sự kiện cũ đến muộn không được ghi đè bản mới)
+      const currentDoc = await db.documents.find(document.id);
+      if (currentDoc && currentDoc.version >= afterVersion) {
+        // Ghi nhận audit log nhưng không update state
+        await db.auditLogs.insert({ eventId: id, ignoredState: true });
+        await db.processedEvents.insert(id);
+        continue;
+      }
+
+      // 3. Lưu Audit Log ngữ nghĩa (Ai sửa? Sửa từ gì sang gì? Lúc nào?)
+      await db.auditLogs.insert({
+        eventId: id,
+        documentId: document.id,
+        changeGroupId,
+        actor: actor ? `${actor.firstName} ${actor.lastName}` : "Unknown",
+        origin,
+        occurredAt,
+        textDiffs, // Mảng [{ action, blockId, offset, fromText, toText }]
+      });
+
+      // 4. Cập nhật phiên bản văn bản hiện tại (UPSERT)
+      await db.documents.upsert(
+        { id: document.id },
+        { version: afterVersion, lastModifiedAt: occurredAt }
+      );
+
+      // 5. Đánh dấu đã xử lý
+      await db.processedEvents.insert(id);
+    }
+  }
+
+  res.status(202).json({ success: true });
+});
+```
+
+---
+
+## 7. Xác định Vị trí Dòng/Đoạn & Ngữ cảnh Thay đổi (Location & Context Mapping)
+
+### 7.1. Tại sao hệ thống quản lý theo "Đoạn (Block)" thay vì "Dòng (Line)"?
+Trong các trình soạn thảo tài liệu chuẩn Word/Canvas (Page Layout Engine):
+* **Số dòng hiển thị (Visual Lines)** không cố định: Khi bạn đổi cỡ chữ, đổi lề trang (margins), đổi khổ giấy từ A4 sang Letter, hoặc thay đổi zoom thì số dòng trên màn hình sẽ tự động co giãn và ngắt dòng khác nhau (*soft line break*).
+* Do đó, đơn vị cấu trúc ngữ nghĩa vững chắc và duy nhất của tài liệu là **Block (Đoạn văn - Paragraph)** có `blockId` cố định và vị trí ký tự **`offset`** (tính từ ký tự 0 đến cuối đoạn).
+
+### 7.2. Cách tra cứu Vị trí Đoạn văn & Ngữ cảnh Câu văn từ `blockId`
+Để biến `blockId: "p-5"` thành thông tin con người dễ đọc hiểu (*"Đoạn 2, mục 1. Thời hạn hợp đồng"*), phía tích hợp có thể tra cứu trực tiếp từ cây tài liệu của Editor:
+
+```ts
+import type { KindyEditor } from "kindy-editor";
+
+/** Tra cứu vị trí đoạn văn, tiêu đề mục bao bọc và ngữ cảnh cả câu */
+export async function resolveChangeLocation(
+  editor: KindyEditor,
+  diff: { blockId: string; offset: number; fromText: string; toText: string }
+) {
+  const handle = await editor.whenReady();
+  const doc = handle.getDocument();
+  const blocks = doc.blocks;
+
+  const blockIndex = blocks.findIndex((b) => b.id === diff.blockId);
+  if (blockIndex === -1) return null;
+
+  const targetBlock = blocks[blockIndex];
+  const blockText = targetBlock.kind === "paragraph"
+    ? targetBlock.runs.map((r) => r.text).join("")
+    : "";
+
+  // 1. Tìm tiêu đề (Heading) gần nhất phía trên đoạn này
+  let nearestHeading = "";
+  for (let i = blockIndex; i >= 0; i--) {
+    const b = blocks[i];
+    if (b.kind === "paragraph" && b.style?.outlineLevel !== undefined && b.style.outlineLevel <= 2) {
+      nearestHeading = b.runs.map((r) => r.text).join("");
+      break;
+    }
+  }
+
+  // 2. Trích xuất ngữ cảnh cả câu văn xung quanh phần sửa
+  const start = Math.max(0, diff.offset - 30);
+  const end = Math.min(blockText.length, diff.offset + (diff.toText.length || diff.fromText.length) + 30);
+  const prefix = (start > 0 ? "…" : "") + blockText.slice(start, diff.offset);
+  const suffix = blockText.slice(diff.offset + (diff.toText.length || 0), end) + (end < blockText.length ? "…" : "");
+
+  const sentenceContext = `${prefix}[~${diff.fromText}~ ➔ ${diff.toText}]${suffix}`;
+
+  return {
+    paragraphNumber: blockIndex + 1, // Đoạn thứ mấy trong tài liệu
+    totalParagraphs: blocks.length,
+    heading: nearestHeading,        // Nằm dưới mục nào
+    fullText: blockText,
+    sentenceContext,               // Ngữ cảnh câu văn
+  };
+}
+```
+
+### 7.3. Tương tác Thị giác 2 chiều: Cuộn đến dòng & Highlight phát sáng
+Khi hiển thị danh sách lịch sử sửa đổi (Change History panel), bạn có thể cho phép người dùng bấm vào một thay đổi để **Editor tự cuộn trang đến đúng dòng đó** và **vẽ viền phát sáng (pulse highlight)** trực tiếp lên trang văn bản:
+
+```ts
+/** Bấm vào sự kiện -> Tự động nhảy đến vị trí sửa trên trang soạn thảo */
+export async function jumpToDiff(
+  editor: KindyEditor,
+  diff: { blockId: string; offset: number; fromText: string; toText: string }
+) {
+  const length = Math.max(1, diff.toText.length || diff.fromText.length);
+  const range = {
+    anchor: { blockId: diff.blockId, offset: diff.offset },
+    focus: { blockId: diff.blockId, offset: diff.offset + length },
+  };
+
+  // 1. Cuộn trang êm ái tới đúng vị trí đoạn văn
+  await editor.revealRange(range, { behavior: "smooth", align: "center" });
+
+  // 2. Vẽ viền highlight phát sáng trong 2.5 giây
+  await editor.setExternalAnnotations([
+    {
+      id: "change-pulse-highlight",
+      range,
+      style: {
+        background: "rgba(16, 185, 129, 0.4)", // Màu xanh ngọc nhẹ
+        borderColor: "#059669",
+        borderWidth: 2,
+      },
+    },
+  ]);
+
+  setTimeout(() => {
+    void editor.clearExternalAnnotations();
+  }, 2500);
+}
+```
+
+---
+
+## 8. Chế độ Track Changes Thị giác Trực tiếp (Visual Suggest Mode)
+
+Hệ thống của Kindy Editor phân biệt rõ 2 nhu cầu:
+1. **Audit / Event Tracking (Chạy ngầm)**: Người dùng soạn thảo bình thường (chữ hiển thị sạch sẽ), nhưng toàn bộ hành vi sửa đổi được ghi lại dưới dạng event `document.change.committed` cho DB / AI.
+2. **Visual Suggest Mode (Hiển thị vết mực trên trang giấy giống Word / Google Docs)**: Chữ cũ bị gạch ngang màu đỏ, chữ mới được gạch chân màu xanh, kèm bong bóng nhận xét ở lề phải.
+
+### 8.1. Kích hoạt Chế độ Suggest Mode
+Bạn có thể thiết lập chế độ này khi khởi tạo hoặc chuyển đổi linh hoạt qua API:
+
+```ts
+// Cách 1: Thiết lập ngay khi khởi tạo
+const editor = new KindyEditor({
+  container: document.getElementById("editor")!,
+  mode: "suggest", // Chế độ gợi ý chỉnh sửa
+  allowedModes: ["edit", "suggest", "view"],
+});
+
+// Cách 2: Chuyển đổi qua API
+await editor.setMode("suggest");
+```
+
+### 8.2. Phê duyệt hoặc Từ chối Thay đổi (Accept / Reject)
+Khi ở chế độ `suggest`, người duyệt có thể duyệt từng thay đổi hoặc duyệt toàn bộ:
+
+```ts
+// Duyệt 1 đề xuất cụ thể
+await editor.acceptSuggestion(suggestionId);
+
+// Từ chối 1 đề xuất
+await editor.rejectSuggestion(suggestionId);
+
+// Duyệt tất cả đề xuất trong tài liệu
+await editor.acceptAllSuggestions();
+
+// Từ chối tất cả đề xuất
+await editor.rejectAllSuggestions();
+```
+
+---
+
+## 9. Thiết kế Database Schema Hoàn chỉnh cho Audit Log & Version History
+
+Dưới đây là schema quan hệ chuẩn (PostgreSQL / MySQL) được khuyến nghị để lưu trữ toàn diện:
+
+### 9.1. Bảng `document_change_sessions` (Lưu từng phiên commit)
+```sql
+CREATE TABLE document_change_sessions (
+    id VARCHAR(64) PRIMARY KEY,              -- changeGroupId (vd: chg-176239)
+    document_id VARCHAR(64) NOT NULL,
+    event_id VARCHAR(64) UNIQUE NOT NULL,    -- event.id (chống duplicate)
+    actor_id VARCHAR(64),                    -- actor.id (người thực hiện)
+    actor_name VARCHAR(255),                 -- Tên người sửa
+    origin VARCHAR(32) NOT NULL,             -- typing, paste, command, undo...
+    before_version INT NOT NULL,             -- Phiên bản trước
+    after_version INT NOT NULL,              -- Phiên bản sau
+    occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+CREATE INDEX idx_change_sessions_doc ON document_change_sessions(document_id, occurred_at);
+```
+
+### 9.2. Bảng `document_text_diffs` (Lưu chi tiết từng đoạn văn bản đổi)
+```sql
+CREATE TABLE document_text_diffs (
+    id BIGSERIAL PRIMARY KEY,
+    session_id VARCHAR(64) REFERENCES document_change_sessions(id) ON DELETE CASCADE,
+    document_id VARCHAR(64) NOT NULL,
+    action VARCHAR(16) NOT NULL,             -- insert, delete, replace
+    block_id VARCHAR(64) NOT NULL,           -- ID đoạn văn (vd: p-5)
+    paragraph_number INT,                    -- Đoạn số mấy (vd: Đoạn 2)
+    heading_title VARCHAR(255),              -- Tiêu đề mục cha (nếu có)
+    offset_start INT NOT NULL,
+    from_text TEXT,                          -- Text cũ
+    to_text TEXT,                            -- Text mới
+    sentence_context TEXT                    -- Trích xuất cả câu văn ngữ cảnh
+);
+
+CREATE INDEX idx_diffs_doc_block ON document_text_diffs(document_id, block_id);
+```
+
+### 9.3. Câu lệnh Truy vấn Mẫu (SQL Queries)
+**Xem lịch sử thay đổi của một tài liệu theo thứ tự thời gian:**
+```sql
+SELECT 
+    s.occurred_at,
+    s.actor_name,
+    s.origin,
+    s.before_version || ' ➔ ' || s.after_version AS version_transition,
+    d.action,
+    d.paragraph_number,
+    d.heading_title,
+    d.from_text,
+    d.to_text,
+    d.sentence_context
+FROM document_change_sessions s
+JOIN document_text_diffs d ON s.id = d.session_id
+WHERE s.document_id = 'contract-2026'
+ORDER BY s.occurred_at DESC;
+```
+
+---
+
+## 10. Checklist Tích hợp & Best Practices khi Triển khai
+
+1. **Chỉ gửi Semantic Events ra ngoài**: Luôn cấu hình `eventTypes: ["document.change.committed", ...]` trong `createHttpEventSink`. Tránh lưu `document.change.applied` vào cơ sở dữ liệu trừ khi bạn có nhu cầu đặc thù là Replay từng phím gõ.
+2. **Đảm bảo tính Idempotency**: Mọi sự kiện đều có trường `event.id` duy nhất. Phía Backend Consumer bắt buộc phải kiểm tra `event.id` trước khi xử lý để chống duplicate do cơ chế retry mạng.
+3. **Flush dữ liệu khi đóng trang**: Luôn gắn listener `window.addEventListener("pagehide", () => void sink.flush())` để không bỏ sót các thao tác gõ cuối cùng trước khi người dùng đóng trình duyệt.
+4. **Bảo mật & Redaction dữ liệu nhạy cảm**: Nếu văn bản có chứa thông tin nhạy cảm (mật khẩu, số thẻ ngân hàng, CCCD), hãy sử dụng callback `redact` trong cấu hình `events`:
+   ```ts
+   const editor = new KindyEditor({
+     container,
+     events: {
+       sink,
+       redact: (event) => {
+         // Lọc hoặc che mờ dữ liệu nhạy cảm trong event.data trước khi gửi đi
+         return event;
+       },
+     },
+   });
+   ```
+5. **Định vị trực quan nâng cao**: Sử dụng kết hợp `editor.revealRange()` và `editor.setExternalAnnotations()` trên Frontend để người dùng bấm vào danh sách lịch sử sửa đổi là màn hình tự nhảy tới đúng dòng và highlight phát sáng.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kindy-editor",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "type": "module",
   "description": "Trình soạn thảo tài liệu Word chính xác, vẽ bằng canvas",
   "license": "MIT",
@@ -40,7 +40,7 @@
   "files": [
     "dist-lib",
     "types",
-    "docs",
+    "docs/*.md",
     "README.md"
   ],
   "scripts": {