From 033e1d4d255010353cdba86dc1e4bf89dd5bc3af Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 01:53:14 +1100
Subject: [PATCH 1/7] fix: emit hashChangeStart/Complete and
 beforeHistoryChange events

Next.js emits hashChangeStart/hashChangeComplete for hash-only
navigation and beforeHistoryChange before every history.pushState/
replaceState call. Our router emitted neither.

- Hash-only push/replace now emit hashChangeStart before and
  hashChangeComplete after (instead of routeChange* events)
- Normal push/replace now emit beforeHistoryChange between
  routeChangeStart and the pushState/replaceState call
- All events now pass { shallow } as the second argument per Next.js
- Popstate handler also emits beforeHistoryChange
- Updated in both useRouter() hook and Router singleton code paths
---
 packages/vinext/src/shims/router.ts           | 33 +++++++---
 tests/e2e/pages-router/router-events.spec.ts  | 62 +++++++++++++++++++
 .../pages-basic/pages/router-events-test.tsx  | 25 ++++++++
 3 files changed, 110 insertions(+), 10 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index d3c9ff58..2377d371 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -505,22 +505,25 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
+        routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
         scrollToHash(hash);
         setState(getPathnameAndQuery());
+        routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
         return true;
       }
 
       saveScrollPosition();
-      routerEvents.emit("routeChangeStart", resolved);
+      routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
       window.history.pushState({}, "", full);
       if (!options?.shallow) {
         await navigateClient(full);
       }
       setState(getPathnameAndQuery());
-      routerEvents.emit("routeChangeComplete", resolved);
+      routerEvents.emit("routeChangeComplete", resolved, { shallow: options?.shallow ?? false });
 
       // Scroll: handle hash target, else scroll to top unless scroll:false
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
@@ -553,21 +556,24 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
+        routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
         scrollToHash(hash);
         setState(getPathnameAndQuery());
+        routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
         return true;
       }
 
-      routerEvents.emit("routeChangeStart", resolved);
+      routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
       window.history.replaceState({}, "", full);
       if (!options?.shallow) {
         await navigateClient(full);
       }
       setState(getPathnameAndQuery());
-      routerEvents.emit("routeChangeComplete", resolved);
+      routerEvents.emit("routeChangeComplete", resolved, { shallow: options?.shallow ?? false });
 
       // Scroll: handle hash target, else scroll to top unless scroll:false
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
@@ -641,9 +647,10 @@ if (typeof window !== "undefined") {
       if (!shouldContinue) return;
     }
 
-    routerEvents.emit("routeChangeStart", appUrl);
+    routerEvents.emit("routeChangeStart", appUrl, { shallow: false });
+    routerEvents.emit("beforeHistoryChange", appUrl, { shallow: false });
     void navigateClient(browserUrl).then(() => {
-      routerEvents.emit("routeChangeComplete", appUrl);
+      routerEvents.emit("routeChangeComplete", appUrl, { shallow: false });
       restoreScrollPosition(e.state);
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
     });
@@ -693,20 +700,23 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
+      routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
       scrollToHash(hash);
+      routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
       return true;
     }
 
     saveScrollPosition();
-    routerEvents.emit("routeChangeStart", resolved);
+    routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
+    routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
     window.history.pushState({}, "", full);
     if (!options?.shallow) {
       await navigateClient(full);
     }
-    routerEvents.emit("routeChangeComplete", resolved);
+    routerEvents.emit("routeChangeComplete", resolved, { shallow: options?.shallow ?? false });
 
     const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
     if (hash) {
@@ -734,19 +744,22 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
+      routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
       scrollToHash(hash);
+      routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
       return true;
     }
 
-    routerEvents.emit("routeChangeStart", resolved);
+    routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
+    routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
     window.history.replaceState({}, "", full);
     if (!options?.shallow) {
       await navigateClient(full);
     }
