# How Hyperclay works

> See how Hyperclay serves malleable documents at public addresses, switches modes, records versions, and syncs live across tabs.

Source: https://hyperclay.com/docs/how-hyperclay-works/

Every document on Hyperclay is a single `.html` or `.htmlclay` file (up to 8 MB) that contains its own markup, styles, scripts, data, and editing interface. Hyperclay serves that file at a web address, checks whether the person opening it is allowed to edit, records a version whenever a save lands from the browser, and pushes updates live to other open tabs.

For how a malleable document works inside the browser, read [The model](https://clayjs.com/docs/guide/model/) in the ClayJS guide.

## Addresses

Every document in your workspace has a path-based address under your username:

```text
https://<owner-username>.hyperclay.com/<folder-path>/<file-name>
```

If a document is at the root of your workspace, its address is `https://<owner-username>.hyperclay.com/<file-name>`. You can also claim a dedicated subdomain (`https://<subdomain>.hyperclay.com`) in the **Claim or change Hyperclay subdomain** dialog, or connect a [custom domain](https://hyperclay.com/docs/custom-domains/) (`https://<domain>`).

You can check any document's current public link in the **Address** row of its **Info** dialog (which reads **No public address** when the document has none).

What happens when someone opens a document's address depends on who is visiting:

- **Anonymous visitors and edit-link holders**: Opening a public document serves the bare page directly.
- **Signed-in owners, team members, and named collaborators**: Opening the document redirects into the workspace editor (`/_/dashboard/site/<id>`, `/_/team/<team>/dashboard/site/<id>`, or `/_/dashboard/shared/<id>`) so you have your file tree, code editor, and version history alongside the page.
- **Private documents**: Private documents open only for the people you allow (through [share links](https://hyperclay.com/docs/share-links/), [named sharing](https://hyperclay.com/docs/share-with-a-person/), or [teams](https://hyperclay.com/docs/teams/)) and for Hyperclay administrators.

See [Addresses and subdomains](https://hyperclay.com/docs/addresses/) for details on managing URLs and subdomains.

## Edit mode and view mode

A malleable document runs in one of two modes: view mode for visitors and edit mode for editors.

When a document opens in the workspace frame, Hyperclay loads it in view mode, even when you can edit it, so opening a document never changes it. A document you have just created from a template is the exception and opens in edit mode. If someone shares a document with you as a viewer, the workspace can only load it in visitor mode.

When you have edit access, you can switch between modes from the document menu, from the **Edit** switch in the page's top right corner (documents that load the [menu plugin](https://clayjs.com/docs/plugins/menu/)), or with `⌘⇧E` inside the page:

- Click **View as visitor** to hide editing controls and inspect the page as a visitor sees it. Switching out of edit mode saves any pending changes first, and if that save cannot land the page stays in edit mode and tells you why.
- Click **Return to editing** to re-enable edit mode.
- Click **Open in its own tab** (`⌘⇧O`) to open the document outside the workspace frame.

For how ClayJS activates editing controls in edit mode and strips temporary UI before saving, read [Edit mode and view mode](https://clayjs.com/docs/guide/edit-mode/) in the ClayJS guide.

## Saving and version history

When you change a document in edit mode, ClayJS sends the updated HTML back to Hyperclay. The workspace status indicator shows **Saving…** while the request is in flight and clears once the save is committed.

Every browser save whose HTML changed writes a backup version before committing the new file:

- The document's **Versions** panel lists the latest 50 versions (`Showing the latest 50 versions.`), with columns for when each version was **Recorded** and who it was **Recorded by**.
- Click **View** on any version to inspect it, then click **Restore** (and confirm with **Restore version** in the **Restore version of `<name>`** dialog) to replace the current document with that saved version. Restoring always saves a backup of the current document first.
- Saves made from [Hyperclay Local](https://hyperclaylocal.com/docs/) or through the [Sync API](https://hyperclay.com/docs/sync-api/) write to the document without creating browser version entries.

If the file changed on the server while you had unsaved edits, Hyperclay catches the conflict rather than overwriting newer changes (`Conflicting changes`). A document saved by a newer ClayJS can carry a block editor format marker (`<meta name="clay-blockeditor-format">`). Hyperclay then refuses saves from an older editor that could not read everything in it (`This document uses a newer page format; update the editor to keep writing.`), so an old tab cannot drop content it does not understand. Your unsaved edits stay in that tab. In the code editor, a conflict banner tells you whether the file was saved from another tab, by someone else, or on the server, and lets you choose **Load their version**, **Keep editing**, or **Save over theirs**.

See [Version history](https://hyperclay.com/docs/version-history/) and [Saving](https://clayjs.com/docs/guide/saving/).

## Live sync across tabs

Every open document subscribes to a live channel (`GET /_/sync`) for that document.

When a save finishes on the server, Hyperclay broadcasts the saved HTML to every other open tab of the same document. ClayJS merges the incoming changes into the open DOM in place without reloading the page, keeping each person's scroll position and cursor placement intact.

In the workspace header, a presence strip (**In this document now**) shows the avatars of everyone currently in the document and marks who **can edit**. See [Presence and comments](https://hyperclay.com/docs/presence-and-comments/) and [Live sync and collaboration](https://clayjs.com/docs/guide/live-sync/).

## Sync keys

A sync key (`hcsk_…`) gives desktop apps and scripts authenticated access to your workspace over the [Sync API](https://hyperclay.com/docs/sync-api/).

To create or manage sync keys:

1. Open the **My account** menu and click **Generate sync key…**.
2. In the **Generate sync key** dialog, generate a new key and click **Copy key**.
3. Save the key somewhere safe. Hyperclay shows the full key only once when you generate it and removes it when you close the dialog.

Generating a sync key requires an active paid plan (**Personal** or **Maker**), or an editor role on a team with a **Maker** plan. Each key expires one year after creation.

With a valid sync key, [Hyperclay Local](https://hyperclaylocal.com/docs/) or an external script can list, read, create, write, rename, move, delete, and restore files, and subscribe to your account's live change stream (`/_/sync/stream`), as well as sync any team workspaces where you are an owner or editor (`/_/team/<username>/sync`).

The **Generate sync key** dialog lists your **Active** keys and **History** (with **Key**, **Created**, **Last used**, and **Expires** columns). Click **Revoke key** on any active key to disconnect devices using that key without replacing your other keys.
