@base44/app-plugin-commerce 0.2.1 → 0.2.3

package/skills/commerce/install/01-install.md

@@ -21,7 +21,7 @@ What lands in the app, how the admin gets mounted, and the order to do the rest
 | `base44/entities/commerce.*.jsonc` | 20 entity schemas, all admin-only RLS |
 | `base44/functions/commerce/` + `shared/` + `agents/` | 16 functions, the engine, the StoreAdmin copilot |
 | `src/commerce/admin/` | the finished admin app — **don't validate it, it ships tested** |
-| `src/commerce/storefront/` + `utils/` | the hooks and blocks you build against ([`./02-storefront.md`](./02-storefront.md)) |
+| `src/commerce/storefront/` + `utils/` | the headless hooks you build the storefront UI on ([`./02-storefront.md`](./02-storefront.md)) |
 | `.agents/skills/commerce/` | these docs |
 
 <details>
@@ -61,7 +61,7 @@ import { Navigate } from "react-router-dom";
 
 - **The `/*` splat is required.** The admin renders nested routes; a bare `path="/store-admin"` matches only the dashboard and every deeper link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` — the prefix *without* the splat.
 - **Give `/` something.** A blank Base44 app has no `/` route, so after mounting only the admin the app's own URL renders "page not found", which reads exactly like a broken install. Redirect until the storefront exists.
-- **`/order-received` is mandatory**, even for a store that only ever takes offline payments. Every payment link (checkout, the admin's payment link, emails) returns there, and confirming is what marks an order paid — without the route a paying customer hits a 404 and the order stays unpaid. The page body is one block, `<OrderReceivedBlock />` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General → *Payment return path*.
+- **`/order-received` is mandatory**, even for a store that only ever takes offline payments. Every payment link (checkout, the admin's payment link, emails) returns there, and confirming is what marks an order paid — without the route a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()`, plus your markup for its states ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General → *Payment return path*.
 
 ## Admin-role enforcement — do not weaken
 

package/skills/commerce/install/02-storefront.md

@@ -5,19 +5,57 @@ skip_when: "The storefront pages already render against live data and pass the c
 forget_when: "The checklist at the bottom passes — every page renders against the seeded catalog and an offline order completes."
 carry_forward:
   - "Payment gateways, currency and countries come from useStoreInfo() only — never off a cart (cart.payment_gateways is always undefined)."
-  - "A store with any coupons must have a coupon field. <CartLinesBlock/> and <CheckoutBlock/> both ship one by default (showCoupon) — keep it unless the store has no codes."
-  - "/order-received renders <OrderReceivedBlock/>, which shows paymentInstructions — how a normal (offline) customer learns how to pay."
+  - "A store with any coupons must have a coupon field (useCoupon) in the cart or the checkout, or its codes can never be redeemed."
+  - "/order-received is mandatory and renders useOrderReturn's states, including paymentInstructions — how a normal (offline) customer learns how to pay."
   - "Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
+  - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
+  - "Every hook on a page goes above its status guards — a hook after an early return crashes with \"Rendered more hooks than during the previous render\"."
 ---
 
 # 02 — Storefront
 