-    routerEvents.emit("routeChangeComplete", resolved);
+    routerEvents.emit("routeChangeComplete", resolved, { shallow: options?.shallow ?? false });
 
     const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
     if (hash) {
diff --git a/tests/e2e/pages-router/router-events.spec.ts b/tests/e2e/pages-router/router-events.spec.ts
index e09717bc..5f52563b 100644
--- a/tests/e2e/pages-router/router-events.spec.ts
+++ b/tests/e2e/pages-router/router-events.spec.ts
@@ -54,6 +54,68 @@ test.describe("router.events (Pages Router)", () => {
     expect(events).toContain("complete:/about");
   });
 
+  test("beforeHistoryChange fires between routeChangeStart and routeChangeComplete", async ({
+    page,
+  }) => {
+    await page.click('[data-testid="push-about"]');
+    await expect(page.locator("h1")).toHaveText("About");
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    const startIdx = events.findIndex((e) => e === "start:/about");
+    const beforeIdx = events.findIndex((e) => e === "beforeHistoryChange:/about");
+    const completeIdx = events.findIndex((e) => e === "complete:/about");
+    expect(startIdx).toBeGreaterThanOrEqual(0);
+    expect(beforeIdx).toBeGreaterThan(startIdx);
+    expect(completeIdx).toBeGreaterThan(beforeIdx);
+  });
+
+  test("hashChangeStart and hashChangeComplete fire on hash-only push", async ({ page }) => {
+    await page.click('[data-testid="push-hash"]');
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    // Should NOT fire routeChange events for hash-only navigation
+    expect(events.some((e) => e.startsWith("start:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+  });
+
+  test("hashChangeStart fires before hashChangeComplete on hash push", async ({ page }) => {
+    await page.click('[data-testid="push-hash"]');
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    const startIdx = events.findIndex((e) => e.startsWith("hashChangeStart:"));
+    const completeIdx = events.findIndex((e) => e.startsWith("hashChangeComplete:"));
+    expect(startIdx).toBeGreaterThanOrEqual(0);
+    expect(completeIdx).toBeGreaterThan(startIdx);
+  });
+
+  test("hashChangeStart and hashChangeComplete fire on hash-only replace", async ({ page }) => {
+    await page.click('[data-testid="replace-hash"]');
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("start:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+  });
+
   test("multiple navigations produce multiple event pairs", async ({ page }) => {
     // Navigate to about
     await page.click('[data-testid="push-about"]');
diff --git a/tests/fixtures/pages-basic/pages/router-events-test.tsx b/tests/fixtures/pages-basic/pages/router-events-test.tsx
index 2b2add68..42c8a16e 100644
--- a/tests/fixtures/pages-basic/pages/router-events-test.tsx
+++ b/tests/fixtures/pages-basic/pages/router-events-test.tsx
@@ -42,14 +42,33 @@ export default function RouterEventsTest() {
       setEvents(getStoredEvents());
     };
 
+    const onBeforeHistoryChange = (url: string) => {
+      storeEvent(`beforeHistoryChange:${url}`);
+      setEvents(getStoredEvents());
+    };
+    const onHashStart = (url: string) => {
+      storeEvent(`hashChangeStart:${url}`);
+      setEvents(getStoredEvents());
+    };
+    const onHashComplete = (url: string) => {
+      storeEvent(`hashChangeComplete:${url}`);
+      setEvents(getStoredEvents());
+    };
+
     router.events.on("routeChangeStart", onStart);
     router.events.on("routeChangeComplete", onComplete);
     router.events.on("routeChangeError", onError);
+    router.events.on("beforeHistoryChange", onBeforeHistoryChange);
+    router.events.on("hashChangeStart", onHashStart);
+    router.events.on("hashChangeComplete", onHashComplete);
 
     return () => {
       router.events.off("routeChangeStart", onStart);
       router.events.off("routeChangeComplete", onComplete);
       router.events.off("routeChangeError", onError);
+      router.events.off("beforeHistoryChange", onBeforeHistoryChange);
+      router.events.off("hashChangeStart", onHashStart);
+      router.events.off("hashChangeComplete", onHashComplete);
     };
   }, [router]);
 
@@ -65,6 +84,12 @@ export default function RouterEventsTest() {
       <button data-testid="push-ssr" onClick={() => router.push("/ssr")}>
         Push SSR
       </button>
+      <button data-testid="push-hash" onClick={() => router.push("#section-1")}>
+        Push Hash
+      </button>
+      <button data-testid="replace-hash" onClick={() => router.replace("#section-2")}>
+        Replace Hash
+      </button>
       <button
         data-testid="clear-events"
         onClick={() => {

From 5336ce32363223dc1e545317e32f8fcfd2126e76 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 02:08:35 +1100
Subject: [PATCH 2/7] fix: emit full URL in hash change events, not just
 fragment

When router.push("#section") is called, emit the full resolved URL
(e.g., "/page#section") in hashChangeStart/hashChangeComplete events
instead of just "#section". Matches Next.js behavior where the event
URL includes the pathname.
---
 packages/vinext/src/shims/router.ts          | 38 +++++++++++++++-----
 tests/e2e/pages-router/router-events.spec.ts | 17 +++++----
 2 files changed, 41 insertions(+), 14 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index 2377d371..7b2439ef 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -156,6 +156,12 @@ export function isExternalUrl(url: string): boolean {
   return /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//");
 }
 
+/** Resolve a fragment-only URL to include the current pathname + search */
+function resolveHashUrl(url: string): string {
+  if (!url.startsWith("#") || typeof window === "undefined") return url;
+  return stripBasePath(window.location.pathname, __basePath) + window.location.search + url;
+}
+
 /** Check if a href is only a hash change relative to the current URL */
 export function isHashOnlyChange(href: string): boolean {
   if (href.startsWith("#")) return true;
@@ -505,12 +511,16 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
-        routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
+        routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+          shallow: options?.shallow ?? false,
+        });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
         scrollToHash(hash);
         setState(getPathnameAndQuery());
-        routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
+        routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+          shallow: options?.shallow ?? false,
+        });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
         return true;
       }
@@ -556,12 +566,16 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
-        routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
+        routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+          shallow: options?.shallow ?? false,
+        });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
         scrollToHash(hash);
         setState(getPathnameAndQuery());
-        routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
+        routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+          shallow: options?.shallow ?? false,
+        });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
         return true;
       }
@@ -700,11 +714,15 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
-      routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+        shallow: options?.shallow ?? false,
+      });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
       scrollToHash(hash);
-      routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+        shallow: options?.shallow ?? false,
+      });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
       return true;
     }
