Document and test the Universal Checkout Web preview

[tiagocandido]

What changes are you making?

Document the experimental Universal Checkout Web contract, package entry point, local sample configuration and remaining release gates. Explain full per-shop snapshots, aggregate timing, malformed-member isolation and the distinction between completion, failure and presentation close.

Add integration coverage that drives protocol batches through the registered element into the sample overlay DOM. The fixtures cover ready, start/update, partial and explicit completion, optional undefined normalization and close/reopen. All fixture values are synthetic.

This remains a draft until real completion/error scenarios and unsettled resource lifecycle behavior are validated. Synthetic tests and a partial browser run do not establish release readiness.

How to test

From the repository root, with dependencies installed:

pnpm --dir platforms/web lint
pnpm --dir platforms/web test
pnpm --dir platforms/web build
pnpm --dir platforms/web verify
pnpm --dir platforms/web sample:build
pnpm --dir protocol test
pnpm --dir protocol lint
pnpm --dir telemetry/languages/typescript test
pnpm --dir platforms/web compare-snapshot

Results for the integrated public-base stack: 440 Web tests, 88 protocol tests and 14 telemetry tests pass; lint/typechecks, library/sample builds, package verification and package contents checks pass.

tophat results

On the public-base revision, the browser loaded two shops from ignored environment configuration, loaded both catalogs, created separate carts and prepared a continuation URL. The overlay opened and its close event appeared in the DOM. Removing a shop invalidated the prepared URL; reload restored configured shops with empty carts. This configuration retest did not receive live start/update events in the in-app browser; the earlier live event evidence remains separate.

The earlier browser run covered two catalogs, independent selections, Storefront carts, session preparation, authenticated presentation, received start/update events and close/reopen. The recording on the overlay PR shows redacted event rendering. No payment was submitted; live completion, real producer errors and the remaining lifecycle gates are explicitly outstanding.