kindy-editor 1.0.1 → 2.0.0

package/docs/getting-started.md

@@ -0,0 +1,180 @@
+# Bắt đầu với Kindy Document Library SDK v2
+
+Tài liệu này tạo một workspace DOCX chạy bằng Memory adapter, sau đó chuyển sang REST adapter.
+
+## 1. Yêu cầu môi trường
+
+- Node.js `^20.19.0` hoặc `>=22.12.0`.
+- Vue `^3.5.0` khi dùng UI.
+- Trình duyệt hiện đại có `fetch`, `AbortController`, Web Worker và `structuredClone` hoặc JSON fallback.
+
+## 2. Cài package
+
+```bash
+npm install kindy-editor vue
+```
+
+Import stylesheet một lần tại entry của ứng dụng:
+
+```ts
+import 'kindy-editor/style'
+```
+
+Container của workspace phải có chiều cao xác định:
+
+```css
+html, body, #app { height: 100%; margin: 0; }
+.document-screen { height: 100vh; }
+```
+
+## 3. Demo bằng Memory adapter
+
+```vue
+<template>
+  <div class="document-screen">
+    <KindyDocumentLibrary
+      :adapter="adapter"
+      :autosave="{ enabled: true, delay: 1500 }"
+      locale="vi-VN"
+      @error="console.error"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import {
+  KindyDocumentLibrary,
+  createMemoryDocumentAdapter,
+} from 'kindy-editor'
+import 'kindy-editor/style'
+
+const adapter = createMemoryDocumentAdapter({
+  folders: [
+    { id: 'contracts', name: 'Hợp đồng', parentId: null },
+    { id: 'forms', name: 'Biểu mẫu', parentId: null },
+  ],
+})
+</script>
+```
+
+Từ giao diện, chọn **Tạo mới**, nhập nội dung, chờ autosave hoặc nhấn **Lưu** để tạo version bền vững trong adapter.
+
+Memory adapter không dùng `localStorage`; reload trang sẽ mất dữ liệu.
+
+## 4. Kết nối REST backend
+
+Đổi adapter mà không thay UI:
+
+```ts
+import { createRestDocumentAdapter } from 'kindy-editor'
+
+const adapter = createRestDocumentAdapter({
+  baseUrl: '/api/document-library',
+  transport: async (url, init) => {
+    const token = await getAccessToken()
+    return fetch(url, {
+      ...init,
+      credentials: 'include',
+      headers: {
+        ...init?.headers,
+        Authorization: `Bearer ${token}`,
+      },
+    })
+  },
+})
+```
+
+SDK không giữ token. Backend phải kiểm tra quyền trên từng document, version và artifact; `capabilities` chỉ điều khiển UI.
+
+Các endpoint và schema nằm trong [`../openapi/document-api.yaml`](../openapi/document-api.yaml).
+
+## 5. Seed document và template
+
+`MemoryDocumentAdapter` nhận `DocumentSnapshot[]` để test tích hợp:
+
+```ts
+import {
+  createEmptyDocumentState,
+  createMemoryDocumentAdapter,
+} from 'kindy-editor'
+
+const state = createEmptyDocumentState({
+  content: {
+    type: 'doc',
+    content: [{
+      type: 'paragraph',
+      content: [{ type: 'text', text: 'Nội dung mẫu' }],
+    }],
+  },
+})
+
+const adapter = createMemoryDocumentAdapter({
+  documents: [{
+    document: {
+      id: 'template-1',
+      title: 'Mẫu hợp đồng',
+      fileName: 'mau-hop-dong.docx',
+      isTemplate: true,
+      currentRevisionId: 'rev-1',
+      currentVersionId: 'version-1',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      capabilities: { view: true, edit: false },
+    },
+    state,
+    revisionId: 'rev-1',
+    version: {
+      id: 'version-1',
+      documentId: 'template-1',
+      number: 1,
+      revisionId: 'rev-1',
+      reason: 'template',
+      createdAt: new Date().toISOString(),
+    },
+  }],
+})
+```
+
+## 6. Lấy workspace handle
+
+```vue
+<KindyDocumentLibrary ref="workspace" :adapter="adapter" />
+```
+
+```ts
+const state = workspace.value.getState()
+await workspace.value.save()
+
+const result = await workspace.value.exportDocx({
+  mode: 'strict',
+  store: true,
+})
+
+workspace.value.print()
+workspace.value.toggleExplorer(false)
+workspace.value.toggleVersions(true)
+```
+
+Các method công khai đầy đủ nằm trong [API reference](./api-reference.md).
+
+## 7. Kiểm tra integration tối thiểu
+
+Trước khi nối backend thật, kiểm tra tuần tự:
+
+1. Explorer tải được document, folder và template.
+2. Create/import trả document rồi `loadState` mở được snapshot.
+3. Gõ nội dung làm phát `changed` và autosave gọi `saveState`.
+4. Manual save tạo version và VersionPanel làm mới.
+5. Mở version phải read-only; quay lại bản hiện hành phải editable.
+6. Restore tạo revision/version mới, không sửa bytes của version cũ.
+7. Export tạo ZIP/OOXML hợp lệ; print mở được print dialog.
+8. Hai client lưu cùng `baseRevisionId` phải khiến client thứ hai nhận `VERSION_CONFLICT`.
+
+Với DOCX thực tế, kiểm tra thêm `CompatibilityReport`: floating image sẽ được làm phẳng thành inline; EMF/WMF/TIFF không thuộc profile render ổn định. Sections/header/footer dùng `docxProfile="kindy-docx-v2.1"`; comments/Track Changes dùng v2.2. Xem ma trận hỗ trợ trước khi bật strict profile cao hơn.
+
+## 8. Bước tiếp theo
+
+- [UI engine](./ui-engine.md)
+- [Backend và security](../GUIDE.md)
+- [DOCX compatibility](../CAPABILITIES.md)
+- [Performance](./performance.md)

