@base44/app-plugin-commerce 0.2.6 → 0.2.7

package/README.md

@@ -12,7 +12,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` normalizes catalog images; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
-- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useAddToCartButton`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). Needs React and nothing else.
+- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -47,15 +47,19 @@ moments. Read nothing else up front.
 
 **The UI is yours, all of it** — every page, element, class and word of copy.
 The kit deliberately ships **no markup and no CSS anywhere**; a brief like
-"make it feel like <site>" is your work, done as you would with no kit.
+"make it feel like <site>" is your work, done as you would with no kit. Encode
+that identity **once** — design classes in `index.css`, spent across every
+page — not as decoration re-typed on every element;
+[`install/02-storefront.md`](./install/02-storefront.md) opens with the
+method.
 
 **The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
 repricing, variant resolution, cart state, coupons, reviews, order-return
-verification, cart-drawer mechanics. Each returns a complete view-model
-(`status` to branch on, ready-to-map arrays, handlers) **plus ready-to-spread
-prop sets** (`inputProps`, `radioProps`, `buttonProps`, `panelProps`) that
-carry the wiring, so your markup is elements and classes. **Never re-implement
-what a hook does** — that is where storefront bugs cluster.
+verification, cart-drawer state. Each returns a complete view-model as **plain
+states and handlers** (`status` to branch on, ready-to-map arrays, `label`s
+and `disabled` flags, callbacks) — you write every element and attribute from
+them. **Never re-implement what a hook does** — that is where storefront bugs
+cluster.
 
 ```jsx
 import { useCart, CartLine } from "@/commerce/storefront";

package/skills/commerce/docs/api-storefront.md

@@ -2,7 +2,7 @@
 
 The raw HTTP/SDK surface behind a customer-facing shopfront. **A React storefront should not call most of it directly** — `src/commerce/storefront/` ships the logic layer, and this file is the reference for what lies beyond it, for non-React and headless clients, and for the exact payloads and error codes.
 
-**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCartButton`, `useProductSpecs`, `useUpsell`), `useCart`/`useCartLine`/`useCoupon`/`useCartUI` (+ `CartUIProvider`), `useCheckout`/`usePlaceOrder` (+ `useAddressForm`, the pickers and prop-getters), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
+**Logic is premade, UI never is.** In a React app, every surface here has a headless hook in `@/commerce/storefront` — `useProductList`, `useProduct` (+ `variantAxes`, `useAddToCart`, `useProductSpecs`, `useUpsell`), `useCart`/`useCartLine`/`useCoupon`/`useCartUI` (+ `CartUIProvider`), `useCheckout`/`usePlaceOrder` (+ `useAddressForm` and the pickers), `useOrderReturn`, `useProductReviews`, `useStorefrontSeo`. The hooks own the API calls and the branching below and hand you a view-model; **all markup and styling are yours** — nothing in the kit renders UI. Never hand-roll a hook's logic. Framework-free helpers (API client, variant resolution, price and totals rules, free-shipping rules) live in `src/commerce/utils/`.
 
 Entities and direct CRUD → [`entities.md`](./entities.md) · admin surface → [`api-admin.md`](./api-admin.md)
 
@@ -94,7 +94,7 @@ await cat({ category_id, sort: "popularity", per_page: 4 });    // top in catego
 ```
 **Errors:** `404 not_found` (missing / not published / hidden).
 
-> **`variations[]` is not a list of choices to show** — variant rule 1 applies, and variant prices come from `variations[]`, never `product.price` (a rolled-up from-price). React: `useProduct` + `useAddToCartButton`. The non-React resolver sample (`resolveSelection` from `@/commerce/utils`) and the variant deep-dive: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+> **`variations[]` is not a list of choices to show** — variant rule 1 applies, and variant prices come from `variations[]`, never `product.price` (a rolled-up from-price). React: `useProduct` + `useAddToCart`. The non-React resolver sample (`resolveSelection` from `@/commerce/utils`) and the variant deep-dive: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
 ### `list-categories`
 No payload. Returns a nested tree: `{ "categories": [ { ...category, "children": [...] } ] }` sorted by `menu_order` then name.

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

@@ -10,16 +10,17 @@ carry_forward:
   - "Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
   - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
   - "Every hook on a page goes above its status guards — a hook after an early return crashes with \"Rendered more hooks than during the previous render\"."
-  - "Spread the hook's prop set (inputProps, radioProps, buttonProps, panelProps, moreProps) and add className — never assemble those attributes by hand."
+  - "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.** The hooks own checkout repricing, variant resolution, cart state, coupon redemption, review policies, order-return verification — hand-writing any of it is where storefront bugs cluster, so **never re-implement what a hook does**. Every element, class, layout and word of copy is yours; nothing in `@/commerce/storefront` renders markup or carries CSS. **Decide how the store looks as if this kit did not exist**, then use this file for how to wire it — the snippets below are implementation reference, not design input.
+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:
 
-- **Prop sets, not hand-assembled attributes.** Hooks return ready-to-spread objects — `f.inputProps`, `m.radioProps`, `buy.buttonProps`, `ui.panelProps`, `list.moreProps` — carrying the handlers, ids, aria wiring and disabled logic. Spread first, put your `className` after; writing `value`/`onChange`/`autoComplete` yourself means re-deriving what a prop set already holds.
+- **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.)
@@ -56,6 +57,52 @@ import AdminApp from "@/commerce/admin";
 
 ⚑ **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`.
 