@@ -744,11 +762,15 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
-      routerEvents.emit("hashChangeStart", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+        shallow: options?.shallow ?? false,
+      });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
       scrollToHash(hash);
-      routerEvents.emit("hashChangeComplete", resolved, { shallow: options?.shallow ?? false });
+      routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+        shallow: options?.shallow ?? false,
+      });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
       return true;
     }
diff --git a/tests/e2e/pages-router/router-events.spec.ts b/tests/e2e/pages-router/router-events.spec.ts
index 5f52563b..a534618f 100644
--- a/tests/e2e/pages-router/router-events.spec.ts
+++ b/tests/e2e/pages-router/router-events.spec.ts
@@ -73,7 +73,9 @@ test.describe("router.events (Pages Router)", () => {
     expect(completeIdx).toBeGreaterThan(beforeIdx);
   });
 
-  test("hashChangeStart and hashChangeComplete fire on hash-only push", async ({ page }) => {
+  test("hashChangeStart and hashChangeComplete fire on hash-only push with full URL", async ({
+    page,
+  }) => {
     await page.click('[data-testid="push-hash"]');
 
     const events: string[] = await page.evaluate((key) => {
@@ -81,8 +83,9 @@ test.describe("router.events (Pages Router)", () => {
       return raw ? JSON.parse(raw) : [];
     }, STORAGE_KEY);
 
-    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
-    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    // Event URL should include pathname, not just the fragment
+    expect(events).toContain("hashChangeStart:/router-events-test#section-1");
+    expect(events).toContain("hashChangeComplete:/router-events-test#section-1");
     // Should NOT fire routeChange events for hash-only navigation
     expect(events.some((e) => e.startsWith("start:"))).toBe(false);
     expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
@@ -102,7 +105,9 @@ test.describe("router.events (Pages Router)", () => {
     expect(completeIdx).toBeGreaterThan(startIdx);
   });
 
-  test("hashChangeStart and hashChangeComplete fire on hash-only replace", async ({ page }) => {
+  test("hashChangeStart and hashChangeComplete fire on hash-only replace with full URL", async ({
+    page,
+  }) => {
     await page.click('[data-testid="replace-hash"]');
 
     const events: string[] = await page.evaluate((key) => {
@@ -110,8 +115,8 @@ test.describe("router.events (Pages Router)", () => {
       return raw ? JSON.parse(raw) : [];
     }, STORAGE_KEY);
 
-    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
-    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    expect(events).toContain("hashChangeStart:/router-events-test#section-2");
+    expect(events).toContain("hashChangeComplete:/router-events-test#section-2");
     expect(events.some((e) => e.startsWith("start:"))).toBe(false);
     expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
   });

From 0276b52d2f2833f733ae6b888ab77153a8662af8 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 12:49:46 +1100
Subject: [PATCH 3/7] fix: handle hash-only popstate and address review
 feedback

- Detect hash-only back/forward in popstate handler by tracking
  pathname+search across navigations; emit hashChangeStart/Complete
  instead of routeChangeStart/Complete and skip unnecessary page fetch
- Add comment explaining beforeHistoryChange semantics in popstate
  (fires after URL change, emitted for API compatibility)
- Cache resolveHashUrl() result in all 4 hash code paths
- Add beforeHistoryChange negative assertions in hash-only tests
- Add E2E test for hash-only back/forward navigation events
---
 packages/vinext/src/shims/router.ts          | 53 +++++++++++++++++---
 tests/e2e/pages-router/router-events.spec.ts | 30 ++++++++++-
 2 files changed, 74 insertions(+), 9 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index 7b2439ef..da5f8e15 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -511,14 +511,16 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
-        routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+        const eventUrl = resolveHashUrl(resolved);
+        routerEvents.emit("hashChangeStart", eventUrl, {
           shallow: options?.shallow ?? false,
         });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
+        _lastPathnameAndSearch = window.location.pathname + window.location.search;
         scrollToHash(hash);
         setState(getPathnameAndQuery());
-        routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+        routerEvents.emit("hashChangeComplete", eventUrl, {
           shallow: options?.shallow ?? false,
         });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
@@ -529,6 +531,7 @@ export function useRouter(): NextRouter {
       routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
       routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
       window.history.pushState({}, "", full);
+      _lastPathnameAndSearch = window.location.pathname + window.location.search;
       if (!options?.shallow) {
         await navigateClient(full);
       }
@@ -566,14 +569,16 @@ export function useRouter(): NextRouter {
 
       // Hash-only change — no page fetch needed
       if (isHashOnlyChange(resolved)) {
-        routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+        const eventUrl = resolveHashUrl(resolved);
+        routerEvents.emit("hashChangeStart", eventUrl, {
           shallow: options?.shallow ?? false,
         });
         const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
         window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
+        _lastPathnameAndSearch = window.location.pathname + window.location.search;
         scrollToHash(hash);
         setState(getPathnameAndQuery());
-        routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+        routerEvents.emit("hashChangeComplete", eventUrl, {
           shallow: options?.shallow ?? false,
         });
         window.dispatchEvent(new CustomEvent("vinext:navigate"));
@@ -583,6 +588,7 @@ export function useRouter(): NextRouter {
       routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
       routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
       window.history.replaceState({}, "", full);
+      _lastPathnameAndSearch = window.location.pathname + window.location.search;
       if (!options?.shallow) {
         await navigateClient(full);
       }
@@ -643,6 +649,12 @@ export function useRouter(): NextRouter {
 // If it returns false, the navigation is cancelled.
 let _beforePopStateCb: BeforePopStateCallback | undefined;
 
+// Track pathname+search for detecting hash-only back/forward in the popstate
+// handler. Updated after every pushState/replaceState so that popstate can
+// compare the previous value with the (already-changed) window.location.
+let _lastPathnameAndSearch =
+  typeof window !== "undefined" ? window.location.pathname + window.location.search : "";
+
 // Module-level popstate listener: handles browser back/forward by re-rendering
 // the React root with the page at the new URL. This runs regardless of whether
 // any component calls useRouter().
@@ -651,6 +663,10 @@ if (typeof window !== "undefined") {
     const browserUrl = window.location.pathname + window.location.search;
     const appUrl = stripBasePath(window.location.pathname, __basePath) + window.location.search;
 
+    // Detect hash-only back/forward: pathname+search unchanged, only hash differs.
+    const isHashOnly = browserUrl === _lastPathnameAndSearch;
+    _lastPathnameAndSearch = browserUrl;
+
     // Check beforePopState callback
     if (_beforePopStateCb !== undefined) {
       const shouldContinue = (_beforePopStateCb as BeforePopStateCallback)({
@@ -661,7 +677,22 @@ if (typeof window !== "undefined") {
       if (!shouldContinue) return;
     }
 
+    if (isHashOnly) {
+      // Hash-only back/forward — no page fetch needed
+      const hashUrl = appUrl + window.location.hash;
+      routerEvents.emit("hashChangeStart", hashUrl, { shallow: false });
+      scrollToHash(window.location.hash);
+      routerEvents.emit("hashChangeComplete", hashUrl, { shallow: false });
+      window.dispatchEvent(new CustomEvent("vinext:navigate"));
+      return;
+    }
+
     routerEvents.emit("routeChangeStart", appUrl, { shallow: false });
+    // Note: The browser has already updated window.location by the time popstate
+    // fires, so this is not truly "before" the URL change. In Next.js the popstate
+    // handler calls replaceState to store history metadata — beforeHistoryChange
+    // precedes that call, not the URL change itself. We emit it here for API
+    // compatibility.
     routerEvents.emit("beforeHistoryChange", appUrl, { shallow: false });
     void navigateClient(browserUrl).then(() => {
       routerEvents.emit("routeChangeComplete", appUrl, { shallow: false });
@@ -714,13 +745,15 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
-      routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+      const eventUrl = resolveHashUrl(resolved);
+      routerEvents.emit("hashChangeStart", eventUrl, {
         shallow: options?.shallow ?? false,
       });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.pushState({}, "", resolved.startsWith("#") ? resolved : full);
+      _lastPathnameAndSearch = window.location.pathname + window.location.search;
       scrollToHash(hash);
-      routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+      routerEvents.emit("hashChangeComplete", eventUrl, {
         shallow: options?.shallow ?? false,
       });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
@@ -731,6 +764,7 @@ const Router = {
     routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
     routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
     window.history.pushState({}, "", full);
+    _lastPathnameAndSearch = window.location.pathname + window.location.search;
     if (!options?.shallow) {
       await navigateClient(full);
     }
@@ -762,13 +796,15 @@ const Router = {
 
     // Hash-only change
     if (isHashOnlyChange(resolved)) {
-      routerEvents.emit("hashChangeStart", resolveHashUrl(resolved), {
+      const eventUrl = resolveHashUrl(resolved);
+      routerEvents.emit("hashChangeStart", eventUrl, {
         shallow: options?.shallow ?? false,
       });
       const hash = resolved.includes("#") ? resolved.slice(resolved.indexOf("#")) : "";
       window.history.replaceState({}, "", resolved.startsWith("#") ? resolved : full);
+      _lastPathnameAndSearch = window.location.pathname + window.location.search;
       scrollToHash(hash);
-      routerEvents.emit("hashChangeComplete", resolveHashUrl(resolved), {
+      routerEvents.emit("hashChangeComplete", eventUrl, {
         shallow: options?.shallow ?? false,
       });
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
@@ -778,6 +814,7 @@ const Router = {
     routerEvents.emit("routeChangeStart", resolved, { shallow: options?.shallow ?? false });
     routerEvents.emit("beforeHistoryChange", resolved, { shallow: options?.shallow ?? false });
     window.history.replaceState({}, "", full);
+    _lastPathnameAndSearch = window.location.pathname + window.location.search;
     if (!options?.shallow) {
       await navigateClient(full);
     }
diff --git a/tests/e2e/pages-router/router-events.spec.ts b/tests/e2e/pages-router/router-events.spec.ts
index a534618f..7bb17833 100644
--- a/tests/e2e/pages-router/router-events.spec.ts
+++ b/tests/e2e/pages-router/router-events.spec.ts
@@ -86,9 +86,10 @@ test.describe("router.events (Pages Router)", () => {
     // Event URL should include pathname, not just the fragment
     expect(events).toContain("hashChangeStart:/router-events-test#section-1");
     expect(events).toContain("hashChangeComplete:/router-events-test#section-1");
-    // Should NOT fire routeChange events for hash-only navigation
+    // Should NOT fire routeChange or beforeHistoryChange events for hash-only navigation
     expect(events.some((e) => e.startsWith("start:"))).toBe(false);
     expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("beforeHistoryChange:"))).toBe(false);
   });
 
   test("hashChangeStart fires before hashChangeComplete on hash push", async ({ page }) => {
@@ -119,6 +120,33 @@ test.describe("router.events (Pages Router)", () => {
     expect(events).toContain("hashChangeComplete:/router-events-test#section-2");
     expect(events.some((e) => e.startsWith("start:"))).toBe(false);
     expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("beforeHistoryChange:"))).toBe(false);
+  });
+
+  test("hash-only back/forward emits hashChange events, not routeChange", async ({ page }) => {
+    // Push a hash change, then go back — popstate should detect hash-only navigation
+    await page.click('[data-testid="push-hash"]');
+    await page.click('[data-testid="clear-events"]');
+    await page.goBack();
+
+    // Wait for popstate handler to record events
+    await page.waitForFunction((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw).length > 0 : false;
+    }, STORAGE_KEY);
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    // Should emit hashChange events for hash-only back navigation
+    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    // Should NOT emit routeChange or beforeHistoryChange events
+    expect(events.some((e) => e.startsWith("start:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("beforeHistoryChange:"))).toBe(false);
   });
 
   test("multiple navigations produce multiple event pairs", async ({ page }) => {

From 3232c85313c13c7b0f42fd90c36ee17c6d8d17de Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 18:59:03 +1100
Subject: [PATCH 4/7] fix: pass { shallow } to routeChangeError, add goForward
 hash test

- routeChangeError now passes { shallow: false } to match Next.js
  signature (err, url, { shallow }), completing the { shallow }
  migration across all router events
- Add E2E test for hash-only goForward() popstate detection
---
 packages/vinext/src/shims/router.ts          |  2 +-
 tests/e2e/pages-router/router-events.spec.ts | 24 ++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index da5f8e15..bd614670 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -426,7 +426,7 @@ async function navigateClient(url: string): Promise<void> {
     root.render(element);
   } catch (err) {
     console.error("[vinext] Client navigation failed:", err);
-    routerEvents.emit("routeChangeError", err, url);
+    routerEvents.emit("routeChangeError", err, url, { shallow: false });
     window.location.href = url;
   } finally {
     _navInProgress = false;
diff --git a/tests/e2e/pages-router/router-events.spec.ts b/tests/e2e/pages-router/router-events.spec.ts
index 7bb17833..37d34f15 100644
--- a/tests/e2e/pages-router/router-events.spec.ts
+++ b/tests/e2e/pages-router/router-events.spec.ts
@@ -149,6 +149,30 @@ test.describe("router.events (Pages Router)", () => {
     expect(events.some((e) => e.startsWith("beforeHistoryChange:"))).toBe(false);
   });
 
+  test("hash-only forward emits hashChange events, not routeChange", async ({ page }) => {
+    // Push a hash, go back, clear events, then go forward
+    await page.click('[data-testid="push-hash"]');
+    await page.goBack();
+    await page.click('[data-testid="clear-events"]');
+    await page.goForward();
+
+    await page.waitForFunction((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw).length > 0 : false;
+    }, STORAGE_KEY);
+
+    const events: string[] = await page.evaluate((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw) : [];
+    }, STORAGE_KEY);
+
+    expect(events.some((e) => e.startsWith("hashChangeStart:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("hashChangeComplete:"))).toBe(true);
+    expect(events.some((e) => e.startsWith("start:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("complete:"))).toBe(false);
+    expect(events.some((e) => e.startsWith("beforeHistoryChange:"))).toBe(false);
+  });
+
   test("multiple navigations produce multiple event pairs", async ({ page }) => {
     // Navigate to about
     await page.click('[data-testid="push-about"]');

From e318312039def6d0f0b089a928c1e4fef96aeddb Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 19:20:41 +1100
Subject: [PATCH 5/7] fix: include hash in popstate beforeHistoryChange URL,
 stabilize forward test

- beforeHistoryChange in popstate now emits appUrl + window.location.hash
  for consistency with push/replace paths that preserve the hash fragment
- Add waitForFunction between goBack() and clear-events in the forward
  test to prevent race between popstate handler and event clearing
---
 packages/vinext/src/shims/router.ts          | 2 +-
 tests/e2e/pages-router/router-events.spec.ts | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index bd614670..9bc4abef 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -693,7 +693,7 @@ if (typeof window !== "undefined") {
     // handler calls replaceState to store history metadata — beforeHistoryChange
     // precedes that call, not the URL change itself. We emit it here for API
     // compatibility.
-    routerEvents.emit("beforeHistoryChange", appUrl, { shallow: false });
+    routerEvents.emit("beforeHistoryChange", appUrl + window.location.hash, { shallow: false });
     void navigateClient(browserUrl).then(() => {
       routerEvents.emit("routeChangeComplete", appUrl, { shallow: false });
       restoreScrollPosition(e.state);
diff --git a/tests/e2e/pages-router/router-events.spec.ts b/tests/e2e/pages-router/router-events.spec.ts
index 37d34f15..7ff64728 100644
--- a/tests/e2e/pages-router/router-events.spec.ts
+++ b/tests/e2e/pages-router/router-events.spec.ts
@@ -150,9 +150,13 @@ test.describe("router.events (Pages Router)", () => {
   });
 
   test("hash-only forward emits hashChange events, not routeChange", async ({ page }) => {
-    // Push a hash, go back, clear events, then go forward
+    // Push a hash, go back, wait for popstate to settle, clear events, then go forward
     await page.click('[data-testid="push-hash"]');
     await page.goBack();
+    await page.waitForFunction((key) => {
+      const raw = sessionStorage.getItem(key);
+      return raw ? JSON.parse(raw).length > 0 : false;
+    }, STORAGE_KEY);
     await page.click('[data-testid="clear-events"]');
     await page.goForward();
 

From d05e0ac8380b42481dd9a1d1d4b7c07c517a5ebd Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 19:38:55 +1100
Subject: [PATCH 6/7] fix: strip basePath from full-path hash URLs, include
 hash in popstate event URLs

- resolveHashUrl now handles full-path hash URLs (e.g. /base/page#hash)
  by parsing and stripping basePath, not just fragment-only URLs (#foo)
- routeChangeStart and routeChangeComplete in popstate now include
  window.location.hash for consistency with beforeHistoryChange and
  the push/replace code paths
---
 packages/vinext/src/shims/router.ts | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index 9bc4abef..d4b44b07 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -156,10 +156,18 @@ export function isExternalUrl(url: string): boolean {
   return /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//");
 }
 
-/** Resolve a fragment-only URL to include the current pathname + search */
+/** Resolve a hash URL to a basePath-stripped app URL for event payloads */
 function resolveHashUrl(url: string): string {
-  if (!url.startsWith("#") || typeof window === "undefined") return url;
-  return stripBasePath(window.location.pathname, __basePath) + window.location.search + url;
+  if (typeof window === "undefined") return url;
+  if (url.startsWith("#"))
+    return stripBasePath(window.location.pathname, __basePath) + window.location.search + url;
+  // Full-path hash URL — strip basePath for consistency with other events
+  try {
+    const parsed = new URL(url, window.location.href);
+    return stripBasePath(parsed.pathname, __basePath) + parsed.search + parsed.hash;
+  } catch {
+    return url;
+  }
 }
 
 /** Check if a href is only a hash change relative to the current URL */
@@ -687,15 +695,16 @@ if (typeof window !== "undefined") {
       return;
     }
 
-    routerEvents.emit("routeChangeStart", appUrl, { shallow: false });
+    const fullAppUrl = appUrl + window.location.hash;
+    routerEvents.emit("routeChangeStart", fullAppUrl, { shallow: false });
     // Note: The browser has already updated window.location by the time popstate
     // fires, so this is not truly "before" the URL change. In Next.js the popstate
     // handler calls replaceState to store history metadata — beforeHistoryChange
     // precedes that call, not the URL change itself. We emit it here for API
     // compatibility.
-    routerEvents.emit("beforeHistoryChange", appUrl + window.location.hash, { shallow: false });
+    routerEvents.emit("beforeHistoryChange", fullAppUrl, { shallow: false });
     void navigateClient(browserUrl).then(() => {
-      routerEvents.emit("routeChangeComplete", appUrl, { shallow: false });
+      routerEvents.emit("routeChangeComplete", fullAppUrl, { shallow: false });
       restoreScrollPosition(e.state);
       window.dispatchEvent(new CustomEvent("vinext:navigate"));
     });

From acce8f835d85b8b143c350b23c2faefbb5451f9e Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Thu, 12 Mar 2026 21:41:37 +1100
Subject: [PATCH 7/7] fix: update _lastPathnameAndSearch after beforePopState
 check

Move tracker update to after beforePopState confirms navigation
proceeds. Previously, if beforePopState returned false (cancelling
navigation), the tracker was already updated to the new browserUrl,
causing the next popstate to compare against the wrong baseline and
potentially misdetect a route change as hash-only.
---
 packages/vinext/src/shims/router.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/vinext/src/shims/router.ts b/packages/vinext/src/shims/router.ts
index d4b44b07..c3da2baf 100644
--- a/packages/vinext/src/shims/router.ts
+++ b/packages/vinext/src/shims/router.ts
@@ -77,10 +77,6 @@ interface TransitionOptions {
   locale?: string;
 }
 
-// Route event handler types (used by consumers via router.events)
-type _RouteChangeHandler = (url: string) => void;
-type _RouteErrorHandler = (err: Error, url: string) => void;
-
 interface RouterEvents {
   on(event: string, handler: (...args: unknown[]) => void): void;
   off(event: string, handler: (...args: unknown[]) => void): void;
@@ -673,7 +669,6 @@ if (typeof window !== "undefined") {
 
     // Detect hash-only back/forward: pathname+search unchanged, only hash differs.
     const isHashOnly = browserUrl === _lastPathnameAndSearch;
-    _lastPathnameAndSearch = browserUrl;
 
     // Check beforePopState callback
     if (_beforePopStateCb !== undefined) {
@@ -685,6 +680,11 @@ if (typeof window !== "undefined") {
       if (!shouldContinue) return;
     }
 
+    // Update tracker only after beforePopState confirms navigation proceeds.
+    // If beforePopState cancels, the tracker must retain the previous value
+    // so the next popstate compares against the correct baseline.
+    _lastPathnameAndSearch = browserUrl;
+
     if (isHashOnly) {
       // Hash-only back/forward — no page fetch needed
       const hashUrl = appUrl + window.location.hash;