package/docs/performance.md

@@ -0,0 +1,149 @@
+# Hiệu năng và tài liệu dài
+
+## Trạng thái v2.0
+
+Kindy v2.0 import DOCX trong Web Worker, nhưng editing surface vẫn là một ProseMirror instance liên tục. Toàn bộ node của document được gắn vào DOM. Automatic pagination chạy sau debounce, cache chiều cao theo DOM node và chỉ invalid block thuộc vùng transaction; `ResizeObserver` và font loading sẽ invalid cache khi layout thật sự đổi.
+
+Vì vậy thư viện chưa cam kết mọi tài liệu 100–200 trang luôn mượt. Độ phức tạp phụ thuộc số node, bảng, ảnh, comment và tracked change nhiều hơn số trang hiển thị.
+
+## Chi phí chính
+
+1. **Mount editor:** ProseMirror tạo DOM cho toàn bộ document.
+2. **Pagination:** lần đầu phải đo tất cả top-level block. Các lần sau vẫn duyệt block metadata O(N), nhưng chỉ đọc layout DOM cho block mới/thay đổi. Engine chừa đúng khoảng trắng còn lại, lề dưới, page gap và lề trên trước block của trang kế tiếp.
+3. **Review UI:** suggestions cần thu thập tracked change trong document.
+4. **Autosave:** workspace gom update trong `stateSyncDelay` (mặc định 300ms), sau đó canonical state được clone và serialize để gửi adapter. Autosave mặc định của client là 30 giây; ứng dụng không nên đặt chu kỳ 1–2 giây cho tài liệu dài.
+5. **Ảnh/bảng:** ảnh editor dùng `loading="lazy"`; import giới hạn mặc định 20MB mỗi media và 100MB tổng media trước khi chuyển thành data URL. Decoding ảnh và layout bảng vẫn có thể tạo long task trên main thread. Bảng cao hơn một trang được giữ liên tục trong editing surface; engine đếm page span nhưng không tách DOM table thành nhiều ProseMirror node.
+
+Module `VirtualScroller` trong codebase là performance primitive, chưa được nối trực tiếp vào editable ProseMirror DOM. Không nên gỡ các node ngoài viewport một cách cơ học vì sẽ phá selection, IME, history, decoration và mapping transaction.
+
+## Ngân sách khuyến nghị
+
+Đây là mục tiêu nghiệm thu cho hệ thống tích hợp, không phải số liệu Kindy hiện đã bảo đảm:
+
+| Chỉ số | Mục tiêu đề xuất |
+|---|---:|
+| Mở JSON 100 trang text cơ bản | ≤ 3 giây trên máy chuẩn dự án |
+| Import DOCX 100 trang | ≤ 8 giây, UI không treo liên tục |
+| Typing latency p95 | ≤ 50 ms |
+| Pagination sau khi dừng gõ | ≤ 500 ms |
+| Autosave không chặn input | Không có long task > 100 ms do save |
+| Scroll | Không có blank page/nhảy layout nghiêm trọng |
+| Peak memory | Đặt theo corpus và thiết bị mục tiêu |
+
+Máy chuẩn, browser version, font và dataset phải được ghi trong báo cáo benchmark.
+
+## Corpus test
+
+Tối thiểu cần năm nhóm fixture:
+
+- 100 trang text/heading/list.
+- 100 trang có bảng hợp đồng và merge cell.
+- 100 trang có ảnh/logo/con dấu.
+- 100 trang có comment/Track Changes.
+- 200 trang mixed content để stress test.
+
+Mỗi fixture cần đo:
+
+```text
+importStart → importComplete
+openStart → editorReady
+firstInput → nextPaint
+transaction → paginationComplete
+changed → saveStarted → saved
+heapBefore → heapAfterOpen → heapAfterClose
+```
+
+Không dùng một paragraph cực dài thay cho tài liệu thật; pagination hiện tính theo top-level block nên fixture phải có cấu trúc tương tự hợp đồng thực tế.
+
+## Cách chạy kiểm thử
+
+Repository hiện có regression/unit test:
+
+```bash
+npm test
+npm run test:e2e
+npm run typecheck
+npm run build
+npm run benchmark:long-doc
+npm run benchmark:ci
+```
+
+`benchmark:ci` áp synthetic budget và ghi `.artifacts/long-document.json`.
+`test:e2e` build demo production, chạy Chromium cho luồng workspace và ghi
+`.artifacts/browser-performance-text.json` cùng
+`.artifacts/browser-performance-mixed.json`. Workflow CI upload các file này
+làm regression artifact; Node benchmark không được dùng thay DOM/paint benchmark.
+
+Mở benchmark UI bằng:
+
+```text
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=200
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100&benchmarkVariant=table
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100&benchmarkVariant=image
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100&benchmarkVariant=review
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100&benchmarkVariant=mixed
+http://127.0.0.1:9000/kindy-editor?benchmarkPages=100&benchmarkVariant=section
+```
+
+### Baseline cục bộ ngày 22/08/2026
+
+Production preview, Google Chrome 151, MacBook Pro Apple M2 8-core/24GB,
+viewport 1600×1000, 40 input samples, autosave tắt trong benchmark:
+
+| Corpus | Top-level block | Bảng | Ảnh | Editor ready | Typing median | Typing p95 | Typing max | Pagination cached | Kết quả budget |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 100 trang text | 999 | 0 | 0 | 490,3 ms | 12,2 ms | 21,5 ms | 26,7 ms | 2,8 ms | Pass ≤ 3s / 50ms |
+| 100 trang mixed | 1.101 | 50 | 100 | 849,7 ms | 29,2 ms | 36,5 ms | 89,9 ms | 3,7 ms | Pass guardrail 75ms |
+
+Mixed có một spike 89,9ms; p95 vẫn 36,5ms và 39 mẫu còn lại chủ yếu dưới 37ms.
+Số liệu JSON được sinh bởi Playwright thay vì chép tay. Baseline development
+bên dưới được giữ để thấy ảnh hưởng của build mode, không dùng làm gate phát hành.
+
+Corpus text semantic, Chromium trong Codex desktop, Vite development mode:
+
+| Corpus | Top-level block | Editor ready | Typing median | Typing p95 | Pagination cached |
+|---|---:|---:|---:|---:|---:|
+| 100 trang | 999 | 0,59–0,67 s | 18,5 ms | 33,3 ms | khoảng 2,5 ms |
+| 200 trang | 1.999 | 0,90 s | 26,0 ms | 38,9 ms | khoảng 3,4 ms |
+
+Corpus mixed semantic (bảng 4x4 xen kẽ, ảnh inline, comment/Track Changes),
+autosave tắt để phép đo không lẫn network/storage và vẫn chạy bằng Vite development:
+
+| Corpus | Top-level block | Bảng | Ảnh | Editor ready | Typing median | Typing p95 | Pagination cached |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| 100 trang mixed | 1.101 | 50 | 100 | 1,03–1,29 s | 33,0–41,3 ms | 36,1–56,6 ms | khoảng 3,3–5,1 ms |
+| 200 trang mixed | 2.201 | 100 | 200 | 1,39 s | 69,5 ms | 85,1 ms | khoảng 11 ms |
+
+Kết luận hiện tại: production harness xác nhận target 100 trang text và guardrail
+100 trang mixed trên máy chuẩn cục bộ. Kết quả development từng dao động quá 50ms,
+vì vậy không suy rộng thành SLA cho mọi thiết bị. Corpus 200 trang mixed không đạt
+và vẫn là stress limit, không được quảng bá là SLA.
+
+Có spike p99 khoảng 184–391ms trong lần đo này. Kết quả chỉ là baseline text,
+không phải SLA cho DOCX có bảng lớn, ảnh, comment hoặc Track Changes. Benchmark
+Node riêng với fixture hiện tại đo state khoảng 328KB/657KB: clone p95 lần
+lượt khoảng 2,23/4,88ms và stringify p95 khoảng 0,82/2,79ms; đây không bao gồm DOM/paint.
+
+Benchmark trình duyệt nên chạy riêng bằng Chromium cố định trong CI và ghi kết quả JSON artifact. Không đặt threshold quá chặt trên shared CI runner; dùng dedicated runner hoặc so sánh regression theo baseline.
+
+## Hướng tối ưu tiếp theo
+
+Thứ tự ưu tiên:
+
+1. Chuyển bước tính page assignment O(N) sang incremental index sau khi measurement cache đã ổn định.
+2. Cache/index tracked changes và chỉ cập nhật range bị thay đổi.
+3. Chuyển clone/hash/serialization autosave nặng sang Worker khi browser hỗ trợ.
+4. Lazy decode ảnh và giới hạn kích thước ảnh import.
+5. Giảm decoration/node view không cần thiết ngoài viewport.
+6. Chỉ sau khi có benchmark, thiết kế viewport rendering tương thích ProseMirror thay vì dùng virtual scroller prototype trực tiếp.
+
+## Checklist trước production
+
+- Chạy corpus của chính hệ thống tích hợp, không chỉ fixture nhỏ của SDK.
+- Đo cả laptop cấu hình thấp nếu đó là thiết bị người dùng.
+- Cài đúng font tiếng Việt trước khi so layout.
+- Test với DevTools đóng và production build.
+- Test autosave qua mạng có latency/loss thực tế.
+- Test mở/đóng nhiều document để phát hiện listener hoặc DOM leak.
+- Không công bố “hỗ trợ 200 trang” nếu chưa có threshold pass trong CI.

