Slots, and why the shell never waits
A fragment that reads something slow becomes a hole by construction, so the first byte is never downstream of the query.
The shell stops waiting for that region; the placeholder is declared, cheap and visibly incomplete, and the real markup lands in the same hole later.
The streaming slots are named. On a route whose slots all buffer, the same line gets a strong tag and a 304 that costs no body.
In plain terms
Mark the slow part of the page as a slot and the shell stops waiting for it. Everything fast goes out immediately, the slow region sends a placeholder, and its real markup arrives later and lands in the right hole.
A slot is a hole in the document that the render does not own. The point is not layout: it is that the bytes before a slot can be on the wire before anything is known about what fills it.
That falls out of the effect graph rather than being asked for. A fragment that reads something slow is a fragment whose bytes cannot be part of the shell, so it becomes a hole — which is why the first byte of a page is never downstream of its slowest query.
A region that cannot be part of the shell
examples/feedReading the clock taints time, which forces a TTL. The rows are one template projected per item, so what arrives late is values rather than markup.
- Olive oil, 2L14
- Basmati rice, 5kg9
- Medjool dates, 1kg12
app/fragments/examples/feed.tsximport { fragment, type Ctx } from '@weftjs/core'
interface Item {
id: number
title: string
price: number
}
/**
* The streaming example. Reading the clock taints `time` and forces a TTL. See
* `spec/kernel/cache.md`. `count` is a prop rather than `items.length`, since a hole binds a value
* and `.length` is an expression the compiler has no lowering for (`E_EXPRESSION_UNSUPPORTED`).
*/
export default fragment(({ count, items }: { count: number; items: Item[] }, ctx: Ctx) => {
const generated = ctx.now()
return (
<section class="feed">
<p class="meta">
<span class="count">{count}</span> items · generated at <span class="at">{generated}</span>
</p>
<ol class="items">
{items.map((item) => (
<li data-id={item.id}>
<span class="title">{item.title}</span>
<span class="price">{item.price}</span>
</li>
))}
</ol>
</section>
)
})
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
count | text | proven-safe |
generated | text | proven-safe |
items | list | trusted-raw |
What the client wires on adoption
No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.
- Sealed templates
- 2
- Version
1f665f431601c5cb7cfc718484232c50
The facts below list time as the read. That single entry is why a policy with no ttl on this route is a build error.
Two orders
| Order | What happens | Cost |
|---|---|---|
in-order | Each slot streams where it sits in the document. A slow slot holds back everything after it. | No JavaScript at all. |
out-of-order | The whole document goes out with an anchor comment per slot; whichever slot resolves first fills first. | One inline fill script, about 330 bytes. |
Which one a route uses is derived: a plan where no slot asked to stream lowers to in-order, so a page of uniformly fast regions never puts the filler on the wire. Asking a slot to stream is what turns the page out-of-order.
export default defineRoute({
slots: {
panel: { html: '' }, // buffered: nothing asked to stream
feed: { fragment: 'feed', stream: { prio: 1 }, load: slowQuery },
recs: { fragment: 'recs', stream: { prio: 2 }, load: slowerQuery },
},
})Waves, not a list
Slots run concurrently under a per-request ceiling. A slot that declares needs on another one is scheduled in a later wave, so a data dependency is a fact the scheduler reads rather than an ordering somebody maintained by hand.