Add a blocked event when the checkout window is blocked

[kyle-schellen]

What changes are you making?

Stacked on #791. Retarget to main once it merges.

When the browser blocks the checkout window, the component now dispatches a blocked event. With #791 alone, stores that hide the overlay get no signal at all, and no store can track how often checkout is blocked.

• blocked fires on every blocked attempt, including retries, whether or not the overlay is shown. It bubbles and has no detail, like close.
• Stores that hide the overlay can show their own message. A retry has to come from a user action such as a click.
• Calling open() directly from a blocked listener is ignored with a warning. Without that guard, the call is blocked again and recurses until the browser throws "Maximum call stack size exceeded".
• New public API: ShopifyCheckoutBlockedEvent and a blocked entry in ShopifyCheckoutEventMap. The README events table and the sample app's event log include it.

How to test

• dev web test and dev web lint. New tests cover blocked with the overlay shown and hidden, and the ignored open() call from a listener.
• Sample app (pnpm sample): under Flow, choose Use existing checkout source and paste a cart permalink. Run window.open = () => null in the DevTools console, then click Open checkout: blocked appears in the Events panel. Reload to undo.
• To see it with the overlay hidden, also run document.head.append(Object.assign(document.createElement('style'), { textContent: 'shopify-checkout::part(overlay) { display: none; }' })) before clicking Open checkout. No overlay appears, and blocked still fires.

---

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)

[github-actions]

Web — Coverage Report

Lines	Statements	Branches	Functions
	95.52% (427/447)	86.64% (227/262)	97.19% (104/107)

[github-actions]

Bundle Size Budgets

Budget	Size	Limits	Result
Web JavaScript (uncompressed)	34.99 KiB (+292 B)	35 KiB soft / 50 KiB hard	✅ Within budget

Bundle and package size

Web bundle sizes cover shipped runtime JavaScript. Package sizes cover the full published archive, including any source maps, declarations, and documentation it contains.

Platform	Measurement	Compression	Base	Head	Delta
Web	JavaScript bundle	Uncompressed	34.7 KiB	35.0 KiB	+292 B
Web	JavaScript bundle	gzip	10.7 KiB	10.8 KiB	+76 B
Web	npm package (.tgz)	gzip	92.5 KiB	93.1 KiB	+651 B

Web package files (uncompressed)

These are uncompressed file sizes; they do not sum to the compressed package size above.

File	Base	Head	Delta
dist/index.js.map	254.2 KiB	255.4 KiB	+1.2 KiB
dist/custom-elements.json	50.1 KiB	51.9 KiB	+1.8 KiB
dist/index.d.ts	48.0 KiB	48.5 KiB	+491 B
dist/index.js	34.7 KiB	35.0 KiB	+292 B
README.md	21.3 KiB	21.7 KiB	+375 B
package.json	3.6 KiB	3.6 KiB	0 B
LICENSE	1.1 KiB	1.1 KiB	0 B

How sizes are measured

Measured from the PR base SHA and PR head SHA. Web bundle rows sum shipped .js, .mjs, and .cjs files under dist/, excluding source maps and declarations. The gzip bundle size sums files compressed individually with gzip -n -9. npm package sizes are gzip-compressed .tgz archives; Android AAR sizes are ZIP archives. Package sizes are not final app binary sizes.

[kiftio]

Should we add one test with document.addEventListener() as we've set bubbles: true

[kyle-schellen]

Good point! I'll add that in