fix(pwa checkout): wait for cart hydration before empty-cart redirect (no more false /panier bounce) (#492)

* @
test(pwa checkout): pin hydration gate before empty-cart redirect

Red tests for the false /panier bounce: a fresh /checkout load with a
non-empty PERSISTED cart must not redirect. Cover the decideCheckoutRedirect
hydration matrix (wait until hydrated; stay on non-empty; redirect on empty)
and the safeReadFromStorage rehydration source (persisted non-empty cart
reads back non-empty).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@

* @
fix(pwa checkout): wait for cart hydration before empty-cart redirect

The cart is localStorage-backed; CartProvider rehydrates in a mount effect
that React commits AFTER the child CheckoutForm redirect effect. On a fresh
/checkout load the form read 0 lines (pre-rehydration EMPTY state) and bounced
a non-empty persisted cart to /panier.

Expose `hydrated` from the cart context (false on server + first client render
for SSR safety, flipped true once the mount effect has read localStorage even
when empty). decideCheckoutRedirect now returns `wait` until hydrated; the form
renders nothing while waiting — no redirect, no form flash. Post-hydration:
empty -> /panier (preserved), non-empty -> render the form.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: alexpmichelet

apps/web/src/components/cart/cart-context.test.ts

@@ -0,0 +1,106 @@
+/**
+ * PWA — `<CartProvider>` rehydration core, exercised through its pure helper
+ * `safeReadFromStorage` (same node-env, no-jsdom convention as the rest of the
+ * PWA decision suite — see `checkout-gate/*.test.ts`).
+ *
+ * Regression context (« /checkout bounce to /panier with items in cart »):
+ * the cart is localStorage-backed and rehydrates in a mount effect. The
+ * `<CheckoutForm>` empty-cart → /panier redirect must wait for that effect
+ * (gated on the context's `hydrated` flag) so a non-empty PERSISTED cart isn't
+ * bounced. The two pieces that close the race are unit-pinned here + in
+ * `checkout-gate/decide-checkout-redirect.test.ts`:
+ *
+ *   1. the redirect decision returns `wait` until `hydrated` (decision test),
+ *   2. a persisted non-empty cart is read back as non-empty so that, once
+ *      hydrated, the decision is `stay` not `redirect` (THIS file).
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { safeReadFromStorage } from "./cart-context";
+import { EMPTY_CART, type CartState } from "@/lib/cart-store";
+
+const STORAGE_KEY = "kb-cart-v1";
+
+/** Minimal in-memory localStorage stub for node env (no jsdom). */
+function installLocalStorage(): Map<string, string> {
+  const store = new Map<string, string>();
+  const fake = {
+    getItem: (k: string): string | null => store.get(k) ?? null,
+    setItem: (k: string, v: string): void => {
+      store.set(k, v);
+    },
+    removeItem: (k: string): void => {
+      store.delete(k);
+    },
+    clear: (): void => {
+      store.clear();
+    },
+  };
+  // `safeReadFromStorage` guards on `typeof window === "undefined"`, so we must
+  // expose BOTH `window` and `window.localStorage`.
+  (globalThis as { window?: unknown }).window = { localStorage: fake };
+  return store;
+}
+
+function uninstallLocalStorage(): void {
+  delete (globalThis as { window?: unknown }).window;
+}
+
+const PERSISTED_NON_EMPTY: CartState = {
+  lines: [
+    {
+      lineId: "item_1::",
+      itemId: "item_1",
+      name: "Smash Double",
+      basePriceCentimes: 1290,
+      photoUrl: null,
+      modifiers: [],
+      qty: 2,
+    },
+  ],
+  note: "Sans oignon",
+};
+
+describe("safeReadFromStorage (cart rehydration source)", () => {
+  let store: Map<string, string>;
+
+  beforeEach(() => {
+    store = installLocalStorage();
+  });
+
+  afterEach(() => {
+    uninstallLocalStorage();
+  });
+
+  it("reads a persisted NON-EMPTY cart back as non-empty (no false /panier bounce)", () => {
+    // This is the exact data that, post-hydration, makes the checkout redirect
+    // decision `stay` instead of bouncing to /panier. If this regressed, the
+    // hydration gate would still hide the form forever.
+    store.set(STORAGE_KEY, JSON.stringify(PERSISTED_NON_EMPTY));
+
+    const read = safeReadFromStorage();
+
+    expect(read.lines.length).toBe(1);
+    expect(read.lines[0]?.qty).toBe(2);
+    expect(read.note).toBe("Sans oignon");
+  });
+
+  it("returns EMPTY_CART when nothing is persisted (genuine empty cart → /panier)", () => {
+    expect(safeReadFromStorage()).toEqual(EMPTY_CART);
+  });
+
+  it("falls back to EMPTY_CART on corrupted JSON (never throws)", () => {
+    store.set(STORAGE_KEY, "{not-valid-json");
+    expect(safeReadFromStorage()).toEqual(EMPTY_CART);
+  });
+
+  it("falls back to EMPTY_CART on a shape-invalid payload (defensive)", () => {
+    store.set(STORAGE_KEY, JSON.stringify({ lines: "nope", note: 42 }));
+    expect(safeReadFromStorage()).toEqual(EMPTY_CART);
+  });
+
+  it("returns EMPTY_CART when there is no window (SSR — hydrated stays false)", () => {
+    uninstallLocalStorage();
+    expect(safeReadFromStorage()).toEqual(EMPTY_CART);
+    store = installLocalStorage(); // restore for afterEach symmetry
+  });
+});

apps/web/src/components/cart/cart-context.tsx

@@ -31,6 +31,7 @@ import {
   useContext,
   useEffect,
   useReducer,
+  useState,
   type Dispatch,
   type ReactNode,
 } from "react";
@@ -51,6 +52,16 @@ type CartContextValue = {
   state: CartState;
   totals: CartTotals;
   dispatch: Dispatch<CartAction>;
+  /**
+   * `false` on the server + the very first client render, flipped to `true`
+   * once the mount effect has read `localStorage` (whether the stored cart
+   * was empty or not — hydration means « we've read storage », NOT « the cart
+   * is non-empty »). Consumers that gate navigation on the cart contents
+   * (e.g. `<CheckoutForm>`'s empty-cart → /panier redirect) MUST wait for
+   * `hydrated === true` before deciding, otherwise they race the rehydration
+   * effect and bounce a non-empty persisted cart back to /panier.
+   */
+  hydrated: boolean;
   /** Sugar: dispatch ADD_LINE; the most common cart action. */
   addLine: (
     item: CartItemView,
@@ -61,8 +72,15 @@ type CartContextValue = {
 
 const CartCtx = createContext<CartContextValue | null>(null);
 
-/** Defensive rehydrate: shape-check the JSON before trusting it. */
-function safeReadFromStorage(): CartState {
+/**
+ * Defensive rehydrate: shape-check the JSON before trusting it.
+ *
+ * Exported (not just an internal helper) so the rehydration contract — « a
+ * persisted non-empty cart is read back as non-empty » — is vitest-pinnable
+ * in node env alongside the rest of the cart decisions. This is the source
+ * the mount effect replays into the reducer.
+ */
+export function safeReadFromStorage(): CartState {
   if (typeof window === "undefined") return EMPTY_CART;
   try {
     const raw = window.localStorage.getItem(STORAGE_KEY);
@@ -95,9 +113,21 @@ export function CartProvider({
   // throw a warning if we initialised from a non-deterministic source).
   const [state, dispatch] = useReducer(cartReducer, EMPTY_CART);
 
+  // `false` until the mount effect has read localStorage. Stays `false` on the
+  // server + first client render so SSR markup matches (localStorage isn't
+  // readable server-side) — no hydration mismatch. Consumers gate navigation
+  // on this so they never decide the empty-cart redirect against the
+  // pre-rehydration EMPTY state (the false /panier-bounce race).
+  const [hydrated, setHydrated] = useState(false);
+
   // Rehydrate once on mount.
   useEffect(() => {
     const stored = safeReadFromStorage();
+    // Flag hydration as DONE regardless of whether the stored cart had items —
+    // « hydrated » means « we've read storage », not « the cart is non-empty ».
+    // Set it even on the empty-cart early-return below so a genuinely empty
+    // cart still unblocks the consumer's (correct) redirect to /panier.
+    setHydrated(true);
     if (stored.lines.length === 0 && stored.note === "") return;
     // Replace state with the persisted one — we don't have a REPLACE action
     // in the reducer (deliberately minimal); we re-add each line in order
@@ -145,7 +175,7 @@ export function CartProvider({
   );
 
   return (
-    <CartCtx.Provider value={{ state, totals, dispatch, addLine }}>
+    <CartCtx.Provider value={{ state, totals, dispatch, addLine, hydrated }}>
       {children}
     </CartCtx.Provider>
   );

apps/web/src/components/checkout/checkout-form.tsx

@@ -84,14 +84,21 @@ export function CheckoutForm({
   // from another tab / from an earlier modal.
   const customer = usePreloadedQuery(preloadedCustomer);
 
-  const { state: cartState, totals } = useCart();
+  const { state: cartState, totals, hydrated } = useCart();
   const { verdict, mode } = useDeliveryMode();
 
   // Decide redirect on every render (the cart can be emptied from another
   // tab in private mode → we react). `useEffect` so the navigation happens
   // post-commit (Next 16 will scream if router.push runs during render).
+  //
+  // `hydrated` is the race guard: the cart rehydrates from localStorage in
+  // `<CartProvider>`'s mount effect, which React commits AFTER this child's
+  // redirect effect. Without the guard a fresh /checkout load reads 0 lines
+  // (the pre-rehydration EMPTY state) and bounces a non-empty persisted cart
+  // to /panier. Until hydrated, the decision is `wait` → no redirect, no form.
   const redirect = decideCheckoutRedirect({
     cartLineCount: cartState.lines.length,
+    hydrated,
   });
   useEffect(() => {
     if (redirect.kind === "redirect") {
@@ -135,9 +142,11 @@ export function CheckoutForm({
     [],
   );
 
-  if (redirect.kind === "redirect") {
-    // Render nothing while the navigation is en route — avoids a flash of
-    // the empty checkout form before the redirect lands.
+  if (redirect.kind !== "stay") {
+    // `wait`     → cart hasn't hydrated from localStorage yet: render nothing
+    //              so we neither flash the form nor bounce a persisted cart.
+    // `redirect` → empty cart confirmed post-hydration: render nothing while
+    //              the navigation to /panier is en route (no empty-form flash).
     return null;
   }
 

apps/web/src/lib/checkout-gate/decide-checkout-redirect.test.ts

@@ -14,23 +14,73 @@ import { describe, expect, it } from "vitest";
 import { decideCheckoutRedirect } from "./decide-checkout-redirect";
 
 describe("decideCheckoutRedirect", () => {
-  it("redirects to /panier when the cart has 0 lines", () => {
-    const action = decideCheckoutRedirect({ cartLineCount: 0 });
+  it("redirects to /panier when the cart has 0 lines (hydrated)", () => {
+    const action = decideCheckoutRedirect({ cartLineCount: 0, hydrated: true });
     expect(action.kind).toBe("redirect");
     if (action.kind !== "redirect") throw new Error("unreachable");
     expect(action.path).toBe("/panier");
   });
 
-  it("stays on the page when the cart has 1+ line(s)", () => {
-    expect(decideCheckoutRedirect({ cartLineCount: 1 }).kind).toBe("stay");
-    expect(decideCheckoutRedirect({ cartLineCount: 5 }).kind).toBe("stay");
+  it("stays on the page when the cart has 1+ line(s) (hydrated)", () => {
+    expect(
+      decideCheckoutRedirect({ cartLineCount: 1, hydrated: true }).kind,
+    ).toBe("stay");
+    expect(
+      decideCheckoutRedirect({ cartLineCount: 5, hydrated: true }).kind,
+    ).toBe("stay");
   });
 
   it("treats a negative count defensively as 0 (no crash on bogus input)", () => {
     // Pure functions should never throw on numerical edge values — the cart
     // store should never produce a negative count, but if it did, behaving
     // like « empty cart » is the safe choice (redirect, do NOT render the
     // checkout form against a bogus state).
-    expect(decideCheckoutRedirect({ cartLineCount: -1 }).kind).toBe("redirect");
+    expect(
+      decideCheckoutRedirect({ cartLineCount: -1, hydrated: true }).kind,
+    ).toBe("redirect");
+  });
+
+  // ── Hydration-race regression (false /panier bounce) ──────────────────
+  // The cart is localStorage-backed and rehydrates in a mount effect that
+  // runs AFTER the child <CheckoutForm> redirect effect (React fires child
+  // effects before parent effects). On a fresh /checkout load the form would
+  // momentarily see 0 lines even though localStorage HAS items → it bounced
+  // to /panier. The fix gates the decision behind `hydrated`: until the cart
+  // has read localStorage we must neither redirect nor render the form.
+  describe("hydration gate (no false /panier bounce)", () => {
+    it("returns `wait` (never redirect) while the cart is NOT hydrated, even with 0 lines", () => {
+      // 0 lines pre-hydration is the EXACT race that caused the bug: the
+      // store starts EMPTY before localStorage is read. We must NOT redirect.
+      const action = decideCheckoutRedirect({
+        cartLineCount: 0,
+        hydrated: false,
+      });
+      expect(action.kind).toBe("wait");
+    });
+
+    it("returns `wait` while not hydrated regardless of the (stale) line count", () => {
+      expect(
+        decideCheckoutRedirect({ cartLineCount: 3, hydrated: false }).kind,
+      ).toBe("wait");
+      expect(
+        decideCheckoutRedirect({ cartLineCount: -1, hydrated: false }).kind,
+      ).toBe("wait");
+    });
+
+    it("once hydrated, a non-empty cart STAYS (no bounce) — the bug is closed", () => {
+      expect(
+        decideCheckoutRedirect({ cartLineCount: 2, hydrated: true }).kind,
+      ).toBe("stay");
+    });
+
+    it("once hydrated, a genuinely empty cart still redirects to /panier", () => {
+      const action = decideCheckoutRedirect({
+        cartLineCount: 0,
+        hydrated: true,
+      });
+      expect(action.kind).toBe("redirect");
+      if (action.kind !== "redirect") throw new Error("unreachable");
+      expect(action.path).toBe("/panier");
+    });
   });
 });

apps/web/src/lib/checkout-gate/decide-checkout-redirect.ts

@@ -12,19 +12,42 @@
  * function just answers « given a line count, what should happen? ».
  */
 
-/** The input the decision needs — just the cart line count for now. */
+/**
+ * The input the decision needs : the cart line count AND whether the cart
+ * context has finished reading `localStorage`.
+ *
+ * `hydrated` closes the false-/panier-bounce race (issue: « /checkout bounce
+ * to /panier with items in cart »). The cart is localStorage-backed and the
+ * `<CartProvider>` rehydration runs in a mount effect that fires AFTER the
+ * child `<CheckoutForm>` redirect effect (React commits child effects before
+ * parent effects). On a fresh `/checkout` load the form would briefly read 0
+ * lines even though localStorage HAS items → redirect to /panier. Until the
+ * cart has read storage we must hold the decision (`wait`), never redirect.
+ */
 export type CheckoutRedirectInput = {
   cartLineCount: number;
+  /** `true` once `<CartProvider>` has read localStorage (empty or not). */
+  hydrated: boolean;
 };
 
-/** The action the calling component should perform. */
+/**
+ * The action the calling component should perform.
+ *
+ * `wait` = the cart hasn't hydrated yet : render nothing, do NOT redirect and
+ * do NOT flash the form (we don't yet know if the persisted cart has items).
+ */
 export type CheckoutRedirectAction =
+  | { kind: "wait" }
   | { kind: "stay" }
   | { kind: "redirect"; path: "/panier" };
 
 /**
- * Decide the redirect for `/checkout`. `cartLineCount <= 0` redirects to
- * /panier; any positive count stays.
+ * Decide the redirect for `/checkout`.
+ *
+ *  - not hydrated yet → `wait` (the localStorage cart is unknown; holding
+ *    avoids the false bounce to /panier on a fresh load with persisted items),
+ *  - hydrated + `cartLineCount <= 0` → redirect to /panier,
+ *  - hydrated + positive count → stay.
  *
  * Negative counts are treated like 0 (defensive: pure functions don't throw
  * on numerical edge cases, and « redirect to /panier on bogus state » is
@@ -34,6 +57,9 @@ export type CheckoutRedirectAction =
 export function decideCheckoutRedirect(
   input: CheckoutRedirectInput,
 ): CheckoutRedirectAction {
+  if (!input.hydrated) {
+    return { kind: "wait" };
+  }
   if (input.cartLineCount <= 0) {
     return { kind: "redirect", path: "/panier" };
   }