Cross-Document View Transitions: The Gotchas Nobody Mentions

I wasted an entire Saturday on this. Not a lazy Saturday either, but one of those rare, carved-out, “I’m finally going to build that thing” Saturdays. I’d seen Jake Archibald’s demos . I’d watched the Chrome Dev Summit talk. I knew cross-document view transitions were real, that you could get those slick native-feeling page transitions on plain old multi-page sites without a single framework. No React. No Astro. No client-side router pretending your multi-page application (MPA) is single-page application (SPA). Just HTML pages linking to other HTML pages, with the browser handling the animation between them. Hell yes. So I started building. And nothing worked. The first tutorial I found had me dropping into my . Seemed simple enough. I added it to both pages, clicked my link, and… nothing. No transition. No error. Just a normal, instant page load like it was 2004. I opened DevTools, double-checked my syntax, restarted the server, tried Chrome Canary, cleared the cache. Nothing. I did what any self-respecting developer does at that point – I copied the code character by character from the blog post and pasted it in. Still nothing. I spent two hours convinced I was an idiot. Turns out that tag syntax? Deprecated. Gone. Chrome shipped it, then replaced it with a CSS-based opt-in, and half the internet’s tutorials still show the old way. Those older blog posts still rank well. They look authoritative. And they’re just wrong now. Not wrong because the authors were bad – wrong because the spec moved under everyone’s feet and nobody went back to update their posts. The other half of the tutorials I found were about same-document view transitions. SPA stuff. document.startViewTransition() called in JavaScript when you swap DOM content yourself, which is cool and useful but a completely different feature when you actually sit down to implement it. The API surface is different. The mental model is different. Th