@takazudo/zfb-runtime 2.5.2 → 2.7.0

package/dist/client-router/router.js

@@ -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;
@@ -50,6 +52,7 @@
 //   - `derivePopDirection` hardens the popstate forward/back calc against an unchanged or
 //     missing/NaN `state.index` that a bfcache restore can leave behind (#1076).
 import { doPreparation, doSwap, onPageLoad, triggerEvent, updateScrollPosition, } from "./events.js";
+import { safePushState, safeReplaceState } from "./history-safe.js";
 import { detectScriptExecuted } from "./swap-functions.js";
 // Island re-bootstrap and deferred-cancel after body swap (W1B §12.2, §12.5).
 // mountNewIslands() is called after runScripts() and before onPageLoad().
@@ -145,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
-        history.replaceState({ 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) {
@@ -274,7 +289,7 @@ historyCommittedEarly = false) => {
                 scrollX,
                 scrollY,
             };
-            history.replaceState({
+            safeReplaceState({
                 ...options.state,
                 index: current.index,
                 scrollX: current.scrollX,
@@ -282,7 +297,7 @@ historyCommittedEarly = false) => {
             }, "", to.href);
         }
         else {
-            history.pushState({ ...options.state, index: ++currentHistoryIndex, scrollX: 0, scrollY: 0 }, "", to.href);
+            safePushState({ ...options.state, index: ++currentHistoryIndex, scrollX: 0, scrollY: 0 }, "", to.href);
         }
     }
     document.title = targetPageTitle;
@@ -311,7 +326,7 @@ historyCommittedEarly = false) => {
             const savedState = history.state;
             location.href = to.href; // this kills the history state on Firefox
             if (!history.state) {
-                history.replaceState(savedState, ""); // this restores the history state
+                safeReplaceState(savedState, ""); // this restores the history state
                 if (intraPage) {
                     window.dispatchEvent(new PopStateEvent("popstate"));
                 }
@@ -368,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
@@ -382,7 +400,7 @@ export function syncHistoryEntry(url, options = {}) {
         // the tracked index rather than stamping NaN/undefined.
         const current = history.state;
         const index = current != null && Number.isFinite(current.index) ? current.index : currentHistoryIndex;
-        history.replaceState({
+        safeReplaceState({
             ...options.state,
             index,
             scrollX: Number.isFinite(current?.scrollX) ? current.scrollX : scrollX,
@@ -401,7 +419,7 @@ export function syncHistoryEntry(url, options = {}) {
         // historyState branch below) scrollTo(0,0) when this entry is later
         // Forward-reopened, snapping the page to the top under the reopened
         // dialog. #1398.
-        history.pushState({ ...options.state, index: ++currentHistoryIndex, scrollX, scrollY }, "", to.href);
+        safePushState({ ...options.state, index: ++currentHistoryIndex, scrollX, scrollY }, "", to.href);
     }
     // Always re-point originalLocation so the next transition()/onPopState uses the
     // correct "from" URL. Skipping this is exactly what makes a raw pushState
@@ -693,7 +711,7 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
                 scrollX,
                 scrollY,
             };
-            history.replaceState({
+            safeReplaceState({
                 ...options.state,
                 index: current.index,
                 scrollX: current.scrollX,
@@ -701,7 +719,7 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
             }, "", prepEvent.to.href);
         }
         else {
-            history.pushState({ ...options.state, index: ++currentHistoryIndex, scrollX: 0, scrollY: 0 }, "", prepEvent.to.href);
+            safePushState({ ...options.state, index: ++currentHistoryIndex, scrollX: 0, scrollY: 0 }, "", prepEvent.to.href);
         }
     }
     if (supportsViewTransitions && !hasUAVisualTransition) {
@@ -809,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) {
@@ -863,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)) {
@@ -888,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.
@@ -1045,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