@base44/app-plugin-commerce 0.2.4 → 0.2.6

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

@@ -10,165 +10,104 @@ carry_forward:
   - "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\"."
+  - "Spread the hook's prop set (inputProps, radioProps, buttonProps, panelProps, moreProps) and add className — never assemble those attributes by hand."
 ---
 
 # 02 — 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`.
+One split decides everything here: **the logic is premade, the UI never is.** The hooks own checkout repricing, variant resolution, cart state, coupon redemption, review policies, order-return verification — hand-writing any of it is where storefront bugs cluster, so **never re-implement what a hook does**. Every element, class, layout and word of copy is yours; nothing in `@/commerce/storefront` renders markup or carries CSS. **Decide how the store looks as if this kit did not exist**, then use this file for how to wire it — the snippets below are implementation reference, not design input.
+
+Two mechanics to hold everywhere:
+
+- **Prop sets, not hand-assembled attributes.** Hooks return ready-to-spread objects — `f.inputProps`, `m.radioProps`, `buy.buttonProps`, `ui.panelProps`, `list.moreProps` — carrying the handlers, ids, aria wiring and disabled logic. Spread first, put your `className` after; writing `value`/`onChange`/`autoComplete` yourself means re-deriving what a prop set already holds.
+- **Each hook's JSDoc is the API reference.** Open the hook's file when you need exact shapes; don't guess fields. Rules marked ⚑ must survive whatever design you build.
+
+**One import path: `@/commerce/storefront`.** Each section opens with its page's exact import line — copy it verbatim, then delete unused names. (`variantAxes` and `productSpecs` are re-exported there; a React page never imports `@/commerce/utils` directly. `useStoreInfo` is the name most often left out — it is the only source of store name and currency.)
 
 ## Setup — once
 
