@base44/app-plugin-commerce 0.3.4 → 0.4.1

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

@@ -5,24 +5,21 @@ skip_when: "The storefront pages already render against live data and pass the c
 forget_when: "The checklist at the bottom passes — every page renders against the seeded catalog and an offline order completes."
 carry_forward:
   - "Payment gateways, currency and countries come from useStoreInfo() only — never off a cart (cart.payment_gateways is always undefined)."
-  - "A store with any coupons must have a coupon field (useCart().applyCoupon) in the cart or the checkout, or its codes can never be redeemed."
-  - "/order-received is mandatory and renders useOrderReturn's states, including paymentInstructions — how a normal (offline) customer learns how to pay."
-  - "Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
+  - "A store with any coupons must place a CouponField part once (cart or checkout), or its codes can never be redeemed."
+  - "The receipt route is mandatory: OrderReceived.Root with all five gates, PaymentInstructions on the unpaid branch."
+  - "Branch custom hook-built UI on `status`, never on `isEmpty`/nullable data; every hook goes above its status guards."
   - "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\"."
-  - "The kit ships no copy: hooks hand you state codes (buy.state, hint.code, blockers) and you write every word — including the reason a disabled button is disabled."
-  - "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."
+  - "No copy ships: every word the parts render comes from the store's copy file (labels); a ⟨copy: …⟩ placeholder on screen is unfinished work."
+  - "Identity is encoded once — design classes in index.css (parts styled via [data-part] selectors, controls always among them) plus one or two signature moments per page."
 ---
 
 # 02 — Storefront
 
