@base44/app-plugin-commerce 0.2.5 → 0.2.7

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

@@ -10,78 +10,40 @@ 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\"."
+  - "Hooks return plain states and handlers (label, disabled, value, set, addToCart) — you write every element and attribute from them; render the state-driven text (buy.label, f.error, hint.message) and never re-derive what a hook already resolves."
+  - "Identity is encoded once — design classes in index.css plus one or two signature moments per page; a utility run that appears twice becomes a class, full-screen states go through the shared StatusScreen, and every page is measured (wc -c) against its char budget."
 ---
 
 # 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.
-
-**One import path: `@/commerce/storefront`.** Each section below opens with its
-page's exact import line — **copy it verbatim** instead of assembling one from
-memory, then delete any name you don't end up using. `variantAxes` and
-`productSpecs` live in `@/commerce/utils` but are re-exported here, so a React
-page never imports from `@/commerce/utils` directly; `useStoreInfo` is the name
-most often left out, and it is the only source of store name and currency.
+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 encode that look **once** as design classes (["Design language"](#design-language--once-before-any-page) below) and build every page in them — the snippets in this file are implementation reference, not design input.
+
+Two mechanics to hold everywhere:
+
+- **States and handlers, not magic.** Hooks return plain values — strings, booleans, arrays, callbacks (`buy.label`, `buy.disabled`, `buy.addToCart`, `f.value`, `f.set`) — never ready-made prop objects to spread. You write every element and every attribute; the hook guarantees the values are right. The flip side: **render what the hook resolves** — the button's text is `{buy.label}`, its gate is `disabled={buy.disabled}` — and never re-derive a state the hook already owns (a ternary chain over `adding`/`purchasable` re-implements `buy.state` wrong).
+- **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 (a nav with a cart badge, a footer), so
-**start from the layout route** — a pathless `<Route>` whose element is your
-layout, rendering `<Outlet/>` where the page goes. It also keeps the admin
-outside the storefront's provider and chrome:
+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 { Routes, Route, Outlet } from "react-router-dom";
-import { StorefrontProvider } from "@/commerce/storefront";
+import { StorefrontProvider, CartUIProvider } from "@/commerce/storefront";
 import { base44 } from "@/api/base44Client";
 import AdminApp from "@/commerce/admin";
 
-// StoreLayout is YOURS: <Nav/> (its cart badge calls useCart) + <Outlet/> + <Footer/>.
-function StoreLayout() { return <><Nav /><Outlet /><Footer /></>; }
-
 <BrowserRouter>
   <Routes>                                {/* ONE <Routes> — merge new pages into the app's */}
-    <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
+    <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 />} />
@@ -93,30 +55,53 @@ function StoreLayout() { return <><Nav /><Outlet /><Footer /></>; }
 </BrowserRouter>
 ```
 
-⚑ **The nesting is provider → layout → `<Outlet/>`, never the reverse.** A
-layout that renders the provider *inside* itself leaves the nav above (or
-outside) it, so the header badge and the cart page read different carts — and a
-`useCart` in the nav throws outright. The provider goes on the layout route's
-element, wrapping your layout component.
+⚑ **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`.
 
-**No shared chrome** (each page draws its own header, or there is one page)?
-Then wrap `<Routes>` directly and skip the layout route:
+## Design language — once, before any page
 
-```jsx
-<StorefrontProvider base44={base44}>     {/* wraps <Routes> — never a child of it */}
-  <Routes>…</Routes>
-</StorefrontProvider>
-```
+The measured cost driver of a generated storefront is not wiring — it is decoration repeated inline. In audited builds ~35% of every hand-written file was className strings, the same 150-char utility run pasted onto every panel, button and heading. Encode the store's identity **once**, then spend it everywhere:
+
+- In `index.css`, set the palette/typography variables, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language:
+
+  ```css
+  @layer components {
+    .panel      { @apply border border-border/40 bg-card p-6; }
+    .btn-cta    { @apply w-full py-4 bg-primary text-primary-foreground text-xs uppercase tracking-[0.2em] hover:bg-primary/90 transition-colors disabled:opacity-40 disabled:cursor-not-allowed; }
+    .label-mono { @apply text-xs uppercase tracking-[0.2em] text-muted-foreground; }
+    .field      { @apply w-full border border-border bg-transparent px-4 py-3 text-sm outline-none focus:border-primary; }
+    .choice-row { @apply flex items-center gap-4 p-4 border border-border/40 cursor-pointer transition-colors hover:border-primary/50; }
+    /* …heading scale, link style, price, alert — whatever THIS store repeats */
+  }
+  ```
+
+  Pages then carry short names plus at most a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class** — pasting the same string onto a second element means it belongs in `index.css`.
+
+- **One `<StatusScreen>` component for every full-screen state.** Loading, empty, error, not-found and order-submitted screens are one layout with different words. It is stateless — every hook already hands the page a plain `status` enum to branch on — so the whole component is this, restyled:
 
-> ⚠ **`<Routes>` accepts only `<Route>` children.** Putting 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>`.
-> A pathless layout route (above) is the one place a wrapper is legal.
+  ```jsx
+  // src/components/store/StatusScreen.jsx — the store's full-screen states, styled once
+  export default function StatusScreen({ title, message, action, busy }) {
+    return (
+      <div role="status" aria-busy={busy || undefined} className="…">  {/* centered, full-height */}
+        {busy && <span className="…" aria-hidden="true" />}            {/* your spinner/pulse */}
+        <h1 className="…">{title}</h1>
+        {message && <p className="…">{message}</p>}
+        {action}
+      </div>
+    );
+  }
+  ```
+
+  Every page's guards then become one-liners:
+
+  ```jsx
+  if (p.status === "loading")   return <StatusScreen busy title="Loading…" />;
+  if (p.status === "not_found") return <StatusScreen title="Not found" action={<Link to="/">Back to the shop</Link>} />;
+  ```
 
-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.
+  ⚑ Once `StatusScreen` exists, no page hand-draws a full-screen status branch — and don't wrap it in a status-mapping hook either; the copy per state is the page's, in words.
+
+**Concentrate identity; don't diffuse it.** The design classes already carry the store's look on every surface. On top of them, spend bespoke markup on **one or two signature moments per page** — the hero, the one product-page module that shows what these products are judged on — and render everything else as conventions in the store's classes. The signature budget concentrates where the products are: **the product page stays the storefront's richest surface** — its section's rules to render axes and specs *by what they are* hold with full force; the richness there is semantic (what the controls and rows show), which costs words, not chrome. One navigation affordance per control (a gallery gets thumbnails *or* arrows, never both plus dots); checkout, bag and order-received are convention surfaces — the classes style them, no bespoke widgets. Identity is legible in the tokens and the signature moments; decorating every element produces bulk, not character.
 
 ## Product list / collection
 
@@ -124,103 +109,52 @@ its whole lifecycle.
 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 — every hook above the guards, and `products` derived once:
+(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, so no defensive `?? []`
+if (list.status === "loading") return <StatusScreen busy title="…" />;
+if (list.status === "error")   return <StatusScreen title="…" action={<button type="button" onClick={list.reload}>Try again</button>} />;
+const products = list.products;   // always an array — never null
 ```
 
-The same opening carries a home page's rails and a search results page — only
-the params and your markup change.
-
-`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`.
+`useProductList(params)` → `{ status, products, hasNext, next, loadMore, busy, 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 paging whenever `hasNext` is true** — `{list.hasNext && <button type="button" onClick={list.next} disabled={list.busy}>Next</button>}` (append mode: `onClick={list.loadMore}` for "Load more"); 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: lead each card with the one or two fields *these* products are judged on (via `productSpecs`) rather than the default name/price/stars trio — but the card is your design classes plus those fields, not a bespoke widget.
+
+**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
 
 ```jsx
-import { useProduct, useProductGallery, useAddToCartButton, useStoreInfo, useStorefrontSeo, productSeo, variantAxes, productSpecs } from "@/commerce/storefront";
+import { useProduct, useProductGallery, useAddToCart, useProductSpecs, useStoreInfo, useStorefrontSeo, productSeo, variantAxes } from "@/commerce/storefront";
 ```
 
-(Add `useProductReviews` only if the store has reviews; drop `productSpecs` if
-these products carry no modifiers.)
+(Add `useProductReviews` only if the store has reviews; drop `useProductSpecs` if these products carry no modifiers.)
 
-`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:
+`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") });
+const buy = useAddToCart(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 */;
+if (p.status === "loading")   return <StatusScreen busy title="…" />;
+if (p.status === "not_found") return <StatusScreen title="…" action={/* link back to the catalog */} />;
 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. **Render each axis by what it is** — swatches for a colour axis, chips with a size guide beside a size axis; every axis as the identical chip row is a generated-page tell. The differentiation is semantic — what the control *shows* — built from your classes, not extra chrome around each row. The shape of the map:
 
   ```jsx
   {variantAxes(view, p.pick).map((axis) => (
@@ -233,129 +167,42 @@ 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, type, number,
-  unit, items }]` from `meta_data` (Material, Care, Provenance, Weight). `[]`
-  means no section at all. ⚑ **Don't `.map()` it into one uniform label/value
-  table** — that is the most reliable tell of a generated product page. Every
-  row's `type` is inferred for you so the branch point is already there:
-  `"numeric"` (with `number` and `unit` split out), `"duration"`, `"location"`,
-  `"list"` (with `items`), `"text"`.
 
-  ```jsx
-  // ❌ what a generated store ships: one grey table, every store the same
-  <dl>{specs.map((s) => <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>)}</dl>
-
-  // ✅ the figures read as figures, the rest falls through to a plain row
-  {productSpecs(product).map((s) =>
-    s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />  // 0.75 ct, set large
-  : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />                             // 70% wool / 30% cashmere
-  : s.type === "location" ? <Sourced key={s.key} place={s.value} />                             // a located line, a pin
-  :                         <Row     key={s.key} label={s.label} value={s.value} />)}
-  ```
-
-  Design the two or three that carry *this* product's meaning; branch on `s.key`
-  instead when one particular modifier deserves its own treatment. And they need
-  not sit in one block — a spec can go under the gallery, beside the price, or
-  inside the description.
-- **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 same rule the specs bullet states
-applies to the axes: `variantAxes` gives you `axis.key` / `axis.name` 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 — every axis rendered as
-the identical chip row is the other half of the generated-page tell. The ⚑ rules
-above (one control per axis, unbuyable options disabled) constrain the
-*behaviour* of a selector, never its form.
+- **Buy box** — `<button type="button" onClick={buy.addToCart} disabled={buy.disabled}>{buy.label}</button>` is the whole button. ⚑ **Both the text and the gate come from the hook** — `{buy.label}` follows the ready/adding/sold-out/needs-selection precedence (`buy.state`; override copy via `labels`), so never hardcode the button text or re-derive `disabled` from your own ternary chain. ⚑ 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. **This is the product page's one signature-moment candidate**: branch on `type` (or `key`) for the two or three `picked` specs that carry *this* product's meaning, and render `rest` as plain rows in your classes — not everything into one uniform table, and not a bespoke widget per spec either. `[]` 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
 
 ```jsx
-import { useCart, CartLine, useTotalsLines, useCoupon, useFormatMoney } from "@/commerce/storefront";
+import { useCart, CartLine, useTotalsLines, useCoupon, useCartUI, useUpsell } from "@/commerce/storefront";
 ```
 
-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.
-
-⚑ **`pending` is one row's flag, and it stays up until that update finishes.**
-The window is not the click: `increase`/`decrease` set the optimistic number and
-start a 250ms debounce, `pending` goes true when the request leaves, and returns
-to false **only after the new cart view has landed** — so `pending === false`
-with no `error` means that row's quantity and the totals are settled, not just
-that a request returned. (`remove()` skips the debounce, `pending` immediately.)
-So **disable and mark only that row** — `disabled={l.pending}` on its own
-controls, `aria-busy` on the row — since `pending` says nothing about the other
-lines, and stalling the whole cart over one 250ms stepper reads as a broken page.
-And note **`status` never returns to `"loading"` for a mutation**: it settles
-once, on first load, then only moves between `"empty"` and `"ready"`. There is
-deliberately no cart-wide busy flag — `status` is the page's shape, `pending` is
-"did that change land".
-
-⚑ **Repeated controls need unique accessible names.** A three-line cart renders
-three buttons named "Remove", and "+" or "×" alone names nothing at all — put the
-line in the label (``aria-label={`Remove ${line.name}`}``, likewise ±, and a
-drawer's close button). Identical or empty names are ambiguous to a screen reader
-and to anything driving the page by name.
-
-**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.
+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 */;
+  if (status === "loading") return <StatusScreen busy title="…" />;
+  if (status === "empty")   return <StatusScreen title="…" action={/* link 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 */
+          {(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}
@@ -365,15 +212,15 @@ function Bag() {
                       aria-label={`Increase quantity of ${line.name}`}>+</button>
               <button onClick={l.remove} disabled={l.pending}
                       aria-label={`Remove ${line.name}`}>Remove</button>
-              {formatMoney(line.total)}
+              {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>
     </>
@@ -381,69 +228,46 @@ 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 — a drawer only adds what a cart *page* gets for free:
-
-**Close it on navigation.** A product link or "Checkout" inside the drawer
-changes the route with the drawer still open, leaving it hanging over the new
-page. One effect covers every link inside, so no link has to remember:
+Same hooks, same rows. The drawer's *state* — open/close, Esc, close-on-route-change, open-on-add — is `useCartUI` (`{ open, openCart, closeCart, toggleCart }`); the markup is yours:
 
 ```jsx
-const { pathname } = useLocation();
-useEffect(() => { setOpen(false); }, [pathname]);
+function StoreLayout() {           // inside <CartUIProvider> (see Setup)
+  const ui = useCartUI();
+  const { itemCount } = useCart();
+  return (<>
+    <header>… <button type="button" onClick={ui.toggleCart} aria-expanded={ui.open}
+                      className="…">Bag ({itemCount})</button></header>
+    <Outlet />
+    {ui.open && (<>
+      <div onClick={ui.closeCart} aria-hidden="true" className="…" />
+      <aside role="dialog" aria-modal="true" aria-label="Cart" className="…">
+        <button type="button" onClick={ui.closeCart} aria-label="Close cart" className="…">×</button>
+        {/* your rows: useCart + CartLine, as above */}
+      </aside>
+    </>)}
+  </>);
+}
 ```
 
-**A closed drawer must be inert, not just invisible.** Hidden with `opacity` or
-`translate`, its buttons stay focusable and clickable — Tab walks into an
-invisible cart, and a click lands on a "Remove" nobody can see. Either don't
-render it (`{open && <Drawer/>}`) or, if it stays mounted for the transition, use
-`hidden` / `visibility: hidden` / `inert`. ⚑ Never `aria-hidden` alone: that
-hides it from a screen reader while leaving it fully clickable.
-
-**The backdrop is not the close button.** Both close the drawer; only one is a
-control. Name the visible button (`aria-label="Close cart"`) and leave the
-backdrop an unnamed overlay — `onClick={close}`, `aria-hidden="true"`, no tab
-stop. Two elements named "Close cart" are ambiguous to a screen reader and to
-anything driving the page; the keyboard's way out is Esc and the button.
+⚑ **Render the drawer conditionally (`{ui.open && …}`), exactly as above.** The classic drawer bug is a panel translated off-screen but still mounted — its buttons stay clickable, tab-able and visible to screen readers. If you keep it mounted to animate the slide, you own that concern: set the `inert` attribute while closed. The overlay is a click-away surface, not the close control — the named close button inside the panel is.
 
 ## Checkout
 
 ```jsx
-import { CheckoutProvider, useCheckoutContext, useCheckoutBlockers, useAddressForm, ShippingMethodPicker, PaymentMethodPicker, useCart, useTotalsLines, useCoupon, useFormatMoney } from "@/commerce/storefront";
+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` + `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.
+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"; wire each address field from its own states — `value={f.value}` `onChange={f.set}` `autoComplete={f.autoComplete}`, and render `f.error` ("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
@@ -453,10 +277,10 @@ function Checkout() {   // hooks read the context BELOW the provider
 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 */;
+  const order = usePlaceOrder();
+  if (order.stage === "submitted") return <StatusScreen busy title="…" />;  // "taking you to your receipt"
+  if (status === "loading") return <StatusScreen busy title="…" />;
+  if (status === "empty")   return <StatusScreen title="…" action={/* link back to the catalog */} />;
   return (
     <>
       <AddressFields which="billing" />
@@ -468,28 +292,27 @@ 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)}
+                <input type="radio" name="shipping-method" checked={m.selected} onChange={m.select} />
+                {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)} />
+                <input type="radio" name="payment-method" checked={g.selected} onChange={g.select} />
                 {g.title} {g.description}
               </label>
             ))}
