How sap works

00Overview

What sap is, the mental model, the API surface, and the attribute vocabulary, sourced from the shipped engine (not the spec).

The core mental model

Most reactive tools keep two copies of your data: one in a JS store, one on the page, and spend their lives keeping the two in sync. Sap deletes the second copy. The input's value is the quantity; the list items are the rows. When anything changes, sap reads the page, recomputes, and writes back. One copy, nothing to drift (README.md:23, src/pass.js:1-3).

The main API surface

The attribute vocabulary (what the engine actually accepts)

Sourced from the linter's allow-lists (src/lint.js:11-17) and error registry (src/errors.js), so this is the shipped surface, not the spec's wish-list.

01Transient state

Where the value lives vs. what serializes

The exact mechanism

• Attribute-carried transient — state="secret:transient". parseStateDecl sets transient:true (dom.js:111-115). The value is kept in el._sapTransient; readTransient seeds it from the attribute-or-default once, then calls el.removeAttribute(name) and returns the stored value (dom.js:139-148). writeTransient stores and strips the same way (dom.js:150-153). Intake routes transient decls through readTransient (pass.js:42-45). The state= declaration token itself stays, so the field keeps existing.
• Control-carried transient — <input bind="q" transient>. The carrier's mirror() sees transient and removes value/checked instead of writing them (carrier.js:85-90). Intake also strips them right after reading a transient bound control (pass.js:63-66). The live property is the only store.
• Password mandate. bind on a type=password without transient halts the whole app at mount (E31); type=file always halts (E32) (lint.js:139-144). A file must never carry a cleartext password.
• Mirroring, via one shared serializer. mirror() delegates to serializeControlToAttributes (control-serialize.js, the single source of truth shared with hyperclayjs): text/number/checkbox/radio write their attribute, select writes selected on the chosen option, textarea writes a cursor-safe data-value (carrier.js:89-97). contenteditable/text-leaf need no mirror — they are textContent, saved as-is. mirror runs on a carrier write; a plain typed value is made durable by persist (below).

Durability: persist

sap honors persist natively — no host platform required. On every edit of a [persist] control inside a [sap] root, the engine mirrors the live value to a serializable attribute through the shared serializer (actions.js:240 → control-serialize.js). hyperclayjs honors the same attribute on the platform through that same serializer, so the two agree by construction. (lint.js also allow-lists the host region attributes no-save/no-watch/no-undo.)

A textarea is the one control whose value the browser does not reload from an attribute (it reloads from child text), so its cursor-safe mirror lives in data-value. sap closes that loop on load: when it mounts a root it restores any textarea[data-value] into the textarea's content and strips the attribute (mount.js → rehydrateControlFromAttributes), so a persisted textarea round-trips standalone, no save step required. On the platform the save already finalized it to textContent, so there is nothing left to restore.

sap and hyperclayjs do not fight: both write the same value through the same shared serializer (control-serialize.js), so the writes are idempotent. But never combine transient + persist: their intent is opposite. transient strips the value every pass; persist forces the live value into the saved bytes and wins, leaking exactly what transient promised to drop. On the platform, hyperclayjs's [persist] also deliberately skips hidden, password, and file: a bound hidden input already persists through sap's carrier mirror, and a password must stay transient or sap halts (E31, above).

click the button to dump the live root…

02Rich text editing

The mechanism

• kindOf returns "leaf" for a contenteditable or bound text leaf (carrier.js:16). readBy leaf returns el.textContent; writeBy leaf sets el.textContent = String(v) (carrier.js:46-47, 74-76). A bound editable reads and writes plain text, never innerHTML.
• Text paints write el.textContent with String() coercion (pass.js:297-303). Every carrier write coerces with String(v) (carrier.js:63-79). Values are scalars or arrays of scalars, never DOM fragments.
• A bind on a container with element children halts with E20 ("a write would overwrite its children"), but a contenteditable container with children binds fine because it is treated as a leaf (lint.js:149-153, test/transient-and-codes.test.js:126-138). The editable still reads as textContent, so any inner markup is dropped from state.

Why it is architectural, not lazy

Embedding a real editor (the escape hatch)

"No rich text" is about engine state, not the page. You can embed a real editor — a formatting contenteditable, or Slate / TinyMCE / ProseMirror — by telling sap to leave that subtree alone. The seam is sap-ignore.