-One split decides everything here: **the logic is premade, the UI never is.** The hooks own checkout repricing, variant resolution, cart state, 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** 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 it **once** as design classes ([below](#design-language--once-before-any-page)) — the snippets here are wiring reference, never design input.
+Two tiers decide everything here. **The catalog surfaces — product list and product page — are fully yours**: the logic ships as hooks, every element, class and word is the store's own, and this is where the design effort goes. **The commodity surfaces — cart, drawer, checkout, order-received — are placed, not written**: `Cart.*` / `CartDrawer.*` / `Checkout.*` / `OrderReceived.*` parts render each section's correct markup with **zero CSS, zero copy and zero navigation**; your page is the layout around them, your copy file their words, your `index.css` their look. Nothing in the kit ships a look or a sentence — **decide how the store looks and sounds as if the kit did not exist**, then encode it once (design classes + the copy file); the snippets here are wiring reference, never design input. Where a state needs words you get the *state* (`buy.state`, a blocker code) and write the words; never re-derive a state you were handed, never leave one unworded.
 
-**States and codes, not copy.** Where a state needs words you get the *state* (`buy.state`, `hint.code`, `blockers`) and write the words. So: never re-derive a state you were handed (a ternary chain over `adding`/`purchasable` re-implements `buy.state`, wrong), and never leave one unworded (a button with no text for `sold_out` renders empty).
+**This file is the whole job.** Every shape and contract you need is in the tables here — **don't open the hook or part files while building**. The parts are the app's own source (`src/commerce/storefront/parts/`), so they *can* be edited — only when a user requirement genuinely exceeds their props, after the cheaper rungs (`classes`/CSS → labels → `…Render` overrides → the hooks, [`../references/storefront-custom.md`](../references/storefront-custom.md)); an edited part is the store's code to maintain. Rules marked ⚑ must survive whatever design you build.
 
-**This file is the whole job.** Every shape you need is in ["What each hook resolves to"](#what-each-hook-resolves-to) — don't open the hook files while building; that is the most expensive way to answer a question this page already answers. 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. Everything a page needs is re-exported there, so a React page never imports `@/commerce/utils` directly. `useStoreInfo` is the name most often left out.
+**One import path: `@/commerce/storefront`.** Each section opens with its import line — copy it, delete unused names.
 
 ## Setup — once
 
@@ -30,53 +27,93 @@ Nearly every store has shared chrome, so **start from a pathless layout route**
 
 ```jsx
 import { Routes, Route, Outlet } from "react-router-dom";
-import { StorefrontProvider, CartUIProvider } from "@/commerce/storefront";
+import { StorefrontProvider, CartUIProvider, useCart } from "@/commerce/storefront";
+import { STORE_COPY } from "@/copy";      // the copy file, below
 import { base44 } from "@/api/base44Client";
 import AdminApp from "@/commerce/admin";
 
 <BrowserRouter>
   <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 */}
+      <StorefrontProvider base44={base44} labels={STORE_COPY}>
+        <CartUIProvider>                  {/* only if the cart is a drawer */}
           <StoreLayout />                 {/* YOURS: header + <Outlet/> + footer + drawer */}
         </CartUIProvider>
       </StorefrontProvider>
     }>
       <Route path="/" element={<Home />} />
       <Route path="/product/:slug" element={<ProductPage />} />
-      {/* /bag, /checkout, and /order-received — which is mandatory */}
+      {/* /bag, /checkout, /order-received (mandatory) */}
     </Route>
     <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
-
-// …and the layout that route renders. Yours to design; the shape is the point:
-function StoreLayout() {
-  const { itemCount } = useCart();          // one cart, shared with every page
-  return (
-    <>
-      <header>{/* nav + your cart trigger, showing itemCount */}</header>
-      <Outlet />                            {/* the routed page lands here */}
-      <footer>…</footer>{/* + the drawer, if the cart is one — see Cart below */}
-    </>
-  );
-}
 ```
 
-⚑ **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`.
+⚑ **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. 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, never touch `cart_token`.
 
 ## Design language — once, before any page
 
-The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row`, a heading scale, a price style — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.**
-
-The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show. It is the half of a store's identity a kit cannot ship.
+The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row` — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.** The store's words work the same way: one copy file in the store's voice (below), written once.
+
+**Concentrate identity; don't diffuse it.** The classes carry the look everywhere; on top of them, spend bespoke markup on **one or two signature moments per page**. **The product page stays the storefront's richest surface**, and that richness is semantic: what the controls and rows *show*. Checkout, bag and order-received are convention surfaces — the parts render their structure, your classes carry their look. Keep components small (~2–4K chars).
+
+## The parts — shared contract
+
+A part renders one section's correct semantic markup — every branch, guard and aria attribute — and nothing else. Your markup arranges the parts (grid, order, sticky aside, accordion steps — a hidden part loses no state; the place-order gate still counts every blocker). Three inputs carry the identity:
+
+- **Styling.** The parts ship **layout geometry only** — field grids, labels above full-width controls, square thumbnails, label-left/value-right totals, the drawer as a right-hand panel — and **no** color, border, radius, shadow or font, so an unstyled store reads as unfinished, never broken. The look is yours: every element carries `data-part` + state attributes (`[data-part="option"][data-state="selected"]`, `[data-part="row"][data-pending]`), each shipped rule sits at **specificity 0** (`:where()`), so a plain selector of yours always wins, and `className`/`classes` take the same names (`classes={{ row: "bag-row", "line-total": "price" }}`). ⚑ **Style the controls at minimum** — `[data-part="control"]`/`[data-part="input"]` need `border`, `background`, `color: inherit`, `font: inherit`, `padding` and a focus ring, or the store ships browser-default white boxes. Space *between* sections is your containers' `gap`; the parts add no outer margins. Selector inventory, the geometry's custom properties (`--commerce-gap`, `--commerce-media-size`, `--commerce-field-columns`, …) and what else repays styling: [`../references/storefront-styling.md`](../references/storefront-styling.md).
+- **Words.** The copy file below, passed once on `StorefrontProvider labels`; override per Root or part with the same shape. A missing key renders a visible `⟨copy: path⟩` and warns — never silent, never English.
+- **Navigation — never rendered, never assumed.** A gate renders *your* element when the state calls for it (function children hand you the data); `OrderReceived.PaymentLink` hands `{ url }` to your element; `Checkout.Root` requires `orderReceivedPath`. Nothing assumes a route, or even an anchor.
+
+A section the props can't express drops to its hook — same shared state, mixing is safe: [`../references/storefront-custom.md`](../references/storefront-custom.md).
+
+### The copy file
+
+Copy this map into `src/copy.js`, then ⚑ **rewrite every value in this store's voice** — the English here is *reference*; shipped verbatim it is how storefronts end up sounding alike (`aria.*` name controls for screen readers; templates take the item's name):
+
+```js
+export const STORE_COPY = {
+  placeOrder: { label: "Place order", placing: "Placing your order…" },
+  blockers: {
+    empty_cart: "Your bag is empty.", billing_incomplete: "Fill in your details above.",
+    shipping_address_incomplete: "Finish the delivery address.",
+    shipping_address_required: "Enter your address to see delivery options.",
+    shipping_method_required: "Choose a delivery option.",
+    shipping_not_available: "We can't deliver to that address.",
+    payment_method_required: "Choose how you'd like to pay.",
+    cart_loading: "One moment — loading your bag.", shipping_recalculating: "Updating delivery costs…",
+  },
+  shipping: {
+    missing_address: "Delivery options appear once your address is entered.",
+    none_available: "We don't deliver to that address yet.",
+    syncing: "Updating delivery options…",
+  },
+  payment: { none_available: "Checkout is unavailable right now — please try again later." },
+  coupon: { placeholder: "Gift or promo code", apply: "Apply", remove: "Remove" },
+  fields: {
+    first_name: "First name", last_name: "Last name", email: "Email", company: "Company",
+    address_1: "Address", address_2: "Apartment, suite (optional)", country: "Country",
+    city: "City", state: "State / Province", postcode: "Postal code",
+    phone: "Phone (optional)", select_placeholder: "Select…",
+  },
+  totals: { subtotal: "Subtotal", discount: "Discount", shipping: "Shipping", tax: "Tax", total: "Total" },
+  bank: { account_name: "Account name", account_number: "Account number", bank_name: "Bank",
+          sort_code: "Sort code", iban: "IBAN", bic: "BIC" },
+  aria: {
+    trigger: "Open your bag", drawer: "Your bag", close: "Close",
+    increase: (name) => `Add one more ${name}`, decrease: (name) => `Remove one ${name}`,
+    remove: (name) => `Remove ${name} from your bag`,
+    shipping_group: "Delivery options", payment_group: "Payment methods",
+  },
+};
+```
 
-**Concentrate identity; don't diffuse it.** The classes carry the look everywhere; 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 classes. **The product page stays the storefront's richest surface**, and that richness is semantic: what the controls and rows *show*, which costs words rather than chrome. One navigation affordance per control (thumbnails *or* arrows, never both plus dots); checkout, bag and order-received are convention surfaces. Keep components small (~2–4K chars) — faster to emit, review and fix than one long page file.
+Blocker lines are what a disabled place-order button says — one per code, naming the thing the customer can fix (`cart_loading`/`shipping_recalculating` are quiet transients, not errors); `shipping.*`/`payment.*` are the pickers' dead-ends, with the server's own message rendered instead where one exists. The key tree is frozen in code as `REQUIRED_LABEL_KEYS`.
 
 ## What each hook resolves to
 
-Everything below is already unwrapped — no `.data`, no envelope. `formatMoney` throughout is `useFormatMoney()`.
+Everything below is already unwrapped — no `.data`, no envelope; `formatMoney` is `useFormatMoney()`. This table serves the catalog surfaces and row/option overrides; the custom-section shapes (`useCartLine`, `useCartUI`, `useCheckoutContext`, `useOrderReturn`, `cartTotalsLines`/`orderTotalsLines`) live in [`../references/storefront-custom.md`](../references/storefront-custom.md).
 
 | Call | Resolves to |
 |---|---|
@@ -93,13 +130,7 @@ Everything below is already unwrapped — no `.data`, no envelope. `formatMoney`
 | `productRibbons(product)` | `[{ id, name }]` — **objects**, and the field can be absent; takes a listing row or `useProduct().product`. |
 | `productSpecs(product)` | `[{ key, label, titleLabel, value }]` from `meta_data`; `findSpec(rows, key)` looks one up ignoring case/spaces/`_`/`-`. Never match on `label` — meta keys are free text. |
 | `useCart()` | `{ status, cart, itemCount, isEmpty, loading, error, mutationError, refresh, addItem, updateItem, removeItem, applyCoupon, removeCoupon }` — `status`: `"loading" \| "ready" \| "empty"`. |
-| `cart.items[n]` | `{ item_key, product_id, variation_id, name, quantity, price, subtotal, total, image, attributes, sold_individually, purchasable }` — `attributes` is an **array** of `{name, option}`; `purchasable` is a **result object** `{ok, code, error}`, not a boolean. |
-| `attributesLabel(item.attributes)` | `"Size: 42 · Color: Ivory"` (`""` when the product has no attributes). |
-| `cartTotalsLines(cart, { formatMoney })` | `[{ key, label, amount, formatted, hidden, emphasis }]` — every line the store has, incl. discount and tax. `orderTotalsLines(order, …)` is the same shape for a receipt. Pass `labels: {…}` to rename a row. |
-| `useCartLine(item)` | `{ quantity, setQuantity, increase, decrease, remove, pending, error, canIncrease, canDecrease, maxQuantity, atMax, atMin }`. |
-| `useCartUI()` | `{ open, openCart, closeCart, toggleCart }`. |
-| `useCheckoutContext()` | the address (`billing`, `updateBilling`, `shipping`, `updateShipping`, `shipToDifferent`, `setShipToDifferent`, `missingBillingFields`, `addressError`), the shipping and payment state (the pickers read those for you), and the gate: `blockers`, `canPlaceOrder`, `placing`, `stage`, `orderError`, `placeOrder` — plus `cart`. The Checkout section wires all of it. |
-| `useOrderReturn()` | `{ status, order, lines, paymentLink, paymentInstructions, error, reload }` — `status`: `"loading" \| "paid" \| "unpaid" \| "cancelled" \| "error"`. An order's totals are **flat** (`order.total`); there is no `order.totals`. |
+| `cart.items[n]` | `{ item_key, product_id, variation_id, name, slug, quantity, price, subtotal, total, image, attributes, sold_individually, purchasable }` — `attributes` is an **array** of `{name, option}` (`attributesLabel(item.attributes)` → `"Size: 42 · Color: Ivory"`); `purchasable` is a **result object** `{ok, code, error}`, not a boolean; `slug` is the line's product-page link. |
 
 ## Product list / collection
 
@@ -123,7 +154,7 @@ A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMo
 import { useProduct, useAddToCart, useStoreInfo, useFormatMoney, useStorefront, variantAxes, productImages, imageIndex, productRibbons, productSpecs, findSpec, storefrontErrorCode } from "@/commerce/storefront";
 ```
 
-`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 with "Rendered more hooks than during the previous render" the moment the product resolves.
+`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; a hook after an early `return` crashes React with "Rendered more hooks than during the previous render" the moment the product resolves.
 
 ```jsx
 const p = useProduct(slug);
@@ -175,183 +206,137 @@ Build your layout from — all optional, **not one component style**:
 - **Description** — `product.description` is HTML; render as rich text, `short_description` above it.
 - **Specs** — `productSpecs(product)` rows from the admin's *Modifiers*. ⚑ **Look a particular spec up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`. Meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. **This is the product page's signature-moment candidate**: pick the two or three keys that carry *this* catalog's meaning and render each as what it is (a weight as a figure, a composition as bars, a provenance beside its place), then let the rest fall through to plain rows in your classes. Not one uniform grey table; not a bespoke widget per row. `[]` means no section at all.
 - **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
-- **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`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
-- **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
+- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards: an average of nothing is `0`). `p.reviews` arrives with the product; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to auto-approving stores — and refresh the list after. Policies and moderation: [`../references/reviews.md`](../references/reviews.md).
+- **Title** — give each page type its own `<title>` and description; one static title everywhere is invisible to search. No structured data ships — for rich results emit your own `Product`/`Offer` JSON-LD from `product` and `view.display`.
 
 ## Cart / bag
 
 ```jsx
-import { useCart, useCartLine, CartLine, useCartUI, useFormatMoney, attributesLabel, cartTotalsLines } from "@/commerce/storefront";
+import { Cart, CartDrawer } from "@/commerce/storefront";
 ```
 
-A cart *page* is optional — decide from what the store sells (buy-now straight to checkout reads better for a single-piece store; a grocery basket needs a page).
-
-⚑ Rules: branch on `status`, never on emptiness while loading. Render `cart.coupon_notices` (`[{ code, error, error_code }]` — a coupon that stopped validating) and `cart.removed_items` (`[{ item_key, product_id, reason, code }]` — a product that vanished or was unpublished): render `error`/`reason`, the server's own words, or a line disappears from the bag with no explanation. Render every non-`hidden` line from `cartTotalsLines` 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) — they are admin-only data, redeemable only through a field the customer types into. `applyCoupon(code)` resolves `{ok: false, message}` for a bad code rather than throwing, so render that inline. No field means no coupons: don't seed them, don't name a code 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** for one row — the rest of the page (notices, coupon field, totals, checkout link) is ordinary markup around it:
+A cart *page* is optional — decide from what the store sells (buy-now-to-checkout suits a single-piece store; a grocery basket needs a page). Page or drawer, the same parts in your layout — here as a drawer (`<CartUIProvider>`, mounted in Setup, owns open/close, Esc, open-on-add, close-on-navigate; a page skips the `CartDrawer.*` wrapper and provider):
 
 ```jsx
-const { status, cart } = useCart();
-const formatMoney = useFormatMoney();
-// guards on status first, then:
-{cart.items.map((item) => (
-  <CartLine key={item.item_key} line={item}>
-    {(l) => (
-      <li aria-busy={l.pending}>          {/* busy scope is THIS row, never the cart */}
-        {item.name} {attributesLabel(item.attributes)} {formatMoney(item.total)}
-        <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
-                aria-label={`Decrease quantity of ${item.name}`}>−</button>
-        {l.quantity}
-        <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
-                aria-label={`Increase quantity of ${item.name}`}>+</button>
-        <button onClick={l.remove} disabled={l.pending}
-                aria-label={`Remove ${item.name}`}>Remove</button>
-        {l.error && <p role="alert">{l.error.message}</p>}
-      </li>
-    )}
-  </CartLine>
-))}
-{cartTotalsLines(cart, { formatMoney }).filter((t) => !t.hidden).map((t) => (
-  <div key={t.key}>{t.label} {t.formatted}</div>       /* t.emphasis → the total row */
-))}
+<header>{/* your nav */}
+  <CartDrawer.Trigger className="nav-icon">
+    {({ count }) => (<><YourBagGlyph />{count > 0 && <span className="badge">{count}</span>}</>)}
+  </CartDrawer.Trigger>
+</header>
+
+<CartDrawer.Panel className="drawer">
+  <header>{/* your title */}<CartDrawer.Close><YourXGlyph /></CartDrawer.Close></header>
+  <Cart.Empty>{/* your empty state + your own link back into the shop */}</Cart.Empty>
+  <Cart.Ready>
+    <Cart.Notices />
+    <Cart.Lines classes={{ row: "bag-row", media: "bag-thumb" }} />
+    <Cart.CouponField />
+    <Cart.Totals pick={["subtotal"]} />
+    {/* your checkout affordance — your element, your route */}
+  </Cart.Ready>
+</CartDrawer.Panel>
 ```
 
-No shipping estimator here — checkout reprices shipping and tax from the address. An upsell beside the lines needs no query: `p.upsells` / `p.crossSells` from `useProduct` are rows you can render and add with `addItem`, matching "already in the bag" by product id, never by display name. ⚑ **A one-click Add only works on a product with no attributes**: one that sells variants answers `400 variation_required`, so link those tiles to the product page instead.
-
-### If the cart is a drawer
+| Part | Renders | Props |
+|---|---|---|
+| `Cart.Loading` / `Empty` / `Ready` | gates — children only in that cart status, so emptiness-while-loading can't render; function children get `{ cart, itemCount }` | — |
+| `Cart.Lines` | the rows: media, name, attributes, stepper (optimistic, coalesces clicks, rolls back — busy scoped to **that row**, never the cart), remove, line total, per-row errors in the server's words | `lineRender(item, l)` replaces a row — `item.slug` for your product link |
+| `Cart.Notices` | expired coupons + vanished products, the server's words — a line never disappears unexplained | — |
+| `Cart.CouponField` | input + apply + applied codes with remove; an invalid code renders inline | — |
+| `Cart.Totals` | every non-hidden summary line, discount and tax included, `data-emphasis` on the total | `pick={["subtotal"]}` |
+| `CartDrawer.Trigger/Panel/Close` | the wired header button (render prop gets `{ count, open }`); the dialog done right — click-away overlay (never the close control), focus in/restored, unmounted while closed (`keepMounted` to animate → the closed panel goes `inert`); the named close button | children; `keepMounted` |
 
-Same hooks, same rows. The drawer's *state* — open/close, Esc, close-on-route-change, open-on-add — is `useCartUI()`; the markup is yours: a trigger in the header (`onClick={ui.toggleCart}`, `aria-expanded={ui.open}`), then `{ui.open && …}` rendering a click-away overlay plus your panel (`role="dialog" aria-modal="true"`, a named close button inside it).
-
-⚑ **Render the drawer conditionally — `{ui.open && …}`.** 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, set the `inert` attribute while closed. The overlay is a click-away surface, not the close control.
+⚑ **A store with any coupons places `CouponField` once** (cart or checkout) — codes are redeemable only through a field; no field → don't seed codes. **Upsells**: `useProduct().upsells` rows added via `useCart().addItem`, matched by product id — ⚑ one-click add only for a product with no attributes (others answer `400 variation_required`; link those tiles to the product page). Drawer position, width and motion are your CSS on `[data-part="panel"]` / `[data-state]`.
 
 ## Checkout
 
 ```jsx
-import { CheckoutProvider, useCheckoutContext, ShippingMethodPicker, PaymentMethodPicker, useCart, useCountries, useFormatMoney, cartTotalsLines, addressFieldSpec, REQUIRED_BILLING_FIELDS } from "@/commerce/storefront";
+import { Checkout } from "@/commerce/storefront";
 ```
 
-`useCheckout` 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** (`<CheckoutProvider options={{ orderReceivedPath: null }}>` for a router transition instead). `CheckoutProvider` shares it across the page's regions.
-
-⚑ 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". Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
-
-⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` (bag is empty) · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (this address can't be delivered to) · `payment_method_required` (choose how to pay) · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
-
-The pickers' `hint.code` works the same way (`missing_address`, `none_available`, `syncing` for shipping; `none_available` for payment): write those words once, and prefer `hint.serverMessage` when it is set — the backend's explanation is more specific than anything you can write.
+`Checkout.Root` mounts the guided state — address edits reprice shipping/tax automatically (debounced, never on a half-typed address), choices derive from store data — and resolves the page's phase: `Submitted` renders above everything (placing an order clears the bag; this ordering kills the empty-bag flash over a just-placed order), then `Loading` / `Empty` / `Form`.
 
-**Reference wiring** — the densest part of the storefront. `Checkout()` is just
-`<CheckoutProvider><CheckoutForm /></CheckoutProvider>`; the hooks read the context **below** the provider. `SHIPPING_HINTS`, `PAYMENT_HINTS`, `BLOCKERS` and the two button labels below are *your* copy maps, written once (see [Design language](#design-language--once-before-any-page)):
+⚑ **`orderReceivedPath` is required** — pass the route *your* order-received page is mounted at; the kit assumes none. The landing is a **full page load** by design (the provider hop leaves the app; the receipt boots from the URL alone — a browser script must navigate fresh to it, not wait for a transition). `null` + `onPlaced(result)` hands the step to you.
 
 ```jsx
-function CheckoutForm() {
-  const { status } = useCart();
-  const c = useCheckoutContext();
-  if (c.stage === "submitted") return /* "taking you to your receipt" screen */;
-  if (status === "loading") return /* your loading screen */;
-  if (status === "empty")   return /* your empty-bag screen */;
-  return (
-    <>
-      <AddressFields which="billing" />
-      {/* a checkbox on c.shipToDifferent / c.setShipToDifferent, your wording */}
-      {c.shipToDifferent && <AddressFields which="shipping" />}
-
-      <ShippingMethodPicker>
-        {({ hint, mustChoose, methods, chosen }) => (
-          <fieldset>{/* renders null for a virtual cart */}
-            {hint && <p role={hint.severity === "error" ? "alert" : "status"}>
-              {hint.serverMessage ?? SHIPPING_HINTS[hint.code]}</p>}
-            {mustChoose && methods.map((m) => (
-              <label key={m.id}>
-                <input type="radio" name="shipping-method" checked={m.selected} onChange={m.select} />
-                {m.title} {m.costLabel}
-              </label>
-            ))}
-            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
-          </fieldset>
-        )}
-      </ShippingMethodPicker>
-
-      {/* PaymentMethodPicker: same shape — hint, then gateways.map radios unless
-          `single`, then `selected.title`. Titles/descriptions are the admin's copy. */}
-
-      {/* summary: coupon field (if not in the cart) + cartTotalsLines(c.cart, { formatMoney }) */}
-
-      <button type="button" onClick={c.placeOrder} disabled={!c.canPlaceOrder || c.placing}>
-        {c.placing ? PLACING_LABEL : PLACE_ORDER_LABEL}
-      </button>
-      {c.orderError && <p role="alert">{c.orderError.message}</p>}
-      {!c.canPlaceOrder && c.blockers.map((code) => <p key={code}>{BLOCKERS[code]}</p>)}
-    </>
-  );
-}
-
-function AddressFields({ which }) {
-  const c = useCheckoutContext();
-  const { countries } = useCountries();     // [] until store info lands — never null
-  const isBilling = which === "billing";
-  const values = isBilling ? c.billing : c.shipping;
-  const set = isBilling ? c.updateBilling : c.updateShipping;
-  const fields = addressFieldSpec({
-    countries,
-    country: values.country,
-    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
-    includeEmail: isBilling,                // one email per order, on billing
-  });
-  return fields.map((f) => (
-    <div key={f.key}>
-      <label htmlFor={`${which}-${f.key}`}>{f.label}{f.required && " *"}</label>
-      {f.type === "select" ? (
-        <select id={`${which}-${f.key}`} value={values[f.key] ?? ""} autoComplete={f.autoComplete}
-                onChange={(e) => set({ [f.key]: e.target.value })}>
-          <option value="">{/* your placeholder */}</option>
-          {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
-        </select>
-      ) : (
-        <input id={`${which}-${f.key}`} type={f.type} value={values[f.key] ?? ""}
-               autoComplete={f.autoComplete} onChange={(e) => set({ [f.key]: e.target.value })} />
-      )}
-      {/* "we don't ship there" is an address-level error — it belongs on country */}
-      {f.key === "country" && c.addressError && <span role="alert">{c.addressError.message}</span>}
+<Checkout.Root orderReceivedPath="/order-received">
+  <Checkout.Submitted>{/* your "taking you to your receipt…" screen */}</Checkout.Submitted>
+  <Checkout.Loading>{/* your loader */}</Checkout.Loading>
+  <Checkout.Empty>{/* your empty state + your own link back */}</Checkout.Empty>
+  <Checkout.Form>
+    <div className="checkout-grid">{/* YOUR layout: order, columns, headings, steps */}
+      <section>
+        <Checkout.AddressFields which="billing" />
+        <Checkout.ShipToDifferent>{/* your label */}</Checkout.ShipToDifferent>
+        <Checkout.AddressFields which="shipping" />
+        <Checkout.ShippingMethods />
+        <Checkout.PaymentMethods />
+      </section>
+      <aside>
+        <Checkout.Items />
+        <Checkout.CouponField />
+        <Checkout.Totals />
+        <Checkout.PlaceOrder className="btn-cta" />
+      </aside>
     </div>
-  ));
-}
+  </Checkout.Form>
+</Checkout.Root>
 ```
 
-⚑ **Passing `country` is what makes the state/province field appear**, with the right options for the US, Canada and Australia — and shipping rates and taxes match on country *plus* state, so a form without that field mis-prices those orders with no error anywhere. ⚑ Keep each field's `autoComplete` token; it is what makes browser autofill work. Labels are plain conventions — rename or restyle freely. `c.missingBillingFields` is the live list of what is still missing, if you want per-field marks; arm them on first edit, not on load.
-
-⚑ **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 an empty bag over a just-placed order.
+| Part | Renders | Props |
+|---|---|---|
+| `Checkout.Root` | the provider, the phase, the labels scope | `orderReceivedPath` (**required**; or `null` + `onPlaced`), `labels`, `options`, `checkout` |
+| `Submitted` / `Loading` / `Empty` / `Form` | gates; function children get `{ checkout, cart }` | — |
+| `AddressFields` | the spec-driven fields: state/province appears once a country is picked (rates and taxes match on country *plus* state — its absence silently mis-prices US/CA/AU orders); `autoComplete` on; required marks arm on blur; "we don't ship there" lands on country; `which="shipping"` renders only when toggled | `which`, `include={["company"]}`, `omit`, `inputRender`, `fieldRender` |
+| `ShipToDifferent` | the wired toggle; children are its label | children |
+| `ShippingMethods` | every branch: the hint line (server's message preferred over yours), a radio list while there is a real choice, the single/auto-selected option *displayed* — never a picker of one, never "nothing selected" — null for a virtual cart | `optionRender(m)` — option content; the radio stays wired |
+| `PaymentMethods` | every **enabled** gateway from store info, titles/descriptions in the admin's words (a default store offers `offline` only — never hardcode a card option); one renders as the selection it is; none renders your unavailable line | `optionRender(g)` |
+| `Items` | the read-only mini summary | `itemRender(item)` |
+| `CouponField` / `Totals` | same parts as the cart's | — / `pick` |
+| `PlaceOrder` | the button (your two labels), the server's order error, and the blocker lines — ⚑ a disabled button always says why | `showBlockers` (default true) |
+| `Blockers` | the reasons alone, for custom placement (then `showBlockers={false}`) | — |
+
+`inputRender` is the middle tier when the fields need your own control — more authored code, more styled: `({ field, id, value, onChange, onBlur, invalid, autoComplete, options }) => <YourField …/>`; `fieldRender` replaces the whole labeled block. **Multi-step checkout is your markup**: wrap parts in your step containers — a hidden step loses nothing, the gate still counts every blocker.
 
 ## Order received
 
 ```jsx
-import { useOrderReturn, useFormatMoney, orderTotalsLines } from "@/commerce/storefront";
+import { OrderReceived } from "@/commerce/storefront";
 ```
 
-**Mandatory route** — every payment link returns here, and confirming is what marks a card order paid. `useOrderReturn()` reads `order_id`/`order_key` from the URL, verifies with the provider (idempotent on every visit), and marks the page noindex itself.
-
-⚑ Rules: render all five states — never a blank page while `"loading"`, a retry via `reload()` on `"error"`, and `paymentLink.url` on `"unpaid"`/`"cancelled"` when present. ⚑ **Never drop `paymentInstructions`** (`{ description, account_details }`) — a manual/offline order settles outside the store, so these ARE how the store's default customer learns how to pay. ⚑ An order's totals are flat (`order.total`, no `order.totals`) — use `orderTotalsLines(order, { formatMoney })`. `lines` are the order's items already normalized (`name`, `attributesLabel`, `quantity`, `image` as `{src, alt}|null`, `totalLabel`), because a receipt reusing cart-row markup otherwise paints a broken image.
+**Mandatory route** — every payment link returns here; visiting verifies with the provider (idempotent) and the page marks itself noindex. ⚑ Render **all five** gates — a blank frame while loading or a wordless error strands a real customer:
 
-A receipt is a convention surface: your classes, every branch present, no bespoke widgets.
+```jsx
+<OrderReceived.Root>
+  <OrderReceived.Loading>{/* confirming copy — never a blank page */}</OrderReceived.Loading>
+  <OrderReceived.Paid>
+    {({ order }) => (<>{/* your thank-you, order #{order.order_number} */}
+      <OrderReceived.Items /><OrderReceived.Totals /></>)}
+  </OrderReceived.Paid>
+  <OrderReceived.Unpaid>{/* your wording for "not settled yet" */}
+    <OrderReceived.PaymentInstructions />   {/* ⚑ see below */}
+    <OrderReceived.PaymentLink>{({ url }) => (/* your pay-now element on url */)}</OrderReceived.PaymentLink>
+    <OrderReceived.Items /><OrderReceived.Totals />
+  </OrderReceived.Unpaid>
+  <OrderReceived.Cancelled>{/* your wording; PaymentLink works here too */}</OrderReceived.Cancelled>
+  <OrderReceived.Error>{({ error, reload }) => (/* error.message + your retry calling reload() */)}</OrderReceived.Error>
+</OrderReceived.Root>
+```
 
-## Driving the storefront from a browser script?
+⚑ **`PaymentInstructions` goes on the unpaid branch.** A default-seeded store settles manually (bank transfer, cash on delivery), so the instructions ARE how its customers pay — a receipt without them strands every real order. It renders the admin's description plus account details (your `bank.*` labels); null for card orders. `PaymentLink` renders your element only when a live link exists; the gates' function children get `{ order, paymentLink, paymentInstructions, error, reload }` for anything custom. `Items` rows arrive normalized; `Totals` owns the flat-totals trap (`order.total`, never `order.totals`).
 
-The cart is optimistic and debounced, so a script that acts faster than it settles sees a working store as broken. Read [`../references/storefront-verification.md`](../references/storefront-verification.md) **before** writing the script — not after it fails.
+**Driving the storefront from a browser script?** The cart is optimistic and debounced, so a script that acts faster than it 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 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.
-- [ ] **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; no unused names.
-- [ ] Pages branch on `status`; gateways/currency/countries read from `useStoreInfo()`/`useCountries()` only.
-- [ ] Every state the hooks expose has words: the buy button reads for all four `buy.state` values, picker `hint` codes and place-order `blockers` each have a line, and no state renders empty.
-- [ ] No re-implemented hook logic (button state precedence, quantity clamps, totals math, drawer state).
-- [ ] Coupon field present if the store has coupons; a paging control rendered whenever `hasNext` is true; ribbons rendered in both the grid and the product page.
+- [ ] Catalog UI in whatever form fits the store; cart (and/or drawer), checkout and `/order-received` built from the parts — all five receipt gates present, `PaymentInstructions` placed on unpaid.
+- [ ] One copy file passed via `<StorefrontProvider labels={…}>`, **every value rewritten in the store's voice** — no `⟨copy: …⟩` on any page, no reference-example sentence shipped verbatim; the buy button reads for all four `buy.state` values.
+- [ ] `index.css` defines the design classes; parts styled via `[data-part]`/`classes` — **controls carry border/background/font/padding + a focus ring**, option rows show their selected state, the drawer panel has a surface, nothing left browser-default; pages carry class names, not repeated utility runs.
+- [ ] **One** `<StorefrontProvider>` above every storefront route (layout-route pattern); no hand-rolled `cart_token`; imports from each section's import line.
+- [ ] Custom hook-built sections branch on `status` and never re-implement part/hook logic; gateways/currency/countries from `useStoreInfo()`/`useCountries()` only.
+- [ ] Coupon field placed if the store has coupons; a paging control whenever `hasNext`; ribbons in both the grid and the product page.
 - [ ] Variant options: one control per axis, unbuyable options disabled, not hidden.
-- [ ] Address form includes the state/province field and every `autoComplete` token.
-- [ ] 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`.
-- [ ] Checkout guards `stage === "submitted"` above its empty-cart branch.
-- [ ] The storefront carries the design you settled on before reading this file — design classes plus one or two signature moments per page; axes and specs rendered by what they are (not one uniform table, not one identical chip row); convention surfaces carry the classes and nothing bespoke.
+- [ ] Navigation affordances are yours: the checkout link in `Cart.Ready`, `orderReceivedPath` on `Checkout.Root`, `PaymentLink`'s child — the kit rendered none of them.
+- [ ] The storefront carries the design you settled on before reading this file — design classes plus one or two signature moments per page; the product page stays the richest surface.
 
-Then copy this file's `carry_forward` lines (in its front matter) into your working notes, and do not re-read this file.
+Then copy this file's `carry_forward` lines into your working notes, and do not re-read this file.