Record who changed what
Read attributed change records from a collaboration room, and learn what your server does to keep them.
SuperDoc turns each edit a session sees into a change record: who made it, when, which paragraph it touched, and what text or formatting changed. You read records through the Document API, in the browser or from the Node.js, Python and Rust SDKs.
Each session keeps only a short window of recent records. SuperDoc does not store history. To keep one, copy records into your own database.
Try it
You need a collaboration room that SuperDoc editors join, and the Node.js SDK.
1. Give each editor an actor id
Records name an author only when the editing session has one. Add user.id to each editor's SuperDoc configuration:
const superdoc = new SuperDoc({
selector: '#editor',
document: { url: '/contract.docx', collaboration },
user: { id: 'alex', name: 'Alex', email: 'alex@example.com' },
});2. Print records from the room
Save this script as print-changes.ts. It joins the room, waits for edits, and prints who made each one:
import { SuperDocClient } from '@superdoc/sdk';
const token = process.env.OBSERVER_TOKEN;
if (!token) throw new Error('Set OBSERVER_TOKEN to a token your collaboration server accepts.');
const client = new SuperDocClient();
try {
await client.connect();
const doc = await client.open(
{
collaboration: {
providerType: 'hocuspocus',
url: process.env.COLLAB_URL ?? 'ws://127.0.0.1:1234',
documentId: process.env.DOCUMENT_ID ?? 'contract-123',
roomMode: 'join',
},
},
{ collaborationAuth: { type: 'token', token } },
);
try {
let cursor: string | null = null;
for (let polls = 0; polls < 10; polls++) {
const result = await doc.changes.list({ ...(cursor ? { after: cursor } : {}), waitMs: 30_000 });
for (const record of result.items) {
const who = record.actor?.id ?? 'unknown';
const when = record.at.declared ?? record.at.observed;
console.log(`${when} ${who} ${record.changes.map((change) => change.kind).join(', ')}`);
}
cursor = result.cursor;
}
} finally {
await doc.close({ discard: true });
}
} finally {
await client.dispose();
}
Run it against your room, then edit the document in a browser:
OBSERVER_TOKEN=... COLLAB_URL=wss://collab.example.com DOCUMENT_ID=contract-123 npx tsx print-changes.tsEach line shows the time, the actor id, and the kinds of change in one record. The script stops after ten polls of up to 30 seconds each.
What SuperDoc does and what your server does
| Job | SuperDoc | Your application or server |
|---|---|---|
| Say who is editing | Publishes the actor id you set into the room, with an optional claim. | Authenticates users, issues tokens and claims, and decides who joins. |
| Turn edits into records | Each session records the edits it sees and keeps the last 1,000 records or 8 MiB. | Runs an observer that copies records out. |
| Keep history | Returns record ids, cursors, snapshots, Yjs state vectors and, on request, each record's Yjs update. | Stores records, ignores duplicate ids, schedules snapshots, and sets retention and backups. |
| Attribute updates on a server | Writes each client's identity and a timestamp into the room's meta map. | Reads those keys if it does not run an observer. |
| Trust the author | Copies a claim into the room and onto records. Never verifies it. | Verifies claims and stores the result. |
| Timeline, replay and restore | Not provided. | Builds them from stored records and snapshots. |
What a record holds
A session produces one record for each Yjs update it applies or sends that changes story content, comments, tracked changes or bookmarks. An update with no change SuperDoc can describe produces no record. This record is one edit by Alex, seen by another session (values are illustrative):
{
"id": "9c1e4b7a2f60d38e5b1a7c42",
"seq": 12,
"revision": "48",
"origin": "remote",
"actor": { "id": "alex", "name": "Alex", "email": "alex@example.com" },
"actorType": "human",
"cause": "user",
"provenance": "declared",
"at": { "declared": "2026-11-05T10:15:02.114Z", "observed": "2026-11-05T10:15:02.391Z" },
"session": { "id": "5b0f2c1e-8d7a-4f3b-9e21-6c4a0d8b7f13", "clientId": 2841734019 },
"changes": [
{
"kind": "text",
"story": { "kind": "story", "storyType": "body" },
"blockId": "p-12",
"range": { "start": 31, "end": 45 },
"inserted": "within 30 days",
"deleted": ""
}
]
}| Field | Meaning |
|---|---|
id | Computed from the Yjs update. Sessions that receive the same update compute the same id. |
seq | Starts at 1 and grows by one for each record in this session. |
revision | The document revision after the change, as doc.info and receipts report it. |
origin | local for edits made in this session, remote for edits from other clients. |
actor | The primary author: { id, name?, email?, claim? }. id is null when the author declared none. |
contributors | The clients that wrote content in the record. Present only when there is more than one. |
actorType | human for supported SuperDoc UI edits, code for public API calls, or null. |
cause | The kind of action: user, api, undo, redo, or null. |
provenance | How the actor was found: authored, declared, relayed or unknown. See below. |
at | declared is the writing client's clock, or null. observed is this session's clock. |
session | id is the writing SuperDoc session, or null. clientId is its Yjs client id. |
changeTag | The changeTag your application passed in the Document API call's options, when there is one. |
changes | What changed. Each entry has a kind: text, format, paragraph, split, merge, move, create, remove, table or sidecar. |
update | The Yjs update behind the record, base64 encoded. Only with includeUpdate: true. |
Suggestions stay tracked changes; a record describes the edit that created, accepted or rejected one.
provenance says where the actor came from:
authored: this session made the edit and has an actor id.declared: another client made the edit, and the actor is that client's declaration in the room.relayed: content from more than one client arrived in one update, for example after a reconnect.actoris the client that wrote the most content, andcontributorslists every client that wrote content.unknown: no actor id is available.
What each change describes
Every change except sidecar names its story: the body ({ kind: 'story', storyType: 'body' }), a header or footer part (storyType: 'headerFooterPart' with refId), a footnote or endnote (storyType: 'footnote' or 'endnote' with noteId), or a text box (storyType: 'textbox' with textboxId).
kind | What it reports |
|---|---|
text | The paragraph's blockId, the range of the inserted text, and the inserted and deleted strings. |
format | A formatted range and its attributes. |
paragraph | Changed paragraph properties, including inlineObjects such as images and fields. |
split | A paragraph split at offset into blockId and tailBlockId. |
merge | mergedBlockId joined into blockId. |
move | A paragraph that changed position, with the paragraph it now follows in afterBlockId. A paragraph rewritten in place is reported as text and paragraph changes, not as a move. |
create | A new paragraph and its text, including paragraphs created by a paste and paragraphs in footnotes and endnotes. |
remove | A removed paragraph and the text it had. |
table | A table's structure changed. tableId is the public table id. detail lists what changed (for example rowsInserted, cellsMerged, width, tableCreated), row, column and cell counts before and after, the affected blockIds, and previousTableId when the table's id changed. |
sidecar | The ids of the comments, tracked changes or bookmarks an edit affected (affects and ids). Tracked formatting and its acceptance also carry a tracked-change sidecar. |
Changing the page settings of the document's last section is reported as a paragraph change on the last body paragraph, with the section's markup in properties.sectPr.
Oversized records
A single record is capped at 64 KiB or the session's retainBytes, whichever is larger. When an edit is bigger, for example a very large paste, the record keeps as much text as fits and adds one more paragraph change with properties.truncated:
{ "truncated": { "omittedCharacters": 182340, "omittedChanges": 0, "update": true } }omittedCharacters and omittedChanges count what was left out. update: true means the record also has no update, even with includeUpdate. The room itself is unaffected; take a snapshot when you need the full state.
Set an identity
- Browser: set
user.idin theSuperDocconfiguration, next tonameandemail. - SDKs: pass
userIdin thedoc.openrequest, next touserNameanduserEmail. - CLI: pass
--user-idtoopen.
SuperDoc never derives an identity from a name, an email, a cursor color or a session id.
Without an actor id, editing, saving and collaboration work as before. Each editing client still writes its two attribution keys into the room's meta map, with actorId: null. Its records carry actor: { id: null } and provenance: 'unknown', and changes.list reports identity: 'missing', so the gap is visible.
To let your server check that an actor id is genuine, attach a signed claim. See Verify claims.
Read records in the browser
Every changes operation returns a promise:
import { SuperDoc, type DocumentCollaborationConfig } from 'superdoc';
import 'superdoc/style.css';
const collaboration = {
providerType: 'hocuspocus',
documentId: 'contract-123',
serverUrl: 'ws://127.0.0.1:1234',
roomMode: 'join',
} satisfies DocumentCollaborationConfig;
const superdoc = new SuperDoc({
selector: '#editor',
document: { url: '/contract.docx', collaboration },
user: { id: 'alex', name: 'Alex', email: 'alex@example.com' },
onReady: async ({ superdoc: ready }) => {
const doc = ready.activeEditor?.doc;
if (!doc) throw new Error('The Document API is not ready.');
const { items, cursor, truncated, identity } = await doc.changes.list({ limit: 50 });
console.log({ count: items.length, cursor, truncated, identity });
const first = items[0];
if (first) {
const record = await doc.changes.get({ id: first.id });
console.log(record?.actor?.id, record?.changes);
}
},
});
const stop = superdoc.ui.document.onChange((change) => {
if (change.cause !== 'remote') return;
for (const record of change.records ?? []) {
console.log(
record.actor?.id ?? 'unknown',
record.changes.map((entry) => entry.kind),
);
}
});
export function stopListening(): void {
stop();
}
| Operation | Returns |
|---|---|
changes.list | Records oldest first, with cursor, truncated, identity and collaboration. |
changes.get | One record by id, or null. |
changes.resolve | The last limit records for a block, following the paragraphs it was split from or merged with, and the lineage of block ids it followed. |
changes.actors | The room's client table: Yjs client id, actor id, name, email, session id, declaration time and claim. |
changes.snapshot | The current revision, cursor, last change id, Yjs state vector, time, and with includeState the full state. |
changes.list accepts after (a cursor), limit (1 to 1,000, default 100), story, blockId, actorId, includeUpdate and waitMs (0 to 30,000). changes.resolve and changes.list({ blockId }) follow splits and merges only through records the session still holds. These are reads. A session with a read-only connection can call them.
superdoc.ui.document.onChange reports a collaborator's edit with cause: 'remote'. That change carries the records behind it in records, oldest first, when the session recorded them. For edits made in this editor, read doc.changes.list.
Which sessions record
- A session in a collaboration room records its own edits and the edits it receives.
changes.listreportscollaboration: true. - A session that is not in a room records its own edits, reports
collaboration: false, and writes no attribution keys. - A session with a read-only connection records the edits it receives and writes nothing to the room.
Limits
These are current limits. Plan your history around them.
- SuperDoc has no history store, no timeline or replay UI, and no restore workflow for a live room. Restoring a room is a workflow your server owns.
- A session records only the edits it sees while connected. If your observer is down, the edits made meanwhile have no records. A snapshot taken when it returns has the room's state, but not who made each edit.
- Records are not authentication. A claim is copied, never verified, and
actorType: 'human'does not prove a person acted. at.declaredcomes from the writing client's clock. For an edit from another client, it is the time of that client's latest timestamp in the room, which can be up to about 10 seconds before the edit.- Edits from a client that was idle for more than 30 days may have no author. See Remove stale keys.
- Edits from SuperDoc versions without change records have no author. See Rooms with older SuperDoc versions.
- Table structure changes inside footnotes and endnotes are left out of records.
- When SuperDoc deletes text in a follow-up transaction while another transaction is finishing, the author's record and its peers' records for that edit can differ.
Next steps
- Copy records to your own store with an observer.
- Read authorship on your own server without running SuperDoc there.
- Verify claims so you can trust who a record names.
- Read the Document API reference for every
changesoperation.