Verniz navigation

Verniz can accelerate an ordinary multi-page site without replacing links, inventing a client route table, or requiring a JavaScript entry. The static Link Graph remains the authority and every page still works as normal HTML when the feature is removed or JavaScript fails.

Enable it explicitly¶

[web.navigation]
mode = "morph"
prefetch = "intent"
transitions = "auto"
cache = "96 KiB"

[web.budgets]
javascript = "128 KiB"

The whole table is opt-in. With no [web.navigation], a pure View remains zero-JavaScript and links perform native document navigations.

• mode = "morph" fetches a validated destination document and morphs its body while updating the title, history, scroll position, islands and client mounts.
• prefetch = "intent" starts only after pointer or keyboard focus intent. There is no eager crawl.
• transitions = "auto" uses the browser View Transitions API when available and otherwise morphs immediately.
• cache is a required positive byte budget when intent prefetch is enabled. It bounds an LRU cache by decoded HTML bytes, not by an arbitrary entry count.

The generated runtime is also charged to [web.budgets].javascript. The build fails before replacing the previous product if the route budget is exceeded.

Keep ordinary links¶

<nav>
  <a href="/">Home</a>
  <a href="/guide/">Guide</a>
  <a href="/account" data-zolo-reload>Account</a>
</nav>

Verniz does not add a special Link component. Static build and preview derive eligible destinations from the validated Link Graph. External URLs, downloads, non-page targets, runtime-only routes and pages with unsafe executable scripts are never prefetched or morphed. target, download, external rel, and data-zolo-reload keep native browser behavior.

Module scripts are supported: after a document morph, newly introduced ESM modules are reactivated with their original integrity and loading attributes. An inline or classic executable script makes that destination ineligible, because silently replaying arbitrary document scripts would not be a safe navigation contract.

Failure and history behavior¶

Prefetch and navigation accept only same-origin destinations sealed into the current page's policy. A destination must return HTML carrying the matching zolo.navigation-v1 contract and route. Otherwise Verniz falls back to location.assign or reloads the current document; the link never becomes a dead JavaScript-only control.

Successful navigation pushes browser history, restores saved scroll positions on Back/Forward and scrolls to an explicit fragment. A later click reuses prefetched HTML from the byte-bounded cache, so intent prefetch and navigation do not perform duplicate requests.

zolo dev injects the same data-only policy into safe HTML responses and serves the same client runtime. Production stores the root policy, per-page targets, cache budget and transitions mode in WebManifest v15. zolo preview recomputes the Link Graph and refuses a product whose navigation targets or HTML contract were changed after build.

Inspect the exact result with:

zolo build --web=static
zolo explain web /
zolo preview dist

See the complete example at examples/features/36-web/25-navigation-site.