fix(transitions): skip view transition when browser already provides one by koji-1009 · Pull Request #16025 · withastro/astro

koji-1009 · 2026-03-22T09:26:46Z

Changes

https://developer.mozilla.org/en-US/docs/Web/API/PopStateEvent/hasUAVisualTransition

Skip document.startViewTransition() when PopStateEvent.hasUAVisualTransition is true
Fixes ClientRouter: flicker on Safari swipe back/forward gesture #16024

Note

On iOS, repeated testing may reveal a remaining minor flicker caused by a separate issue. However, this PR eliminates the double-animation flicker by properly supporting the hasUAVisualTransition API.

Testing

Manually tested on macOS Safari and iOS Safari:

Navigate between pages using <ClientRouter />
Swipe back/forward with gesture
Confirm no flicker occurs

iOS.26.fixed.mov

macOS.26.fixed.mov

Docs

No docs needed. This is a bug fix with no API changes.

changeset-bot · 2026-03-22T09:26:52Z

🦋 Changeset detected

Latest commit: 26d1256

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

martrapp · 2026-03-22T09:40:01Z

hey @koji-1009, that was fast ;-)

I was thinking if it wouldn't be cleaner to skip transition() completely in the popstate handler.
Have you tried that as a solution and would that work, too?

koji-1009 · 2026-03-22T09:46:40Z

OK! I'll try it!

koji-1009 · 2026-03-22T10:34:17Z

I tried skipping transition() entirely, but navigation breaks after the swipe gesture.

if (ev.hasUAVisualTransition) {
  return;
}

transition(direction, originalLocation, new URL(location.href), {}, state);

skip.mov

.changeset/common-symbols-teach.md

packages/astro/src/transitions/router.ts

codspeed-hq · 2026-03-23T09:58:13Z

Merging this PR will improve performance by 11.16%

⚡ 1 improved benchmark
✅ 17 untouched benchmarks

Performance Changes

	Mode	Benchmark	`BASE`	`HEAD`	Efficiency
⚡	Simulation	`Build: hybrid site (static + server)`	8.9 s	8 s	+11.16%

_{Comparing koji-1009:fix/safari_gesture_navigation (26d1256) with main (198d31b)}

martrapp

Currently the code duplicates some non trivial part of the router.

