Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Server-sent events keep one long-lived HTTP response open and let the backend push named messages to the browser without polling.

How it works

The browser opens an EventSource connection to the SSE endpoint, and the Semitexa SSE runtime streams text/event-stream frames as backend events arrive. The demo keeps this surface authenticated because a persistent stream is a resource multiplier.

Why it matters

SSE is a pragmatic fit for one-way real-time updates. It uses plain HTTP, works well with browsers, and avoids the extra complexity of WebSockets when the client only needs to receive updates.

Key concepts

EventSource: Browser API for opening an SSE connection over plain HTTP.
text/event-stream: HTTP content type used by the SSE protocol.
long-lived response: A response that stays open so the server can push multiple messages over time.

Server Push

Event stream over plain HTTP

Connect once, then watch the backend push named events from the server into this page without WebSockets or manual refresh.

Authorization is required to open the long-lived SSE stream used by this demo.

HTTP Transport

text/event-stream Content type

EventSource Browser API

Authorization required

Next backend minute tick

-- sec

Authorization is required to open the long-lived SSE stream used by this demo.

Backend events will appear here…

AsyncResourceSseServer SSE_PUBLIC_ANONYMOUS SSE_MAX_CONN_PER_IP SSE_MAX_CONN_GLOBAL SSE_MAX_CONNECTION_AGE_SECONDS

Verified against Semitexa Ultimate 2026.09.19.1020

SSE Stream

Real-time server push without WebSockets — a persistent HTTP connection that streams events. The client opens one EventSource connection and the server sends named events as they occur.

How it works

The SSE endpoint holds an open text/event-stream response. The server pushes named event frames over this connection whenever backend activity produces output. The client JavaScript receives each frame and updates the page without polling or a WebSocket handshake.

Collection feed frames

A collection feed (AbstractSseCollectionFeedHandler) streams a fixed, canonical frame vocabulary — the event names are an allow-list, never a client-controlled string:

ui.collection.data — carries the canonical { data, meta } collection envelope, the same projection the JSON pull mode returns, so the client renders both transports from one code path. Emitted on initial connect, on rehydration, and on Track-R-driven re-runs.
ui.collection.error — collection-level errors on the same stream.

(The legacy ui.grid.data / ui.grid.error frames that carried the v1 UiGridDataResponse shape were removed in the Phase 6 sweep.)

Why this matters

SSE is simpler than WebSockets for unidirectional server-to-client push: plain HTTP and native browser support via EventSource. Semitexa's AsyncResourceSseServer integrates with the event dispatcher so that async and queued listener completions can be streamed to the correct session without the client needing to poll.

Security model

A long-lived SSE connection holds a Swoole coroutine, a file descriptor, and a response handle for as long as the client stays connected. Unbounded public SSE is a DoS vector — an attacker who can open N connections keeps N workers busy. Semitexa treats SSE as a privileged resource.

Defaults:

Authentication is required. /__semitexa_kiss — the single SSE stream endpoint, used by Semitexa's browser-side SSE bootstrap — enforces an authenticated session. An unauthenticated request receives 401 Unauthorized.
Per-IP connection cap. SSE_MAX_CONN_PER_IP (default 5) bounds concurrent streams from a single client. Exceeding the cap returns 429 Too Many Requests with Retry-After: 30.
Per-worker global cap. SSE_MAX_CONN_GLOBAL (default 500) bounds total concurrent streams in one worker. Production deployments should size this against available FD and coroutine budget.
Hard connection age. SSE_MAX_CONNECTION_AGE_SECONDS (default 600) forces the server to send a close event and disconnect after ten minutes. Browser EventSource auto-reconnects; long-lived clients must handle the reconnect path.
Same-origin handshake. The request must carry Origin or Referer and the host must match the server. Requests with neither header present are rejected with 403 Forbidden.

Opt-in anonymous streams. For public-facing streams (dashboards, ticker widgets, etc.) set SSE_PUBLIC_ANONYMOUS=true. Anonymous requests are then allowed, but the connection caps above still apply unchanged.

Client contract

