realtime.sse

Return a selector-safe DOM id or fail with migration guidance.

Stream Server-Sent Events over an ASGI connection.

1. Sendshttp.response.start with text/event-streamheaders.
2. Launches two concurrent tasks:
   • Event producer: consumes the async generator, converts each yielded value to SSE wire format, and sends as ASGI body chunks.
   • Disconnect monitor: awaitshttp.disconnectfrom the client and cancels the producer.
3. Sends periodic heartbeat comments (:) on idle.

captured_context carries the request-scoped state (request, auth user, CSRF token,g, CSP nonce) snapshotted at negotiation time, while the middleware ContextVars were still live. The handlerfinallyresets those vars the instant it returns — before any event is produced here — so they are re-established insideproduce_events(in its own task) for the lifetime of the stream. This keepsget_request(), get_user()/ current_user(), get_csrf_token(), g, and the live CSP nonce working identically inside the EventStream generator (mirrors the StreamingResponse drain in sender()).

SSE identity is pinned at connect time: the captured snapshot is fixed for the connection's lifetime. A user logged out or permission-revoked mid-stream keeps the connect-time identity until they reconnect.

Convert a yielded value to SSE wire format.

Dispatch:

• SSEEvent-> encode as-is
• Fragment-> render via kida, then use the selected client envelope
• str-> wrap as data
• dict-> JSON-serialize as data

Return bounded metadata about a formatted SSE event.

Format an error as an SSE event for a failed render.

For targetedFragmentvalues, htmx 2 uses the named event and htmx 4 uses an unnamed partial so the error replaces the specific block in the DOM. This keeps the broken block visible without changing render surfaces.

For other value types, sends a genericerrorevent.