Show a retry overlay when the checkout window is blocked

[kyle-schellen]

What changes are you making?

Problem. When the browser blocks the checkout window (window.open returns null), the overlay still says "Continue your purchase in the checkout window". There is no window, the "checkout window" link does nothing, and the only way out is to close the overlay. Blocks usually happen because the host page does work (for example, creating a cart) between the buyer's click and open(), and browsers only allow a new window shortly after a click.

Change. The overlay now shows a blocked state: "Your browser blocked the checkout window." with Open checkout and Close. Open checkout calls window.open again from the buyer's own click, which browsers allow, so the common case recovers in one tap.

Situation	Buyer sees	Host page receives
Window blocked	Blocked overlay	Nothing yet
Open checkout, window opens	Checkout window; overlay switches to its normal state	start, then close when checkout ends
Open checkout, blocked again	Blocked overlay stays	Nothing yet
Blocked overlay closed (Close, Escape, close(), or a target change)	Overlay hidden	close
Overlay hidden by the host (display: none on the element or ::part(overlay))	Nothing	Nothing

Other details:

• Trying again never dispatches close, whether it's our Open checkout button, a store's own button in the overlay-blocked slot, or the store's code calling open() again.
• Logs a warning at log-level="warn". blocked telemetry is now retryable: true, with isRetry: true when a retry is blocked again.
• No changes to attributes, properties, methods, or events. The blocked copy sits in a new overlay-blocked slot next to the existing overlay slot, and data-state="blocked" on the dialog switches between them.
• The overlay visibility check moved into #isDialogVisible() so both states share it.
• The <dialog> element's native close listeners ignore the event if the dialog is open again. The native event fires asynchronously, and a retry closes and re-shows the dialog in the same task.

Not in this PR: accessible names for the overlay (both states).

Context: https://shopify.slack.com/archives/C0B2UHWSG7M/p1789743314060319

How to test

• dev web test and dev web lint. New tests cover the blocked overlay, the retry, and close when the blocked overlay is closed.
• Sample app (pnpm sample): under Flow, choose Use existing checkout source and paste a cart permalink (https://your-store.myshopify.com/cart/<variant-id>:1). In the DevTools console, run setTimeout(() => document.querySelector('shopify-checkout').open(), 8000), then don't click or type on the page for 8 seconds (a click gives the page a fresh user activation, so the window would open). The browser blocks the window and the overlay shows the blocked state. Click Open checkout and checkout opens. Run it again and click Close to see close in the Events panel.
• To see a retry that's blocked again, run window.open = () => null in the console first (reload to undo).

---

Before you merge

Important

• I've added tests to support my implementation
• I have read and agree with the Contribution Guidelines
• I have read and agree with the Code of Conduct
• I've updated the relevant platform README (platforms/web/README.md)

Screen.Recording.2026-09-28.at.11.40.53.AM.mov

[kyle-schellen]

• Show a retry overlay when the checkout window is blocked #791 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Web — Coverage Report

Lines	Statements	Branches	Functions
	95.33% (409/429)	84.21% (208/247)	97.32% (109/112)

[github-actions]

Package Size

Platform	Artifact	Base	Head	Delta
Web	npm tarball	90.0 KiB	91.6 KiB	+1.6 KiB

Web file breakdown

File	Base	Head	Delta
dist/index.js.map	247.2 KiB	251.7 KiB	+4.6 KiB
dist/custom-elements.json	48.0 KiB	49.8 KiB	+1.8 KiB
dist/index.d.ts	47.7 KiB	47.8 KiB	+34 B
dist/index.js	41.2 KiB	43.2 KiB	+2.0 KiB
README.md	20.1 KiB	20.6 KiB	+568 B
package.json	2.9 KiB	2.9 KiB	0 B
LICENSE	1.1 KiB	1.1 KiB	0 B

Measured from the PR base SHA and PR head SHA. The file breakdown shows uncompressed sizes within each package artifact, so individual files do not sum to the compressed artifact total. This comment reports package artifact sizes only; it is not a final app binary-size report.