@base44/app-plugin-commerce 0.2.7 → 0.3.1

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

@@ -109,7 +109,7 @@ Continent codes in full, state regions, tax binding, VAT-on-shipping, day-2 edit
 
 ## Images
 
-**The URL you seed is the URL the store serves.** Resolve each to its final, permanent URL before seeding: the app's image generation, or `base44.integrations.Core.UploadFile({ file })` → public URL. A temporary/**signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile` first — the failure is silent at seed time and visible only in the store. Seeding imageless and patching later is allowed but is open debt; close it before handover.
+**The URL you seed is the URL the store serves.** Resolve each to its final, permanent URL before seeding: the app's image generation, or `base44.integrations.Core.UploadFile({ file })` → public URL. A temporary/**signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile` first — the failure is silent at seed time and visible only in the store. Cheap insurance before seeding: fetch one or two of the URLs and check they answer 200 with an image content type. Seeding imageless and patching later is allowed but is open debt; close it before handover.
 
 ## Payments — the decision
 

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

@@ -5,7 +5,7 @@ skip_when: "The listing and product page render correctly from useProductList /
 forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
 carry_forward:
   - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
-  - "A variant parent's `price` is a FROM price — render it through productPrice/useProductPrice, never as the price."
+  - "A variant parent's `price` is a FROM price — render it through productPrice(row, { formatMoney }), never as the price."
   - "Product images are objects `{src, name, alt}` and the array can be empty — go through productImages/normalizeImage and render a placeholder."
 ---
 
@@ -13,16 +13,16 @@ carry_forward:
 
 Both storefront surfaces render the same catalog record from a different call:
 
-| View | Call | Hook | Returns |
+| View | `commerce/storefront-catalog` action | Hook | Returns |
 |---|---|---|---|
-| Listing / grid / search / ribbon & category pages | `commerce/storefront-catalog` `list-products` | `useProductList` | `{ products: [row…], page, per_page, has_next }` |
-| Product page | `commerce/storefront-catalog` `get-product` | `useProduct` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
+| Listing / grid / search / ribbon & category pages | `list-products` | `useProductList` | `{ products: [row…], page, per_page, has_next }` |
+| Product page | `get-product` | `useProduct` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
 
-Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). You choose what belongs in each view — but you can only render what the call returns, and §1 is that boundary.
+Shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). What belongs in each view is yours — you can only render what the call returns, and §1 is that boundary.
 
 ## 1. Field availability
 
-A listing **row** is the product record itself (minus paywalled fields) plus resolved `ribbons`. `get-product` adds everything that needs a second read.
+A listing **row** is the product record (minus paywalled fields) plus resolved `ribbons`; `get-product` adds everything that needs a second read.
 
 | Data | `list-products` row | `get-product` | Notes |
 |---|---|---|---|
@@ -30,85 +30,79 @@ A listing **row** is the product record itself (minus paywalled fields) plus res
 | `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a *from* price — §2 |
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`; every entry is an **object** — §2 |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
-| `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into typed spec rows) |
+| `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves aren't |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` the descriptive **modifiers** (`productSpecs(product)` → spec rows) |
 | **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | Rows carry `{id, name}` ribbons; `get-product` returns the full records |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | §6 to add them to rows |
 | **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | Why a product with variants can't be fully priced from a row |
 | **`reviews`** (paged items + aggregates) | ❌ | ✅ | Rows still carry the aggregate numbers |
 | **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
-| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** public — reached only through `commerce/storefront-account` `get-download` |
+| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** public — only via `commerce/storefront-account` `get-download` |
 
-## 2. Two shapes, and the three rules the code now owns
+## 2. Two shapes, and three rules the exports own
 
 There is **no product `type` field**. `attributes[]` tells the shapes apart:
 
-| Shape | Test | Card | Product page |
-|---|---|---|---|
-| **Single item** | `attributes` is empty | price, and Add to cart straight from the card if you want one | one Add to cart — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
-| **Sells variants** | `attributes` is non-empty | price **range or "From €19"**, never selectors — link through | one control per axis — §5 |
+| Shape | Test | Renders as |
+|---|---|---|
+| **Single item** | `attributes` empty | one price; one Add to cart, from the card too if you want (`resolveSelection` gives no axes, `complete: true`, a ready `addToCart`) |
+| **Sells variants** | `attributes` non-empty | card: price **range or "From €19"**, never selectors — link through. Page: one control per axis (§5) |
 
