docs: warn that backgrounded SSE tabs drop events and document resync#1978
Merged
Merged
Conversation
htmx v4's hx-sse:connect enables pauseOnBackground by default, closing the stream while a tab is hidden with no replay, so events broadcast during the hidden window are lost and live views silently go stale (issue #1976). Document the resync-on-reconnect pattern (re-fetch current state on htmx:after:sse:connection), the pauseOnBackground knob, and the per-process buffer_size multi-worker caveat. Also correct the SSE client examples for the htmx 4 model: sse-connect -> hx-sse:connect, and sse-swap is removed (named events dispatch as DOM triggers; unnamed messages auto-swap), across the development guide, htmx migration guide, background-tasks guide, llms-full.txt, the JS README, and the scaffolded template frontend rules. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
davidpoblador
pushed a commit
that referenced
this pull request
Jun 2, 2026
🤖 I have created a release *beep* *boop* --- ## [10.22.4](v10.22.3...v10.22.4) (2026-06-02) ### Bug Fixes * fast-path worker-health to skip CLI bootstrap ([#1974](#1974)) ([#1977](#1977)) ([ee77f6c](ee77f6c)) * load ProjectConfiguration deploy-config from .env ([#1970](#1970)) ([#1971](#1971)) ([13b67a7](13b67a7)) * negotiate Accept-Language with language-only subtag fallback ([#1973](#1973)) ([#1975](#1975)) ([0738181](0738181)) ### Documentation Updates * warn that backgrounded SSE tabs drop events and document resync ([#1978](#1978)) ([6bb1a91](6bb1a91)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1976.
Problem
hx-sse:connectin htmx v4 enablespauseOnBackgroundby default: when a tabis hidden the extension closes the stream, and
sse_endpoint(...)has no replaywithout
buffer_size. Anybroadcast()sent during the hidden window is lostpermanently, so live views silently go stale until the next event or a manual
reload. Nothing in the docs flagged this, and the existing SSE client examples
used
sse-connect/sse-swap, which htmx v4 has deprecated (sse-connect)and removed (
sse-swap).What changed (docs only)
development-guide.md— rewrote the HTMX Integration section to the htmx 4model (named events → DOM triggers consumed via
hx-trigger; unnamed messagesauto-swap). Added a "Backgrounded Tabs Drop Events — Resync on Reconnect"
section with the
pauseOnBackgroundwarning, the resync pattern(
htmx:after:sse:connectiontrigger re-fetches current state on everyreconnect), the
hx-config="sse.pauseOnBackground:false"knob, and abuffer_sizemulti-worker caveat (per-process monotonic IDs can't replayreliably across workers).
htmx-migration.md— corrected the SSE migration section, which wronglyclaimed
sse-connect/sse-swap"work exactly the same" in v4; documented thatsse-swapis removed and there is nohx-sse:swap; added the backgroundingwarning; fixed the troubleshooting note and a dead upstream link.
background-tasks.md— updated the upload-progress example to the v4unnamed-message auto-swap model and cross-linked the resync guidance.
llms-full.txt— mirrored the client example and migration fixes with aconcise warning.
vibetuner-js/README.mdandvibetuner-template/.claude/rules/frontend.md— fixed the remaining deprecated
sse-connect/sse-swapsnippets.Verification
hx-sse.js(
pauseOnBackground: isConnect,reader.cancel()onvisibilitychange,named→
htmx.trigger, unnamed→htmx.swap,htmx:after:sse:connectionon everyreconnect,
sse-swapremoval warning) and against the upstream htmx 4 SSE docs.rumdlpasses on all touched markdown files (via pre-commit).🤖 Generated with Claude Code