diff --git a/.github/workflows/ci-examples.yml b/.github/workflows/ci-examples.yml
index 3c94c34a9c..a7d6e46809 100644
--- a/.github/workflows/ci-examples.yml
+++ b/.github/workflows/ci-examples.yml
@@ -200,7 +200,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- surface: [toolbar, comments]
+ surface: [toolbar, comments, track-changes]
framework: [vanilla]
steps:
- name: Restore workspace
diff --git a/examples/README.md b/examples/README.md
index e45968bfec..89c8d97db4 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -41,6 +41,7 @@ Build your own toolbar, comments sidebar, and review panel against the `superdoc
|---------|------|
| [toolbar/vanilla](./editor/custom-ui/toolbar/vanilla) | [docs](https://docs.superdoc.dev/editor/custom-ui/overview) |
| [comments/vanilla](./editor/custom-ui/comments/vanilla) | [docs](https://docs.superdoc.dev/editor/custom-ui/comments) |
+| [track-changes/vanilla](./editor/custom-ui/track-changes/vanilla) | [docs](https://docs.superdoc.dev/editor/custom-ui/track-changes) |
### Theming
diff --git a/examples/editor/custom-ui/track-changes/vanilla/README.md b/examples/editor/custom-ui/track-changes/vanilla/README.md
new file mode 100644
index 0000000000..0284753c05
--- /dev/null
+++ b/examples/editor/custom-ui/track-changes/vanilla/README.md
@@ -0,0 +1,28 @@
+# Custom UI: vanilla tracked changes
+
+A custom SuperDoc tracked-changes review panel in plain TypeScript. Single file, no framework, copy-paste into your own app.
+
+## What this teaches
+
+- `ui.trackChanges.observe(snapshot => ...)` to render the review list from a single subscription.
+- `ui.trackChanges.accept(id)` / `.reject(id)` for per-change decisions.
+- `ui.trackChanges.acceptAll()` / `.rejectAll()` for bulk decisions.
+- `ui.trackChanges.next()` / `.previous()` / `.scrollTo(id)` for navigation, plus the live `activeId` so the panel highlights the change under the cursor.
+- `ui.document.observe` + `setMode('editing' | 'suggesting')` so the user can toggle between editing normally and recording tracked changes.
+- `ui.createScope()` for lifecycle, plus `ui.destroy()` cascading on tear-down.
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Switch to **Suggest** mode and edit the document. Each insertion or deletion becomes a tracked change in the right-hand panel. Accept and reject decisions round-trip through Word.
+
+The `predev` script builds the local `superdoc` workspace package so type imports resolve from `dist/`. From a published `npm` install this step is unnecessary.
+
+## See also
+
+- Docs: [Custom UI > Track changes](https://docs.superdoc.dev/editor/custom-ui/track-changes)
+- Sibling examples: [`toolbar/vanilla`](../../toolbar/vanilla), [`comments/vanilla`](../../comments/vanilla)
diff --git a/examples/editor/custom-ui/track-changes/vanilla/index.html b/examples/editor/custom-ui/track-changes/vanilla/index.html
new file mode 100644
index 0000000000..507432ed46
--- /dev/null
+++ b/examples/editor/custom-ui/track-changes/vanilla/index.html
@@ -0,0 +1,29 @@
+
+
+
+
+
+ SuperDoc Custom UI: vanilla tracked changes
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/examples/editor/custom-ui/track-changes/vanilla/package.json b/examples/editor/custom-ui/track-changes/vanilla/package.json
new file mode 100644
index 0000000000..b0a86a05b2
--- /dev/null
+++ b/examples/editor/custom-ui/track-changes/vanilla/package.json
@@ -0,0 +1,18 @@
+{
+ "name": "@superdoc-examples/custom-ui-track-changes-vanilla",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "predev": "pnpm --filter superdoc build",
+ "dev": "vite",
+ "build": "tsc --noEmit && vite build",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "superdoc": "workspace:*"
+ },
+ "devDependencies": {
+ "typescript": "catalog:",
+ "vite": "catalog:"
+ }
+}
diff --git a/examples/editor/custom-ui/track-changes/vanilla/public/test_file.docx b/examples/editor/custom-ui/track-changes/vanilla/public/test_file.docx
new file mode 100644
index 0000000000..b1b8c8f5a7
Binary files /dev/null and b/examples/editor/custom-ui/track-changes/vanilla/public/test_file.docx differ
diff --git a/examples/editor/custom-ui/track-changes/vanilla/src/main.ts b/examples/editor/custom-ui/track-changes/vanilla/src/main.ts
new file mode 100644
index 0000000000..57cf47ad94
--- /dev/null
+++ b/examples/editor/custom-ui/track-changes/vanilla/src/main.ts
@@ -0,0 +1,140 @@
+/**
+ * Custom tracked-changes review panel (vanilla TypeScript), single file.
+ *
+ * Patterns to notice:
+ *
+ * - `ui.trackChanges.observe(snapshot => ...)` drives the panel
+ * list AND the bulk-action enable state from one subscription.
+ * The snapshot carries `items`, `total`, and `activeId`.
+ * - `ui.trackChanges.accept(id) / .reject(id)` resolve one change.
+ * `.acceptAll() / .rejectAll()` are the bulk verbs.
+ * `.next() / .previous() / .scrollTo(id)` drive navigation;
+ * `activeId` reflects whichever change is under the cursor.
+ * - `ui.document.observe + setMode('editing' | 'suggesting')` lets
+ * the user toggle between editing normally and recording each
+ * edit as a tracked change. Without Suggest mode, the panel is
+ * empty by design.
+ * - `ui.createScope()` collects every subscription so the whole
+ * surface tears down cleanly on `ui.destroy()`.
+ *
+ * `trackChanges.replacements: 'independent'` tells the engine to
+ * surface a typed-over selection as two separate review items
+ * (insert + delete) instead of one composite. Matches what most
+ * review UIs want to render.
+ */
+
+import { SuperDoc } from 'superdoc';
+import { createSuperDocUI, type TrackChangesSlice } from 'superdoc/ui';
+import 'superdoc/style.css';
+import './style.css';
+
+const superdoc = new SuperDoc({
+ selector: '#editor',
+ document: '/test_file.docx',
+ documentMode: 'suggesting',
+ user: { name: 'Alex Rivera', email: 'alex@example.com' },
+ modules: { trackChanges: { replacements: 'independent' } },
+});
+
+const ui = createSuperDocUI({ superdoc });
+const scope = ui.createScope();
+
+const modeEl = document.querySelector('#mode-toggle')!;
+const list = document.querySelector('#changes')!;
+const prevBtn = document.querySelector('#prev')!;
+const nextBtn = document.querySelector('#next')!;
+const acceptAllBtn = document.querySelector('#accept-all')!;
+const rejectAllBtn = document.querySelector('#reject-all')!;
+
+// Edit / Suggest toggle. ui.document carries `mode`; setMode flips
+// the routed editor and fires the same `document-mode-change` event
+// the React wrapper consumes.
+modeEl.innerHTML = `
+
+
+`;
+modeEl.addEventListener('click', (e) => {
+ const t = (e.target as HTMLElement).closest('button[data-mode]');
+ if (!t) return;
+ ui.document.setMode(t.dataset.mode as 'editing' | 'suggesting');
+});
+scope.add(
+ ui.document.observe((doc) => {
+ modeEl.querySelectorAll('button[data-mode]').forEach((b) => {
+ b.classList.toggle('active', b.dataset.mode === doc.mode);
+ b.disabled = !doc.ready;
+ });
+ }),
+);
+
+// Bulk action wiring.
+prevBtn.addEventListener('click', () => {
+ const id = ui.trackChanges.previous();
+ if (id) void ui.trackChanges.scrollTo(id);
+});
+nextBtn.addEventListener('click', () => {
+ const id = ui.trackChanges.next();
+ if (id) void ui.trackChanges.scrollTo(id);
+});
+acceptAllBtn.addEventListener('click', () => ui.trackChanges.acceptAll());
+rejectAllBtn.addEventListener('click', () => ui.trackChanges.rejectAll());
+
+// One subscription drives the list AND the bulk-action enable state.
+scope.add(
+ ui.trackChanges.observe((snapshot) => render(snapshot)),
+);
+
+function render(snapshot: TrackChangesSlice): void {
+ const empty = snapshot.items.length === 0;
+ prevBtn.disabled = empty;
+ nextBtn.disabled = empty;
+ acceptAllBtn.disabled = empty;
+ rejectAllBtn.disabled = empty;
+
+ list.innerHTML = '';
+ if (empty) {
+ const li = document.createElement('li');
+ li.className = 'empty';
+ li.textContent = 'No tracked changes. Switch to Suggest mode and edit the document.';
+ list.appendChild(li);
+ return;
+ }
+
+ for (const { id, change } of snapshot.items) {
+ const kind = change.type === 'insert' ? 'insertion' : change.type === 'delete' ? 'deletion' : 'format';
+ const author = change.author ?? change.authorEmail ?? 'Unknown';
+ const li = document.createElement('li');
+ li.className = `card${id === snapshot.activeId ? ' active' : ''}`;
+ li.dataset.id = id;
+ li.innerHTML = `
+ ${kind}
+