Host compatibility

ClayJS runs in the browser, while a host serves the HTML file and accepts saves. Every ClayJS document works across Hyperclay, HTML Clay, Hyperclay Local, and your own server, and ClayJS discovers which optional features the current host supports at runtime.

A plain static server or a file:// URL can open a document in view mode, and the demo plugin can simulate saving into browser storage, but saving back to the file requires a host that implements POST /_/save.

Feature support by host#

How ClayJS learns what a host supports#

ClayJS never infers host capabilities from the hostname, port, or trial requests. Instead, it reads capabilities from the GET /_/meta discovery endpoint and from attributes the host stamps on <html> when serving the page.

Capability discovery (GET /_/meta)#

When a feature needs to know what the host supports, ClayJS sends a GET request to /_/meta (or /_/meta/{token} when <html savetoken> is present) with the Document-URL header set to window.location.href, cache: "no-store", redirect: "manual", and a 6-second timeout. In visitor draft mode, ClayJS skips discovery and treats the host as a bare core host immediately.

Only a 2xx JSON response with a numeric spec property is accepted as a capability document:

{
  "spec": 1,
  "extensions": ["conditional", "save-history", "sync", "upload", "data-read", "data-write", "wire", "people"],
  "document": {
    "etag": "\"8f02c16e7b4d9a30\"",
    "saveId": "b3f1c8e2-...",
    "upload": { "maxBytes": 26214400 },
    "helpers": [{ "name": "ai-edit", "state": "ready" }],
    "people": { "me": { "id": "u1", "name": "Ada" } }
  }
}

If /_/meta returns 404, a redirect, an HTML error page, or any non-JSON body, ClayJS treats the server as a bare core host ({ spec: null, extensions: [], document: null }) that supports only POST /_/save. Discovery never throws or rejects.

Extension names in extensions#

The page-state resource#

document.pageState.href names the route that returns the page editor’s stored Yjs state for the exact bytes a client accepted. ClayJS asks it only when an accepted save’s own capture cannot prove a checkpoint, and it asks conditionally:

• The request is a GET with If-Match set to the ETag that save carried, Document-URL set to window.location.href, cache: "no-store" and redirect: "manual".
• 428 means no condition was sent, 412 means another version of the document is stored, and 404 means the host keeps no page state for these bytes. Each of them, and every other failure, keeps the journal exactly as it was.
• A 2xx answer carries version at 1, documentId, generation, etag, stateHash and tag. ClayJS accepts it only when the document identity, the generation and the ETag match the ones it accepted, when the digest of the decoded state matches stateHash, and when that state projects to the article the save sent.

{
  "version": 1,
  "documentId": "b3f1c8e2-4d1a-4f8e-9c2b-7a6d5e4f3c21",
  "generation": "9c1f4a7e2b8d4c6f0a3e5d7b9c1f2a4e",
  "etag": "8f02c16e7b4d9a30",
  "stateHash": "5f0c1d8a3b7e94f2c6d05a1e8b3f7c9d2e4a6b8c0d1e3f5a7b9c1d2e3f4a5b6c",
  "tag": "{\"v\":1,\"g\":0,\"y\":{\"seed\":\"...\"}}"
}

Hyperclay and Hyperclay Local answer /_/page-state under the document lock, and HTML Clay answers /_/page-state/{token} for the token in <html savetoken>. Hyperclay names its document row id and HTML Clay the id behind its history key; Hyperclay Local mints no document id at all and answers documentId: null.

Host-injected attributes on <html>#

A host can also stamp three attributes onto the root <html> element when serving a document. ClayJS reads them once at boot and strips all three before every save:

• savetoken: Arms edit mode and sends requests to /_/save/{token}, /_/meta/{token}, and /_/upload/{token}. (If a host sends only the legacy pre-1.9.0 htmlclaytoken attribute, ClayJS logs a warning and keeps edit mode off.)
• documentetag: Seeds the initial ETag stamp for the version of the file that was served.
• sitevisibility: Sets clay.siteVisibility to "private" or "public" (or null when absent).