+## Design language — once, before any page
+
+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:
+
+  ```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>} />;
+  ```
+
+  ⚑ 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
 
 ```jsx
@@ -69,21 +116,21 @@ 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() */;
+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
 ```
 
-`useProductList(params)` → `{ status, products, hasNext, moreProps, refreshing, setParams, reload }`. ⚑ `status` is `"loading" | "ready" | "empty" | "error"` — branch on it, so a failed request renders as a failure instead of an empty grid. `setParams({ category_id, search, on_sale, in_stock_only, … })` resets to page 1 and keeps current rows on screen (`refreshing`). ⚑ **Render `<button {...list.moreProps}>Load more</button>`** (or "Next") — it hides itself on the last page; a page that renders nothing for paging ships a catalog silently capped at `per_page`. `useCategories()` / `useRibbons()` → `{ items }` — drive filters from that data, never from hardcoded names (a renamed ribbon must not strand a dead button).
+`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: give the grid a rhythm and lead each card with the one or two fields *these* products are judged on (via `productSpecs`), not the name/price/stars trio every generated store ships.
+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, useProductSpecs, useStoreInfo, useStorefrontSeo, productSeo, variantAxes } from "@/commerce/storefront";
+import { useProduct, useProductGallery, useAddToCart, useProductSpecs, useStoreInfo, useStorefrontSeo, productSeo, variantAxes } from "@/commerce/storefront";
 ```
 
 (Add `useProductReviews` only if the store has reviews; drop `useProductSpecs` if these products carry no modifiers.)
@@ -93,13 +140,13 @@ import { useProduct, useProductGallery, useAddToCartButton, useProductSpecs, use
 ```jsx
 const p = useProduct(slug);
 const g = useProductGallery(p.product, p.view);
-const buy = useAddToCartButton(p, { labels: { ready: "Add to 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;
 ```
 
@@ -107,7 +154,7 @@ Build your layout from — all optional, each one hook, **not one component styl
 
 - **Price** — `price.label`, plus `price.compareAtLabel` (struck through) when on sale. Never read `product.price` directly — the parent's price is a rolled-up from-price.
 - **Gallery** — `g` → `{ hasImages, images, active, activeIndex, setActiveIndex, next, prev }`. The active image follows the variant selection; `hasImages: false` means render your placeholder.
-- **Variant selector** — `variantAxes(view, p.pick)` → one entry per axis: `{ key, name, selectedOption, options: [{ value, selected, disabled, outOfStock, pick }] }`. ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. The shape of the map (the control itself is yours — swatches for a colour axis, chips with a size guide for a size axis; every axis as the identical chip row is a generated-page tell):
+- **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) => (
@@ -121,9 +168,9 @@ Build your layout from — all optional, each one hook, **not one component styl
   ))}
   ```
 
-- **Buy box** — `<button {...buy.buttonProps}>{buy.label}</button>` is the whole button: gate, busy state and the ready/adding/sold-out/needs-selection precedence are inside (`buy.state`; override copy via `labels`). ⚑ Render `buy.error.message` inline; ⚑ `buy.showQuantity: false` means no stepper (`increase`/`decrease`/`canIncrease` drive one when true). With `<CartUIProvider>` mounted, a successful add opens the drawer by itself.
+- **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. ⚑ **Don't `.map()` everything into one uniform label/value table** — branch on `type` (or `key`) for the two or three specs that carry *this* product's meaning; `[]` means no section at all.
+- **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
@@ -148,8 +195,8 @@ A cart *page* is optional (buy-now straight to checkout reads better for a singl
 function Bag() {
   const { status, lines, notices } = useCart();
   const totals = useTotalsLines();
-  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>)}
@@ -185,25 +232,28 @@ No shipping estimator here — checkout reprices shipping and tax from the addre
 
 ### If the cart is a drawer
 
-Same hooks, same rows. The drawer's *machinery* — close-on-route-change, inert-when-closed, dialog semantics, Esc, focus, open-on-add — is `useCartUI`, and hand-writing any of it is how drawers break (invisible-but-clickable controls, a drawer hanging over the checkout):
+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
 function StoreLayout() {           // inside <CartUIProvider> (see Setup)
   const ui = useCartUI();
   const { itemCount } = useCart();
   return (<>
-    <header>… <button {...ui.triggerProps} className="…">Bag ({itemCount})</button></header>
+    <header>… <button type="button" onClick={ui.toggleCart} aria-expanded={ui.open}
+                      className="…">Bag ({itemCount})</button></header>
     <Outlet />
-    <div {...ui.overlayProps} className={ui.open ? "…" : "hidden"} />
-    <aside {...ui.panelProps} className={ui.open ? "… translate-x-0" : "… translate-x-full"}>
-      <button {...ui.closeButtonProps} className="…">×</button>
-      {/* your rows: useCart + CartLine, as above */}
-    </aside>
+    {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>
+    </>)}
   </>);
 }
 ```
 