-Two tiers, and the split decides how much you write.
-
-- **Identity tier — yours, always.** Home, the collection grid, **the product card**, the product page's layout, typography, motion, theme. Where "make it look like X" lives; no markup ships for it.
-- **Commodity tier — ships as blocks.** Checkout, cart lines, totals, coupon field, reviews, order-received, and the product page's internals (variant selector, gallery, specs, breadcrumbs, strips). Every store's version is functionally identical: **restyle or replace them, never hand-roll their logic.**
-
-Blocks are thin compositions of the same package's hooks, styled by inheritance — semantic markup, your theme tokens, a `data-commerce="…"` attribute on every element. Each takes `className`, most take `slots` or a render prop, so outgrowing one means rewriting *one region* against hooks you already know. Everything imports from `@/commerce/storefront`.
+One split decides everything here: **the logic is premade, the UI never is.**
+
+- **Logic — hooks, shipped.** Checkout repricing from the address, variant
+  resolution, cart state, coupon redemption, review policies, order-return
+  verification. Every store's version of these is functionally identical, and
+  hand-writing them is where storefront bugs cluster: **never re-implement what
+  a hook does.**
+- **UI — yours, always.** Every element, class, layout and word of copy on
+  every page. Nothing in `@/commerce/storefront` renders markup or carries CSS,
+  so there is no component to drop in and nothing to restyle — the design is
+  the part of the storefront only you can do, and it should be designed, not
+  assembled.
+
+## Before you begin
+
+**Decide how the store looks as if this kit did not exist** — identity, type,
+palette, spacing, the shape of a card, how a checkout is laid out — from the
+brief and your own judgement. Then use this file for **how to wire it**:
+everything below is implementation reference and **none of it is design input**.
+The bare tags, flat structure and placeholder copy show where the data goes in
+the fewest characters; they are not a look to adopt, keep or tweak. The finished
+store should look like what you would have built with no kit at all — the kit's
+only job is to make it cost far less code.
+
+Each hook returns a complete view-model — a `status` to branch on,
+ready-to-map arrays, handlers, error objects — and its **doc comment (JSDoc) is
+the API reference**: open the hook's file when you need exact shapes; don't
+guess fields. This file gives you the routing, each surface's hook, and the
+render rules that keep a store correct (marked ⚑ — these must survive whatever
+design you build).
+
+Where you get a **reference implementation** and where you get only the hook is
+deliberate: **cart, checkout and order-received** have reference code below —
+their wiring is dense enough that reading it is cheaper than deriving it, and
+they are conventions (a form, a receipt) where familiarity beats invention.
+The **identity surfaces** — home, collection, the card, the product page's
+layout — get hooks only, on purpose: reference markup there would make every
+store look the same, and their design is the work only you can do. Either way
+the hooks are high-level enough that a page is a handful of calls plus your
+markup — writing more code than the budgets at the bottom allow means you are
+re-deriving logic a hook already owns. Everything imports from
+`@/commerce/storefront`.
 
 ## Setup — once
 
@@ -39,9 +77,16 @@ import { base44 } from "@/api/base44Client";
 </BrowserRouter>
 ```
 
-The provider owns the shared client, the store-info cache and **one** shared cart, so a header badge, a drawer and the checkout render the same state. Never mount a second provider, and never touch the `cart_token` — the provider owns its whole lifecycle.
+The provider owns the shared client, the store-info cache and **one** shared
+cart, so a header badge, a drawer and the checkout render the same state. Never
+mount a second provider, and never touch the `cart_token` — the provider owns
+its whole lifecycle.
 
-> ⚠ **`<Routes>` accepts only `<Route>` children.** Nesting the provider inside it — the natural reading of "wrap the storefront routes" — throws at render: `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`. To scope the provider to storefront routes only, use a pathless **layout route**, the one place a wrapper is legal:
+> ⚠ **`<Routes>` accepts only `<Route>` children.** Nesting the provider inside
+> it — the natural reading of "wrap the storefront routes" — throws at render:
+> `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`.
+> To scope the provider to storefront routes only, use a pathless **layout
+> route**, the one place a wrapper is legal:
 > ```jsx
 > <Route element={<StorefrontProvider base44={base44}><Outlet /></StorefrontProvider>}>
 >   <Route path="/" element={<Home />} />