-A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, with no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident (§5 covers rendering that state).
+A product with attributes is **only** sellable through a variant — `add-item` with no `variation_id` is `400 variation_required`, no parent fall-back — so attributes with no variations is unsellable by design, not by accident (§5 renders it).
 
-Three rules are enforced by exports — use them and they can't drift between views:
+Three rules the exports enforce, so two views can't drift apart:
 
-- **From-price.** A parent's `regular_price`/`price`/`on_sale` are rolled up from the cheapest publishable variant on every save (by `admin-products` and the seeder) — real, sortable, filterable, but the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` take a listing row **or** a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range unresolved, the exact price resolved.
-- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string — passing the object itself to `<img src>` fails the load — and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`); an empty array means *render your placeholder* (`useProductGallery` builds on them, `hasImages`).
-- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is descriptive — never a selector, never a ribbon; how it renders is a design decision (§3), a control is what it can never become.
+- **From-price.** A parent's `regular_price`/`price`/`on_sale` are rolled up from the cheapest publishable variant on every save (`admin-products`, the seeder) — real, sortable, filterable, but the **lowest** price, not *the* price. `productPrice(rowOrView, { formatMoney })` (`formatMoney` from `useFormatMoney()`) takes a listing row **or** a `resolveSelection` view → `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range unresolved, the exact price once resolved.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string — passing the object to an `<img src>` fails the load, on every product at once — and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean, de-duplicated entries (non-empty `src`, defaulted `alt`); `[]` means *render your placeholder*. Same trap one level in: `view.display.image` is that normalized object or **`null`** — render `display.image?.src`/`?.alt`, and `null` (no variation *or* parent image) is the one placeholder case.
+- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is descriptive — never a selector, never a ribbon; how it renders is a design decision (§3), a control is what it can never be.
 
 ## 3. What each view *can* render
 
-Both lists below are field inventories — what the data supports — **not a layout and not an order**; a store rendering exactly these fields in exactly this sequence is the generic storefront every generated catalog produces.
+Both lists are inventories of what the data supports — **not a layout and not an order**: rendering exactly these fields in this sequence is the generic storefront.
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`). Link the whole card to the product page; the layout is yours.
+**Card:** image, name, `price.label`, a sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `productSpecs`). Link the whole card through; 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)`, `useAddToCart`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, upsells/cross-sells. All but the markup is handed to you: `productImages(product)` + your own active index, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `p.reviews` (+ `submitReview` off `useStorefront()`), and `p.upsells`/`p.crossSells` — added with `useCart().addItem`, matching "already in cart" by product id.
 
-**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.
+**Attributes and modifiers are individually designable.** `productSpecs(product)` rows are `{key, label, titleLabel, value}` and nothing more. ⚑ **Look a row up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`: meta keys are free text typed per product (`care`, `Care`, `Care Instructions`), so an equality test on `label` — or on one spelling of `key` — silently never fires and the feature renders its fallback forever; `titleLabel` is the display-cased form, for a heading. What a row *looks* like is a per-catalog design decision — not one uniform chip row per axis and one grey label/value table ([`../install/02-storefront.md`](../install/02-storefront.md)); §5's rules govern selector *behaviour*, never its form.
 
 ## 4. Ribbons — in **both** views
 
 Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.
 
-- **Listing rows carry resolved `ribbons`**, so a card renders them with no extra call; the product page renders the top-level `ribbons` near the metadata, lighter than the breadcrumb. One or two per card is useful, more is noise, and an empty array means render nothing — never a dangling "Ribbons:" label.
-- **Every ribbon links to a filtered listing** — `list-products` with `ribbon_id`, never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<id>`) to keep the page shareable across reloads.
+- **Listing rows carry resolved `ribbons`** — a card renders them with no extra call; the product page renders its top-level `ribbons` near the metadata, lighter than the breadcrumb. One or two per card is useful, more is noise, and `[]` means render nothing — never a dangling "Ribbons:" label.
+- **Every ribbon links to a filtered listing** — `list-products` with `ribbon_id`, never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<id>`) to stay shareable across reloads.
 - **Offer ribbons as a filter** from `useRibbons()` / `list-ribbons`, which hides ribbons no published product carries and gives a `count` for labels like "Gift (12)". `ribbon_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
 - Ribbons are not breadcrumbs and never variant options — a size or colour is an `attribute`.
 
 ## 5. Variant selection
 
