@reblu/site-next 1.14.0 → 1.15.1

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @reblu/site-next
 
+## 1.15.1
+
+### Patch Changes
+
+- f0b1d63: Fix `useShopOrderStatus` never resolving `paid` when wired as documented (REB-839).
+  `createShopOrderRoute` forwards base-api's body verbatim, and base-api wraps every
+  payload as `{ data: <order> }`; the hook read `paymentStatus` off the raw body, so
+  every order looked PENDING (`pending_timeout` after the window, cart never cleared,
+  `order` holding the envelope). The hook now unwraps `body.data` when present and
+  still accepts a bare order from a custom route.
+
+  Also: `addItem` on a line already at `maxStock` (or reconciled down by fresher
+  stock) now returns `{ status: 'refused' }` instead of `'clamped'`, so
+  `AddToCartButton` and the toast no longer report «Añadido ✓» when nothing was
+  added. `quantity` remains the resulting line quantity (README updated).
+
+## 1.15.0
+
+### Minor Changes
+
+- 21feec3: REB-836 — checkout hardening: Stripe redirect-origin check + stable checkout error codes.
+  - `@reblu/site-contracts`: re-exports the new `ShopErrorCode` type (type-only, `z.infer` from base-api's `shopErrorCodeSchema`, no Zod reaches the published `.d.ts`) — nine values: `STOCK_CHANGED`, `PRICE_CHANGED`, `PRODUCT_UNAVAILABLE`, `DISCOUNT_INVALID`, `SHIPPING_UNAVAILABLE`, `INVALID_INPUT`, `STORE_DISABLED`, `PAYMENT_PROVIDER_ERROR`, and `INTERNAL_ERROR` (added in a native-review follow-up to distinguish an unexpected, non-Stripe failure — reported as HTTP 500 — from a Stripe failure, reported as 400 or, for a transient/5xx Stripe error, 503). This is the shop write endpoints' (`checkout`/`validateCart`/`applyDiscount`) new optional error-body `code` field.
+  - `@reblu/site-client`: (1) `shop.checkout()` now validates the returned Stripe Checkout URL is `https:` on an allowed host (default `checkout.stripe.com`, injectable via the new `RebluClientConfig.checkoutRedirectHosts`) before ever returning it, throwing the new `UnsafeCheckoutRedirectError` otherwise — exported alongside `isSafeCheckoutRedirectUrl` and `DEFAULT_CHECKOUT_REDIRECT_HOSTS`. (2) `ApiError.body` (`ApiErrorBody`/`ApiErrorDetails`) gains the optional `code` and `details.productIds` fields.
+  - `@reblu/site-next`: (1) `createShopCheckoutRoute` re-checks the Checkout URL server-side before responding to the browser (502 `unsafe_redirect` when it fails the check) — new `ShopCheckoutRouteOptions.allowedRedirectHosts`/`unsafeRedirectMessage`. (2) Native-review follow-up: that same route now strips `content-encoding`/`content-length`/`transfer-encoding` from its re-serialized response instead of forwarding them from the upstream proxy response, fixing a "browser tries to gunzip already-decoded JSON" failure mode.
+  - `@reblu/site-blocks`: adds `DEFAULT_SHOP_ERROR_MESSAGES` (a default Spanish message per `ShopErrorCode`, including `INTERNAL_ERROR`'s "Ha ocurrido un error inesperado. Inténtalo de nuevo en unos minutos.") and `getShopErrorMessage(code, overrides?, fallback?)`, which a SITE can override per code without restating the others.
+
+  All new fields/exports are additive and optional (REB-788) — a SITE that ignores `code`/`checkoutRedirectHosts` keeps working unchanged. The base-api side of this change (the `ShopErrorCode` schema itself, `checkout.service.ts`'s Stripe-vs-internal error classification, and `apiError()`'s options-object signature) is unpublished — it ships with the next base-api deploy, not through these changesets.
+
+- b86a16b: `addItem` (REB-837) now returns `{ status: 'added' | 'clamped' | 'refused',
+quantity }` instead of `void` — `quantity` is the resulting line quantity.
+  Backward compatible: existing callers that ignore the return value are
+  unaffected. `useCart()` gains `hydrated: boolean` (also exported standalone
+  as `useCartHydrated()`), built with `useSyncExternalStore` over zustand
+  persist's `onFinishHydration`/`hasHydrated` — fixes the "bump on every page
+  load" bug: `CartIcon`'s `bumpOnAdd` guard needs this to tell a real add apart
+  from the `itemCount` 0 -> N jump that `CartProvider`'s post-mount rehydration
+  causes on every page load with a non-empty persisted cart. README documents
+  the exact persisted shape (pinned by a test) and the hydration gotcha.
+- b86a16b: Standard success/cancel URLs (REB-837). `createShopCheckoutRoute` now
+  accepts `successPath`/`cancelPath`/`cartPath` and injects `successUrl`/
+  `cancelUrl` into the posted body — absolute from the REQUEST's own origin,
+  never a caller-supplied one — when the body doesn't already carry them; an
+  explicit value on the body always wins, so this is fully backward
+  compatible. Defaults to `/cart?pago=ok&session_id={CHECKOUT_SESSION_ID}` and
+  `/cart?pago=cancelado`. New `useCheckoutReturn()` (`./shop`) parses that
+  return query. `createProxyRoute` gained a small supporting `transformBody`
+  option (generic, additive) that this feature is built on.
+- b86a16b: Add `useShopOrderStatus(sessionId, opts?)` from `./shop` (REB-837): polls the
+  SITE's own order Route Handler with an `AbortController`, for a configurable
+  window (default 30s) with backoff, and clears the cart ONLY once the order
+  resolves to PAID. Returns `loading | paid | pending_timeout | failed |
+refunded | partially_refunded | not_found | error`, mapped from
+  `ShopOrder.paymentStatus` and the route's own 404, with a `recheck()` to
+  restart the poll loop. Fixes a real infinite-loop bug where a caller passing
+  the natural `{ buildUrl: (id) => ... }` object literal would re-fetch
+  forever — `buildUrl` is now read through a ref, not a polling-effect
+  dependency.
+- b86a16b: Gentle AI review follow-up (REB-837):
+  - `useShopOrderStatus` gains `requestTimeoutMs` (default 8000ms) — a single
+    hung/slow request is now aborted and retried, and `timeoutMs` (the WHOLE
+    polling window) is enforced by its own independent timer, not by checking
+    elapsed time inside `poll()`. Previously a request that never settled left
+    `status` stuck on `'loading'` forever, with no way to ever reach
+    `pending_timeout`.
+  - `useCartStore`'s `globalThis`-keyed singleton is now versioned
+    (`CART_STORE_PERSIST_VERSION`, folded into the registry key) and a new
+    `__resetCartStoreForTests()` clears the slot for tests that need to prove
+    something about the singleton mechanism itself. New test
+    (`tests/cart-store-cross-entry-singleton.test.ts`) proves `./cart` and
+    `./shop` resolve to the exact same store instance by building and loading
+    both real entries.
+
+### Patch Changes
+
+- b86a16b: Fix a cross-entry singleton bug in `useCartStore` (REB-837, found while
+  adopting `useShopOrderStatus` in demo-site): `splitting: false` bundles each
+  tsup entry standalone, so `./shop`'s relative import of `./cart/store`
+  inlined a SEPARATE store instance — `useShopOrderStatus`'s cart-clearing ran
+  against a disconnected store, never the one `@reblu/site-next/cart`
+  consumers actually read. `useCartStore` is now a `globalThis`-keyed
+  singleton (`Symbol.for(...)`), so every entry that imports it resolves to
+  the SAME instance regardless of how many times esbuild inlines the module.
+  No API change.
+- Updated dependencies [21feec3]
+- Updated dependencies [b86a16b]
+  - @reblu/site-contracts@1.6.0
+  - @reblu/site-client@5.3.0
+  - @reblu/site-ui@0.6.0
+
 ## 1.14.0
 
 ### Minor Changes

package/README.md

@@ -322,12 +322,14 @@ its own Client Component.
 | Export | Subpath | Needs `'use client'`? |
 | ------ | ------- | ---------------------- |
 | `CartProvider`, `useCart()`, `useCartStore`, `CartItem` | `./cart` | **Yes** |
-| `createShopCheckoutRoute()` | `./shop-route-handlers` | No |
+| `createShopCheckoutRoute(opts?)` | `./shop-route-handlers` | No |
 | `createShopValidateCartRoute()` | `./shop-route-handlers` | No |
 | `createShopApplyDiscountRoute()` | `./shop-route-handlers` | No |
 | `createShopCheckEmailRoute()` | `./shop-route-handlers` | No |
 | `createShopOrderRoute()` | `./shop-route-handlers` | No |
 | `getShopOrderSummary(client, sessionId)` | `./shop-server` | No |
+| `useShopOrderStatus(sessionId, opts?)` | `./shop` | **Yes** |
+| `useCheckoutReturn()` | `./shop` | **Yes** |
 
 ### Wiring a SITE
 
@@ -392,6 +394,193 @@ load-bearing: it stops the store from reading `localStorage` during SSR
 `useCartStore.persist.rehydrate()` in a `useEffect` — mount it once, or the
 cart UI renders permanently empty.
 
+**The exact persisted shape** (pinned by a test — `store.test.ts`, "persisted
+shape (REB-837 pin)" — any future change to it MUST bump the zustand
+`persist` `version` option with a migration, never edit the shape in place):
+
+```json
+{
+  "state": {
+    "items": [
+      {
+        "productId": "p1",
+        "variantId": null,
+        "name": "Serum",
+        "variantName": "50ml",
+        "unitPrice": 1999,
+        "quantity": 2,
+        "imageUrl": "https://cdn.example.com/serum.png",
+        "maxStock": 10,
+        "taxRateBps": 2100,
+        "taxRateName": "IVA 21%"
+      }
+    ]
+  },
+  "version": 0
+}
+```
+
+No expiry — a cart written today is read back unchanged next month. Nothing
+clears it except an explicit `clearCart()` call, and the ONLY built-in caller
+of that is `useShopOrderStatus` (below), and only when the order resolves to
+`paid`.
+
+`useCartStore` is a `globalThis`-keyed singleton versioned by
+`CART_STORE_PERSIST_VERSION` (REB-837 review fix): every tsup entry that
+reaches for the store — `./cart` directly, `./shop` via `useShopOrderStatus`
+— resolves to the exact same instance, never a disconnected copy a build
+accidentally inlined. Bump `CART_STORE_PERSIST_VERSION` alongside a
+`migrate` option if the persisted shape ever changes incompatibly — that
+also mints a new singleton key, so a stale old-shape instance kept alive
+across a dev HMR reload can never satisfy the new one. `__resetCartStoreForTests()`
+clears the singleton slot for a test that needs to prove something about the
+mechanism itself; an ordinary test should keep resetting STATE via
+`useCartStore.setState(...)` in `beforeEach` instead.
+
+### The hydration gotcha (REB-837)
+
+`CartProvider` rehydrates AFTER mount (the `skipHydration` contract above),
+so on every page load with a non-empty persisted cart, `itemCount` jumps
+`0 -> N` the instant hydration finishes — observed in production on the
+Dermamedicin SITE as `CartIcon`'s badge "bumping" on every single page load,
+not just on a real add.
+
+`useCart()` exposes `hydrated: boolean` for exactly this (`false` on the
+server and on the very first client render, `true` once
+`persist.onFinishHydration` fires — built with `useSyncExternalStore`, server
+snapshot `false`). Pass it straight through to `CartIcon`'s `bumpOnAdd`:
+
+```tsx
+const { itemCount, hydrated } = useCart()
+<CartIcon itemCount={itemCount} href='/shop/cart' hydrated={hydrated} bumpOnAdd />
+```
+
+`CartIcon` compares `itemCount` AND `hydrated` against their own previous
+values — a bump only fires when the cart was ALREADY hydrated on the
+previous render and `itemCount` increased since. The simultaneous
+`false -> true` / `0 -> N` rehydration transition fails that first
+condition; a real add afterward (hydrated already `true` on both sides)
+passes it. A standalone `useCartHydrated()` is also exported for a SITE that
+only needs the flag.
+
+### `addItem`'s return value (REB-837)
+
+`addItem` (both on `useCartStore` and via `useCart()`) returns
+`{ status: 'added' | 'clamped' | 'refused', quantity: number }` — `quantity`
+is the RESULTING line quantity (`0` when refused and no line exists).
+Existing callers that ignore the return value keep working unchanged.
+
+- `'added'` — the full requested quantity was applied.
+- `'clamped'` — applied, but capped below what was requested by `maxStock`
+  (the line still GREW).
+- `'refused'` — nothing was added: an invalid quantity, the product is out of
+  stock, or the line was already at `maxStock` (REB-839 — this used to come
+  back as `'clamped'`). `quantity` is still the RESULTING line quantity, which
+  may be lower than before if fresher stock data reconciled the line down.
+
+Use this to drive an `AddToCartButton`/`AddedToCartToast` pair's copy — see
+`@reblu/site-blocks`'s README "Add-to-cart feedback" for the full recipe.
+
+### `useShopOrderStatus` — the order-confirmation flow (REB-837)
+
+```tsx
+'use client'
+import { useShopOrderStatus } from '@reblu/site-next/shop'
+import { OrderConfirmation } from '@reblu/site-blocks'
+import { useSearchParams } from 'next/navigation'
+
+export default function OrderConfirmationPage() {
+  const sessionId = useSearchParams().get('session_id')
+  const { status, order, recheck } = useShopOrderStatus(sessionId)
+
+  return (
+    <OrderConfirmation
+      status={status}
+      order={order}
+      sessionId={sessionId ?? undefined}
+      cartHref='/shop/cart'
+      onRecheck={recheck}
+    />
+  )
+}
+```
+
+Polls `GET /api/shop/order/{sessionId}` — the SITE's OWN Route Handler built
+from `createShopOrderRoute`, never base-api directly — via `fetch` with an
+`AbortController`, for a configurable window (`timeoutMs`, default 30000ms)
+with backoff (`intervalMs` × `backoffFactor` per attempt, capped at
+`maxIntervalMs`). Returns one of `loading | paid | pending_timeout | failed |
+refunded | partially_refunded | not_found | error`, mapped from
+`ShopOrder.paymentStatus` (`PENDING|PAID|FAILED|REFUNDED|PARTIALLY_REFUNDED`)
+and the route's own 404. `OrderConfirmation` accepts every one of these
+statuses directly — `loading`/`paid` are drop-in aliases for its original
+`polling`/`found` states, so existing callers on the old 3-state API are
+unaffected.
+
+Clears the cart (`@reblu/site-next/cart`'s store, imperatively — not
+`useCart()`, since this runs outside a component body) **ONLY on `paid`**.
+`recheck()` restarts the poll loop from `loading` — wire it to
+`OrderConfirmation`'s `onRecheck`, which renders it as the "Volver a
+comprobar" button on `pending_timeout`/`error`.
+
+Pass `buildUrl` to point at a non-default order route path; everything else
+(`timeoutMs`/`intervalMs`/`backoffFactor`/`maxIntervalMs`/`requestTimeoutMs`)
+tunes the polling window. Checkout is card-only today, so a `PENDING` order
+past the window is expected to be transient — see REB-836 for the
+redirect-origin hardening this flow sits behind.
+
+`timeoutMs` (default 30000ms) bounds the WHOLE polling window via its own
+independent timer — it fires `pending_timeout` even if a single request
+hangs forever, never relying on that request ever settling. `requestTimeoutMs`
+(default 8000ms) is the separate PER-REQUEST timeout: one slow/hung request
+past it is aborted and retried with backoff (transient, not fatal); only the
+window elapsing is terminal.
+
+### Standard success/cancel URLs (REB-837)
+
+`createShopCheckoutRoute` builds `successUrl`/`cancelUrl` for you when the
+posted body doesn't already include them — an EXPLICIT value on the body
+always wins, so a SITE that already builds its own is completely unaffected:
+
+```ts
+// app/api/shop/checkout/route.ts — defaults to /cart?pago=ok&session_id={CHECKOUT_SESSION_ID}
+// and /cart?pago=cancelado
+export const POST = createShopCheckoutRoute()
+
+// Custom cart path — reshapes BOTH defaults:
+export const POST = createShopCheckoutRoute({ cartPath: '/tienda/carrito' })
+
+// Fully custom paths:
+export const POST = createShopCheckoutRoute({
+  successPath: '/checkout/gracias?session_id={CHECKOUT_SESSION_ID}',
+  cancelPath: '/checkout/cancelado',
+})
+```
+
+Built absolute from the REQUEST's own origin (`request.nextUrl.origin`) —
+never a caller-supplied value, so the built URL can never point off-SITE.
+The `{CHECKOUT_SESSION_ID}` placeholder is preserved verbatim; Stripe
+substitutes it at redirect time.
+
+`useCheckoutReturn()` (client hook, `./shop`) parses the return query on the
+cart page:
+
+```tsx
+'use client'
+import { useCheckoutReturn } from '@reblu/site-next/shop'
+import { CartSummary } from '@reblu/site-blocks'
+
+function CartPage() {
+  const { status } = useCheckoutReturn() // 'ok' | 'cancelled' | null
+  // ...
+  return <CartSummary {...summaryProps} notice={status === 'cancelled'} />
+}
+```
+
+`CartSummary`/`CartLineList`'s `notice` prop (`@reblu/site-blocks`) renders
+the default «Pago cancelado: tu carrito sigue aquí» copy when `true`, or any
+custom `ReactNode` — see that package's README.
+
 ## Structured data (JSON-LD)
 
 `@reblu/site-next/json-ld` (REB-622, server-only, dependency-free) renders one

package/dist/cart.cjs

@@ -22,8 +22,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var cart_exports = {};
 __export(cart_exports, {
   CART_STORAGE_KEY: () => CART_STORAGE_KEY,
+  CART_STORE_PERSIST_VERSION: () => CART_STORE_PERSIST_VERSION,
   CartProvider: () => CartProvider,
+  __resetCartStoreForTests: () => __resetCartStoreForTests,
   useCart: () => useCart,
+  useCartHydrated: () => useCartHydrated,
   useCartStore: () => useCartStore
 });
 module.exports = __toCommonJS(cart_exports);
@@ -35,6 +38,7 @@ var import_react = require("react");
 var import_zustand = require("zustand");
 var import_middleware = require("zustand/middleware");
 var CART_STORAGE_KEY = "shop-cart";
+var CART_STORE_PERSIST_VERSION = 0;
 function isSameItem(a, productId, variantId) {
   return a.productId === productId && (a.variantId ?? null) === (variantId ?? null);
 }
@@ -47,65 +51,87 @@ function normalizeQuantity(quantity, maxStock) {
   if (maxTruncated < 1) return 0;
   return Math.min(truncated, maxTruncated);
 }
-var useCartStore = (0, import_zustand.create)()(
-  (0, import_middleware.persist)(
-    (set, get) => ({
-      items: [],
-      addItem: (item) => {
-        set((state) => {
-          const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId));
-          if (existing) {
-            if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {
+function createCartStore() {
+  return (0, import_zustand.create)()(
+    (0, import_middleware.persist)(
+      (set, get) => ({
+        items: [],
+        addItem: (item) => {
+          let outcome = { status: "refused", quantity: 0 };
+          set((state) => {
+            const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId));
+            if (existing) {
+              if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {
+                outcome = { status: "refused", quantity: 0 };
+                return {
+                  items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId))
+                };
+              }
+              const requestedQty = existing.quantity + item.quantity;
+              const newQty = normalizeQuantity(requestedQty, item.maxStock);
+              if (newQty < 1) {
+                outcome = { status: "refused", quantity: existing.quantity };
+                return {};
+              }
+              outcome = {
+                status: newQty <= existing.quantity ? "refused" : newQty < requestedQty ? "clamped" : "added",
+                quantity: newQty
+              };
               return {
-                items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId))
+                items: state.items.map(
+                  (i) => isSameItem(i, item.productId, item.variantId) ? { ...i, quantity: newQty, maxStock: item.maxStock } : i
+                )
               };
             }
-            const newQty = normalizeQuantity(existing.quantity + item.quantity, item.maxStock);
-            if (newQty < 1) {
+            const qty = normalizeQuantity(item.quantity, item.maxStock);
+            if (qty < 1) {
+              outcome = { status: "refused", quantity: 0 };
               return {};
             }
-            return {
-              items: state.items.map(
-                (i) => isSameItem(i, item.productId, item.variantId) ? { ...i, quantity: newQty, maxStock: item.maxStock } : i
-              )
-            };
-          }
-          const qty = normalizeQuantity(item.quantity, item.maxStock);
-          if (qty < 1) {
-            return {};
+            outcome = { status: qty < item.quantity ? "clamped" : "added", quantity: qty };
+            return { items: [...state.items, { ...item, quantity: qty }] };
+          });
+          return outcome;
+        },
+        removeItem: (productId, variantId) => {
+          set((state) => ({
+            items: state.items.filter((i) => !isSameItem(i, productId, variantId))
+          }));
+        },
+        updateQuantity: (productId, variantId, quantity) => {
+          const existing = get().items.find((i) => isSameItem(i, productId, variantId));
+          if (!existing) return;
+          const newQty = normalizeQuantity(quantity, existing.maxStock);
+          if (newQty < 1) {
+            get().removeItem(productId, variantId);
+            return;
           }
-          return { items: [...state.items, { ...item, quantity: qty }] };
-        });
-      },
-      removeItem: (productId, variantId) => {
-        set((state) => ({
-          items: state.items.filter((i) => !isSameItem(i, productId, variantId))
-        }));
-      },
-      updateQuantity: (productId, variantId, quantity) => {
-        const existing = get().items.find((i) => isSameItem(i, productId, variantId));
-        if (!existing) return;
-        const newQty = normalizeQuantity(quantity, existing.maxStock);
-        if (newQty < 1) {
-          get().removeItem(productId, variantId);
-          return;
-        }
-        set((state) => ({
-          items: state.items.map(
-            (i) => isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i
-          )
-        }));
-      },
-      clearCart: () => set({ items: [] }),
-      getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),
-      getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0)
-    }),
-    {
-      name: CART_STORAGE_KEY,
-      skipHydration: true
-    }
-  )
+          set((state) => ({
+            items: state.items.map(
+              (i) => isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i
+            )
+          }));
+        },
+        clearCart: () => set({ items: [] }),
+        getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),
+        getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0)
+      }),
+      {
+        name: CART_STORAGE_KEY,
+        version: CART_STORE_PERSIST_VERSION,
+        skipHydration: true
+      }
+    )
+  );
+}
+var CART_STORE_GLOBAL_KEY = /* @__PURE__ */ Symbol.for(
+  `@reblu/site-next/cart-store@v${CART_STORE_PERSIST_VERSION}`
 );