@@ -50,124 +95,361 @@ The provider owns the shared client, the store-info cache and **one** shared car
 > <Route path="/store-admin/*" element={<AdminApp />} />   {/* outside the provider */}
 > ```
 
-## Product list / collection — identity tier
+## Product list / collection
+
+`useProductList(params)` → `{ status, products, hasNext, next, refreshing,
+setParams, reload }`. ⚑ `status` is `"loading" | "ready" | "empty" | "error"`
+— branch on it, so a failed request renders as a failure instead of an empty
+grid. `setParams({ category_id, search, on_sale, min_price, in_stock_only })`
+resets to page 1 and keeps the current rows on screen (`refreshing`) while the
+page loads. `useCategories()` / `useRibbons()` → `{ items }` (arrays, children
+nested).
+
+Your card renders `name`, `images[0]?.src` (⚑ **images are `{src,name,alt}`
+objects and the array may be empty — render a placeholder, never a broken
+`<img>`**), `useProductPrice(row).label` (already "From €19.99" when the
+product sells variants — there is no product `type` flag), `on_sale`,
+`short_description`, `stock_status`, `average_rating`/`rating_count`,
+`ribbons`. Full field matrix:
+[`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+
+**Rails** (featured row, "new in") are the same hook with a filter
+(`{ featured: true, per_page: 4 }`). ⚑ Any filter may legitimately match
+nothing — render *nothing* then, never a heading over an empty row. Upsells
+beside a product need no query: `p.upsells` / `p.crossSells` from `useProduct`.
+
+## Product page
+
+`useProduct(slug)` (or `{ id }`) owns fetch + variant selection + quantity +
+price, race-safe, selection mirrored to the URL. ⚑ `status: "not_found"` is a
+404 page, not a spinner.
+
+⚑ **Call every hook above the status guards.** This page needs more than one,
+and a hook placed after an early `return` runs on some renders but not others —
+React then throws *"Rendered more hooks than during the previous render"* the
+moment the product resolves. All of these tolerate a null/loading product
+precisely so they can sit at the top:
 
 ```jsx
-const list = useProductList({ per_page: 12, sort: "-created_date" });
-const { items: categories } = useCategories();          // ARRAY, children nested
-
-if (list.status === "error") return <ErrorState onRetry={list.reload} />;
-if (list.status === "empty") return <EmptyState />;
-
-{list.products.map((p) => <MyCard key={p.id} product={p} />)}   {/* your card */}
-{list.hasNext && <button onClick={list.next}>Next</button>}
-// list.setParams({ category_id, search, on_sale: true, min_price, in_stock_only })
-//   → resets to page 1, keeps the current rows on screen (list.refreshing) while the page loads
-```
-
-`status` is `"loading" | "ready" | "empty" | "error"` — branch on it, so a failed request renders as a failure instead of an empty grid. `useRibbons()` has the same shape as `useCategories()`.
-
-A card uses `name`, `images[0]?.src` (**images are `{src,name,alt}` objects and the array may be empty — render a placeholder, never a broken `<img>`**), `useProductPrice(row).label` (already "From €19.99" when the product sells variants — there is no product `type` flag), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `ribbons`. Full field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+const p = useProduct(slug);
+const g = useProductGallery(p.product, p.view);
+const buy = useAddToCartButton(p, { onAdded: () => navigate("/bag") });
+useStorefrontSeo(productSeo(p.product, p.view, { storeName, currency }));
 
-**Rails** (featured row, "new in", upsells) are one block, and `renderCard` is required because the card is identity tier:
-
-```jsx
-<ProductStripBlock params={{ featured: true, per_page: 4 }} title="Featured"
-                   renderCard={(p) => <MyCard key={p.id} product={p} />} />
-// or products={p.upsells} (from useProduct) for rows you already have. A filter may match nothing —
-// the block renders nothing at all rather than a heading over an empty row.
-```
-
-## Product page — custom layout, blocks inside
-
-```jsx
-const p = useProduct(slug);                          // slug from the route; { id } also works
-if (p.status === "loading")   return <Skeleton />;
-if (p.status === "not_found") return <NotFound />;   // a 404 is a status, not a spinner
+if (p.status === "loading")   return /* your loading state */;
+if (p.status === "not_found") return /* your 404 */;
 const { product, view, price, categories } = p;
-
-<BreadcrumbsBlock categories={categories} current={product.name} />
-<ProductGalleryBlock product={product} view={view} imageClassName="aspect-[3/4] object-cover" />
-<h1>{product.name}</h1>
-<p>{price.label}{price.compareAtLabel && <s>{price.compareAtLabel}</s>}</p>
-<VariantSelectorBlock view={view} onPick={p.pick} />       {/* one control per axis */}
-<AddToCartBlock product={p} onAdded={() => navigate("/bag")} />   {/* pass the whole hook result */}
-<div dangerouslySetInnerHTML={{ __html: product.description }} />  {/* HTML — render as rich text */}
-<ProductSpecsBlock product={product} />                    {/* product.meta_data → spec table */}
-<ReviewsBlock product={product} />
 ```
 
