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:

CapabilityPurpose
navigateNavigate to a request routed to this owner.
handoffNavigationAccept a document another runtime already fetched.
reloadCurrentPageRe-render the current URL in place; clearCache discards cached client state and moduleUrl forces a page entry.
cleanupBeforeHandoffRelease 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.
enableReloadStatePreservationStart keeping what reloadCurrentPage needs to preserve state.

The coordinator arbitrates three things:

  • Ownership. claimOwnership and releaseOwnership track the active owner (browser-router, react-router or none). A rendered document names its owner in data-eco-document-owner; adoptDocumentOwner reads it, and a document without the marker leaves the router on its local default.
  • Transactions. beginNavigationTransaction starts a new navigation and invalidates the previous one. A transaction exposes an AbortSignal, isCurrent() and isSuperseded(). Superseded differs from not current: a navigation that completed normally is no longer current, yet still owes work such as eco:page-load, which is skipped only when a newer navigation replaced it or it was cancelled.
  • Handoff and reload. requestNavigation and requestHandoff send a request or a pre-fetched document to another registered runtime; reloadCurrentPage asks the active owner; enableReloadStatePreservation asks 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

ModuleRole
link-intentFinds 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-policyDecides 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-documentFetches and parses the next page, with an HTML cache and a final-URL map for redirects.
navigation-headReconciles the document head and activates staged stylesheets before the swap.
navigation-commit, navigation-pipelineThe shared commit pipeline that each router plugs its page swap into.
navigation-view-transitionWraps the swap in a View Transition.
navigation-replayDecides 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-lifecycleDispatches 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-equiv or charset; a link by rel and resolved href (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() exposes requiresReload, 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, then id, then its src resolved against the document base, then its trimmed inline content. A data-eco-rerun script keeps its original src in data-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 bypassCache and only writes to it.
  • View transitions. The update callback of runNavigationViewTransition() returns false when 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.