@base44/app-plugin-commerce 0.2.7 → 0.3.2

package/src/commerce/storefront/pickers.jsx

@@ -9,10 +9,24 @@ import { useFormatMoney } from "./StorefrontProvider";
  * can't skip a `shipping_status` state or invent a payment method.
  *
  * Every option comes decorated with plain states and one handler — `selected`
- * (boolean), `select()` (pick it) and pre-formatted money (`costLabel`) — so
- * the child is markup + classes and nothing else. `hint` is the one message
- * the picker wants shown right now (or null) — render it and the status
- * branching is done.
+ * (boolean), `select()` (pick it) and money formatted in the store's currency
+ * (`costLabel`) — so the child is markup + classes and nothing else.
+ *
+ * `hint` is the one thing the picker needs said right now, as a **code**, never
+ * as copy: `{ code, severity: "info"|"error", serverMessage }`. The words are
+ * the store's — write one line per code (there are three) in the store's own
+ * voice. `serverMessage` is set only when the backend explained the situation
+ * itself (an undeliverable address); it is more specific than anything you can
+ * write, so prefer it when present:
+ *
+ *   const SHIPPING_HINTS = {            // your words, once, near the checkout
+ *     missing_address: "Enter your address to see delivery options.",
+ *     none_available:  "We can't deliver to that address yet.",
+ *     syncing:         "Updating delivery options…",
+ *   };
+ *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>
+ *     {hint.serverMessage ?? SHIPPING_HINTS[hint.code]}
+ *   </p>}
  *
  * Both read the nearest <CheckoutProvider>, or take an explicit `checkout`
  * prop when you called `useCheckout` yourself.
@@ -27,40 +41,25 @@ function resolveCheckout(name, prop, ctx) {
 }
 
 /**
- * Shipping options. Renders null for a virtual cart (`not_needed`) and while
- * the cart is loading; otherwise calls `children` with:
- *
- *   {
- *     status,        // "missing_address" | "choice_required" | "chosen"
- *                    //   | "auto_selected" | "none_available"
- *     methods,       // [{ id, title, cost, costLabel, selected,
- *                    //    select }] — what this address is offered
- *     chosen,        // the chosen/auto-selected entry (with costLabel), or null
- *     selected,      // alias of `chosen` — the same name the payment picker uses
- *     choose,        // (id) => Promise — call with a method's id on pick
- *     mustChoose,    // status === "choice_required" → render methods as a picker
- *     single,        // exactly one method offered — already chosen; skip the
- *                    //   picker but still show `chosen.title` and `chosen.costLabel`
- *     syncing,       // an address edit is being repriced — show a subtle busy state
- *     hint,          // { code, message, severity: "info"|"error" } | null — the
- *                    //   one notice to show now (address missing / not deliverable
- *                    //   / repricing); render `hint.message`, done
- *     addressError,  // { code, message } | null — also surfaces on the address
- *   }                //   form's country field
+ * Shipping options. Renders null for a virtual cart (`not_needed`) and while the
+ * cart is loading; otherwise calls `children` with:
  *
- * The child's whole job:
- *
- *   {hint && <p role={hint.severity === "error" ? "alert" : "status"}>{hint.message}</p>}
- *   {mustChoose && methods.map(m => (
- *     <label key={m.id} className="…">
- *       <input type="radio" name="shipping-method" checked={m.selected} onChange={m.select}
- *              className="…" /> {m.title} <span>{m.costLabel}</span>
- *     </label>
- *   ))}
- *   {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+ *   status         "missing_address" | "choice_required" | "chosen"
+ *                  | "auto_selected" | "none_available"
+ *   methods        [{ id, title, cost, costLabel, selected, select }]
+ *   chosen         the chosen/auto-selected entry, or null
+ *   selected       alias of `chosen` (the name the payment picker uses)
+ *   choose         (id) => Promise
+ *   mustChoose     status === "choice_required" → render methods as a picker
+ *   single         exactly one method offered — already chosen
+ *   syncing        an address edit is being repriced
+ *   hint           { code, severity, serverMessage } | null (see above)
+ *   addressError   { code, message } | null — the server's own words
  *
  * `single` and `mustChoose` are never both true, and `single` guarantees
- * `chosen` — a single option still *shows* what it is, never a picker of one.
+ * `chosen` — a single option still *shows* what it is (title + `costLabel`),
+ * never a picker of one. Never render `cart.chosen_shipping_method` directly:
+ * it is the rate's id, which is why `chosen` is handed to you resolved.
  */
 export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("ShippingMethodPicker", checkoutProp, useCheckoutContextOptional());