-The one interaction agents reliably get wrong. `variantAxes(view, pick)` hands you the render-ready model that encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
+The one interaction agents reliably get wrong. `variantAxes(view, pick)` is the render-ready model, and it encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise hiding the product's structure); an unbuyable option renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
 
-Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js` — `defaultSelection` → `selectOption` on a click → `resolveSelection` for the view. Every `product.attributes[]` entry is an **axis** in `position` order; every `variations[]` record is one combination. Bind the UI to `view`, not to `product.*`, or a selection changes nothing:
+Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js`: `defaultSelection` → `selectOption` per click → `resolveSelection`. That middle step keeps dead ends out — it holds the just-picked option and clears **only** conflicting axes (Red/L → click Blue → `{Color: Blue}`, size re-opens), never parking the customer on a combination that resolves to nothing. Every `product.attributes[]` entry is an **axis** in `position` order, every `variations[]` record one combination. Bind the UI to `view`, not `product.*`, or a selection changes nothing:
 
 | `view` field | Binds to |
 |---|---|
 | `axes` | the controls: `[{ key, name, attribute_id, options[] }]`, dead options already dropped |
 | `availability[axisKey][option]` | `"available"` / `"out_of_stock"` / `"unavailable"` (constants `OPTION_*`) |
-| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback; `display.image` is normalized or `null` |
-| `priceRange` | `{min, max, on_sale, count}` while the selection is incomplete — render via `useProductPrice(view)` |
+| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback; `display.image` per §2 |
+| `priceRange` | `{min, max, on_sale, count}` while the selection is incomplete — render via `productPrice(view, { formatMoney })` |
 | `complete` / `missingAxes` | the button label: `Select a ${view.missingAxes[0]?.name}` |
 | `purchasable` / `addToCart` | gate **Add to cart** on `purchasable`, send `addToCart` (`{product_id, variation_id}`, or `null`) |
-| `variation` / `candidates` / `isVariable` / `selection` | the record itself, the variations still reachable, and the state the selector renders from |
+| `variation` / `candidates` / `isVariable` / `selection` | the record itself, the variations still reachable, the state the selector renders from |
 
 Three decisions the helpers can't make for you:
 
-- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → visible and labelled. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
-- **Incomplete selection.** Show the range from `useProductPrice(view)` — never `€0`, never the bare parent price — and keep Add to cart disabled with a hint at what's missing.
-- **Linkability.** `useProduct` mirrors the selection into the URL (`?color=Ivory`) and hydrates from it, so a variant is shareable and survives a reload; `selectionToParams`/`selectionFromParams` do a custom round-trip, and `selectionForVariation` hydrates controls from a cart line or an `?variation=` link.
+- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → visible, labelled. `onbackorder` is available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
+- **Incomplete selection.** Show the range from `productPrice(view, { formatMoney })` — never `€0`, never the bare parent price — and keep Add to cart disabled with a hint at what's missing.
+- **Linkability.** `useProduct` mirrors the selection into the URL (`?color=Ivory`) and hydrates from it, so a variant is shareable and survives a reload; `selectionToParams`/`selectionFromParams` are that round-trip by hand, `selectionForVariation` hydrates controls from a cart line or an `?variation=` link.
 