package/docs/plugin-development.md

@@ -0,0 +1,100 @@
+# Mở rộng Kindy Editor v2
+
+V2 không công bố một plugin manager tổng quát. Có ba extension boundary được hỗ trợ: UI composition, editor options/extensions và engine adapter.
+
+## 1. UI composition
+
+Ưu tiên slots và component độc lập:
+
+```vue
+<KindyDocumentLibrary :adapter="adapter">
+  <template #explorer-actions="{ refresh }">
+    <button @click="syncThen(refresh)">Đồng bộ DMS</button>
+  </template>
+
+  <template #topbar="scope">
+    <CompanyDocumentBar v-bind="scope" />
+  </template>
+</KindyDocumentLibrary>
+```
+
+Nếu cần layout hoàn toàn riêng, dùng `KindyDocumentLibraryShell`, `KindyDocumentExplorer`, `KindyEditor` và `KindyVersionPanel` độc lập.
+
+## 2. Tùy biến editor
+
+Truyền option hiện có qua `editorOptions`:
+
+```vue
+<KindyDocumentLibrary
+  :adapter="adapter"
+  :editor-options="{
+    toolbar: companyToolbar,
+    disableExtensions: ['ai'],
+    translations: companyTranslations,
+  }"
+/>
+```
+
+Workspace luôn quản lý các giá trị sau và override option tương ứng:
+
+- `document.title`
+- `document.content`
+- `document.readOnly`
+- `document.autoSave`
+- page state thuộc snapshot
+
+Không tạo storage side effect trong Tiptap extension. Persistence phải đi qua `DocumentApiAdapter` để giữ conflict/version semantics.
+
+## 3. Engine adapter
+
+```ts
+interface EditorEngineAdapter {
+  readonly id: string
+  mount(
+    container: HTMLElement,
+    options?: Record<string, unknown>,
+  ): EditorEngineHandle | Promise<EditorEngineHandle>
+}
+
+interface EditorEngineHandle {
+  load(state: KindyDocumentState): void | Promise<void>
+  getState(): KindyDocumentState
+  setReadOnly(readOnly: boolean): void
+  focus(): void
+  destroy(): void
+  onChange(listener: (state: KindyDocumentState) => void): () => void
+}
+```
+
+V2 chỉ ship `TiptapEngineAdapter`. Adapter riêng phải trả đúng canonical `KindyDocumentState`, không trả HTML làm state dài hạn.
+
+## 4. Adapter nghiệp vụ riêng
+
+Đây là extension boundary chính để nối DMS/CRM/ERP:
+
+```ts
+class CompanyDocumentAdapter implements DocumentApiAdapter {
+  async loadState(documentId, versionId, signal) {
+    const response = await companyApi.load({ documentId, versionId, signal })
+    return mapCompanySnapshot(response)
+  }
+
+  async saveState(documentId, input, signal) {
+    return companyApi.compareAndSave({ documentId, ...input, signal })
+  }
+
+  // Các method còn lại theo contract.
+}
+```
+
+Chạy cùng contract tests dùng cho Memory/REST adapter. Không nuốt `VERSION_CONFLICT`; SDK cần code này để dừng autosave.
+
+## 5. Checklist extension
+
+- Không thêm token hoặc secret vào document state.
+- Không gọi backend trực tiếp từ toolbar action nếu thao tác thuộc document lifecycle; gọi workspace/client/adapter.
+- Extension state phải JSON serializable nếu cần lưu trong document.
+- Mọi event listener phải được tháo khi component/engine destroy.
+- Tác vụ DOCX nặng phải ở Worker khi có thể.
+- Feature DOCX mới chỉ đánh dấu supported sau khi có golden round-trip test.
+- Test read-only, undo/redo, IME tiếng Việt, table selection và 100-page corpus.