@@ -84,11 +83,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     };
   const hint =
     status === "missing_address"
-      ? { code: "missing_address", severity: "info", message: "Delivery options appear once your address is entered." }
+      ? { code: "missing_address", severity: "info", serverMessage: null }
       : status === "none_available" || addressError?.code === "shipping_not_available"
-        ? { code: "none_available", severity: "error", message: addressError?.message ?? "We don't deliver to that address yet." }
+        ? { code: "none_available", severity: "error", serverMessage: addressError?.message ?? null }
         : syncing
-          ? { code: "syncing", severity: "info", message: "Updating delivery options…" }
+          ? { code: "syncing", severity: "info", serverMessage: null }
           : null;
   const decoratedChosen = decorate(chosen) ?? null;
   return children({
@@ -106,35 +105,22 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
 }
 
 /**
- * Payment methods — every gateway the admin has ENABLED, from store info
- * (their only source). Renders null while store info loads; otherwise calls
- * `children` with:
- *
- *   {
- *     gateways,   // [{ slug, title, description, online, selected,
- *                 //    select }] — admin-owned data, decorated
- *     value,      // the selected slug ("" while none)
- *     select,     // (slug) => void
- *     selected,   // the selected gateway entry, or null
- *     single,     // exactly one gateway — already selected; skip the picker but
- *                 //   still show its title so the customer knows how they pay
- *     hint,       // { code, message, severity } | null — set when there are no
- *   }             //   gateways: checkout is unavailable, say so
- *
- * The child's whole job:
+ * Payment methods — every gateway the admin has ENABLED, from store info (their
+ * only source). Renders null while store info loads; otherwise calls `children`
+ * with:
  *
- *   {hint && <p role="alert">{hint.message}</p>}
- *   {!single && gateways.map(g => (
- *     <label key={g.slug} className="…">
- *       <input type="radio" name="payment-method" checked={g.selected} onChange={g.select}
- *              className="…" /> {g.title} <span>{g.description}</span>
- *     </label>
- *   ))}
- *   {single && selected && <p>{selected.title} — {selected.description}</p>}
+ *   gateways   [{ slug, title, description, online, selected, select }]
+ *   value      the selected slug ("" while none)
+ *   select     (slug) => void
+ *   selected   the selected gateway entry, or null
+ *   single     exactly one gateway — already selected
+ *   hint       { code: "none_available", severity, serverMessage } | null —
+ *              no gateways at all: say checkout is unavailable, in your words
  *
  * `single` guarantees `value` and `selected` — never render the one-gateway
  * branch as "nothing selected yet" — and both re-resolve when store info
- * changes. Titles and descriptions are the admin's copy: render them, don't
+ * changes. A default-seeded store offers `offline` only, so never hardcode a
+ * card option. Titles and descriptions are the admin's copy: render them, don't
  * invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
@@ -153,7 +139,7 @@ export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   }));
   const hint =
     gateways.length === 0
-      ? { code: "none_available", severity: "error", message: "No payment method is available right now." }
+      ? { code: "none_available", severity: "error", serverMessage: null }
       : null;
   return children({
     gateways: decorated,

package/src/commerce/storefront/useCartLine.js

@@ -20,39 +20,23 @@ import { useCart } from "./StorefrontProvider";
  * request per settle instead of one per click; and `sold_individually` is
  * respected, so a one-per-customer product has no working "+".
  *
- * ## When `pending` settles — the exact window
+ * **When `pending` settles.** It is this row's flag, not the cart's, and not
+ * true for the whole gesture: a click only sets the optimistic quantity and
+ * (re)starts the 250ms timer, so a burst of clicks sends **one** request;
+ * `pending` goes true when that request leaves (`remove()` skips the wait); it
+ * returns to false only after the server's new cart view has been published
+ * through the provider's queue. So `pending === false` with `error === null`
+ * means this row, the cart's totals and any badge are all settled — it is the
+ * only mutation-settled signal (`useCart().status` never returns to
+ * `"loading"` for a mutation), and what a script driving the page waits on.
+ * Scope the busy state to this row: greying the whole cart for a 250ms step
+ * reads as a page-wide stall. On failure the quantity rolls back to what the
+ * server still holds and `error` is `{ code, message }`.
  *
- * `pending` is this line's own flag, not the cart's, and it is **not** true for
- * the whole gesture:
+ * It owns the quantity only. The row's own content — name, `attributesLabel`,
+ * image, money — you render from the `cart.items[n]` you passed in.
  *
- * 1. **Click → `pending` stays `false`.** `increase`/`decrease` only set the
- *    optimistic `quantity` and (re)start a `debounceMs` (250ms) timer. Nothing
- *    is in flight yet, and a further click restarts the timer, so a burst of
- *    clicks sends **one** request for the final number.
- * 2. **Debounce elapses → `pending` becomes `true`** and the request goes out.
- *    `remove()` skips this step: it cancels the timer and goes `pending`
- *    immediately.
- * 3. **`pending` returns to `false` only after the server's new cart view has
- *    been published to the provider** — the awaited mutation resolves through
- *    the provider's serialized queue, which sets the shared cart state before
- *    the await returns. So `pending === false` with `error === null` means this
- *    row's quantity, the cart's totals and any dependent badge are settled, not
- *    merely that the request finished.
- *
- * Two consequences worth designing for. **Disable and mark only this row**
- * (`disabled={!l.canIncrease || l.pending}`) — `pending` says nothing about the
- * other lines, and greying the whole cart because one stepper is busy makes a
- * 250ms update look like a page-wide stall. And **`pending` is the only
- * mutation-settled signal**: `useCart().status` never returns to `"loading"`
- * for a mutation (see its doc comment), so a caller that needs to know an
- * update landed — a script driving the page, a queued follow-up action — waits
- * on this flag, per row, and not on cart `status`.
- *
- * On failure `pending` returns to `false`, the optimistic quantity rolls back
- * to what the server still holds, and `error` is `{ code, message }`.
- *
- * @param {object} line a decorated line from `useCart().lines` (a raw
- *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
+ * @param {object} line one `cart.items[n]` from `useCart()`
  * @param {{debounceMs?: number}} [options]
  */
 export function useCartLine(line, { debounceMs = 250 } = {}) {
@@ -133,10 +117,6 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
     maxQuantity,
     atMax: quantity >= maxQuantity,
     atMin: quantity <= 1,
-    attributesLabel: line?.attributesLabel ?? "",
-    image: line?.image ?? null,
-    totalLabel: line?.totalLabel ?? "",
-    unitPriceLabel: line?.unitPriceLabel ?? "",
   };
 }
 
