@takazudo/zfb-runtime 0.1.0-next.9 → 0.1.0-next.91

package/dist/client-router/router.js

@@ -24,7 +24,8 @@
 //   - `inBrowser` evaluates to `typeof document !== "undefined"` rather than relying
 //     on the SSR flag, because the runtime package serves both server- and client-side
 //     code; same observable behavior in browser and on SSR.
-//   - `announce()` is a TODO stub (W3C3 owns the route announcer).
+//   - `announce()` was a TODO stub at W1B port time; W3C3 implemented it and #1063 gave
+//     its 60ms timer explicit lifecycle ownership — see the route-announcer block below.
 //
 // W3C2 additions (this file):
 //   - `navigate()` public entry.
@@ -33,9 +34,21 @@
 //     from `history.state`, registers popstate / load / scrollend listeners, and
 //     marks already-executed scripts with `dataset["zfbExec"] = ""`).
 //
-// W3C1 deferred to W3C3:
-//   - `announce()` route-announcer implementation.
-//   - Click + form intercept.
+// W3C1 items deferred to — and since implemented in — W3C3:
+//   - `announce()` route-announcer implementation (see the route-announcer block below;
+//     timer lifecycle ownership hardened in #1063).
+//   - Click + form intercept (see `handleClick` / `handleSubmit` / `init()` below).
+//
+// zfb-only additions (no Astro upstream — #1076):
+//   - `onPageShow` pageshow/bfcache re-sync, registered inside the init block alongside
+//     popstate/load/scrollend. Verified against live Astro `main`: neither
+//     `transitions/router.ts` nor `ClientRouter.astro` has any pageshow/`persisted`
+//     handler, so this is original design, not a port. WebKit serves Back after an SPA
+//     route change from the bfcache without re-evaluating this module, desyncing the
+//     tracked `currentHistoryIndex` from the live history stack; `onPageShow` re-seeds it
+//     (and restores scroll) on a persisted restore — see the `onPageShow` block below.
+//   - `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 { detectScriptExecuted } from "./swap-functions.js";
 // Island re-bootstrap and deferred-cancel after body swap (W1B §12.2, §12.5).
@@ -53,6 +66,17 @@ const internalFetchHeaders = {};
 const inBrowser = typeof document !== "undefined";
 export const supportsViewTransitions = inBrowser && !!document.startViewTransition;
 export const transitionEnabledOnThisPage = () => inBrowser && !!document.querySelector('[name="zfb-view-transitions-enabled"]');
+// A same-page Back/Forward traversal (two history entries sharing pathname +
+// search) is served from the live DOM by the fast-path in transition() — no
+// re-fetch, no re-swap, no lifecycle events. A per-request SSR page
+// (`prerender = false`) whose server output can differ between two visits to
+// the SAME url opts back INTO the fetch by emitting
+// <meta name="zfb-traverse-refetch" content="true"> (via <ClientRouter
+// traverseRefetch />); skipping the fetch on such a page would pin the stale
+// first-render content. Read from the CURRENT document — for a same-page
+// traverse the current document IS the target page. Mirrors the
+// zfb-prefetch-disabled meta reader. (#1376)
+const traverseRefetchOptedOut = () => inBrowser && !!document.querySelector('meta[name="zfb-traverse-refetch"][content="true"]');
 const samePage = (thisLocation, otherLocation) => thisLocation.pathname === otherLocation.pathname && thisLocation.search === otherLocation.search;
 // The previous navigation that might still be in processing
 let mostRecentNavigation;
@@ -61,24 +85,59 @@ let mostRecentTransition;
 // When we traverse the history, the window.location is already set to the new location.
 // This variable tells us where we came from
 let originalLocation;
