Instant navigation
A route fetched, parsed, and painting nothing, committed by a click.
The staged epoch paints nothing, so prefetch cannot disturb the present and rollback is discarding it. 254 bytes on the client.
17.0 ms staged against 605.0 ms on a slow page; on loopback a staged click loses to the browser. That is the floor of the idea, and the table says so.
In plain terms
Hovering a link fetches the next page into a staging area that paints nothing. Clicking swaps it in as one atomic change. If you never click, nothing you saw was disturbed — discarding a staged epoch is free.
A route fetched, parsed, and resolved, painting nothing — and a click that commits it. That is the whole mechanism, and almost none of it was new: an epoch is already data that has arrived and has not been painted, the resident store already keeps templates across visits, and the swap is the one a control that changes a query has always done.
What was missing was the notion of a staged route. Regions are keyed by slot on the page you are on, so without that, tomorrow’s prices could be staged into today’s page.
Ordinary anchors
examples/linksNothing here opts into staging. A link is a link, and what the client does behind it is a deployment’s decision rather than an author’s.
app/fragments/examples/links.tsximport { fragment } from '@weftjs/core'
interface Link {
href: string
label: string
/** Whether this is the page you are on. Per item, because a row receives only its own item. */
here: boolean
}
/**
* Ordinary anchors — nothing opts a link into instant navigation. See `spec/client/navigation.md`.
* `here` is a field on the item, not a `current` prop compared inside the row: a row receives only
* its own item, and reading an outer value is `E_OUT_OF_ROW_SCOPE`. See `spec/compiler/supported-subset.md`.
*/
export default fragment(({ links }: { links: Link[] }) => (
<nav class="links">
{links.map((link) => (
<a href={link.href} data-current={link.here}>
{link.label}
</a>
))}
</nav>
))
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
links | 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
e2dcca59235428eb573ac44a2f978541
A page that links nowhere never carries the staging model. That is why this is an anchor rather than a component.
What a click costs
| State when clicked | What happens |
|---|---|
| Staged and resolved | A commit. The DOM is swapped from data already in memory — no request. |
| Staged, still arriving | The commit waits on the response already in flight. No second request. |
| Not staged | An ordinary fetch, then a commit. The same path, without the head start. |
| Staging unavailable | A full navigation. The link is an anchor, so the browser does what it always did. |
The last row is the reason this is safe to turn on: every rung down from staging is a rung the browser already implements. There is no state to reconstruct, because a staged route that is never committed was never painted.
Two documents can only swap if they are the same document
A staged route is committed into the page you are on, so the two must have been built from the same layout chain in the same order. When they were not, the destination is a full navigation rather than a swap — E_NOT_THE_SAME_DOCUMENT where the code asks for one explicitly.
That is also what makes shared regions honest: a nav bar that is the same sealed template on both pages is not re-rendered, and one that is not the same template cannot pretend to be.
What it adds to the page
Its own client entry, with its own ceiling, and a page that links nowhere does not carry it — see what the page downloads. Prefetch policy comes from the profile when there is one: the routes worth staging are the ones readers actually went to next.