myrole-docx-editor 0.1.4 → 0.1.5

package/README.md

@@ -189,3 +189,32 @@ const { pages } = await renderDocx(url, hiddenDiv)   // HTMLCanvasElement[]
 
 `pnpm build` writes `dist/` (ESM, one chunk per entry, types) and packs the
 fonts. CI publishes on a `v*` tag; see `.gitlab-ci.yml` at the repository root.
+
+## Exclusive editing
+
+An optional `lock` adapter supplies `acquire(sessionId)`, `renew(sessionId)`,
+`release(sessionId)` and `read(sessionId)`. Acquire and renew return
+`{ acquired: true, ttlMs }` or `{ acquired: false, owner?: string }`. Read returns
+fresh `Uint8Array` document bytes after acquisition. Configure one adapter per
+document and remount the editor when the document identity changes.
+
+```tsx
+<DocxEditor
+  src={initialDocument}
+  lock={documentLockAdapter}
+  onSave={(bytes, {lockId}) => saveWithVerifiedLock(bytes, lockId)}
+  onLockState={state => console.log(state.status)}
+/>
+```
+
+The SDK stays read-only until ownership is confirmed, renews the lease, retries
+occupied sessions and suspends editing on connection loss or expiration. The
+server must reject every write without a valid lease; a `409` error thrown from
+`onSave` also suspends editing. The banner identifies the blocking user, offers
+retry and finishes the session with save-before-release. Unsaved changes survive
+a lost lease in the open editor and can be downloaded for recovery.
+
+`editor.lock` exposes `state()`, `acquire()` and `release()` (or is `null` when
+locking is disabled). `destroy()` attempts final saving and release; the server
+must expire abandoned sessions because browser shutdown is not reliable.
+Read-only viewers acquire nothing. React exports `DOCX_LOCKING_VERSION = 1`.