Live editing

VegaStack keeps an open workspace replica per user so navigation is instant and other people's edits show up without a reload. This page explains what you should expect to see.

The realtime loop

Every workspace tab keeps a local replica (in the browser) and one socket to the workspace. When anyone saves, the server emits a lightweight pulse (it carries no data) to every connected tab; each tab then pulls the changed deltas over the access-filtered sync feed and updates its replica. Readers using that data update reactively.

In practice: while you're looking at a page someone else is editing, their changes appear in about a second. Page titles, sidebar renames, new/trashed pages, comments, and table rows all update live the same way.

Instant navigation

Because the replica is already warm, clicking around the sidebar and breadcrumbs renders from local data first — no spinner waiting on the network. The server is still consulted to stay fresh, but the first paint is immediate.

Merges and conflicts

When you and someone else edit the same page body at the same time, VegaStack runs a three-way merge (your draft, the shared base, and the incoming remote version) on the next sync. Non-overlapping changes merge automatically. If the same lines were changed on both sides, the page enters a conflict state and a resolver lets you choose how to combine them — your in-progress edits are never silently overwritten.

While you have unsaved (dirty) edits open, an incoming remote update does not yank your text out from under you: your draft and its merge base are preserved so the eventual merge is correct, and the live refresh is suppressed for that page until you're no longer dirty or the conflict is resolved.

Optimistic structure operations

Renaming, moving, creating, trashing, and restoring pages apply optimistically — the change shows in the UI immediately, then reconciles with the server. If the server rejects it, the change rolls back and a toast explains why. These structure operations are online-only; the menu items are disabled while offline.

Offline

• Body edits keep working offline — your draft is saved to the local replica and pushed when you reconnect (the merge runs on reconnect).
• Reading cached pages works offline; the warm replica serves the body and the sidebar tree.
• Structure operations (create/move/rename/trash) are disabled offline.

Poll interval

The replica polls on a background interval as a backstop to the pulse (the pulse is what makes updates feel instant; the poll catches anything missed). In production this is every ~15 seconds. For local development and end-to-end tests it is overridden to ~1 second via NEXT_PUBLIC_VEGASTACK_SYNC_POLL_MS so tests observe live updates quickly (the value is clamped to a 1-second minimum).