- Hyperclay
- Behind the project
- How Hyperclay works
How Hyperclay works
See how Hyperclay serves malleable documents at public addresses, switches modes, records versions, and syncs live across tabs.
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 in the ClayJS guide.
Addresses#
Every document in your workspace has a path-based address under your username:
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://<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, named sharing, or teams) and for Hyperclay administrators.
See Addresses and subdomains 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), 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 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 or through the 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 and 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 and Live sync and collaboration.
Sync keys#
A sync key (hcsk_…) gives desktop apps and scripts authenticated access to your workspace over the Sync API.
To create or manage sync keys:
- Open the My account menu and click Generate sync key….
- In the Generate sync key dialog, generate a new key and click Copy key.
- 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 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.