weft
ir 2.6.0 · warp 1.8.0

The Guide

22 pages, in the order the framework is easiest to learn in. Every page links the reference documents it introduces, so you can drop from the introduction straight into the exact rules whenever you want them.

/guide — the front door This is the top of the Guide index. It opens the page; the directory of all 22 pages sits directly below it, on the same route. The page directory ↓

Before the 22 pages

The architecture, and where every idea lives in it

10 packages, one request path, three tiers and three wire forms. Read this page and the rest of the guide is detail: each later page takes one box out of these diagrams and shows what it refuses. Everything below is the real dependency graph and the real state machine — every figure states what it measured and on what.

1 · Ten packages, and what each one is allowed to know

The dependency direction is the design. @weftjs/ir and @weftjs/warp are data formats with no dependencies at all; the kernel knows about those two and nothing else, which is what lets the same kernel run on Node, Deno, Bun, a worker and the edge with no adapter to choose. The client package sits beside the server rather than under it, so one code path serves a socket, an SSE stream and a test.

@weftjs/ir2.6.0 · no deps@weftjs/warp1.8.0 · no deps@weftjs/client6,137 B brotli@weftjs/compilerTSX → IR, on Oxc@weftjs/kernelthe request path@weftjs/planplan DSL, validation@weftjs/adapters14 ports implementedweftthe front door@weftjs/docsthis site, as an app@weftjs/inspectora station per mechanism@weftjs/benchthe benchmarkscreate-weftdepends on nothing
The real workspace dependency graph, animated in pnpm build order: ir · warp · client · compiler · kernel · plan · adapters · weft. Every arrow is an actual dependency, and a test fails the build if one stops being one.

2 · One request, and the line through the middle of it

A document request is a state machine, and the envelope closes partway through it. Everything a response header can say has to be said before that point — which is why the two halves are different context types rather than the same object with a rule attached.

receivedthe request arrivesenvelopestatus · headers · cookiesplannedkeys resolved, waves builtstreamingslots land as they finishsettledlast byte

Valid here · phase A, EnvelopeContext

status()header()cookie()sendEarlyHints()

103 Early Hints goes out here at effectively zero milliseconds, with the envelope still open — and it reports whether it actually went out.

Not available here · phase B, RenderContext

read()slot()

Cache-Control and Vary are written before the seal, from the resolved keys. After it, there is nothing to write them with.

Five states, and a hard line through the middle of them. Writing a header after the response has begun is not a rule you have to remember here; it is a method that does not exist on the type you are holding.

3 · What runs at once, and what has to wait

Inside planned, the slots become waves. A slot that names another in needs lands in a later one; everything else goes together. The saving is real and bounded, and the reason it is safe is a property of the whole design rather than a scheduler trick.

wave 1 — all 4 at oncewave 2wave 3
headerreads nothingnavreads nothingitemsreads the cartfeedreads the feedtotalneeds itemspricesneeds itemsrelatedneeds feedsummaryneeds total, pricesfooterneeds related

What runs when — the same 9 slots on a clock

header 20.0 ms
nav 10.9 ms
items 20.0 ms
feed 22.0 ms
total 9.3 ms
prices 8.4 ms
related 14.0 ms
summary 12.0 ms
footer 6.7 ms
010203040 42.7 ms
sequential 123.3 ms
Nothing in wave 1 depends on anything, so all 4 start at once — the bars leave the origin together and the wave finishes when its slowest member does. Wave 2 begins per slot, the moment the slot it names lands: total and prices at 20 ms when items finishes, related at 22 ms when feed does. 9 slots take 42.7 ms concurrently against 123.3 ms one after another, and the accent chain is the critical path.

4 · Three tiers, and how far a request falls

The fastest request is the one the kernel never sees. weft build renders every route twice under two deliberately different requests and writes the byte-identical ones out as files, so weft start can answer them before routing. What cannot be a file says why, in the build output, every time.

a requestL0 — a file.weft/static/ · answered before the kernel is reached, with an ETag and a 304the kernelenvelope · keys · waves · the stream — 8,273 B on the document patha region hopanother process · a service binding · another pod — over Warp frames304, no body396 of this site’s pages stopherestatic: false/play, and the build says whyit cannot be one
A request falls only as far as it must. weft build renders every route twice under two deliberately different requests and writes the byte-identical ones out as files; what cannot be a file says why, in the build output, every time.

5 · The negotiation this framework is named for

A region that changed has three ways onto the wire, and the kernel picks per request from what the client says it holds. The fragment is unaware of all of it: the same declaration serves a first visit, a surgical refresh and a client holding a template from last week.

HELDthe client names the template versionand the base render it holdsholds the template?advertised as a coarse digestvalues projectable?a raw() value, an isolated instance or aslot hole says nodelta — 371 B · 190 brotlione write per changed value, into DOM thatalready existspatch — between the twoaddressed the way adoption addresses the DOMhtml — 6,289 B · 605 brotlithe whole region, re-parsed