-`view` is the resolved selection: `view.axes` (one control each), `view.availability` (unbuyable options render *disabled*, not hidden — the block does this), `view.purchasable`, `view.addToCart` (`{product_id, variation_id}` — a product with attributes is rejected without it). `p.price` is the *current* selection's price, a range until it resolves; the selection is mirrored to the URL, so a variant is linkable. Custom buy box: `p.pick`, `p.quantity`/`p.incQuantity`/`p.maxQuantity`, and `useAddToCart()` whose `add()` never throws and resolves `{ ok, error: { code, message, shouldReload } }`.
-
-**Reviews** are the one line above. The custom path is `useProductReviews(product, { policy, user })` — list, paging, aggregate rating, and the submit form with field-level errors; `policy` is `"open" | "login" | "verified_buyers"`, and the confirmation copy comes from the server's response, so it is right whether or not the store auto-approves.
-
-## Cart / bag — commodity tier
-
-A cart *page* is optional: a store selling one made-to-order piece reads better as buy-now straight to checkout. When you build one:
+(`variantAxes` and `productSpecs` are plain functions, not hooks — they can go
+anywhere.) Build your layout from:
+
+- **Price** — `price.label`, plus `price.compareAtLabel` (struck through) when
+  on sale. Never read `product.price` directly — the parent's price is a
+  rolled-up from-price.
+- **Gallery** — `g` from above → `{ hasImages, images, active, activeIndex,
+  setActiveIndex, next, prev }`. The active image already follows the variant
+  selection; `hasImages: false` means render your placeholder.
+- **Variant selector** — `variantAxes(view, p.pick)` → one entry per axis:
+  `{ key, name, selectedOption, options: [{ value, selected, disabled,
+  outOfStock, pick }] }`. Map it to any control — buttons, swatches, a dropdown.
+  ⚑ **One control per axis, never a list of variations** (`Red / S`, `Red / M`,
+  … is n × m noise), and ⚑ **an unbuyable option renders `disabled`, never
+  hidden** (`outOfStock` stays visible, just marked) — a customer who can't see
+  that a size exists assumes the store doesn't carry it. `view.missingAxes`
+  names what's still unpicked. The shape of the map (the one interaction agents
+  reliably get wrong — the control itself is yours):
+
+  ```jsx
+  {variantAxes(view, p.pick).map((axis) => (
+    <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
+      {axis.options.map((o) => (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
+          {o.value}{/* o.outOfStock → mark visibly, keep clickable-looking off */}
+        </button>
+      ))}
+    </fieldset>
+  ))}
+  ```
+- **Buy box** — `buy` from above → `{ add, adding, error, disabled, soldOut,
+  needsSelection, quantity, increase, decrease, canIncrease, canDecrease,
+  showQuantity }`. It gates on purchasability, recovers from every add failure
+  and clamps quantity to stock and `sold_individually`. ⚑ Render `error.message`
+  inline; ⚑ `showQuantity: false` means no stepper (only 1 can be bought); the
+  button label should reflect `adding`/`soldOut`/`needsSelection` — the words
+  are yours.
+- **Description** — `product.description` is HTML; render as rich text
+  (`dangerouslySetInnerHTML`), `short_description` above it.
+- **Specs** — `productSpecs(product)` → `[{ key, label, value }]` from
+  `meta_data` (Material, Care). `[]` means no section at all.
+- **Breadcrumbs** — build from `categories`
+  (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons are
+  labels, not breadcrumbs.
+
+All optional — include what this store's products actually have.
+
+### Reviews — optional
+
+**Build reviews only if the store wants them** — because the brief asks, or the
+products are the kind customers rate. No review UI means no reviews, and that
+is a complete outcome. (If you skip them, don't put star ratings on cards
+either — an average of nothing is `0`.)
+
+`useProductReviews(product, { policy, user })` is the whole surface: `items`,
+paging (`hasNext`/`loadMore`), `averageRating`/`ratingCount`, and the submit
+form — `form`/`setField`/`fieldErrors` (matching the server's error codes),
+`valid`, `submit`, `requiresEmail` (false for a signed-in visitor),
+`reviewBlockedReason` (`"login_required"` / `"not_a_buyer"` under the stricter
+policies). ⚑ The confirmation copy is `message`, **taken from the server's
+response** — a store with auto-approval on says "published", not "awaiting
+approval", so render `message`, never your own text. `policy` is
+`"open" | "login" | "verified_buyers"`. Details beyond this:
+[`../references/reviews.md`](../references/reviews.md).
+
+## Cart / bag
+
+A cart *page* is optional: a store selling one made-to-order piece reads better
+as buy-now straight to checkout. The surface is four hooks: `useCart()`
+(`status`, `lines`, `notices`), `CartLine` (headless render-prop binding
+`useCartLine` per row — quantity stepping that clamps, coalesces and recovers),
+`useTotalsLines()`, `useCoupon()`.
+
+⚑ Rules: branch on `status`, never on emptiness while loading. Render
+`notices` — they say what auto-dropped from the cart and why. Render every
+non-`hidden` totals line rather than hardcoding subtotal/total — a hand-written
+summary omits discount and tax, then stops adding up the day a coupon or a tax
+rate exists. **A store with any coupons must have a coupon field** (here or in
+the checkout): coupons are admin-only data, redeemable only through a field the
+customer types into — if no field exists anywhere, don't seed coupons and don't
+write "use WELCOME10" in the copy.
+
+**Reference implementation** — read once for the wiring, then write your own
+page: the structure below is correct, the presentation is deliberately absent.
+Restyle, rearrange, split into your own components; the ⚑ rules are the part
+that must survive.
 
 ```jsx
-const { status } = useCart();
-if (status === "loading") return <Skeleton />;      // never branch on isEmpty while loading
-if (status === "empty")   return <EmptyBag />;
-
-<CartLinesBlock />        {/* lines, variant labels, steppers, and the notices saying what auto-dropped */}
-{/* <CartLinesBlock/> already renders the coupon field (showCoupon, default on) */}
-<TotalsBlock />           {/* subtotal · discount · shipping · tax · total, zero rows hidden */}
-<Link to="/checkout">Checkout</Link>
+function Bag() {
+  const { status, lines, notices } = useCart();
+  const totals = useTotalsLines();
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* your loading state */;
+  if (status === "empty")   return /* your empty-bag state, linking back to the catalog */;
+  return (
+    <>
+      {notices.map((n, i) => <p key={i} role="status">{n.message}</p>)}
+      {lines.map((line) => (
+        <CartLine key={line.item_key} line={line}>
+          {(l) => (   /* line: name, attributesLabel, image, total — l: the controls */
+            <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>
+              {formatMoney(line.total)}
+              {l.error && <p role="alert">{l.error.message}</p>}
+            </li>
+          )}
+        </CartLine>
+      ))}
+      <CouponField />   {/* useCoupon: code/setCode, apply, applying, error, applied[] + remove */}
+      {totals.filter((l) => !l.hidden).map((l) => (
+        <div key={l.key}>{l.label} {l.formatted}</div>   /* l.emphasis → the total row */
+      ))}
+      <Link to="/checkout">Checkout</Link>
+    </>
+  );
+}
 ```
 
-**A store with any coupons must have a coupon field, or its codes can never be redeemed.** Coupons are admin-only data — a storefront cannot list codes, so the only way in is a field the customer types into. Both `<CartLinesBlock/>` and `<CheckoutBlock/>` render one by default (`showCoupon`), so the safe outcome is the one you get for free; pass `showCoupon={false}` only for a store with no codes. Standalone, the field is `<CouponFieldBlock/>`. If no field exists anywhere, don't seed coupons and don't write "use WELCOME10" in the copy.
+No shipping estimator here — checkout reprices shipping and tax from the
+address.
+
+## Checkout
+
+The state machine is `useCheckout`, shared across the page's regions by
+`CheckoutProvider` + `useCheckoutContext()`. It reprices shipping/tax from the
+address automatically (debounced, never on a half-typed address), derives the
+shipping and payment choices, gates the button (`canPlaceOrder` +
+`useCheckoutBlockers()` in words), and `placeOrder()` handles **both**
+navigations — online gateway → provider redirect, everything else →
+`/order-received`. The address form comes from `useAddressForm(which)` as a
+field spec (`state` collected, country options never null); the two
+store-data choices come through the headless `ShippingMethodPicker` /
+`PaymentMethodPicker`, whose render props enumerate every branch.
+
+⚑ Rules: handle every picker branch (they exist because every one occurs in a
+normal store); a single shipping or payment option still *shows* what it is —
+never a picker of one, never "nothing selected"; zero gateways → say checkout
+is unavailable instead of a dead button; keep each field's `autoComplete` (the
+spec provides it) and render `f.error` — "we don't ship there" arrives on the
+country field; show `orderError.message` and the blockers so the gate explains
+itself. ⚑ Payment methods, currency and countries come from `useStoreInfo()`
+only — `cart.payment_gateways` is always `undefined`, and a default store
+offers `offline` only ([`./03-data.md`](./03-data.md)).
+
+**Reference implementation** — the densest wiring in the storefront; read it,
+then build yours around it. Structure correct, presentation absent.
 
-No shipping estimator here — `useCheckout` reprices shipping and tax from the address. Custom rows: `useCartLine(line)` (optimistic, clamped, coalesced) and `useCoupon()`.
+```jsx
+function Checkout() {   // hooks read the context BELOW the provider
+  return <CheckoutProvider><CheckoutForm /></CheckoutProvider>;
+}
 
-## Checkout — one block
+function CheckoutForm() {
+  const { status } = useCart();
+  const checkout = useCheckoutContext();
+  const blockers = useCheckoutBlockers();
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* loading */;
+  if (status === "empty")   return /* "your bag is empty" — a checkout with nothing says so */;
+  return (
+    <>
+      <AddressFields which="billing" />
+      <label>
+        <input type="checkbox" checked={checkout.shipToDifferent}
+               onChange={(e) => checkout.setShipToDifferent(e.target.checked)} />
+        Deliver to a different address
+      </label>
+      {checkout.shipToDifferent && <AddressFields which="shipping" />}
+
+      <ShippingMethodPicker>
+        {({ status, methods, chosen, choose, mustChoose, syncing }) => (
+          <fieldset>{/* syncing → subtle busy state; renders null for a virtual cart */}
+            {status === "missing_address" && <p>Delivery options appear once your address is entered.</p>}
+            {status === "none_available"  && <p role="alert">We don't deliver to that address yet.</p>}
+            {mustChoose && methods.map((m) => (
+              <label key={m.id}>
+                <input type="radio" checked={chosen?.id === m.id} onChange={() => choose(m.id)} />
+                {m.title} {formatMoney(m.cost)}
+              </label>
+            ))}
+            {!mustChoose && chosen && <p>{chosen.title} {formatMoney(chosen.cost)}</p>}
+          </fieldset>
+        )}
+      </ShippingMethodPicker>
+
+      <PaymentMethodPicker>
+        {({ gateways, value, select, selected, single }) => (
+          <fieldset>
+            {gateways.length === 0 && <p role="alert">No payment method is available right now.</p>}
+            {!single && gateways.map((g) => (
+              <label key={g.slug}>
+                <input type="radio" checked={value === g.slug} onChange={() => select(g.slug)} />
+                {g.title} {g.description}
+              </label>
+            ))}
+            {single && selected && <p>{selected.title}</p>}
+          </fieldset>
+        )}
+      </PaymentMethodPicker>
+
+      {/* summary: coupon field (if not in the cart) + useTotalsLines(), as in the cart page */}
+
+      <button disabled={!checkout.canPlaceOrder || checkout.placing} onClick={() => checkout.placeOrder()}>
+        {checkout.placing ? "Placing your order…" : "Place order"}
+      </button>
+      {checkout.orderError && <p role="alert">{checkout.orderError.message}</p>}
+      {!checkout.canPlaceOrder && blockers.map((b) => <p key={b.code}>{b.message}</p>)}
+    </>
+  );
+}
 
-```jsx
-export default function Checkout() {
-  return <main className="mx-auto max-w-3xl px-6 py-16">
-    <h1 className="font-heading text-5xl">Checkout</h1>
-    <CheckoutBlock />
-  </main>;
+function AddressFields({ which }) {
+  const { fields, countriesLoading } = useAddressForm(which);
+  return fields.map((f) => (        /* each field carries its own setter: f.set */
+    <label key={f.key}>
+      {f.label}{f.required && " *"}
+      {f.type === "select" ? (
+        <select value={f.value} onChange={(e) => f.set(e.target.value)} autoComplete={f.autoComplete}>
+          <option value="">{f.key === "country" && countriesLoading ? "Loading…" : `Select ${f.label}`}</option>
+          {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
+        </select>
+      ) : (
+        <input type={f.type} value={f.value} required={f.required}
+               onChange={(e) => f.set(e.target.value)} autoComplete={f.autoComplete} />
+      )}
+      {f.error && <span role="alert">{f.error}</span>}
+    </label>
+  ));
 }
 ```
 
-That is the whole page: address → delivery → payment → coupon → summary → place order, with its own `<CheckoutProvider>`. Correct with zero props in a default-seeded store, and every branch a checkout must handle is wired: shipping repricing from the address, a single option reading as selected, a store with no enabled gateway saying so instead of rendering a dead button, the place-order gate explaining itself, the redirect for an online gateway. Restyle with `className`, replace a region with `slots={{ summary: <MySummary/> }}`, or set `onPlaced`/`orderReceivedPath`.
+## Order received
 
-Escalate only for different *structure*, and then to the hooks the block itself uses: `useCheckout` / `CheckoutProvider` / `useCheckoutContext`, `useAddressForm("billing")` (fields including `state`, country options never null), `<ShippingMethodPicker>` / `<PaymentMethodPicker>` (headless render props over the two choices that are store data), `useTotalsLines()`, `useCheckoutBlockers()`.
+**Mandatory route** — every payment link returns here, and confirming is what
+marks a card order paid. `useOrderReturn()` is the whole page's logic: it reads
+`order_id`/`order_key` from the URL, verifies with the provider (idempotent),
+and marks the page noindex itself.
 
-**Payment methods, currency and countries come from `useStoreInfo()` only** — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only ([`./03-data.md`](./03-data.md)).
+⚑ Rules: render all five states — never a blank page while `"loading"`, and a
+retry via `reload()` on `"error"`. ⚑ **Never drop `paymentInstructions`**: a
+manual/offline order settles outside the store, so these ARE how the store's
+default customer learns how to pay — render them whenever present, on any
+state. ⚑ An order's totals are **flat** — `order.total`; there is no
+`order.totals` (use `useTotalsLines(order)`).
 
-## Order received
+**Reference implementation** — a receipt is a convention, not an identity
+surface: take this structure, restyle it to the store, keep every branch.
 
 ```jsx
-<main className="mx-auto max-w-2xl px-6 py-20"><OrderReceivedBlock /></main>
+function OrderReceived() {
+  const { status, order, lines, paymentLink, paymentInstructions, error, reload } = useOrderReturn();
+  const totals = useTotalsLines(order);
+  const formatMoney = useFormatMoney();
+  if (status === "loading") return /* confirming copy */;
+  if (status === "error")   return <><p role="alert">{error.message}</p>
+                                     <button onClick={() => reload()}>Try again</button></>;
+  return (
+    <>
+      {status === "paid"      && /* thank-you heading */}
+      {status === "unpaid"    && <>{/* awaiting-payment heading */}
+                                   {paymentLink?.url && <a href={paymentLink.url}>Pay now</a>}</>}
+      {status === "cancelled" && <>{/* payment-cancelled heading */}
+                                   {paymentLink?.url && <a href={paymentLink.url}>Try payment again</a>}</>}
+      {order?.order_number && <p>Order {order.order_number}</p>}
+      {paymentInstructions && (
+        <section>{/* "How to pay" — the offline customer's next step */}
+          {paymentInstructions.description && <p>{paymentInstructions.description}</p>}
+          {paymentInstructions.account_details && Object.entries(paymentInstructions.account_details)
+            .map(([k, v]) => <p key={k}>{k.replace(/_/g, " ")}: {String(v)}</p>)}
+        </section>
+      )}
+      {lines.map((l, i) => <p key={i}>{l.name} {l.attributesLabel} × {l.quantity} — {formatMoney(l.total)}</p>)}
+      {totals.filter((t) => !t.hidden).map((t) => <p key={t.key}>{t.label} {t.formatted}</p>)}
+    </>
+  );
+}
 ```
 
-Mandatory route. It renders all five states, including the two hand-written pages drop: **`paymentInstructions` for a manual/offline order** — the default gateway, so this is how the store's normal customer learns how to pay — and the pay-now link for an unpaid card order. It is `noindex`, as a receipt carrying an order key should be. Custom version: `useOrderReturn()` + `useTotalsLines(order)` (an order's totals are **flat** — `order.total`; there is no `order.totals`).
-
 ## SEO — one line per page type
 
 ```jsx
 useStorefrontSeo(productSeo(p.product, p.view, { storeName, currency }));  // product page
 useStorefrontSeo(collectionSeo({ title, products: list.products }));      // collection / home
-useStorefrontSeo(orderSeo(order));            // order-received & checkout → noindex
+// order-received is already noindex via useOrderReturn
 ```
 
-It is a hook — call it above the page's early returns (the builders tolerate a null product).
+The `*Seo` builders tolerate a null product, so this sits with the other hooks
+above the status guards.
 
 ## Per-page output budgets
 
 | Page | budget (chars) | rationale |
 |---|---|---|
-| Checkout | ≤ 2K | `<CheckoutBlock/>` + theme overrides; hand-rolling any step means a block escape hatch was missed |
-| Cart / bag | ≤ 2K | `<CartLinesBlock/>` + `<TotalsBlock/>` + empty state |
-| Order-received | ≤ 1.5K | `<OrderReceivedBlock/>` + brand framing |
-| Product page | ≤ 4K | custom layout around `useProduct` + the five blocks above |
+| Checkout | ≤ 5K | your markup over the reference above — the logic is all hook calls |
+| Cart / bag | ≤ 3K | `useCart` + `CartLine` rows + totals + coupon + empty state |
+| Order-received | ≤ 2.5K | five states + payment instructions + summary |
+| Product page | ≤ 5K | your layout and type around `useProduct`, `variantAxes`, `useAddToCartButton`, the gallery |
 | Collection | ≤ 3K | `useProductList` + custom card + pagination controls |
-| Home | ≤ 5K | pure identity tier — hero/editorial earn their chars |
+| Home | ≤ 5K | pure identity — hero/editorial earn their chars |
 | Any single component file | ≤ 4K, hard ceiling 8K | Base1 evidence: decode is 34% of wall; a 12K file is a 45s write batch |
 
-Over budget ⇒ extract components, or adopt the block you are re-implementing. **A page re-implementing something a block ships — an address step, a quantity stepper, a totals row, a variant control — has missed an escape hatch: take the block and restyle it.**
+These budgets assume the hooks carry the logic and your markup carries only the
+design. Over budget ⇒ you are re-implementing something a hook does — an
+address spec, a quantity clamp, totals math, variant resolution, add-to-cart
+error recovery. Go back to the hook and delete your version.
 
 ## Done — forget this file
 
@@ -175,14 +457,19 @@ Over budget ⇒ extract components, or adopt the block you are re-implementing.
 - [ ] **One** `<StorefrontProvider>` above every storefront route, wrapping `<Routes>` (or a layout route's `<Outlet/>`); one client, no hand-rolled `cart_token`.
 - [ ] Pages branch on `status`; no page maps a possibly-null list or shows an empty state while loading.
 - [ ] Gateways/currency/countries read from `useStoreInfo()` only.
-- [ ] If the store has coupons, a coupon field exists in the cart or the checkout.
-- [ ] `/order-received` renders `<OrderReceivedBlock/>` (payment instructions included).
+- [ ] If the store has coupons, a coupon field (`useCoupon`) exists in the cart or the checkout.
+- [ ] `/order-received` renders `useOrderReturn`'s states **including `paymentInstructions`**.
+- [ ] Variant options render one control per axis; unbuyable options are disabled, not hidden.
+- [ ] No hook logic was re-implemented by hand (address fields, quantity clamps, totals rows, shipping/payment branching).
+- [ ] The storefront carries the design you settled on before reading this file — no page ships the reference snippets' bare structure or placeholder copy.
 - [ ] Every page is within its budget above.
 - [ ] A real purchase completes in the preview — pick a variant, add it, check out, place an offline order, land on `/order-received`.
 
 Record these lines in your working notes; do not re-read this file.
 
 - Payment gateways, currency and countries come from `useStoreInfo()` only — never off a cart (`cart.payment_gateways` is always undefined).
-- A store with any coupons must have a coupon field. `<CartLinesBlock/>` and `<CheckoutBlock/>` both ship one by default (`showCoupon`) — keep it unless the store has no codes.
-- `/order-received` renders `<OrderReceivedBlock/>`, which shows `paymentInstructions` — how a normal (offline) customer learns how to pay.
+- A store with any coupons must have a coupon field (`useCoupon`) in the cart or the checkout, or its codes can never be redeemed.
+- `/order-received` is mandatory and renders `useOrderReturn`'s states, including `paymentInstructions` — how a normal (offline) customer learns how to pay.
 - Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design.
+- Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations.
+- Every hook on a page goes above its status guards — a hook after an early return crashes with "Rendered more hooks than during the previous render".