package/docs/ui-engine.md

@@ -0,0 +1,242 @@
+# UI engine
+
+UI v2 được chia thành hai lớp: component trình bày và workspace orchestration. Cách chia này giúp ứng dụng chủ có thể dùng trọn bộ UI hoặc lấy từng component mà không làm thay đổi storage contract.
+
+## Thành phần
+
+```text
+KindyDocumentLibrary                  orchestration
+  └─ KindyDocumentLibraryShell       layout engine
+       ├─ KindyDocumentExplorer      document navigation
+       ├─ KindyEditor                editing surface
+       └─ KindyVersionPanel          version navigation
+```
+
+`KindyDocumentLibrary` chịu trách nhiệm mở snapshot, đồng bộ editor state với `DocumentLibraryClient`, autosave, preview/restore và export. `KindyDocumentLibraryShell` chỉ chịu trách nhiệm layout, responsive và slots; shell không gọi API.
+
+## Preset Contract mặc định
+
+Workspace dùng `CONTRACT_EDITOR_OPTIONS` để giữ UI đúng phạm vi soạn hợp đồng:
+
+- Toolbar `classic` compact, khóa một hàng và không hiển thị nút đổi sang ribbon.
+- Chỉ có các nhóm `base`, `insert`, `table`, `page`, `export`.
+- Import DOCX, tải DOCX và In/PDF luôn có ở topbar; nhóm `export` lặp lại ba action này để người dùng tìm thấy ngay trong toolbar.
+- Với workspace, các action file gọi `DocumentLibraryClient`/adapter; không dùng IO trực tiếp của editor để tránh bỏ qua revision, artifact và compatibility report.
+- Chỉ có Page view; Web view bị loại khỏi `page.layouts`.
+- Không load menu Mermaid, diagram, chart, web page, media web, Chinese date hoặc Chinese case.
+- Status bar chỉ giữ bộ đếm `Trang X / Y`, số ký tự, zoom và locale.
+
+Preset là public API và dùng được cho editor độc lập:
+
+```ts
+import {
+  CONTRACT_EDITOR_OPTIONS,
+  createContractEditorOptions,
+} from 'kindy-editor'
+
+const editorOptions = createContractEditorOptions({
+  statusbar: { showLocale: false },
+})
+```
+
+Override được merge theo từng nhóm `toolbar`, `statusbar`, `page`. Nếu truyền `disableExtensions`, mảng của ứng dụng chủ thay thế mảng preset; nhờ đó việc mở rộng UI luôn là quyết định tường minh của host.
+
+## Cấu hình layout
+
+```vue
+<KindyDocumentLibrary
+  :adapter="adapter"
+  :ui="{
+    density: 'comfortable',
+    explorerWidth: '320px',
+    versionsWidth: '300px',
+    showTopbar: true,
+    showExplorer: true,
+    showVersions: true,
+  }"
+/>
+```
+
+```ts
+interface KindyLibraryUiOptions {
+  density: 'compact' | 'comfortable'
+  explorerWidth: string
+  versionsWidth: string
+  showTopbar: boolean
+  showExplorer: boolean
+  showVersions: boolean
+}
+```
+
+Từ `1440px`, workspace mặc định mở đủ ba vùng. Trong khoảng `1025–1439px`, Explorer vẫn mở nhưng Versions mặc định thu gọn để editor/ribbon không bị ép chiều ngang; người dùng mở lại bằng nút lịch sử. Từ `1024px` trở xuống, Explorer và Versions trở thành drawer có scrim; workspace handle hoặc các nút topbar có thể mở/đóng panel.
+
+## Theme tokens
+
+Truyền CSS variables qua prop `theme`:
+
+```ts
+const theme = {
+  '--kindy-library-bg': '#f5f7fb',
+  '--kindy-library-surface': '#ffffff',
+  '--kindy-library-sidebar-bg': '#ffffff',
+  '--kindy-library-text': '#172033',
+  '--kindy-library-muted': '#667085',
+  '--kindy-library-border': '#d0d5dd',
+  '--kindy-library-selection': '#e8f3ff',
+  '--kindy-library-selection-text': '#075985',
+  '--kindy-library-primary': '#0b74de',
+  '--kindy-library-primary-hover': '#095fae',
+  '--kindy-library-danger': '#b42318',
+  '--kindy-library-radius': '10px',
+  '--kindy-library-shadow': '0 18px 48px rgb(15 23 42 / 14%)',
+}
+```
+
+`createLibraryTheme(overrides)` hợp nhất override với token mặc định:
+
+```ts
+import { createLibraryTheme } from 'kindy-editor'
+
+const theme = createLibraryTheme({
+  '--kindy-library-primary': '#7c3aed',
+})
+```
+
+Theme của Library shell độc lập với `theme`/`skin` nội bộ của `KindyEditor`. Truyền cấu hình editor qua `editorOptions`:
+
+```vue
+<KindyDocumentLibrary
+  :adapter="adapter"
+  :editor-options="{
+    theme: 'light',
+    toolbar: { defaultMode: 'classic' },
+    statusbar: { showLocale: true },
+  }"
+/>
+```
+
+Workspace luôn ghi đè `document.content`, `document.readOnly` và tắt autosave legacy của editor để tránh hai autosave pipeline chạy đồng thời.
+
+## Page canvas và điều hướng trang
+
+Ở layout `page`, editor dùng một ProseMirror surface liên tục và chèn page gap bằng decoration. Page gap không hiển thị nhãn nổi trong nội dung; số trang nằm ở status bar theo dạng `Trang hiện tại / tổng trang`. Người dùng có thể bấm bộ đếm, nhập số trang và nhảy tới block đầu của trang đó. Trang hiện tại được cập nhật theo viewport khi cuộn, kể cả khi trang cuối ngắn hơn chiều cao viewport.
+
+Ảnh DrawingML/VML nằm trong DOCX header được render từ canonical header state. Ảnh banner rộng giữ nguyên tỷ lệ và được lặp lại trong header band của các trang tự động tiếp theo. Pagination sử dụng cùng effective header/footer band với canvas để nội dung trang sau không chồng lên logo hoặc footer. Đây vẫn là browser preview; vị trí line-break tự động có thể khác Word do font metrics.
+
+## Locale và message override
+
+Editor ship locale `vi-VN`, `en-US`, `zh-CN`, `it-IT` và `ru-RU`. `locale` truyền từ ứng dụng chủ được ưu tiên hơn giá trị localStorage cũ; đổi ngôn ngữ trong editor có hiệu lực ngay, không reload trang. Workspace đồng bộ Explorer/topbar/Versions trong cùng lần đổi và phát event `locale-changed`. Library shell dùng message tiếng Việt và fallback English:
+
+```vue
+<KindyDocumentLibrary
+  locale="vi-VN"
+  :messages="{
+    documents: 'Kho văn bản',
+    newDocument: 'Soạn văn bản',
+    downloadDocx: 'Tải bản Word',
+  }"
+/>
+```
+
+Các export liên quan:
+
+```ts
+VI_LIBRARY_MESSAGES
+EN_LIBRARY_MESSAGES
+resolveLibraryMessages(locale, overrides)
+```
+
+`messages` của Library UI không thay toàn bộ locale message của editor toolbar. Toolbar vẫn dùng hệ thống i18n của `KindyEditor`.
+
+## Slots
+
+### Workspace slots
+
+| Slot | Slot props | Mục đích |
+|---|---|---|
+| `topbar` | `document`, `status`, `save` | Thay toàn bộ topbar mặc định |
+| `empty` | — | Empty state khi chưa mở document |
+| `explorer-actions` | `refresh`, `busy` | Thêm action ở Explorer |
+| `document` | `document` | Bổ sung UI cho mỗi document item |
+
+Các slot khác được chuyển tiếp vào `KindyEditor`, ví dụ bubble menu hoặc toolbar slot mà editor hỗ trợ.
+
+```vue
+<KindyDocumentLibrary :adapter="adapter">
+  <template #topbar="{ document, status, save }">
+    <CompanyToolbar
+      :title="document?.title"
+      :status="status"
+      @save="save"
+    />
+  </template>
+
+  <template #explorer-actions="{ refresh }">
+    <button @click="refresh">Đồng bộ</button>
+  </template>
+</KindyDocumentLibrary>
+```
+
+### Dùng shell độc lập
+
+```vue
+<KindyDocumentLibraryShell
+  :explorer-open="explorerOpen"
+  :versions-open="versionsOpen"
+  @close-panels="closeMobileDrawers"
+>
+  <template #explorer><CompanyExplorer /></template>
+  <template #topbar><CompanyToolbar /></template>
+  <CompanyEditor />
+  <template #versions><CompanyVersions /></template>
+</KindyDocumentLibraryShell>
+```
+
+Shell không quản lý state mở panel; component cha là source of truth.
+
+## Workspace handle
+
+```ts
+interface KindyDocumentLibraryHandle {
+  client: DocumentLibraryClient
+  openDocument(document: DocumentSummary): Promise<void>
+  closeDocument(): void
+  save(): Promise<unknown>
+  exportDocx(options?: { mode?, store?, fileName?, preferOriginal? }): Promise<DocxExportResult & { source: 'original' | 'serialized' }>
+  downloadDocx(): Promise<void>
+  importDocument(): void
+  preparePrint(): Promise<unknown>
+  print(): void
+  getState(): KindyDocumentState
+  getEditor(): KindyEditorHandle | null
+  refresh(): Promise<void>
+  toggleExplorer(open?: boolean): void
+  toggleVersions(open?: boolean): void
+}
+```
+
+## Trạng thái UI
+
+Topbar chuẩn hóa các trạng thái:
+
+- `idle`: chưa mở document.
+- `ready`/`saved`: state hiện tại đã đồng bộ.
+- `dirty`: đã thay đổi và đang chờ autosave/manual save.
+- `saving`: adapter đang lưu.
+- `readonly`: document không có quyền edit.
+- `preview`: đang xem một version cũ.
+- `conflict`: backend trả `VERSION_CONFLICT`.
+- `error`: lỗi import/load/save/export khác.
+
+Preview version dùng editor read-only và không thay `DocumentLibraryClient.current`. Nút “Quay lại bản hiện hành” phục hồi live snapshot; restore mới thay live snapshot và tạo version mới qua adapter.
+
+## Accessibility
+
+- Explorer, workspace và VersionPanel có landmark/ARIA label riêng.
+- Loading dùng `aria-busy` và `role=status`.
+- Error dùng `role=alert` và có retry.
+- Active document dùng `aria-current=page`.
+- Nút icon có accessible name.
+- Animation spinner tuân theo `prefers-reduced-motion`.
+
+Ứng dụng chủ vẫn phải kiểm tra keyboard navigation và contrast sau khi override theme.