@@ -144,29 +124,18 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
  * 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:
+ * It exists so an `items.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 aria-busy={l.pending}>
- *           {line.name} {line.attributesLabel}
- *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
- *                   aria-label={`Decrease quantity of ${line.name}`}>−</button>
- *           {l.quantity}
- *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
- *                   aria-label={`Increase quantity of ${line.name}`}>+</button>
- *           <button onClick={l.remove} aria-label={`Remove ${line.name}`}>Remove</button>
- *           {l.totalLabel}
- *           {l.error && <p role="alert">{l.error.message}</p>}
- *         </li>
- *       )}
+ *   {cart.items.map(item => (
+ *     <CartLine key={item.item_key} line={item}>
+ *       {(l) => <li aria-busy={l.pending}>…your row, using item and l…</li>}
  *     </CartLine>
  *   ))}
  *
- * Equivalent to extracting your own row component that calls `useCartLine` —
- * use whichever reads better in your page.
+ * Give each row's controls their own accessible name (`Remove ${item.name}`):
+ * three buttons all named "Remove" are ambiguous to a screen reader and to a
+ * script driving the page. 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
@@ -179,79 +148,3 @@ export function CartLine({ line, options, children }) {
   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

@@ -39,50 +39,44 @@ function resolvePaymentMethod(gateways, picked) {
  * checkout must get right, so the page you build is only markup around it:
  *
  * - **Address → shipping/tax recalculation, automatic.** Edit the billing (or
- *   separate shipping) address through `updateBilling`/`updateShipping`; the
- *   moment the address is complete enough to price (default: country + city —
- *   see `isShippingAddressComplete`), the hook debounces and calls
- *   `set-shipping-address`, which recalculates every shipping option, its
- *   cost and the taxes. Half-typed addresses are never sent, an unchanged
- *   address is never re-sent, and an address the store doesn't ship to
- *   surfaces as `addressError` — show it on the address fields.
- * - **Shipping choice.** `shippingStatus` mirrors the cart's state:
- *   `auto_selected` (one option, already applied — just display
- *   `chosenShippingMethod`), `chosen`, `choice_required` (render
- *   `shippingMethods` and call `chooseShippingMethod(id)`), `missing_address`
- *   (collect the address), `not_needed` (virtual cart — render nothing).
- *   `singleShippingMethod` flags the one-option case, and `chosenShippingMethod`
- *   is filled for it — a single option is never left unselected.
+ *   separate shipping) address through `updateBilling`/`updateShipping`; once
+ *   the address is complete enough to price (default: country + city, see
+ *   `isShippingAddressComplete`), the hook debounces and calls
+ *   `set-shipping-address`, recalculating every option, its cost and the taxes.
+ *   Half-typed addresses are never sent, an unchanged address is never re-sent,
+ *   and an address the store doesn't ship to surfaces as `addressError` (the
+ *   server's own words) — render it on the address fields.
+ * - **Shipping choice.** `shippingStatus` mirrors the cart: `auto_selected`
+ *   (one option, already applied — display `chosenShippingMethod`), `chosen`,
+ *   `choice_required` (render `shippingMethods`, call
+ *   `chooseShippingMethod(id)`), `missing_address`, `none_available`,
+ *   `not_needed` (virtual cart — render nothing). `singleShippingMethod` flags
+ *   the one-option case and `chosenShippingMethod` is filled for it, so a single
+ *   option is never left unselected and never rendered as a picker of one.
  * - **Payment choice.** `paymentMethods` come from store info (their ONLY
- *   source); a store with exactly one enabled gateway gets it selected
- *   (`singlePaymentMethod`, with `selectedGateway` filled) from the first
- *   render that has store info. The selection is derived from the current
- *   gateway list, not remembered: when store info changes, a gateway that is
- *   no longer enabled is dropped and a list that is down to one gateway
- *   selects it — the customer's own pick survives as long as it stays enabled.
- * - **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 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
+ *   source — `cart.payment_gateways` is always undefined). One enabled gateway
+ *   is selected from the first render that has store info. The selection is
+ *   derived from the current list, not remembered: a gateway the admin disables
+ *   drops out, and if that leaves one, it takes over.
+ * - **The gate.** `canPlaceOrder` + `blockers` say what still stands between the
+ *   customer and the order — drive the button's disabled state and the
+ *   what's-missing lines from them instead of re-deriving.
+ * - **placeOrder.** Sends the order, clears the shared cart, and navigates: an
+ *   online gateway redirects to the provider (`redirectToPayment`), everything
+ *   else lands on `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 `{ ok: true,
+ *   result }` or `{ ok: false, error }`. Pass `orderReceivedPath: null` to
+ *   handle the result yourself (a manual result carries
  *   `result.payment_instructions`).
  *
