SSE Patterns

Overview

Real-time applications mix different update strategies on the same page. A collaborative editor, for example, has a status badge (server-rendered), an editing surface (client-managed), an AI chat (streaming tokens), and CRUD actions (one-shot). Each requires a different approach.

This guide covers the four patterns and when to use each.

Pattern 1: Display-Only Reactive

Use for: status badges, counters, presence lists, dashboards -- any element where the server is the sole rendering authority and the client is a passive display.

# Server: yield Fragment with target matching the sse-swap attribute
async def stream():
    async for change in bus.subscribe(scope):
        yield Fragment("page.html", "status_block",
                       target="status", stats=get_stats())

<!-- Client: sse-swap on a CHILD of sse-connect -->
<div hx-ext="sse"
     sse-connect="/stream"
     hx-disinherit="hx-target hx-swap">
  <span id="status" sse-swap="status">
    {% block status_block %}v{{ stats.version }}{% endblock %}
  </span>
</div>

Key rules:

Fragment.targetbecomes the SSE event name.
sse-swap must be on a child of sse-connect, never the same element.
Addhx-disinherit="hx-target hx-swap" on the sse-connect element to prevent layout-level hx-targetfrom bleeding into SSE swaps.

chirp checkvalidates all three rules at compile time.

Pattern 2: Client-Managed Surfaces

Use for:contenteditableeditors, canvas drawing, drag-and-drop, code editors -- any element where the browser owns the DOM tree.

The browser maintains internal state (cursor position, undo history, selection, paragraph elements) that cannot survive innerHTML replacement. Do not register these blocks in the reactive dependency index.

# Server: return JSON, not rendered HTML
async def post(doc_id: str, request: Request) -> dict:
    edit = parse_edit(await request.json())
    updated = store.apply_edit(edit)
    return {"ok": True, "version": updated.version}

<!-- Client: no sse-swap, no reactive rendering -->
<div class="editor"
     id="editor"
     contenteditable="true"
     data-doc-id="{{ doc.id }}"
     data-version="{{ doc.version }}"
>{{ doc.content }}</div>

# Dependency index: editor block is NOT registered
index._path_to_blocks["doc.version"] = [status_block]  # display-only
index._path_to_blocks["doc.title"] = [title_block]      # display-only
# doc.content is NOT mapped -- editor is client-managed

For multi-user collaboration, send OT/CRDT operations over SSE as JSON (via SSEEvent) and apply them client-side. Do not re-render HTML.

Pattern 3: Streaming Append

Use for: AI chat tokens, live logs, activity feeds -- content that arrives incrementally and appends to a container.

This pattern has two phases: a POST that returns scaffolding, and an SSE stream that fills it in.

Phase 1 -- POST returns the scaffolding:

async def post(doc_id: str, request: Request) -> Fragment:
    form = await request.form()
    message = form["message"]
    return Fragment("_chat.html", "chat_start",
                    doc_id=doc_id, user_content=message)

{# Phase 1: POST response -- user bubble + AI bubble with SSE #}
{% block chat_start %}
<div class="msg msg-user">{{ user_content }}</div>
<div class="msg msg-ai"
     hx-ext="sse"
     sse-connect="/doc/{{ doc_id }}/chat/stream"
     sse-close="done">
  <span class="tokens" sse-swap="fragment" hx-swap="beforeend"></span>
  <span class="typing-cursor"></span>
</div>
{% endblock %}

Phase 2 -- SSE streams tokens:

def get(doc_id: str) -> EventStream:
    async def generate():
        async for token in ai_session.stream_reply():
            yield Fragment("_chat.html", "chat_token", token=token)
        yield SSEEvent(event="done", data="complete")
    return EventStream(generate())

{# Phase 2: each token #}
{%- block chat_token -%}
{%- if token is defined %}{{ token }}{% end -%}
{%- end -%}

Key rules:

sse-swap is on the inner <span>, not the sse-connectdiv.
hx-swap="beforeend"appends tokens instead of replacing.
sse-close="done"closes the connection when streaming finishes.
TheFragment.target defaults to "fragment"when not set.

Pattern 4: One-Shot Mutations

Use for: form submissions, delete buttons, rename actions -- requests that produce a single response and are done.

async def post(doc_id: str, request: Request) -> Action:
    store.rename(doc_id, title=(await request.form())["title"])
    return Action(trigger="renamed")

Chirp provides several return types for this pattern:

Return Type	Behavior
`Action()`	204 No Content -- side effect only, no swap
`Action(trigger="event")`	204 +`HX-Trigger`header
`Fragment(...)`	Render a block, swap into the target
`OOB(main, *oob)`	Primary swap + out-of-band fragment swaps
`ValidationError(...)`	422 + re-rendered form with errors

Mixing Patterns on One Page

Most pages combine multiple patterns. The key principle: establish scope boundaries so patterns don't interfere with each other.

<body hx-boost="true" hx-target="#app-content">
  <nav>...</nav>
  <main id="app-content">
    <!-- SSE scope boundary: hx-disinherit prevents
         layout-level hx-target from reaching SSE swaps -->
    <div hx-ext="sse"
         sse-connect="/doc/{{ doc.id }}/stream"
         hx-disinherit="hx-target hx-swap">

      <!-- Pattern 1: display-only reactive -->
      <span id="status" sse-swap="status">v{{ doc.version }}</span>
      <span id="title" sse-swap="title">{{ doc.title }}</span>

      <!-- Pattern 2: client-managed (no sse-swap) -->
      <div id="editor" contenteditable="true">{{ doc.content }}</div>

      <!-- Pattern 4: one-shot mutation (explicit hx-target) -->
      <div class="toolbar" hx-target="#app-content">
        <a href="/documents" hx-push-url="true">Back</a>
      </div>

      <!-- Pattern 3: streaming append (nested SSE) -->
      <div id="chat">
        <form hx-post="/doc/{{ doc.id }}/chat"
              hx-target="#chat-messages"
              hx-swap="beforeend">
          <input name="message">
          <button>Send</button>
        </form>
        <div id="chat-messages"></div>
      </div>
    </div>
  </main>
</body>

Rules for mixing:

SSE containers gethx-disinherit -- isolate SSE swaps from layout targets.
Navigation links restorehx-target -- add hx-target="#app-content"on toolbar/nav containers inside the SSE scope.
Client-managed elements have nosse-swap -- they are invisible to the reactive system.
Nested SSE connections (like chat) putsse-swap on a child, never on the sse-connectelement.

Compile-Time Validation

chirp checkcatches common SSE mistakes:

Check	Severity	What it catches
`sse_self_swap`	ERROR	`sse-swap` on the same element as `sse-connect`
`sse_scope`	WARNING	`sse-connect` inside broad `hx-target` without `hx-disinherit`
`swap_safety`	WARNING	`sse-swap` element inheriting a broad `hx-target`

Runchirp checkduring development to catch these before they become runtime mysteries.