Malleable HTML, drawn

1. One file, two forms

A malleable HTML file exists in two forms. The saved file is the bytes on disk. The open page is the live DOM in an editor's browser. ClayJS turns the file into the page on open, and the page back into a file on save. With the sync plugin, it also merges outside changes into the open page.

ClayJS handles two sets of marked regions:

• Stripped regions are clay="editor-ui", clay="no-save" and clay="no-snapshot". Saving removes them.
• Excluded regions are those three plus clay="freeze". Sync skips them.

A clay="freeze" region in the file is saved with the contents it had when the page loaded.

ClayJS translates every difference between the two forms that it knows about, in both directions. So keep the two forms as close as the app allows, and mark every difference your code adds.

2. How much the two forms differ

Pick the lowest of these four rungs that fits the file. Each rung up moves the two forms further apart and costs you more rules. Gray marks a control saved in the file.

3. Why stripping makes sync harder

An agent edits the file on disk, so its edit arrives in saved form. Its editing attributes are inert, and from rung 3 up it has no toolbar. ClayJS brings the edit into the open page in three steps.

Three cases need care.

• An outside change never updates an excluded region, so rebuild anything inside one yourself.
• An unmarked class or button from boot code is ordinary content. The next save writes it, and an outside change can remove it.
• A viewer's page with sync receives the stripped file, never an editor's open page.

4. The mistakes, drawn

Each of these breaks saving, syncing or privacy without an error.

clay.onSnapshot((root) => {
  const body = root.querySelector("body");
  if (body.style.overflow === "hidden") body.style.removeProperty("overflow");
});

5. Where each piece of state goes

Ask these questions of every element, attribute and variable.

If the file itself must show a derived value, render it into a clay="no-dirty" region. Writing there starts no save. The value reaches the file with the next save of other content, and an outside change replaces it.

6. The smallest rung 2 file

This file is a task list you can add to, rename and reorder. Its controls are in the file and hidden from viewers, which makes it rung 2.

<!DOCTYPE html>
<html lang="en" autosave>
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <style>html:not([editmode="true"]) [show-when\:editmode="true"] { display: none }</style>
</head>
<body>
  <h1 editmode:contenteditable inert-contenteditable="plaintext-only">Tasks</h1>
  <ul id="tasks" sortable="tasks">
    <li data-id="t-1"><span show-when:editmode="true" sortable-handle>↕</span> <span editmode:contenteditable inert-contenteditable="plaintext-only">Write the brief</span></li>
  </ul>
  <button show-when:editmode="true" type="button" data-action="add">Add task</button>
  <template id="task-tpl">
    <li><span show-when:editmode="true" sortable-handle>↕</span> <span editmode:contenteditable contenteditable="plaintext-only">New task</span></li>
  </template>

  <script src="https://clayjs.com/v1/clay.js?plugins=sync,sortable,indicator&exclude=richclay"></script>
  <script src="https://clayjs.com/v1/clay-options.js"></script>
  <script>
    document.addEventListener("click", (event) => {
      if (!event.target.closest('[data-action="add"]') || !clay.isEditMode) return;
      const li = document.getElementById("task-tpl").content.firstElementChild.cloneNode(true);
      li.dataset.id = "t-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
      document.getElementById("tasks").append(li);
    });
  </script>
</body>
</html>

Open the file through your host. Add a task, rename it, drag it above "Write the brief", and wait for the indicator to show saved. Reopen it: there is still one Add task button, and the task keeps its new name and place.

• The record is written in its saved form (inert-contenteditable), so a viewer gets plain text from the first open. The <template> holds the form the open page uses (contenteditable), because a clone is only ever inserted while someone is editing.
• New items come from the template, never from a copy of an item on the page. Each one gets a fresh data-id, built without crypto.randomUUID, which is missing outside a secure context (for example plain http on a public host).
• The click handler checks clay.isEditMode, because hidden buttons are still in a viewer's page.
• sortable="tasks" makes the list draggable by each item's ↕ grip, marked sortable-handle.
• exclude=richclay skips the rich-text editor, because every field here is plain text. indicator shows save status.
• clay-options.js turns each distinct show-when: attribute and value into one CSS rule, in a <style data-name="option-visibility"> tag. A file gets that tag with its first save.
• Without a fallback, a viewer's browser shows the controls of a never-saved file until the script runs. So this file carries one in its own <style> tag. The backslash in show-when\:editmode escapes the colon. Without it, the browser drops the whole rule. The rule is keyed on :not([editmode="true"]), because the saved file has no editmode attribute.

Move to rung 3 only when viewers must receive HTML without the controls. For undo, a filter and a computed summary, study examples/skeleton.html. It renders the filter and summary into clay="editor-ui" and keeps its controls in the file, hidden by mode.

Full reference: the complete guide.