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

A live slot can keep refreshing itself while the page remains SSR-first and HTML-driven.

How it works

refreshInterval on #[AsSlotResource] tells the framework to re-fetch the slot over SSE on a timer. The client swaps HTML in place and reconnects automatically if the stream drops.

Why it matters

This gives you live widgets without building a parallel client-side rendering system just to maintain one dynamic region.

Key concepts

refreshInterval: Declarative live-refresh interval for a slot resource.
SSE reconnection: Keeps the live slot updating even if the stream temporarily drops.
SSR-first live UI: A live region remains part of the server-rendered page model instead of becoming a mini SPA.

Reactive Slot Refresh

Live widgets without a client-side data loop

The server keeps re-rendering the slot as HTML, and the page swaps it in place. The widget feels live, but the UI model stays SSR-first.

Why this matters

Live UI often pushes teams toward a separate client-side state system for even simple status widgets.
Polling code and reconnection logic usually leak into ad hoc JavaScript instead of staying part of the rendering model.
The shell and the live widget can drift into two different architectures even though they belong to one page.

5s refresh interval declared on the slot

1 rendering model for static and live regions

0 custom polling loop to maintain

Client Loop Creep

Widget becomes a mini frontend app

State fetches, retry logic, and rendering drift into custom client code for what should be one live region.

The page stops having one rendering story.

SSR-First Live Region

Slot keeps itself fresh

refreshInterval stays on the slot contract, and the framework handles reconnection and HTML replacement.

Live behavior feels native without turning the page into a SPA shell.

auto-refresh

Verified against Semitexa Ultimate 2026.09.19.1020

Live Widgets

Set refreshInterval and the server keeps re-rendering the widget for you. Live UI without converting the page into an app shell.

The problem

Live UI often pushes teams toward a separate client-side state system for even simple status widgets. Polling code and reconnection logic usually leak into ad hoc JavaScript instead of staying part of the rendering model. The shell and the live widget can drift into two different architectures even though they belong to one page.

How it works

A deferred slot with refreshInterval set keeps its SSE connection open after the first delivery. The SERVER holds a coroutine for that page, re-renders the slot when the interval elapses, and pushes the new HTML down the connection the page already has; the client swaps it into position. Nothing is re-requested on a timer: there is no polling interval and no request per refresh. The browser does still open a request when the SSE connection itself has to be re-established — recovery is handled by the framework, so reconnection logic does not need to be written by hand, but those reconnects are real HTTP requests and count against authentication, rate limits and capacity like any other.

Key mechanisms

refreshInterval — declares the push cadence in seconds directly on the slot resource. Its cost is a held coroutine per connected user for as long as the page is open, which is what makes this a capacity decision and not only a UX one.
server push — the framework re-renders on its own clock and pushes; the page never polls.
SSE reconnection — the framework recovers dropped connections automatically without custom retry code.
SSR-first live UI — the slot stays part of the server-rendered page model rather than becoming a client-managed widget.

Why this matters

Without a framework-level refresh mechanism, live regions require bespoke polling loops, reconnection handlers, and custom HTML replacement code. Declaring refreshInterval on the slot keeps the live behavior co-located with the slot contract and removes the need for per-widget polling infrastructure.

1<?php23declare(strict_types=1);45namespace App\Application\Resource\Slot;67use Semitexa\Ssr\Attribute\AsSlotResource;89#[AsSlotResource(10    handle: 'dashboard',11    slot: 'dashboard.sidebar',12    template: '@project/dashboard/deferred-sidebar.html.twig',13    deferred: true,14)]15final class DeferredSidebarSlot16{17    /**18     * @param list<string> $items19     */20    public function __construct(21        public readonly string $headline,22        public readonly array $items,23    ) {}24}25

<?php

declare(strict_types=1);

namespace App\Application\Resource\Slot;

use Semitexa\Ssr\Attribute\AsSlotResource;

#[AsSlotResource(
    handle: 'dashboard',
    slot: 'dashboard.sidebar',
    template: '@project/dashboard/deferred-sidebar.html.twig',
    deferred: true,
)]
final class DeferredSidebarSlot
{
    /**
     * @param list<string> $items
     */
    public function __construct(
        public readonly string $headline,
        public readonly array $items,
    ) {}
}

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Rendering;67use App\Application\Payload\Page\DashboardPayload;8use App\Application\Resource\Page\DashboardPageResource;9use App\Application\Resource\Slot\DeferredSidebarSlot;10use App\Domain\Dashboard\DashboardMetricsInterface;11use Semitexa\Core\Attribute\AsPayloadHandler;12use Semitexa\Core\Attribute\InjectAsReadonly;13use Semitexa\Core\Contract\TypedHandlerInterface;1415#[AsPayloadHandler(payload: DashboardPayload::class, resource: DashboardPageResource::class)]16final class DeferredSlotHandler implements TypedHandlerInterface17{18    #[InjectAsReadonly]19    protected DashboardMetricsInterface $metrics;2021    public function handle(DashboardPayload $payload, DashboardPageResource $resource): DashboardPageResource22    {23        return $resource->withDeferredSlot(24            new DeferredSidebarSlot('Live metrics', $this->metrics->latest())25        );26    }27}28

<?php

declare(strict_types=1);

namespace App\Application\Handler\Rendering;

use App\Application\Payload\Page\DashboardPayload;
use App\Application\Resource\Page\DashboardPageResource;
use App\Application\Resource\Slot\DeferredSidebarSlot;
use App\Domain\Dashboard\DashboardMetricsInterface;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Attribute\InjectAsReadonly;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: DashboardPayload::class, resource: DashboardPageResource::class)]
final class DeferredSlotHandler implements TypedHandlerInterface
{
    #[InjectAsReadonly]
    protected DashboardMetricsInterface $metrics;

    public function handle(DashboardPayload $payload, DashboardPageResource $resource): DashboardPageResource
    {
        return $resource->withDeferredSlot(
            new DeferredSidebarSlot('Live metrics', $this->metrics->latest())
        );
    }
}

How it works

refreshInterval on #[AsSlotResource] tells the framework to re-fetch the slot over SSE on a timer. The client swaps HTML in place and reconnects automatically if the stream drops.

Why it matters

This gives you live widgets without building a parallel client-side rendering system just to maintain one dynamic region.

Key concepts

refreshInterval: Declarative live-refresh interval for a slot resource.
SSE reconnection: Keeps the live slot updating even if the stream temporarily drops.
SSR-first live UI: A live region remains part of the server-rendered page model instead of becoming a mini SPA.