Live updates between tabs

Multiple tabs or workspace window views open on the same document stay in step through Server-Sent Events on /_/sync and through the local authority’s live-data rooms. For how ClayJS connects to these streams in the browser, see the live sync plugin and Live sync and collaboration.

Subscribe to /_/sync#

Tabs subscribe to a document’s event stream with GET /_/sync:

GET /_/sync?document-url=http://localhost:4321/index.html
GET /_/sync?document-url=http://localhost:4321/index.html&lane=saved

• Two lanes:
  • live (the default when lane is omitted): Carries pre-strip DOM snapshots between edit-mode tabs.
  • saved (lane=saved): Carries post-strip on-disk HTML to view-mode tabs after a save or a viewer broadcast.
• Stream lifecycle: The Server-Sent Events response opens with : connected and writes a keep-alive comment every 30 seconds.

Publish to /_/sync#

An edit-mode tab broadcasts changes to peers with POST /_/sync:

POST /_/sync
Content-Type: application/json
Document-URL: http://localhost:4321/index.html

{"snapshot": "<!DOCTYPE html>...", "sender": "tab-1"}

• Artifacts and fields:
  • snapshot: Sent to other edit-mode tabs on the live lane.
  • document: Sent to view-mode tabs on the saved lane.
  • sender: Echoed to subscribers so the sending tab can ignore its own broadcast.
  • identityMap: Forwarded to peers so receiving tabs pair elements across a DOM morph without losing focus or in-progress typing.
  • etag: Forwarded on the editor (live) lane so another edit tab can adopt the file stamp together with the snapshot that stamp describes. The viewer (saved) lane drops etag because view-mode tabs hold a whole rendered document and do not make conditional saves.
• Credential stripping: Any save-token attributes on the opening <html> tag (and any documentetag stamp) are stripped on the live-sync relay so credentials are never handed to another tab.
• Body size limit: Maximum POST body size is 10 MB.
• Legacy routes and field names: GET /_/live-sync/stream and POST /_/live-sync/save are aliases for the same handlers. The server also accepts html as the older spelling of snapshot, and page-url as the older spelling of document-url.

Live-data rooms#

In addition to whole-document snapshot broadcasts, each served folder runs a local authority that advertises "live-data" and "live-provenance" on GET /_/meta:

• Live values: Live-data saves, state reads, room streams, and per-client receipts are served locally. Live values up to 5 MB are accepted, and a value larger than a stream frame is fetched in its own request.
• Room lifecycle and moves: Open live rooms follow their documents across folder moves and renames. When the last editor leaves a room, Hyperclay Local saves the room’s accepted state to the file on disk (retrying transient failures and never recreating a document that was deleted meanwhile), and flushes open rooms before a folder stops or the app quits.

External edits from the Data API or disk#

When a document changes outside the current browser tab, Hyperclay Local coordinates the update through the folder’s write gate:

• Data API and code-view writes: Writes through the Data API, code-view saves, and older copies written to disk merge into the stored page or reach open edit tabs as an external change, protecting any region where someone is actively typing.
• In-page conflict bar: When an incoming edit replaces changes in an open page, the page shows a notice bar (Another edit replaced N changes. / This page changed by someone else | in another tab | by an agent.) with a Review button and options to Download my copy, Revert to mine, or Accept theirs (or Keep mine, Accept theirs, and Yes, drop my edits when a save was refused).
• Disk replacement with unsaved live edits: If an external program on disk replaces or deletes a document while an open room holds unsaved live edits, the file on disk wins and the unsaved edits are written to <folder>/.hyperclay/recovered/<doc>/recovered-<timestamp>.html. You can restore the recovered copy from Version history routes.