-// Route announcer — ported from Astro's announce(). Creates (or reuses) a single
-// shared aria-live <div> per navigation, so screen readers announce the new page title.
+// Route announcer — ported from Astro's announce(). Each navigation appends a fresh
+// aria-live <div> (after removing any prior announcer, so exactly one ever exists) and
+// writes the new page title into it 60ms later, so screen readers announce the new page.
+//
+// zfb deviation from Astro / design decision for #1063 (timer lifecycle ownership):
+//   - The 60ms timer id is stored and cleared when a newer navigation supersedes a
+//     still-pending announcement, so a superseded page's title is never written to a
+//     now-detached announcer. (Astro leaves the timer fire-and-forget.)
+//   - The previous announcer is removed before a new one is appended, so they never
+//     accumulate. We deliberately do NOT *reuse* one element across navigations (which
+//     #1063 floated): a reused live region is detached and re-inserted into the a11y
+//     tree on every body swap, and a repeated title would be a no-op text write — both
+//     make re-announcement unreliable across screen readers. Creating a fresh empty
+//     element and writing text 60ms later is Astro's proven, reliable announce trigger.
+//
 // The 60ms delay is Astro's magic number: screen readers need to see the element change
 // and may miss it if it happens too quickly.
+let announceTimer;
 const announce = () => {
-    let div = document.createElement("div");
+    // A newer navigation supersedes any still-pending announcement: cancel the old
+    // timer so it can't write a now-stale title after this navigation's swap.
+    if (announceTimer !== undefined)
+        window.clearTimeout(announceTimer);
+    // Keep exactly one announcer: drop any leftover from a prior navigation that the
+    // body swap did not already detach.
+    document.querySelector(".zfb-route-announcer")?.remove();
+    const div = document.createElement("div");
     div.setAttribute("aria-live", "assertive");
     div.setAttribute("aria-atomic", "true");
     div.className = "zfb-route-announcer";
     document.body.append(div);
-    setTimeout(() => {
-        let title = document.title || document.querySelector("h1")?.textContent || location.pathname;
+    announceTimer = window.setTimeout(() => {
+        announceTimer = undefined;
+        // This timer can outlive its document context — a test-env teardown
+        // (vitest/happy-dom) or a real page unload removes `document` (and
+        // `location`) before the 60ms elapses. `typeof` is safe even when the
+        // global is gone, so bail out instead of throwing an unhandled
+        // ReferenceError (#1061); the announcement is moot once the page is gone.
+        // Both globals the callback dereferences are checked, not just `document`.
+        if (typeof document === "undefined" || typeof location === "undefined")
+            return;
+        const title = document.title || document.querySelector("h1")?.textContent || location.pathname;
         div.textContent = title;
-    }, 
-    // Screen readers need to see the element change; 60ms is Astro's empirically chosen delay.
-    60);
+    }, 60);
 };
 const PERSIST_ATTR = "data-zfb-transition-persist";
+const attrValueSelector = (attr, value) => value === "" ? `[${attr}=""]` : `[${attr}=${CSS.escape(value)}]`;
+const querySelectorWithAttrValue = (root, selectorPrefix, attr, value) => {
+    const escapedMatch = root.querySelector(`${selectorPrefix}${attrValueSelector(attr, value)}`);
+    if (escapedMatch)
+        return escapedMatch;
+    return (Array.from(root.querySelectorAll(`${selectorPrefix}[${attr}]`)).find((el) => el.getAttribute(attr) === value) ?? null);
+};
 const DIRECTION_ATTR = "data-zfb-transition";
 const OLD_NEW_ATTR = "data-zfb-transition-fallback";
 let parser;