- *   Both navigations are **full page loads** (`window.location.assign`), not
- *   router transitions: the provider hop has to leave the app, and the
- *   order-received page is built to boot from the URL alone (`order_id` +
- *   `order_key`), so a reload there is correct and shareable. Consequences
- *   worth knowing: React state does not survive it, and a browser script
- *   driving checkout loses its page context at this point — the order is
- *   still placed, so verify by navigating fresh to
- *   `orderReceivedUrl(result)`. For a client-side transition instead, pass
- *   `orderReceivedPath: null` and `navigate(orderReceivedUrl(result))`
- *   yourself.
+ *   Both navigations are **full page loads** (`window.location.assign`): the
+ *   provider hop leaves the app, and the receipt boots from the URL alone
+ *   (`order_id` + `order_key`), so a reload there is correct and shareable.
+ *   React state does not survive it, and a browser script driving checkout
+ *   loses its page context here — the order *is* placed, so verify by
+ *   navigating fresh to `orderReceivedUrl(result)`. For a client-side
+ *   transition, pass `orderReceivedPath: null` and navigate yourself.
  *
  * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
  * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
@@ -93,7 +87,14 @@ function resolvePaymentMethod(gateways, picked) {
  * accepted; the navigation away is already in flight). **Guard on it before the
  * cart's empty branch** — `placeOrder` clears the cart, so a page that checks
  * only `cart.status` repaints "your bag is empty" over a just-placed order for
