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.
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.
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.
Valid here · phase A, EnvelopeContext
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
Cache-Control and Vary are written before the seal, from the resolved keys. After it, there is nothing to write them with.
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.
What runs when — the same 9 slots on a clock
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.
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.
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.
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.
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
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.
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
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 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.
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.
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.
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.
the reference: the mechanism, its refusals, and what each deliberately does not do
the live version: a station per capability, each with a control
the introduction: what it is, in order, with examples that run
03Fragments and templates
A fragment compiles to a sealed template: pre-encoded bytes with holes, and a version that is a hash of its content.
2 live examples
04One fragment inside another
A tag is resolved to a sealed template at build time, not mounted at runtime.
1 live example
05A component’s own stylesheet
Name a sheet .scoped.css and its selectors reach the elements that component declares, and nothing else on the page.
06Layouts, and documents that nest
A route names one document. That document may be a chain, and the chain comes from the directory tree.
07What a fragment reads decides everything
The cache key, the class and the Vary header are derived from the reads the compiler saw. None of them can be declared.
2 live examples
08Slots, 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.
1 live example
09Where a render runs, and what it may cost
Render is a DAG rather than a tree walk, executors are crash domains, and a budget is only a limit where something can be preempted.
1 live example
10What a route declares
Placement, delivery, cache policy and budgets are declared per route — and checked against what the compiler inferred.
11A plan generated from measurement
The file tree cannot say what anything costs, and delivery is a decision about cost. So record it, and let the recording decide.
12Adoption, signals, and what ships
No hydration: the server-rendered DOM is adopted, and what the client wires is one entry per binding.
1 live example
13Instant navigation
A route fetched, parsed, and painting nothing, committed by a click.
1 live example
14Intents: the only thing that writes
A render cannot write. Mutations are intents, addressed by an opaque id, with their writes declared.
1 live example
15Live 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.
1 live example
16What the page downloads
Entries, not a bundle — and a ceiling per entry, because one number over several jobs is a label rather than a gate.
17Ports, config, and the build
Ports replace, plugins extend. Fourteen are declared and eleven are bound by the front door with no configuration at all.
18A region that lives somewhere else
A shell is a fragment tree whose leaves are regions, and a region is a fragment that happens to render on another deployment.
1 live example
19Every surface at once
Nothing here fails on an old engine. Every missing capability costs a wire form, a fill mechanism, or an animation.
1 live example
20Versions, and what may change
Two artifacts were versioned before there was a framework, because a wire format cannot be versioned retroactively.
21Checking your own application
A fragment is data, so testing one needs no browser, no server and no snapshot to keep in sync.
22The CLI
Nine commands, and this page is generated from the one that prints them — so it cannot describe a flag that does not exist.