Mutations
How document mutations persist and fan out to clients.
A mutation is a persistent change to a Mini Agency document. The editor, AI chat, and MCP tools all use the same mutation pipeline so every client sees consistent state.
Persistent writes
Persistent document writes go through the document mutation endpoint or site-scoped server helpers. A successful mutation updates the server document, increments version, schedules or performs persistence, and fans out updates to connected clients.
Local optimistic edits
Some gestures must feel instant. Drag, resize, scrub, color slider, and similar continuous interactions update local editor state while the gesture is active. When the gesture ends, the editor sends one persistent mutation.
This prevents server flooding, SSE churn, undo-history bloat, and collisions with AI or MCP reads.
Sidebar inputs
Text-shaped sidebar inputs keep local draft state and commit on blur, Enter, or unmount. They do not save every keystroke. This protects user input when the selected node changes before blur fires and keeps undo usable.
SSE fan-out
Connected editor clients receive document changes through the document stream. When an MCP tool edits a site, the browser editor should update without a manual refresh. If a client appears stale, check site identity first, then the stream connection.
Undo and version history
Undo is most useful when each user intention creates one mutation. That is why continuous gestures and text inputs commit on boundaries. Version history provides a broader recovery path after larger sequences of changes.