Hypermedia

Every top-level element of a response replaces the element on the page with the same id. A top-level <title> sets the tab title. Nothing else is interpreted -- no swap modes, no client-side targets, no out-of-band markers.

<span id="hm-count">7</span>

# lands on the element with that id.
# Nothing else on the page is touched.

<a href> and <form action method>, intercepted at the document level. Progressive enhancement is structural rather than a rule to remember: the fallback and the enhancement are the same markup.

data-stream="/url" on an element holds a server-sent event stream open for as long as that element is on the page. Every message's data is HTML, applied by the same same-id rule -- so a handler pushes the components it would have rendered for a request, and there is no second vocabulary to learn.

It stays one-way on purpose: this is the server's mouth, never its ear. Actions remain ordinary requests.

s := web.NewStream(w)
for {
    select {
    case <-tick.C:
        s.Send(ctx, Region(n))
    case <-r.Context().Done():
        return
    }
}

A network error, a non-HTML answer or an error status during navigation hands the URL to the browser, which can always render it -- because every control is a real URL. The app cannot get stuck half-swapped.

Click between the pages in the top bar and watch it: the bar is outside the swapped region, so it is not in any response. If a shell flickers, the fragment branch is missing or its root lost its id.

data-action plus data-method on a switch. It is a named field, so it submits itself the way a one-field form would -- and since the browser already moved it, the answer is one word, not the control.

The same optimism, and the other half of it. This switch moves on the click like the one beside it, but the endpoint always refuses -- so no fragment arrives to correct it, and the runtime restores it from the markup the server rendered. Nothing was remembered to do that: defaultChecked is the checked attribute, which is the server's own answer, still sitting in the DOM.

The runtime only gates the request -- the question's wording and its dialog belong to the app. With no hm:confirm listener it falls back to the browser's own confirm, which is what happens here.

• hm.visit(url)navigate
• hm.request(url, opts)everything else
• hm:applieddetail {url, method, pushed, elements, ids}
• hm:confirmcancelable; detail.proceed() sends it
• hm:errora request that could not be applied

Two cases, both load-bearing: the response must arrive on a real navigation (login, register, logout -- iOS Safari drops a session cookie set on a fetch response), or the page's own script already handles that click.

The runtime's listeners are on document and a bundle's are registered later, so without it the runtime wins the race and fires a second request.

Swap modes, client-side targets, out-of-band markers, DOM history snapshots, request queues, an extension system. Back and forward re-fetch instead of restoring a cached DOM: one round trip, and never a stale page.

Offline-first behaviour is not free here: it wants client state, and there is none. Anything genuinely local (a canvas, a text editor, the chat composer) is a page script that marks its controls data-native and owns them.

Optimism is the exception, and only in one shape: a control may move before the answer arrives when putting it back is a re-derivation rather than a remembered undo -- a switch re-read from the markup, a nav tab re-derived from the URL. An optimistic list insert or a mutation queue would need the previous state kept somewhere, which is the client cache this runtime exists without.

A fragment whose id is nowhere on the page is logged loudly rather than silently dropped -- the console is where a wrong id shows up, which is why the id is the contract and not a convention.

The AI chat has its own SSE protocol and its own renderer, and that is settled rather than a gap -- it was converted to data-stream and reverted. A typewriter is display pacing, and replace-by-id cannot express it: replacing an element destroys the node identity the reveal is measured against, partial markdown is not prefix-stable, and a tool chip inside a fragment cannot wait for the text before it to finish typing.

So the rule is cadence. A region that changes when state changes is what data-stream is for; a turn arriving token by token, wanting to be paced, is not.

Nothing is wrong with htmx. This is one file we can read end to end and change in an afternoon, in place of 48KB of someone else's semantics -- and the file is the same across every app of this lineage.