@cartbase/storefront 0.18.0 → 0.19.0

package/src/cart-drawer/context.tsx

@@ -134,6 +134,20 @@ export type CartMutationResult =
 /** The id prefix of a line the platform has not confirmed yet. */
 const PENDING_PREFIX = "optimistic-"
 
+/**
+ * A cart that can still be shopped. A completed cart is an order now: the
+ * platform still answers it, lines and all, but refuses every change to it.
+ */
+export function isLiveCart(cart: Cart | null | undefined): cart is Cart {
+  return Boolean(cart && !cart.completed_at)
+}
+
+/** The platform's answer that the cart a change was aimed at is over (ordered, or gone). */
+export function isEndedCartError(err: unknown): boolean {
+  const code = (err as { code?: unknown } | null)?.code
+  return code === "cart_completed" || code === "cart_not_found"
+}
+
 /**
  * A line the platform has not confirmed yet: it was added a moment ago and
  * carries a placeholder id. Its quantity and removal work already (the
@@ -196,6 +210,12 @@ type CartDrawerContextValue = {
   removeItem: (lineId: string) => Promise<boolean>
   /** Re-read the decorated cart (totals/gift-card tender are live per read). */
   refresh: () => Promise<void>
+  /**
+   * The cart is over (the order was placed): the drawer empties and the
+   * store's `onCartEnd` clears its cookie. The checkout calls it; the next
+   * add starts a new cart.
+   */
+  forget: () => Promise<void>
   /** True when the provider was given a client, so the methods above reach the platform. */
   canMutate: boolean
   labels: CartDrawerLabels