A delta is memoized under delta:<tpl>:<from>-><to>, so 1,000 clients on one base cost one diff — 0.4 ms against a per-connection differ’s 9.2 ms. The same clients each on a different base share nothing, and the shared path then costs 18.7 ms against 9.6 ms.

All three forms produce identical DOM, so which one you get is never something you have to reason about: you write the fragment once and delivery is negotiated underneath it.

6 · How a frame reaches the browser at all

Figure 5 is one negotiation and this is the other, and conflating them is the usual mistake. Form decides what a region becomes on the wire. Delivery decides how any frame gets there — and the two are independent, so every form is available on every binding.

RESIDENTthe client names its versions,the forms it takes, and the transport it hassocket — strategy socketdown: one WebSocketup: the same socketstream — strategy streamdown: a held GET responseup: discrete POSTssse — strategy streamdown: text/event-streamup: discrete POSTsturn — strategy streamdown: the POST's own responseup: the same POSTWARPevery axis settled, and a nameddowngrade for each one that was not

Every form in figure 5 is available on every binding — a turn is a bounded stream, not a degraded one. What differs is only whether the server can speak without being asked, which is why the one binding that cannot says so on the handshake: no held downstream, so the server cannot speak first: an invalidation is carried on the next turn rather than pushed when it happens

The client says which transport it has and the server says what it will do with it. Nothing above the handshake knows which of the four it got.

Up6 kinds — everything a client can ask

  • RESIDENTwhat I am: versions, forms, transport, engine
  • HELDwhat I am showing, per region
  • REFRESHthis region, again
  • WARMstage this and paint nothing — a template, a route, or a subtree of the plan
  • INTENTrun this write
  • RESUMEI was evicted; continue from this epoch

Down20 kinds — everything a server can say

  • WARPeverything settled, and every downgrade named
  • SHELLthe document around the holes
  • SLOTa hole, and which region fills it
  • HTMLthe whole region, as markup
  • TPLa sealed template you did not hold
  • DATAvalues, for a region that can project them
  • DELTAonly what changed, against a base you named
  • PATCHaddressed the way adoption addresses the DOM
  • SIGNALa shell value a region on this page consumes
  • COMMITpaint the epoch — the only frame that changes what is seen
  • MODa module this region needs
  • CSSa stylesheet, before the thing it styles paints
  • STALEsomething you hold is known wrong; ask when you like
  • NAVthe route you staged, and whether it shares this shell
  • PLANroutes you have not been to, and what they cost
  • ERRORrefused, by name
  • REDIRECTgo here instead
  • COOKIEset this, because a channel is not a response
  • ACKyour intent, and whether its epoch survives
  • REGIONframes another deployment produced, passed through

One vocabulary, every binding. A turn narrows when the right-hand column can be sent, never which of it exists — which is why the same client code applies frames from a socket, from an event stream and from a POST response without knowing the difference.

26 frame kinds is the entire protocol surface. The set and the direction here are read from the frame table itself, so this figure cannot drift from it.

The whole handshake is one frame each way. The client sends RESIDENT: the protocol version it speaks, the template format it can apply, the wire forms it accepts, the transport it actually has, and what its engine can do — incremental declarative shadow DOM, view transitions, a service worker, IndexedDB. The server answers WARP, which settles every axis at once and carries a named line for each one it could not honour.

That list of names is the part worth dwelling on. A framework that degrades silently is a framework whose failures look like bugs: a region that never updates and a navigation that is always a document are the same symptom whether the cause is a blocked port, a proxy eating an upgrade, or a client three template majors behind. So nothing degrades quietly here. Every downgrade is a sentence on the frame that settled it, which is why the one thing a turn cannot do is written into its handshake rather than into a paragraph somebody has to find.

What the handshake settles

warp
the frame protocol version, settled to the lower of the two. a major mismatch is fatal on the frame that settles it: the stream is unusable and nothing renders under it, rather than frames arriving that depend on a version nobody has
ir
the template format the client can apply. a major mismatch drops every client to html — the whole region, re-parsed — because a delta names paths into a template shape it does not have
forms
which of html, delta, patch, split and bundle this client accepts. the kernel picks the smallest form both sides hold; a client that takes only html gets html, over the wire and not merely in the plan
strategy
how frames move: socket, stream, or collapse. collapse is the webview case — the host app buffers the document, so holes cannot arrive out of order and slots fold into the document instead
fill
declarative shadow DOM, or a script that moves the nodes. a client without incremental DSD parsing is filled by script; the DOM is identical either way
commit
whether an epoch commits inside a view transition. without one the commit is instant — still atomic, just not animated
residency
where resident templates live: a service worker, IndexedDB, or the HTTP cache. the HTTP cache is the floor, and repeat-visit gains stop being guaranteed
resumable
whether this client may come back with RESUME and continue. a buffered transport cannot, so an evicted webview starts over rather than continuing from its last commit

