⌁⌁ Chirp

Route functions return values. The framework handles content negotiation based on the type:

return "Hello"                                  # -> 200, text/html
return {"users": [...]}                         # -> 200, application/json
return Template("page.html", title="Home")      # -> 200, rendered via Kida
return Page("search.html", "results", items=x)  # -> Fragment or Template (auto)
return Fragment("page.html", "results", items=x) # -> 200, rendered block
return Stream("dashboard.html", **async_ctx)    # -> 200, streamed HTML
return Suspense("dashboard.html", stats=...)    # -> shell + OOB swaps
return EventStream(generator())                 # -> SSE stream
return hx_redirect("/dashboard")                # -> Location + HX-Redirect
return Response(body=b"...", status=201)         # -> explicit control
return Redirect("/login")                       # -> 302

No make_response(). No jsonify(). The type is the intent.

For htmx-driven form posts or mutations that should trigger a full-page navigation, prefer hx_redirect() so both plain browser and htmx requests follow the redirect correctly.

Kida can render a named block from a template independently, without rendering the whole page:

{# templates/search.html #}
{% extends "base.html" %}

{% block content %}
  <input type="search" hx-get="/search" hx-target="#results" name="q">
  {% block results_list %}
    <div id="results">
      {% for item in results %}
        <div class="result">{{ item.title }}</div>
      {% end %}
    </div>
  {% endblock %}
{% endblock %}

@app.route("/search")
async def search(request: Request):
    results = await db.search(request.query.get("q", ""))
    if request.is_fragment:
        return Fragment("search.html", "results_list", results=results)
    return Template("search.html", results=results)

Full page request renders everything. htmx request renders just the results_list block. Same template, same data, different scope. No separate "partials" directory.

chirp.validation is a small, composable rule library. Validators are plain callables ((str) -> str | None); rules compose into a dict; validate() returns a ValidationResult that's truthy iff the form is clean.

from chirp import Page, ValidationError
from chirp.validation import validate, required, email, max_length

@app.route("/contacts", methods=["POST"])
async def create_contact(request: Request):
    form = await request.form()
    result = validate(form, {
        "name":  [required, max_length(200)],
        "email": [required, email],
    })
    if not result:
        return ValidationError("contacts.html", "form", errors=result.errors, form=form)
    contacts.append(Contact(**result.data))
    return Page("contacts.html", "list", contacts=contacts)

ValidationError returns a 422 with the re-rendered form fragment so htmx swaps the error inline; non-htmx requests get the full page back.

Kida renders template sections as they complete. The browser receives the shell immediately and content fills in progressively:

@app.route("/dashboard")
async def dashboard(request: Request):
    return Stream("dashboard.html",
        header=site_header(),
        stats=await load_stats(),
        activity=await load_activity(),
    )

Push Kida-rendered HTML fragments to the browser in real-time:

@app.route("/notifications")
async def notifications(request: Request):
    async def stream():
        async for event in notification_bus.subscribe(request.user):
            yield Fragment("components/notification.html", event=event)
    return EventStream(stream())

Combined with htmx's SSE support, this enables real-time UI updates with zero client-side JavaScript. The server renders HTML, the browser swaps it in.

No base class. No inheritance. A middleware is anything that matches the protocol:

async def timing(request: Request, next: Next) -> Response:
    start = time.monotonic()
    response = await next(request)
    elapsed = time.monotonic() - start
    return response.with_header("X-Time", f"{elapsed:.3f}")

app.add_middleware(timing)

Built-in middleware: CORS, StaticFiles, HTMLInject, Sessions, SecurityHeaders.

Chirp validates the server-client boundary at startup:

# Prints a contract report and exits non-zero on errors.
app.check()

# Optional strict mode: treat warnings as failures too.
app.check(warnings_as_errors=True)

Every hx-get, hx-post, and action attribute in your templates is checked against the registered route table. Every Fragment and SSE return type is checked against available template blocks. SSE safety checks catch broken sse-connect / sse-swap structures and unsafe inherited target scopes before runtime.

For strict CI:

chirp check myapp:app --warnings-as-errors

Run the app in debug mode:

chirp dev myapp:app

Open the app in a browser and press Ctrl+Shift+D for Chirp DevTools. The drawer shows htmx activity, effective hx-* inheritance, render plans, native Chirp EventStream traces, View Transitions, DOM diffs, and Swap Doctor warnings.

Browser-capable agents can discover and export diagnostics with:

window.ChirpHtmxDebug.help()
window.ChirpHtmxDebug.exportRecordsJson()