@@ -215,6 +235,7 @@ const CartDrawerContext = createContext<CartDrawerContextValue>({
   updateQuantity: async () => false,
   removeItem: async () => false,
   refresh: async () => {},
+  forget: async () => {},
   canMutate: false,
   labels: defaultCartDrawerLabels,
   hrefs: defaultHrefs,
@@ -351,6 +372,7 @@ export function CartDrawerProvider({
   client,
   cartId,
   onCartChange,
+  onCartEnd,
   onOptimisticError,
   labels: labelOverrides,
   hrefs: hrefOverrides,
@@ -374,6 +396,13 @@ export function CartDrawerProvider({
    * here so the cart survives reloads.
    */
   onCartChange?: (cart: Cart) => void
+  /**
+   * Fires when the cart is over: the order was placed, or the platform
+   * answered that the stored cart is completed or gone. Clear the stored
+   * cart id (the cookie) here; the next add creates a new cart and
+   * `onCartChange` stores its id.
+   */
+  onCartEnd?: () => void
   /** Ops funnel for every failed optimistic mutation (see module JSDoc). */
   onOptimisticError?: (failure: OptimisticCartError) => void
   /**
@@ -392,27 +421,55 @@ export function CartDrawerProvider({
   // it reads when a change's turn comes (state lags a render behind).
   const queue = useRef<CartMutationQueue | null>(null)
   if (!queue.current) queue.current = createCartMutationQueue()
-  const latest = useRef<Cart | null>(cart ?? null)
+  // A completed cart is an order: the drawer never holds one.
+  const latest = useRef<Cart | null>(isLiveCart(cart) ? cart : null)
+
+  // The store's hooks, read through refs so an inline handler never re-runs an effect.
+  const cartEnded = useRef(onCartEnd)
+  cartEnded.current = onCartEnd
 
   // Confirmed snapshot: seeded from the prop, replaced by every SDK
   // mutation response and by prop updates from server refreshes.
-  const [serverCart, setServerCart] = useState<Cart | null>(cart ?? null)
+  const [serverCart, setServerCart] = useState<Cart | null>(latest.current)
+
+  /** The cart is over: the drawer empties and the store forgets the id. */
+  const end = useCallback(() => {
+    latest.current = null
+    startTransition(() => setServerCart(null))
+    try {
+      cartEnded.current?.()
+    } catch {
+      // A store's handler must never break the drawer.
+    }
+  }, [])
+
   useEffect(() => {
     if (cart === undefined) return
     // A refresh carrying the cart as it was must not overwrite an answer
     // still on its way; the queue's own answers are newer.
     if (queue.current?.busy()) return
+    if (cart && !isLiveCart(cart)) {
+      end()
+      return
+    }
     latest.current = cart
     setServerCart(cart)
-  }, [cart])
+  }, [cart, end])
 
   // A confirmed cart becomes the snapshot inside a transition, so it lands
   // together with the end of the change that asked for it and a pending
-  // line is never shown twice.
-  const adopt = useCallback((next: Cart) => {
-    latest.current = next
-    startTransition(() => setServerCart(next))
-  }, [])
+  // line is never shown twice. A completed one ends the cart instead.
+  const adopt = useCallback(
+    (next: Cart) => {
+      if (!isLiveCart(next)) {
+        end()
+        return
+      }
+      latest.current = next
+      startTransition(() => setServerCart(next))
+    },
+    [end]
+  )
 
   // Client+cartId mode: read the cart on mount, through the queue, so an
   // add made before the read answers goes to this cart, not a new one.
@@ -423,15 +480,16 @@ export function CartDrawerProvider({
       try {
         const res = await sdkRetrieveCart(client, cartId)
         if (!cancelled) adopt(res.cart)
-      } catch {
-        // 404 cart_not_found (expired/foreign id) → stay empty; the next
-        // addLine creates a fresh cart.
+      } catch (err) {
+        // A stored id the platform no longer knows: forget it. Any other
+        // failure (a network blip) keeps the id for the next visit.
+        if (!cancelled && isEndedCartError(err)) end()
       }
     })
     return () => {
       cancelled = true
     }
-  }, [cart, client, cartId, adopt])
+  }, [cart, client, cartId, adopt, end])
 
   const [optimisticCart, dispatchOptimistic] = useOptimistic(
     serverCart,
@@ -532,7 +590,8 @@ export function CartDrawerProvider({
   const confirm = useCallback(
     (next: Cart) => {
       adopt(next)
-      onCartChange?.(next)
+      // A completed cart has ended the cart; its id is never stored again.
+      if (isLiveCart(next)) onCartChange?.(next)
     },
     [adopt, onCartChange]
   )
@@ -561,13 +620,26 @@ export function CartDrawerProvider({
         ...display,
       }
       const work = queue.current!.run(async (): Promise<CartMutationResult> => {
+        // First add with no cart: create one with the item in a single
+        // call. region_id falls back to the store default server-side.
+        const create = () => sdkCreateCart(client, { items: [{ variant_id: variantId, quantity }] })
         try {
           const cartId = latest.current?.id
-          const res = cartId
-            ? await sdkAddLineItem(client, cartId, { variant_id: variantId, quantity })
-            : // First add with no cart: create one with the item in a single
-              // call. region_id falls back to the store default server-side.
-              await sdkCreateCart(client, { items: [{ variant_id: variantId, quantity }] })
+          let res
+          if (!cartId) {
+            res = await create()
+          } else {
+            try {
+              res = await sdkAddLineItem(client, cartId, { variant_id: variantId, quantity })
+            } catch (error) {
+              // The stored cart is over (ordered in another tab, or gone):
+              // Medusa's starter treats it as no cart, so a new one starts
+              // with this item.
+              if (!isEndedCartError(error)) throw error
+              end()
+              res = await create()
+            }
+          }
           confirm(res.cart)
           return { ok: true, cart: res.cart }
         } catch (error) {
@@ -577,7 +649,7 @@ export function CartDrawerProvider({
       })
       return showWhile(action, work)
     },
-    [client, confirm, report, showWhile]
+    [client, confirm, report, showWhile, end]
   )
 
   const addItem = useCallback(
@@ -599,7 +671,8 @@ export function CartDrawerProvider({
           confirm(res.cart)
           return true
         } catch (err) {
-          report({ type: "update_quantity", lineId, quantity: latestQuantity }, err)
+          if (isEndedCartError(err)) end()
+          else report({ type: "update_quantity", lineId, quantity: latestQuantity }, err)
           return false
         }
       })
@@ -608,7 +681,7 @@ export function CartDrawerProvider({
         work.then((sent) => sent === true)
       )
     },
-    [client, lineNow, confirm, report, showWhile]
+    [client, lineNow, confirm, report, showWhile, end]
   )
 
   const removeItem = useCallback(
@@ -627,13 +700,17 @@ export function CartDrawerProvider({
           confirm(res.cart)
           return true
         } catch (err) {
+          if (isEndedCartError(err)) {
+            end()
+            return true
+          }
           report(action, err)
           return false
         }
       })
       return showWhile(action, work)
     },
-    [client, lineNow, confirm, report, showWhile]
+    [client, lineNow, confirm, report, showWhile, end]
   )
 
   const refresh = useCallback(
@@ -645,12 +722,20 @@ export function CartDrawerProvider({
         try {
           const res = await sdkRetrieveCart(client, id)
           confirm(res.cart)
-        } catch {
-          // Keep the last snapshot on transient failure.
+        } catch (err) {
+          // A cart the platform no longer knows ends; a transient failure
+          // keeps the last snapshot.
+          if (isEndedCartError(err)) end()
         }
       })
     },
-    [client, confirm]
+    [client, confirm, end]
+  )
+
+  /** The order was placed: empty the drawer and let the store forget the id. */
+  const forget = useCallback(
+    (): Promise<void> => queue.current!.run(async () => end()),
+    [end]
   )
 
   // The mounted language is the default (2026-09-14): a store that mounts
@@ -681,6 +766,7 @@ export function CartDrawerProvider({
         updateQuantity,
         removeItem,
         refresh,
+        forget,
         canMutate: Boolean(client),
         labels,
         hrefs,

package/src/cart-drawer/index.ts

@@ -21,6 +21,8 @@ export {
   reduceCart,
   makeOptimisticLine,
   isPendingLine,
+  isLiveCart,
+  isEndedCartError,
   type CartMutationResult,
   type OptimisticCartAction,
   type OptimisticAddDisplay,

package/src/checkout/use-checkout-orchestration.ts

@@ -41,6 +41,8 @@ import {
   type UpdateCustomerInput,
 } from "../api/customers"
 import { isStripeLike } from "../lib/payment-constants"
+import { clearCartCookie } from "../lib/cookie-names"
+import { useCartDrawer } from "../cart-drawer/context"
 import compareAddresses from "./compare-addresses"
 import { translateAddressError } from "./address-error-copy"
 import { translatePaymentError } from "./payment-error-copy"
@@ -303,6 +305,9 @@ export function useCheckoutOrchestration({
   const contextOrderConfirmedPath = useOrderConfirmedPath()
   const orderConfirmedPath =
     orderConfirmedPathProp ?? contextOrderConfirmedPath
+  // The mounted cart drawer, emptied when the order is placed (a no-op
+  // when the store mounts none).
+  const { forget: forgetCart } = useCartDrawer()
 
   // ── Completed-cart detection ────────────────────────────────────────
   // Surfaced as a flag so the page-level server component can redirect
@@ -1041,6 +1046,12 @@ export function useCheckoutOrchestration({
 
     const { order } = await completeCart(client, cart.id)
 
+    // The cart is an order now (Medusa's placeOrder: removeCartId()): the
+    // stored id goes and the drawer empties, so the next add starts a new
+    // cart instead of being refused by the completed one.
+    clearCartCookie()
+    await forgetCart()
+
     if (onOrderPlaced) {
       onOrderPlaced(order)
     } else if (typeof window !== "undefined") {
@@ -1057,6 +1068,7 @@ export function useCheckoutOrchestration({
     client,
     cart.id,
     cart.metadata,
+    forgetCart,
     onOrderPlaced,
     orderConfirmedPath,
     resolveTrackingMetadata,

package/src/common/cart-button-client.tsx

@@ -18,9 +18,13 @@ import { useCartDrawer } from "../cart-drawer/context"
  * NOTE: depends on the sibling `cart-drawer` family's context (ported in
  * the same batch); mount inside `<CartDrawerProvider>`.
  */
-export function CartButtonClient({ cart }: { cart: Cart | null }) {
-  const { open } = useCartDrawer()
-  const totalItems = productItemCount(cart?.items)
+export function CartButtonClient({ cart }: { cart?: Cart | null }) {
+  const drawer = useCartDrawer()
+  // Leave `cart` out and the badge counts the drawer's own cart, the one
+  // the provider read in the browser, so the header needs no server read
+  // and the page around it can be prerendered.
+  const totalItems = productItemCount((cart === undefined ? drawer.cart : cart)?.items)
+  const { open } = drawer
 
   return (
     <button

package/src/lib/cookie-names.ts

@@ -3,9 +3,10 @@
  * (platform-fingerprints card, fingerprint #4 — cookie names are a
  * primary Wappalyzer/BuiltWith detection signal).
  *
- * The app still OWNS *setting* the cart cookie — carts.md is explicit that
- * "the SDK never persists the cart" — this module is the single source of
- * the NAME so every consumer emits the same wire fingerprint instead of
+ * The app decides WHEN the cart cookie is written (it hands
+ * `writeCartCookie` to the drawer's `onCartChange`); this module is the
+ * single source of the NAME and the shape, so every consumer emits the
+ * same wire fingerprint instead of
  * inventing its own prefix (the reference app previously hardcoded
  * `_barter_cart_id` locally in `examples/storefront/src/lib/config.ts`).
  *
@@ -40,6 +41,53 @@ export function readCartCookie(
   return get(CART_COOKIE) ?? get(LEGACY_CART_COOKIE)
 }
 
+/** How long a stored cart id lives: thirty days. */
+export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30
+
+/**
+ * The stored cart id, read in the browser; null on the server or when none
+ * is stored. A storefront hands it to `CartDrawerProvider` as `cartId`, so
+ * no page reads the cart cookie on the server and every page can be
+ * prerendered (Cache Components).
+ */
+export function readBrowserCartId(): string | null {
+  if (typeof document === "undefined") return null
+  const cookies = new Map(
+    document.cookie
+      .split("; ")
+      .filter(Boolean)
+      .map((row) => {
+        const at = row.indexOf("=")
+        return [row.slice(0, at), decodeURIComponent(row.slice(at + 1))] as const
+      })
+  )
+  return readCartCookie((name) => cookies.get(name) || undefined) ?? null
+}
+
+/**
+ * Store the cart id in the browser, under the current name: what a
+ * storefront hands to `CartDrawerProvider`'s `onCartChange`. A no-op on the
+ * server.
+ */
+export function writeCartCookie(cartId: string): void {
+  if (typeof document === "undefined") return
+  document.cookie = `${CART_COOKIE}=${encodeURIComponent(cartId)};path=/;max-age=${CART_COOKIE_MAX_AGE};samesite=lax`
+}
+
+/**
+ * Forget the stored cart in the browser, under both names: Medusa's
+ * `removeCartId()`. The package's checkout calls it when the order is
+ * placed, and a store hands it to `CartDrawerProvider`'s `onCartEnd` so a
+ * cart that turned out to be completed or gone is forgotten too. A no-op
+ * on the server.
+ */
+export function clearCartCookie(): void {
+  if (typeof document === "undefined") return
+  for (const name of [CART_COOKIE, LEGACY_CART_COOKIE]) {
+    document.cookie = `${name}=;path=/;max-age=0;samesite=lax`
+  }
+}
+
 /**
  * THE VISITOR ID — our own per-browser id and the join key between browsing
  * and money (ecommerce-analytics §3.1). It is OURS deliberately: the

package/src/locales/bg.ts

@@ -389,6 +389,13 @@ export const bg: StorefrontLocale = {
     showPhoto: "Покажи снимка",
     playVideo: "Пусни видео",
     close: "Затвори",
+    openReview: "Отвори отзива",
+    verifiedInfo: "Какво значи потвърден",
+    storeReply: "Отговор от магазина",
+    previous: "Предишен",
+    next: "Следващ",
+    mediaAlt: "Снимка {n} от {total}, {name}",
+    showMediaAt: "Покажи снимка {n}",
     expiredTitle: "Този линк за отзив е изтекъл",
     expiredBody:
       "Линкът беше валиден 60 дни от датата на покупката. Ако искаш да оставиш отзив, пиши ни на {email}.",

package/src/locales/es.ts

@@ -399,6 +399,13 @@ export const es: StorefrontLocale = {
     showPhoto: "Ver foto",
     playVideo: "Reproducir vídeo",
     close: "Cerrar",
+    openReview: "Abrir la valoración",
+    verifiedInfo: "Qué significa compra verificada",
+    storeReply: "Respuesta de la tienda",
+    previous: "Anterior",
+    next: "Siguiente",
+    mediaAlt: "Foto {n} de {total} de {name}",
+    showMediaAt: "Ver foto {n}",
     expiredTitle: "Este enlace de valoración ha caducado",
     expiredBody:
       "El enlace era válido durante 60 días desde tu compra. Si quieres dejar una valoración, escríbenos a {email}.",

package/src/products/product-actions-wrapper.tsx

@@ -23,8 +23,12 @@ type ProductActionsWrapperProps = {
   id: string
   /** Pricing context so `calculated_price` is present for the price panel. */
   pricingContext?: PricingContextQuery
-  /** The variant the address names; see the product page contract. */
-  initialVariantId?: string | null
+  /**
+   * The variant the address names; see the product page contract. A promise
+   * is read here, behind the template's boundary, so a page on Cache
+   * Components never reads its query outside one.
+   */
+  initialVariantId?: string | null | Promise<string | null | undefined>
   /** A server action; leave it out for the instant add through the mounted cart drawer. */
   addToCart?: (input: AddToCartInput) => Promise<void>
   onAddToCart?: (product: StoreProduct, variant: StoreProductVariant) => void
@@ -40,6 +44,9 @@ export async function ProductActionsWrapper({
   onAddToCart,
   openCart,
 }: ProductActionsWrapperProps) {
+  // The address first: it is request data, so the live read never runs
+  // while a build prerenders the page.
+  const variantId = await initialVariantId
   let product: StoreProduct
   try {
     const res = await retrieveProduct(client, id, pricingContext)
@@ -52,7 +59,7 @@ export async function ProductActionsWrapper({
   return (
     <ProductActions
       product={product}
-      initialVariantId={initialVariantId}
+      initialVariantId={variantId}
       addToCart={addToCart}
       onAddToCart={onAddToCart}
       openCart={openCart}

package/src/products/product-template.tsx

@@ -26,6 +26,8 @@ import { RelatedProducts } from "./related-products"
 import { ProductInfo } from "./product-info"
 import { ProductActionsWrapper } from "./product-actions-wrapper"
 
+type VariantParam = string | null | Promise<string | null | undefined>
+
 type ProductTemplateProps = {
   client: StorefrontClient
   product: StoreProduct
@@ -59,11 +61,13 @@ type ProductTemplateProps = {
   /** Anything else the store wants in the accordion, appended in order. */
   sections?: ProductSection[]
   /**
-   * The variant the address names: pass `searchParams.variant` from the
-   * page, so the server renders that variant's price, code and stock and
-   * nothing flashes (the product page contract, `use-product-actions.ts`).
+   * The variant the address names, so the server renders that variant's
+   * price, code and stock and nothing flashes (the product page contract,
+   * `use-product-actions.ts`). On Cache Components pass it as a promise
+   * (`searchParams.then((q) => q.variant)`): the live buy box reads it
+   * behind its boundary and the rest of the page stays prerendered.
    */
-  initialVariantId?: string | null
+  initialVariantId?: VariantParam
   /** The store's own card for the related strip; the library's preview without it. */
   renderProduct?: ComponentType<{ product: StoreProduct }>
 }
@@ -112,7 +116,7 @@ export function ProductTemplate({
               <ProductActions
                 disabled={true}
                 product={product}
-                initialVariantId={initialVariantId}
+                initialVariantId={typeof initialVariantId === "string" ? initialVariantId : null}
                 addToCart={addToCart}
                 onAddToCart={onAddToCart}
                 openCart={openCart}

package/src/products/use-product-actions.ts

@@ -31,7 +31,7 @@
  * to out of stock until the choice changes.
  */
 import { useCallback, useEffect, useMemo, useState } from "react"
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { usePathname, useRouter } from "next/navigation"
 
 import type { StoreProduct, StoreProductVariant } from "../api/products"
 import { useCartDrawer } from "../cart-drawer/context"
@@ -102,7 +102,6 @@ export function useProductActions({
   const router = useRouter()
   const drawer = useCartDrawer()
   const pathname = usePathname()
-  const searchParams = useSearchParams()
   const variants = product.variants ?? []
 
   const [chosen, setChosen] = useState<OptionChoices>(() => {
@@ -127,12 +126,16 @@ export function useProductActions({
     setQuantityState(Math.max(1, Math.floor(next) || 1))
   }, [])
 
-  // Rule 3: the address follows the choice, in the browser alone.
+  // Rule 3: the address follows the choice, in the browser alone. The query
+  // is read here, when the address is written, and never while rendering: a
+  // render that reads the query is request data, and would stop a store on
+  // Cache Components from prerendering its product pages.
   useEffect(() => {
     if (!syncAddress || variants.length < 2 || !variant) return
-    if (searchParams.get(VARIANT_PARAM) === variantParamValue(variant.id)) return
-    window.history.replaceState(null, "", variantHref(pathname, searchParams, variant.id))
-  }, [syncAddress, variants.length, variant, searchParams, pathname])
+    const search = new URLSearchParams(window.location.search)
+    if (search.get(VARIANT_PARAM) === variantParamValue(variant.id)) return
+    window.history.replaceState(null, "", variantHref(pathname, search, variant.id))
+  }, [syncAddress, variants.length, variant, pathname])
 
   const inStock = useMemo(() => {
     if (!variant) return false

package/src/reviews-ui/index.ts

@@ -50,11 +50,15 @@ export {
   type RatingDistributionProps,
 } from "./star-badge"
 
+export { ReviewList, type ReviewListProps } from "./review-list"
+
+export { ReviewLightbox, type ReviewLightboxProps } from "./review-lightbox"
+
 export {
-  ReviewList,
-  ReviewLightbox,
-  type ReviewListProps,
-} from "./review-list"
+  lightboxMedia,
+  stepLightbox,
+  type LightboxPosition,
+} from "./lightbox-state"
 
 export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
 

package/src/reviews-ui/labels.ts

@@ -31,6 +31,18 @@ export type ReviewsUiLabels = {
   showPhoto: string
   playVideo: string
   close: string
+  // — lightbox —
+  /** A review card's own button: the whole card opens the lightbox. */
+  openReview: string
+  /** The info button beside "Verified"; its popover says `verifiedTitle`. */
+  verifiedInfo: string
+  storeReply: string
+  previous: string
+  next: string
+  /** `{n}` = position, `{total}` = the review's photo count, `{name}` = reviewer. */
+  mediaAlt: string
+  /** A dot under the photo; `{n}` = position. */
+  showMediaAt: string
   // — wizard: entry states (ported from the alenika /review/[token] page) —
   expiredTitle: string
   /** `{email}` = store support email. */
@@ -133,6 +145,13 @@ export const defaultReviewsUiLabels: ReviewsUiLabels = {
   showPhoto: "View photo",
   playVideo: "Play video",
   close: "Close",
+  openReview: "Open the review",
+  verifiedInfo: "What verified means",
+  storeReply: "Reply from the store",
+  previous: "Previous",
+  next: "Next",
+  mediaAlt: "Photo {n} of {total} from {name}",
+  showMediaAt: "Show photo {n}",
   expiredTitle: "This review link has expired",
   expiredBody:
     "The link was valid for 60 days after your purchase. If you'd like to leave a review, write to us at {email}.",

package/src/reviews-ui/lightbox-state.ts

@@ -0,0 +1,46 @@
+/**
+ * Where the review lightbox stands, and how it steps. Pure, no React, so
+ * every widget that opens the lightbox (the review list, a carousel, a
+ * store's own row of reviews) walks the same sequence. Unit-tested in
+ * tests/unit/storefront-review-lightbox.test.ts.
+ */
+import type { PublicReview, ReviewMedia } from "../api/reviews"
+
+/** The open review (its index in the widget's list) and which of its photos or videos. */
+export interface LightboxPosition {
+  review: number
+  media: number
+}
+
+/**
+ * A review's photos and videos as the lightbox shows them: the SAME
+ * filtered list the cards count their indexes from, so a falsy entry can
+ * never shift which item opens (the Alenika production fix).
+ */
+export function lightboxMedia(review: Pick<PublicReview, "media"> | undefined): ReviewMedia[] {
+  return (review?.media ?? []).filter(Boolean)
+}
+
+/**
+ * One step through the reviews: through the open review's photos first,
+ * then on to the next review's first one, or back to the previous review's
+ * last. Null at either end, where the arrow is not drawn.
+ */
+export function stepLightbox(
+  reviews: ReadonlyArray<Pick<PublicReview, "media">>,
+  at: LightboxPosition,
+  direction: 1 | -1
+): LightboxPosition | null {
+  const count = lightboxMedia(reviews[at.review]).length
+  if (direction === 1) {
+    if (at.media + 1 < count) return { review: at.review, media: at.media + 1 }
+    if (at.review + 1 < reviews.length) return { review: at.review + 1, media: 0 }
+    return null
+  }
+  if (at.media > 0) return { review: at.review, media: at.media - 1 }
+  if (at.review > 0) {
+    const previous = lightboxMedia(reviews[at.review - 1]).length
+    return { review: at.review - 1, media: Math.max(previous - 1, 0) }
+  }
+  return null
+}