The framework does not replay missed events on reconnect. When a client reconnects after a network drop or after the server hits the age cap, it receives a fresh stream from the server's current state. If your application needs at-least-once delivery semantics, queue events domain-side and re-emit them on reconnect based on the Last-Event-ID header or your own cursor.

Environment variables

Variable	Default	Purpose
`SSE_PUBLIC_ANONYMOUS`	`false`	Allow unauthenticated clients to open `/__semitexa_kiss`.
`SSE_MAX_CONN_PER_IP`	`5`	Concurrent SSE connections allowed from one IP per worker.
`SSE_MAX_CONN_GLOBAL`	`500`	Concurrent SSE connections allowed per worker.
`SSE_MAX_CONNECTION_AGE_SECONDS`	`600`	Seconds before the server force-closes the stream. `0` disables the cap.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Events;67use App\Application\Payload\Events\ActivityStreamPayload;8use App\Application\Resource\Sse\ActivityStreamResource;9use Semitexa\Core\Attribute\AsPayloadHandler;10use Semitexa\Core\Contract\TypedHandlerInterface;1112#[AsPayloadHandler(payload: ActivityStreamPayload::class, resource: ActivityStreamResource::class)]13final class SseStreamHandler implements TypedHandlerInterface14{15    public function handle(ActivityStreamPayload $payload, ActivityStreamResource $resource): ActivityStreamResource16    {17        return $resource->stream('catalog.activity');18    }19}20

<?php

declare(strict_types=1);

namespace App\Application\Handler\Events;

use App\Application\Payload\Events\ActivityStreamPayload;
use App\Application\Resource\Sse\ActivityStreamResource;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ActivityStreamPayload::class, resource: ActivityStreamResource::class)]
final class SseStreamHandler implements TypedHandlerInterface
{
    public function handle(ActivityStreamPayload $payload, ActivityStreamResource $resource): ActivityStreamResource
    {
        return $resource->stream('catalog.activity');
    }
}