+Nearly every store has shared chrome, so **start from a pathless layout route** — it also keeps the admin outside the storefront's provider:
+
 ```jsx
-import { StorefrontProvider } from "@/commerce/storefront";
+import { Routes, Route, Outlet } from "react-router-dom";
+import { StorefrontProvider, CartUIProvider } from "@/commerce/storefront";
 import { base44 } from "@/api/base44Client";
+import AdminApp from "@/commerce/admin";
 
 <BrowserRouter>
-  <StorefrontProvider base44={base44}>     {/* wraps <Routes> — never a child of it */}
-    <Routes>                               {/* ONE <Routes> — merge new pages into the app's */}
+  <Routes>                                {/* ONE <Routes> — merge new pages into the app's */}
+    <Route element={
+      <StorefrontProvider base44={base44}>
+        <CartUIProvider>                  {/* only if the cart is a drawer — see Cart below */}
+          <StoreLayout />                 {/* YOURS: header + <Outlet/> + footer + drawer */}
+        </CartUIProvider>
+      </StorefrontProvider>
+    }>
       <Route path="/" element={<Home />} />
       <Route path="/product/:slug" element={<ProductPage />} />
       <Route path="/bag" element={<Bag />} />
       <Route path="/checkout" element={<Checkout />} />
       <Route path="/order-received" element={<OrderReceived />} />
-      <Route path="/store-admin/*" element={<AdminApp />} />
-    </Routes>
-  </StorefrontProvider>
+    </Route>
+    <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
+  </Routes>
 </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.
-
-> ⚠ **`<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 />} />
->   <Route path="/checkout" element={<Checkout />} />
-> </Route>
-> <Route path="/store-admin/*" element={<AdminApp />} />   {/* outside the provider */}
-> ```
+⚑ **The nesting is provider → layout → `<Outlet/>`, never the reverse** — a layout that renders the provider inside itself leaves the nav's cart badge on a different cart (or throws). With no shared chrome, wrap `<Routes>` in the provider instead; a provider *inside* `<Routes>` throws ("is not a `<Route>` component"). The provider owns the shared client, store info and **one** shared cart — never mount a second one, never touch `cart_token`.
 
 ## 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 can render `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` — and a row carries the whole product record, so `weight`,
-`dimensions`, `attributes[]` and `meta_data` are there too. Full field matrix:
-[`../references/catalog-rendering.md`](../references/catalog-rendering.md).
-
-That is an inventory of what you *can* show, not a card design and not a list
-to render in order. An even grid of identical cards, each with the same
-name/price/stars trio, is where a generated store lands by default and almost
-never where this catalog belongs: give the grid a rhythm (a hero piece spanning
-two columns, an editorial break between rows, a denser tile for a large
-catalog), and lead each card with the one or two fields *these* products are
-judged on — carat weight, focal length, edition size, ABV — read off
-`meta_data` via `productSpecs(row)`, not the fields every store shows.
-
-**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`.
+```jsx
+import { useProductList, useCategories, useProductPrice, useStoreInfo, useStorefrontSeo, collectionSeo, productSpecs } from "@/commerce/storefront";
+```
+
+(Drop `useCategories` with no filter bar, `productSpecs` if the card shows no modifiers, add `useRibbons` for a ribbon filter.) The top of the component, before any markup:
+
+```jsx
+const list = useProductList({ per_page: 24 });
+const { settings } = useStoreInfo();
+useStorefrontSeo(collectionSeo({ title: "…", products: list.products, storeName: settings?.store_name }));
+
+if (list.status === "loading") return /* your loading state */;
+if (list.status === "error")   return /* your failure state, with a retry calling list.reload() */;
+const products = list.products;   // always an array — never null
+```
+
+`useProductList(params)` → `{ status, products, hasNext, moreProps, 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, in_stock_only, … })` resets to page 1 and keeps current rows on screen (`refreshing`). ⚑ **Render `<button {...list.moreProps}>Load more</button>`** (or "Next") — it hides itself on the last page; a page that renders nothing for paging ships a catalog silently capped at `per_page`. `useCategories()` / `useRibbons()` → `{ items }` — drive filters from that data, never from hardcoded names (a renamed ribbon must not strand a dead button).
+
+Your card can render `name`, `productImages(row)[0]` (⚑ **images are `{src, 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`, and `meta_data` via `productSpecs(row)`. Full field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That is an inventory, not a card design: give the grid a rhythm and lead each card with the one or two fields *these* products are judged on (via `productSpecs`), not the name/price/stars trio every generated store ships.
+
+**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` (render via `useUpsell` — see Cart).
 
 ## 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.
+```jsx
+import { useProduct, useProductGallery, useAddToCartButton, useProductSpecs, useStoreInfo, useStorefrontSeo, productSeo, variantAxes } from "@/commerce/storefront";
+```
+
+(Add `useProductReviews` only if the store has reviews; drop `useProductSpecs` if these products carry no modifiers.)
 
-⚑ **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:
+`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** — they all tolerate a null/loading product precisely so they can sit at the top; a hook after an early `return` crashes React the moment the product resolves.
 
 ```jsx
 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 }));
+const buy = useAddToCartButton(p, { labels: { ready: "Add to bag" } });
+const specs = useProductSpecs(p.product, { pick: ["material", "care"] });
+const { settings } = useStoreInfo();   // the ONLY source of store name + currency
+useStorefrontSeo(productSeo(p.product, p.view, { storeName: settings?.store_name, currency: settings?.currency }));
 
 if (p.status === "loading")   return /* your loading state */;
 if (p.status === "not_found") return /* your 404 */;
 const { product, view, price, categories } = p;
 ```
 
-(`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):
+Build your layout from — all optional, each one hook, **not one component style**:
+
+- **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` → `{ hasImages, images, active, activeIndex, setActiveIndex, next, prev }`. The active image 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 }] }`. ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. The shape of the map (the control itself is yours — swatches for a colour axis, chips with a size guide for a size axis; every axis as the identical chip row is a generated-page tell):
 
   ```jsx
   {variantAxes(view, p.pick).map((axis) => (
@@ -181,80 +120,34 @@ anywhere.) Build your layout from:
     </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, Provenance). `[]` 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 — and each is
-one hook, **not one component style**. The tell of a generated product page is
-that every axis is the same chip row and every modifier the same grey
-label/value line. Branch on what they are: `variantAxes` gives you `axis.key` /
-`axis.name`, `productSpecs` gives you `key` / `label`, so a colour axis can be
-swatches in the real colours, a size axis chips with a size guide beside them,
-a material axis a small sample image; a "Composition" modifier can be bars, a
-"Provenance" a map pin, a "Certification" a seal, a "Weight" a figure set in
-the display face. Design the two or three that carry this product's meaning,
-let the rest fall back to a plain row, and don't feel obliged to keep them in
-one block — a spec can sit under the gallery, beside the price, or inside the
-description. The ⚑ rules above (one control per axis, unbuyable options
-disabled) constrain the *behaviour* of a selector, never its form.
+
+- **Buy box** — `<button {...buy.buttonProps}>{buy.label}</button>` is the whole button: gate, busy state and the ready/adding/sold-out/needs-selection precedence are inside (`buy.state`; override copy via `labels`). ⚑ Render `buy.error.message` inline; ⚑ `buy.showQuantity: false` means no stepper (`increase`/`decrease`/`canIncrease` drive one when true). With `<CartUIProvider>` mounted, a successful add opens the drawer by itself.
+- **Description** — `product.description` is HTML; render as rich text, `short_description` above it.
+- **Specs** — `useProductSpecs(product, { pick: [...] })`: `picked` are the rows to feature (matched case/`_`-insensitively — ⚑ **never match rows by `label` equality**, it silently misses), `rest` is the remainder, safe to render as plain rows. Each row carries `titleLabel` (display-cased) and a `type` with `number`/`unit`/`items` split out, so a weight can be a figure and a composition bars. ⚑ **Don't `.map()` everything into one uniform label/value table** — branch on `type` (or `key`) for the two or three specs that carry *this* product's meaning; `[]` means no section at all.
+- **Breadcrumbs** — build from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons are labels, not breadcrumbs.
 
 ### 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).
+**Build reviews only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either — an average of nothing is `0`). `useProductReviews(product, { policy, user })` is the whole surface: `items`, paging, `averageRating`, and the submit form (`form`/`setField`/`fieldErrors`, `valid`, `submit`, `requiresEmail`, `reviewBlockedReason`). ⚑ The confirmation copy is `message`, **taken from the server's response** — a store with auto-approval says "published", not "awaiting approval". `policy` is `"open" | "login" | "verified_buyers"`; details: [`../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
+import { useCart, CartLine, useTotalsLines, useCoupon, useCartUI, useUpsell } from "@/commerce/storefront";
+```
+
+A cart *page* is optional (buy-now straight to checkout reads better for a single-piece store). The surface: `useCart()` (`status`, `lines`, `notices`), `CartLine` (headless per-row binding — 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 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 none exists, don't seed coupons and don't write "use WELCOME10" in the copy.
+
+⚑ **`pending` is one row's flag**: it goes true when that row's debounced request leaves and false only after the new cart view lands — so disable and mark only that row (`disabled={l.pending}`, `aria-busy` on the row), never the whole cart. `status` never returns to `"loading"` for a mutation; there is deliberately no cart-wide busy flag. ⚑ **Repeated controls need unique accessible names** — three "Remove" buttons name nothing; put the line in the label.
+
+**Reference wiring** — structure correct, presentation deliberately absent; restyle and rearrange, keep the ⚑ rules:
 
 ```jsx
 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 (
@@ -262,22 +155,25 @@ function Bag() {
       {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>
+          {(l) => (   /* line: name, attributesLabel, image, totalLabel — l: the controls */
+            <li aria-busy={l.pending}>       {/* busy scope is THIS row, never the cart */}
               {line.name} {line.attributesLabel}
-              <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+              <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}>+</button>
-              <button onClick={l.remove}>Remove</button>
-              {formatMoney(line.total)}
+              <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
+                      aria-label={`Increase quantity of ${line.name}`}>+</button>
+              <button onClick={l.remove} disabled={l.pending}
+                      aria-label={`Remove ${line.name}`}>Remove</button>
+              {l.totalLabel}
               {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 */
+      {totals.filter((t) => !t.hidden).map((t) => (
+        <div key={t.key}>{t.label} {t.formatted}</div>   /* t.emphasis → the total row */
       ))}
       <Link to="/checkout">Checkout</Link>
     </>
@@ -285,37 +181,43 @@ function Bag() {
 }
 ```
 
-No shipping estimator here — checkout reprices shipping and tax from the
-address.
+No shipping estimator here — checkout reprices shipping and tax from the address. An upsell beside the lines is one hook: `const kit = useUpsell(slugOrRow)` → `{ show, product, price, add, adding }`; branch on `show` (it is false while loading, out of stock, or already in the cart — matched by id).
+
+### If the cart is a drawer
+
+Same hooks, same rows. The drawer's *machinery* — close-on-route-change, inert-when-closed, dialog semantics, Esc, focus, open-on-add — is `useCartUI`, and hand-writing any of it is how drawers break (invisible-but-clickable controls, a drawer hanging over the checkout):
+
+```jsx
+function StoreLayout() {           // inside <CartUIProvider> (see Setup)
+  const ui = useCartUI();
+  const { itemCount } = useCart();
+  return (<>
+    <header>… <button {...ui.triggerProps} className="…">Bag ({itemCount})</button></header>
+    <Outlet />
+    <div {...ui.overlayProps} className={ui.open ? "…" : "hidden"} />
+    <aside {...ui.panelProps} className={ui.open ? "… translate-x-0" : "… translate-x-full"}>
+      <button {...ui.closeButtonProps} className="…">×</button>
+      {/* your rows: useCart + CartLine, as above */}
+    </aside>
+  </>);
+}
+```
+
+⚑ Keep the panel mounted and animate with classes — `panelProps` makes it inert while closed, which is what an off-screen drawer needs and `aria-hidden` alone does not provide. The overlay is not a second close control; the named close button is `closeButtonProps`.
 
 ## 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`. Both are **full page loads** (`window.location.assign`),
-which is why the order-received page boots from the URL alone; pass
-`orderReceivedPath: null` and `navigate(orderReceivedUrl(result))` if you want
-a router transition instead. 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
+import { CheckoutProvider, useCheckoutContext, usePlaceOrder, useAddressForm, ShippingMethodPicker, PaymentMethodPicker, useCart, useTotalsLines, useCoupon } from "@/commerce/storefront";
+```
+
+(`useCoupon` only if the coupon field lives here rather than in the cart.)
+
+The state machine is `useCheckout`, shared across the page's regions by `CheckoutProvider`. It reprices shipping/tax from the address automatically (debounced, never on a half-typed address), derives the shipping and payment choices, gates the button, and `placeOrder()` handles **both** navigations — online gateway → provider redirect, everything else → `/order-received` — as **full page loads** (pass `orderReceivedPath: null` for a router transition; see `useCheckout`'s JSDoc).
+
+⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected"; keep each field's spread props intact (they carry `autoComplete` and the error wiring — "we don't ship there" arrives on the country field); render the gate's `error` and `blockers` so a disabled button explains itself. ⚑ Payment methods, currency and countries come from `useStoreInfo()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only.
+
+**Reference implementation** — the densest wiring in the storefront; read it, then build yours around it:
 
 ```jsx
 function Checkout() {   // hooks read the context BELOW the provider
@@ -325,10 +227,10 @@ function Checkout() {   // hooks read the context BELOW the provider
 function CheckoutForm() {
   const { status } = useCart();
   const checkout = useCheckoutContext();
-  const blockers = useCheckoutBlockers();
-  const formatMoney = useFormatMoney();
+  const order = usePlaceOrder();
+  if (order.stage === "submitted") return /* "order placed — taking you to your receipt…" */;
   if (status === "loading") return /* loading */;
-  if (status === "empty")   return /* "your bag is empty" — a checkout with nothing says so */;
+  if (status === "empty")   return /* "your bag is empty" */;
   return (
     <>
       <AddressFields which="billing" />
@@ -340,30 +242,23 @@ function CheckoutForm() {
       {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>}
+        {({ hint, mustChoose, methods, chosen }) => (
+          <fieldset>{/* renders null for a virtual cart */}
+            {hint && <p role={hint.severity === "error" ? "alert" : "status"}>{hint.message}</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>
+              <label key={m.id} {...m.labelProps}><input {...m.radioProps} /> {m.title} {m.costLabel}</label>
             ))}
-            {!mustChoose && chosen && <p>{chosen.title} {formatMoney(chosen.cost)}</p>}
+            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
           </fieldset>
         )}
       </ShippingMethodPicker>
 
       <PaymentMethodPicker>
-        {({ gateways, value, select, selected, single }) => (
+        {({ hint, single, gateways, selected }) => (
           <fieldset>
-            {gateways.length === 0 && <p role="alert">No payment method is available right now.</p>}
+            {hint && <p role="alert">{hint.message}</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>
+              <label key={g.slug} {...g.labelProps}><input {...g.radioProps} /> {g.title} {g.description}</label>
             ))}
             {single && selected && <p>{selected.title}</p>}
           </fieldset>
@@ -372,57 +267,48 @@ function CheckoutForm() {
 
       {/* 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>)}
+      <button {...order.buttonProps}>{order.label}</button>
+      {order.error && <p {...order.errorProps}>{order.error.message}</p>}
+      {!order.canPlaceOrder && order.blockers.map((b) => <p key={b.code}>{b.message}</p>)}
     </>
   );
 }
 
 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>
+  const { fields } = useAddressForm(which);
+  return fields.map((f) => (
+    <div key={f.key}>
+      <label {...f.labelProps}>{f.label}{f.required && " *"}</label>
+      {f.isSelect ? (
+        <select {...f.selectProps}>
+          <option value="">{f.placeholder}</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>
+      ) : <input {...f.inputProps} />}
+      {f.error && <span {...f.errorProps}>{f.error}</span>}
+    </div>
   ));
 }
 ```
 
+⚑ **The `stage === "submitted"` guard goes above the empty-cart branch** — placing an order clears the cart before the browser navigates, and without the guard the page flashes "your bag is empty" over a just-placed order.
+
 ## Order received
 
-**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.
+```jsx
+import { useOrderReturn, useTotalsLines } from "@/commerce/storefront";
+```
+
+**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.
 
-⚑ 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)`).
+⚑ Rules: render all five states — never a blank page while `"loading"`, 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. ⚑ An order's totals are flat (`order.total`, no `order.totals`) — use `useTotalsLines(order)`.
 
-**Reference implementation** — a receipt is a convention, not an identity
-surface: take this structure, restyle it to the store, keep every branch.
+**Reference implementation** — a receipt is a convention, not an identity surface: take this structure, restyle it, keep every branch.
 
 ```jsx
 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></>;
@@ -441,7 +327,7 @@ function OrderReceived() {
             .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>)}
+      {lines.map((l, i) => <p key={i}>{l.name} {l.attributesLabel} × {l.quantity} — {l.totalLabel}</p>)}
       {totals.filter((t) => !t.hidden).map((t) => <p key={t.key}>{t.label} {t.formatted}</p>)}
     </>
   );
@@ -456,59 +342,38 @@ useStorefrontSeo(collectionSeo({ title, products: list.products }));      // col
 // order-received is already noindex via useOrderReturn
 ```
 
-The `*Seo` builders tolerate a null product, so this sits with the other hooks
-above the status guards.
+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 | ≤ 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 — 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 |
-
-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. Design detail is
-not what pushes a page over: giving a colour axis swatches or a composition
-modifier bars costs a few hundred characters, and that is what the budget is
-for.
-
-## If you drive the storefront from a browser script
-
-Whatever you choose to check and however you check it, two things make a
-working storefront look broken under a script:
-
-- **Filling the checkout.** Every field is a controlled React input, so writing
-  `el.value` changes nothing React sees. Use the harness's own fill (it
-  dispatches `input` + `change`) — never lift the native setter off
-  `HTMLInputElement.prototype` and call `descriptor.set(v)`: detached from the
-  element it throws `Illegal invocation`, and the workaround it is reaching for
-  is what the fill helper already does.
-- **`placeOrder` ends the page.** It navigates with `window.location.assign`
-  (above), so a script that placed an order loses its page context and can land
-  back at `/` — while the order itself was created normally. That is the hard
-  navigation, not a broken redirect. The confirmation is reachable at any time
-  from a fresh navigation to `/order-received?order_id=…&order_key=…` (the ids
-  come back in `placeOrder`'s result, and `commerce/admin-orders` `search` has
-  the order either way).
+| Page | budget (chars) |
+|---|---|
+| Checkout | ≤ 3.5K |
+| Cart / bag | ≤ 3K (a drawer is its own component with its own 3K) |
+| Order-received | ≤ 2.5K |
+| Product page | ≤ 5K |
+| Collection | ≤ 3K |
+| Home | ≤ 5K — pure identity; hero/editorial earn their chars |
+| Any single component file | ≤ 4K, hard ceiling 8K |
+
+These budgets assume the hooks carry the logic and your markup carries only the design. Over budget ⇒ you are re-implementing something a hook or a prop set already does (an address field's attributes, a quantity clamp, totals math, drawer state) — go back to the hook and delete your version. Design detail is not what pushes a page over.
+
+## Driving the storefront from a browser script?
+
+The hooks are optimistic and debounced, so a script that acts faster than the cart settles sees a working store as broken. Read [`../references/storefront-verification.md`](../references/storefront-verification.md) **before** writing the script — not after it fails.
 
 ## Done — forget this file
 
-- [ ] Catalog UI exists in whatever form fits the store (list, product pages, or both), plus a checkout, plus `/order-received`.
-- [ ] **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 (`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, and the attributes and modifiers that matter to these products are designed rather than poured into one uniform block.
+- [ ] Catalog UI in whatever form fits the store, plus a checkout, plus `/order-received` rendering `useOrderReturn`'s states **including `paymentInstructions`**.
+- [ ] **One** `<StorefrontProvider>` above every storefront route (layout-route pattern); one client, no hand-rolled `cart_token`.
+- [ ] Every page's imports came from its section's import line; nothing imported from `@/commerce/utils`; no unused names.
+- [ ] Pages branch on `status`; gateways/currency/countries read from `useStoreInfo()` only.
+- [ ] Prop sets spread wherever one exists — no hand-assembled `value`/`onChange`/`autoComplete`/radio/drawer wiring, no re-implemented hook logic.
+- [ ] Coupon field present if the store has coupons; paging rendered via `moreProps`.
+- [ ] Variant options: one control per axis, unbuyable options disabled, not hidden.
+- [ ] Cart rows scope busy state to the row; repeated controls have unique accessible names; a drawer uses `useCartUI` (inert when closed, closes on route change).
+- [ ] Checkout guards `stage === "submitted"` above its empty-cart branch.
+- [ ] The storefront carries the design you settled on before reading this file — no page ships the reference snippets' bare structure; specs and axes are rendered by what they are, not one uniform table and one identical chip row.
 - [ ] Every page is within its budget above.
 
 Record these lines in your working notes; do not re-read this file.
@@ -519,3 +384,4 @@ Record these lines in your working notes; do not re-read this file.
 - 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".
+- Spread the hook's prop set (`inputProps`, `radioProps`, `buttonProps`, `panelProps`, `moreProps`) and add `className` — never assemble those attributes by hand.