Determine what should happen when reloading after a shallow navigation

[Rich-Harris]

Describe the problem

Opening this to keep track of #16449 (comment), in case we don't figure out an answer we like before that PR gets merged.

If you shallowly navigate from /photos to /photos/123 (displaying a modal), then reload such that you're then on the 'real' photo page, then navigate back, then navigate forwards, you will see the modal again. This feels a bit unnatural to me.

Describe the proposed solution

Reloading should probably 'upgrade' the history entry such that a back-then-forward navigation takes you to the full /photos/123 page rather than /photos with a modal.

Things I'm not sure about:

• whether this should be configurable
• whether it's somehow related to persistState
• whether any other entries in the stack should also be upgraded, so that lateral navigations are consistent

(I did a very brief survey of whatever prior art I could find and didn't turn up much. Our go-to Instagram example fails hard at this test. Might be worth looking at https://nextjs.org/docs/app/api-reference/file-conventions/intercepting-routes, though the docs themselves are rather vague, and the feature seems a bit complicated to use.)

Alternatives considered

No response

Importance

nice to have

Additional Information

No response

[teemingc]

If each modal navigation is a shallow navigation that doesn't persist state (which should be the default), and the modal is only open when let's say state.modal === true, shouldn't all those pages render without the modal when navigating backwards or reloading?

[dummdidumm]

I see only two valid solutions:

1. Keep it as-is today: You upgrade to the full page on reload but if you go back/forward you enter shallow mode again. The Unsplash example where the one you reloaded on is kept as full-page is really weird (especially if you consider that you could go back, reload, go back (shallow), go forward (upgraded full page), go forward (shallow again)). I think the human brain values consistency of the navigations it experiences higher than remembering "oh this used to look a bit different last I was here".
2. Upgrade all shallow navigations in the history stack around the reload (stopping where there were original real navigations) to "full" navigations. E.g. if you do photos->photo/1->photos/2->reload then both photos 1 and 2 are now full page and not shallow anymore.

I lean towards 1 because it's simpler to implement (and it's already like this) and because chances that something breaks in slightly unexpected ways is lower. Because what do we do with the page.state object in this case? Do we remove them for all of the upgraded navigations, or keep them? Both could have unintended breakage, so variant 1 is safer.

[Nic-Polumeyv]

Wizard flows that keep the current step in page.state (advanced with pushState) are a different class of usage here, and reload is supposed to restart the flow from the server-decided step. For modals the reload question is about what feels natural. For wizards it decides whether "reload resets the flow" holds at all, because back-then-forward after a reload resurrects the mid-flow step.

@teemingc no entry actually resets. Reload renders the fresh document without applying the stored state, but the state itself survives in history.state on every entry, including the one you reloaded, so back-then-forward re-applies it. That's what taught me the wrong rule for a while, I assumed reload clears the whole stack.

auth.uber.com looks like this pattern but isn't. Its bundle contains no pushState calls; the step stack lives in JS memory and on the server, so reload resets because the stack dies with the document, at the cost of the back button not walking steps. Wizard steps in history entries are only attractive because back/swipe walks the steps, and that only holds together if the reload boundary clears stale sibling entries, which is option 2. Under option 1 the safe architecture is Uber's and page.state stays a modal-only tool.

[Nic-Polumeyv]

Another argument for option 2 is that option 1 is not designed behavior. It's what falls out of the History API, and everyone's default assumption, this thread included, is that reload resets.

Eager upgrade is impossible either way since a document can't touch sibling entries, but lazily it's three moves:

• Stamp a per-document epoch into the entries kit already writes in pushState/replaceState/navigate.
• In the popstate handler, ignore stored state on entries from an older document and navigate to their visible URL as a real page instead. The existing has_navigated guard already tries to catch exactly this case, it just checks whether this document has navigated rather than whether that entry is stale, which is why the resurrection survives it.
• Then replaceState with the state stripped so the upgrade sticks.

The open knob is persistState from #16449, which would need re-stamping at boot, and this lands on top of that PR anyway since it rewrites the same lines.

Lateral entries then upgrade lazily when visited, and page.state on upgraded entries is dropped, same as what reload already shows. The cost is that traversal onto a stale entry becomes a full navigation that can fail or redirect, though that's the same surface reloading it already has.

Am I missing something?

[Rich-Harris]

The 'upgrade on reload' behaviour only makes sense if the URL and page.state are interchangeable — in other words, visiting /photos/123 is equivalent to being on /photos with a page.state of { photo: '123' }. If not, then upgrading lateral navigations (e.g. to an entry that added { modal: ... } state, but didn't change the URL, would lose that information.

Viewed in that light, varying this on persistState kind of makes sense to me, because persistState: true is what you use when the URL doesn't contain the same information as page.state.

So I think for me it's a choice between these two options:

1. Keep the behaviour as-is
2. After a reload, upgrade any history entries without persistState: true

[dummdidumm]

I vote 1 because it's less likely to have unintended consequences. Knowing about the nuance of how persistState plays into your shallow navigations is a bit much to ask.

[Nic-Polumeyv]

With option 1, hidden behavior like state resurrecting after a reload makes page.state something you can't trust, and primitives you can't trust naturally don't get built on... that's why shallow routing stays a modal trick instead of something with more complex uses.

The unintended consequences of option 1 are already filed: #15618, #16457, #11956. You don't need to know persistState to hit those, but you do need to know the resurrection nuance to debug them. Tightening the guards (#16449) doesn't change that — the state object itself is never validated, including after a deploy, where the new build applies state the old build wrote.

The browser does keep history.state across reloads, but kit already overrides that halfway, and applying it on load instead was ruled out long ago (#11956's hydration-flash reasoning). Finishing the override is the only consistent direction left, and it makes reload a boundary you can trust, with persistState covering state that genuinely should survive.

my peasant vote on the matter is option 2.