kindy-editor 3.2.5 → 3.2.7

package/dist-lib/{qrcode-efBlPzzh.js → qrcode-B-JKix2T.js}

@@ -2288,13 +2288,13 @@ export {
   Ue as i,
   $e as j,
   qe as k,
-  pt as l,
-  Ke as m,
-  U as n,
-  lt as o,
+  lt as l,
+  Ct as m,
+  pt as n,
+  U as o,
   jt as p,
   z as q,
-  Ct as r,
+  Ke as r,
   Ut as s,
   X as t,
   He as u,

package/dist-lib/{qrcode-oNwKusWD.js → qrcode-BCaJLV1G.js}

@@ -1,4 +1,4 @@
-import { q as u } from "./qrcode-efBlPzzh.js";
+import { q as u } from "./qrcode-B-JKix2T.js";
 async function f(t) {
   const e = await crypto.subtle.digest("SHA-256", t), r = new Uint8Array(e);
   let a = "";

package/dist-lib/recalc-docx.js

@@ -1,6 +1,6 @@
 import { u, s as f, a as m, z as g } from "./browser-ODPzT3Lm.js";
 import { f as h } from "./contentTypes-ChqPfcVI.js";
-import { p as b, c as k } from "./recalcToc-Bc8V9Ecn.js";
+import { p as b, c as k } from "./recalcToc-CaiTn2IJ.js";
 function w(s, r) {
   const n = b(r), a = {};
   for (const [o, i] of Object.entries(s.bookmarks ?? {})) {

package/dist-lib/{recalcToc-Bc8V9Ecn.js → recalcToc-CaiTn2IJ.js}

@@ -1,4 +1,4 @@
-import { o as Ln, r as Ls, t as Os, s as Ps } from "./qrcode-efBlPzzh.js";
+import { l as Ln, m as Ls, t as Os, s as Ps } from "./qrcode-B-JKix2T.js";
 import { c as Is, f as Ze } from "./lists-BVCy5dMa.js";
 import { m as he, f as Ue, c as le } from "./metrics-CdfHD-8y.js";
 import { c as vs, f as On, M as nt, g as Rs, P as Mt, w as Ws, s as Ts } from "./paintStyle-Cb7IGKPW.js";

package/dist-lib/{stylesheet-BT1DGhnx.js → stylesheet-BPIJJMlK.js}

@@ -1,4 +1,4 @@
-import { p as u } from "./qrcode-efBlPzzh.js";
+import { p as u } from "./qrcode-B-JKix2T.js";
 function p(e) {
   return e.type ?? "paragraph";
 }

package/dist-lib/{webmcp-BcWSo1v9.js → webmcp-B0swfp0T.js}

@@ -1,4 +1,4 @@
-import { p as j, c as _, e as F, t as k, D as L } from "./qrcode-efBlPzzh.js";
+import { p as j, c as _, e as F, t as k, D as L } from "./qrcode-B-JKix2T.js";
 const s = (e) => Math.round(e * 100) / 100;
 function A(e) {
   const o = { font: e.fontFamily, sizePx: e.fontSizePx };
@@ -332,7 +332,7 @@ function H(e, o = {}, r = {}) {
       if (i && e.search(i).total === 0)
         return e.searchClear(), f(`text not found: ${i}`);
       if (!e.getSelection()) return f("no selection (pass 'find' or select_range first)");
-      const { insertText: d } = await import("./editorApp-B6qDC4lD.js").then((m) => m.c);
+      const { insertText: d } = await import("./editorApp-BtDzRfJq.js").then((m) => m.c);
       return e.dispatch(d(t)), i && e.searchClear(), g("inserted");
     }
   }), a({

package/docs/find-and-replace.md

@@ -0,0 +1,224 @@
+# Tìm kiếm, Thay thế & Cuộn Focus (Find & Replace API)
+
+Kindy Editor cung cấp hệ thống Tìm kiếm & Thay thế (Find & Replace) mạnh mẽ trên nền Canvas, hỗ trợ tính toán tọa độ ký tự chính xác, tự động bôi đen (selection) và **tự động cuộn màn hình (scroll focus)** đến vị trí văn bản cần thay thế.
+
+---
+
+## 1. Cơ chế hoạt động (How it works)
+
+Khi tìm kiếm hoặc thay thế, editor thực hiện các bước sau:
+
+```text
+[search(query)] 
+   │
+   ├── 1. Quét AST text của các block trong Document
+   ├── 2. Highlight tất cả các matches trên Canvas overlay
+   └── 3. gotoMatch(0):
+            ├── setSelection({ anchor, focus })  --> Bôi đen match
+            ├── caretRect(tree, position)        --> Tính tọa độ pixel trên trang
+            └── paint.ensureVisible(rect)        --> TỰ ĐỘNG CUỘN VIEWPORT ĐẾN MATCH
+```
+
+Khi thực hiện thay thế (`searchReplaceCurrent`):
+1. Match đang chọn được thay thế bằng chuỗi mới thông qua một **Transaction nguyên tử** (Atomic Op Group: `deleteRange` + `insertText`).
+2. Editor tự động quét lại các match còn lại.
+3. Tự động chuyển con trỏ và **cuộn màn hình đến match kế tiếp** ngay lập tức.
+4. Toàn bộ thao tác có thể **Undo (`Ctrl+Z`)** hoàn hảo.
+
+---
+
+## 2. Danh sách API (API Reference)
+
+Các API này có thể được gọi trực tiếp từ đối tượng editor (`KindyEditorElement` hoặc `EditorHandle`):
+
+### `search(query, opts?): Promise<SearchState>`
+Tìm kiếm văn bản trong tài liệu, đánh dấu tất cả các vị trí trùng khớp và tự động cuộn focus đến match đầu tiên.
+- **Tham số**:
+  - `query: string`: Từ khóa cần tìm.
+  - `opts?: { matchCase?: boolean; wholeWord?: boolean }`:
+    - `matchCase`: Khớp chính xác chữ hoa/chữ thường (mặc định: `false`).
+    - `wholeWord`: Chỉ khớp từ nguyên vẹn (mặc định: `false`).
+- **Trả về**: `Promise<SearchState>` gồm `{ index: number, total: number }` (1-based, ví dụ `1/12`).
+
+### `searchNav(dir): Promise<SearchState>`
+Điều hướng giữa các kết quả tìm kiếm và tự động cuộn màn hình đến kết quả đó.
+- **Tham số**:
+  - `dir: 1 | -1`: `1` để chuyển đến match kế tiếp, `-1` để quay lại match trước.
+- **Trả về**: `Promise<SearchState>`.
+
+### `searchReplaceCurrent(replacement): Promise<SearchState>`
+Thay thế kết quả đang được chọn bằng nội dung mới, sau đó **tự động nhảy và cuộn focus đến match kế tiếp**.
+- **Tham số**:
+  - `replacement: string`: Chuỗi văn bản thay thế.
+- **Trả về**: `Promise<SearchState>` biểu thị vị trí match tiếp theo.
+
+### `searchReplaceAll(replacement): Promise<number>`
+Thay thế toàn bộ tất cả các kết quả tìm kiếm trong tài liệu trong một transaction duy nhất (1 lần Undo).
+- **Tham số**:
+  - `replacement: string`: Chuỗi văn bản thay thế.
+- **Trả về**: `Promise<number>`: Số lượng đoạn văn bản đã được thay thế.
+
+### `searchClear(): Promise<void>`
+Xóa tất cả highlight tìm kiếm và đóng trạng thái tìm kiếm hiện tại.
+
+### `revealRange(range, options?): Promise<void>`
+Cuộn viewport đến bất kỳ vị trí text range nào trong văn bản (hữu ích cho AI suggestion hoặc spellcheck).
+- **Tham số**:
+  - `range: ExternalRange`: Gồm `{ start: { blockId, offset }, end: { blockId, offset } }`.
+  - `options?: RevealRangeOptions`:
+    - `behavior?: "auto" | "smooth"`: Hiệu ứng cuộn mượt (mặc định `"smooth"`).
+    - `align?: "nearest" | "center"`: Vị trí canh lề (mặc định `"center"`).
+    - `durationMs?: number`: Thời gian animation cuộn (mặc định `280ms`).
+
+---
+
+## 3. Hướng dẫn tích hợp hệ thống (System Integration Guide)
+
+### Cách 1: Sử dụng UI Tìm kiếm & Thay thế có sẵn (Built-in UI)
+
+Kindy Editor đã tích hợp sẵn thanh công cụ Find & Replace:
+- **Phím tắt**: Nhấn `Ctrl + F` (hoặc `Cmd + F` trên macOS).
+- **Ribbon**: Chọn tab **Trang chủ** / **Home** -> nút **Tìm kiếm / Thay thế**.
+- Giao diện có sẵn:
+  - Ô nhập từ khóa tìm kiếm và ô nhập nội dung thay thế.
+  - Tùy chọn khớp hoa/thường (`Aa`) và khớp nguyên từ (`[W]`).
+  - Nút điều hướng trước/sau (`‹`, `›`) với phím tắt `Enter` / `Shift+Enter`.
+  - Nút `Replace` và `Replace All`.
+  - Bộ đếm `1/5` hiển thị số lượng match trực quan.
+
+---
+
+### Cách 2: Tích hợp Custom Search & Replace Toolbar từ Host Application
+
+Nếu hệ thống của bạn muốn xây dựng thanh tìm kiếm riêng bên ngoài khung editor (ví dụ: thanh công cụ header của ứng dụng web React / Vue / Angular):
+
+#### Mã nguồn tích hợp JavaScript / TypeScript:
+
+```ts
+import type { KindyEditorElement, SearchState } from "kindy-editor";
+
+// 1. Lấy tham chiếu đến web component kindy-editor
+const editor = document.querySelector("kindy-editor") as KindyEditorElement;
+
+// 2. Thực hiện tìm kiếm
+async function handleSearch(keyword: string) {
+  if (!keyword.trim()) {
+    await editor.searchClear();
+    return;
+  }
+
+  // search() tự động highlight VÀ cuộn focus đến kết quả đầu tiên
+  const state: SearchState = await editor.search(keyword, {
+    matchCase: false, // Không phân biệt hoa/thường
+    wholeWord: false, // Không bắt buộc nguyên từ
+  });
+
+  console.log(`Tìm thấy ${state.total} kết quả. Đang ở vị trí ${state.index}`);
+  updateMatchUI(state);
+}
+
+// 3. Chuyển sang kết quả tiếp theo (Next match)
+async function handleNext() {
+  const state = await editor.searchNav(1);
+  updateMatchUI(state);
+}
+
+// 4. Quay lại kết quả trước (Previous match)
+async function handlePrev() {
+  const state = await editor.searchNav(-1);
+  updateMatchUI(state);
+}
+
+// 5. Thay thế kết quả hiện tại và tự động cuộn đến kết quả tiếp theo
+async function handleReplace(newText: string) {
+  const state = await editor.searchReplaceCurrent(newText);
+  console.log(`Đã thay thế. Chuyển đến kết quả tiếp theo: ${state.index}/${state.total}`);
+  updateMatchUI(state);
+}
+
+// 6. Thay thế tất cả (Replace All)
+async function handleReplaceAll(newText: string) {
+  const count = await editor.searchReplaceAll(newText);
+  alert(`Đã thay thế thành công ${count} vị trí.`);
+  await editor.searchClear();
+}
+
+// 7. Đóng tìm kiếm
+async function handleCloseSearch() {
+  await editor.searchClear();
+}
+
+function updateMatchUI(state: SearchState) {
+  const badge = document.getElementById("search-counter");
+  if (badge) {
+    badge.innerText = state.total > 0 ? `${state.index}/${state.total}` : "0/0";
+  }
+}
+```
+
+---
+
+### Cách 3: Thay thế tại vị trí cụ thể và Scroll Focus (AI Suggestion / Linter)
+
+Khi hệ thống backend (AI rà soát hợp đồng, kiểm tra chính tả) trả về một vị trí lỗi cụ thể và bạn muốn người dùng duyệt qua từng lỗi, cuộn màn hình đến đoạn đó và thay thế:
+
+```ts
+interface ReplacementSuggestion {
+  range: {
+    start: { blockId: string; offset: number };
+    end: { blockId: string; offset: number };
+  };
+  originalText: string;
+  suggestedText: string;
+}
+
+async function reviewAndApplySuggestion(suggestion: ReplacementSuggestion) {
+  // 1. Cuộn màn hình canvas đến vị trí cần sửa với animation mượt
+  await editor.revealRange(suggestion.range, {
+    behavior: "smooth",
+    align: "center",
+  });
+
+  // 2. Tùy chọn: Chọn đoạn văn bản đó để người dùng thấy rõ
+  // (Nếu host có hỗ trợ setSelection)
+
+  // 3. Khi người dùng bấm "Chấp nhận thay thế":
+  // Nếu dùng search theo cụm từ:
+  const state = await editor.search(suggestion.originalText);
+  if (state.total > 0) {
+    await editor.searchReplaceCurrent(suggestion.suggestedText);
+  }
+}
+```
+
+---
+
+### Cách 4: Phân biệt với Thay thế Biến mẫu hợp đồng (`setTemplateVariables`)
+
+Nếu mục đích của bạn là **điền dữ liệu hợp đồng tự động** (ví dụ thay thế `{{HO_TEN}}`, `{{SO_CCCD}}`, `{{NGAY_KY}}`):
+
+👉 **Nên dùng `setTemplateVariables`** thay vì `searchReplaceCurrent`:
+- `setTemplateVariables` cập nhật nguyên tử, bảo toàn format chữ, không phá vỡ cấu trúc và có lịch sử Audit Trail.
+- `searchReplaceCurrent` phù hợp cho tìm kiếm / thay thế văn bản thông thường của người dùng.
+
+```ts
+// Điền tự động các trường dữ liệu hợp đồng
+await editor.setTemplateVariables({
+  HO_TEN: "Nguyễn Văn A",
+  SO_CCCD: "0123456789",
+  NGAY_KY: "10/10/2026"
+});
+```
+
+---
+
+## 4. Bảng tóm tắt các tính năng
+
+| Nhu cầu | Hàm đề xuất | Tự động Scroll & Focus? |
+| :--- | :--- | :---: |
+| Tìm từ khóa và nhảy đến vị trí đó | `editor.search(query, opts)` |  Có (`gotoMatch` -> `paint.ensureVisible`) |
+| Xem kết quả kế tiếp / trước đó | `editor.searchNav(1)` / `(-1)` |  Có |
+| Thay thế từ đang chọn và nhảy đến từ kế tiếp | `editor.searchReplaceCurrent(newText)` |  Có |
+| Thay thế toàn bộ tài liệu | `editor.searchReplaceAll(newText)` | Giữ nguyên selection |
+| Cuộn đến một đoạn bất kỳ theo Range | `editor.revealRange(range, options)` |  Có (Smooth animation) |
+| Xóa highlight tìm kiếm | `editor.searchClear()` | - |

package/docs/qrcode-integration-guide.md

@@ -514,8 +514,43 @@ Mỗi khi cấu hình mã QR được cập nhật (`editor.setQRCode(...)`), h
 
 ---
 
-## 11. Lịch sử Cập nhật (Update Log)
+## 11. Xử lý Điều Hướng Trang Khi Quét QR (`goToPage`)
 
+Khi người dùng quét mã QR trên bản in hoặc văn bản điện tử, đường dẫn mở ra sẽ chứa tham số trang:
+```text
+https://my-hospital.vn/verify/BA-2026-0012?page=3
+```
+
+Ứng dụng Host FE chỉ cần đọc tham số `?page=N` từ URL và gọi `goToPage` trên `KindyEditor` hoặc `EditorHandle`:
+
+```ts
+const urlParams = new URLSearchParams(window.location.search);
+const pageParam = urlParams.get("page");
+
+if (pageParam) {
+  const page = parseInt(pageParam, 10);
+  // Tự động chờ layout render xong, tự scroll chuẩn xác container Kindy
+  const success = await editor.goToPage(page, { behavior: "smooth" });
+  if (!success) {
+    console.warn("Không thể chuyển tới trang:", page);
+  }
+}
+```
+
+### Các ưu điểm nổi bật của `goToPage`:
+- **`pageNumber` bắt đầu từ 1** (1-based).
+- **Tự động chờ layout hoàn tất**: Tự đợi layout engine tính toán và DOM mount xong trước khi scroll, giải quyết triệt để lỗi scroll hụt khi vừa mở tài liệu.
+- **Tự scroll đúng container Kindy**: Cuộn chính xác thanh cuộn `.ked-app` của editor, không làm lệch hay cuộn trang web bên ngoài của host.
+- **Tự clamp trang**: Nếu số trang truyền vào vượt quá tổng số trang tài liệu (ví dụ trang 10 nhưng tài liệu chỉ có 4 trang), editor tự động cuộn đến trang cuối cùng.
+- **Kiểm tra hợp lệ an toàn**: Trả về `false` nếu `pageNumber` không hợp lệ (`<= 0`, `NaN`, chuỗi không phải số).
+- **Hoạt động đa nền tảng & đa chế độ**: Hoạt động hoàn hảo trong mọi chế độ (`view`, `comment`, `edit`), chế độ toàn màn hình (fullscreen) cũng như giao diện thu gọn trên điện thoại di động (mobile).
+
+---
+
+## 12. Lịch sử Cập nhật (Update Log)
+
+* **v3.2.5**:
+  - ✅ **Bổ sung `goToPage(pageNumber, options)`**: Hỗ trợ cuộn mượt hoặc tức thì tới trang chỉ định theo tham số `?page=N` từ URL khi quét mã QR, tự động chờ layout render và tự clamp trang.
 * **v3.2.4**:
   - ✅ **Tự động sinh `?page=N` (`autoPageParam`)**: Chỉ cần truyền URL gốc (ví dụ: `https://my-hospital.vn/verify/{docId}`), thư viện sẽ tự động phân tích và sinh thêm `?page=1`, `?page=2`... cho từng trang. Tự động dùng `&page=N` nếu URL đã có sẵn tham số.
   - ✅ **Chuẩn hóa URL Parameter**: Đổi từ `?page={page}/{totalPages}` sang chuẩn web `?page={page}` (ví dụ: `?page=1`, `?page=2`).

package/docs/security-review.md

@@ -0,0 +1,26 @@
+# Security review — editor hardening
+
+**Reviewed:** 2026-10-09  
+**Scope:** editor repository changes based on `c1aef59f`, covering signature demo DOM rendering, host table mutation permissions and input limits, DOCX archive import, QR configuration logging, and JavaScript development/build dependencies. This is a scoped code review, not a penetration test or product-wide compliance assessment.
+
+## Changes made
+
+- Signature metadata from imported documents is written with DOM `textContent`; the demo's dynamic log messages are text nodes. Fixed placeholder HTML was replaced with DOM construction as well.
+- Host table mutation remains available in normal edit mode. It is off in view/comment modes and turns off when `editContent: false` unless the host explicitly enables `hostTableMutation`. Hosts still need to authorize users and documents at their own trusted boundary.
+- Host table APIs reject over-budget tables and replacements before allocating new cells: 10,000 rows, 256 columns, 50,000 cells, 1,000,000 text characters, 100,000 characters or 1,024 paragraphs per cell, 20,000 paragraphs, and 8 nested table levels.
+- DOCX import rejects archives over 64 MiB compressed, more than 4,096 entries, an entry over 32 MiB expanded, or more than 128 MiB expanded in total. The file/Blob size is checked before reading it into memory.
+- QR configuration values are no longer printed to the developer console. `.env*` files are ignored, with `.env.example` permitted.
+- Updated Vite to 6.4.4, Vitest to 4.1.11, and Vue to 3.5.43. A workspace override keeps VitePress and its Vite plugins on Vite 6.4.4, which meets their published peer ranges.
+
+## Verification
+
+- Focused regression/security tests: **PASS**, 36 tests across table mutation, permissions, DOCX archive limits, and signature rendering, using Vitest 4.1.11.
+- Production library build: **PASS**, Vite 6.4.4.
+- Production dependency audit (`npm audit --omit=dev`): **PASS**, 0 reported findings.
+- Typecheck: **FAIL**. The repository has existing errors in demo/test fixtures, including model shape mismatches and stale editor APIs. This scoped change also revealed no retained `defaultReviewAccessCan` missing-import error; full typecheck remains blocked by the listed broader issues.
+- `npm audit`: **12 findings remain**: 4 high, 2 moderate, and 6 low. High findings are in the `patch-package` → `find-yarn-workspace-root` → `micromatch`/`braces` install tooling chain; npm offers only a major downgrade to patch-package 6.0.7. Remaining moderate findings are `pbkdf2` and `qs`; remaining low findings are in the `vite-plugin-node-polyfills`/`node-stdlib-browser` compatibility chain, whose npm fix also requires a major downgrade. These were not changed automatically because doing so would alter the patch workflow or browser polyfill support. Review and replace these toolchain components before production release if their install/build risk is unacceptable.
+- Secret-pattern scan: **PASS for the checked patterns only** across tracked files and this reviewed change (0 matches); it does not prove the entire Git history is free of secrets.
+
+## Remaining limits and risk
+
+This review does not verify server authentication/authorization, hosting headers/CSP, CORS, CSRF, production secrets, external API rate limits, or runtime behavior in every host integration. The DOCX byte budgets bound archive expansion; malformed files and parser complexity still need normal failure handling. No browser exploit exercise or complete Git-history secrets scan was run.

package/docs/table-editing.md

@@ -26,7 +26,105 @@ Vì vậy thao tác chèn/xóa hàng hoặc cột, merge/unmerge và undo đều
 
 Mọi structural command là một transaction duy nhất, nên Undo/Redo không để lại bảng ở trạng thái trung gian.
 
-## API tích hợp
+## Thao tác bảng từ Host Application trong View Mode (`mode: "view"`)
+
+Khi ứng dụng chạy ở chế độ xem (`mode: "view"`), người dùng **không thể click hoặc chỉnh sửa canvas trực tiếp**. Toolbar, thanh hover rail và context menu chỉnh sửa hoàn toàn bị khóa.
+
+Trong `edit` mode, các thao tác bảng sẵn có được bật như trước. Nếu đặt `editContent: false`, thao tác bảng từ host sẽ tự tắt trừ khi ứng dụng cấp rõ ràng `hostTableMutation: true` sau khi xác thực actor và tài liệu tại lớp host/backend. Trong `view`/`comment` mode, quyền này mặc định tắt:
+
+```ts
+const editor = new KindyEditor({
+  container: document.getElementById("editor"),
+  mode: "view",
+  permissions: {
+    hostTableMutation: true,
+  },
+});
+```
+
+Các giới hạn để tránh payload làm nghẽn giao diện: tối đa 10.000 hàng đầu vào, 256 cột mỗi hàng, 50.000 ô trong bảng sau khi thay thế, 1.000.000 ký tự tổng, 100.000 ký tự và 1.024 đoạn trong một ô, 20.000 paragraph và 8 tầng bảng lồng. API trả `false` khi vượt giới hạn; bảng giữ nguyên.
+
+### Các API thao tác bảng từ Host
+
+#### 1. Lấy danh sách bảng (`getTables`)
+```ts
+const tables = editor.getTables();
+// [
+//   {
+//     tableId: "table_1",
+//     tablePath: { story: { kind: "body" }, ancestors: [], tableId: "table_1" },
+//     rows: 5,
+//     cols: 3,
+//     header: ["STT", "Tên hàng", "Thành tiền"],
+//     hasMergedCells: false
+//   }
+// ]
+```
+
+#### 2. Thực thi Table Action với selection trực tiếp (`executeHostTableAction`)
+Không cần người dùng click canvas. Host truyền trực tiếp `TableAction` cùng selection:
+
+```ts
+// Thêm 1 dòng dưới dòng index 1
+await editor.executeHostTableAction("insertRowBelow", { tableId: "table_1", row: 1 });
+
+// Thêm 1 cột bên phải cột index 0
+await editor.executeHostTableAction("insertColumnRight", { tableId: "table_1", col: 0 });
+
+// Xóa dòng index 2
+await editor.executeHostTableAction("deleteRow", { tableId: "table_1", row: 2 });
+
+// Merge các ô từ (1, 0) đến (1, 2)
+await editor.executeHostTableAction("mergeCells", {
+  tableId: "table_1",
+  fromRow: 1,
+  toRow: 1,
+  fromCol: 0,
+  toCol: 2
+});
+
+// Xóa bảng
+await editor.executeHostTableAction("deleteTable", "table_1");
+```
+
+Kiểm tra action có khả thi trước khi thực thi:
+```ts
+if (editor.canExecuteHostTableAction("deleteRow", { tableId: "table_1", row: 1 })) {
+  await editor.executeHostTableAction("deleteRow", { tableId: "table_1", row: 1 });
+}
+```
+
+#### 3. Nhập giá trị vào 1 ô (`setTableCellValue`)
+Cập nhật nội dung một ô theo tọa độ `(row, column)`. Tự động giữ nguyên định dạng cell/paragraph (font, kích thước, căn lề, màu sắc) và hỗ trợ xuống dòng:
+
+```ts
+await editor.setTableCellValue("table_1", 1, 2, "250.000 đ");
+```
+
+#### 4. Thay thế nhiều dòng dữ liệu cùng lúc (`replaceTableRows`)
+Cập nhật hàng loạt dòng dữ liệu trong một transaction nguyên tử (atomic update).
+- Tự động giữ format từ dòng mẫu (`sampleRowIndex`).
+- Giữ nguyên header (`headerRows`) và footer (`footerRows`).
+- Tự động sinh ID duy nhất cho cell/paragraph mới.
+- Validate cấu trúc bảng và render canvas đúng một lần.
+
+```ts
+await editor.replaceTableRows(
+  "table_1",
+  [
+    ["1", "Sản phẩm A", "100.000"],
+    ["2", "Sản phẩm B", "200.000"],
+    ["3", "Sản phẩm C", "300.000"],
+  ],
+  {
+    headerRows: 1,      // Giữ nguyên dòng tiêu đề
+    footerRows: 1,      // Giữ nguyên dòng tổng cộng
+    sampleRowIndex: 1,  // Lấy định dạng font/style từ dòng mẫu 1
+  }
+);
+```
+
+## API tương tác canvas thông thường
 
 ```ts
 import type { TablePath, TableSelection } from "kindy-editor";

package/docs/table-form-integration.md

@@ -533,7 +533,98 @@ Thanh công cụ Ribbon của Editor có độ rộng mặc định tương đ
 
 ---
 
-## 10. Trải Nghiệm Trang Demo Trực Quan
+## 10. Thao Tác Table Native Trong View Mode (`mode: "view"`)
+
+Nếu sản phẩm yêu cầu Kindy chạy ở chế độ **View Mode** (người dùng không thể gõ hoặc sửa trực tiếp trên canvas, toolbar/context menu/hover rail bị khóa), FE có thể dùng các API table native tích hợp sẵn:
+
+### 10.1 Cấp quyền `hostTableMutation`
+
+Quyền này mặc định tắt trong `view`/`comment` mode. Ở `edit` mode, thao tác bảng tích hợp vẫn được bật. Nếu đặt `editContent: false`, thao tác bảng từ host tự tắt trừ khi ứng dụng cấp rõ ràng `hostTableMutation: true` sau khi xác thực quyền người dùng và tài liệu. Đây là quyền ngoại lệ ở API client, không thay thế kiểm tra quyền backend.
+
+```ts
+const editor = new KindyEditor({
+  container: document.getElementById("editor-container"),
+  mode: "view",
+  permissions: {
+    hostTableMutation: true, // Cho phép host thao tác bảng trong View Mode
+  },
+});
+```
+
+Giới hạn đầu vào `replaceTableRows`: 10.000 hàng, 256 cột mỗi hàng, tối đa 50.000 ô sau khi thay thế, 1.000.000 ký tự tổng, 100.000 ký tự/1.024 paragraph mỗi ô, tối đa 20.000 paragraph và 8 tầng bảng lồng. API trả `false` nếu vượt ngưỡng và không ghi thay đổi.
+
+### 10.2 Lấy danh sách bảng (`editor.getTables()`)
+
+```ts
+const tables = editor.getTables();
+// tables[0] -> {
+//   tableId: "tbl_invoice",
+//   rows: 4,
+//   cols: 5,
+//   header: ["STT", "Mã", "Tên dịch vụ", "Số lượng", "Đơn giá"],
+//   hasMergedCells: false
+// }
+```
+
+### 10.3 Cập nhật giá trị ô (`editor.setTableCellValue()`)
+
+```ts
+// Cập nhật ô dòng 1, cột 2 (0-indexed)
+await editor.setTableCellValue("tbl_invoice", 1, 2, "Khám tổng quát");
+```
+
+### 10.4 Thay thế nhiều dòng dữ liệu một lần (`editor.replaceTableRows()`)
+
+Cập nhật hàng loạt dòng dữ liệu trong một transaction nguyên tử:
+- Giữ nguyên số dòng header (`headerRows`) và footer (`footerRows`).
+- Giữ format font, shading, border từ dòng mẫu (`sampleRowIndex`).
+- Tự động sinh ID hợp lệ duy nhất cho từng cell và paragraph.
+- Validate bảng và render canvas đúng một lần.
+
+```ts
+const rowsFromForm = [
+  ["1", "DV01", "Siêu âm màu", "1", "150.000"],
+  ["2", "DV02", "Xét nghiệm máu", "1", "200.000"],
+  ["3", "DV03", "Chụp X-quang", "2", "300.000"],
+];
+
+await editor.replaceTableRows("tbl_invoice", rowsFromForm, {
+  headerRows: 1,
+  footerRows: 1,
+  sampleRowIndex: 1,
+});
+```
+
+### 10.5 Chạy Table Action từ FE (`editor.executeHostTableAction()`)
+
+Tái sử dụng toàn bộ 9 Table Action mà không phụ thuộc con trỏ chuột:
+
+```ts
+// Thêm 1 dòng dưới dòng 1
+await editor.executeHostTableAction("insertRowBelow", { tableId: "tbl_invoice", row: 1 });
+
+// Thêm cột bên phải cột 2
+await editor.executeHostTableAction("insertColumnRight", { tableId: "tbl_invoice", col: 2 });
+
+// Xóa dòng 3
+await editor.executeHostTableAction("deleteRow", { tableId: "tbl_invoice", row: 3 });
+
+// Merge ô từ dòng 1 cột 0 đến dòng 1 cột 2
+await editor.executeHostTableAction("mergeCells", {
+  tableId: "tbl_invoice",
+  fromRow: 1,
+  toRow: 1,
+  fromCol: 0,
+  toCol: 2,
+});
+
+// Xóa bảng
+await editor.executeHostTableAction("deleteTable", "tbl_invoice");
+```
+
+---
+
+## 11. Trải Nghiệm Trang Demo Trực Quan
 
 Kindy Editor cung cấp sẵn trang demo tương tác đầy đủ các tính năng trên:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kindy-editor",
-  "version": "3.2.5",
+  "version": "3.2.7",
   "type": "module",
   "description": "Trình soạn thảo tài liệu Word chính xác, vẽ bằng canvas",
   "license": "MIT",
@@ -59,10 +59,10 @@
     "fontkit": "^2.0.4",
     "pdfkit": "^0.19.0",
     "txml": "^6.0.0",
-    "vite": "^6.0.0",
-    "vite-plugin-node-polyfills": "^0.28.0",
-    "vitest": "^3.0.0",
     "typescript": "^5.9.2",
-    "vue": "^3.5.29"
+    "vite": "^6.4.4",
+    "vite-plugin-node-polyfills": "^0.28.0",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.43"
   }
-}
+}

package/types/import.d.ts

@@ -10,6 +10,13 @@ export type { Document } from "./model";
 
 export type ImportPhase = "unzip" | "styles" | "parse" | "map";
 
+export type ImportErrorCode = "NOT_ZIP" | "ENCRYPTED" | "NO_DOCUMENT_PART" | "MALFORMED_XML" | "ARCHIVE_LIMIT";
+
+/** Error raised when a DOCX is malformed, encrypted, missing its main part, or exceeds safe import limits. */
+export declare class ImportError extends Error {
+  readonly code: ImportErrorCode;
+}
+
 /** A lossy-mapping decision — surfaced, not swallowed (deduplicated by code). */
 export interface ImportWarning {
   code: string;