@@ -500,64 +323,51 @@ 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 type="button" onClick={order.placeOrder} disabled={order.disabled}>{order.label}</button>
+      {order.error && <p role="alert">{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 htmlFor={f.id}>{f.label}{f.required && " *"}</label>
+      {f.isSelect ? (
+        <select id={f.id} value={f.value} onChange={f.set} autoComplete={f.autoComplete}>
+          <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} />
-      )}
+      ) : <input id={f.id} type={f.type} value={f.value} onChange={f.set} autoComplete={f.autoComplete} />}
       {f.error && <span role="alert">{f.error}</span>}
-    </label>
+    </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
 
 ```jsx
-import { useOrderReturn, useTotalsLines, useFormatMoney } from "@/commerce/storefront";
+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.
+**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></>;
+  if (status === "loading") return <StatusScreen busy title="…" />;   // confirming copy
+  if (status === "error")   return <StatusScreen title="…" message={error.message}
+                                     action={<button type="button" onClick={() => reload()}>Try again</button>} />;
   return (
     <>
       {status === "paid"      && /* thank-you heading */}
@@ -573,7 +383,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>)}
     </>
   );
@@ -588,88 +398,49 @@ 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.
-
-## 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 — a drawer is its own component with its own 3K, not an extension of this one |
-| 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, these are what make a
-working storefront look broken under a script. The common cause is acting
-faster than the cart settles: the hooks are optimistic and debounced, so the DOM
-is briefly right about the *intent* and wrong about the *state*.
-
-- **Wait for the cart, then for each row.** Two waits, neither optional. Before
-  the first action, wait for the initial load to settle — `status` leaves
-  `"loading"` exactly once, so the signal is the loaded UI (a row, or the empty
-  state), never a fixed sleep. Then after every stepper click wait for **that
-  row**: the click starts a 250ms debounce before the request even leaves, so
-  reading the quantity or total straight after gives the optimistic number and
-  stale totals, and two quick clicks send **one** request for the final number.
-  Wait for the row's busy state to clear (`aria-busy`, re-enabled buttons) before
-  reading or clicking again.
-- **Scope actions to the visible drawer.** With a drawer, the page can hold two
-  "Remove" buttons for one line — drawer and cart page behind it — and a
-  closed-but-mounted drawer keeps its copies clickable. Query inside the open
-  drawer's container, not the document. A click that seems to do nothing usually
-  hit the hidden copy.
-- **Remove lines one at a time.** Clicking every "Remove" in one pass fails on
-  its own terms: cart calls are serialized, each removal re-renders the list, and
-  buttons collected up front are detached by the time the loop reaches them.
-  Remove one, wait for the row to disappear, then the next.
-- **Verify the checkout navigation before cleaning up.** Confirm you are on
-  `/checkout` — URL plus a field of the form on screen — before emptying the cart
-  or moving on. Tearing the cart down while still on the cart page, or
-  mid-navigation, produces an empty checkout that reads as a routing bug.
-- **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).
+The `*Seo` builders tolerate a null product, so this sits with the other hooks above the status guards.
+
+## Per-page output budgets — measured, not aspirational
+
+| 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 — identity lives in the hero + one editorial moment, in your classes |
+| Any single component file | ≤ 4K, hard ceiling 8K |
+
+When the storefront builds clean, **measure** (adjust the paths to your component folder names):
+
+```bash
+wc -c src/pages/*.jsx src/components/store*/*.jsx
+```
+
+A page over budget has one of two problems — fix in this order, and never by dropping states, branches or ⚑ rules:
+
+1. **Inline decoration that belongs in `index.css`** — this is where the chars measurably are. Extract every repeated utility run into the design classes, fold hand-drawn status branches into `StatusScreen`, and cut any second navigation affordance or off-signature widget.
+2. **Re-implemented hook logic** (a buy button's state precedence, a quantity clamp, totals math, drawer state) — go back to the hook and delete your version.
+
+## 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 — on the layout route's element, wrapping the layout that renders `<Outlet/>` (or wrapping `<Routes>` if the store has no shared chrome); one client, no hand-rolled `cart_token`.
-- [ ] Every page's imports came from its section's import line above: one path (`@/commerce/storefront`), nothing imported from `@/commerce/utils`, and no imported name — React's included — left unused.
-- [ ] 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.
-- [ ] Cart rows scope their busy state to the row (`l.pending` + `aria-busy`), and every repeated control (remove, ±, a drawer's close) has a unique accessible name.
-- [ ] A cart drawer closes on route change, is **inert** when closed (not merely invisible), and its backdrop is not a second control named "Close cart".
-- [ ] 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.
-- [ ] Specs and axes are rendered by what they are (`productSpecs`' `type`/`key`, `axis.key`) — not one uniform label/value table and one identical chip row.
-- [ ] Every page is within its budget above.
+- [ ] Catalog UI in whatever form fits the store, plus a checkout, plus `/order-received` rendering `useOrderReturn`'s states **including `paymentInstructions`**.
+- [ ] `index.css` defines the store's design classes; pages carry class names, not repeated utility runs; every full-screen state goes through the shared `StatusScreen`.
+- [ ] **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.
+- [ ] Every control renders the hook's states — button text is `buy.label`/`order.label`, gates are the hook's `disabled`, address fields wire `value={f.value}` `onChange={f.set}` `autoComplete={f.autoComplete}` — no re-implemented hook logic.
+- [ ] Coupon field present if the store has coupons; a paging control rendered whenever `hasNext` is true.
+- [ ] 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` and is rendered conditionally on `ui.open` (closes on route change by itself).
+- [ ] Checkout guards `stage === "submitted"` above its empty-cart branch.
+- [ ] The storefront carries the design you settled on before reading this file — encoded in the design classes plus one or two signature moments per page; on the product page, axes and specs are rendered by what they are (not one uniform table, not one identical chip row); convention surfaces (checkout, bag, order-received) carry the classes and nothing bespoke.
+- [ ] Measured with `wc -c` — every page within its budget above.
 
 Record these lines in your working notes; do not re-read this file.
 
@@ -679,3 +450,5 @@ 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".
+- Hooks return plain states and handlers (`label`, `disabled`, `value`, `set`, `addToCart`) — you write every element and attribute from them; render the state-driven text (`buy.label`, `f.error`, `hint.message`) and never re-derive what a hook already resolves.
+- Identity is encoded once — design classes in `index.css` plus one or two signature moments per page; a utility run that appears twice becomes a class, full-screen states go through the shared `StatusScreen`, and every page is measured (`wc -c`) against its char budget.