The four bindings, and the one that holds nothing

Three of the four hold a downstream open, and answer down it. A socket is one connection carrying both directions. The streamed binding is a long-lived GET with discrete POSTs going up, and the SSE binding is the same arrangement in text framing — which is why it is not the default, since it cannot carry binary and pays base64 on every body. All three share one consequence: the server can speak first. An invalidation reaches the reader the moment the write happens.

The fourth holds nothing. A turn carries frames up in a request body and the answer back in that request's own response, so it is a function from bytes to bytes with no state between calls. That is the only shape that runs on a platform which terminates no upgrade and outlives no request — a serverless function — and it needs no server memory because the protocol was already client-authoritative: RESIDENT says what the client holds and HELD says what it is showing, both in the same body, so a channel built for one request answers exactly as a socket would. It opens, is used, and is dropped.

What it gives up is the ability to be spoken to. With no held downstream there is nowhere to put an unasked STALE, so an invalidation waits and is carried on the next turn — which is a real limitation and a small one, because everything a client asks for it still gets: intents, surgical refreshes, a whole route staged before it is clicked.

Which one you get, and who decides

The client does not guess. A deployment that cannot hold a connection says so, and the client takes turns from its first request. Guessing is worse than it sounds: the upgrade fails, the streamed GET then appears to work, and the POSTs that follow land on whichever instance the platform happened to route to — so a channel that is merely unavailable ends up looking broken, intermittently. A deployment that did not say is still not stranded: the first refusal switches bindings and takes the refused frames as a turn rather than losing them.

The difference, drawn to scale

socket, stream, sse
a write invalidatesSTALE, pushed
the write and the telling are one instant
turn
the same writethe reader’s next turnSTALE, carried
nothing to push to, so the journal holds it until the reader asks

Both rows run on one clock, so the gap is the figure. The dashes are the stretch where a held binding has already told the reader and a turn has nobody to tell: no held downstream, so the server cannot speak first: an invalidation is carried on the next turn rather than pushed when it happens

The whole of what a turn gives up, drawn to scale: not whether the reader is told, but when. Everything the client asks for is answered on the same request that asked.

The gap a turn leaves is filled from outside the hub, by whichever of two things a deployment needs. A fanout carries an invalidation to the other instances holding a connection right now, which is what more than one replica requires whatever binding it serves. A journal writes down what a client with no connection will ask for later. The hub knows about neither: it takes one hook and tells whatever is on the other end, because which of them applies is a property of the deployment and not of the protocol.

7 · What paints, and when

Frames arriving is not the same as the page changing, and keeping those two apart is what makes a background revalidation safe. Data staged under an epoch is resolved, held, and invisible; only COMMIT paints, and it paints all of it at once.

without epochs
DELTA — paintsDELTA — paintsDELTA — paints
what the reader sees
every frame paints as it lands, including the ones nobody asked for
staged in an epoch
DELTA — stagedDELTA — stagedCOMMIT — paints
what the reader sees
three frames change nothing; one COMMIT changes everything, at once

One clock, two lanes, and the head reaches the same three moments in each. Only the accent marks changed what the reader sees — which on the second lane is the last one alone. A frame carrying an epoch is invisible until its COMMIT, and that is a property of where frames are routed rather than of anything an application remembers to do. It is also what makes a staged route possible: a whole page can be resolved and held, painting nothing, until the reader actually clicks.

Nothing paints on arrival unless the frame says to — which is what lets the server revalidate under a reader without ever disturbing what they are doing.

8 · From your files to what the browser fetches

The build produces sealed templates, a generated plan, a manifest and revved assets — and prints which pages became files. Nothing is bundled at any point, which is why the byte budget is measured on the real walk over HTTP: 26,551 B brotli for the demo, agreeing within 0.34% with the same walk over the build's own graph.

app/**.tsxwhat you wroteOxcparse — no bundlerIR 2.6.0segments · holes · effectssealed templatesand the generated planmanifestevery URL carries a digest396 filesserved without the kernel

weft devserves the same bytes at stable names with no-store — a stylesheet you just edited, served as immutable, is a framework that lies to you for a year.

Client modules are TypeScript with their types stripped by Node and two bare specifiers rewritten, so what runs in the browser is the file on disk.
spec/

the reference: the mechanism, its refusals, and what each deliberately does not do

@weftjs/inspector

the live version: a station per capability, each with a control

this guide

the introduction: what it is, in order, with examples that run

Start here what the thing is 2 pages
Rendering what a fragment is, and what it compiles to 4 pages
Delivery reads, keys, streaming, and where a render runs 5 pages
Change the client, and the only thing allowed to write 5 pages
Operating it ports, tiers, devices, versions 6 pages