+var globalForCartStore = globalThis;
+var useCartStore = globalForCartStore[CART_STORE_GLOBAL_KEY] ?? (globalForCartStore[CART_STORE_GLOBAL_KEY] = createCartStore());
+function __resetCartStoreForTests() {
+  delete globalForCartStore[CART_STORE_GLOBAL_KEY];
+}
 
 // src/cart/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -117,21 +143,38 @@ function CartProvider({ children }) {
 }
 
 // src/cart/use-cart.ts
+var import_react2 = require("react");
+function subscribeHydration(onStoreChange) {
+  return useCartStore.persist.onFinishHydration(onStoreChange);
+}
+function getHydratedSnapshot() {
+  return useCartStore.persist.hasHydrated();
+}
+function getServerHydratedSnapshot() {
+  return false;
+}
+function useCartHydrated() {
+  return (0, import_react2.useSyncExternalStore)(subscribeHydration, getHydratedSnapshot, getServerHydratedSnapshot);
+}
 function useCart() {
   const items = useCartStore((s) => s.items);
   const addItem = useCartStore((s) => s.addItem);
   const removeItem = useCartStore((s) => s.removeItem);
   const updateQuantity = useCartStore((s) => s.updateQuantity);
   const clearCart = useCartStore((s) => s.clearCart);
+  const hydrated = useCartHydrated();
   const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0);
   const itemCount = items.reduce((sum, item) => sum + item.quantity, 0);
