fix(ep-commerce): cart mutation errors and multilocation quantity updates

[mzaintariq]

Summary

• Reject cart mutation proxy/SDK failures instead of silently resolving to null.
• Surface Add to Cart errors through $ctx.addToCartState.error.
• Preserve/recover multilocation location on quantity updates.
• Harden quantity controls with in-flight protection, optimistic updates + rollback, and stock-aware increment limits.
• Use the strict proxy path for remove mutations.

What changed

Error handling

callEpProxy now throws when no fallback is supplied, while reads can continue to soft-fail by passing an explicit fallback:

// Read: soft failure
callEpProxy("getCart", input, null);

// Mutation: reject on failure
callEpProxy("addCartItem", input);

Elastic Path add/update/remove mutations also validate SDK { error } responses instead of treating them as successful.

Add to Cart

Failures now reach the existing Studio-facing state:

$ctx.addToCartState.error

Previous errors are cleared on a new attempt, and onAddedToCart only runs after a successful mutation.

No default toast or banner is added; designers can bind their own UI to the error state.

Multilocation quantity updates

Cart-line location is retained as locationSlug and passed with quantity updates.

If location is missing from the client request, the server attempts to recover it from the existing cart line before updating Elastic Path.

This fixes repeated multilocation +/- failures and incorrect insufficient-stock errors during decrement.

Quantity / remove

Quantity updates now:

• prevent overlapping requests
• optimistically update and roll back on failure
• revalidate the cart after failure
• respect known stock limits
• preserve button/ARIA busy and disabled behaviour

Remove now rejects proxy/SDK failures and refreshes the cart after success. Failed remove leaves the item in the cart.

Quantity/remove errors remain log-only in this MR.

Designer impact

Designers can bind custom error UI to $ctx.addToCartState.error.

Existing projects will not automatically display an error unless UI is bound to that value.

Implementor notes

• Two-argument callEpProxy calls now reject on failure.
• Reads that should soft-fail must pass an explicit fallback.
• Quantity updates accept an optional location; if omitted, the server may perform an additional cart read to recover it.

Testing

Automated

• Focused tests: 157 passed
• Package Jest: 1932 passed
• Package Vitest: 31 passed
• git diff --check: passed

Coverage includes proxy strict/fallback behaviour, SDK soft errors, ATC error/callback handling, multilocation location passing/recovery, quantity rollback/in-flight behaviour, stock limits, remove behaviour, and button accessibility/Studio preview states.

Manual

Verified:

• successful and failed Add to Cart
• repeated multilocation +/-
• location present in update requests
• rapid-click/in-flight behaviour
• rollback after failed quantity updates
• remove behaviour
• single-location/non-location regression checks

Fixes #392