npm - @takazudo/zfb-runtime - Versions diffs - 2.6.0 → 2.7.0 - Mend

@takazudo/zfb-runtime 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/README.md +47 -16
package/dist/client-router/index.js +5 -1
package/dist/client-router/index.js.map +1 -1
package/dist/client-router/router.d.ts +8 -2
package/dist/client-router/router.js +179 -92
package/dist/client-router/router.js.map +1 -1
package/dist/client-router-component.d.ts +74 -0
package/dist/client-router-component.js +157 -0
package/dist/client-router-component.js.map +1 -0
package/dist/client-router.d.ts +1 -72
package/dist/client-router.js +19 -146
package/dist/client-router.js.map +1 -1
package/dist/index.d.ts +1 -1
package/dist/index.js +9 -1
package/dist/index.js.map +1 -1
package/package.json +3 -3

package/README.md CHANGED Viewed

@@ -79,7 +79,7 @@ import type {
 ```ts
 import {
-  ClientRouter,               // framework-agnostic <head> helper — enables view-transition intercepts
+  ClientRouter,               // framework-agnostic <head> helper — mount it to opt a page into SPA navigation
   navigate,                   // imperative navigation
   supportsViewTransitions,    // browser capability check
   transitionEnabledOnThisPage, // reads zfb-view-transitions-enabled meta
@@ -104,6 +104,13 @@ import type { ContentSnapshot } from "@takazudo/zfb-runtime/snapshot";
 import { ClientRouter } from "@takazudo/zfb-runtime/client-router";
 ```
+The two differ in one way that matters: the root barrel is **side-effect-free**
+— importing anything from it, `ClientRouter` included, registers no listeners
+and touches no history — while evaluating the `./client-router` subpath calls
+`init()` and activates the router on the current page. See [Enabling SPA
+soft-navigation](#enabling-spa-soft-navigation-the-runtime-ships-automatically)
+below for how a normal zfb build gets that activation for you.
 #### Enabling SPA soft-navigation (the runtime ships automatically)
 Mounting `<ClientRouter />` in your layout `<head>` is normally **all you need**.
@@ -146,9 +153,15 @@ export default function Layout({ children }) {
   SPA navigation set so traversal behavior is deterministic.
 **How the runtime reaches the browser.** `<ClientRouter />` itself only renders
-SSR `<head>` tags. The click/form interception is registered by an `init()` call
-that runs as a side effect when `@takazudo/zfb-runtime/client-router` is imported
-in the browser, guarded so it never runs during SSR:
+SSR `<head>` tags, and the module it lives in is pure: importing `ClientRouter`
+from the `@takazudo/zfb-runtime` barrel registers nothing and runs no code on
+the page. Everything the router does at startup — seeding this page's history
+entry and scroll position, marking the scripts the initial load already ran, and
+registering the `popstate` / `load` / `pageshow` / scroll listeners plus the
+click and form-submit intercepts — happens inside a single `init()` call.
+`init()` is invoked as a side effect when `@takazudo/zfb-runtime/client-router`
+is evaluated in the browser, guarded so it never runs during SSR:
 ```ts
 // inside @takazudo/zfb-runtime — client-router.ts
@@ -157,6 +170,9 @@ if (typeof document !== "undefined") {
 }
 ```
+`init()` is idempotent: calling it again (a second `<ClientRouter />` mount, an
+HMR re-run, a manual call) is a no-op for the parts already done.
 To get that side-effect import into the client bundle, zfb's island scanner
 detects when a page transitively reaches `<ClientRouter />` and injects
 `import "@takazudo/zfb-runtime/client-router"` into the islands asset
@@ -188,7 +204,10 @@ trigger — firing on them would ship the runtime to projects that only referenc
   `rt.ClientRouter`, and
 - a type-only import — `import type { ClientRouter }` (or `{ type ClientRouter }`).
-If soft-navigation is not working because your reference takes one of these forms
+When detection misses, nothing else picks up the slack: the barrel import is
+side-effect-free, so an undetected `<ClientRouter />` renders its meta tags into
+`<head>` and no runtime is ever shipped to activate against them. If
+soft-navigation is not working because your reference takes one of these forms
 (or the mounting module is otherwise not reachable from a page), force the
 runtime in with an explicit side-effect import from a page-reachable
 `"use client"` island. The island renders nothing; running its bundle in the
@@ -228,17 +247,29 @@ for the full API.
 #### `navigate()` needs `<ClientRouter />` mounted on the current page
-The root barrel exports `navigate` and `syncHistoryEntry`, but **not** `init`
-— importing either of those two on their own is not enough to get soft
-navigation. `navigate()` checks for the `<meta
-name="zfb-view-transitions-enabled">` tag that `<ClientRouter />` renders into
-`<head>` before it will do a soft swap; with that tag absent it silently falls
-back to a full `location.href` load. Mount `<ClientRouter />` in the layout
-`<head>` of every page that should be soft-navigable — it both renders that
-meta tag and calls `init()` (click/form interception) as a side effect. `init`
-itself is exported from the `@takazudo/zfb-runtime/client-router` subpath, not
-the root barrel, for the rare case where you want to call it directly instead
-of mounting the component.
+The root barrel exports `navigate` and `syncHistoryEntry`, but **not** `init`,
+and importing from that barrel installs no interception listeners. Each helper
+still does exactly what its own docs say when you call it — a direct
+`navigate()` call navigates, `syncHistoryEntry()` writes its history entry —
+but nothing starts intercepting the user's link clicks and form submits on
+your behalf.
+Soft navigation needs two separate things on the current page:
+1. **The opt-in meta tag.** `navigate()` reaches `<meta
+   name="zfb-view-transitions-enabled">`, which `<ClientRouter />` renders into
+   `<head>`, before it will do a soft swap; with that tag absent it falls back
+   to a full `location.href` load.
+2. **An activated router.** That comes from `init()` — in a normal zfb build,
+   from the `import "@takazudo/zfb-runtime/client-router"` the island scanner
+   injects once it sees a page reach `<ClientRouter />` (see above).
+So the answer for both is the same: mount `<ClientRouter />` in the layout
+`<head>` of every page that should be soft-navigable, and let the build ship
+the runtime. `init` itself is exported from the
+`@takazudo/zfb-runtime/client-router` subpath, not the root barrel, for the
+rare case where you want to call it directly instead of relying on the
+subpath's own import-time activation.
 #### Persisting elements and island state across navigations (`data-zfb-transition-persist`)

package/dist/client-router/index.js CHANGED Viewed

@@ -1,7 +1,11 @@
 // Public API surface for the client-router module.
 // This file is the barrel for @takazudo/zfb-runtime's client-router export.
 // W3D adds the <ClientRouter /> component and ClientRouterProps re-exports.
-// Component (W3D).
+// Component (W3D). Re-exported via the activation shim `../client-router.js`
+// (not `../client-router-component.js` directly) so importing this subpath
+// barrel — the target of the islands bundler's auto-injected
+// `import "@takazudo/zfb-runtime/client-router"` — keeps activating the
+// router at module eval, byte-compatible with pre-split behavior (#2437).
 export { ClientRouter } from "../client-router.js";
 export { TRANSITION_BEFORE_PREPARATION, TRANSITION_AFTER_PREPARATION, TRANSITION_BEFORE_SWAP, TRANSITION_AFTER_SWAP, TRANSITION_PAGE_LOAD, TRANSITION_NAVIGATION_ABORTED, TransitionBeforePreparationEvent, TransitionBeforeSwapEvent, isTransitionBeforePreparationEvent, isTransitionBeforeSwapEvent, } from "./events.js";
 export { swapFunctions, swap } from "./swap-functions.js";

package/dist/client-router/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client-router/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,4EAA4E;AAC5E,4EAA4E;AAE5E,~~mBAAmB~~;~~AACnB~~,OAAO,EAAE,YAAY,EAA0B,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE1D,yBAAyB;AACzB,sEAAsE;AACtE,oDAAoD;AACpD,yFAAyF;AACzF,iFAAiF;AACjF,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,2BAA2B,EAC3B,IAAI,EACJ,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,kCAAkC;AAClC,8EAA8E;AAC9E,kCAAkC;AAClC,OAAO,EAAE,QAAQ,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC","sourcesContent":["// Public API surface for the client-router module.\n// This file is the barrel for @takazudo/zfb-runtime's client-router export.\n// W3D adds the <ClientRouter /> component and ClientRouterProps re-exports.\n\n// Component (W3D).\nexport { ClientRouter, type ClientRouterProps } from \"../client-router.js\";\n\nexport {\n TRANSITION_BEFORE_PREPARATION,\n TRANSITION_AFTER_PREPARATION,\n TRANSITION_BEFORE_SWAP,\n TRANSITION_AFTER_SWAP,\n TRANSITION_PAGE_LOAD,\n TRANSITION_NAVIGATION_ABORTED,\n TransitionBeforePreparationEvent,\n TransitionBeforeSwapEvent,\n isTransitionBeforePreparationEvent,\n isTransitionBeforeSwapEvent,\n} from \"./events.js\";\n\nexport type {\n Direction,\n Fallback,\n NavigationTypeString,\n Options,\n SyncHistoryEntryOptions,\n} from \"./types.js\";\n\nexport { swapFunctions, swap } from \"./swap-functions.js\";\n\n// Router public surface.\n// - W3C1: `supportsViewTransitions`, `transitionEnabledOnThisPage`.\n// - W3C2: `navigate()` (public navigation entry).\n// - W3C3: `init()` (idempotent bootstrap: registers click + form intercept listeners).\n// - W2 (#1377): `syncHistoryEntry()` (history bookkeeping without navigation).\nexport {\n navigate,\n supportsViewTransitions,\n transitionEnabledOnThisPage,\n init,\n syncHistoryEntry,\n} from \"./router.js\";\nexport type { InitOptions } from \"./router.js\";\n\n// Prefetch public surface (#276).\n// `init` from prefetch.ts is re-exported as `prefetchInit` to avoid colliding\n// with the router's `init` above.\nexport { prefetch, init as prefetchInit } from \"./prefetch.js\";\nexport type { PrefetchStrategy, PrefetchInitOptions, PrefetchOptions } from \"./prefetch.js\";\n"]}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client-router/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,4EAA4E;AAC5E,4EAA4E;AAE5E,6EAA6E;AAC7E,2EAA2E;AAC3E,6DAA6D;AAC7D,wEAAwE;AACxE,0EAA0E;AAC1E,OAAO,EAAE,YAAY,EAA0B,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,6BAA6B,EAC7B,4BAA4B,EAC5B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,EAChC,yBAAyB,EACzB,kCAAkC,EAClC,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAE1D,yBAAyB;AACzB,sEAAsE;AACtE,oDAAoD;AACpD,yFAAyF;AACzF,iFAAiF;AACjF,OAAO,EACL,QAAQ,EACR,uBAAuB,EACvB,2BAA2B,EAC3B,IAAI,EACJ,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,kCAAkC;AAClC,8EAA8E;AAC9E,kCAAkC;AAClC,OAAO,EAAE,QAAQ,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC","sourcesContent":["// Public API surface for the client-router module.\n// This file is the barrel for @takazudo/zfb-runtime's client-router export.\n// W3D adds the <ClientRouter /> component and ClientRouterProps re-exports.\n\n// Component (W3D). Re-exported via the activation shim `../client-router.js`\n// (not `../client-router-component.js` directly) so importing this subpath\n// barrel — the target of the islands bundler's auto-injected\n// `import \"@takazudo/zfb-runtime/client-router\"` — keeps activating the\n// router at module eval, byte-compatible with pre-split behavior (#2437).\nexport { ClientRouter, type ClientRouterProps } from \"../client-router.js\";\n\nexport {\n TRANSITION_BEFORE_PREPARATION,\n TRANSITION_AFTER_PREPARATION,\n TRANSITION_BEFORE_SWAP,\n TRANSITION_AFTER_SWAP,\n TRANSITION_PAGE_LOAD,\n TRANSITION_NAVIGATION_ABORTED,\n TransitionBeforePreparationEvent,\n TransitionBeforeSwapEvent,\n isTransitionBeforePreparationEvent,\n isTransitionBeforeSwapEvent,\n} from \"./events.js\";\n\nexport type {\n Direction,\n Fallback,\n NavigationTypeString,\n Options,\n SyncHistoryEntryOptions,\n} from \"./types.js\";\n\nexport { swapFunctions, swap } from \"./swap-functions.js\";\n\n// Router public surface.\n// - W3C1: `supportsViewTransitions`, `transitionEnabledOnThisPage`.\n// - W3C2: `navigate()` (public navigation entry).\n// - W3C3: `init()` (idempotent bootstrap: registers click + form intercept listeners).\n// - W2 (#1377): `syncHistoryEntry()` (history bookkeeping without navigation).\nexport {\n navigate,\n supportsViewTransitions,\n transitionEnabledOnThisPage,\n init,\n syncHistoryEntry,\n} from \"./router.js\";\nexport type { InitOptions } from \"./router.js\";\n\n// Prefetch public surface (#276).\n// `init` from prefetch.ts is re-exported as `prefetchInit` to avoid colliding\n// with the router's `init` above.\nexport { prefetch, init as prefetchInit } from \"./prefetch.js\";\nexport type { PrefetchStrategy, PrefetchInitOptions, PrefetchOptions } from \"./prefetch.js\";\n"]}

package/dist/client-router/router.d.ts CHANGED Viewed

@@ -35,8 +35,14 @@ export interface InitOptions {
     prefetchAll?: boolean;
 }
 /**
- * Wire up the client-router's click and form-submit intercepts.
- * Safe to call multiple times — subsequent calls are no-ops (idempotent).
+ * Bootstrap the client router on this page: restore its history entry, mark
+ * the already-executed scripts, and wire up the navigation, click and
+ * form-submit listeners. Safe to call multiple times — each of the two phases
+ * runs at most once (idempotent).
+ *
+ * Evaluating this module does nothing; every side effect the router performs
+ * at startup happens here (#2436). Two once-guards rather than one, because
+ * the phases have different eligibility — see `pageStateSeeded`.
  *
  * @param _options - Forward-compat hook matching Astro's init() signature. Ignored in v1.
  */

package/dist/client-router/router.js CHANGED Viewed

@@ -30,9 +30,11 @@
 // W3C2 additions (this file):
 //   - `navigate()` public entry.
 //   - `onPopState`, `onScrollEnd`.
-//   - Top-level `if (inBrowser)` initialization block (seeds `currentHistoryIndex`
-//     from `history.state`, registers popstate / load / scrollend listeners, and
-//     marks already-executed scripts with `dataset["zfbExec"] = ""`).
+//   - Seeding `currentHistoryIndex` from `history.state`, registering popstate /
+//     load / scrollend listeners, and marking already-executed scripts with
+//     `dataset["zfbExec"] = ""`. W3C2 did all of this in two bare top-level
+//     `if (inBrowser)` blocks; #2436 folded both into `init()` (see the two
+//     once-guards there) so evaluating this module has no side effect at all.
 //
 // W3C1 items deferred to — and since implemented in — W3C3:
 //   - `announce()` route-announcer implementation (see the route-announcer block below;
@@ -146,19 +148,31 @@ let parser;
 // you can figure it using an index. On pushState the index is incremented so you
 // can use that to determine popstate if going forward or back.
 let currentHistoryIndex = 0;
-if (inBrowser) {
-    if (history.state) {
-        // Here we reloaded a page with history state
-        // (e.g. history navigation from non-transition page or browser reload)
-        currentHistoryIndex = history.state.index;
-        scrollTo({ left: history.state.scrollX, top: history.state.scrollY });
-    }
-    else if (transitionEnabledOnThisPage()) {
-        // This page is loaded from the browser address bar or via a link from extern,
-        // it needs a state in the history
-        safeReplaceState({ index: currentHistoryIndex, scrollX, scrollY }, "");
-        history.scrollRestoration = "manual";
-    }
+// Once-guard for the navigation bookkeeping below. `init()` sets it too, so a
+// later ensureNavigationState() can never clobber the activation-time seed.
+let navigationStateSeeded = false;
+/**
+ * Seed the module's navigation bookkeeping — `originalLocation` (declared
+ * without an initializer) and the tracked history index — from the live
+ * document, once.
+ *
+ * Deliberately side-effect free beyond those two variables: it registers no
+ * listener, writes no history entry, never scrolls, and never marks scripts.
+ * All of that belongs to {@link init}. Its only job is to keep an init-less
+ * `navigate()` / `syncHistoryEntry()` from reading `undefined` or stamping a
+ * fresh entry with the module default index — using the router without
+ * activating it is documented as unsupported, but it must not throw and must
+ * not mis-stamp. An existing finite `history.state.index` is ADOPTED, never
+ * reset: on a page whose entry is already index 7, the next push must be 8. (#2436)
+ */
+function ensureNavigationState() {
+    if (navigationStateSeeded || !inBrowser)
+        return;
+    navigationStateSeeded = true;
+    originalLocation = new URL(location.href);
+    const index = history.state?.index;
+    if (Number.isFinite(index))
+        currentHistoryIndex = index;
 }
 // returns the contents of the page or null if the router can't deal with it.
 async function fetchHTML(href, init) {
@@ -369,6 +383,9 @@ export function syncHistoryEntry(url, options = {}) {
         }
         return;
     }
+    // Adopt this page's existing history index before stamping an entry — an
+    // init-less caller must not reset a live entry's index to the module default.
+    ensureNavigationState();
     const to = new URL(url, location.href);
     // Cross-origin is not ours to manage. The History API would throw a native
     // SecurityError for a cross-origin URL, but we guard explicitly so the failure
@@ -810,6 +827,9 @@ export async function navigate(href, options) {
         }
         return;
     }
+    // `originalLocation` is seeded by init(); seed it here too so an init-less
+    // caller never hands transition() an undefined "from" URL.
+    ensureNavigationState();
     await transition("forward", originalLocation, new URL(href, location.href), options ?? {});
 }
 function onPopState(ev) {
@@ -864,22 +884,22 @@ const onScrollEnd = () => {
 };
 // zfb-only addition (no Astro upstream — see file header "zfb-only additions").
 // WebKit serves Back navigations after an SPA route change from the bfcache:
-// the page is restored without re-evaluating this module, so the init-block
-// seed below (which sets `currentHistoryIndex` from `history.state.index`)
-// never re-runs and the tracked index can desync from the live history stack.
-// A desynced index makes onPopState's direction calc misfire, so Back skips an
-// entry. On a persisted (bfcache) restore we re-seed the tracked index and the
-// `originalLocation` "from" URL from the live state, and restore scroll —
-// mirroring the init-block seed. This is a no-op on a normal load (`persisted`
-// falsy/absent) and idempotent (re-seeding from the same state twice changes
-// nothing and fires no transition).
+// the page is restored without re-evaluating this module or re-running init(),
+// so `seedPageState()` below (which sets `currentHistoryIndex` from
+// `history.state.index`) never re-runs and the tracked index can desync from
+// the live history stack. A desynced index makes onPopState's direction calc
+// misfire, so Back skips an entry. On a persisted (bfcache) restore we re-seed
+// the tracked index and the `originalLocation` "from" URL from the live state,
+// and restore scroll — mirroring that seed. This is a no-op on a normal load
+// (`persisted` falsy/absent) and idempotent (re-seeding from the same state
+// twice changes nothing and fires no transition).
 const onPageShow = (ev) => {
-    // Normal (non-bfcache) loads already ran the init-block seed; leave them be.
+    // Normal (non-bfcache) loads already ran init()'s seed; leave them be.
     if (!ev.persisted)
         return;
-    // The init block sets `originalLocation` and `currentHistoryIndex` together;
-    // re-sync both here so the next transition() gets the correct `from` URL
-    // (a stale `originalLocation` would feed onPopState the wrong origin).
+    // init() seeds `originalLocation` and `currentHistoryIndex` together; re-sync
+    // both here so the next transition() gets the correct `from` URL (a stale
+    // `originalLocation` would feed onPopState the wrong origin).
     originalLocation = new URL(location.href);
     const index = history.state?.index;
     if (Number.isFinite(index)) {
@@ -889,67 +909,116 @@ const onPageShow = (ev) => {
         scrollTo({ left: history.state.scrollX, top: history.state.scrollY });
     }
 };
-// initialization
-if (inBrowser) {
-    if (supportsViewTransitions || getFallback() !== "none") {
-        originalLocation = new URL(location.href);
-        addEventListener("popstate", onPopState);
-        addEventListener("load", onPageLoad);
-        // Re-sync the tracked history index + scroll on a WebKit bfcache restore;
-        // a no-op on normal loads. See onPageShow above.
-        addEventListener("pageshow", onPageShow);
-        // There's not a good way to record scroll position before a history back
-        // navigation, so we will record it when the user has stopped scrolling.
-        if ("onscrollend" in window)
-            addEventListener("scrollend", onScrollEnd);
-        else {
-            // Keep track of state between intervals
-            let intervalId, lastY, lastX, lastIndex;
-            const scrollInterval = () => {
-                // The interval can outlive its document context — a test-env teardown or a
-                // real page unload removes window/history before the 50ms tick. `typeof`
-                // never throws even when the global is gone: stop the interval and bail
-                // rather than dereferencing a torn-down global (the #1061 bug class; #1063).
-                // In a real browser these globals always exist, so this path is test-env
-                // only. clearInterval may itself be mid-teardown, so guard the call too.
-                if (typeof window === "undefined" || typeof history === "undefined") {
-                    if (typeof clearInterval === "function")
-                        clearInterval(intervalId);
-                    intervalId = undefined;
-                    return;
-                }
-                // Check the index to see if a popstate event was fired
-                if (lastIndex !== history.state?.index) {
-                    clearInterval(intervalId);
-                    intervalId = undefined;
-                    return;
-                }
-                // Check if the user stopped scrolling
-                if (lastY === scrollY && lastX === scrollX) {
-                    // Cancel the interval and update scroll positions
-                    clearInterval(intervalId);
-                    intervalId = undefined;
-                    onScrollEnd();
-                    return;
-                }
-                else {
-                    ((lastY = scrollY), (lastX = scrollX));
-                }
-            };
-            // We can't know when or how often scroll events fire, so we'll just use them to start intervals
-            addEventListener("scroll", () => {
-                if (intervalId !== undefined)
-                    return;
-                ((lastIndex = history.state?.index), (lastY = scrollY), (lastX = scrollX));
-                intervalId = window.setInterval(scrollInterval, 50);
-            }, { passive: true });
+// ---- initialization (folded out of module scope by #2436) ----
+// Once-guard for the page-state phase of init(). Deliberately SEPARATE from the
+// `initialized` latch below, because the two phases have different eligibility:
+// this one runs on EVERY browser page — including one where view transitions
+// are ineligible (no native support and fallback "none") — while the activation
+// listeners are VT-gated. A single shared latch would either skip this phase
+// forever after an ineligible early call, or latch activation on a page that
+// never qualified for it. (#2436)
+let pageStateSeeded = false;
+/**
+ * Everything module evaluation used to do for EVERY browser page, regardless
+ * of view-transition eligibility: restore (or seed) this page's history entry
+ * and its scroll position, and mark the scripts the initial page load already
+ * executed so runScripts() does not re-run them after a swap.
+ *
+ * Called from init() BEFORE its eligibility early-return — that gating
+ * asymmetry is load-bearing and predates the fold: a page with fallback "none"
+ * still needs its history entry restored and its scripts marked. (#2436)
+ */
+function seedPageState() {
+    if (pageStateSeeded)
+        return;
+    pageStateSeeded = true;
+    if (history.state) {
+        // Here we reloaded a page with history state
+        // (e.g. history navigation from non-transition page or browser reload)
+        // Adopt only a finite index — a foreign pre-init history.state (e.g. a
+        // consumer's own replaceState({modal: true})) has no router index, and
+        // adopting undefined would stamp the next push with NaN. Same guard as
+        // ensureNavigationState() and onPageShow(). (#2436)
+        const index = history.state.index;
+        if (Number.isFinite(index))
+            currentHistoryIndex = index;
+        // Skip the scroll restore when an init-less navigate()/syncHistoryEntry()
+        // already ran on this page (navigationStateSeeded latched before init):
+        // the entry it pushed is stamped scrollX/scrollY 0, and a late-activating
+        // init() must not yank the already-scrolled viewport to the top. (#2436)
+        if (!navigationStateSeeded) {
+            scrollTo({ left: history.state.scrollX, top: history.state.scrollY });
         }
     }
+    else if (transitionEnabledOnThisPage()) {
+        // This page is loaded from the browser address bar or via a link from extern,
+        // it needs a state in the history
+        safeReplaceState({ index: currentHistoryIndex, scrollX, scrollY }, "");
+        history.scrollRestoration = "manual";
+    }
     for (const script of document.getElementsByTagName("script")) {
         detectScriptExecuted(script);
         script.dataset["zfbExec"] = "";
     }
 }
+/**
+ * Register the window-level navigation listeners. Called from init() only
+ * after the view-transition eligibility check, and only once — the
+ * `initialized` latch owns this phase.
+ */
+function registerNavigationListeners() {
+    addEventListener("popstate", onPopState);
+    addEventListener("load", onPageLoad);
+    // Re-sync the tracked history index + scroll on a WebKit bfcache restore;
+    // a no-op on normal loads. See onPageShow above.
+    addEventListener("pageshow", onPageShow);
+    // There's not a good way to record scroll position before a history back
+    // navigation, so we will record it when the user has stopped scrolling.
+    if ("onscrollend" in window)
+        addEventListener("scrollend", onScrollEnd);
+    else {
+        // Keep track of state between intervals
+        let intervalId, lastY, lastX, lastIndex;
+        const scrollInterval = () => {
+            // The interval can outlive its document context — a test-env teardown or a
+            // real page unload removes window/history before the 50ms tick. `typeof`
+            // never throws even when the global is gone: stop the interval and bail
+            // rather than dereferencing a torn-down global (the #1061 bug class; #1063).
+            // In a real browser these globals always exist, so this path is test-env
+            // only. clearInterval may itself be mid-teardown, so guard the call too.
+            if (typeof window === "undefined" || typeof history === "undefined") {
+                if (typeof clearInterval === "function")
+                    clearInterval(intervalId);
+                intervalId = undefined;
+                return;
+            }
+            // Check the index to see if a popstate event was fired
+            if (lastIndex !== history.state?.index) {
+                clearInterval(intervalId);
+                intervalId = undefined;
+                return;
+            }
+            // Check if the user stopped scrolling
+            if (lastY === scrollY && lastX === scrollX) {
+                // Cancel the interval and update scroll positions
+                clearInterval(intervalId);
+                intervalId = undefined;
+                onScrollEnd();
+                return;
+            }
+            else {
+                ((lastY = scrollY), (lastX = scrollX));
+            }
+        };
+        // We can't know when or how often scroll events fire, so we'll just use them to start intervals
+        addEventListener("scroll", () => {
+            if (intervalId !== undefined)
+                return;
+            ((lastIndex = history.state?.index), (lastY = scrollY), (lastX = scrollX));
+            intervalId = window.setInterval(scrollInterval, 50);
+        }, { passive: true });
+    }
+}
 // ---- W3C3: click + form intercept, public idempotent init() ----
 // Returns true when the modifier-key combo or mouse button means "open in new tab / download".
 // Matches Astro's `leavesWindow` helper in ClientRouter.astro.
@@ -1046,26 +1115,44 @@ function handleSubmit(ev) {
     ev.preventDefault();
     navigate(action, options);
 }
-// Guard flag — ensures click + submit listeners are registered only once even if
-// init() is called multiple times (e.g. two <ClientRouter> mounts on the same page).
+// Guard flag — ensures the activation listeners (popstate/load/pageshow/scroll
+// plus click + submit) are registered only once even if init() is called
+// multiple times (e.g. two <ClientRouter> mounts on the same page).
 let initialized = false;
 /**
- * Wire up the client-router's click and form-submit intercepts.
- * Safe to call multiple times — subsequent calls are no-ops (idempotent).
+ * Bootstrap the client router on this page: restore its history entry, mark
+ * the already-executed scripts, and wire up the navigation, click and
+ * form-submit listeners. Safe to call multiple times — each of the two phases
+ * runs at most once (idempotent).
+ *
+ * Evaluating this module does nothing; every side effect the router performs
+ * at startup happens here (#2436). Two once-guards rather than one, because
+ * the phases have different eligibility — see `pageStateSeeded`.
  *
  * @param _options - Forward-compat hook matching Astro's init() signature. Ignored in v1.
  */
 export function init(_options) {
-    if (initialized)
-        return;
-    // Latch the guard only AFTER the early-return guards below: an ineligible
-    // early call (no browser, or fallback "none") must not permanently latch
-    // `initialized`, or a later legitimately-eligible init() would no-op forever.
     if (!inBrowser)
         return;
+    // Phase 1 — runs on every browser page, even a view-transition-ineligible
+    // one, and therefore BEFORE the eligibility early-return below.
+    seedPageState();
+    if (initialized)
+        return;
+    // Phase 2 — activation. Latch the guard only AFTER this eligibility check:
+    // an ineligible early call (fallback "none" and no native view transitions)
+    // must not permanently latch `initialized`, or a later legitimately-eligible
+    // init() would no-op forever.
     if (!supportsViewTransitions && getFallback() === "none")
         return;
     initialized = true;
+    // Where we came from, for the first transition() of this page. Re-seeded
+    // unconditionally at activation (as module evaluation used to do), so it
+    // reflects the URL at activation time even if an init-less navigate() or
+    // syncHistoryEntry() already primed it via ensureNavigationState().
+    navigationStateSeeded = true;
+    originalLocation = new URL(location.href);
+    registerNavigationListeners();
     document.addEventListener("click", handleClick);
     document.addEventListener("submit", handleSubmit);
     // Prefetch hook intentionally omitted from v1 — see https://github.com/zudolab/zudo-doc/issues/1527