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.

Laravel Posts

The optional Posts backend uses a revision token and a separate publication snapshot. It does not store historical revisions: PostPageStore::listRevisions() returns [], restore requests are rejected, and its save label/trail arguments are not persisted. The in-session editor undo history still works. Add host revision storage if you need durable historical restore or an edit trail after reload.

See Laravel Post Backend.