I guess we should remove the duplication and replace

	if (supportsViewTransitions) {
		if (hasUAVisualTransition) {

with

	if (supportsViewTransitions && !hasUAVisualTransition) {

and change the fallback() call in line 536 to hasUAVisualTransition ? "swap" : getFallback()

What do you think?

martrapp · 2026-03-23T10:05:43Z

Hi @koji-1009, I had some minor nits on how to tweak the code a bit and made a suggestion how to remove of the code duplication.

Co-authored-by: Martin Trapp <94928215+martrapp@users.noreply.github.com>

…on mode

…odes

koji-1009 · 2026-03-23T14:09:00Z

Thanks! I've implemented it in two commits:

eb922d7
- Merged the hasUAVisualTransition path into simulation mode.
26d1256
- Since 'swap' is now passed to updateDOM, viewTransitionFinished needs to be called for non-'animate' fallback modes too.

martrapp

Looks Good To Me!

Thank you @koji-1009 for tackling this!

martrapp · 2026-03-23T20:10:57Z

packages/astro/src/transitions/router.ts

+	// Resolve the finished promise of the simulation's ViewTransition.
+	// For 'animate', wait for the new-page animation to complete first.
+	// For other fallback modes (e.g. 'swap'), resolve immediately — no animation needed.
+	if (fallback === 'animate' && !currentTransition.transitionSkipped && !swapEvent.signal.aborted) {


Ah, you want to ensure that the simulated finished promise resolves.
The code for the simulated promises might need some update, anyhow.
For now this seems good enough.

koji-1009 · 2026-03-24T00:53:18Z

Thanks for the review and merge!

While testing with the merged code, I noticed that setting history.scrollRestoration = 'manual' causes iOS Safari to show a blank page preview during swipe gesture navigation when the page is scrolled. Removing the 'manual' settings resolves this — the correct page snapshot is shown regardless of scroll position.

Would you prefer I open an issue or a draft PR for discussion?

martrapp · 2026-03-24T05:51:55Z

For the sake of traceability, a second issue is of course preferable. You can keep it very brief and simply refer to the existing one.

This PR contains the following updates: | Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) | |---|---|---|---| | [astro](https://astro.build) ([source](https://github.com/withastro/astro/tree/HEAD/packages/astro)) | [`6.0.8` → `6.1.1`](https://renovatebot.com/diffs/npm/astro/6.0.8/6.1.1) | ![age](https://developer.mend.io/api/mc/badges/age/npm/astro/6.1.1?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/astro/6.0.8/6.1.1?slim=true) | --- ### Release Notes <details> <summary>withastro/astro (astro)</summary> ### [`v6.1.1`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#611) [Compare Source](https://github.com/withastro/astro/compare/astro@6.1.0...astro@6.1.1) ##### Patch Changes - [#16105](withastro/astro#16105) [`23d60de`](withastro/astro@23d60de) Thanks [@matthewp](https://github.com/matthewp)! - Fix dev toolbar audit crash when encountering the `image` ARIA role - [#16089](withastro/astro#16089) [`999c875`](withastro/astro@999c875) Thanks [@martrapp](https://github.com/martrapp)! - Fixes an issue with the client router where Vue's `:deep()` notation was ignored in dev mode. ### [`v6.1.0`](https://github.com/withastro/astro/blob/HEAD/packages/astro/CHANGELOG.md#610) [Compare Source](https://github.com/withastro/astro/compare/astro@6.0.8...astro@6.1.0) ##### Minor Changes - [#15804](withastro/astro#15804) [`a5e7232`](withastro/astro@a5e7232) Thanks [@merlinnot](https://github.com/merlinnot)! - Allows setting codec-specific defaults for Astro's built-in Sharp image service via `image.service.config`. You can now configure encoder-level options such as `jpeg.mozjpeg`, `webp.effort`, `webp.alphaQuality`, `avif.effort`, `avif.chromaSubsampling`, and `png.compressionLevel` when using `astro/assets/services/sharp` for compile-time image generation. These settings apply as defaults for the built-in Sharp pipeline, while per-image `quality` still takes precedence when set on `<Image />`, `<Picture />`, or `getImage()`. - [#15455](withastro/astro#15455) [`babf57f`](withastro/astro@babf57f) Thanks [@AhmadYasser1](https://github.com/AhmadYasser1)! - Adds `fallbackRoutes` to the `IntegrationResolvedRoute` type, exposing i18n fallback routes to integrations via the `astro:routes:resolved` hook for projects using `fallbackType: 'rewrite'`. This allows integrations such as the sitemap integration to properly include generated fallback routes in their output. ```js { 'astro:routes:resolved': ({ routes }) => { for (const route of routes) { for (const fallback of route.fallbackRoutes) { console.log(fallback.pathname) // e.g. /fr/about/ } } } } ``` - [#15340](withastro/astro#15340) [`10a1a5a`](withastro/astro@10a1a5a) Thanks [@trueberryless](https://github.com/trueberryless)! - Adds support for advanced configuration of SmartyPants in Markdown. You can now pass an options object to `markdown.smartypants` in your Astro configuration to fine-tune how punctuation, dashes, and quotes are transformed. This is helpful for projects that require specific typographic standards, such as "oldschool" dash handling or localized quotation marks. ```js // astro.config.mjs export default defineConfig({ markdown: { smartypants: { backticks: 'all', dashes: 'oldschool', ellipses: 'unspaced', openingQuotes: { double: '«', single: '‹' }, closingQuotes: { double: '»', single: '›' }, quotes: false, }, }, }); ``` See [the `retext-smartypants` options](https://github.com/retextjs/retext-smartypants?tab=readme-ov-file#fields) for more information. ##### Patch Changes - [#16025](withastro/astro#16025) [`a09f319`](withastro/astro@a09f319) Thanks [@koji-1009](https://github.com/koji-1009)! - Instructs the client router to skip view transition animations when the browser is already providing its own visual transition, such as a swipe gesture. - [#16055](withastro/astro#16055) [`ccecb8f`](withastro/astro@ccecb8f) Thanks [@Gautam-Bharadwaj](https://github.com/Gautam-Bharadwaj)! - Fixes an issue where `client:only` components could have duplicate `client:component-path` attributes added in MDX in rare cases - [#16081](withastro/astro#16081) [`44fc340`](withastro/astro@44fc340) Thanks [@crazylogic03](https://github.com/crazylogic03)! - Fixes the `emitFile() is not supported in serve mode` warning that appears during `astro dev` when using integrations that inject before-hydration scripts (e.g. `@astrojs/react`) - [#16068](withastro/astro#16068) [`31d733b`](withastro/astro@31d733b) Thanks [@Karthikeya1500](https://github.com/Karthikeya1500)! - Fixes the dev toolbar a11y audit incorrectly classifying `menuitemradio` as a non-interactive ARIA role. - [#16080](withastro/astro#16080) [`e80ac73`](withastro/astro@e80ac73) Thanks [@ematipico](https://github.com/ematipico)! - Fixes `experimental.queuedRendering` incorrectly escaping the HTML output of `.html` page files, causing the page content to render as plain text instead of HTML in the browser. - [#16048](withastro/astro#16048) [`13b9d56`](withastro/astro@13b9d56) Thanks [@matthewp](https://github.com/matthewp)! - Fixes a dev server crash (`serverIslandNameMap.get is not a function`) that occurred when navigating to a page with `server:defer` after first visiting a page without one, when using `@astrojs/cloudflare` - [#16093](withastro/astro#16093) [`336e086`](withastro/astro@336e086) Thanks [@Snugug](https://github.com/Snugug)! - Fixes Zod meta not correctly being rendered on top-level schema when converted into JSON Schema - [#16043](withastro/astro#16043) [`d402485`](withastro/astro@d402485) Thanks [@ematipico](https://github.com/ematipico)! - Fixes `checkOrigin` CSRF protection in `astro dev` behind a TLS-terminating reverse proxy. The dev server now reads `X-Forwarded-Proto` (gated on `security.allowedDomains`, matching production behaviour) so the constructed request origin matches the `https://` origin the browser sends. Also ensures `security.allowedDomains` and `security.checkOrigin` are respected in dev. - [#16064](withastro/astro#16064) [`ba58e0d`](withastro/astro@ba58e0d) Thanks [@ematipico](https://github.com/ematipico)! - Updates the dependency `svgo` to the latest, to fix a security issue. - [#16007](withastro/astro#16007) [`2dcd8d5`](withastro/astro@2dcd8d5) Thanks [@florian-lefebvre](https://github.com/florian-lefebvre)! - Fixes a case where fonts files would unecessarily be copied several times during the build - [#16017](withastro/astro#16017) [`b089b90`](withastro/astro@b089b90) Thanks [@felmonon](https://github.com/felmonon)! - Fix the `astro sync` error message when `getImage()` is called while loading content collections. - [#16014](withastro/astro#16014) [`fa73fbb`](withastro/astro@fa73fbb) Thanks [@matthewp](https://github.com/matthewp)! - Fixes a build error where using `astro:config/client` inside a `<script>` tag would cause Rollup to fail with "failed to resolve import `virtual:astro:routes` from `virtual:astro:manifest`" - [#16054](withastro/astro#16054) [`f74465a`](withastro/astro@f74465a) Thanks [@seroperson](https://github.com/seroperson)! - Fixes an issue with the development server, where changes to the middleware weren't picked, and it required a full restart of the server. - [#16033](withastro/astro#16033) [`198d31b`](withastro/astro@198d31b) Thanks [@adampage](https://github.com/adampage)! - Fixes a bug where the the role `image` was incorrectly reported by audit tool bar. - [#15935](withastro/astro#15935) [`278828c`](withastro/astro@278828c) Thanks [@oliverlynch](https://github.com/oliverlynch)! - Fixes cached assets failing to revalidate due to redirect check mishandling Not Modified responses. - [#16075](withastro/astro#16075) [`2c1ae85`](withastro/astro@2c1ae85) Thanks [@florian-lefebvre](https://github.com/florian-lefebvre)! - Fixes a case where invalid URLs would be generated in development when using font families with an oblique `style` and angles - [#16062](withastro/astro#16062) [`87fd6a4`](withastro/astro@87fd6a4) Thanks [@matthewp](https://github.com/matthewp)! - Warns on dev server startup when Vite 8 is detected at the top level of the user's project, and automatically adds a `"overrides": { "vite": "^7" }` entry to `package.json` when running `astro add cloudflare`. This prevents a `require_dist is not a function` crash caused by a Vite version split between Astro (requires Vite 7) and packages like `@tailwindcss/vite` that hoist Vite 8. - Updated dependencies \[[`10a1a5a`](withastro/astro@10a1a5a)]: - [@astrojs/markdown-remark](https://github.com/astrojs/markdown-remark)@7.1.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Co-authored-by: Renovate Bot <renovate@zarantonello.dev> Co-committed-by: Renovate Bot <renovate@zarantonello.dev>

koji-1009 added 2 commits March 22, 2026 17:49

fix(transitions): skip view transition when browser already provides one

795520a

chore: Add changeset

6227023

github-actions bot added the pkg: astro Related to the core `astro` package (scope) label Mar 22, 2026

koji-1009 mentioned this pull request Mar 22, 2026

ClientRouter: flicker on Safari swipe back/forward gesture #16024

Closed

1 task

koji-1009 marked this pull request as ready for review March 22, 2026 11:11

koji-1009 mentioned this pull request Mar 22, 2026

BUG: When a site has view transitions, and scroll-behavior: smooth, the back button has an annoying scroll animation. #10615

Closed

1 task

Merge branch 'main' into fix/safari_gesture_navigation

c01709d

martrapp reviewed Mar 23, 2026

View reviewed changes

.changeset/common-symbols-teach.md Outdated Show resolved Hide resolved

martrapp reviewed Mar 23, 2026

View reviewed changes

packages/astro/src/transitions/router.ts Outdated Show resolved Hide resolved

martrapp reviewed Mar 23, 2026

View reviewed changes

koji-1009 and others added 3 commits March 23, 2026 21:38

Apply suggestions from code review

7a7e7d8

Co-authored-by: Martin Trapp <94928215+martrapp@users.noreply.github.com>

refactor(transitions): merge hasUAVisualTransition path into simulati…

eb922d7

…on mode

fix(transitions): resolve finished promise for non-animate fallback m…

26d1256

…odes

martrapp approved these changes Mar 23, 2026

View reviewed changes

martrapp merged commit a09f319 into withastro:main Mar 23, 2026
26 checks passed

astrobot-houston mentioned this pull request Mar 23, 2026

[ci] release #16020

Merged

koji-1009 deleted the fix/safari_gesture_navigation branch March 23, 2026 22:12

koji-1009 mentioned this pull request Mar 24, 2026

ClientRouter: blank page snapshot during Safari swipe gesture when page is scrolled #16058

Open

1 task

Uh oh!

Conversation

koji-1009 commented Mar 22, 2026

Changes

Note

Testing

Docs

Uh oh!

changeset-bot bot commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

martrapp commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koji-1009 commented Mar 22, 2026

Uh oh!

koji-1009 commented Mar 22, 2026

Uh oh!

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will improve performance by 11.16%

Performance Changes

Uh oh!

martrapp left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martrapp commented Mar 23, 2026

Uh oh!

koji-1009 commented Mar 23, 2026

Uh oh!

martrapp left a comment

Choose a reason for hiding this comment

Uh oh!

martrapp Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

koji-1009 commented Mar 24, 2026

Uh oh!

martrapp commented Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Mar 22, 2026 •

edited

Loading

martrapp commented Mar 22, 2026 •

edited

Loading

codspeed-hq bot commented Mar 23, 2026 •

edited

Loading

martrapp left a comment •

edited

Loading