-**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").
+**Attributes but no usable variations** — attaching an attribute and stopping — gets no parent fallback by design, since `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(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"**.
+**Add to cart** goes through `useAddToCart(product)`: `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`, `variation_not_found` (the catalog changed under the page → the hook reloads it). `product.sold_individually` caps quantity at 1, reflected in `useProduct().maxQuantity`. Two behaviors only a hand-rolled view model gets wrong: non-publishable variations never leak an option into the UI, and an empty `option` on an axis means **"any"**.
 
 ## 6. Adding a `get-product`-only field to the listing
 
-If the store needs something a row doesn't carry — resolved categories are the common one — resolve it **in the listing call**, never with `get-product` per card (N requests for one grid). `list-products` resolves its page slice through a helper in `base44/functions/commerce/storefront-catalog/entry.ts`:
-
-```ts
-const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
-```
-
-`withRibbons` reads the taxonomy **once per request** and maps ids onto the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to fields the UI renders; a listing payload is served on every browse.
+Something a row doesn't carry (resolved categories, typically) gets resolved **in the listing call**, never `get-product` per card (N requests for one grid). `list-products` resolves its page slice through one helper in `base44/functions/commerce/storefront-catalog/entry.ts` — `await withRibbons(sr, pageRows.map(publicProduct))` — which reads the taxonomy **once per request**, not once per row, and maps ids onto the rows. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to fields the UI renders — a listing payload is served on every browse.
 
-Don't add `variations` to every row — the heaviest read in the catalog, and a grid doesn't need it; if cards must show true ranges, precompute `price_min`/`price_max`. And don't relax entity RLS to read the catalog from the client — it is admin-only by design ([`guest-access-security.md`](./guest-access-security.md)); widen the function's response instead.
+Don't add `variations` to every row — the heaviest read in the catalog, and a grid doesn't need it; if cards must show true ranges, precompute `price_min`/`price_max`. And don't relax entity RLS to read the catalog client-side — it is admin-only by design ([`guest-access-security.md`](./guest-access-security.md)); widen the function's response instead.

package/skills/commerce/references/reviews.md

@@ -1,41 +1,48 @@
 ---
 stage: reference
-read_when: "You need review behaviour beyond useProductReviews — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
-skip_when: "useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
+read_when: "You are building the review surface — the list, the form, a policy (login-gated, verified buyers) — or need moderation, auto-approval, or a customer's own reviews."
+skip_when: "The product page already renders `p.reviews` and submits through `submitReview`, with the confirmation copy following the response's `status`."
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
-  - "Reviews are part of the happy path: one hook. The confirmation copy must come from the submit response, never hardcoded."
+  - "Reviews are part of the happy path: the list arrives with the product, submitting is one client call. The confirmation copy must come from the submit response's `status`, never hardcoded."
 ---
 
 # Reviews
 
-Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the whole UI contract is one hook. Unless the store explicitly doesn't want them, put them on the product page: `useProductReviews(product, { policy, user, requireRating, perPage })` — the list with paging (`items`, `hasNext`/`loadMore`), the aggregates (`averageRating`, `ratingCount`), the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc. The markup around it — stars, rows, the form — is yours, like all storefront UI.
+Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the storefront's half is two calls. Unless the store explicitly doesn't want them, put them on the product page — `useProduct(slug)` already hands you `p.reviews` (the first page of approved reviews plus the aggregates, fetched with the product), and submitting is one method. There is no reviews hook and no review markup: the stars, the rows, the form and every word around them are yours, like all storefront UI.
+
+## The two client calls
+
+Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
+
+- **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
+- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
 - `get-product` returns **paginated `reviews`** plus `average_rating`, `rating_count` and a `verified` flag per review; `list-products` rows carry the aggregates, so **stars on cards cost no extra call**;
-- `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. A signed-in caller's session email always wins (the payload cannot impersonate); a guest supplies `email`; `verified` comes from that email's order history. The three error codes (`400 email_required | review_incomplete | invalid_rating`) land on their fields via `fieldErrors` instead of rejecting into nothing;
+- `submit-review` accepts `{ product_id, email, reviewer?, review, rating? }` from **anyone — no login**. A signed-in caller's session email always wins (the payload cannot impersonate); a guest supplies `email`; `verified` comes from that email's order history;
 - `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
 - moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
 
-## The `policy` prop
+## The policy is the store's
 
-`policy` is the store's review rule as one option, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`useProductReviews(product, { policy: "login", user })`) — the stricter policies need it:
+Which visitors may submit is a gate **you** render, in your own words. The three patterns worth knowing:
 
-| `policy` | Who may submit | Blocked as |
+| Policy | Who may submit | How you implement it |
 |---|---|---|
-| `"open"` (default) | anyone with a valid email — the server's own rule | — |
-| `"login"` | a signed-in visitor only | `reviewBlockedReason: "login_required"` |
-| `"verified_buyers"` | someone whose own orders include a `processing`/`completed` order for this product (checked via `my-orders`) | `"not_a_buyer"` |
+| **Open** (the server's own rule) | anyone with a valid email | render the form for everyone; the email field is required for guests |
+| **Login-gated** | a signed-in visitor only | render the form only when your app has a user; otherwise your "sign in to review" line |
+| **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
-Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate. `requireRating: true` makes the stars mandatory; `requiresEmail` is `false` for a signed-in visitor, so the field is hidden (the session's email wins server-side anyway). A policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 
 `products.auto_approve_reviews` ([`store-settings.md`](./store-settings.md), toggle on the admin's Reviews screen) is the **only** server-side switch: off (the default) holds every review as `hold` for moderation; on publishes immediately.
 
-So **the confirmation copy must come from the response**: `submit()` resolves `{ ok, status, verified }` with `status` `"approved"` or `"hold"`, and `message` follows it. A hardcoded "awaiting approval" lies to every store with auto-approval on — and after an approved submission the hook refreshes the list so the review actually appears.
+So **the confirmation copy must come from the response**: `submitReview` resolves `{ review_id, status, verified }` with `status` `"approved"` or `"hold"`, and your message follows it. A hardcoded "awaiting approval" lies to every store with auto-approval on — and only the approved case is worth refreshing the list for.
 
-Disabling reviews store-wide is simply building no review UI; there is no server switch to keep in sync.
+Disabling reviews store-wide is simply building no review UI; there is no server switch to keep in sync (and then no star ratings on cards either — an average of nothing is `0`).
 
 Shapes and error details: [`../docs/api-storefront.md`](../docs/api-storefront.md#submit-review). Where ratings belong per view: [`catalog-rendering.md`](./catalog-rendering.md).

package/skills/commerce/references/store-settings.md

@@ -15,7 +15,7 @@ Six records, one per group: `general`, `products`, `inventory`, `tax`, `shipping
 |---|---|---|
 | **`general`** | | |
 | `order_received_path` | `"/order-received"` | The route a paying customer returns to; `shared/commerce/payments.ts` builds the provider's success/cancel URLs from it. A value that doesn't match your route is a 404 after payment and an order never confirmed. |
