If it is not in the docs, it can't be true ;-)
https://bsky.app/profile/puruvj.dev/post/3lqrha2othk27

The ClientRouter and the View Transition API have different scopes. Some ClientRouter functionality is about turning a MPA into a SPA (transition:persist, cross-page state, script re-execution, route-announcer), others are extensions of the View Transition / Navigation API (forward/backward directions, predefined (fade/slide) and custom animation functions, reduced motion check, automatic cross-document names, sourceElement, popstate events), others are just different (programmatic navigation, lifecycle events)

To me, untangling these feature does not seem worth it. So I would leave the ClientRouter as is but add some explanation at the start of the current view transition docs:

If you only want view transitions during navigation, you can use the browser-native View Transition API's cross-document support. There is nothing Astro-specific about this. It works in all major browsers and should also be coming soon to Firefox.

Alternatively, you can use the Client Router. It adds some extra features to cross-document view transitions, like directional animations and auto-naming, but it also turns your multi-page app into a single-page app. That comes with benefits, like shared state across pages and persistent elements, and some drawbacks, such as needing to manually reinitialize scripts or state after navigation. Choose wisely.

(One can certainly wish for extensions to view transitions (things like directional animations, state transfer, or ready-made animations) but those can come from third-party libraries. They do not need to be part of the Astro core).

Thank you Martin for this great and detailed analysis to get this started!

I will firstly say, just to frame any further work (and make public for the sake of others who may be newly getting involved with how Astro docs works), that the ultimate purpose of Astro Docs is to document how Astro works: it's not our mandate to document "how to do view transitions" as a broad browser concept (e.g. https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using#basic_mpa_view_transition), and instead our primary focus is documenting "Astro features that we built and how they work" (e.g. <ClientRouter />)

A page intro could start with basic content (e.g. along the lines of this content from Mozilla), much like our other "general concept done in Astro" pages, like Markdown for example, where we define what the thing is, then say how it is used in Astro:

View transitions are animated transitions between different website views. View transitions are a popular design choice for reducing perceived loading latency as visitors move between states or views of an application.

These view transitions are used in Astro to animate the navigation between documents in a multi-page app (MPA), often providing the experience of client-side routing of single-page applications. These browser-native, cross-document view transitions don’t alter the core functionality of a multi-page application, nor do they affect any existing scripts or add additional JavaScript to your page load. They simply add animations.

From here, Martin's points follow nicely, allowing us to move into what Astro provides and what it is for, focusing on using it for cases where support is lacking:

For enhanced client-side routing and view transition features not yet fully supported by the View Transition API , Astro provides a built-in, lightweight component to enable client-side routing and turn your multi-page app into a single-page app. That comes with some benefits, like shared state across pages and persistent elements, and some drawbacks, such as needing to manually reinitialize scripts or state after navigation.

Adding the <ClientRouter /> intercepts page navigation and gives you considerable control over this process; extends and enhances some View Transition/Navigation API features; and additionally allows you to configure fallback strategies for when native browser support is lacking.

However, as browser APIs and web standards evolve, using Astro's <ClientRouter /> for this additional functionality will increasingly become unnecessary. We recommend keeping up with the current state of browser APIs so you can decide whether you still need Astro's client-side routing for the specific features you use.

So, I'm thinking something like that to frame this page? (Obviously you will help make sure that it's accurate and the right nuance of everything!) This also feels fairly "future-proof" in that it nudges to consider the development of web standards, even while we still maintain comprehensive documentation of everything we provide.

Thanks a lot, @sarah11918!

The way you tell stories feels so effortless. It’s honestly beyond me how you manage that.

From my perspective, this is a nearly finished, perfect starting point for a PR. It really supports my intention to help people better understand what they are getting into.

We can adjust the small details in the PR.
(I guess i would just completely focus on cross-document view transitions from the beginning.)

(You're too kind, Martin!)

So I would say, it sounds like we have an idea for a reframing for the intro of this page! I'm happy if you'd like to make a PR to update the intro to the View Transitions guide and we can work out all the details in the PR.

(Part of me wonders whether this page should really be (end up being?) "Client-side routing" ... but I don't think we can handle that much right now! 😂 I'm cool taking baby steps here...)

Please make a PR at your leisure with whatever you would intro the page with, and we'll all pick this discussion up there! 🙌