Cart storefront

Signed-in customers add products, edit quantities, remove lines and return to a saved cart. Next.js Server Components read the private cart and Server Actions apply changes through FastAPI; shared shadcn controls provide pending, validation and recovery feedback. Delivered in #80 (#72), on top of the persistent cart API (#71 / PR #79). Checkout and sandbox payments are delivered as subsequent stages; see the shopping walkthrough and canonical plan for their hosted acceptance.

Walk through the demo

Use the development storefront for experiments with a unique fictional email. Do not simulate outages or alter inventory on the shared demo; faults are covered by the disposable browser suite.

Step	Action	Expected result
Sign-in prompt	Open /cart signed out.	Sign-in prompt, no saved products.
Add	Open an in-stock product and press Add to cart.	Navigation count rises; reload keeps it.
Manage	On /cart, increase, decrease, type a quantity and press Update, then remove a line.	Quantities, count and GBP subtotal agree.
Invalid input	Submit 0, 100 or a fractional quantity.	Inline validation error; saved quantity unchanged.
Stock limit	Request more than available stock.	Stock error; saved quantity unchanged.
Persistence	Sign out and back in; try a second fictional account.	Saved items return; the second account starts independently.
Account change	With the cart open, change the signed-in account in another tab, return and try a quantity control.	The old cart cannot modify the new account; refresh shows the current account's cart.

Keyboard-only navigation and narrow mobile viewports are supported with visible focus, labels, pending buttons and readable errors.

Boundaries and limitations

FastAPI owns permissions, prices, stock and totals. Server Components resolve identity through FastAPI per request; the HttpOnly bearer never reaches browser JavaScript and only the verified email plus cart display data enter client props. Server Actions re-verify ownership, so a stale page cannot write into a different signed-in account. Quantities use absolute-quantity PUT semantics: independent clients racing a read-then-write land last-write-wins; there is no atomic increment API and adding objects does not reserve stock. Availability is revalidated at atomic order placement. Placement claims inventory; the subsequent sandbox payment lifecycle releases unpaid cancelled/expired stock exactly once. See order decisions.

A timed-out mutation has an uncertain outcome: the UI offers an explicit fresh read rather than repeating the write. Pending identity checks conceal private controls with native inert, removing them from keyboard navigation until the current account is verified. Known-offline action failures keep recovery feedback available and skip automatic route refresh; reconnecting and deliberately retrying the read restores authoritative state. The online hint does not detect every outage or cancel an already dispatched write. General delayed-write ordering remains a documented limitation.

Reproduce the automated evidence

Follow frontend setup and verification to install the locked dependencies and Playwright Chromium. From frontend/:

npm run build
npm run test:e2e

The suite starts disposable local FastAPI/SQLite and fault-fixture services and injects per-session upstream failures. The cart-desktop and cart-mobile projects cover persistence, removal, validation, stock rejection, rapid and queued actions, stale-account rejection, cross-account isolation, failed reads and timeout recovery, with keyboard and axe checks. Cart projects disable automatic traces and screenshots because they render private data. Pixel 7 is browser emulation, not a physical-device test.

Evidence	Location
Server boundaries, private reads, action refreshes	cart-server.test.ts
Journeys, isolation, failures and recovery	cart.spec.ts
Architecture, flows and manual walkthrough	cart storefront design
Cart API contract	cart API design

Verified recovery checkpoint — 2 October 2026

PR #252 fixes the demonstrated Next.js mutation-deadline signal loss and known-offline refresh failure. The enabled desktop/mobile recovery regressions passed 24 local repeats without retries; the complete suite passed 129 tests with two existing skips. These demonstrated causes do not explain every historical intermittent symptom.

Normal development deployment published reviewed release a03545d. The VIN-89 hosted evidence records persistence, one client-only disconnected action and explicit read recovery, independent fictional carts, and returned-tab account switching. Both tested carts were emptied and browser sessions signed out. No orders were placed or inventory changed. Failed transport alone is not proof that a write never committed.