RFC: polling is the element's lifetime (htmx 4, #4040)

[manwithacat]

#4040 asks how four should cancel hx-trigger="every …". The 2.x answers were a magic status (286), a cancelled flag, and (in #2576) a header, an event, and cancelPollingOnError. Four dropped all of that: setInterval on the node, clearInterval when the node is gone.

This RFC argues that is not a hole. It is the hypermedia rule, and it should be the canonical 4.x model.

The poll is a representation

htmx’s bet is that HTML is the state. A node with hx-trigger="every 2s" is a poller. A node without it is not. The server does not send a command (“stop polling”). It sends a new representation.

That is the same idea as a link that disappears when the action is no longer available, or a form that is replaced by a confirmation. 286 is the other shape: “keep this element, but change a hidden client flag.” The DOM still looks like a poller. process() would arm it again. A public htmx.cancelPolling() / resumePolling() has the same problem unless it also rewrites the attributes — at which point you have reimplemented a swap.

The 4.x runtime already matches the HTML-as-state story:

spec.interval = setInterval(() => {
    if (elt.isConnected) this.__trigger(elt, 'every', {}, false);
    else clearInterval(spec.interval);
}, …);

__cleanup clears the timer on swap. The polling and progress bar demos already stop by omitting hx-trigger on the morphed element.

What 286 was papering over

innerHTML + every cannot self-stop. The poller is the outer node; innerHTML never replaces it, so isConnected stays true. 286 existed so the server could cancel without changing that node.

Four can say that out loud instead of restoring a status code:

• The swap that stops a poll must replace the poller (outerHTML / outerMorph, or HX-Reswap: outerHTML when the request would otherwise innerHTML).
• Pause / resume are the same: markup without the trigger, then markup with it.
• Unchanged bodies are hx-ptag / 304, not cancel.
• Hidden tabs are a filter ([document.visibilityState === 'visible']), not cancel. The interval lives; the request does not.
• High-frequency updates are SSE/WS. every is the fallback heartbeat, not a faster poll.

We had to learn this the slow way

We maintain a server-rendered app on htmx 4. When 286 became a silent no-op, polls that used to stop just… did not. The fix was not a JS API. It was the progress-bar pattern applied on the server: return the polling element without every, with HX-Reswap: outerHTML when the request was innerHTML. SSE for the live path, every as the heartbeat. That is already in the demos. It was not written down as the rule, so 2.x muscle memory (return 286) kept shipping.

Proposed 4.x answers to #4040

Question	Proposal
Honor 286?	No, not in core. If 2.x compat needs it, htmx-2-compat or an extension.
htmx.cancelPolling(elt)?	No. The markup is the state.
Permanent vs resume?	Resume is a representation that has every again.
every 1s for 60s?	Interesting (Michael sketched this on #2576). A client bound, not a cancel protocol. Separate from this RFC.

Evidence in the draft PR

Tests that pin current four-dev (no core behavior change):

• 286 does not stop every
• innerHTML keeps the poller, so every continues
• outerHTML without every stops
• HX-Reswap: outerHTML of a triggerless copy stops an innerHTML poller

Docs, what’s-new, upgrade-check (flag 286 next to poll/hx-trigger), and the 2→4 skill.

Not proposing merge until this discussion lands. If the room wants 286 back in core, this PR is easy to close.

[manwithacat]

Draft PR (not for merge until this discussion lands): #4049