• The walk stops. isInert returns true for sap-ignore, so the pass walker never descends into it and sap neither reads nor paints inside (dom.js:14-16,25). The editor's own markup is left exactly as authored; it round-trips because Hyperclay saves the live DOM as-is.
• The linter stops too. A sap-ignore subtree is skipped whole during mount analysis, so foreign markup or a third-party editor's attributes inside it never trip E01 (lint.js:33-35). (A template subtree is still scanned; only sap-ignore is fully exempt.)
• The Notion shape. sap owns the block list (items/item + trigger-add/move:/trigger-remove); each block body is a sap-ignore editor mount. Add, remove, and reorder stay fully reactive; the prose stays rich.

<main sap>
  <ul items="blocks">
    <li item template>
      <input bind="kind">                <!-- block metadata: reactive -->
      <button move:up>↑</button>
      <button trigger-remove>✕</button>
      <div sap-ignore no-undo
           contenteditable="true">…</div> <!-- the real editor: sap never reads this -->
    </li>
    <!-- …authored rows… -->
  </ul>
  <form trigger-add="blocks"><input bind="kind" required></form>
</main>

Three caveats when you embed (all code-grounded)

03Extending sap / plugins

The one extension API (with a working example)

// register a custom format — either form works
Sap.formats.eur = (n) => "€" + Number(n).toFixed(2);
Sap.config({ formats: { gbp: (n) => "£" + Number(n).toFixed(2) } });

// then use it anywhere a built-in format goes
<span text:eur="state.price"></span>

• Format registry: the formats object lives in helpers.js:67-91. applyFormat(name, v) looks it up and throws a tagged E22 for an unknown name, or for a numeric built-in format applied to non-finite input (helpers.js:97-114).
• Registration surface: Sap.formats = formats (sap.js:129) and Sap.config({formats}) which does Object.assign(formats, options.formats) (sap.js:131-134).
• Frozen signature: ["state","item","el","root","fmt","num","sum","count","avg","min","max","plural","days"] (compile.js:6). Custom formats extend the fmt namespace object passed at runtime, never the parameter list, so the source-keyed compile cache never invalidates (compile.js:26-41).

Why it is frozen (the real reason)

sap ✗ E01 foreign-dialect
  at main[sap] > output — x-text="state.total"
  problem: "x-text" is a foreign-dialect attribute; Sap has no x-text directive
  fix: use text="state.x" (Sap paints text only) — or wrap the subtree in sap-ignore if intentional

04All the ways to set state

One recompute path (with its real write-path differences)

A programmatic write to a bound control looks like typing after it hits the carrier, so recompute and platform hooks can observe it through the same event surface. The honest caveats: user typing starts as a native event, attribute-carried state= writes skip synthetic events and schedule directly, row-order writes schedule after moving DOM nodes, and paints write silently.

The complete reference (every mechanism, grounded)

05Modals / showing item details

The mechanism

• The pass parses LIST by KEYEXPR, resolves the list (walking through nested lists, so lists.cards finds a card in any list), evaluates the key and finds the record whose $key matches. A malformed spec or a throwing key expression just hides or closes the container, silently.
• Projection paints write each bound control silently and skip the focused element, so typing is never clobbered.
• Edits route back: an input inside the panel writes through to the source row's field, and Sap(this) inside the panel resolves the projected row, so $remove() and $move() act on the source row.
• A user close (Esc, or a method="dialog" button) clears a plain state.NAME key. With any other key the dialog stays closed until the key changes. An items= list inside a detail= panel is mount error E17.

06Verify it yourself

This page is held to sap's own agent contract (demos.html:1173-1175): every demo mounts sap ✓, Sap.status().ok is true, and there are zero [sap-error] beacons — three of the contract's four clauses (the fourth, an empty Sap.doctor(), is advisory on a teaching page). Run the checks below; they call the real console API on the demos above.

// click "Run page gate" — the verdict appears here and in the devtools console

Note on the editable demo: re-mounting fresh markup leaves the old, now-disconnected root in the internal order array. Sap.refresh() skips disconnected roots (sap.js:120), but Sap.status() still counts them, so after you edit, the app count rises while connected apps stay green. The gate below reports connected apps separately.