1/**2 * SSE Demo — connects to the Semitexa SSE endpoint and renders incoming events.3 */4(function () {5    'use strict';67    const DEFERRED_KISS_MODE = 'deferred_kiss';8    // The producer's stream name, not this widget's streamMode ('standalone' here):9    // SseDemoStreamProducer answers only to 'showcase', and only when APP_DEBUG is on.10    const SHOWCASE_STREAM = 'showcase';1112    function init() {13        const rootEl = document.getElementById('sse-demo');14        const streamMode = rootEl ? (rootEl.getAttribute('data-stream-mode') || 'standalone') : 'standalone';15        const SSE_ENDPOINT = rootEl ? (rootEl.getAttribute('data-sse-endpoint') || '/sse') : '/sse';16        const connectBtn = document.getElementById('sse-connect');17        const disconnectBtn = document.getElementById('sse-disconnect');18        const statusEl = document.getElementById('sse-status');19        const logEl = document.getElementById('sse-event-log');20        const logShellEl = logEl ? logEl.closest('.preview-sse-panel__log-shell') : null;21        const minuteSyncEl = document.getElementById('sse-minute-sync');22        const minuteValueEl = document.getElementById('sse-minute-value');23        const minuteSummaryEl = document.getElementById('sse-minute-summary');2425        if (!statusEl || !logEl || !minuteSyncEl || !minuteValueEl || !minuteSummaryEl) return;2627        const authRequired = rootEl ? rootEl.getAttribute('data-authorization-required') === 'true' : false;28        const isAuthenticated = rootEl ? rootEl.getAttribute('data-is-authenticated') === 'true' : false;29        const authRequiredMessage = rootEl ? (rootEl.getAttribute('data-auth-required-message') || 'Authorization is required.') : 'Authorization is required.';30        const expectedCadenceSeconds = rootEl ? Math.max(1, parseInt(rootEl.getAttribute('data-expected-cadence-seconds') || '60', 10) || 60) : 60;3132        let source = null;33        let currentSessionId = '';34        let countdownTimer = null;35        let deferredSummary = 'Shared kiss stream will stay open. The timer tracks the next scheduled heartbeat broadcast from the backend.';3637        function setDeferredState(summary) {38            deferredSummary = summary;39            minuteSummaryEl.textContent = summary;40        }4142        function setStatus(text, variant) {43            statusEl.innerHTML = '<span class="preview-pill preview-pill--' + variant + '">' + text + '</span>';44        }4546        function appendEvent(name, data) {47            const placeholder = logEl.querySelector('.preview-sse-panel__placeholder');48            if (placeholder) placeholder.remove();4950            const item = document.createElement('li');51            item.className = 'preview-sse-panel__event';52            item.innerHTML =53                '<span class="preview-sse-panel__event-name">' + escHtml(name) + '</span> ' +54                '<span class="preview-sse-panel__event-data">' + escHtml(typeof data === 'string' ? data : JSON.stringify(data)) + '</span>' +55                '<span class="preview-sse-panel__event-time">' + new Date().toLocaleTimeString() + '</span>';5657            logEl.appendChild(item);5859            // Keep at most 20 entries60            while (logEl.children.length > 20) {61                logEl.removeChild(logEl.firstChild);62            }6364            if (logShellEl) {65                logShellEl.scrollTop = logShellEl.scrollHeight;66            }67        }6869        function parseEventData(raw) {70            if (typeof raw !== 'string') {71                return raw;72            }7374            try {75                return JSON.parse(raw);76            } catch (_error) {77                return raw;78            }79        }8081        function formatEventData(data) {82            if (!data || typeof data !== 'object') {83                return typeof data === 'string' ? data : JSON.stringify(data);84            }8586            const prefix = [];87            if (data.source) prefix.push(data.source);88            if (data.level) prefix.push(data.level);8990            const title = data.title ? data.title + ': ' : '';91            const message = data.message || JSON.stringify(data);9293            return (prefix.length ? '[' + prefix.join(' / ') + '] ' : '') + title + message;94        }9596        function createSessionId() {97            return 'demo_sse_' + Math.random().toString(36).slice(2, 10) + '_' + Date.now().toString(36);98        }99100        function secondsUntilNextWindow(intervalSeconds) {101            const intervalMs = intervalSeconds * 1000;102            const remainder = Date.now() % intervalMs;103104            if (remainder === 0) {105                return 0;106            }107108            return Math.ceil((intervalMs - remainder) / 1000);109        }110111        function renderCountdown(seconds) {112            minuteValueEl.textContent = String(seconds).padStart(2, '0');113114            if (source) {115                minuteSummaryEl.textContent = 'The SSE connection is open. The backend will publish the next scheduled event when this counter reaches zero.';116                return;117            }118119            if (authRequired && !isAuthenticated) {120                minuteSummaryEl.textContent = authRequiredMessage;121                return;122            }123124            if (streamMode === DEFERRED_KISS_MODE) {125                minuteValueEl.textContent = String(secondsUntilNextWindow(expectedCadenceSeconds)).padStart(2, '0');126                minuteSummaryEl.textContent = deferredSummary;127                return;128            }129130            minuteSummaryEl.textContent = 'Connect once. The backend will emit a fresh SSE message on every new minute.';131        }132133        function clearCountdown() {134            if (countdownTimer) {135                window.clearInterval(countdownTimer);136                countdownTimer = null;137            }138        }139140        function startCountdownLoop() {141            clearCountdown();142143            const tick = function () {144                renderCountdown(secondsUntilNextWindow(expectedCadenceSeconds));145            };146147            tick();148            countdownTimer = window.setInterval(tick, 250);149        }150151        function openStream() {152            currentSessionId = createSessionId();153            source = new EventSource(154                SSE_ENDPOINT155                + '?session_id=' + encodeURIComponent(currentSessionId)156                + '&demo_stream=' + encodeURIComponent(SHOWCASE_STREAM)157            );158            setStatus('Connecting…', 'warning');159            connectBtn.style.display = 'none';160            disconnectBtn.style.display = '';161162            source.addEventListener('open', function () {163                setStatus('Connected to backend stream', 'active');164                minuteSummaryEl.textContent = 'Live backend SSE connection is open. A new backend message will arrive on every next minute boundary.';165            });166167            source.addEventListener('message', function (e) {168                const payload = parseEventData(e.data);169                appendEvent('message', formatEventData(payload));170            });171172            ['connected', 'resource.updated', 'notification', 'scheduler.tick', 'ping'].forEach(function (eventName) {173                source.addEventListener(eventName, function (e) {174                    const payload = parseEventData(e.data);175                    appendEvent(eventName, formatEventData(payload));176                    if (eventName === 'scheduler.tick') {177                        setStatus('Minute tick received', 'success');178                        minuteSummaryEl.textContent = 'Fresh backend minute tick received. Countdown restarted for the next minute.';179                    }180                });181            });182183            source.addEventListener('error', function () {184                setStatus('Reconnecting…', 'warning');185                minuteSummaryEl.textContent = 'The connection dropped. EventSource is retrying automatically.';186            });187        }188189        function initDeferredKissObserver() {190            setStatus('Waiting for deferred stream', 'warning');191            setDeferredState('Waiting for the deferred runtime to open its shared kiss stream and deliver page blocks.');192193            document.addEventListener('semitexa:deferred:stream', function (e) {194                const detail = e.detail || {};195                const phase = detail.phase || 'update';196197                if (phase === 'connecting') {198                    setStatus('Opening shared kiss stream…', 'warning');199                    setDeferredState('The deferred runtime is opening its shared SSE connection. The countdown tracks the next scheduled heartbeat window.');200                    appendEvent('kiss.connecting', 'Opening __semitexa_kiss for deferred blocks');201                    return;202                }203204                if (phase === 'connected') {205                    setStatus('Shared kiss stream connected', 'active');206                    setDeferredState('The deferred runtime is streaming blocks over its shared kiss connection. The countdown tracks the next scheduled heartbeat window.');207                    appendEvent('kiss.connected', 'Shared __semitexa_kiss connection established');208                    return;209                }210211                if (phase === 'done') {212                    setStatus(detail.live ? 'Deferred stream live' : 'Deferred stream complete', 'success');213                    setDeferredState(detail.live214                        ? 'Initial deferred delivery finished; the shared kiss connection remains open.'215                        : 'Deferred delivery finished and the shared kiss connection closed.');216                    appendEvent('kiss.done', detail.live ? 'Initial blocks delivered, live updates remain enabled' : 'Initial deferred delivery completed');217                    return;218                }219220                if (phase === 'error') {221                    setStatus('Shared kiss stream interrupted', 'warning');222                    setDeferredState('The shared deferred stream dropped; runtime fallback or reconnect logic may take over.');223                    appendEvent('kiss.error', 'The shared __semitexa_kiss connection dropped');224                }225            });226227            document.addEventListener('semitexa:deferred:block', function (e) {228                const detail = e.detail || {};229                if (!detail.slotId) return;230231                if (detail.mode === 'template') {232                    return;233                }234235                if (detail.mode === 'html') {236                    return;237                }238239                if (detail.mode === 'fallback') {240                    return;241                }242            });243244            document.addEventListener('semitexa:deferred:message', function (e) {245                const detail = e.detail || {};246                const payload = detail.payload || {};247                const eventName = detail.eventName || 'message';248249                if (eventName === 'scheduler.tick') {250                    appendEvent(eventName, formatEventData(payload));251                    setStatus('Scheduled heartbeat received', 'success');252                    setDeferredState('A real scheduled backend heartbeat arrived over the shared kiss stream. The countdown restarted for the next scheduler window.');253                    return;254                }255            });256257            if (window.SemitexaSSR && window.SemitexaSSR._connected) {258                setStatus('Shared kiss stream connected', 'active');259                setDeferredState('The deferred runtime already has an open shared kiss stream. The countdown tracks the next scheduled heartbeat window.');260            }261        }262263        function escHtml(str) {264            return String(str)265                .replace(/&/g, '&amp;')266                .replace(/</g, '&lt;')267                .replace(/>/g, '&gt;')268                .replace(/"/g, '&quot;');269        }270271        if (streamMode === DEFERRED_KISS_MODE) {272            initDeferredKissObserver();273        } else {274            if (!connectBtn || !disconnectBtn) return;275276            connectBtn.addEventListener('click', function () {277                if (source || connectBtn.disabled) return;278279                openStream();280            });281282            disconnectBtn.addEventListener('click', function () {283                if (source) {284                    source.close();285                    source = null;286                }287                currentSessionId = '';288                setStatus('Disconnected', 'warning');289                minuteSummaryEl.textContent = 'Connect once. The backend will emit a fresh SSE message on every new minute.';290                connectBtn.style.display = '';291                disconnectBtn.style.display = 'none';292            });293        }294295        startCountdownLoop();296    }297298    if (document.readyState === 'loading') {299        document.addEventListener('DOMContentLoaded', init);300    } else {301        init();302    }303}());304

/**
 * SSE Demo — connects to the Semitexa SSE endpoint and renders incoming events.
 */
(function () {
    'use strict';

    const DEFERRED_KISS_MODE = 'deferred_kiss';
    // The producer's stream name, not this widget's streamMode ('standalone' here):
    // SseDemoStreamProducer answers only to 'showcase', and only when APP_DEBUG is on.
    const SHOWCASE_STREAM = 'showcase';

    function init() {
        const rootEl = document.getElementById('sse-demo');
        const streamMode = rootEl ? (rootEl.getAttribute('data-stream-mode') || 'standalone') : 'standalone';
        const SSE_ENDPOINT = rootEl ? (rootEl.getAttribute('data-sse-endpoint') || '/sse') : '/sse';
        const connectBtn = document.getElementById('sse-connect');
        const disconnectBtn = document.getElementById('sse-disconnect');
        const statusEl = document.getElementById('sse-status');
        const logEl = document.getElementById('sse-event-log');
        const logShellEl = logEl ? logEl.closest('.preview-sse-panel__log-shell') : null;
        const minuteSyncEl = document.getElementById('sse-minute-sync');
        const minuteValueEl = document.getElementById('sse-minute-value');
        const minuteSummaryEl = document.getElementById('sse-minute-summary');

        if (!statusEl || !logEl || !minuteSyncEl || !minuteValueEl || !minuteSummaryEl) return;

        const authRequired = rootEl ? rootEl.getAttribute('data-authorization-required') === 'true' : false;
        const isAuthenticated = rootEl ? rootEl.getAttribute('data-is-authenticated') === 'true' : false;
        const authRequiredMessage = rootEl ? (rootEl.getAttribute('data-auth-required-message') || 'Authorization is required.') : 'Authorization is required.';
        const expectedCadenceSeconds = rootEl ? Math.max(1, parseInt(rootEl.getAttribute('data-expected-cadence-seconds') || '60', 10) || 60) : 60;

        let source = null;
        let currentSessionId = '';
        let countdownTimer = null;
        let deferredSummary = 'Shared kiss stream will stay open. The timer tracks the next scheduled heartbeat broadcast from the backend.';

        function setDeferredState(summary) {
            deferredSummary = summary;
            minuteSummaryEl.textContent = summary;
        }

        function setStatus(text, variant) {
            statusEl.innerHTML = '<span class="preview-pill preview-pill--' + variant + '">' + text + '</span>';
        }

        function appendEvent(name, data) {
            const placeholder = logEl.querySelector('.preview-sse-panel__placeholder');
            if (placeholder) placeholder.remove();

            const item = document.createElement('li');
            item.className = 'preview-sse-panel__event';
            item.innerHTML =
                '<span class="preview-sse-panel__event-name">' + escHtml(name) + '</span> ' +
                '<span class="preview-sse-panel__event-data">' + escHtml(typeof data === 'string' ? data : JSON.stringify(data)) + '</span>' +
                '<span class="preview-sse-panel__event-time">' + new Date().toLocaleTimeString() + '</span>';

            logEl.appendChild(item);

            // Keep at most 20 entries
            while (logEl.children.length > 20) {
                logEl.removeChild(logEl.firstChild);
            }

            if (logShellEl) {
                logShellEl.scrollTop = logShellEl.scrollHeight;
            }
        }

        function parseEventData(raw) {
            if (typeof raw !== 'string') {
                return raw;
            }

            try {
                return JSON.parse(raw);
            } catch (_error) {
                return raw;
            }
        }

        function formatEventData(data) {
            if (!data || typeof data !== 'object') {
                return typeof data === 'string' ? data : JSON.stringify(data);
            }

            const prefix = [];
            if (data.source) prefix.push(data.source);
            if (data.level) prefix.push(data.level);

            const title = data.title ? data.title + ': ' : '';
            const message = data.message || JSON.stringify(data);

            return (prefix.length ? '[' + prefix.join(' / ') + '] ' : '') + title + message;
        }

        function createSessionId() {
            return 'demo_sse_' + Math.random().toString(36).slice(2, 10) + '_' + Date.now().toString(36);
        }

        function secondsUntilNextWindow(intervalSeconds) {
            const intervalMs = intervalSeconds * 1000;
            const remainder = Date.now() % intervalMs;

            if (remainder === 0) {
                return 0;
            }

            return Math.ceil((intervalMs - remainder) / 1000);
        }

        function renderCountdown(seconds) {
            minuteValueEl.textContent = String(seconds).padStart(2, '0');

            if (source) {
                minuteSummaryEl.textContent = 'The SSE connection is open. The backend will publish the next scheduled event when this counter reaches zero.';
                return;
            }

            if (authRequired && !isAuthenticated) {
                minuteSummaryEl.textContent = authRequiredMessage;
                return;
            }

            if (streamMode === DEFERRED_KISS_MODE) {
                minuteValueEl.textContent = String(secondsUntilNextWindow(expectedCadenceSeconds)).padStart(2, '0');
                minuteSummaryEl.textContent = deferredSummary;
                return;
            }

            minuteSummaryEl.textContent = 'Connect once. The backend will emit a fresh SSE message on every new minute.';
        }

        function clearCountdown() {
            if (countdownTimer) {
                window.clearInterval(countdownTimer);
                countdownTimer = null;
            }
        }

        function startCountdownLoop() {
            clearCountdown();

            const tick = function () {
                renderCountdown(secondsUntilNextWindow(expectedCadenceSeconds));
            };

            tick();
            countdownTimer = window.setInterval(tick, 250);
        }

        function openStream() {
            currentSessionId = createSessionId();
            source = new EventSource(
                SSE_ENDPOINT
                + '?session_id=' + encodeURIComponent(currentSessionId)
                + '&demo_stream=' + encodeURIComponent(SHOWCASE_STREAM)
            );
            setStatus('Connecting…', 'warning');
            connectBtn.style.display = 'none';
            disconnectBtn.style.display = '';

            source.addEventListener('open', function () {
                setStatus('Connected to backend stream', 'active');
                minuteSummaryEl.textContent = 'Live backend SSE connection is open. A new backend message will arrive on every next minute boundary.';
            });

            source.addEventListener('message', function (e) {
                const payload = parseEventData(e.data);
                appendEvent('message', formatEventData(payload));
            });

            ['connected', 'resource.updated', 'notification', 'scheduler.tick', 'ping'].forEach(function (eventName) {
                source.addEventListener(eventName, function (e) {
                    const payload = parseEventData(e.data);
                    appendEvent(eventName, formatEventData(payload));
                    if (eventName === 'scheduler.tick') {
                        setStatus('Minute tick received', 'success');
                        minuteSummaryEl.textContent = 'Fresh backend minute tick received. Countdown restarted for the next minute.';
                    }
                });
            });

            source.addEventListener('error', function () {
                setStatus('Reconnecting…', 'warning');
                minuteSummaryEl.textContent = 'The connection dropped. EventSource is retrying automatically.';
            });
        }

        function initDeferredKissObserver() {
            setStatus('Waiting for deferred stream', 'warning');
            setDeferredState('Waiting for the deferred runtime to open its shared kiss stream and deliver page blocks.');

            document.addEventListener('semitexa:deferred:stream', function (e) {
                const detail = e.detail || {};
                const phase = detail.phase || 'update';

                if (phase === 'connecting') {
                    setStatus('Opening shared kiss stream…', 'warning');
                    setDeferredState('The deferred runtime is opening its shared SSE connection. The countdown tracks the next scheduled heartbeat window.');
                    appendEvent('kiss.connecting', 'Opening __semitexa_kiss for deferred blocks');
                    return;
                }

                if (phase === 'connected') {
                    setStatus('Shared kiss stream connected', 'active');
                    setDeferredState('The deferred runtime is streaming blocks over its shared kiss connection. The countdown tracks the next scheduled heartbeat window.');
                    appendEvent('kiss.connected', 'Shared __semitexa_kiss connection established');
                    return;
                }

                if (phase === 'done') {
                    setStatus(detail.live ? 'Deferred stream live' : 'Deferred stream complete', 'success');
                    setDeferredState(detail.live
                        ? 'Initial deferred delivery finished; the shared kiss connection remains open.'
                        : 'Deferred delivery finished and the shared kiss connection closed.');
                    appendEvent('kiss.done', detail.live ? 'Initial blocks delivered, live updates remain enabled' : 'Initial deferred delivery completed');
                    return;
                }

                if (phase === 'error') {
                    setStatus('Shared kiss stream interrupted', 'warning');
                    setDeferredState('The shared deferred stream dropped; runtime fallback or reconnect logic may take over.');
                    appendEvent('kiss.error', 'The shared __semitexa_kiss connection dropped');
                }
            });

            document.addEventListener('semitexa:deferred:block', function (e) {
                const detail = e.detail || {};
                if (!detail.slotId) return;

                if (detail.mode === 'template') {
                    return;
                }

                if (detail.mode === 'html') {
                    return;
                }

                if (detail.mode === 'fallback') {
                    return;
                }
            });

            document.addEventListener('semitexa:deferred:message', function (e) {
                const detail = e.detail || {};
                const payload = detail.payload || {};
                const eventName = detail.eventName || 'message';

                if (eventName === 'scheduler.tick') {
                    appendEvent(eventName, formatEventData(payload));
                    setStatus('Scheduled heartbeat received', 'success');
                    setDeferredState('A real scheduled backend heartbeat arrived over the shared kiss stream. The countdown restarted for the next scheduler window.');
                    return;
                }
            });

            if (window.SemitexaSSR && window.SemitexaSSR._connected) {
                setStatus('Shared kiss stream connected', 'active');
                setDeferredState('The deferred runtime already has an open shared kiss stream. The countdown tracks the next scheduled heartbeat window.');
            }
        }

        function escHtml(str) {
            return String(str)
                .replace(/&/g, '&amp;')
                .replace(/</g, '&lt;')
                .replace(/>/g, '&gt;')
                .replace(/"/g, '&quot;');
        }

        if (streamMode === DEFERRED_KISS_MODE) {
            initDeferredKissObserver();
        } else {
            if (!connectBtn || !disconnectBtn) return;

            connectBtn.addEventListener('click', function () {
                if (source || connectBtn.disabled) return;

                openStream();
            });

            disconnectBtn.addEventListener('click', function () {
                if (source) {
                    source.close();
                    source = null;
                }
                currentSessionId = '';
                setStatus('Disconnected', 'warning');
                minuteSummaryEl.textContent = 'Connect once. The backend will emit a fresh SSE message on every new minute.';
                connectBtn.style.display = '';
                disconnectBtn.style.display = 'none';
            });
        }

        startCountdownLoop();
    }

    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', init);
    } else {
        init();
    }
}());

How it works

Why it matters

SSE is a pragmatic fit for one-way real-time updates. It uses plain HTTP, works well with browsers, and avoids the extra complexity of WebSockets when the client only needs to receive updates.

Key concepts

EventSource: Browser API for opening an SSE connection over plain HTTP.
text/event-stream: HTTP content type used by the SSE protocol.
long-lived response: A response that stays open so the server can push multiple messages over time.