-| `currency` | `"USD"` | ISO code, **a value not a format**. Stamped on orders by `storefront-checkout`; published on `get-store-info` for `useMoney`/`useFormatMoney`. |
+| `currency` | `"USD"` | ISO code, **a value not a format**. Stamped on orders by `storefront-checkout`; published on `get-store-info` for `useFormatMoney`. |
 | `weight_unit` / `dimension_unit` | `"kg"` / `"cm"` | Labels only — nothing converts. Admin product form, `get-store-info`. |
 | **`products`** | | |
 | `auto_approve_reviews` | `false` | The **only** server-enforced review rule: `submit-review` returns `status: "hold"` or `"approved"`. Confirmation copy comes from that response ([`reviews.md`](./reviews.md)). |

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

@@ -11,19 +11,24 @@ faster than the cart settles: the hooks are optimistic and debounced, so the
 DOM is briefly right about the *intent* and wrong about the *state*.
 
 - **Wait for the cart, then for each row.** Two waits, neither optional. Before
-  the first action, wait for the initial load to settle — `status` leaves
-  `"loading"` exactly once, so the signal is the loaded UI (a row, or the empty
-  state), never a fixed sleep. Then after every stepper click wait for **that
-  row**: the click starts a 250ms debounce before the request even leaves, so
-  reading the quantity or total straight after gives the optimistic number and
-  stale totals, and two quick clicks send **one** request for the final number.
-  Wait for the row's busy state to clear (`aria-busy`, re-enabled buttons)
-  before reading or clicking again.
+  the first action, wait for the initial load to settle — `useCart().status`
+  leaves `"loading"` exactly once and never returns there for a mutation, so the
+  signal is the loaded UI (a row, or the empty state), never a fixed sleep. Then
+  after every stepper click wait for **that row**: `useCartLine` starts a 250ms
+  debounce before the request even leaves, so reading the quantity or total
+  straight after gives the optimistic number and stale totals, and two quick
+  clicks send **one** request for the final number. The row's `pending` is the
+  only mutation-settled signal there is (`pending === false` with no `error`
+  means the row, the totals and any badge have all landed) — wait for the busy
+  state the page renders from it (`aria-busy`, re-enabled buttons) before
+  reading or clicking again.
 - **Scope actions to the visible drawer.** With a drawer, the page can hold two
