# Live updates between tabs

> Keep multiple browser tabs and workspace views in step over Server-Sent Events and live-data rooms.

Source: https://hyperclaylocal.com/docs/live-updates/

Multiple tabs or [workspace window](https://hyperclaylocal.com/docs/guide/workspace/) 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](https://clayjs.com/docs/plugins/live-sync/) and [Live sync and collaboration](https://clayjs.com/docs/guide/live-sync/).

## Subscribe to `/_/sync`

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

```http
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`:

```http
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](https://hyperclaylocal.com/docs/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](https://hyperclaylocal.com/docs/version-history/).