Navigation
Two routers can run in one site: browser-router for server-rendered documents and react-router for React pages. Neither owns navigation alone. packages/core/src/router/client/ holds the framework-agnostic parts they share, so a click, a handoff between them and a development reload all agree on who owns the document and which navigation is current.
The coordinator
navigation-coordinator.ts keeps one EcoNavigationRuntime on window.__ECO_PAGES__.navigation. A router registers an EcoNavigationRuntimeRegistration with optional capabilities:
| Capability | Purpose |
|---|---|
navigate | Navigate to a request routed to this owner. |
handoffNavigation | Accept a document another runtime already fetched. |
reloadCurrentPage | Re-render the current URL in place; clearCache discards cached client state and moduleUrl forces a page entry. |
cleanupBeforeHandoff | Release client state before another runtime commits a document. requestHandoff() does not run it; the accepting runtime decides when, so the current page is not blanked before the incoming document is ready. |
enableReloadStatePreservation | Start keeping what reloadCurrentPage needs to preserve state. |
The coordinator arbitrates three things:
- Ownership.
claimOwnershipandreleaseOwnershiptrack the active owner (browser-router,react-routerornone). A rendered document names its owner indata-eco-document-owner;adoptDocumentOwnerreads it, and a document without the marker leaves the router on its local default. - Transactions.
beginNavigationTransactionstarts a new navigation and invalidates the previous one. A transaction exposes anAbortSignal,isCurrent()andisSuperseded(). Superseded differs from not current: a navigation that completed normally is no longer current, yet still owes work such aseco:page-load, which is skipped only when a newer navigation replaced it or it was cancelled. - Handoff and reload.
requestNavigationandrequestHandoffsend a request or a pre-fetched document to another registered runtime;reloadCurrentPageasks the active owner;enableReloadStatePreservationasks every runtime now and any that registers later.
A handoff carries the already fetched Document, so the receiving runtime commits it without another request.
Shared helpers
| Module | Role |
|---|---|
link-intent | Finds the anchor for a click, pointer or hover event across Shadow DOM boundaries, and remembers the last valid target while a navigation is in flight. |
link-navigation-policy | Decides whether a link is intercepted. It returns the refusal reason: modified or non-left click, external target, explicit reload attribute, download, no-prefetch, invalid or cross-origin href, static asset, or same-page hash. |
navigation-document | Fetches and parses the next page, with an HTML cache and a final-URL map for redirects. |
navigation-head | Reconciles the document head and activates staged stylesheets before the swap. |
navigation-commit, navigation-pipeline | The shared commit pipeline that each router plugs its page swap into. |
navigation-view-transition | Wraps the swap in a View Transition. |
navigation-replay | Decides what happens to a click queued during a navigation: nothing for the same page and hash, otherwise a local navigation or one through the coordinator. |
navigation-lifecycle | Dispatches the public events. |
Contract for router authors
@ecopages/core/client exports the pipeline for browser runtime authors: document loading and cache control (fetchNavigationPage, parseNavigationDocument, cacheNavigationHtml, getCachedNavigationHtml, invalidateNavigationHtml, clearNavigationHtmlCache), prefetch and replay policy (shouldPrefetchLink, isSamePageHref, decideQueuedNavigationReplay), staged updates (prepareNavigationHead, activatePreparedNavigationScripts, commitNavigationPage), script activation (activateNavigationScripts, activateScriptsInOrder, collectBodyScripts), loadNavigationGlobalScripts, runNavigationViewTransition, the view-transition style helpers and ECO_PERSIST_ATTRIBUTE. loadNavigationGlobalScripts runs before a router imports the next Page's modules: it inserts the incoming document's data-eco-global-script scripts that the live head lacks and waits until they have run, so a hook a Component module reads while it evaluates is in place. A custom runtime commits through commitNavigationPage and never dispatches the lifecycle events itself. The order of a commit is in Browser router.
- Head keys. Head elements are keyed by identity: meta
name,property,http-equivorcharset; a link byreland resolvedhref(one key for all icons, one for the canonical), so two links to the same stylesheet URL count as one; a script by its navigation identity. Elements the incoming page lacks are removed unless persisted, and a link whose URL already resolves to the incoming one is not rewritten, so the stylesheet does not reload. - Staged stylesheets. New stylesheets load with
media="not all"so they cannot affect the outgoing page, and uniquely keyed styles follow the destination's cascade order.prepareNavigationHead()exposesrequiresReload, re-evaluated on every read: true when a stylesheet failed, a persisted style or stylesheet would change order, or a later update broke the prepared order. A caller checks it right before committing and navigates the document instead;commit()throws when it is true. A later commit that removes a staged link settles its load wait, so the superseded navigation finishes. - Script identity. A script matches across pages by
data-eco-script-id, thenid, then itssrcresolved against the document base, then its trimmed inline content. Adata-eco-rerunscript keeps its originalsrcindata-eco-rerun-src, so it is replaced across pages with different<base>URLs while the new copy loads from the incoming page's resolved URL. - HTML cache. Browser-router prefetches into the shared cache and reads it on click; react-router fetches with
bypassCacheand only writes to it. - View transitions. The update callback of
runNavigationViewTransition()returnsfalsewhen it did not commit; a void result counts as committed. A later navigation supersedes cleanup from earlier transitions, and a failed or uncommitted swap clears transition names.
Lifecycle events
eco:before-swap, eco:after-swap and eco:page-load are the public contract for dev tooling, global injectors and layout scripts. Dispatch helpers live in navigation-lifecycle.ts so both routers stay aligned. eco:before-swap reports whether a listener asked for a reload. eco:after-swap fires after the commit, and eco:page-load is scheduled on the next animation frame unless a newer navigation replaced this one. Router specifics, such as the body morph and persisted elements, are in Browser router; React's page swap is in React router. The HMR client reaches both through reloadCurrentPage; see HMR client.
Sources
This page describes the code below.