*navigate / n-navigate

Summary

*navigate sends an explicit navigation target through the navigation adapter. The adapter decides how the current environment should perform that navigation.

*navigate is the trigger side of Navigate Pager. Sercrod itself does not globally intercept normal links.

Basic example

<serc-rod>
  <button type="button" *navigate="'/spa/home.html'">Home</button>
  <button type="button" *navigate="'/spa/a.html'">A</button>

  <section *page="'/spa/home.html'"></section>
  <section *page="'/spa/a.html'"></section>
</serc-rod>

The value of *navigate is evaluated and sent as target. It is matched directly against *page values in the same host.

Browser adapter

Load the distributable navigation adapter after the runtime:

<script src="/sercrod.js"></script>
<script src="./adapters/navigation.js"></script>

The distributable source is dist/adapters/navigation.js. The complete browser and Capacitor example is sandbox/app/navigation/; it uses the same directive markup in both environments and requires no native Capacitor plugin.

When the Navigation API is available, the browser adapter calls:

navigation.navigate(target, { info: { sercrod: true } });

It then intercepts only matching same-origin *page targets through the browser navigate event. If the Navigation API is unavailable, fallback uses history.pushState() and popstate.

After a navigation target is handled, the host uses document.startViewTransition() for the matching *page activation when the browser supports it and the feature is enabled. This does not change *navigate semantics; it only lets supported browsers animate the page swap. Unsupported browsers, reduced-motion users, hosts with no-view-transition or n-no-view-transition, configuration window.__Sercrod.config.navigation.view_transitions = false, initial activation, and same-page activation all use the existing non-transition path.

Behavior

• *navigate and n-navigate are aliases.
• The value is evaluated as an expression; use quoted string values such as *navigate="'/spa/a.html'".
• Empty targets warn and do nothing.
• Sercrod does not infer targets from href, id, hash fragments, or CSS selectors.
• The click handler asks the adapter synchronously whether it handled the navigation. Async page fetching happens later in the activation path.

Service Worker fallback

The browser adapter can register the app-scope adapter copy as a Service Worker so a normal reload on /spa/a.html can return the shell, such as /spa/index.html, while ordinary partial fetches still pass through.

The fallback is enabled by default. Disable it before loading the adapter when a project does not want Service Worker behavior:

window.__Sercrod = window.__Sercrod || {};
window.__Sercrod.config = window.__Sercrod.config || {};
window.__Sercrod.config.navigation = {
  service_worker: false
};

When the adapter is loaded from an adapters/ subdirectory, use an app-root navigation-worker.js that imports ./adapters/navigation.js, and configure it as service_worker_script. This gives the worker the app scope without a Service-Worker-Allowed header. Capacitor does not need this browser reload fallback.