-⚑ Keep the panel mounted and animate with classes — `panelProps` makes it inert while closed, which is what an off-screen drawer needs and `aria-hidden` alone does not provide. The overlay is not a second close control; the named close button is `closeButtonProps`.
+⚑ **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
 
@@ -215,7 +265,7 @@ import { CheckoutProvider, useCheckoutContext, usePlaceOrder, useAddressForm, Sh
 
 The state machine is `useCheckout`, shared across the page's regions by `CheckoutProvider`. It reprices shipping/tax from the address automatically (debounced, never on a half-typed address), derives the shipping and payment choices, gates the button, and `placeOrder()` handles **both** navigations — online gateway → provider redirect, everything else → `/order-received` — as **full page loads** (pass `orderReceivedPath: null` for a router transition; see `useCheckout`'s JSDoc).
 
-⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected"; keep each field's spread props intact (they carry `autoComplete` and the error wiring — "we don't ship there" arrives on the country field); render the gate's `error` and `blockers` so a disabled button explains itself. ⚑ Payment methods, currency and countries come from `useStoreInfo()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only.
+⚑ 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:
 
@@ -228,9 +278,9 @@ function CheckoutForm() {
   const { status } = useCart();
   const checkout = useCheckoutContext();
   const order = usePlaceOrder();
-  if (order.stage === "submitted") return /* "order placed — taking you to your receipt…" */;
-  if (status === "loading") return /* loading */;
-  if (status === "empty")   return /* "your bag is empty" */;
+  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" />
@@ -246,7 +296,10 @@ function CheckoutForm() {
           <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} {...m.labelProps}><input {...m.radioProps} /> {m.title} {m.costLabel}</label>
+              <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>
@@ -258,7 +311,10 @@ function CheckoutForm() {
           <fieldset>
             {hint && <p role="alert">{hint.message}</p>}
             {!single && gateways.map((g) => (
-              <label key={g.slug} {...g.labelProps}><input {...g.radioProps} /> {g.title} {g.description}</label>
+              <label key={g.slug}>
+                <input type="radio" name="payment-method" checked={g.selected} onChange={g.select} />
+                {g.title} {g.description}
+              </label>
             ))}
             {single && selected && <p>{selected.title}</p>}
           </fieldset>
@@ -267,8 +323,8 @@ function CheckoutForm() {
 
       {/* summary: coupon field (if not in the cart) + useTotalsLines(), as in the cart page */}
 
-      <button {...order.buttonProps}>{order.label}</button>
-      {order.error && <p {...order.errorProps}>{order.error.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>)}
     </>
   );
@@ -278,14 +334,14 @@ function AddressFields({ which }) {
   const { fields } = useAddressForm(which);
   return fields.map((f) => (
     <div key={f.key}>
-      <label {...f.labelProps}>{f.label}{f.required && " *"}</label>
+      <label htmlFor={f.id}>{f.label}{f.required && " *"}</label>
       {f.isSelect ? (
-        <select {...f.selectProps}>
+        <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 {...f.inputProps} />}
-      {f.error && <span {...f.errorProps}>{f.error}</span>}
+      ) : <input id={f.id} type={f.type} value={f.value} onChange={f.set} autoComplete={f.autoComplete} />}
+      {f.error && <span role="alert">{f.error}</span>}
     </div>
   ));
 }
@@ -309,9 +365,9 @@ import { useOrderReturn, useTotalsLines } from "@/commerce/storefront";
 function OrderReceived() {
   const { status, order, lines, paymentLink, paymentInstructions, error, reload } = useOrderReturn();
   const totals = useTotalsLines(order);
-  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 */}
@@ -344,7 +400,7 @@ useStorefrontSeo(collectionSeo({ title, products: list.products }));      // col
 
 The `*Seo` builders tolerate a null product, so this sits with the other hooks above the status guards.
 
-## Per-page output budgets
+## Per-page output budgets — measured, not aspirational
 
 | Page | budget (chars) |
 |---|---|
@@ -353,10 +409,19 @@ The `*Seo` builders tolerate a null product, so this sits with the other hooks a
 | Order-received | ≤ 2.5K |
 | Product page | ≤ 5K |
 | Collection | ≤ 3K |
-| Home | ≤ 5K — pure identity; hero/editorial earn their chars |
+| Home | ≤ 5K — identity lives in the hero + one editorial moment, in your classes |
 | Any single component file | ≤ 4K, hard ceiling 8K |
 
-These budgets assume the hooks carry the logic and your markup carries only the design. Over budget ⇒ you are re-implementing something a hook or a prop set already does (an address field's attributes, a quantity clamp, totals math, drawer state) — go back to the hook and delete your version. Design detail is not what pushes a page over.
+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?
 
@@ -365,16 +430,17 @@ The hooks are optimistic and debounced, so a script that acts faster than the ca
 ## 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; 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.
-- [ ] Prop sets spread wherever one exists — no hand-assembled `value`/`onChange`/`autoComplete`/radio/drawer wiring, no re-implemented hook logic.
-- [ ] Coupon field present if the store has coupons; paging rendered via `moreProps`.
+- [ ] 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` (inert when closed, closes on route change).
+- [ ] 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 — no page ships the reference snippets' bare structure; specs and axes are rendered by what they are, not one uniform table and one identical chip row.
-- [ ] Every page is within its budget above.
+- [ ] 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.
 
