[fredericoo]

TL;DR: Replace mutable optimistic baselines with keyed transaction projections, and coalesce ambiguous overlapping mutations into one authoritative cart refresh.

Before

Each cart domain managed separate controllers and rollback baselines. Concurrent responses could arrive out of order, allowing a stale snapshot to resurrect removed lines or overwrite unrelated optimistic work.

Treating the last-started response as the latest cart was also insufficient. Cart responses expose lines(first: 250), so the loaded line connection can be partial. Local arithmetic over visible lines cannot recover authoritative totalQuantity for hidden lines, and currency amounts cannot be calculated safely on the client.

After

Visible cart state is derived from settled data, pending transactions, and keyed error projections. Line transactions reconcile only their owned lines and preserve quantities outside the loaded connection.

When mutations overlap, their cart-wide snapshots are ambiguous. The store keeps the scoped projections, marks state.revalidating, and performs one authoritative cart refresh after the burst settles. This refresh supplies the complete quantity and server-derived cost truth without issuing one fetch per mutation.

What this changes

• Replaces cart mutation internals with a typed transaction registry.
• Prevents out-of-order remove responses from resurrecting lines or leaving totalQuantity stale.
• Coalesces overlapping mutation recovery into one cancellable, trailing cart refresh.
• Waits for returned mutation transports, not only Standard Event promises, before refreshing.
• Correlates delayed internal events with per-dispatch UUIDs so identical external events remain independent.
• Rejects stale refreshes by cart identity, store generation, and mutation revision.
• Preserves omitted custom fields, line metadata, and enriched merchandise when applying authoritative data.
• Serialises only the first identity-establishing add transport, then releases queued adds with the created cartId.
• Surfaces refresh failures through keyed network errors that clear on the next refresh.
• Keeps totals and analytics unconfirmed while state.revalidating is true.
• Keeps cart IDs out of endpoint URLs and marks cart GET responses private and non-cacheable across browsers, CDNs, and surrogate caches.

Developer impact

Includes a patch changeset for @shopify/hydrogen. CartState gains an additive optional revalidating flag. There are no new exports or required migrations; consumers can use the flag to distinguish cart-wide authoritative reconciliation from entity-level pending work.

The packaged cart and analytics skills document the new settlement signal. Reference examples use it for totals styling, analytics suppression, live status announcements, and refresh errors. Cart drawer guidance opens optimistic state before submission when the canonical trigger is an anchor.

Bundle impact

Measured from the same source entry with tsdown before and after this branch:

Measurement	Before	After	Delta
Published cart.mjs	38.67 kB	41.99 kB	+3.32 kB (+8.6%)
Published cart.mjs gzip	8.86 kB	9.75 kB	+0.89 kB (+10.0%)
Isolated minified cart	19.61 kB	22.15 kB	+2.54 kB (+13.0%)
Isolated minified cart gzip	6.08 kB	7.29 kB	+1.21 kB (+19.9%)

The isolated comparison used pnpm exec tsdown src/core/cart/cart.ts --no-config --format esm --minify --platform browser.

UX impact

• Rapid cart interactions remain optimistic and controls stay enabled.
• Stale totals remain visibly marked as updating until authoritative reconciliation completes.
• Screen readers receive persistent update, completion, and failure announcements, including when the cart becomes empty.
• Checkout controls retain full contrast while totals are unconfirmed.

Risk

• Each overlapping mutation burst adds one authoritative cart GET. Revalidation is single-flight, abortable, and coalesced; a mutation during refresh schedules one trailing fetch.
• First-cart adds queue transport until identity exists. Their optimistic projections still appear immediately.
• Event correlation depends on Standard Actions preserving custom event detail. Both synchronous and asynchronous event paths have regression coverage.
• Relative add requests remain independent; failed additions roll back only their own projected quantity.
• The isolated minified cart gzip size increases by 1.21 kB due to transaction and ownership bookkeeping.

How to Test

1. Run pnpm install && pnpm --filter @shopify/hydrogen build.
2. Run pnpm dev:rr and open the local React Router storefront.
3. Add multiple products, then remove several lines rapidly.
4. Confirm every line disappears immediately, no line returns, and the final count and costs match the server cart.
5. Rapidly increase and decrease different lines; confirm totals remain visibly updating until reconciliation completes.
6. Starting from an empty cart, add the same product several times quickly. Confirm one cart is created and the final quantity includes every click.
7. Simulate a failed cart refresh and confirm the local cart remains visible with an accessible network error.

[frandiox]

Approved again with extra review, left a few comments. Thanks!