weft
ir 2.6.0 · warp 1.8.0

Live regions and the channel

A region can be refreshed over a channel, and the smallest honest form is a delta computed once for every client on the same base.

the browserholds templates, and one baserender per regionRESIDENT · HELDwhat I already have, namedthe deploymentrecovers that base, diffs,memoizesTPL · DELTA · COMMITa template only if missing, thenvalues

up · codes below 0x10 — what the client tells the server

0x01RESIDENTthe template versions it is holding
0x02HELDthe base render per slot, so a diff has a from
0x03REFRESHthis region, again, please
0x04WARMa hint, and refusable
One socket, and a vocabulary small enough to read in full. The client opens by naming what it already holds, so the server can send the smallest thing that will do — and when the upgrade does not survive the path, the same frames arrive over an SSE stream and a POST instead.
✓ Valid HELD, and the smallest form that will do

No template if the client has one, values alone if they project, one COMMIT when a staged set should become visible.

✕ Refused a POST whose downstream has dropped
what you wrote→the half-duplex bindings answer on the other connection→E_NO_DOWNSTREAM

The frames were understood and there was nowhere to put the answer, so it says so — a silent 200 would be the wrong answer to a real question. A frame arriving from the wrong direction is rejected before anything reads it.

In plain terms

A live region keeps a page current without polling it. The client opens by saying which templates and which base render it holds; the server diffs against that base and sends the smallest form that will do. A thousand clients on the same base cost one diff, because the answer is memoized by the transition rather than computed per connection.

A region marked live can be refreshed over a channel without the page navigating. What arrives is chosen from a ladder of wire forms, and the interesting rung is the smallest one.

The same fragment, and one price changed. The table under it is the three encodings measured on this render rather than quoted from a benchmark.

output

Your basket

Olive oil, 2L14
Basmati rice, 5kg9
Medjool dates, 1kg12

Total 35

app/fragments/examples/prices.tsx
import { fragment } from '@weftjs/core'

interface Line {
  sku: string
  name: string
  price: number
}

/**
 * The fragment the wire-form comparison on `/guide/live-regions` is computed from.
 *
 * Nothing about it is special — a heading, a total and one row template — and that is the point.
 * `html`, `patch` and `delta` are three encodings of the *same* sealed template, so the byte counts
 * beside it are three ways of saying one price changed, not three implementations.
 */
export default fragment(({ heading, total, lines }: { heading: string; total: number; lines: Line[] }) => (
  <section class="prices">
    <h3>{heading}</h3>
    <table class="rows">
      <tbody>
        {lines.map((line) => (
          <tr data-sku={line.sku}>
            <td>{line.name}</td>
            <td class="num">{line.price}</td>
          </tr>
        ))}
      </tbody>
    </table>
    <p class="total">
      Total <output>{total}</output>
    </p>
  </section>
))
What the compiler knows
Holes3
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
headingtextescape
lineslisttrusted-raw
totaltextproven-safe

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
3fdd7374ceb2f6e5a794ff4329425df2

The same change, in three forms

One price rose by two. Here is what each form costs for that change, measured on the render above rather than quoted from a benchmark:

FormBytesAgainst htmlWhat it carriesWhat it needs
html367 B—the region, renderednothing — always available
patch336 B8% smallerthe markup of the holes that changed, as DOM writesnothing resident on the client
delta186 B49% smallerthe changed values onlythe template, and the base render the client names

Measured when this page rendered, from the sealed template of examples/prices and two value sets one price apart. JSON payloads are counted as written; a socket sends them inside a warp frame, which adds its own header.

The forms, and how one is chosen

FormWhat it carriesWhat it needs
htmlThe region’s markup.Nothing. Always available.
patchThe markup of the holes that changed.Nothing resident.
deltaThe changed values only.The client holds the template and names the base render it has.

The negotiation is not a preference: every form of a fragment must produce identical bytes, and the benchmark harness refuses to publish a number until it has checked that they do.

Why a delta is cheap for the server too

Because the client names the base render it holds, a delta is a pure function of two content-addressed states — so it is memoised by the transition it encodes. One computation serves every client making the same transition, where a diff kept per connection produces one diff per connection. That is architectural rather than a tuning choice, and it is the claim the harness’s deltas command exists to measure.

Epochs

An optimistic update is staged into an epoch and committed atomically: every region in it flips at once. Rollback is discarding the epoch — nothing was painted, so there is nothing to un-paint and no prior state to reconstruct.