# 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 [#try-it]

You need a collaboration room that SuperDoc editors join, and the [Node.js SDK](/agents/automation/node-sdk).

### 1. Give each editor an actor id [#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:

```ts
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 [#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:

```ts
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:

```bash
OBSERVER_TOKEN=... COLLAB_URL=wss://collab.example.com DOCUMENT_ID=contract-123 npx tsx print-changes.ts
```

Each 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 [#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](/editor/collaboration/copy-records-to-your-own-store) 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](/editor/collaboration/read-authorship-on-your-server) if it does not run an observer. |
| Trust the author              | Copies a claim into the room and onto records. Never verifies it.                                    | [Verifies claims](/editor/collaboration/verify-claims) and stores the result.                            |
| Timeline, replay and restore  | Not provided.                                                                                        | Builds them from stored records and snapshots.                                                           |

## What a record holds [#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):

```json
{
  "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](/editor/track-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. `actor` is the client that wrote the most content, and `contributors` lists every client that wrote content.
* `unknown`: no actor id is available.

## What each change describes [#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 [#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`:

```json
{ "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 [#set-an-identity]

* Browser: set `user.id` in the `SuperDoc` configuration, next to `name` and `email`.
* SDKs: pass `userId` in the `doc.open` request, next to `userName` and `userEmail`.
* CLI: pass `--user-id` to `open`.

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](/editor/collaboration/verify-claims).

## Read records in the browser [#read-records-in-the-browser]

Every `changes` operation returns a promise:

```ts
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 [#which-sessions-record]

* A session in a collaboration room records its own edits and the edits it receives. `changes.list` reports `collaboration: 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.

> **Records are a window, not a store (warning)**
>
> Each session keeps 1,000 records or 8 MiB, whichever comes first. The size counts captured updates. The oldest
> records are dropped first, and `truncated: true` tells you records you asked for are gone. In the browser, set
> `changes: { retainRecords, retainBytes }` to change the limits. In an SDK, pass `changesRetainRecords` and
> `changesRetainBytes` to `doc.open`. A session also sees only the edits made while it is connected.


## Limits [#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.declared` comes 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](/editor/collaboration/read-authorship-on-your-server#remove-stale-keys).
* Edits from SuperDoc versions without change records have no author. See [Rooms with older SuperDoc versions](/editor/collaboration/read-authorship-on-your-server#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 [#next-steps]

* [Copy records to your own store](/editor/collaboration/copy-records-to-your-own-store) with an observer.
* [Read authorship on your own server](/editor/collaboration/read-authorship-on-your-server) without running SuperDoc there.
* [Verify claims](/editor/collaboration/verify-claims) so you can trust who a record names.
* Read the [Document API reference](/document-api/reference) for every `changes` operation.
