signal_globals

Template globals for thesignal()primitive.

Request-aware globals, registered at freeze only when signals exist, emit client-tier markup from the frozen htmx manifest. Htmx 2 usessse-swapand sse-connect. The exact htmx 4 preview uses stable data-chirp-signal sinks and one native hx-sse:connect.

Legacy behavior:

signal(name)— an SSR-seeded scalar sink: <span sse-swap="name" hx-target="this">{seed}</span>. The seed is the current rendered value (from the value cache /spec.initial) so there is no empty-then-fill flash; htmx's defaultsse-swap swap is innerHTML.
signal_block(name) — the same, for an HTML fragment, on a <div>.
signal_attrs(name) / signal_bind(name)— the binding attributes only (sse-swap="name" hx-target="this") for an EXISTING element, so a layout's own semantic container (a CSS-grid<section>, a <ul>) becomes a live sink with no injected wrapper. The element keeps rendering its own SSR body; live events innerHTML-swap it. Like signal()/signal_block()it records the topic and is detected by the dead-binding contract via the call-site, so the binding is validated even though the element'ssse-swapis produced at render time. signal_bind is the preferred public name; signal_attrsis retained as an alias.
signal_connect()— the one shared connection wrapper: <div hx-ext="sse" sse-connect="/_chirp/live?topics=..." hx-disinherit="...">. All signal sinks on the page live inside this single wrapper; one connection carries every topic (the RFC's connection-budget win).

Eachsignal() / signal_block()call records the referenced name into a request-scopedContextVar so signal_connect()can scope the stream to the topics actually used on this render. The globals build the seeded element with Markup (already-safe HTML), mirroring alpine_json_config.

realtime.signal_globals

Name	Type	Default	Description
`type`		—
`qualified_name`		—
`element_type`		—
`description`		—
`source_file`		—
`line_number`		—
`is_autodoc`		—
`autodoc_element`		—
`_autodoc_template`		—
`_autodoc_url_path`		—
`_autodoc_page_type`		—
`title`		—
`doc_content_hash`		—

Symbols on this page

function reset_referenced

Start a fresh per-render referenced-set. Returns a reset token.

function restore_referenced

Restore the referenced-set from a priorreset_referenced() token.

function bind_signal_render_path

Bind the page path used for optional prefix-topic merge.

function restore_signal_render_path function _active_registry

Return the active app's signal registry when rendering under a request.

function _connect_query

Build the public/_chirp/livequery from bound topic names only.

function apply_signal_connect

Finalize deferredsignal_connect()placeholders in rendered HTML.

signal_connect()emits a marker element at render time; once every signal() / signal_block() / signal_bind()on the…

function render_with_signal_finalize

Run render with a fresh referenced-set and finalize signal connects.

function set_signal_audience

Bind the session audience key for session-scoped signal SSR + SSE.

function reset_signal_audience function current_signal_audience function make_signal_globals

Build version-aware signal sink and connection globals.

reset_referenced

function

def reset_referenced() -> contextvars.Token[set[str]]

Start a fresh per-render referenced-set. Returns a reset token.

No parameters.

restore_referenced

function

def restore_referenced(token: contextvars.Token[set[str]]) -> None

Restore the referenced-set from a priorreset_referenced() token.

Parameters

Name	Type	Default	Description
`token`	`contextvars.Token[set[str]]`	—

bind_signal_render_path

function

def bind_signal_render_path(path: str) -> contextvars.Token[str]

Bind the page path used for optional prefix-topic merge.

Parameters

Name	Type	Default	Description
`path`	`str`	—

restore_signal_render_path

function

def restore_signal_render_path(token: contextvars.Token[str]) -> None

Parameters

Name	Type	Default	Description
`token`	`contextvars.Token[str]`	—

_active_registry

function

def _active_registry() -> SignalRegistry | None

Return the active app's signal registry when rendering under a request.

No parameters.

_connect_query

function

def _connect_query() -> str

Build the public/_chirp/livequery from bound topic names only.

No parameters.

apply_signal_connect

function

def apply_signal_connect(html: str) -> str

Finalize deferredsignal_connect()placeholders in rendered HTML.

signal_connect()emits a marker element at render time; once every signal() / signal_block() / signal_bind()on the page has recorded its topic, this patches the marker with the scopedsse-connect URL. When no topics were bound, subscribe-all (bare/_chirp/live).

Parameters

Name	Type	Default	Description
`html`	`str`	—

render_with_signal_finalize

function

def render_with_signal_finalize(render: Callable[[], str]) -> str

Run render with a fresh referenced-set and finalize signal connects.

Parameters

Name	Type	Default	Description
`render`	`Callable[[], str]`	—

set_signal_audience

function

def set_signal_audience(audience_key: str) -> contextvars.Token[str]

Bind the session audience key for session-scoped signal SSR + SSE.

Parameters

Name	Type	Default	Description
`audience_key`	`str`	—

reset_signal_audience

function

def reset_signal_audience(token: contextvars.Token[str]) -> None

Parameters

Name	Type	Default	Description
`token`	`contextvars.Token[str]`	—

current_signal_audience

function

def current_signal_audience() -> str

No parameters.

make_signal_globals

function

def make_signal_globals(registry: SignalRegistry, *, htmx4: bool = False) -> dict[str, Any]

Build version-aware signal sink and connection globals.

Parameters

Name	Type	Default	Description
`registry`	`SignalRegistry`	—
`htmx4`	`bool`	`False`

View source · /home/runner/work/chirp/chirp/site/../src/chirp/realtime/signal_globals.py:1