-  "Remove" buttons for one line — drawer and cart page behind it. A drawer built
-  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" buttons for one line — drawer and cart page behind it. `useCartUI`
+  only hands the page an `open` flag: whether the closed drawer is unmounted
+  (`{ui.open && …}`) or merely translated off-screen is the store's choice, so
+  assume the duplicates exist and query inside the open drawer's container,
+  never 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
@@ -42,6 +47,7 @@ DOM is briefly right about the *intent* and wrong about the *state*.
   so a script that placed an order loses its page context and can land back at
   `/` — while the order itself was created normally. That is the hard
   navigation, not a broken redirect. The confirmation is reachable at any time
-  from a fresh navigation to `/order-received?order_id=…&order_key=…` (the ids
-  come back in `placeOrder`'s result, and `commerce/admin-orders` `search` has
-  the order either way).
+  from a fresh navigation to `orderReceivedUrl(result)`
+  (`/order-received?order_id=…&order_key=…` — the ids come back in
+  `placeOrder`'s result, and `commerce/admin-orders` `search` has the order
+  either way).

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -8,8 +8,6 @@ import React, {
   useState,
 } from "react";
 import {
-  attributesLabel,
-  cartTotalsLines,
   createStorefront,
   storefrontErrorCode,
   storefrontErrorMessage,
@@ -18,43 +16,24 @@ import {
 /**
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
  *
- * Mount it once, above every storefront page (product list, product page,
- * cart, checkout, order-received). It is NOT a <Route>. A store with shared
- * chrome — nearly all of them — mounts it on a pathless layout route, wrapping
- * the layout that renders <Outlet/>, which keeps the nav's cart badge and the
- * page on one cart and leaves the admin outside:
+ * Mount it **once**, above every storefront page, on a pathless layout route
+ * wrapping the layout that renders `<Outlet/>` (`<StorefrontProvider
+ * base44={base44}><StoreLayout /></StorefrontProvider>` as that route's
+ * `element`); with no shared layout, wrap `<Routes>` instead. Two ways to get
+ * this wrong, both with symptoms:
+ * - as a child of `<Routes>` React Router throws "is not a `<Route>` component";
+ * - a layout that renders the provider *inside* itself leaves the nav outside
+ *   it, so the cart badge and the cart page read different carts.
  *
- *   import { base44 } from "@/api/base44Client";
- *   <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
- *     <Route path="/" element={<Home />} /> …
- *   </Route>
+ * Pass `base44`, or `store={createStorefront(base44)}` when other modules need
+ * the same client.
  *
- * With no shared layout it can wrap <Routes> directly instead:
- *
- *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
- *
- * As a child of <Routes> it throws ("is not a <Route> component"), since React
- * Router allows only <Route>/<Fragment> children there. Never the other way
- * round either: a layout that renders the provider inside itself puts the nav
- * outside it, so the badge and the cart page read different carts.
- *
- * or, if other modules also need the raw client, create it once and share it:
- *
- *   // src/lib/storefront.js
- *   import { createStorefront } from "@/commerce/utils";
- *   import { base44 } from "@/api/base44Client";
- *   export const store = createStorefront(base44);
- *
- *   <StorefrontProvider store={store}> ... </StorefrontProvider>
- *
- * What lives here (and why it must not be duplicated per page):
- * - the `createStorefront` instance — it owns the cart_token lifecycle;
- * - store info — payment_gateways, currency, countries/currencies come from
- *   `get-store-info` ONLY (never off a cart view), cached for the session;
- * - the cart view — every mutation from any component funnels through one
- *   serialized queue, so a slow response can never clobber a newer cart, and
- *   a header badge, a cart drawer and the checkout all re-render from the
- *   same state.
+ * What lives here, and why it must not be duplicated per page: the client (it
+ * owns the cart_token lifecycle); store info, cached for the session —
+ * payment gateways, currency and countries come from `get-store-info` ONLY,
+ * never off a cart view; and the cart, whose every mutation funnels through one
+ * serialized queue, so a slow response cannot clobber a newer cart and the
+ * badge, the drawer and the checkout all re-render from one state.
  */
 
 const StorefrontContext = createContext(null);
@@ -167,6 +146,22 @@ export function useStoreInfo() {
   };
 }
 
+/**
+ * The store's country list, **always as an array** — `{ countries, options,
+ * loading, error }`, `options` as `{value, label}` for a `<select>`.
+ *
+ * `useStoreInfo().countries` is `null` until store info resolves, so mapping it
+ * directly white-screens the checkout on a cold load — the most severe defect
+ * observed in a generated storefront. Here the list is empty-then-full, never
+ * null, and `loading` says which.
+ */
+export function useCountries() {
+  const { countries, loading, error } = useStoreInfo();
+  const list = Array.isArray(countries) ? countries : [];
+  const options = useMemo(() => list.map((c) => ({ value: c.code, label: c.name })), [countries]); // eslint-disable-line react-hooks/exhaustive-deps
+  return { countries: list, options, loading, error };
+}
+
 /**
  * `(amount) => "€19.99"` in the store's currency, per the viewer's locale.
  * Falls back to a plain number while store info is still loading.
@@ -189,55 +184,49 @@ export function useFormatMoney() {
 }
 
 /**
- * The shared cart — state, decorated lines, and every cart mutation. All
- * consumers see the same view; every action resolves to the fresh priced cart.
+ * The shared cart — state plus every cart mutation. All consumers see the same
+ * view; every action resolves to the fresh priced cart it published.
  *
- *   const { status, lines, totalsLines, notices, updateItem, removeItem } = useCart();
- *   if (status === "loading") return <Skeleton />;
- *   if (status === "empty")   return <EmptyBag />;
- *   lines.map(line => …)   // line.attributesLabel, line.image, line.canIncrease
+ *   const { status, cart, updateItem, removeItem, applyCoupon } = useCart();
+ *   if (status === "loading") return <YourSkeleton />;
+ *   if (status === "empty")   return <YourEmptyBag />;
+ *   cart.items.map(item => …)   // your rows; useCartLine(item) per row
  *
  * **Branch on `status`, not on `isEmpty`.** `isEmpty` is true while the cart is
  * still loading (there are no items *yet*), so a page that renders its empty
  * state from it flashes "your bag is empty" on every visit before the cart
  * arrives. `status` separates the two: `"loading"` → `"empty"` | `"ready"`.
  *
- * - `lines` are `cart.items` decorated with what a renderer needs and would
- *   otherwise re-derive: `attributesLabel` ("Size: 42 · Color: Ivory" — the raw
- *   `attributes` is an **array** of `{name, option}`, never a map),
- *   `image` normalized to `{src, alt}` or null, money pre-formatted
- *   (`totalLabel`, `subtotalLabel`, `unitPriceLabel` — no `useFormatMoney`
- *   needed in a row), `purchasable` as a boolean with `unavailableReason`
- *   beside it, and the quantity bounds.
- * - `notices` normalizes `coupon_notices` + `removed_items` into one list —
- *   render it, or a line that auto-dropped vanishes with no explanation.
- * - `mutationError` is the last failed mutation (insufficient stock, an expired
- *   cart), cleared on the next success. Mutations still reject, so
- *   `useCartLine`/`useAddToCart` can handle failures locally.
- * - `applyCoupon(code)` resolves to `{ ok, cart }` or `{ ok: false, code,
- *   message }` — an invalid code is expected flow, not an exception.
- *
- * ## When `status` settles — and what it does not cover
+ * Rendering `cart.items` is yours; three shapes in there are easy to misread,
+ * and `@/commerce/utils` has the helper for each:
+ * - `item.attributes` is an **array** of `{name, option}`, never a map →
+ *   `attributesLabel(item.attributes)`.
+ * - `item.purchasable` is a **result object** `{ok, code, error}`, not a
+ *   boolean — truthiness alone calls every line purchasable.
+ * - the cart's totals are **nested** (`cart.totals`), an order's are flat →
+ *   `cartTotalsLines(cart, { formatMoney })` renders every line the store
+ *   actually has, including the discount and tax rows a hand-written summary
+ *   drops.
  *
- * `status` is `"loading"` for exactly one thing: the **first** `getCart()` of
- * the session has not resolved yet (internally, `cart === undefined`). It
- * settles once, to `"empty"` or `"ready"`, and after that:
+ * Also render `cart.coupon_notices` / `cart.removed_items` when present: they
+ * say what auto-dropped and why, in the server's words.
  *
- * - **A mutation never returns it to `"loading"`.** Adding, updating, removing
- *   or couponing leaves `status` as it was, previous numbers on screen, until
- *   the new view lands. There is no cart-wide busy flag by design: a page-wide
- *   spinner for a 250ms quantity step is worse than the stale number, and the
- *   right busy scope is the row (`useCartLine`'s `pending`) or the control that
- *   started it.
- * - `"empty"` therefore means *loaded, with no items* — including after
- *   checkout consumes the cart — never "still arriving".
- * - It flips `"empty"` → `"ready"` when the first line lands, so a header badge
- *   and a drawer switch states off the same signal.
+ * - `mutationError` is the last failed mutation (insufficient stock, an expired
+ *   cart) as `{code, message}`, cleared on the next success. Mutations still
+ *   reject, so a caller can handle failures locally too.
+ * - `applyCoupon(code)` resolves `{ ok, cart }` or `{ ok: false, code, message }`
+ *   — an invalid code is expected flow, not an exception. Coupons are admin-only
+ *   data, so a seeded code is reachable **only** through a field the customer
+ *   types it into: a store with coupons needs one, in the cart or the checkout.
  *
- * So branch **`status`** for the page's loading/empty/ready shape, and watch
- * **`useCartLine().pending`** (or your own flag around `addItem`) for "did that
- * change land". Anything waiting on a mutation — a queued follow-up action, a
- * script driving the page — waits on the second, never the first.
+ * `status` settles **once** — `"loading"` means only that the session's first
+ * `getCart()` is outstanding. A mutation never returns it to `"loading"`
+ * (previous numbers stay on screen until the new view lands), so there is no
+ * cart-wide busy flag by design: the right busy scope is the row
+ * (`useCartLine().pending`) or the control that started it. `"empty"` therefore
+ * always means *loaded, with no items* — including after checkout consumes the
+ * cart. Anything waiting for a mutation to land waits on `pending`, never on
+ * `status`.
  */
 export function useCart() {
   const { client, cart, cartError, mutationError, runCart } = useStorefrontState();
@@ -270,58 +259,9 @@ export function useCart() {
     [client, runCart],
   );
 
-  const formatMoney = useFormatMoney();
   const items = cart?.items ?? [];
   const loading = cart === undefined;
 
-  const lines = useMemo(
-    () =>
-      items.map((item) => {
-        // A cart line's `purchasable` is a RESULT object ({ ok, code, error }),
-        // not a boolean — truthiness alone would call every line purchasable.
-        const purchasable = item.purchasable?.ok ?? Boolean(item.purchasable);
-        // `sold_individually` is the only per-line ceiling the cart view
-        // carries; real stock limits surface as `insufficient_stock` from the
-        // server when a customer tries to exceed them.
-        const maxQuantity = item.sold_individually ? 1 : Infinity;
-        return {
-          ...item,
-          attributesLabel: attributesLabel(item.attributes),
-          image: item.image ? { src: item.image, alt: item.name ?? "" } : null,
-          totalLabel: item.total != null ? formatMoney(item.total) : "",
-          subtotalLabel: item.subtotal != null ? formatMoney(item.subtotal) : "",
-          unitPriceLabel: item.price != null ? formatMoney(item.price) : "",
-          maxQuantity,
-          canIncrease: item.quantity < maxQuantity,
-          canDecrease: item.quantity > 1,
-          purchasable,
-          unavailableReason: purchasable ? null : (item.purchasable?.error ?? null),
-        };
-      }),
-    [items, formatMoney],
-  );
-
-  const notices = useMemo(
-    () => [
-      ...(cart?.coupon_notices ?? []).map((n) => ({
-        kind: "coupon",
-        code: n.error_code ?? n.code ?? "coupon_invalid",
-        message: n.error ?? `Coupon ${n.code} is no longer valid.`,
-      })),
-      ...(cart?.removed_items ?? []).map((r) => ({
-        kind: "removed_item",
-        code: r.code ?? "unavailable",
-        message: r.reason ?? "An item is no longer available and was removed.",
-      })),
-    ],
-    [cart],
-  );
-
-  const totalsLines = useMemo(
-    () => (cart ? cartTotalsLines(cart, { formatMoney }) : []),
-    [cart, formatMoney],
-  );
-
   return {
     cart: cart ?? null,
     loading,
@@ -330,9 +270,6 @@ export function useCart() {
     itemCount: items.reduce((n, i) => n + (i.quantity || 0), 0),
     isEmpty: !items.length,
     status: loading ? "loading" : items.length ? "ready" : "empty",
-    lines,
-    notices,
-    totalsLines,
     refresh,
     addItem,
     updateItem,