@@ -130,10 +189,19 @@ async function fetchHTML(href, init) {
 export function getFallback() {
     const el = document.querySelector('[name="zfb-view-transitions-fallback"]');
     if (el) {
-        return el.getAttribute("content");
+        // Astro casts `content` straight to Fallback; harden against an arbitrary/typo'd
+        // attribute value by validating against the known set and defaulting to "animate".
+        const content = el.getAttribute("content");
+        if (content === "none" || content === "animate" || content === "swap") {
+            return content;
+        }
     }
     return "animate";
 }
+// Upper bound (ms) for waiting on a single external <script>'s load/error in
+// runScripts(). Not an Astro upstream value — added so a slow/broken external
+// script can never hang the transition indefinitely.
+const EXTERNAL_SCRIPT_WAIT_TIMEOUT = 5000;
 function runScripts() {
     let wait = Promise.resolve();
     let needsWaitForInlineModuleScript = false;
@@ -159,8 +227,17 @@ function runScripts() {
         newScript.innerHTML = script.innerHTML;
         for (const attr of script.attributes) {
             if (attr.name === "src") {
+                // Astro awaits onload/onerror with no upper bound; a slow or broken
+                // external <script> would then hang the whole transition. Race the
+                // load against a timeout so the transition can always proceed.
                 const p = new Promise((r) => {
-                    newScript.onload = newScript.onerror = r;
+                    let timer;
+                    const done = () => {
+                        clearTimeout(timer);
+                        r();
+                    };
+                    newScript.onload = newScript.onerror = done;
+                    timer = setTimeout(done, EXTERNAL_SCRIPT_WAIT_TIMEOUT);
                 });
                 wait = wait.then(() => p);
             }
@@ -173,14 +250,30 @@ function runScripts() {
 }
 // Add a new entry to the browser history. This also sets the new page in the browser address bar.
 // Sets the scroll position according to the hash fragment of the new location.
-const moveToLocation = (to, from, options, pageTitleForBrowserHistory, historyState) => {
+const moveToLocation = (to, from, options, pageTitleForBrowserHistory, historyState, 
+// True when transition() already committed a history entry for THIS
+// navigation before the swap ran (the WebKit-workaround early commit
+// below). `to` here may differ from that committed entry's URL if a
+// `zfb:before-swap` listener mutated `event.to` (writable per Astro
+// parity) after the early commit already ran — in that case we must
+// REPLACE the already-committed entry instead of pushing a second one, or
+// a single navigation would leave two history entries (a phantom Back
+// stop). #1398.
+historyCommittedEarly = false) => {
     const intraPage = samePage(from, to);
     const targetPageTitle = document.title;
     document.title = pageTitleForBrowserHistory;
     let scrolledToTop = false;
     if (to.href !== location.href && !historyState) {
-        if (options.history === "replace") {
-            const current = history.state;
+        if (options.history === "replace" || historyCommittedEarly) {
+            // Astro reads current.index/scrollX/scrollY directly; `history.state` can be
+            // null (page entered without a transition state), which would throw a
+            // TypeError. Fall back to a synthesized state from the tracked index/scroll.
+            const current = history.state ?? {
+                index: currentHistoryIndex,
+                scrollX,
+                scrollY,
+            };
             history.replaceState({
                 ...options.state,
                 index: current.index,
@@ -202,7 +295,12 @@ const moveToLocation = (to, from, options, pageTitleForBrowserHistory, historySt
         scrolledToTop = true;
     }
     if (historyState) {
-        scrollTo(historyState.scrollX, historyState.scrollY);
+        // Raw-History consumers may push partial/empty state (`{}`), so the tracked
+        // scroll fields can be absent or non-finite. Never scrollTo(undefined, …) —
+        // leave scroll where it is rather than jumping to (0,0). #1376.
+        if (Number.isFinite(historyState.scrollX) && Number.isFinite(historyState.scrollY)) {
+            scrollTo(historyState.scrollX, historyState.scrollY);
+        }
     }
     else {
         if (to.hash) {
@@ -227,15 +325,111 @@ const moveToLocation = (to, from, options, pageTitleForBrowserHistory, historySt
         history.scrollRestoration = "manual";
     }
 };
+let syncHistoryEntryOnServerWarned = false;
+/**
+ * Write a router-managed history entry (push or replace) WITHOUT any
+ * navigation, DOM, or lifecycle side effect. This is the supported path for
+ * consumers deep-linking transient UI state (dialogs/modals, a photo
+ * viewer's `/photos/<slug>/` URL). Hand-rolled raw `history.pushState`
+ * desyncs `originalLocation` and the index bookkeeping that popstate
+ * direction detection ({@link derivePopDirection}) and the same-page
+ * traverse fast-path depend on; `navigate()` can't be used instead because
+ * it forces a fetch. See #1377 / #1374.
+ *
+ * Never scrolls the viewport itself — but the entry it writes IS stamped
+ * with the CURRENT scroll position (`scrollX`/`scrollY` at call time), not
+ * `(0, 0)` (issue #1398). This matters only for a later Forward-traversal
+ * back to this entry: the same-page traverse fast-path restores whatever
+ * scroll position was stamped on the entry, so a same-page push (e.g.
+ * opening a dialog) does not snap the underlying page to the top when the
+ * dialog is later reopened via Forward.
+ *
+ * @param url - The URL to write. Cross-origin URLs throw rather than
+ *   silently falling back to a full-page load.
+ * @param options.replace - Use `history.replaceState` instead of
+ *   `history.pushState` (no new Back-button entry). Default: push.
+ * @param options.state - Merged into the entry's `history.state`; the
+ *   router's own bookkeeping keys (`index`, `scrollX`, `scrollY`) always win
+ *   on a colliding key.
+ */
+export function syncHistoryEntry(url, options = {}) {
+    // SSR guard: no window/history to touch. Mirror navigate()'s server no-op +
+    // one-time console warning. Checked at call time via `typeof document` (not the
+    // module-eval `inBrowser` const) so the branch is reachable and behavior is
+    // identical in a real environment (document is always present in a browser).
+    if (typeof document === "undefined") {
+        if (!syncHistoryEntryOnServerWarned) {
+            // instantiate an error for the stacktrace to show to user.
+            const warning = new Error("syncHistoryEntry() was called during a server side render. This may be unintentional as it is expected to be called in response to a client-side user interaction. Please make sure that your usage is correct.");
+            warning.name = "Warning";
+            // biome-ignore lint/suspicious/noConsole: allowed
+            console.warn(warning);
+            syncHistoryEntryOnServerWarned = true;
+        }
+        return;
+    }
+    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
+    // is a clear, documented contract violation rather than an opaque platform
+    // error — and never a silent full-page load. #1377.
+    if (to.origin !== location.origin) {
+        throw new Error(`syncHistoryEntry(): refusing to write a cross-origin history entry for "${to.href}" (current origin: ${location.origin}).`);
+    }
+    if (options.replace) {
+        // Replace keeps the current entry's index. A consumer migrating from raw
+        // history.pushState may have left a missing/invalid index, so fall back to
+        // 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({
+            ...options.state,
+            index,
+            scrollX: Number.isFinite(current?.scrollX) ? current.scrollX : scrollX,
+            scrollY: Number.isFinite(current?.scrollY) ? current.scrollY : scrollY,
+        }, "", to.href);
+    }
+    else {
+        // Persist the CURRENT (outgoing) entry's latest scroll before pushing, so a
+        // later Back restoration can't lose scroll that `scrollend` hasn't flushed
+        // yet — the same guard transition() applies before a non-traverse push.
+        updateScrollPosition({ scrollX, scrollY });
+        // Stamp the CURRENT scroll on the freshly-pushed entry too — NOT (0,0).
+        // This is a same-page push (dialog/photo-viewer pattern): the underlying
+        // page never actually scrolled anywhere, it just gained an overlay. A
+        // (0,0)-stamped entry would make the traverse fast-path (moveToLocation's
+        // 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);
+    }
+    // Always re-point originalLocation so the next transition()/onPopState uses the
+    // correct "from" URL. Skipping this is exactly what makes a raw pushState
+    // desync the router (a same-page Back would miss the traverse fast path).
+    originalLocation = to;
+}
 function preloadStyleLinks(newDocument) {
     const links = [];
     for (const el of newDocument.querySelectorAll("head link[rel=stylesheet]")) {
+        const persistId = el.getAttribute(PERSIST_ATTR);
+        const href = el.getAttribute("href");
+        const existingSelectors = [
+            persistId !== null ? attrValueSelector(PERSIST_ATTR, persistId) : null,
+            href !== null ? `link[rel=stylesheet]${attrValueSelector("href", href)}` : null,
+        ].filter((selector) => selector !== null);
+        const existingLink = (existingSelectors.length ? document.querySelector(existingSelectors.join(", ")) : null) ??
+            (persistId !== null
+                ? querySelectorWithAttrValue(document, "", PERSIST_ATTR, persistId)
+                : null) ??
+            (href !== null
+                ? querySelectorWithAttrValue(document, "link[rel=stylesheet]", "href", href)
+                : null);
         // Do not preload links that are already on the page.
-        if (!document.querySelector(`[${PERSIST_ATTR}="${el.getAttribute(PERSIST_ATTR)}"], link[rel=stylesheet][href="${el.getAttribute("href")}"]`)) {
+        if (href !== null && !existingLink) {
             const c = document.createElement("link");
             c.setAttribute("rel", "preload");
             c.setAttribute("as", "style");
-            c.setAttribute("href", el.getAttribute("href"));
+            c.setAttribute("href", href);
             links.push(new Promise((resolve) => {
                 ["load", "error"].forEach((evName) => c.addEventListener(evName, resolve));
                 document.head.append(c);
@@ -248,7 +442,9 @@ function preloadStyleLinks(newDocument) {
 // if !popstate, update the history entry and scroll position according to toLocation
 // if popState is given, this holds the scroll position for history navigation
 // if fallback === "animate" then simulate view transitions
-async function updateDOM(preparationEvent, options, currentTransition, historyState, fallback) {
+async function updateDOM(preparationEvent, options, currentTransition, historyState, fallback, 
+// Forwarded to moveToLocation() — see its parameter doc. #1398.
+historyCommittedEarly = false) {
     async function animate(phase) {
         function isInfinite(animation) {
             const effect = animation.effect;
@@ -288,9 +484,15 @@ async function updateDOM(preparationEvent, options, currentTransition, historySt
     // trees receive render(null, element) / root.unmount() and their useEffect
     // cleanups fire. Must happen after cancelPendingIslands() and before doSwap()
     // so document.body still points to the old body.
-    unmountIslands();
+    //
+    // Pass the incoming body so unmountIslands can SKIP islands that swapBodyElement
+    // will lift into the new body (a persisted marker matched on both sides). Those
+    // nodes are physically moved, not discarded, so their component instance and
+    // state must survive the swap — unmounting them here would empty the container
+    // before the lift and defeat data-zfb-transition-persist entirely (issue #1389).
+    unmountIslands(document.body, preparationEvent.newDocument.body);
     const swapEvent = await doSwap(preparationEvent, currentTransition.viewTransition, animateFallbackOld);
-    moveToLocation(swapEvent.to, swapEvent.from, options, pageTitleForBrowserHistory, historyState);
+    moveToLocation(swapEvent.to, swapEvent.from, options, pageTitleForBrowserHistory, historyState, historyCommittedEarly);
     triggerEvent("zfb:after-swap");
     // Resolve the finished promise of the simulation's ViewTransition.
     // For 'animate', wait for the new-page animation to complete first.
@@ -331,7 +533,12 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
         updateScrollPosition({ scrollX, scrollY });
     }
     if (samePage(from, to) && !options.formData) {
-        if ((direction !== "back" && to.hash) || (direction === "back" && from.hash)) {
+        if (
+        // Same-page Back/Forward: serve from the live DOM (no re-fetch/re-swap)
+        // unless this page opted back into the fetch (per-request SSR). #1374/#1376.
+        (navigationType === "traverse" && !traverseRefetchOptedOut()) ||
+            (direction !== "back" && to.hash) ||
+            (direction === "back" && from.hash)) {
             moveToLocation(to, from, options, document.title, historyState);
             if (currentNavigation === mostRecentNavigation)
                 mostRecentNavigation = undefined;
@@ -369,8 +576,11 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
             //
             // Note: getNamedItem can return null in real life, even if TypeScript doesn't think so, hence
             // the ?.
+            // `form` can be null (closest() miss, or a form-less form-associated
+            // element) — `!= null` covers both null and undefined so Reflect.get
+            // is never invoked on a non-element receiver ("Illegal invocation").
             init.body =
-                form !== undefined &&
+                form != null &&
                     Reflect.get(HTMLFormElement.prototype, "attributes", form).getNamedItem("enctype")
                         ?.value === "application/x-www-form-urlencoded"
                     ? new URLSearchParams(preparationEvent.formData)
@@ -446,10 +656,58 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
         return;
     }
     document.documentElement.setAttribute(DIRECTION_ATTR, prepEvent.direction);
+    // Commit the SPA history entry BEFORE the transition's update callback runs.
+    //
+    // WebKit (all iOS browsers, incl. iOS Chrome) does not reliably commit a
+    // distinct back/forward history entry when history.pushState() is issued
+    // *inside* the document.startViewTransition() update callback: the URL bar
+    // updates but no new entry is created, so a single Back press falls off the
+    // site to the browser home (zudolab/zzmod#662). Committing the entry here —
+    // outside the transition's update callback — makes WebKit create it; Chromium
+    // is unaffected either way. moveToLocation() (called later from updateDOM,
+    // inside the callback) then no-ops its own push/replace via the
+    // `to.href !== location.href` guard, since location is already at the
+    // committed URL, so currentHistoryIndex is not double-advanced.
+    //
+    // We use prepEvent.to (redirects are already resolved into it during
+    // preparation) and write before the swap, while document.title is still the
+    // old page's title — so the back entry keeps the correct (old-page) title
+    // without needing moveToLocation's title juggle. Writing here also covers the
+    // non-VT fallback path below in one place.
+    //
+    // Traverse (popstate) navigations carry historyState: the browser has already
+    // moved, so they must NOT create a new entry here.
+    //
+    // Tracks whether this block ran (push OR replace) so moveToLocation (called
+    // later, from updateDOM) knows a commit already happened for THIS navigation
+    // — see moveToLocation's `historyCommittedEarly` parameter doc. #1398.
+    let historyCommittedEarly = false;
+    if (!historyState && prepEvent.to.href !== location.href) {
+        historyCommittedEarly = true;
+        if (options.history === "replace") {
+            // Mirror of the moveToLocation replace-path guard: `history.state` can be
+            // null here too (page entered without a transition state), so synthesize a
+            // state from the tracked index/scroll instead of dereferencing null.
+            const current = history.state ?? {
+                index: currentHistoryIndex,
+                scrollX,
+                scrollY,
+            };
+            history.replaceState({
+                ...options.state,
+                index: current.index,
+                scrollX: current.scrollX,
+                scrollY: current.scrollY,
+            }, "", prepEvent.to.href);
+        }
+        else {
+            history.pushState({ ...options.state, index: ++currentHistoryIndex, scrollX: 0, scrollY: 0 }, "", prepEvent.to.href);
+        }
+    }
     if (supportsViewTransitions && !hasUAVisualTransition) {
         // This automatically cancels any previous transition
         // We also already took care that the earlier update callback got through
-        currentTransition.viewTransition = document.startViewTransition(async () => await updateDOM(prepEvent, options, currentTransition, historyState));
+        currentTransition.viewTransition = document.startViewTransition(async () => await updateDOM(prepEvent, options, currentTransition, historyState, undefined, historyCommittedEarly));
     }
     else {
         // Simulation mode requires a bit more manual work.
@@ -459,7 +717,7 @@ async function transition(direction, from, to, options, historyState, hasUAVisua
         const updateDone = (async () => {
             // Immediately paused to set up the ViewTransition object for Fallback mode
             await Promise.resolve(); // hop through the micro task queue
-            await updateDOM(prepEvent, options, currentTransition, historyState, hasUAVisualTransition ? "swap" : getFallback());
+            await updateDOM(prepEvent, options, currentTransition, historyState, hasUAVisualTransition ? "swap" : getFallback(), historyCommittedEarly);
             return undefined;
         })();
         // When the updateDone promise is settled,
@@ -539,6 +797,18 @@ export async function navigate(href, options) {
         }
         return;
     }
+    if (!supportsViewTransitions && getFallback() === "none") {
+        const url = new URL(href, location.href);
+        // Honor the history option on the full-load fallback path: "replace"
+        // must not leave a back-button entry, so use location.replace().
+        if (options?.history === "replace") {
+            location.replace(url.href);
+        }
+        else {
+            location.href = url.href;
+        }
+        return;
+    }
     await transition("forward", originalLocation, new URL(href, location.href), options ?? {});
 }
 function onPopState(ev) {
@@ -558,10 +828,29 @@ function onPopState(ev) {
     }
     const state = history.state;
     const nextIndex = state.index;
-    const direction = nextIndex > currentHistoryIndex ? "forward" : "back";
-    currentHistoryIndex = nextIndex;
+    const direction = derivePopDirection(nextIndex, currentHistoryIndex);
+    // Only advance the tracked index when the entry carries a usable index.
+    // After a bfcache restore the index can be missing/NaN; clobbering the
+    // tracked value with NaN would poison every subsequent direction calc, so
+    // keep the last known-good index in that case (see derivePopDirection).
+    if (Number.isFinite(nextIndex)) {
+        currentHistoryIndex = nextIndex;
+    }
     transition(direction, originalLocation, new URL(location.href), {}, state, ev.hasUAVisualTransition);
 }
+// Decide forward vs back from the popped entry's index against the last
+// tracked index. Two desync cases a WebKit bfcache restore can produce:
+//   - missing / NaN `next` (restored entry lost its index): handled explicitly
+//     below — we cannot prove a forward move, so treat it as "back" (the safe
+//     default; a forward misclassification is what makes Back skip to the wrong
+//     page).
+//   - `next === current` (index unchanged after a desync/replace): falls out of
+//     the `>` comparison as "back" — not a forward navigation.
+function derivePopDirection(nextIndex, trackedIndex) {
+    if (!Number.isFinite(nextIndex))
+        return "back";
+    return nextIndex > trackedIndex ? "forward" : "back";
+}
 const onScrollEnd = () => {
     // NOTE: our "popstate" event handler may call `pushState()` or
     // `replaceState()` and then `scrollTo()`, which will fire "scroll" and
@@ -572,12 +861,42 @@ const onScrollEnd = () => {
         updateScrollPosition({ scrollX, scrollY });
     }
 };
+// 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).
+const onPageShow = (ev) => {
+    // Normal (non-bfcache) loads already ran the init-block 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).
+    originalLocation = new URL(location.href);
+    const index = history.state?.index;
+    if (Number.isFinite(index)) {
+        currentHistoryIndex = index;
+    }
+    if (history.state) {
+        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)
@@ -586,6 +905,18 @@ if (inBrowser) {
             // 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);
@@ -726,11 +1057,14 @@ let initialized = false;
 export function init(_options) {
     if (initialized)
         return;
-    initialized = true;
+    // 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;
     if (!supportsViewTransitions && getFallback() === "none")
         return;
+    initialized = true;
     document.addEventListener("click", handleClick);
     document.addEventListener("submit", handleSubmit);
     // Prefetch hook intentionally omitted from v1 — see https://github.com/zudolab/zudo-doc/issues/1527