In a vanilla JavaScript router, calling history.pushState({}, '', '/about') updates the address bar but the view never changes and the window's popstate listener never runs. Why does the browser not notify you, and what must the router do instead?

## What pushState actually does `history.pushState(state, unused, url)` performs exactly three things: it serializes `state` and stores it on a **new** session history entry, sets that entry's URL to `url`, and makes it the current entry. It does not fetch anything, does not replace the document, does not run `beforeunload`, does not reset scroll position, and does not fire an event. A few mechanical details are worth carrying into an interview. The second argument is a title that every browser ignores; the convention is to pass `''`. The `url` argument is resolved against the current document's URL, so `pushState({}, '', 'about')` from `/docs/` yields `/docs/about`. It must be **same-origin**, and a cross-origin value throws a `SecurityError`. Passing no URL (or the same one) keeps the address bar unchanged while still creating an entry — occasionally useful for capturing a state snapshot. ## Why popstate does not fire The HTML specification fires `popstate` when the browser **traverses** session history to a different entry within the same document. Traversal means the Back or Forward button, a keyboard or trackpad back gesture, or `history.back()` / `history.forward()` / `history.go(n)`. It does not mean "the current entry changed by script". The design is intentional. If `pushState` fired `popstate`, every router would immediately re-enter its own handler and would have to distinguish self-inflicted events from user-driven ones. Instead the split is clean: **you push, so you render; the user traverses, so the browser tells you.** `hashchange` is the same story from the other direction. It fires when the document's fragment changes through a navigation — clicking `<a href="#section">`, assigning `location.hash` — and it too is not fired by `pushState`, even when the pushed URL differs only in its fragment. ## The three pieces of a client router ```js const routes = { '/': Home, '/about': About }; function render() { const view = routes[location.pathname] ?? NotFound; document.querySelector('#app').replaceChildren(view()); } function navigate(url) { history.pushState(null, '', url); render(); // pushState will not do this for you } window.addEventListener('popstate', render); // Back / Forward render(); // first paint ``` The missing third piece is link interception. A plain `<a href="/about">` still performs a full cross-document navigation, which throws the whole SPA away and reloads it. Routers attach one delegated click listener on `document` and call `preventDefault()` only when the click is safe to hijack: ```js document.addEventListener('click', (e) => { const a = e.target.closest('a'); if (!a || e.defaultPrevented) return; if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; // new tab / window if (a.target && a.target !== '_self') return; if (a.hasAttribute('download') || a.origin !== location.origin) return; e.preventDefault(); navigate(a.pathname + a.search + a.hash); }); ``` Every one of those guards exists because a user did something reasonable that the naive version broke: cmd-click to open in a new tab, a download link, an external link, a link with `target="_blank"`. ## Symptoms in the wild - **URL changes, screen does not.** The `navigate()` helper pushes but forgets to render — or renders only in the `popstate` handler, which never fires for pushes. - **Back changes the URL but not the view.** The `popstate` listener is missing, or it was attached to `document` instead of `window`; `popstate` is fired at the `window`. - **Clicking a link reloads the whole app.** No click interception, so the anchor's default cross-document navigation ran. - **Rendering runs twice per click.** The handler both listens to `popstate` and re-renders inside `navigate()` *and* something calls `history.back()` internally. Trace which of the two paths fired. ## Reading the current state Because no event announces a push, the current entry's data is read synchronously from `history.state`, and the target entry's data arrives on the traversal event as `event.state`. Keeping the two in sync — always render from `location` plus `history.state`, never from a variable you mutated on the side — is what keeps Back, Forward and reload consistent.