-  return { items, total, itemCount, addItem, removeItem, updateQuantity, clearCart };
+  return { items, total, itemCount, hydrated, addItem, removeItem, updateQuantity, clearCart };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CART_STORAGE_KEY,
+  CART_STORE_PERSIST_VERSION,
   CartProvider,
+  __resetCartStoreForTests,
   useCart,
+  useCartHydrated,
   useCartStore
 });
 //# sourceMappingURL=cart.cjs.map

package/dist/cart.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cart/index.ts","../src/cart/provider.tsx","../src/cart/store.ts","../src/cart/use-cart.ts"],"sourcesContent":["'use client'\n\n/**\n * `@reblu/site-next/cart` (REB-829) — the SDK's cart client surface. This\n * barrel MUST begin with its OWN leading `'use client'` directive — same R4\n * rule as `./auth`/`./academy`: tsup only preserves a directive prologue\n * declared by the entry file itself (see `tsup.config.ts`).\n *\n * Mount `CartProvider` once near the root layout, then read/mutate the cart\n * from any Client Component via `useCart()` (derived `total`/`itemCount`) or\n * the raw `useCartStore` (per-field selectors, zustand-idiomatic). Both\n * share the SAME store instance and the SAME `shop-cart` localStorage key a\n * SITE migrating off a hand-rolled store already used.\n */\nexport { CartProvider } from './provider'\nexport { useCart, type UseCartResult } from './use-cart'\nexport { useCartStore, CART_STORAGE_KEY, type CartItem, type CartStore } from './store'\n","'use client'\n\nimport { useEffect } from 'react'\nimport { useCartStore } from './store'\n\n/**\n * `CartProvider` — mount this once near the root layout (inside a Client\n * Component boundary). It owns the ONE explicit-hydration call\n * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`\n * doc) — a SITE that forgets to mount it gets an always-empty cart that never\n * reads back whatever a previous visit (or page reload) persisted.\n */\nexport function CartProvider({ children }: { children: React.ReactNode }) {\n  useEffect(() => {\n    useCartStore.persist.rehydrate()\n  }, [])\n\n  return <>{children}</>\n}\n","import { create } from 'zustand'\nimport { persist } from 'zustand/middleware'\n\n/**\n * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same\n * shape, same quantity-clamping rules) from demo-site's local\n * `lib/store/cart-store.ts`, which every SITE was otherwise expected to\n * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a\n * SITE migrating from the local copy keeps its visitors' existing carts.\n *\n * `skipHydration: true` (zustand persist) is load-bearing for SSR: without\n * it, zustand's persist middleware reads `localStorage` synchronously during\n * module evaluation, which throws (or silently desyncs) on the server. The\n * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`\n * inside a `useEffect`, so hydration only ever happens client-side, after\n * mount — the same explicit-hydration contract the SITE README documents.\n */\nexport const CART_STORAGE_KEY = 'shop-cart'\n\nexport interface CartItem {\n  productId: string\n  variantId?: string | null\n  name: string\n  variantName?: string\n  /** Integer cents — every Reblu shop price travels as cents, never a float. */\n  unitPrice: number\n  quantity: number\n  imageUrl?: string\n  /** `null` means untracked/unlimited stock — never clamp against it. */\n  maxStock: number | null\n  /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */\n  taxRateBps?: number | null\n  taxRateName?: string | null\n}\n\nexport interface CartStore {\n  items: CartItem[]\n  addItem: (item: CartItem) => void\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n  getTotal: () => number\n  getItemCount: () => number\n}\n\nfunction isSameItem(a: CartItem, productId: string, variantId?: string | null): boolean {\n  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null)\n}\n\n/**\n * REB-829 review finding: neither `addItem` nor `updateQuantity` validated\n * `quantity` — `0`, a negative number, `NaN` (e.g. a stray `parseInt('')`\n * upstream), a non-integer, or `maxStock` itself being `0` (out of stock)\n * all used to leave an invalid line sitting in the cart, silently reaching\n * checkout.\n *\n * Normalizes to a safe POSITIVE INTEGER clamped to `maxStock`. Returns `0`\n * to signal \"not a valid positive quantity\" — callers decide what that\n * means for them: `addItem` ignores the call (never creates/corrupts a\n * line), `updateQuantity` removes the line (same as its pre-existing\n * `quantity <= 0` → remove contract, just now reached by more inputs).\n *\n * `Math.trunc` rounds toward zero (not `Math.floor`, which would round a\n * negative input further negative before the `< 1` check below ever saw it\n * — not a behavioural difference here since any negative result is\n * rejected either way, but `trunc` is the operation that actually means\n * \"drop the fractional part\").\n */\nfunction normalizeQuantity(quantity: number, maxStock: number | null): number {\n  if (!Number.isFinite(quantity)) return 0\n  const truncated = Math.trunc(quantity)\n  if (truncated < 1) return 0\n  if (maxStock === null) return truncated\n  const maxTruncated = Math.trunc(maxStock)\n  if (maxTruncated < 1) return 0\n  return Math.min(truncated, maxTruncated)\n}\n\nexport const useCartStore = create<CartStore>()(\n  persist(\n    (set, get) => ({\n      items: [],\n\n      addItem: (item) => {\n        set((state) => {\n          const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId))\n\n          if (existing) {\n            // REB-829 review follow-up (a): incoming maxStock is the\n            // FRESHEST stock signal available — if it says 0, the product is\n            // confirmed out of stock right now, so the existing line is\n            // removed outright (same contract as updateQuantity's own\n            // \"quantity resolves to <1 → remove\"), not merely left alone.\n            if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {\n              return {\n                items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId)),\n              }\n            }\n\n            const newQty = normalizeQuantity(existing.quantity + item.quantity, item.maxStock)\n            if (newQty < 1) {\n              // Invalid delta (NaN/non-positive quantity) — leave the\n              // existing, previously-valid line untouched rather than\n              // destroying good data because of one bad call.\n              return {}\n            }\n\n            // Refresh maxStock with the incoming value on every successful\n            // merge — the stale-maxStock finding: a stored line used to keep\n            // its ORIGINAL maxStock forever, so a later updateQuantity call\n            // clamped against stock data that could be long out of date.\n            return {\n              items: state.items.map((i) =>\n                isSameItem(i, item.productId, item.variantId)\n                  ? { ...i, quantity: newQty, maxStock: item.maxStock }\n                  : i,\n              ),\n            }\n          }\n\n          const qty = normalizeQuantity(item.quantity, item.maxStock)\n          if (qty < 1) {\n            // Invalid quantity, or maxStock 0 (out of stock) — never create\n            // a line nobody could actually buy.\n            return {}\n          }\n\n          return { items: [...state.items, { ...item, quantity: qty }] }\n        })\n      },\n\n      removeItem: (productId, variantId) => {\n        set((state) => ({\n          items: state.items.filter((i) => !isSameItem(i, productId, variantId)),\n        }))\n      },\n\n      updateQuantity: (productId, variantId, quantity) => {\n        const existing = get().items.find((i) => isSameItem(i, productId, variantId))\n        if (!existing) return\n\n        const newQty = normalizeQuantity(quantity, existing.maxStock)\n        if (newQty < 1) {\n          get().removeItem(productId, variantId)\n          return\n        }\n\n        set((state) => ({\n          items: state.items.map((i) =>\n            isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i,\n          ),\n        }))\n      },\n\n      clearCart: () => set({ items: [] }),\n\n      getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),\n\n      getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0),\n    }),\n    {\n      name: CART_STORAGE_KEY,\n      skipHydration: true,\n    },\n  ),\n)\n","'use client'\n\nimport { useCartStore, type CartItem } from './store'\n\nexport interface UseCartResult {\n  items: CartItem[]\n  /** Sum of every line's `unitPrice * quantity`, in integer cents. */\n  total: number\n  /** Sum of every line's `quantity`. */\n  itemCount: number\n  addItem: (item: CartItem) => void\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n}\n\n/**\n * `useCart` — the ergonomic entry point for a SITE's cart UI: a single\n * selector call that re-renders only on `items` changes, with `total`/\n * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small\n * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`\n * selectors, which are stable function references and would NOT trigger a\n * re-render on their own. A SITE that wants raw store access (existing\n * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still\n * import `useCartStore` directly — this hook doesn't replace it.\n */\nexport function useCart(): UseCartResult {\n  const items = useCartStore((s) => s.items)\n  const addItem = useCartStore((s) => s.addItem)\n  const removeItem = useCartStore((s) => s.removeItem)\n  const updateQuantity = useCartStore((s) => s.updateQuantity)\n  const clearCart = useCartStore((s) => s.clearCart)\n\n  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0)\n  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0)\n\n  return { items, total, itemCount, addItem, removeItem, updateQuantity, clearCart }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/cart/index.ts","../src/cart/provider.tsx","../src/cart/store.ts","../src/cart/use-cart.ts"],"sourcesContent":["'use client'\n\n/**\n * `@reblu/site-next/cart` (REB-829) — the SDK's cart client surface. This\n * barrel MUST begin with its OWN leading `'use client'` directive — same R4\n * rule as `./auth`/`./academy`: tsup only preserves a directive prologue\n * declared by the entry file itself (see `tsup.config.ts`).\n *\n * Mount `CartProvider` once near the root layout, then read/mutate the cart\n * from any Client Component via `useCart()` (derived `total`/`itemCount`) or\n * the raw `useCartStore` (per-field selectors, zustand-idiomatic). Both\n * share the SAME store instance and the SAME `shop-cart` localStorage key a\n * SITE migrating off a hand-rolled store already used.\n */\nexport { CartProvider } from './provider'\nexport { useCart, useCartHydrated, type UseCartResult } from './use-cart'\nexport {\n  useCartStore,\n  CART_STORAGE_KEY,\n  CART_STORE_PERSIST_VERSION,\n  __resetCartStoreForTests,\n  type CartItem,\n  type CartStore,\n  type AddItemOutcome,\n  type AddItemStatus,\n} from './store'\n","'use client'\n\nimport { useEffect } from 'react'\nimport { useCartStore } from './store'\n\n/**\n * `CartProvider` — mount this once near the root layout (inside a Client\n * Component boundary). It owns the ONE explicit-hydration call\n * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`\n * doc) — a SITE that forgets to mount it gets an always-empty cart that never\n * reads back whatever a previous visit (or page reload) persisted.\n */\nexport function CartProvider({ children }: { children: React.ReactNode }) {\n  useEffect(() => {\n    useCartStore.persist.rehydrate()\n  }, [])\n\n  return <>{children}</>\n}\n","import { create } from 'zustand'\nimport { persist } from 'zustand/middleware'\n\n/**\n * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same\n * shape, same quantity-clamping rules) from demo-site's local\n * `lib/store/cart-store.ts`, which every SITE was otherwise expected to\n * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a\n * SITE migrating from the local copy keeps its visitors' existing carts.\n *\n * `skipHydration: true` (zustand persist) is load-bearing for SSR: without\n * it, zustand's persist middleware reads `localStorage` synchronously during\n * module evaluation, which throws (or silently desyncs) on the server. The\n * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`\n * inside a `useEffect`, so hydration only ever happens client-side, after\n * mount — the same explicit-hydration contract the SITE README documents.\n */\nexport const CART_STORAGE_KEY = 'shop-cart'\n\n/**\n * The zustand `persist` schema version for the cart's PERSISTED shape (the\n * `CartItem[]` written to `localStorage` under `CART_STORAGE_KEY`) — bump\n * this (with a `migrate` option) if that shape ever changes incompatibly.\n * Also folded into {@link CART_STORE_GLOBAL_KEY} (REB-837 review fix): a\n * future incompatible shape change should mint a NEW global singleton\n * rather than let a stale, already-evaluated old-shape instance (e.g. kept\n * alive across an HMR reload in dev) silently satisfy the new one.\n */\nexport const CART_STORE_PERSIST_VERSION = 0\n\nexport interface CartItem {\n  productId: string\n  variantId?: string | null\n  name: string\n  variantName?: string\n  /** Integer cents — every Reblu shop price travels as cents, never a float. */\n  unitPrice: number\n  quantity: number\n  imageUrl?: string\n  /** `null` means untracked/unlimited stock — never clamp against it. */\n  maxStock: number | null\n  /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */\n  taxRateBps?: number | null\n  taxRateName?: string | null\n}\n\n/**\n * Outcome of `addItem` (REB-837): a SITE's add-to-cart feedback (toast,\n * `AddToCartButton`'s built-in confirmed/error state) needs to know what\n * actually happened, not just fire-and-forget — `'clamped'` only differs\n * from `'added'` in the RESULTING quantity reaching less than what was\n * requested (capped by `maxStock`) while the line still grew; `'refused'`\n * means nothing was added (invalid quantity, out of stock, or the line was\n * already at `maxStock` — REB-839).\n */\nexport type AddItemStatus = 'added' | 'clamped' | 'refused'\n\nexport interface AddItemOutcome {\n  status: AddItemStatus\n  /** The resulting line quantity after the call (`0` when refused and no line exists). */\n  quantity: number\n}\n\nexport interface CartStore {\n  items: CartItem[]\n  addItem: (item: CartItem) => AddItemOutcome\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n  getTotal: () => number\n  getItemCount: () => number\n}\n\nfunction isSameItem(a: CartItem, productId: string, variantId?: string | null): boolean {\n  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null)\n}\n\n/**\n * REB-829 review finding: neither `addItem` nor `updateQuantity` validated\n * `quantity` — `0`, a negative number, `NaN` (e.g. a stray `parseInt('')`\n * upstream), a non-integer, or `maxStock` itself being `0` (out of stock)\n * all used to leave an invalid line sitting in the cart, silently reaching\n * checkout.\n *\n * Normalizes to a safe POSITIVE INTEGER clamped to `maxStock`. Returns `0`\n * to signal \"not a valid positive quantity\" — callers decide what that\n * means for them: `addItem` ignores the call (never creates/corrupts a\n * line), `updateQuantity` removes the line (same as its pre-existing\n * `quantity <= 0` → remove contract, just now reached by more inputs).\n *\n * `Math.trunc` rounds toward zero (not `Math.floor`, which would round a\n * negative input further negative before the `< 1` check below ever saw it\n * — not a behavioural difference here since any negative result is\n * rejected either way, but `trunc` is the operation that actually means\n * \"drop the fractional part\").\n */\nfunction normalizeQuantity(quantity: number, maxStock: number | null): number {\n  if (!Number.isFinite(quantity)) return 0\n  const truncated = Math.trunc(quantity)\n  if (truncated < 1) return 0\n  if (maxStock === null) return truncated\n  const maxTruncated = Math.trunc(maxStock)\n  if (maxTruncated < 1) return 0\n  return Math.min(truncated, maxTruncated)\n}\n\n/**\n * REB-837 cross-entry singleton guard — the mutation that caught it: a\n * single test rendering `useShopOrderStatus` (the `./shop` tsup entry) and\n * asserting on `useCartStore` (the `./cart` entry) saw the order resolve to\n * `paid` but the cart stay non-empty. Root cause: `splitting: false` (R4,\n * `tsup.config.ts`) bundles each entry standalone, so a plain relative\n * import of this file from `./shop` INLINES a SEPARATE copy of this\n * `create(...)` call — a second, disconnected store instance with its own\n * state, not the one `@reblu/site-next/cart` consumers read. `clearCart()`\n * from inside the hook silently cleared the WRONG store.\n *\n * `globalThis` keyed by a `Symbol.for(...)` (same registry entry regardless\n * of which bundle's copy of this module evaluates it first) makes every\n * entry that imports this file — however many times esbuild inlines it —\n * resolve to the SAME store. Verified by mutation: removing this guard\n * (reverting to a bare `export const useCartStore = create(...)`) turns\n * `use-shop-order-status.test.ts`'s cart-clearing assertions red again once\n * the hook is exercised through its OWN entry rather than imported directly\n * within `cart`'s own test file (which never saw the bug, since it only\n * ever touches ONE copy of this module).\n */\nfunction createCartStore() {\n  return create<CartStore>()(\n    persist(\n      (set, get) => ({\n        items: [],\n\n        addItem: (item) => {\n          // REB-837: `set`'s updater can't return a value to the caller, so the\n          // outcome is captured in this closure variable and returned after.\n          let outcome: AddItemOutcome = { status: 'refused', quantity: 0 }\n\n          set((state) => {\n            const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId))\n\n            if (existing) {\n              // REB-829 review follow-up (a): incoming maxStock is the\n              // FRESHEST stock signal available — if it says 0, the product is\n              // confirmed out of stock right now, so the existing line is\n              // removed outright (same contract as updateQuantity's own\n              // \"quantity resolves to <1 → remove\"), not merely left alone.\n              if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {\n                outcome = { status: 'refused', quantity: 0 }\n                return {\n                  items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId)),\n                }\n              }\n\n              const requestedQty = existing.quantity + item.quantity\n              const newQty = normalizeQuantity(requestedQty, item.maxStock)\n              if (newQty < 1) {\n                // Invalid delta (NaN/non-positive quantity) — leave the\n                // existing, previously-valid line untouched rather than\n                // destroying good data because of one bad call.\n                outcome = { status: 'refused', quantity: existing.quantity }\n                return {}\n              }\n\n              // REB-839: nothing was gained when stock caps the line at (or,\n              // with fresher stock, below) what it already held — report that\n              // as 'refused', never as a partial-success 'clamped'. The line is\n              // still reconciled below to the fresher maxStock.\n              outcome = {\n                status:\n                  newQty <= existing.quantity\n                    ? 'refused'\n                    : newQty < requestedQty\n                      ? 'clamped'\n                      : 'added',\n                quantity: newQty,\n              }\n\n              // Refresh maxStock with the incoming value on every successful\n              // merge — the stale-maxStock finding: a stored line used to keep\n              // its ORIGINAL maxStock forever, so a later updateQuantity call\n              // clamped against stock data that could be long out of date.\n              return {\n                items: state.items.map((i) =>\n                  isSameItem(i, item.productId, item.variantId)\n                    ? { ...i, quantity: newQty, maxStock: item.maxStock }\n                    : i,\n                ),\n              }\n            }\n\n            const qty = normalizeQuantity(item.quantity, item.maxStock)\n            if (qty < 1) {\n              // Invalid quantity, or maxStock 0 (out of stock) — never create\n              // a line nobody could actually buy.\n              outcome = { status: 'refused', quantity: 0 }\n              return {}\n            }\n\n            outcome = { status: qty < item.quantity ? 'clamped' : 'added', quantity: qty }\n            return { items: [...state.items, { ...item, quantity: qty }] }\n          })\n\n          return outcome\n        },\n\n        removeItem: (productId, variantId) => {\n          set((state) => ({\n            items: state.items.filter((i) => !isSameItem(i, productId, variantId)),\n          }))\n        },\n\n        updateQuantity: (productId, variantId, quantity) => {\n          const existing = get().items.find((i) => isSameItem(i, productId, variantId))\n          if (!existing) return\n\n          const newQty = normalizeQuantity(quantity, existing.maxStock)\n          if (newQty < 1) {\n            get().removeItem(productId, variantId)\n            return\n          }\n\n          set((state) => ({\n            items: state.items.map((i) =>\n              isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i,\n            ),\n          }))\n        },\n\n        clearCart: () => set({ items: [] }),\n\n        getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),\n\n        getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0),\n      }),\n      {\n        name: CART_STORAGE_KEY,\n        version: CART_STORE_PERSIST_VERSION,\n        skipHydration: true,\n      },\n    ),\n  )\n}\n\ntype CartStoreApi = ReturnType<typeof createCartStore>\n\n/**\n * Versioned (REB-837 review fix) with {@link CART_STORE_PERSIST_VERSION} —\n * an incompatible shape change bumps that version, which mints a NEW\n * `Symbol.for(...)` registry key, so a stale old-shape singleton (e.g. kept\n * alive across an HMR reload in dev before a code change takes effect)\n * never satisfies the new one.\n */\nconst CART_STORE_GLOBAL_KEY = Symbol.for(\n  `@reblu/site-next/cart-store@v${CART_STORE_PERSIST_VERSION}`,\n)\n\ninterface GlobalWithCartStore {\n  [CART_STORE_GLOBAL_KEY]?: CartStoreApi\n}\n\nconst globalForCartStore = globalThis as typeof globalThis & GlobalWithCartStore\n\nexport const useCartStore: CartStoreApi =\n  globalForCartStore[CART_STORE_GLOBAL_KEY] ??\n  (globalForCartStore[CART_STORE_GLOBAL_KEY] = createCartStore())\n\n/**\n * TEST-ONLY (REB-837 review fix). Clears the `globalThis`-keyed slot so the\n * NEXT access to `useCartStore` — in THIS module instance — creates a fresh\n * store. The singleton is intentionally shared process-wide; most tests\n * should keep resetting STATE via `useCartStore.setState(...)` in\n * `beforeEach`, not the instance itself. Reach for this only to prove\n * something about the singleton mechanism (e.g. the cross-entry test in\n * `tests/cart-store-cross-entry-singleton.test.ts`) — it does not and\n * cannot affect an ALREADY-evaluated copy of this module inlined into a\n * different tsup entry's bundle (each such copy owns its own `const\n * globalForCartStore`/`CART_STORE_GLOBAL_KEY` closed over at that copy's\n * own module-evaluation time, same as any other ES module binding).\n */\nexport function __resetCartStoreForTests(): void {\n  delete globalForCartStore[CART_STORE_GLOBAL_KEY]\n}\n","'use client'\n\nimport { useSyncExternalStore } from 'react'\n\nimport { useCartStore, type AddItemOutcome, type CartItem } from './store'\n\nexport interface UseCartResult {\n  items: CartItem[]\n  /** Sum of every line's `unitPrice * quantity`, in integer cents. */\n  total: number\n  /** Sum of every line's `quantity`. */\n  itemCount: number\n  /**\n   * Whether `CartProvider`'s `persist.rehydrate()` has finished (REB-837).\n   * `false` on the server and on the very first client render — `items`\n   * (and therefore `itemCount`) jumps from `0` to whatever was persisted the\n   * instant hydration finishes, which is NOT a real \"item added\" event. A\n   * consumer driving `CartIcon`'s `bumpOnAdd` MUST gate the bump on this\n   * flag (see `CartIcon`'s own guard) or every page load with a non-empty\n   * cart bumps the badge once for free.\n   */\n  hydrated: boolean\n  addItem: (item: CartItem) => AddItemOutcome\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n}\n\nfunction subscribeHydration(onStoreChange: () => void): () => void {\n  return useCartStore.persist.onFinishHydration(onStoreChange)\n}\n\nfunction getHydratedSnapshot(): boolean {\n  return useCartStore.persist.hasHydrated()\n}\n\n/** Server snapshot is always `false` — the server never reads `localStorage`. */\nfunction getServerHydratedSnapshot(): boolean {\n  return false\n}\n\n/**\n * `useCartHydrated` — standalone so a SITE that only needs the flag (e.g. to\n * gate its own effects) doesn't have to subscribe to the whole cart via\n * `useCart()`.\n */\nexport function useCartHydrated(): boolean {\n  return useSyncExternalStore(subscribeHydration, getHydratedSnapshot, getServerHydratedSnapshot)\n}\n\n/**\n * `useCart` — the ergonomic entry point for a SITE's cart UI: a single\n * selector call that re-renders only on `items` changes, with `total`/\n * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small\n * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`\n * selectors, which are stable function references and would NOT trigger a\n * re-render on their own. A SITE that wants raw store access (existing\n * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still\n * import `useCartStore` directly — this hook doesn't replace it.\n */\nexport function useCart(): UseCartResult {\n  const items = useCartStore((s) => s.items)\n  const addItem = useCartStore((s) => s.addItem)\n  const removeItem = useCartStore((s) => s.removeItem)\n  const updateQuantity = useCartStore((s) => s.updateQuantity)\n  const clearCart = useCartStore((s) => s.clearCart)\n  const hydrated = useCartHydrated()\n\n  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0)\n  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0)\n\n  return { items, total, itemCount, hydrated, addItem, removeItem, updateQuantity, clearCart }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,mBAA0B;;;ACF1B,qBAAuB;AACvB,wBAAwB;AAgBjB,IAAM,mBAAmB;AAWzB,IAAM,6BAA6B;AAiD1C,SAAS,WAAW,GAAa,WAAmB,WAAoC;AACtF,SAAO,EAAE,cAAc,cAAc,EAAE,aAAa,WAAW,aAAa;AAC9E;AAqBA,SAAS,kBAAkB,UAAkB,UAAiC;AAC5E,MAAI,CAAC,OAAO,SAAS,QAAQ,EAAG,QAAO;AACvC,QAAM,YAAY,KAAK,MAAM,QAAQ;AACrC,MAAI,YAAY,EAAG,QAAO;AAC1B,MAAI,aAAa,KAAM,QAAO;AAC9B,QAAM,eAAe,KAAK,MAAM,QAAQ;AACxC,MAAI,eAAe,EAAG,QAAO;AAC7B,SAAO,KAAK,IAAI,WAAW,YAAY;AACzC;AAuBA,SAAS,kBAAkB;AACzB,aAAO,uBAAkB;AAAA,QACvB;AAAA,MACE,CAAC,KAAK,SAAS;AAAA,QACb,OAAO,CAAC;AAAA,QAER,SAAS,CAAC,SAAS;AAGjB,cAAI,UAA0B,EAAE,QAAQ,WAAW,UAAU,EAAE;AAE/D,cAAI,CAAC,UAAU;AACb,kBAAM,WAAW,MAAM,MAAM,KAAK,CAAC,MAAM,WAAW,GAAG,KAAK,WAAW,KAAK,SAAS,CAAC;AAEtF,gBAAI,UAAU;AAMZ,kBAAI,KAAK,aAAa,QAAQ,KAAK,MAAM,KAAK,QAAQ,IAAI,GAAG;AAC3D,0BAAU,EAAE,QAAQ,WAAW,UAAU,EAAE;AAC3C,uBAAO;AAAA,kBACL,OAAO,MAAM,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,GAAG,KAAK,WAAW,KAAK,SAAS,CAAC;AAAA,gBACjF;AAAA,cACF;AAEA,oBAAM,eAAe,SAAS,WAAW,KAAK;AAC9C,oBAAM,SAAS,kBAAkB,cAAc,KAAK,QAAQ;AAC5D,kBAAI,SAAS,GAAG;AAId,0BAAU,EAAE,QAAQ,WAAW,UAAU,SAAS,SAAS;AAC3D,uBAAO,CAAC;AAAA,cACV;AAMA,wBAAU;AAAA,gBACR,QACE,UAAU,SAAS,WACf,YACA,SAAS,eACP,YACA;AAAA,gBACR,UAAU;AAAA,cACZ;AAMA,qBAAO;AAAA,gBACL,OAAO,MAAM,MAAM;AAAA,kBAAI,CAAC,MACtB,WAAW,GAAG,KAAK,WAAW,KAAK,SAAS,IACxC,EAAE,GAAG,GAAG,UAAU,QAAQ,UAAU,KAAK,SAAS,IAClD;AAAA,gBACN;AAAA,cACF;AAAA,YACF;AAEA,kBAAM,MAAM,kBAAkB,KAAK,UAAU,KAAK,QAAQ;AAC1D,gBAAI,MAAM,GAAG;AAGX,wBAAU,EAAE,QAAQ,WAAW,UAAU,EAAE;AAC3C,qBAAO,CAAC;AAAA,YACV;AAEA,sBAAU,EAAE,QAAQ,MAAM,KAAK,WAAW,YAAY,SAAS,UAAU,IAAI;AAC7E,mBAAO,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,EAAE,GAAG,MAAM,UAAU,IAAI,CAAC,EAAE;AAAA,UAC/D,CAAC;AAED,iBAAO;AAAA,QACT;AAAA,QAEA,YAAY,CAAC,WAAW,cAAc;AACpC,cAAI,CAAC,WAAW;AAAA,YACd,OAAO,MAAM,MAAM,OAAO,CAAC,MAAM,CAAC,WAAW,GAAG,WAAW,SAAS,CAAC;AAAA,UACvE,EAAE;AAAA,QACJ;AAAA,QAEA,gBAAgB,CAAC,WAAW,WAAW,aAAa;AAClD,gBAAM,WAAW,IAAI,EAAE,MAAM,KAAK,CAAC,MAAM,WAAW,GAAG,WAAW,SAAS,CAAC;AAC5E,cAAI,CAAC,SAAU;AAEf,gBAAM,SAAS,kBAAkB,UAAU,SAAS,QAAQ;AAC5D,cAAI,SAAS,GAAG;AACd,gBAAI,EAAE,WAAW,WAAW,SAAS;AACrC;AAAA,UACF;AAEA,cAAI,CAAC,WAAW;AAAA,YACd,OAAO,MAAM,MAAM;AAAA,cAAI,CAAC,MACtB,WAAW,GAAG,WAAW,SAAS,IAAI,EAAE,GAAG,GAAG,UAAU,OAAO,IAAI;AAAA,YACrE;AAAA,UACF,EAAE;AAAA,QACJ;AAAA,QAEA,WAAW,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;AAAA,QAElC,UAAU,MAAM,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,SAAS,MAAM,KAAK,YAAY,KAAK,UAAU,CAAC;AAAA,QAEzF,cAAc,MAAM,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,SAAS,MAAM,KAAK,UAAU,CAAC;AAAA,MAC9E;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,SAAS;AAAA,QACT,eAAe;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AACF;AAWA,IAAM,wBAAwB,uBAAO;AAAA,EACnC,gCAAgC,0BAA0B;AAC5D;AAMA,IAAM,qBAAqB;AAEpB,IAAM,eACX,mBAAmB,qBAAqB,MACvC,mBAAmB,qBAAqB,IAAI,gBAAgB;AAexD,SAAS,2BAAiC;AAC/C,SAAO,mBAAmB,qBAAqB;AACjD;;;AD7QS;AALF,SAAS,aAAa,EAAE,SAAS,GAAkC;AACxE,8BAAU,MAAM;AACd,iBAAa,QAAQ,UAAU;AAAA,EACjC,GAAG,CAAC,CAAC;AAEL,SAAO,2EAAG,UAAS;AACrB;;;AEhBA,IAAAA,gBAAqC;AA8BrC,SAAS,mBAAmB,eAAuC;AACjE,SAAO,aAAa,QAAQ,kBAAkB,aAAa;AAC7D;AAEA,SAAS,sBAA+B;AACtC,SAAO,aAAa,QAAQ,YAAY;AAC1C;AAGA,SAAS,4BAAqC;AAC5C,SAAO;AACT;AAOO,SAAS,kBAA2B;AACzC,aAAO,oCAAqB,oBAAoB,qBAAqB,yBAAyB;AAChG;AAYO,SAAS,UAAyB;AACvC,QAAM,QAAQ,aAAa,CAAC,MAAM,EAAE,KAAK;AACzC,QAAM,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO;AAC7C,QAAM,aAAa,aAAa,CAAC,MAAM,EAAE,UAAU;AACnD,QAAM,iBAAiB,aAAa,CAAC,MAAM,EAAE,cAAc;AAC3D,QAAM,YAAY,aAAa,CAAC,MAAM,EAAE,SAAS;AACjD,QAAM,WAAW,gBAAgB;AAEjC,QAAM,QAAQ,MAAM,OAAO,CAAC,KAAK,SAAS,MAAM,KAAK,YAAY,KAAK,UAAU,CAAC;AACjF,QAAM,YAAY,MAAM,OAAO,CAAC,KAAK,SAAS,MAAM,KAAK,UAAU,CAAC;AAEpE,SAAO,EAAE,OAAO,OAAO,WAAW,UAAU,SAAS,YAAY,gBAAgB,UAAU;AAC7F;","names":["import_react"]}