- * the frames before the browser leaves. `usePlaceOrder` packages this gate.
+ * the frames before the browser leaves.
+ *
+ * The button is `disabled={!canPlaceOrder || placing}`, and `placeOrder` works
+ * as an `onClick` handler directly (a click event is not read as order fields).
+ * A disabled button must still say why: render one line per `blockers` code, in
+ * the store's own words — the silent disabled button is the most common
+ * checkout dead end. The codes are listed above; each maps to one thing the
+ * customer can fix.
  *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
  * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
@@ -214,6 +215,12 @@ export function useCheckout(options = {}) {
   const placeOrder = useCallback(
     async (extra = {}) => {
       if (placing) return { ok: false, error: { code: "placing", message: "Order already being placed." } };
+      // Safe as `onClick={checkout.placeOrder}`: a DOM/React event is not
+      // `extra`. Spreading one into the order payload would send a circular
+      // SyntheticEvent as order fields — an explicit object still forwards.
+      const isEvent =
+        extra && typeof extra === "object" && ("nativeEvent" in extra || "target" in extra);
+      const fields = isEvent ? {} : extra;
       setPlacing(true);
       setOrderError(null);
       try {
@@ -221,7 +228,7 @@ export function useCheckout(options = {}) {
           payment_method: paymentMethod,
           billing,
           ...(shipToDifferent ? { shipping } : {}),
-          ...extra, // customer_note, success_url/cancel_url overrides, …
+          ...fields, // customer_note, success_url/cancel_url overrides, …
         });
         // `submitted` flips BEFORE the cart clears, in the same commit — the
         // page's `stage === "submitted"` guard is what stands between a placed

package/src/commerce/storefront/useOrderReturn.js

@@ -1,7 +1,6 @@
 import { useCallback, useEffect, useState } from "react";
 import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useFormatMoney, useStorefrontState } from "./StorefrontProvider";
-import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
  * useOrderReturn — the whole `/order-received` page in one hook. Mount the
@@ -19,11 +18,12 @@ import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
  *   // "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 —
- * `attributesLabel`, `image` as `{src, alt}|null`, `totalLabel` pre-formatted —
- * 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).
+ * `lines` are the order's items normalized for rendering — `attributesLabel`,
+ * `image` as `{src, alt}|null`, `totalLabel` pre-formatted — because a receipt
+ * reusing cart-row markup otherwise reads `item.image` as an object and paints
+ * a broken image. Totals: `orderTotalsLines(order, { formatMoney })` from
+ * `@/commerce/utils`. 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.
@@ -61,7 +61,17 @@ export function useOrderReturn({ auto = true, seo = true } = {}) {
     if (auto) reload();
   }, [auto, reload]);
 
-  useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
+  // A receipt's URL carries an order key, so the page must not rank. One meta
+  // tag, added on mount and removed on unmount; the rest of this page's head —
+  // title, description — is yours to set. `seo: false` opts out entirely.
+  useEffect(() => {
+    if (!seo || typeof document === "undefined") return undefined;
+    const tag = document.createElement("meta");
+    tag.setAttribute("name", "robots");
+    tag.setAttribute("content", "noindex, nofollow");
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  }, [seo]);
 
   return { ...result, lines: orderLines(result.order ?? null, { formatMoney }), reload };
 }