@@ -384,4 +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".
-- Spread the hook's prop set (`inputProps`, `radioProps`, `buttonProps`, `panelProps`, `moreProps`) and add `className` — never assemble those attributes by hand.
+- 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.

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

@@ -62,7 +62,7 @@ Both lists below are field inventories — what the data supports — **not a la
 
 **Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`). Link the whole card to the product page; the layout is yours.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
 
 **Attributes and modifiers are individually designable.** `productSpecs` rows carry `key`/`label`/`titleLabel` (display-cased) plus an inferred `type` (`numeric` with `number`/`unit` split out, `duration`, `location`, `list` with `items`, `text`); `useProductSpecs(product, { pick })` is the React wrapper, its get/pick case/underscore-insensitive. Branch on `type`/`key` instead of mapping everything into one uniform chip row per axis and one grey label/value table — the design guidance is [`../install/02-storefront.md`](../install/02-storefront.md)'s; §5's rules govern selector *behaviour*, never its form.
 
@@ -99,7 +99,7 @@ Three decisions the helpers can't make for you:
 
 **Attributes but no usable variations** — what attaching an attribute and stopping leaves behind — deliberately gets no parent fallback, because `add-item` would reject it: empty `axes[].options`, `purchasable: false`, `addToCart: null`. Render it as unavailable rather than painting empty selector groups, and guard the label (with no attributes at all `missingAxes[0]?.name` is `undefined` → "Select a undefined").
 
-**Add to cart** goes through `useAddToCart()`, which never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → `shouldReload: true`, refetch). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
+**Add to cart** goes through `useAddToCart(product)`, whose `addToCart()` never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → the hook reloads the product itself). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
 
 ## 6. Adding a `get-product`-only field to the listing
 

package/skills/commerce/references/storefront-verification.md

@@ -21,9 +21,9 @@ DOM is briefly right about the *intent* and wrong about the *state*.
   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. A drawer built
-  on `useCartUI` is inert while closed, so its copies can't be hit by mistake —
-  but still query inside the open drawer's container, not the document. A click
-  that seems to do nothing usually hit the hidden copy.
+  on `useCartUI` is unmounted while closed, so its copies can't be hit by
+  mistake — but still query inside the open drawer's container, not the
+  document. A click that seems to do nothing usually hit a 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