@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/src/commerce/storefront/index.js

@@ -1,10 +1,20 @@
 /**
- * Storefront React layer — hooks + headless helpers for the cart, checkout
- * and order-received parts of the shopfront you build. Ships with the Base44
- * Commerce Template next to the framework-free `@/commerce/utils` (which it
- * builds on); needs React and nothing else. NO visual components ship here —
- * every pixel stays yours. The hooks own the contracts that are easy to get
- * subtly wrong; you own the markup.
+ * Storefront React layer — **headless**: hooks and render-prop components that
+ * own the store's logic and hand you the data; they render nothing and carry
+ * no styling. Every element, class and word of copy in the storefront is
+ * written by you, against these APIs. Ships with the Base44 Commerce Template
+ * next to the framework-free `@/commerce/utils` (which it builds on); needs
+ * React and nothing else.
+ *
+ * The split: **logic is premade, UI never is.** Checkout repricing, variant
+ * resolution, cart state, review policies, order-return verification — done
+ * here, and hand-rolling any of it is where storefront bugs cluster. What a
+ * checkout or a product page *looks like* is the store's identity, and no two
+ * stores should share it — so nothing here emits markup. Each hook returns a
+ * complete view-model (statuses to branch on, ready-to-map arrays, handlers,
+ * error objects), and each doc comment states the render rules that keep the
+ * store correct (e.g. an unbuyable variant option renders *disabled, not
+ * hidden*; a receipt page must render `paymentInstructions`).
  *
  * Setup (once, above every storefront route — it wraps <Routes>; placed as a
  * child of <Routes> React Router throws "is not a <Route> component"):
@@ -13,25 +23,47 @@
  *   import { base44 } from "@/api/base44Client";
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * - `StorefrontProvider` / `useStorefront` / `useStoreInfo` / `useFormatMoney`
- *     — one client, cached store info (the ONLY source of payment gateways,
- *     currency, countries), money formatting in the store's currency.
- * - `useCart` — the shared cart: state + every mutation, serialized so
- *     responses never apply out of order; a header badge, a cart drawer and
- *     the checkout all see the same view.
+ * ## Hooks
+ * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
+ *     shared client, cached store info (the ONLY source of payment gateways,
+ *     currency and countries), money in the store's currency.
+ * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
+ *     filters, `refreshing`, and failure as a visible state.
+ * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `useProductPrice` /
+ *     `useProductGallery` — the product page: fetch + variant selection +
+ *     quantity + price + gallery, race-safe, with `status: "not_found"` and
+ *     every add-to-cart failure handled. `variantAxes(view, pick)` (from
+ *     `@/commerce/utils`, re-exported here) turns the resolved view into a
+ *     render-ready model for the selector you write.
+ * - `useProductReviews` — the review list and the submit form, with the store's
+ *     policy as a prop and field errors matching the server's codes.
+ * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
+ *     `status`, render `lines` and `notices`), quantity steppers that clamp and
+ *     recover, and the coupon field a store with coupons must have.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
- *     checkout: address form state with automatic debounced shipping/tax
- *     recalculation once the address is complete, shipping-method choice,
- *     payment-method choice, a `canPlaceOrder` gate with named blockers, and
- *     `placeOrder` with the online-payment redirect handled.
- * - `ShippingMethodPicker` / `PaymentMethodPicker` — headless (render-prop)
- *     wrappers over the two choices that are store data, never hardcoded.
- * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
- * - `address.js` — framework-free address-completeness rules (also exported).
+ *     checkout: address state with automatic debounced shipping/tax
+ *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
+ *     named blockers, `placeOrder` with both navigations handled (online →
+ *     provider redirect, manual → `/order-received`).
+ * - `useAddressForm` / `useCountries` / `useTotalsLines` /
+ *     `useCheckoutBlockers` — the address form as a field spec you map to your
+ *     own inputs (state included, country options never null), one totals
+ *     projection for cart and order, and blocker codes turned into copy.
+ * - `useOrderReturn` — the mandatory `/order-received` page in one hook:
+ *     status, order, `lines`, `paymentLink`, `paymentInstructions`, noindex.
+ * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
+ *     meta and product structured data; receipts are `noindex`.
+ *
+ * ## Render-prop components (headless — children is a function, no markup ships)
+ * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
+ *     that are store data, never hardcoded, with their branching enumerated.
+ * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
+ *     `lines.map(...)` never calls a hook in a loop.
  *
- * Catalog calls (product list, product page) intentionally stay thin — use
- * `useStorefront()` for the client plus the variant helpers from
- * `@/commerce/utils`; those views are where the design freedom lives.
+ * ## Helpers re-exported from `@/commerce/utils`
+ * - `variantAxes(view, pick)` — axes → options with selected/disabled/stock
+ *     state derived, for the variant selector you write.
+ * - `productSpecs(product)` — `meta_data` → spec-table rows.
  */
 export {
   StorefrontProvider,
@@ -42,7 +74,7 @@ export {
   useCart,
 } from "./StorefrontProvider";
 export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
-export { useOrderReturn } from "./useOrderReturn";
+export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
 export {
   REQUIRED_BILLING_FIELDS,
@@ -50,3 +82,21 @@ export {
   shippingSlice,
   isShippingAddressComplete,
 } from "./address";
+
+// ── catalog ────────────────────────────────────────────────────────────────
+export { useProductList, useCategories, useRibbons } from "./useProductList";
+export { useProduct, useAddToCart, useAddToCartButton } from "./useProduct";
+export { useProductPrice, useMoney } from "./useProductPrice";
+export { useProductGallery } from "./useProductGallery";
+export { useProductReviews } from "./useProductReviews";
+
+// ── cart & checkout ────────────────────────────────────────────────────────
+export { useCartLine, useCoupon, CartLine } from "./useCartLine";
+export { useAddressForm, useCountries } from "./useAddressForm";
+export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotalsLines";
+
+// ── SEO ────────────────────────────────────────────────────────────────────
+export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
+
+// ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
+export { variantAxes, productSpecs } from "@/commerce/utils";

package/src/commerce/storefront/internal/useAsyncData.js

@@ -0,0 +1,86 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+
+/**
+ * Internal async primitive for the storefront hooks — the storefront twin of
+ * the admin's `useAsync`/`usePagedList`. Not exported from the package: it
+ * exists so every catalog hook gets the same three properties for free, each
+ * of which a hand-written `useEffect` reliably misses:
+ *
+ * - **Race-safety.** Only the newest request may publish. Two `getProduct`
+ *   calls in flight (the customer clicked a second product) can otherwise
+ *   resolve out of order and paint the wrong page.
+ * - **`loading` vs `refreshing`.** First load is `loading`; a reload caused by
+ *   changed params is `refreshing` with the previous data still on screen, so
+ *   a filter change doesn't flash an empty grid.
+ * - **Failure is a state, not a silence.** An error sets `error` and (with
+ *   `keepPreviousData`) leaves the last good data in place — the common
+ *   hand-rolled shape, `.finally(() => setLoading(false))`, renders a failed
+ *   fetch as a legitimately empty result.
+ *
+ * @param {(signal: {cancelled: boolean}) => Promise<any>} fn the request
+ * @param {Array<any>} deps re-runs when these change (like useEffect's)
+ * @param {{keepPreviousData?: boolean, enabled?: boolean, initialData?: any}} [opts]
+ */
+export function useAsyncData(fn, deps, { keepPreviousData = true, enabled = true, initialData = null } = {}) {
+  const [state, setState] = useState({
+    data: initialData,
+    loading: enabled,
+    refreshing: false,
+    error: null,
+  });
+  // Monotonic request id: a response may only publish if it is still the newest.
+  const requestId = useRef(0);
+  const hasData = useRef(initialData != null);
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+
+  const run = useCallback(
+    async ({ quiet = false } = {}) => {
+      if (!enabled) return;
+      const id = ++requestId.current;
+      const firstLoad = !hasData.current;
+      if (!quiet) {
+        setState((s) => ({
+          ...s,
+          loading: firstLoad,
+          refreshing: !firstLoad,
+          data: keepPreviousData ? s.data : firstLoad ? s.data : null,
+        }));
+      }
+      try {
+        const data = await fnRef.current();
+        if (id !== requestId.current) return; // a newer request won
+        hasData.current = true;
+        setState({ data, loading: false, refreshing: false, error: null });
+      } catch (e) {
+        if (id !== requestId.current) return;
+        setState((s) => ({
+          data: keepPreviousData ? s.data : null,
+          loading: false,
+          refreshing: false,
+          error: { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) },
+        }));
+      }
+    },
+    [enabled, keepPreviousData],
+  );
+
+  useEffect(() => {
+    run();
+    // Bump the id on unmount/dep-change so an in-flight response can't publish.
+    return () => {
+      requestId.current += 1;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [run, ...deps]);
+
+  const reload = useCallback(() => run(), [run]);
+  const reloadQuiet = useCallback(() => run({ quiet: true }), [run]);
+  const setData = useCallback((next) => {
+    hasData.current = true;
+    setState((s) => ({ ...s, data: typeof next === "function" ? next(s.data) : next }));
+  }, []);
+
+  return { ...state, reload, reloadQuiet, setData };
+}

package/src/commerce/storefront/useAddressForm.js

@@ -0,0 +1,96 @@
+import { useMemo } from "react";
+import { addressFieldSpec } from "@/commerce/utils";
+import { useStoreInfo } from "./StorefrontProvider";
+import { useCheckoutContext } from "./useCheckout";
+import { REQUIRED_BILLING_FIELDS } from "./address";
+
+/**
+ * The store's country list, **always as an array**.
+ *
+ *   const { options, loading } = useCountries();
+ *   <select>{options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}</select>
+ *
+ * `useStoreInfo().countries` is `null` until store info resolves, so mapping it
+ * directly white-screens the checkout on a cold load — the most severe defect
+ * observed in a generated storefront. Here the list is empty-then-full, never
+ * null, and `loading` says which.
+ */
+export function useCountries() {
+  const { countries, loading, error } = useStoreInfo();
+  const list = Array.isArray(countries) ? countries : [];
+  const options = useMemo(() => list.map((c) => ({ value: c.code, label: c.name })), [countries]); // eslint-disable-line react-hooks/exhaustive-deps
+  return { countries: list, options, loading, error };
+}
+
+/**
+ * useAddressForm — the checkout address form as a field list bound to the
+ * guided checkout. Needs a `<CheckoutProvider>` above it.
+ *
+ *   const { fields, set } = useAddressForm("billing");
+ *   {fields.map(f => (
+ *     <label key={f.key}>
+ *       {f.label}{f.required && " *"}
+ *       {f.type === "select"
+ *         ? <select value={f.value} onChange={e => set(f.key, e.target.value)}>
+ *             {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
+ *           </select>
+ *         : <input type={f.type} value={f.value} autoComplete={f.autoComplete}
+ *                  onChange={e => set(f.key, e.target.value)} />}
+ *       {f.error && <span role="alert">{f.error}</span>}
+ *     </label>
+ *   ))}
+ *
+ * Editing a field is all it takes to trigger the shipping/tax recalculation —
+ * `useCheckout` debounces and calls `set-shipping-address` once the address is
+ * complete enough to price. Two things the field list gets right that a
+ * hand-typed table did not: **`state` is present** (rates and taxes match on
+ * country + state, and it switches to a select for countries with
+ * subdivisions), and the country options are never null.
+ *
+ * @param {"billing"|"shipping"} [which]
+ * @param {{includeState?: boolean, includePhone?: boolean, includeCompany?: boolean}} [options]
+ */
+export function useAddressForm(which = "billing", options = {}) {
+  const checkout = useCheckoutContext();
+  const { countries, loading: countriesLoading } = useCountries();
+
+  const isBilling = which === "billing";
+  const values = isBilling ? checkout.billing : checkout.shipping;
+  const set = isBilling
+    ? (key, value) => checkout.updateBilling({ [key]: value })
+    : (key, value) => checkout.updateShipping({ [key]: value });
+
+  // `place-order` only enforces required fields on billing; a separate shipping
+  // address is priced, not validated field-by-field.
+  const missing = isBilling ? checkout.missingBillingFields : [];
+
+  const fields = useMemo(() => {
+    const spec = addressFieldSpec({
+      countries,
+      country: values?.country,
+      required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+      includeEmail: isBilling, // one email per order, on billing
+      ...options,
+    });
+    return spec.map((f) => ({
+      ...f,
+      value: values?.[f.key] ?? "",
+      // The address-level error ("we don't ship there") belongs on country.
+      error:
+        f.key === "country" && checkout.addressError?.code === "shipping_not_available"
+          ? checkout.addressError.message
+          : null,
+    }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [countries, values, isBilling, checkout.addressError, JSON.stringify(options)]);
+
+  return {
+    fields,
+    set,
+    values: values ?? {},
+    missing,
+    complete: missing.length === 0,
+    error: checkout.addressError ?? null,
+    countriesLoading,
+  };
+}

package/src/commerce/storefront/useCartLine.js

@@ -0,0 +1,221 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { useCart } from "./StorefrontProvider";
+
+/**
+ * useCartLine — one cart line's quantity control, with the interaction solved.
+ *
+ *   const l = useCartLine(line);
+ *   <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *   <span>{l.quantity}</span>
+ *   <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
+ *   <button onClick={l.remove}>Remove</button>
+ *   {l.error && <p role="alert">{l.error.message}</p>}
+ *
+ * What the obvious version (`onClick={() => updateItem(key, qty + 1)}`) gets
+ * wrong, and this does not: the mutation is **awaited and caught**, so a stock
+ * rejection shows as `error` instead of an unhandled rejection with the number
+ * silently snapping back; the displayed quantity is **optimistic** and rolls
+ * back only if the server disagrees; rapid clicks are **coalesced** into one
+ * request per settle instead of one per click; and `sold_individually` is
+ * respected, so a one-per-customer product has no working "+".
+ *
+ * @param {object} line a decorated line from `useCart().lines` (a raw
+ *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
+ * @param {{debounceMs?: number}} [options]
+ */
+export function useCartLine(line, { debounceMs = 250 } = {}) {
+  const { updateItem, removeItem } = useCart();
+  const serverQuantity = line?.quantity ?? 1;
+  const maxQuantity = line?.maxQuantity ?? (line?.sold_individually ? 1 : Infinity);
+
+  const [optimistic, setOptimistic] = useState(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState(null);
+  const timer = useRef(null);
+  const target = useRef(null);
+
+  // The server is the truth: whenever its quantity lands, drop the optimistic
+  // value (whether it agreed with us or not).
+  useEffect(() => {
+    setOptimistic(null);
+  }, [serverQuantity]);
+
+  useEffect(() => () => clearTimeout(timer.current), []);
+
+  const quantity = optimistic ?? serverQuantity;
+
+  const commit = useCallback(async () => {
+    const next = target.current;
+    if (next == null || next === serverQuantity) return;
+    setPending(true);
+    setError(null);
+    try {
+      await updateItem(line.item_key, next);
+    } catch (e) {
+      setOptimistic(null); // roll back to what the server still holds
+      setError({ code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) });
+    } finally {
+      setPending(false);
+      target.current = null;
+    }
+  }, [line?.item_key, serverQuantity, updateItem]);
+
+  const setQuantity = useCallback(
+    (n) => {
+      const clamped = Math.max(1, Math.min(maxQuantity, Math.floor(Number(n) || 1)));
+      setOptimistic(clamped);
+      setError(null);
+      target.current = clamped;
+      clearTimeout(timer.current);
+      timer.current = setTimeout(commit, debounceMs);
+    },
+    [maxQuantity, commit, debounceMs],
+  );
+
+  const increase = useCallback(() => setQuantity(quantity + 1), [quantity, setQuantity]);
+  const decrease = useCallback(() => setQuantity(quantity - 1), [quantity, setQuantity]);
+
+  const remove = useCallback(async () => {
+    clearTimeout(timer.current);
+    setPending(true);
+    setError(null);
+    try {
+      await removeItem(line.item_key);
+    } catch (e) {
+      setError({ code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) });
+    } finally {
+      setPending(false);
+    }
+  }, [line?.item_key, removeItem]);
+
+  return {
+    quantity,
+    setQuantity,
+    increase,
+    decrease,
+    remove,
+    pending,
+    error,
+    canIncrease: quantity < maxQuantity,
+    canDecrease: quantity > 1,
+    maxQuantity,
+    atMax: quantity >= maxQuantity,
+    atMin: quantity <= 1,
+    attributesLabel: line?.attributesLabel ?? "",
+    image: line?.image ?? null,
+  };
+}
+
+/**
+ * CartLine — headless per-line binding for the rows of a cart you render
+ * yourself. It renders **nothing**: the render function you pass as `children`
+ * receives the `useCartLine` controls for that line and returns your markup.
+ * It exists so a `lines.map(...)` doesn't tempt a hook call inside a loop:
+ *
+ *   const { lines } = useCart();
+ *   {lines.map(line => (
+ *     <CartLine key={line.item_key} line={line}>
+ *       {(l) => (
+ *         <li>
+ *           {line.name} {line.attributesLabel}
+ *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *           {l.quantity}
+ *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
+ *           <button onClick={l.remove}>Remove</button>
+ *           {l.error && <p role="alert">{l.error.message}</p>}
+ *         </li>
+ *       )}
+ *     </CartLine>
+ *   ))}
+ *
+ * Equivalent to extracting your own row component that calls `useCartLine` —
+ * use whichever reads better in your page.
+ *
+ * @param {{line: object, options?: {debounceMs?: number},
+ *   children: (controls: object) => React.ReactNode}} props
+ */
+export function CartLine({ line, options, children }) {
+  const controls = useCartLine(line, options);
+  if (typeof children !== "function") {
+    throw new Error("<CartLine> is headless: pass a render function as its only child.");
+  }
+  if (!line) return null;
+  return children(controls);
+}
+
+/**
+ * useCoupon — the coupon field. Small, and the difference between a store that
+ * can honour its own discounts and one that cannot.
+ *
+ *   const c = useCoupon();
+ *   <input value={c.code} onChange={(e) => c.setCode(e.target.value)} />
+ *   <button onClick={c.apply} disabled={c.applying}>Apply</button>
+ *   {c.error && <p role="alert">{c.error.message}</p>}
+ *   {c.applied.map(a => <Chip key={a.code} onRemove={() => c.remove(a.code)} …/>)}
+ *
+ * Coupons are admin-only data — a storefront cannot list codes, so a seeded
+ * code is reachable **only** through a field the customer types it into. If the
+ * store has any coupons, this field must exist somewhere in the cart or the
+ * checkout, or those codes can never be redeemed.
+ *
+ * An invalid, expired or ineligible code is **expected flow**: `apply()`
+ * resolves `{ ok: false, error }` and never throws — render `error.message`
+ * inline next to the field.
+ */
+export function useCoupon() {
+  const { cart, applyCoupon, removeCoupon } = useCart();
+  const [code, setCode] = useState("");
+  const [applying, setApplying] = useState(false);
+  const [error, setError] = useState(null);
+
+  const apply = useCallback(
+    async (explicit) => {
+      const value = String(explicit ?? code ?? "").trim();
+      if (!value) return { ok: false, error: { code: "empty", message: "Enter a code." } };
+      setApplying(true);
+      setError(null);
+      const res = await applyCoupon(value);
+      setApplying(false);
+      if (res.ok) {
+        setCode("");
+        return { ok: true, cart: res.cart };
+      }
+      const err = { code: res.code ?? "coupon_invalid", message: res.message };
+      setError(err);
+      return { ok: false, error: err };
+    },
+    [code, applyCoupon],
+  );
+
+  const remove = useCallback(
+    async (codeOrEntry) => {
+      const value = typeof codeOrEntry === "string" ? codeOrEntry : codeOrEntry?.code;
+      setError(null);
+      try {
+        await removeCoupon(value);
+        return { ok: true };
+      } catch (e) {
+        const err = { code: storefrontErrorCode(e) ?? "error", message: storefrontErrorMessage(e) };
+        setError(err);
+        return { ok: false, error: err };
+      }
+    },
+    [removeCoupon],
+  );
+
+  return {
+    code,
+    setCode,
+    apply,
+    remove,
+    applied: (cart?.coupons ?? []).map((c) => ({
+      code: c.code,
+      discount: c.discount ?? 0,
+      freeShipping: Boolean(c.free_shipping),
+    })),
+    applying,
+    error,
+    discountTotal: cart?.totals?.discount_total ?? 0,
+  };
+}

package/src/commerce/storefront/useCheckout.jsx

@@ -1,6 +1,7 @@
 import React, { createContext, useCallback, useContext, useEffect, useState } from "react";
 import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useStorefrontState } from "./StorefrontProvider";
+import { orderReceivedUrl } from "./useOrderReturn";
 import {
   REQUIRED_BILLING_FIELDS,
   isShippingAddressComplete,
@@ -62,10 +63,15 @@ function resolvePaymentMethod(gateways, picked) {
  * - **The gate.** `canPlaceOrder` + `blockers` say exactly what still stands
  *   between the customer and the order — drive the button's disabled state
  *   and the "what's missing" hints from them instead of re-deriving.
- * - **placeOrder.** Sends the order, clears the shared cart, and (by default)
- *   redirects to the provider's payment page when the gateway is online.
- *   Resolves to `{ ok: true, result }` or `{ ok: false, error }`; a manual-
- *   gateway result carries `result.payment_instructions` to render.
+ * - **placeOrder.** Sends the order, clears the shared cart, and navigates:
+ *   an online gateway redirects to the provider's payment page
+ *   (`redirectToPayment`), everything else lands on the order-received page
+ *   (`orderReceivedPath`, default `/order-received`) — which is where a manual
+ *   order's payment instructions are rendered, so the offline default confirms
+ *   properly with no extra wiring. Resolves to `{ ok: true, result }` or
+ *   `{ ok: false, error }`. Pass `orderReceivedPath: null` to handle the
+ *   result yourself (a manual-gateway result carries
+ *   `result.payment_instructions`).
  *
  * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
  * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
@@ -73,7 +79,8 @@ function resolvePaymentMethod(gateways, picked) {
  * `shipping_not_available`, `payment_method_required`.
  *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
- * country+city rule), `requiredBillingFields`, `redirectToPayment` (true).
+ * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
+ * `orderReceivedPath` ("/order-received"; null disables the navigation).
  */
 export function useCheckout(options = {}) {
   const {
@@ -81,6 +88,7 @@ export function useCheckout(options = {}) {
     addressComplete = isShippingAddressComplete,
     requiredBillingFields = REQUIRED_BILLING_FIELDS,
     redirectToPayment = true,
+    orderReceivedPath = "/order-received",
   } = options;
 
   const { client, info, cart, runCart, clearCart } = useStorefrontState();
@@ -204,6 +212,10 @@ export function useCheckout(options = {}) {
           typeof window !== "undefined"
         ) {
           window.location.assign(result.payment.checkout_url);
+        } else if (orderReceivedPath && !result.payment && typeof window !== "undefined") {
+          // A manual/offline order settles nothing online — land it on the
+          // order-received page, where its payment instructions are rendered.
+          window.location.assign(orderReceivedUrl(result, orderReceivedPath));
         }
         return { ok: true, result };
       } catch (e) {
@@ -224,7 +236,7 @@ export function useCheckout(options = {}) {
         setPlacing(false);
       }
     },
-    [placing, client, paymentMethod, billing, shipToDifferent, shipping, clearCart, redirectToPayment, runCart],
+    [placing, client, paymentMethod, billing, shipToDifferent, shipping, clearCart, redirectToPayment, orderReceivedPath, runCart],
   );
 
   return {

package/src/commerce/storefront/useOrderReturn.js

@@ -1,29 +1,36 @@
 import { useCallback, useEffect, useState } from "react";
-import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useStorefrontState } from "./StorefrontProvider";
+import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
  * useOrderReturn — the whole `/order-received` page in one hook. Mount the
  * route (it is mandatory — every payment link returns here) and branch on
- * `status`:
+ * `status`; the markup for every state is yours to write:
  *
- *   const { status, order, paymentLink, paymentInstructions, error, reload } =
- *     useOrderReturn();
- *   // "loading"   → spinner
- *   // "paid"      → thank-you + order summary (the order is now marked paid)
- *   // "unpaid"    → card order: offer paymentLink.url to pay now;
+ *   const { status, order, lines, paymentLink, paymentInstructions, error,
+ *     reload } = useOrderReturn();
+ *   // "loading"   → confirming copy (never an empty page)
+ *   // "paid"      → thank-you + order number + summary (the order is now paid)
+ *   // "unpaid"    → card order: link paymentLink.url to pay now;
  *   //               manual order: render paymentInstructions
- *   //               ({ description, account_details })
+ *   //               ({ description, account_details }) — these ARE how the
+ *   //               customer pays; a page that drops them strands the order
  *   // "cancelled" → payment was cancelled — offer paymentLink.url or support
  *   // "error"     → render error.message with a retry via reload()
  *
+ * `lines` are the order's items in the decorated cart-line shape, so the same
+ * row markup renders the bag and the confirmation; totals come from
+ * `useTotalsLines(order)`. The page is marked `noindex` automatically — a
+ * receipt carrying an order key must not rank (`seo: false` opts out).
+ *
  * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
  * with the payment provider server-side — safe and idempotent on every visit.
  *
  * `order` carries FLAT totals — `order.total`, `order.shipping_total`,
  * `order.total_tax`; there is no `order.totals` object on it.
  */
-export function useOrderReturn({ auto = true } = {}) {
+export function useOrderReturn({ auto = true, seo = true } = {}) {
   const { client } = useStorefrontState();
   const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
 
@@ -52,5 +59,24 @@ export function useOrderReturn({ auto = true } = {}) {
     if (auto) reload();
   }, [auto, reload]);
 
-  return { ...result, reload };
+  useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
+
+  return { ...result, lines: orderLines(result.order ?? null), reload };
+}
+
+/**
+ * The URL a just-placed manual/offline order should land on: the order-received
+ * page, carrying the id + key `useOrderReturn` reads back. `useCheckout` builds
+ * this itself by default (`orderReceivedPath`); use it directly only in a
+ * custom `placeOrder` flow.
+ *
+ * @param {{order_id: string, order_key: string}} result from `placeOrder`
+ * @param {string} [path]
+ */
+export function orderReceivedUrl(result, path = "/order-received") {
+  const q = new URLSearchParams({
+    order_id: result?.order_id ?? "",
+    order_key: result?.order_key ?? "",
+  });
+  return `${path}?${q}`;
 }