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

Two identical blocks on the same page run independently — scoped DOM, scoped JS, no conflicts.

Scoped Instances

Same slot class, separate runtime state

Two countdown blocks reuse the same widget template and client module, but each instance keeps its own timer and DOM scope.

This widget runs its own timer state and restart flow without touching the other instance.

Timer A 30s

Waiting for the first backend sync tick.

This widget runs its own timer state and restart flow without touching the other instance.

Timer B 60s

Waiting for the first backend sync tick.

DOM scoping data-instance block isolation independent timers

Verified against Semitexa Ultimate 2026.09.19.1020

Block Isolation

Two identical blocks on the same page run independently — scoped DOM, scoped JS, no conflicts. Repeated deferred blocks stay isolated through per-instance data attributes and scoped DOM.

How it works

Each deferred block instance receives a unique data-instance attribute when it renders. Client-side behavior scopes its DOM queries to the component root instead of using global selectors. This means two instances of the same slot class can run on the same page with independent state, independent timers, and no interference between their DOM trees.

Key mechanisms

DOM scoping — each block instance owns its own DOM subtree, identified by data-instance.
data-instance — unique per-render attribute that client scripts use as the scope root.
block isolation — slot handler, template, and client module all treat each instance as independent.
independent timers — two countdown or refresh loops running the same slot code do not share state.

Why this matters

Without per-instance scoping, placing the same deferred widget twice on a page causes client scripts to interfere with each other — shared class names, shared DOM queries, and racing timers. Block isolation makes duplication safe by default, so the same slot can appear any number of times on one page without custom disambiguation code.

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())
        );
    }
}

Find a concept, task, or command

Block Isolation

What this does

Same slot class, separate runtime state

Countdown widget

Countdown widget

Block Isolation

How it works

Key mechanisms

Why this matters