@base44/app-plugin-commerce 0.2.1 → 0.2.2

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

@@ -5,19 +5,45 @@ 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."
 ---
 
 # 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,
+  and this file deliberately doesn't hand you page bodies either — the design
+  is the part of the storefront only you can do, and it should be designed,
+  not assembled.
+
+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 +65,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 +83,343 @@ 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
-
-```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).
-
-**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
+## 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. Destructure `{ product, view, price, categories }`
+and 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** — `useProductGallery(product, view)` → `{ 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** — `useAddToCartButton(p, { onAdded })` → `{ 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 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
-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} />
+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>
+    </>
+  );
+}
 ```
 
-`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:
+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.
 
 ```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>
-```
-
-**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 — `useCheckout` reprices shipping and tax from the address. Custom rows: `useCartLine(line)` (optimistic, clamped, coalesced) and `useCoupon()`.
+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, set, countriesLoading } = useAddressForm(which);
+  return 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)} 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) => set(f.key, 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).
+It is a hook — call it above the page's early returns (the builders tolerate a
+null product).
 
 ## 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 +427,18 @@ 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 looks designed — the reference implementations above were adapted into this store's design, not shipped bare.
 - [ ] 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.

package/skills/commerce/install/03-data.md

@@ -133,16 +133,16 @@ Both failure modes are silent at seed time and visible only in the store, so che
 
 | What the request says | Decision |
 |---|---|
-| A provider is named or a key handed over ("connect Stripe") | wire it, then enable `card` — whenever convenient; it blocks nothing |
-| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: ask for the provider + key **after** the store works |
+| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient; it blocks nothing |
+| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: raise the provider **after** the store works |
 | Paid another way (transfer, COD, invoice, pickup, quotes) | nothing to do — the default already is exactly this |
 | Payments not mentioned at all | leave the default and **mention it at handover** |
 
-**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so asking a user to fetch a secret key before their store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
+**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so putting the provider connection before the store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
 
 **Say where payments landed** in your handover summary, including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
 
-*Only for a store that opted into cards:* wiring is a **file copy, not code you write** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation; copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy), store the provider secret as an app secret, register `https://<app-domain>/functions/commerce/payment-webhook` with the provider, then enable the gateway. Steps, other providers and the webhook model: [`../references/online-payments.md`](../references/online-payments.md).
+*Only for a store that opted into cards:* **if it is Stripe, the code is already written** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation, used **as-is**. Copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy) and enable the gateway with `payment_methods: ["offline", "card"]`. Nothing in it needs filling in and no key belongs in the code; it reads the credential the app's Stripe connection publishes. Any other provider means implementing four functions in that one file — [`../references/online-payments.md`](../references/online-payments.md).
 
 ## Done — forget this file
 
@@ -150,7 +150,7 @@ Both failure modes are silent at seed time and visible only in the store, so che
 - [ ] `warnings` in the response is empty, or every warning is deliberate and stated to the user.
 - [ ] Shipping is expressed in `locations` (with a catch-all if the store ships worldwide), not patched into entities afterwards.
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
-- [ ] Cards are either off, or on with a provider wired (file copied whole, secret stored, webhook registered).
+- [ ] Cards are either off, or on with the provider file copied whole and the `card` gateway enabled.
 - [ ] Product slugs from `catalog.products[]` recorded, and the storefront links by them.
 - [ ] If the brief named tiered rates, each named region prices to its rate (the `set-shipping-address` check above).
 

package/skills/commerce/references/catalog-rendering.md

@@ -1,7 +1,7 @@
 ---
 stage: reference
 read_when: "You are asking which fields a card or a product page can actually show, or hit a variant edge case (unavailable combinations, attributes with no variations, price ranges, linkable selections)."
-skip_when: "The listing and product page render correctly from useProductList / useProduct and the blocks — the quick start in ../install/02-storefront.md covers the happy path."
+skip_when: "The listing and product page render correctly from useProductList / useProduct and the render-model helpers — the quick start in ../install/02-storefront.md covers the happy path."
 forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
 carry_forward:
   - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
@@ -31,7 +31,7 @@ A listing **row** is the product record itself (minus paywalled fields) plus res
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`; every entry is an **object** — §2 |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`<ProductSpecsBlock/>` renders them) |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into spec-table rows) |
 | **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | Rows carry `{id, name}` ribbons; `get-product` returns the full records |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | §6 to add them to rows |
 | **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | Why a product with variants can't be fully priced from a row |
@@ -53,14 +53,14 @@ A product with attributes is **only** sellable through a variant: `add-item` wit
 Three rules used to be prose here and are now enforced by exports — use them and they can't drift between views:
 
 - **From-price.** `admin-products` (and the seeder) roll a parent's `regular_price`/`price`/`on_sale` up from the cheapest publishable variant on every save, so the parent price is real, sortable and filterable — but it is the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` accept **either** a listing row or a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range on an unresolved page, the exact price once resolved.
-- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` and `<ProductGalleryBlock/>` build on them. Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` builds on them (`hasImages`). Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
 - **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is a spec table — never a selector, never a ribbon.
 
 ## 3. What each view renders
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page. The card is deliberately the one thing no block ships — it is the most identity-defining component in a storefront.
+**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page — like every other piece of storefront UI, the card is entirely yours to design.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except layout and styling has a block: `<ProductGalleryBlock/>`, `<VariantSelectorBlock/>`, `<AddToCartBlock/>`, `<ProductSpecsBlock/>`, `<BreadcrumbsBlock/>`, `<ReviewsBlock/>`, `<ProductStripBlock/>`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
 
 ## 4. Ribbons — in **both** views
 
@@ -73,7 +73,7 @@ Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categorie
 
 ## 5. Variant selection
 
-The one interaction agents reliably get wrong. `<VariantSelectorBlock view={view} onPick={pick} />` encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable is rendered **disabled, not removed**. Take the block; drop to the hook only for different *structure* (`renderOption` covers swatches).
+The one interaction agents reliably get wrong. `variantAxes(view, pick)` hands you the render-ready model that encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
 
 Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js` — `defaultSelection` → `selectOption` on a click → `resolveSelection` for the view. Every `product.attributes[]` entry is an **axis** in `position` order; every `variations[]` record is one combination. Bind the UI to `view`, not to `product.*`, or a selection changes nothing: