Revisions and Conflicts

PageConfig._version and BuilderDocument.revision solve different problems.

Value	Meaning
PageConfig._version	Version of the JSON wire format
BuilderDocument.revision	Version of this page's content

Do not use _version as a save counter.

Prevent stale writes

Return a revision when loading or saving a document:

{
  "id": "home",
  "definition": { "sections": [] },
  "revision": "12",
  "capabilities": {}
}

The next save sends that revision. If another session has already created revision 13, reject the stale save instead of silently overwriting it.

Handle a conflict

When createHttpTransport throws RevisionConflictError, the host should:

1. preserve the user's unsaved definition;
2. explain that a newer revision exists;
3. offer a deliberate reload, compare, or retry workflow;
4. avoid replacing local editor state without consent.

Revision history is optional

TransportClient may implement listRevisions and restoreRevision. If it does not, the rest of the editor still works.

Restoring a revision should create or return the new current document according to your backend's history model.

Keep the edit trail with each revision

A save may include label and trail. Store both on the new revision and return them from listRevisions.

The trail lets the Editor explain what changed inside a saved revision after the page is reloaded. Manual changes use small metadata-only entries. Copilot and fill changes also carry a before-and-after snapshot so the exact AI change can be reverted.

See Show and Save the Edit Trail for the save flow and UI wiring.