weft
ir 2.6.0 · warp 1.8.0

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.

In orderthe shell waits
shell
feed — 80 ms feed
prices
105 ms
Out of orderwhatever is ready goes first
shell
prices
feed — 80 ms feed
23 ms105 ms
Both lanes settle at 105 ms with identical DOM in Chromium, Firefox and WebKit. The difference is when the fast region became visible, and it costs 329 bytes of inline script.
✓ Valid stream: true, with a placeholder

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.

✕ Refused etag: true on a route whose slots stream
what you wrote→an ETag digests a whole entity; the envelope seals first→E_ETAG_STREAMS

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.

Reading 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.

output

3 items · generated at

  1. Olive oil, 2L14
  2. Basmati rice, 5kg9
  3. Medjool dates, 1kg12
app/fragments/examples/feed.tsx
import { 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
Holes3
Escape elided0
Effect settime
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
counttextproven-safe
generatedtextproven-safe
itemslisttrusted-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

OrderWhat happensCost
in-orderEach slot streams where it sits in the document. A slow slot holds back everything after it.No JavaScript at all.
out-of-orderThe 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.

sketch — not compiled
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.