@base44/app-plugin-commerce 0.3.1 → 0.3.3

package/README.md

@@ -11,8 +11,8 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires a provider by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`. **For Stripe there is nothing to write**: `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation used as-is — copy it over the stub and enable the gateway. Any other provider (PayPal, Adyen, a local PSP) follows the same shape. Enable the gateway only with a provider behind it, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); provider mechanics: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
 - **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. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — 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), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). 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 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` and `ribbons.js` normalize the two catalog fields that are arrays of objects (`{src, name, alt}` images, `{id, name}` ribbons) rather than strings; `types.js` writes the catalog shapes down as JSDoc typedefs (`StorefrontProduct` and the rest), so what a field holds is answerable from the frontend; `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. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — 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), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). 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`; …) and names its return type from `storefront/types.js`, so a page reads a field's shape off the hook instead of off a backend function. 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/base44/entities/commerce.PaymentGateway.jsonc

@@ -1,7 +1,7 @@
 {
   "name": "commerce.PaymentGateway",
   "type": "object",
-  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Secrets are never stored here; use Base44 secrets.",
+  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Enable or disable a gateway with commerce/seed-store payment_methods — e.g. { payment_methods: [\"offline\", \"card\"] }, valid at any time and the whole payload — never by writing enabled on this row: the seeder owns the on/off state and the next call overwrites a hand edit. Secrets are never stored here; use Base44 secrets.",
   "properties": {
     "slug": {
       "type": "string",

package/base44/functions/commerce/seed-store/entry.ts

@@ -47,6 +47,14 @@
  * the one call covers "card-only" stores with no entity editing. Explicit
  * values always win, on first seed and re-runs alike (like `currency`).
  *
+ * **Every key is independent, and the call is the day-2 tool as much as the
+ * install one.** A later call carries only the slice being changed — enabling
+ * cards on a live store is `{ payment_methods: ["offline", "card"] }` and
+ * nothing else. Omitted keys are not reset: no `products` means no catalog work
+ * at all, and no `locations` leaves the store's shipping untouched. This is the
+ * supported way to change store configuration; editing `commerce.PaymentGateway`
+ * (or the settings rows) by hand is not.
+ *
  * `store_name` is required on a first seed: a function's env is only
  * BASE44_APP_ID, so it cannot read the app's name, and subjects need one.
  * `currency` is an ISO code and `weight_unit`/`dimension_unit` are the
@@ -249,9 +257,15 @@ Deno.serve(async (req) => {
     if (catalogSpec?.locations?.length && !catalogSpec.locations.some((l: any) => !l.regions?.length)) {
       warnings.push("no_catchall_location: addresses outside your locations will get shipping_not_available — add a location with rest_of_world: true if you ship worldwide");
     }
+    // The same reasoning applies to a later call that simply doesn't mention
+    // shipping — flipping `payment_methods` on a live store, say. The merchant's
+    // locations are still the shipping story, so the test is whether the store
+    // has ANY location, not whether one carries this default's name: matching by
+    // name would drop a free worldwide rate behind a catch-all called anything
+    // else, which is the exact record the paragraph above refuses to create.
     if (!catalogSpec?.locations?.length) {
-      const fallback = ((await sr.entities["commerce.ShippingTaxLocation"].filter({ name: REST_OF_WORLD_LOCATION.name }, undefined, 1)) ?? [])[0];
-      if (!fallback) {
+      const existing = (await sr.entities["commerce.ShippingTaxLocation"].list(undefined, 1)) ?? [];
+      if (!existing.length) {
         await sr.entities["commerce.ShippingTaxLocation"].create(REST_OF_WORLD_LOCATION);
         seeded.locations++;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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

@@ -33,8 +33,11 @@ moments. Read nothing else up front.
   `base44.entities["commerce.Product"]`. `commerce__Product` and `Product` do
   not exist. The map is [`docs/entities.md`](./docs/entities.md); never scan
   `base44/entities/` for a name.
-- **Store configuration is declared in one seed call** — catalog, shipping
-  zones, currency, payment methods — never assembled by editing records
+- **Store configuration is declared through `commerce/seed-store`** — catalog,
+  shipping zones, currency, payment methods — never assembled by editing
+  records. It is idempotent and every key is independent, so it is the day-2
+  tool as much as the install one: a later call carries only the slice it
+  changes — enabling cards is `{ payment_methods: ["offline", "card"] }`, whole
   ([`install/03-data.md`](./install/03-data.md)).
 - **Don't weaken the admin gating** — three layers (UI guard, entity RLS,
   `requireAdmin()`); keep all three when touching routes or schemas
@@ -105,13 +108,13 @@ Open a file when its work starts — not while planning.
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 5K |
 | [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 33K |
-| [`install/03-data.md`](./install/03-data.md) | seeding catalog/shipping, payments decision | 11K |
+| [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
-| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | 13K |
+| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
-| [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | 8K |
+| [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
 | [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |

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

@@ -59,7 +59,7 @@ Only `status: "publish"` products are returned — the admin's single **Visible*
 
 **Response:** `{ "products": [Product...], "page": 1, "per_page": 12, "has_next": true }`
 
-Each row is the product record (minus paywalled fields) **plus a resolved `ribbons` array** (`[{ id, name }]`), so cards show ribbons without a second call. `categories` are **not** resolved — `category_ids` only. What a row can and can't show, and how to add a `get-product`-only field to this call instead of fetching per card: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
+Each row is the product record (minus paywalled fields) **plus a resolved `ribbons` array** (`[{ id, name }]` — objects, and the key is omitted entirely when no row on the page carries a ribbon), so cards show ribbons without a second call. `categories` are **not** resolved — `category_ids` only. Every field's exact shape, what a row can and can't show, and how to add a `get-product`-only field to this call instead of fetching per card: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
 **Filters stack** — all of them are ANDed, so "Dresses + gift + on sale" is one request. Build the controls from [`list-categories`](#list-categories), [`list-ribbons`](#list-ribbons) (its `count` gives you "Gift (12)") and [`list-attributes`](#list-attributes), and mirror active filters into the URL so a filtered listing is shareable and survives reload.
 
@@ -84,7 +84,7 @@ await cat({ category_id, sort: "popularity", per_page: 4 });    // top in catego
   "product": { Product },
   "variations": [ ProductVariation... ],          // publishable only; [] when the product has no attributes
   "categories": [ ProductCategory... ],
-  "ribbons": [ ProductRibbon... ],
+  "ribbons": [ ProductRibbon... ],                // { id, name, count } records, beside the product — not on it
   "reviews": { "items": [ { "id", "reviewer", "review", "rating", "verified", "created_date" } ],
                "page": 1, "per_page": 10, "has_next": false,
                "average_rating": 4.5, "rating_count": 12 },
@@ -94,6 +94,8 @@ await cat({ category_id, sort: "popularity", per_page: 4 });    // top in catego
 ```
 **Errors:** `404 not_found` (missing / not published / hidden).
 
+In React, `useProduct` normalizes those ribbons to a listing row's `{ id, name }` and attaches them to `product`, so one card component can render a row *or* this product (`productRibbons(product)`); ribbon counts for a filter come from [`list-ribbons`](#list-ribbons).
+
 > **`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). In React the product page's hooks in `@/commerce/storefront` resolve this for you. The non-React resolver sample (`resolveSelection` from `@/commerce/utils`) and the variant deep-dive: [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
 ### `list-categories`

package/skills/commerce/install/01-install.md

@@ -67,9 +67,4 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 Then continue: **[`./02-storefront.md`](./02-storefront.md) when you start building UI**, **[`./03-data.md`](./03-data.md) when you start the seed payload**. Do **not** read them now, and open no `references/` or `docs/` file during an install — a file read early costs its size on every later call.
 
-Record these lines in your working notes; do not re-read this file.
-
-- Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them.
-- `/order-received` must exist as a route: every payment link returns there, and confirming is what marks an order paid.
-- Interleave: start image generation first → mount admin + build the storefront while images render → seed when the URLs are back → payments last.
-- Entities are dotted + bracket-syntax only (`base44.entities["commerce.X"]`); the map is [`../docs/entities.md`](../docs/entities.md) — never scan `base44/entities/`.
+Then copy this file's `carry_forward` lines (in its front matter) into your working notes, and do not re-read this file.

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

@@ -16,13 +16,13 @@ carry_forward:
 
 # 02 — Storefront
 
-One split decides everything here: **the logic is premade, the UI never is.** The hooks own checkout repricing, variant resolution, cart state, order-return verification — hand-writing any of it is where storefront bugs cluster, so **never re-implement what a hook does**. Every element, class, layout and **word** is yours; nothing in `@/commerce/storefront` renders markup, carries CSS, or contains a sentence a customer will read. **Decide how the store looks as if this kit did not exist**, then encode that look **once** as design classes ([below](#design-language--once-before-any-page)) and build every page in them — the snippets here are wiring reference, never design input.
+One split decides everything here: **the logic is premade, the UI never is.** The hooks own checkout repricing, variant resolution, cart state, order-return verification — hand-writing any of it is where storefront bugs cluster, so **never re-implement what a hook does**. Every element, class, layout and **word** is yours; nothing in `@/commerce/storefront` renders markup or carries CSS. **Decide how the store looks as if this kit did not exist**, then encode it **once** as design classes ([below](#design-language--once-before-any-page)) — the snippets here are wiring reference, never design input.
 
 **States and codes, not copy.** Where a state needs words you get the *state* (`buy.state`, `hint.code`, `blockers`) and write the words. So: never re-derive a state you were handed (a ternary chain over `adding`/`purchasable` re-implements `buy.state`, wrong), and never leave one unworded (a button with no text for `sold_out` renders empty).
 
-**This file is the whole job.** Every shape you need is in ["What each hook resolves to"](#what-each-hook-resolves-to) — you do not need to open the hook files while building, and doing so mid-build is the most expensive way to answer a question this page already answers. Rules marked ⚑ must survive whatever design you build.
+**This file is the whole job.** Every shape you need is in ["What each hook resolves to"](#what-each-hook-resolves-to) — don't open the hook files while building; that is the most expensive way to answer a question this page already answers. Rules marked ⚑ must survive whatever design you build.
 
-**One import path: `@/commerce/storefront`.** Each section opens with its page's exact import line — copy it verbatim, then delete unused names. Everything a page needs is re-exported there, so a React page never imports `@/commerce/utils` directly. `useStoreInfo` is the name most often left out — it is the only source of store name and currency.
+**One import path: `@/commerce/storefront`.** Each section opens with its page's exact import line — copy it verbatim, then delete unused names. Everything a page needs is re-exported there, so a React page never imports `@/commerce/utils` directly. `useStoreInfo` is the name most often left out.
 
 ## Setup — once
 
@@ -45,13 +45,23 @@ import AdminApp from "@/commerce/admin";
     }>
       <Route path="/" element={<Home />} />
       <Route path="/product/:slug" element={<ProductPage />} />
-      <Route path="/bag" element={<Bag />} />
-      <Route path="/checkout" element={<Checkout />} />
-      <Route path="/order-received" element={<OrderReceived />} />
+      {/* /bag, /checkout, and /order-received — which is mandatory */}
     </Route>
     <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
+
+// …and the layout that route renders. Yours to design; the shape is the point:
+function StoreLayout() {
+  const { itemCount } = useCart();          // one cart, shared with every page
+  return (
+    <>
+      <header>{/* nav + your cart trigger, showing itemCount */}</header>
+      <Outlet />                            {/* the routed page lands here */}
+      <footer>…</footer>{/* + the drawer, if the cart is one — see Cart below */}
+    </>
+  );
+}
 ```
 
 ⚑ **The nesting is provider → layout → `<Outlet/>`, never the reverse** — a layout that renders the provider inside itself leaves the nav's cart badge on a different cart (or throws). With no shared chrome, wrap `<Routes>` in the provider instead; a provider *inside* `<Routes>` throws ("is not a `<Route>` component"). The provider owns the shared client, store info and **one** shared cart — never mount a second one, never touch `cart_token`.
@@ -60,9 +70,9 @@ import AdminApp from "@/commerce/admin";
 
 The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row`, a heading scale, a price style — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.**
 
-The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show — rather than inventing a phrase per call site. It is the half of the store's identity a kit cannot ship: "Add to bag" in every store built from this plugin is exactly how stores end up reading like each other.
+The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show. It is the half of a store's identity a kit cannot ship.
 
-**Concentrate identity; don't diffuse it.** The classes carry the look everywhere; on top of them, spend bespoke markup on **one or two signature moments per page** — the hero, the one product-page module that shows what these products are judged on — and render everything else as conventions in the classes. The signature budget concentrates where the products are: **the product page stays the storefront's richest surface**, and its rules to render axes and specs *by what they are* hold at full force — that richness is semantic (what the controls and rows show), which costs words, not chrome. One navigation affordance per control (thumbnails *or* arrows, never both plus dots); checkout, bag and order-received are convention surfaces. Keep components small (~2–4K chars) — faster to emit, review and fix than one long page file.
+**Concentrate identity; don't diffuse it.** The classes carry the look everywhere; on top of them, spend bespoke markup on **one or two signature moments per page** — the hero, the one product-page module that shows what these products are judged on — and render everything else as conventions in the classes. **The product page stays the storefront's richest surface**, and that richness is semantic: what the controls and rows *show*, which costs words rather than chrome. One navigation affordance per control (thumbnails *or* arrows, never both plus dots); checkout, bag and order-received are convention surfaces. Keep components small (~2–4K chars) — faster to emit, review and fix than one long page file.
 
 ## What each hook resolves to
 
@@ -80,6 +90,7 @@ Everything below is already unwrapped — no `.data`, no envelope. `formatMoney`
 | `variantAxes(view, pick)` | `[{ key, name, selectedOption, options: [{ value, selected, disabled, outOfStock, pick }] }]`. |
 | `productPrice(rowOrView, { formatMoney })` | `{ label, compareAtLabel, onSale, isFrom, isRange, min, max }` — `label` is what to render. |
 | `productImages(product)` | `[{ src, name, alt }]`, de-duplicated. `[]` is legitimate → render your placeholder. |
+| `productRibbons(product)` | `[{ id, name }]` — **objects**, and the field can be absent; takes a listing row or `useProduct().product`. |
 | `productSpecs(product)` | `[{ key, label, titleLabel, value }]` from `meta_data`; `findSpec(rows, key)` looks one up ignoring case/spaces/`_`/`-`. Never match on `label` — meta keys are free text. |
 | `useCart()` | `{ status, cart, itemCount, isEmpty, loading, error, mutationError, refresh, addItem, updateItem, removeItem, applyCoupon, removeCoupon }` — `status`: `"loading" \| "ready" \| "empty"`. |
 | `cart.items[n]` | `{ item_key, product_id, variation_id, name, quantity, price, subtotal, total, image, attributes, sold_individually, purchasable }` — `attributes` is an **array** of `{name, option}`; `purchasable` is a **result object** `{ok, code, error}`, not a boolean. |
@@ -87,29 +98,29 @@ Everything below is already unwrapped — no `.data`, no envelope. `formatMoney`
 | `cartTotalsLines(cart, { formatMoney })` | `[{ key, label, amount, formatted, hidden, emphasis }]` — every line the store has, incl. discount and tax. `orderTotalsLines(order, …)` is the same shape for a receipt. Pass `labels: {…}` to rename a row. |
 | `useCartLine(item)` | `{ quantity, setQuantity, increase, decrease, remove, pending, error, canIncrease, canDecrease, maxQuantity, atMax, atMin }`. |
 | `useCartUI()` | `{ open, openCart, closeCart, toggleCart }`. |
-| `useCheckoutContext()` | the address (`billing`, `updateBilling`, `shipping`, `updateShipping`, `shipToDifferent`, `setShipToDifferent`, `missingBillingFields`, `addressError`), the shipping state (`shippingStatus`, `shippingMethods`, `chosenShippingMethod`, `chooseShippingMethod`, `shippingSyncing`), the payment state (`paymentMethods`, `paymentMethod`, `setPaymentMethod`, `selectedGateway`, `singlePaymentMethod`) and the gate (`blockers`, `canPlaceOrder`, `placing`, `stage`, `orderError`, `placeOrder`) — plus `cart`. The pickers below read the shipping/payment parts for you. |
+| `useCheckoutContext()` | the address (`billing`, `updateBilling`, `shipping`, `updateShipping`, `shipToDifferent`, `setShipToDifferent`, `missingBillingFields`, `addressError`), the shipping and payment state (the pickers read those for you), and the gate: `blockers`, `canPlaceOrder`, `placing`, `stage`, `orderError`, `placeOrder` — plus `cart`. The Checkout section wires all of it. |
 | `useOrderReturn()` | `{ status, order, lines, paymentLink, paymentInstructions, error, reload }` — `status`: `"loading" \| "paid" \| "unpaid" \| "cancelled" \| "error"`. An order's totals are **flat** (`order.total`); there is no `order.totals`. |
 
 ## Product list / collection
 
 ```jsx
-import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPrice, productImages } from "@/commerce/storefront";
+import { useProductList, useCategories, useStoreInfo, useFormatMoney, productPrice, productImages, productRibbons } from "@/commerce/storefront";
 ```
 
 (Drop `useCategories` with no filter bar; add `useRibbons` for a ribbon filter.) `const list = useProductList({ per_page: 24 })`, then guards on `list.status` before any markup — ⚑ branch on `status`, so a failed request renders as a failure instead of an empty grid, with a retry calling `list.reload`.
 
 ⚑ **Render paging whenever `hasNext` is true** — `{list.hasNext && <button type="button" onClick={list.next} disabled={list.busy}>…</button>}` (append mode: `list.loadMore`); a page that renders nothing for paging ships a catalog silently capped at `per_page`. Drive filters from `useCategories()`/`useRibbons()` data via `setParams`, never from hardcoded names — a renamed ribbon must not strand a dead button.
 
-A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` on its own is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `ribbons`, `productSpecs(row)`. ⚑ **Images are objects and the array may be empty** — render your placeholder, never a broken `<img>`. Full field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design: lead with the one or two fields *these* products are judged on rather than the default name/price/stars trio.
+A card can render `name`, `productImages(row)[0]`, `productPrice(row, { formatMoney }).label` (already "From €19.99" when the product sells variants — there is no product `type` flag, and `product.price` alone is a rolled-up from-price), `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count`, `productRibbons(row)`, `productSpecs(row)`. ⚑ **Images and ribbons are objects, either may be empty** — render your placeholder, never a broken `<img>` or a raw object. Field matrix: [`../references/catalog-rendering.md`](../references/catalog-rendering.md). That list is an inventory, not a card design: lead with the one or two fields *these* products are judged on rather than the default name/price/stars trio.
 
-⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), the most-skipped part of catalog rendering, and each links to its filtered listing (`/collection?ribbon_id=<id>`). Never render a bare "Ribbons:" label with nothing after it.
+⚑ **Ribbons belong in both views** — grid and product page. They are the merchant's own merchandising ("Limited", "Last pieces"), and each links to its filtered listing (`/collection?ribbon_id=<id>`). `productRibbons(row)` hands you `{id, name}` **objects** — render `r.name`, key the link on `r.id`; the entry itself in JSX is React's "Objects are not valid as a React child". Never render a bare "Ribbons:" label with nothing after it.
 
 **Rails** (featured row, "new in") are the same hook with a filter (`{ featured: true, per_page: 4 }`) — `featured` is the merchant's own flag, so the rail stays curated store data instead of hardcoded slugs. ⚑ Any filter may legitimately match nothing — render *nothing* then, never a heading over an empty row.
 
 ## Product page
 
 ```jsx
-import { useProduct, useAddToCart, useStoreInfo, useFormatMoney, useStorefront, variantAxes, productImages, imageIndex, productSpecs, findSpec, storefrontErrorCode } from "@/commerce/storefront";
+import { useProduct, useAddToCart, useStoreInfo, useFormatMoney, useStorefront, variantAxes, productImages, imageIndex, productRibbons, productSpecs, findSpec, storefrontErrorCode } from "@/commerce/storefront";
 ```
 
 `useProduct(slug)` (or `{ id }`) owns fetch + variant selection + quantity + price, race-safe, selection mirrored to the URL. ⚑ `status: "not_found"` is a 404 page, not a spinner. ⚑ **Call every hook above the status guards** — they all tolerate a null/loading product precisely so they can sit at the top; a hook after an early `return` crashes React with "Rendered more hooks than during the previous render" the moment the product resolves.
@@ -136,7 +147,7 @@ Build your layout from — all optional, **not one component style**:
   useEffect(() => setPicked(null), [view?.variation?.id]);   // a new variant re-takes the lead
   ```
 
-  ⚑ **Render the main frame from `view.display.image`, not from an index into the strip.** A variation's own image lives on the variation and is usually *not* in `product.images`, so indexing the strip shows the wrong colour the moment a variant is picked. `display.image` is variation-first with a parent fallback and is exactly the same shape as a strip entry (`{src, name, alt}`), which is why `imageIndex` can locate it when it *is* there and return `-1` when it isn't. `active === null` only when the product has no images at all — the one placeholder case.
+  ⚑ **The main frame comes from `view.display.image`, never from an index into the strip.** A variation's image lives on the variation and is usually *not* in `product.images`, so indexing the strip shows the wrong colour as soon as a variant is picked. `display.image` is variation-first with a parent fallback, in the same `{src, name, alt}` shape as a strip entry — which is why `imageIndex` locates it when it is there and returns `-1` when it isn't. `active === null` only when the product has no images at all.
 - **Variant selector** — `variantAxes(view, p.pick)`, one entry per axis:
 
   ```jsx
@@ -162,8 +173,8 @@ Build your layout from — all optional, **not one component style**:
 
   ⚑ **Text for every state, and the gate from the hook.** `buy.state` resolves the precedence — never re-derive `disabled` from your own ternary chain, and never leave a state unworded (the button renders empty). ⚑ `buy.showQuantity: false` means no stepper. 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** — `productSpecs(product)` rows from the admin's *Modifiers*. ⚑ **Look a particular spec up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`. Meta keys are free text typed by whoever set the product up (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and the feature renders its fallback forever. **This is the product page's signature-moment candidate**: pick the two or three keys that carry *this* catalog's meaning and render each as what it is (a weight as a figure, a composition as bars, a provenance beside its place), then let the rest fall through to plain rows in your classes. Not everything into one uniform grey table; not a bespoke widget per row. `[]` means no section at all.
-- **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons are labels, not breadcrumbs.
+- **Specs** — `productSpecs(product)` rows from the admin's *Modifiers*. ⚑ **Look a particular spec up with `findSpec(rows, "care")`**, which ignores case, spaces, `_` and `-`. Meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. **This is the product page's signature-moment candidate**: pick the two or three keys that carry *this* catalog's meaning and render each as what it is (a weight as a figure, a composition as bars, a provenance beside its place), then let the rest fall through to plain rows in your classes. Not one uniform grey table; not a bespoke widget per row. `[]` means no section at all.
+- **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
 - **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
 - **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
 
@@ -175,7 +186,7 @@ import { useCart, useCartLine, CartLine, useCartUI, useFormatMoney, attributesLa
 
 A cart *page* is optional — decide from what the store sells (buy-now straight to checkout reads better for a single-piece store; a grocery basket needs a page).
 
-⚑ Rules: branch on `status`, never on emptiness while loading. Render `cart.coupon_notices` (`[{ code, error, error_code }]` — a coupon that stopped validating) and `cart.removed_items` (`[{ item_key, product_id, reason, code }]` — a product that vanished or was unpublished): render `error`/`reason`, the server's own words, or a line disappears from the bag with no explanation. Render every non-`hidden` line from `cartTotalsLines` rather than hardcoding subtotal/total — a hand-written summary omits discount and tax, then stops adding up the day a coupon or tax rate exists. **A store with any coupons must have a coupon field** (here or in the checkout): `applyCoupon(code)` resolves `{ok: false, message}` for a bad code rather than throwing, so render that message inline. Coupons are admin-only data, redeemable only through a field the customer types into; if none exists, don't seed coupons and don't write "use WELCOME10" in the copy.
+⚑ Rules: branch on `status`, never on emptiness while loading. Render `cart.coupon_notices` (`[{ code, error, error_code }]` — a coupon that stopped validating) and `cart.removed_items` (`[{ item_key, product_id, reason, code }]` — a product that vanished or was unpublished): render `error`/`reason`, the server's own words, or a line disappears from the bag with no explanation. Render every non-`hidden` line from `cartTotalsLines` rather than hardcoding subtotal/total — a hand-written summary omits discount and tax, then stops adding up the day a coupon or tax rate exists. **A store with any coupons must have a coupon field** (here or in the checkout) — they are admin-only data, redeemable only through a field the customer types into. `applyCoupon(code)` resolves `{ok: false, message}` for a bad code rather than throwing, so render that inline. No field means no coupons: don't seed them, don't name a code in the copy.
 
 ⚑ **`pending` is one row's flag**: it goes true when that row's debounced request leaves and false only after the new cart view lands — so disable and mark only that row (`disabled={l.pending}`, `aria-busy` on the row), never the whole cart. `status` never returns to `"loading"` for a mutation; there is deliberately no cart-wide busy flag. ⚑ **Repeated controls need unique accessible names** — three "Remove" buttons name nothing; put the line in the label.
 
@@ -207,13 +218,13 @@ const formatMoney = useFormatMoney();
 ))}
 ```
 
-No shipping estimator here — checkout reprices shipping and tax from the address. An upsell beside the lines needs no query: `p.upsells` / `p.crossSells` from `useProduct` are rows you can render and add with `addItem`, matching "already in the bag" by product id, never by display name (a rename must not break the match). ⚑ **A one-click Add only works on a product with no attributes** — one that sells variants needs a `variation_id`, so `addItem({ product_id })` answers `400 variation_required`; link those tiles to the product page instead of adding from the rail.
+No shipping estimator here — checkout reprices shipping and tax from the address. An upsell beside the lines needs no query: `p.upsells` / `p.crossSells` from `useProduct` are rows you can render and add with `addItem`, matching "already in the bag" by product id, never by display name. ⚑ **A one-click Add only works on a product with no attributes**: one that sells variants answers `400 variation_required`, so link those tiles to the product page instead.
 
 ### If the cart is a drawer
 
 Same hooks, same rows. The drawer's *state* — open/close, Esc, close-on-route-change, open-on-add — is `useCartUI()`; the markup is yours: a trigger in the header (`onClick={ui.toggleCart}`, `aria-expanded={ui.open}`), then `{ui.open && …}` rendering a click-away overlay plus your panel (`role="dialog" aria-modal="true"`, a named close button inside it).
 
-⚑ **Render the drawer conditionally — `{ui.open && …}`.** The classic drawer bug is a panel translated off-screen but still mounted: its buttons stay clickable, tab-able and visible to screen readers. If you keep it mounted to animate the slide, you own that concern — set the `inert` attribute while closed. The overlay is a click-away surface, not the close control.
+⚑ **Render the drawer conditionally — `{ui.open && …}`.** The classic drawer bug is a panel translated off-screen but still mounted: its buttons stay clickable, tab-able and visible to screen readers. If you keep it mounted to animate the slide, set the `inert` attribute while closed. The overlay is a click-away surface, not the close control.
 
 ## Checkout
 
@@ -307,7 +318,7 @@ function AddressFields({ which }) {
 }
 ```
 
-Passing `country` is what makes the **state/province field appear, with the right options**, for the US, Canada and Australia. ⚑ **Never omit that field**: shipping rates and taxes match on country *plus* state, so a form without it mis-prices those orders with no error anywhere. ⚑ Keep each field's `autoComplete` token — it is what makes browser autofill work. Labels here are plain conventions; rename or restyle freely. `c.missingBillingFields` is the live list of what is still missing, if you want per-field marks — arm them on first edit rather than on load, so an untouched form doesn't open covered in "required" marks.
+⚑ **Passing `country` is what makes the state/province field appear**, with the right options for the US, Canada and Australia — and shipping rates and taxes match on country *plus* state, so a form without that field mis-prices those orders with no error anywhere. ⚑ Keep each field's `autoComplete` token; it is what makes browser autofill work. Labels are plain conventions — rename or restyle freely. `c.missingBillingFields` is the live list of what is still missing, if you want per-field marks; arm them on first edit, not on load.
 
 ⚑ **The `stage === "submitted"` guard goes above the empty-cart branch** — placing an order clears the cart before the browser navigates, and without the guard the page flashes an empty bag over a just-placed order.
 
@@ -341,6 +352,6 @@ The cart is optimistic and debounced, so a script that acts faster than it settl
 - [ ] Address form includes the state/province field and every `autoComplete` token.
 - [ ] Cart rows scope busy state to the row; repeated controls have unique accessible names; a drawer uses `useCartUI` and is rendered conditionally on `ui.open`.
 - [ ] Checkout guards `stage === "submitted"` above its empty-cart branch.
-- [ ] The storefront carries the design you settled on before reading this file — design classes plus one or two signature moments per page; 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.
+- [ ] The storefront carries the design you settled on before reading this file — design classes plus one or two signature moments per page; axes and specs rendered by what they are (not one uniform table, not one identical chip row); convention surfaces carry the classes and nothing bespoke.
 
 Then copy this file's `carry_forward` lines (in its front matter) into your working notes, and do not re-read this file.

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

@@ -22,7 +22,7 @@ A fresh install has **no settings and no catalog**. One admin-only, idempotent c
 
 **`store_name` is required on a first seed** — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). **`currency`** is an ISO code (`"EUR"`); formatting follows the viewer's locale, nothing else to set. Explicit values always win, first seed and re-runs alike.
 
-The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, dimensions…) is in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store) — open it only if the catalog needs one of those:
+The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, dimensions…) lives in `api-admin.md` — open it only if the catalog needs one:
 
 ```js
 try {
@@ -45,11 +45,10 @@ try {
         categories: ["Shoes"],                     // get-or-created by display name
         ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
 
-        // Descriptive properties → the product page's spec rows (productSpecs
-        // types each one). NOT variant axes, NOT ribbons. Strings; `_` hides.
+        // Descriptive spec rows (productSpecs). NOT axes, NOT ribbons; `_` hides.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Weight", value: "248 g" },       // "<number> <unit>" → a numeric row
+          { key: "Weight",   value: "248 g" },
         ],
 
         attributes: [                              // the axes → one selector each
@@ -76,7 +75,7 @@ try {
 
 **Running this through a code-execution tool? Return `res.data`, never the raw response** — the raw response carries circular objects and fails `Converting circular structure to JSON` *even when the seed succeeded*; a thrown error needs `e.response?.data` for the same reason.
 
-Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface. **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. **Limits:** ≤100 products, ≤500 variations, ≤50 locations per call. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written.
+Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface. **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written; per-call limits (≤100 products, ≤500 variations, ≤50 locations) and the full key list are in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store).
 
 The response reports everything; these matter downstream:
 
@@ -94,16 +93,19 @@ Each location is a scope plus its rates and taxes; locations match in payload or
 
 ```js
 locations: [
-  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard",      cost: 20 }] },
+  { name: "Europe",    continents: ["EU"],    shipping_rates: [{ name: "Standard", cost: 20 },
+                                                               { name: "Express",  cost: 35 }] },
   { name: "Worldwide", rest_of_world: true,   shipping_rates: [{ name: "International", cost: 100 }] },
 ]
 ```
 
+⚑ **Speeds go in one location's `shipping_rates`; zones are separate locations.** Exactly one location matches an address, so several rates in it become the customer's pick at checkout (`shipping_status: "choice_required"`), while a second location with the same scope is simply dead — never matched, its rates never offered.
+
 - **`continents: ["EU"]`** spares you a 51-country list — and `EU` is the *continent* Europe, not the European Union.
-- **`rest_of_world: true`** is the catch-all. There is **no country code meaning "everywhere"** (`["*"]`, `["ALL"]`, alpha-3 like `["USA"]` all fail **400**); other scopes are `countries: ["IL", "DE"]` or `regions: [{ type: "state", code: "US:CA" }]`. Matching is country + state only.
-- A matched location supplies **both** shipping rates and tax groups (`tax_groups`, `shipping_tax`, `free_over` — see the reference below).
+- **`rest_of_world: true`** is the catch-all — there is **no country code meaning "everywhere"**, and improvised ones (`["*"]`, `["ALL"]`, alpha-3 `["USA"]`) fail **400**. The narrower scope is `countries: ["IL", "DE"]`; matching is country + state only.
+- The matched location supplies the taxes too (`tax_groups`, `shipping_tax`) and `free_over` zeroes a rate above a subtotal — reference below.
 
-**The catch-all trap.** Passing any `locations` suppresses the seeded worldwide fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. Plausibly intended, so it is a warning, not an error: **read `warnings` on every seed** and either add a `rest_of_world` location or state the restriction to the user. If the brief named tiered rates, assert them once by pricing a cart against one address per zone (`set-shipping-address` → `available_shipping_methods`; a `[]` means no location matched).
+**The catch-all trap.** Passing any `locations` suppresses the seeded worldwide fallback, so scoped locations with nothing behind them answer `shipping_not_available` to every other address. Plausibly intended, so it warns rather than fails: **read `warnings` on every seed** and either add a `rest_of_world` location or state the restriction to the user. If the brief named tiered rates, price a cart against one address per zone to check them (`set-shipping-address` → `available_shipping_methods`; `[]` means no location matched).
 
 Continent codes in full, state regions, tax binding, VAT-on-shipping, day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
@@ -115,7 +117,7 @@ Continent codes in full, state regions, tax binding, VAT-on-shipping, day-2 edit
 
 Online card payments are **off by default**: the seeded store takes the manual `offline` method and is complete and payable — the order goes on-hold and `/order-received` renders the gateway's payment instructions, no code, no credentials. **Enable `card` only if a provider is wired in the same stretch of work**: an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it.
 
-`payment_methods` is the on/off switch — the listed slugs are enabled, every other row disabled; it is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later switch.
+`payment_methods` is the on/off switch — the listed slugs are enabled, every other row disabled. ⚑ **Never write `enabled` on the `commerce.PaymentGateway` row instead.** **Seeding need not happen all at once:** every key is independent, so re-call `commerce/seed-store` whenever one slice of configuration changes, carrying only that slice — `{ payment_methods: ["offline", "card"] }` is a complete standalone call, as valid on a live store weeks later as during the install (`store_name` is required only on a store's first seed).
 
 | The request says | Decision |
 |---|---|

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

@@ -7,6 +7,7 @@ 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(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."
+  - "Ribbons are objects `{id, name}` and the field can be absent — go through productRibbons(product), which works on a listing row and on useProduct's product alike."
 ---
 
 # Rendering the catalog: listing and product page
@@ -32,13 +33,43 @@ A listing **row** is the product record (minus paywalled fields) plus resolved `
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `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 |
+| **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | `{id, name}` objects on a row; `get-product` returns the records beside the product, which `useProduct` normalizes and attaches |
 | **`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 — only via `commerce/storefront-account` `get-download` |
 
+### What each field actually holds
+
+Most of the interesting ones are **arrays of objects** where a card tends to
+assume strings — `{p.ribbons[0]}` in JSX is React's *"Objects are not valid as a
+React child"*, `<img src={p.images[0]}>` a broken image on every product at
+once. The whole list, so none of it has to be read out of the backend:
+
+| Field | Shape | Render it through |
+|---|---|---|
+| `images[]` | `{src, name, alt}` — **objects**; `[]` is legitimate | `productImages(product)` |
+| `ribbons[]` | `{id, name}` — **objects**; the field is **absent**, not `[]`, when no row on the page carries one | `productRibbons(product)` |
+| `meta_data[]` | `{key, value}` — keys are free text | `productSpecs(product)` + `findSpec` |
+| `attributes[]` | `{attribute_id, name, position, options: string[]}` — one entry per **axis** | `variantAxes(view, pick)` |
+| `default_attributes[]` | `{attribute_id, name, option}` — the merchant's pre-selection | `defaultSelection` (automatic in `useProduct`) |
+| `dimensions` | `{length, width, height}` in the store's unit | — |
+| `category_ids[]`, `ribbon_ids[]` | id **strings** | `category_id` / `ribbon_id` filters |
+| `categories[]` *(get-product)* | full records — `{id, name, slug, parent_id, image, menu_order, count}` | breadcrumb links on `c.id` |
+| `variations[]` *(get-product)* | `{id, product_id, attributes: [{attribute_id, name, option}], price, sale_price, on_sale, sku, image, stock_status, stock_quantity, …}` | `view`, never the list itself (§5) |
+| `reviews` *(get-product)* | `{items: [{id, reviewer, review, rating, verified, created_date}], page, per_page, has_next, average_rating, rating_count}` | — |
+| `upsells[]`, `cross_sells[]` *(get-product)* | `{id, name, slug, price, on_sale, image, stock_status}` — here `image` **is** a plain URL string | — |
+
+The React layer carries all of this as types the hooks name on their `@returns`
+— `StorefrontProduct` and the rest in `src/commerce/utils/types.js`, each hook's
+result in `src/commerce/storefront/types.js` — so an editor answers "what is in
+this field?" on hover. And `useProduct` attaches its resolved `ribbons` to
+`product` in the listing row's `{id, name}` shape, which is why one card
+component can render a row *or* the product page's product. (Ribbon `count` is
+not in that shape: filter counts come from `useRibbons()` / `list-ribbons`,
+which counts only the products the catalog would list.)
+
 ## 2. Two shapes, and three rules the exports own
 
 There is **no product `type` field**. `attributes[]` tells the shapes apart:
@@ -70,7 +101,7 @@ Both lists are inventories of what the data supports — **not a layout and not
 
 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`** — 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.
+- **Both views carry resolved ribbons**, so a card needs no extra call: `productRibbons(product)` reads a listing row and `useProduct`'s product alike (the page can also take `p.ribbons`), and always answers `[{id, name}]` — including when the row has no `ribbons` field at all. Render `r.name`, never the entry itself; the product page's row sits 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`.

package/skills/commerce/references/online-payments.md

@@ -17,6 +17,16 @@ What it does **not** ship is a live provider. Wiring one means **one file** —
 
 Card payments are **off by default** and are the last thing to add, never the first — the rule, the timing and the decision table live in [`../install/03-data.md`](../install/03-data.md). Everything below assumes that decision is made.
 
+## Enabling the gateway — one seed call, at any time
+
+⚑ **Turning `card` on is a `commerce/seed-store` call, never an edit to `commerce.PaymentGateway`.** The gateway row is derived data: the seeder enables every slug you list and disables every one you don't, so writing `enabled` on the record by hand is undone by the next seed and skips the checks the seeder makes.
+
+```js
+await base44.functions.invoke("commerce/seed-store", { payment_methods: ["offline", "card"] });
+```
+
+That is the **whole payload**. `seed-store` is idempotent and every key is independent, so this is as valid on a live store months later as it is during the install: no `products` key means no catalog work, no `locations` key leaves shipping exactly as it is, and `store_name` is only required on a store's very first seed. Drop `"offline"` from the array for a card-only store — the list is the complete set of enabled methods, not an addition to it.
+
 | Function | Backs |
 |---|---|
 | `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` | checkout + payment links: a hosted page for `order.total`, returning `{ url, reference }`, with `order.id`/`order.order_key` on the payment's metadata |

package/src/commerce/storefront/index.js

@@ -41,6 +41,8 @@
  * `productPrice` (the from-price and incomplete-selection range rules),
  * `productImages` + `imageIndex` (an image's position in that list — how a
  * gallery follows the variant selection without owning a second copy of it),
+ * `productRibbons` (ribbons are `{id, name}` objects, not strings — rendering
+ * one straight into JSX is React's "Objects are not valid as a React child"),
  * `productSpecs` + `findSpec` (meta keys are free text, so featuring a
  * particular spec needs a tolerant lookup, not an equality test),
  * `attributesLabel`, `cartTotalsLines` / `orderTotalsLines`,
@@ -49,6 +51,13 @@
  * `storefrontErrorCode` / `storefrontErrorMessage` for the calls you make
  * yourself — every rejection from the client carries a code worth branching on.
  *
+ * **What a field holds** — every catalog shape a page renders from is written
+ * down in `./types.js` (`StorefrontProduct`, `ProductRibbon`, `ProductImage`,
+ * `ProductCategory`, `ProductSummary`, and each hook's result), and the hooks
+ * carry those types on their `@returns`. Read that instead of a backend
+ * function's source; the render rules that go with the shapes stay in the doc
+ * comments here and in the skill's references/catalog-rendering.md.
+ *
  * The catalog and product surfaces are where the design freedom lives: these
  * hooks hand you resolved data, and the rendering is entirely yours.
  */
@@ -85,6 +94,7 @@ export {
   productPrice,
   productImages,
   imageIndex,
+  productRibbons,
   productSpecs,
   findSpec,
   attributesLabel,

package/src/commerce/storefront/types.js

@@ -0,0 +1,120 @@
+/**
+ * What the catalog hooks resolve to — the return shapes of `useProductList`,
+ * `useProduct`, `useCategories` and `useRibbons`, so a page never has to open a
+ * hook (or a backend function) to learn what a field holds.
+ *
+ * **Types only** — JSDoc `@typedef`s, no runtime code. The product shapes
+ * themselves live one layer down in `@/commerce/utils` (framework-free) and are
+ * re-declared here so this file is the only one a React page needs:
+ * `StorefrontProduct`, `ProductRibbon`, `ProductImage`, `ProductCategory`,
+ * `StorefrontVariation`, `ProductSummary`, `ProductReviews`.
+ *
+ * The rendering rules that go with these shapes are in each hook's doc comment
+ * and in the commerce skill's references/catalog-rendering.md — a type says a
+ * ribbon is `{id, name}`, not that an unbuyable variant option renders disabled
+ * rather than hidden.
+ */
+
+/** @typedef {import("../utils/types.js").StorefrontProduct} StorefrontProduct */
+/** @typedef {import("../utils/types.js").StorefrontVariation} StorefrontVariation */
+/** @typedef {import("../utils/types.js").ProductImage} ProductImage */
+/** @typedef {import("../utils/types.js").ProductRibbon} ProductRibbon */
+/** @typedef {import("../utils/types.js").ProductCategory} ProductCategory */
+/** @typedef {import("../utils/types.js").ProductSummary} ProductSummary */
+/** @typedef {import("../utils/types.js").ProductReview} ProductReview */
+/** @typedef {import("../utils/types.js").ProductReviews} ProductReviews */
+/** @typedef {import("../utils/types.js").ProductMeta} ProductMeta */
+/** @typedef {import("../utils/types.js").ProductAttributeAxis} ProductAttributeAxis */
+
+/**
+ * A failed storefront call, as the hooks expose it. `code` is the backend's
+ * stable code (`not_found`, `out_of_stock`, …) — branch on it, render `message`.
+ *
+ * @typedef {object} StorefrontError
+ * @property {string|null} code
+ * @property {string} message
+ */
+
+/**
+ * `useProductList(params, options)` — a catalog listing with its state solved.
+ *
+ * @typedef {object} UseProductListResult
+ * @property {StorefrontProduct[]} products — the current page (accumulated, in `mode: "append"`)
+ * @property {"loading"|"ready"|"empty"|"error"} status — what the page renders from
+ * @property {number} page
+ * @property {number} perPage
+ * @property {boolean} hasNext — true ⇒ render a paging control, or the catalog is capped at one page
+ * @property {number} totalLoaded
+ * @property {boolean} loading
+ * @property {boolean} refreshing
+ * @property {boolean} busy — `loading || refreshing`; what a paging button disables on
+ * @property {StorefrontError|null} error
+ * @property {boolean} isEmpty — never true while loading
+ * @property {object} params — the live `list-products` params
+ * @property {(patch: object) => void} setParams — any change but `page` returns to page 1
+ * @property {() => void} resetParams
+ * @property {() => void} next
+ * @property {() => void} prev
+ * @property {(page: number) => void} goToPage
+ * @property {() => void} loadMore — the paging call in `mode: "append"`
+ * @property {() => void} reload
+ * @property {() => void} reloadQuiet
+ */
+
+/**
+ * `useProduct(ref, options)` — the product page's data and selection lifecycle.
+ * `view` is `resolveSelection`'s render model (`axes`, `display`, `purchasable`,
+ * `addToCart`, `priceRange`, `complete`, `missingAxes` — bind controls to it,
+ * never to `product.*`), and `price` is `productPrice`'s from-price/range rules.
+ *
+ * @typedef {object} UseProductResult
+ * @property {"loading"|"ready"|"not_found"|"error"} status — `"not_found"` is a 404 page, not a spinner
+ * @property {boolean} loading
+ * @property {StorefrontError|null} error — null when the product simply isn't there
+ * @property {boolean} notFound
+ * @property {() => void} reload
+ * @property {StorefrontProduct|null} product — carries the resolved `ribbons`, like a listing row
+ * @property {StorefrontVariation[]} variations — publishable only; `[]` without attributes
+ * @property {ProductCategory[]} categories — resolved records, for a breadcrumb
+ * @property {ProductRibbon[]} ribbons — `{id, name}`, same array as `product.ribbons`
+ * @property {ProductSummary[]} upsells
+ * @property {ProductSummary[]} crossSells
+ * @property {ProductReviews|null} reviews
+ * @property {object|null} view — the resolved selection view
+ * @property {object} selection — `{ [axisKey]: option }`
+ * @property {(axisKey: string, option: string) => void} pick
+ * @property {(selection: object) => void} setSelection
+ * @property {() => void} resetSelection
+ * @property {number} quantity
+ * @property {(n: number) => void} setQuantity
+ * @property {() => void} incQuantity
+ * @property {() => void} decQuantity
+ * @property {number} maxQuantity — respects `sold_individually` and tracked stock
+ * @property {boolean} canIncrease
+ * @property {{label: string, compareAtLabel: string|null, onSale: boolean,
+ *   isFrom: boolean, isRange: boolean, min: number|null, max: number|null}} price
+ */
+
+/**
+ * `useCategories()` — the category tree, roots with `children` nested.
+ *
+ * @typedef {object} UseCategoriesResult
+ * @property {ProductCategory[]} items — always an array
+ * @property {boolean} loading
+ * @property {StorefrontError|null} error
+ * @property {() => void} reload
+ */
+
+/**
+ * `useRibbons()` — the ribbon list for a filter or a "shop by ribbon" nav.
+ * `count` is tallied from the products the catalog would actually list, so
+ * "Gift (12)" and the ribbon's listing agree.
+ *
+ * @typedef {object} UseRibbonsResult
+ * @property {Array<ProductRibbon & {count: number}>} items — always an array
+ * @property {boolean} loading
+ * @property {StorefrontError|null} error
+ * @property {() => void} reload
+ */
+
+export {};

package/src/commerce/storefront/useProduct.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import {
   defaultSelection,
   productPrice,
+  productRibbons,
   resolveSelection,
   selectOption,
   selectionFromParams,
@@ -32,9 +33,15 @@ import { useAsyncData } from "./internal/useAsyncData";
  * flight can never paint over a newer one; and the selection is mirrored to the
  * URL (`?color=Ivory`) so a chosen variant is linkable and survives a reload.
  *
+ * `product` is a `StorefrontProduct` (`src/commerce/utils/types.js`) carrying
+ * the resolved `ribbons` exactly as a listing row does, so one card component
+ * can render from either — `productImages(product)` and
+ * `productRibbons(product)` both hand back objects, never strings.
+ *
  * @param {string|{id: string}} ref slug or `{ id }`
  * @param {{syncSelectionToUrl?: boolean, reviewsPerPage?: number,
  *   initialSelection?: object}} [options]
+ * @returns {import("./types.js").UseProductResult}
  */
 export function useProduct(ref, options = {}) {
   const { syncSelectionToUrl = true, reviewsPerPage, initialSelection } = options;
@@ -47,7 +54,16 @@ export function useProduct(ref, options = {}) {
     { keepPreviousData: false },
   );
 
-  const product = data?.product ?? null;
+  // `get-product` returns the ribbons *beside* the product; a listing row
+  // carries them ON the row. Attach them here so both surfaces read one field
+  // in one shape — `productRibbons(product)` works on a card and on this page —
+  // and normalize to the row's `{id, name}`: the full record's `count` counts
+  // drafts and drifts, so filter counts come from `useRibbons()` instead.
+  const ribbons = useMemo(() => productRibbons(data?.ribbons ?? []), [data]);
+  const product = useMemo(
+    () => (data?.product ? { ...data.product, ribbons } : null),
+    [data, ribbons],
+  );
   const variations = data?.variations ?? [];
 
   // ── selection ──────────────────────────────────────────────────────────────
@@ -141,7 +157,7 @@ export function useProduct(ref, options = {}) {
     product,
     variations,
     categories: data?.categories ?? [],
-    ribbons: data?.ribbons ?? [],
+    ribbons,
     upsells: data?.upsells ?? [],
     crossSells: data?.cross_sells ?? [],
     reviews: data?.reviews ?? null,

package/src/commerce/storefront/useProductList.js

@@ -24,10 +24,17 @@ import { useAsyncData } from "./internal/useAsyncData";
  * legitimately match nothing — render from `isEmpty`, never on the assumption
  * that rows came back.
  *
+ * Each row is a `StorefrontProduct` — the whole published product record, with
+ * `images` as `{src, name, alt}` objects and the resolved `ribbons` as
+ * `{id, name}` objects (both are objects, both may be missing; go through
+ * `productImages` / `productRibbons`). The field list is
+ * `src/commerce/utils/types.js`.
+ *
  * @param {object} [initialParams] `list-products` params (page/per_page and any filter)
  * @param {{mode?: "pages"|"append", perPage?: number, keepPreviousData?: boolean}} [options]
  *   `mode: "append"` accumulates pages for a "load more" / infinite-scroll
  *   catalog; `loadMore()` is then the paging call.
+ * @returns {import("./types.js").UseProductListResult}
  */
 export function useProductList(initialParams = {}, options = {}) {
   const { mode = "pages", perPage: perPageOption, keepPreviousData = true } = options;
@@ -131,7 +138,7 @@ export function useProductList(initialParams = {}, options = {}) {
  * under `children`. One cached call; use it for navigation and for the
  * `category_id` filter on `useProductList`.
  *
- * @returns {{items: Array<object>, loading: boolean, error: object|null, reload: () => void}}
+ * @returns {import("./types.js").UseCategoriesResult}
  */
 export function useCategories() {
   const store = useStorefront();
@@ -140,10 +147,12 @@ export function useCategories() {
 }
 
 /**
- * Ribbons — an ARRAY of `{ id, name, count }`. Labels like "Best Seller" for
- * cards and the product page, and the `ribbon_id` filter's option list.
+ * Ribbons — an ARRAY of `{ id, name, count }` **objects**, for the `ribbon_id`
+ * filter's option list and a "shop by ribbon" nav. A product's own ribbons ride
+ * on the product (`productRibbons(product)`); this is the store's whole set,
+ * with the counts a filter labels itself with ("Gift (12)").
  *
- * @returns {{items: Array<object>, loading: boolean, error: object|null, reload: () => void}}
+ * @returns {import("./types.js").UseRibbonsResult}
  */
 export function useRibbons() {
   const store = useStorefront();

package/src/commerce/utils/index.js

@@ -25,16 +25,21 @@
  * - `address-spec.js` — `addressFieldSpec`: the checkout address form as data,
  *   with country/state options that are always arrays.
  * - `images.js` — `productImages`: images normalized to `{src, name, alt}`.
+ * - `ribbons.js` — `productRibbons`: ribbons normalized to `{id, name}` — they
+ *   are objects, and the field is absent on a listing page that carries none.
  * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows (`key`, `label`,
  *   `titleLabel`, `value`). Match rows by `key`, never by `label`.
+ * - `types.js` — types only: `StorefrontProduct` and the rest of the catalog
+ *   shapes as JSDoc typedefs, so what a field holds is readable from the
+ *   frontend instead of from the backend function's source.
  *
  * Building the storefront in React? Import from **`@/commerce/storefront`** and
  * nothing else — it adds the headless hooks and re-exports the helpers a page
  * actually needs (`variantAxes`, `productPrice`, `productImages`,
- * `productSpecs`, `attributesLabel`, `cartTotalsLines`, `orderTotalsLines`), so
- * one import line covers a page. Neither layer ships any UI: all markup,
- * styling and copy belong to the storefront you build. Use this module directly
- * for non-React code and inside your own custom logic.
+ * `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`,
+ * `orderTotalsLines`), so one import line covers a page. Neither layer ships
+ * any UI: all markup, styling and copy belong to the storefront you build. Use
+ * this module directly for non-React code and inside your own custom logic.
  */
 export * from "./storefront.js";
 export * from "./variants.js";
@@ -43,4 +48,5 @@ export * from "./price.js";
 export * from "./totals.js";
 export * from "./address-spec.js";
 export * from "./images.js";
+export * from "./ribbons.js";
 export * from "./specs.js";

package/src/commerce/utils/ribbons.js

@@ -0,0 +1,51 @@
+/**
+ * Product ribbons, normalized — the merchant's own merchandising labels
+ * ("Best Seller", "Last pieces"), rendered on cards and on the product page.
+ *
+ * Every ribbon is an **object** — `{ id, name }` — never a string, and
+ * `{product.ribbons[0]}` in JSX is React's "Objects are not valid as a React
+ * child" on the first product that carries one. Two more facts a hand-written
+ * `product.ribbons.map(...)` gets wrong: the field is **absent**, not `[]`, on a
+ * listing page where no row carries a ribbon (`list-products` only decorates
+ * when there is something to decorate), and the product page's ribbons arrive
+ * beside the product rather than on it. `productRibbons` takes any of those —
+ * a listing row, `useProduct().product`, the raw `get-product` payload, or the
+ * array itself — and always answers with the same clean array.
+ *
+ * ```jsx
+ * {productRibbons(product).map((r) => (
+ *   <a key={r.id} href={`/collection?ribbon_id=${r.id}`}>{r.name}</a>
+ * ))}
+ * ```
+ *
+ * `[]` means render nothing — never a dangling "Ribbons:" label. A ribbon has
+ * no slug, so a link keys on `r.id`; counts for a filter's labels ("Gift (12)")
+ * come from `useRibbons()` / `list-ribbons`, not from here.
+ */
+
+/**
+ * A product's ribbons as renderable `{ id, name }` entries, de-duplicated.
+ *
+ * @param {object|Array<object|string>|null|undefined} source a listing row, a
+ *   product, the `get-product` payload — anything carrying `ribbons` — or the
+ *   ribbon array itself
+ * @returns {Array<{id: string, name: string}>} may be empty; `name` is the
+ *   merchant's own text, unchanged
+ */
+export function productRibbons(source) {
+  const raw = Array.isArray(source) ? source : (source?.ribbons ?? []);
+  const seen = new Set();
+  const out = [];
+  for (const entry of raw) {
+    // A bare string is accepted because seed-store takes `ribbons: ["Gift"]`,
+    // so that shape turns up in code that moves catalog data around.
+    const name = String((typeof entry === "string" ? entry : entry?.name) ?? "").trim();
+    if (!name) continue;
+    const id = String((typeof entry === "string" ? "" : entry?.id) ?? "");
+    const key = id || `name:${name.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ id, name });
+  }
+  return out;
+}

package/src/commerce/utils/types.js

@@ -0,0 +1,193 @@
+/**
+ * The catalog shapes, written down once — what `list-products` and
+ * `get-product` actually hand a storefront, so the answer to "what is in
+ * `ribbons[0]`?" is here rather than in the backend function's source.
+ *
+ * **This module is types only** — JSDoc `@typedef`s, no runtime code. Editors
+ * resolve them through the `@returns` annotations on the storefront hooks and
+ * helpers (`useProductList().products` is a `StorefrontProduct[]`), and they
+ * read on their own as the field list a card or a product page can render.
+ *
+ * Three shapes are objects where a storefront tends to assume strings — the
+ * whole reason this file exists:
+ *
+ * - `images[]` → `{ src, name, alt }`, and the array may be empty
+ *   (`productImages(product)`)
+ * - `ribbons[]` → `{ id, name }`, and the field may be absent
+ *   (`productRibbons(product)`)
+ * - `meta_data[]` → `{ key, value }` with free-text keys (`productSpecs(product)`)
+ *
+ * …while `ProductSummary.image` (upsells and cross-sells) *is* a plain URL
+ * string. Go through the helpers and the difference stops mattering.
+ *
+ * Field-by-field notes on what each view can render:
+ * the commerce skill's references/catalog-rendering.md.
+ */
+
+/**
+ * A product image. Stored on the product; `alt` falls back to `name`.
+ *
+ * @typedef {object} ProductImage
+ * @property {string} src
+ * @property {string} name
+ * @property {string} alt
+ * @property {number} [position]
+ */
+
+/**
+ * A ribbon as a storefront sees it — a flat merchandising label. The full
+ * `commerce.ProductRibbon` record is admin-only; a storefront gets `{id, name}`
+ * on catalog rows and `{id, name, count}` from `list-ribbons` / `useRibbons()`.
+ *
+ * @typedef {object} ProductRibbon
+ * @property {string} id — the `list-products` `ribbon_id` filter value; ribbons have no slug
+ * @property {string} name
+ */
+
+/**
+ * A category. `get-product` returns the full records; `list-categories` /
+ * `useCategories()` nests the tree under `children`.
+ *
+ * @typedef {object} ProductCategory
+ * @property {string} id
+ * @property {string} name
+ * @property {string} slug
+ * @property {string} [parent_id] — empty at top level
+ * @property {string} [description]
+ * @property {{src: string, alt: string}} [image]
+ * @property {number} [menu_order]
+ * @property {number} [count] — derived, admin-maintained; may drift
+ * @property {ProductCategory[]} [children] — `list-categories` only
+ */
+
+/**
+ * One variant **axis** on a product (Size, Color). A non-empty `attributes[]`
+ * is what makes a product sell variants — there is no `type` field.
+ *
+ * @typedef {object} ProductAttributeAxis
+ * @property {string} attribute_id
+ * @property {string} name
+ * @property {number} [position] — the order axes are presented in
+ * @property {string[]} options — the values this product comes in
+ */
+
+/**
+ * A descriptive property (the admin's *Modifiers*) — never a selector.
+ * Keys are free text: look rows up with `findSpec`, never by `label`.
+ *
+ * @typedef {object} ProductMeta
+ * @property {string} key
+ * @property {string} value
+ */
+
+/**
+ * A published catalog product, as returned by `list-products` (one row) and
+ * `get-product` (`product`). It is the `commerce.Product` record minus the
+ * paywalled download fields, plus the resolved `ribbons`.
+ *
+ * @typedef {object} StorefrontProduct
+ * @property {string} id
+ * @property {string} name
+ * @property {string} slug
+ * @property {"publish"} status — only published products are ever returned
+ * @property {boolean} [featured] — the merchant's own flag, for curated rails
+ * @property {string} [description] — HTML; render as rich text
+ * @property {string} [short_description]
+ * @property {string} [sku]
+ * @property {number|null} [price] — with variants this is a **from** price; render via `productPrice`
+ * @property {number|null} [regular_price]
+ * @property {number|null} [sale_price]
+ * @property {boolean} [on_sale]
+ * @property {string} [date_on_sale_from]
+ * @property {string} [date_on_sale_to]
+ * @property {ProductImage[]} [images] — **objects**, first is primary, may be empty
+ * @property {ProductRibbon[]} [ribbons] — resolved `{id, name}`; **absent** when the page carries none
+ * @property {string[]} [ribbon_ids]
+ * @property {string[]} [category_ids] — rows carry ids only; `get-product` resolves the records
+ * @property {ProductAttributeAxis[]} [attributes] — non-empty ⇒ sells variants
+ * @property {Array<{attribute_id: string, name: string, option: string}>} [default_attributes]
+ * @property {ProductMeta[]} [meta_data] — descriptive rows; use `productSpecs`
+ * @property {"instock"|"outofstock"|"onbackorder"} [stock_status]
+ * @property {boolean} [manage_stock]
+ * @property {number|null} [stock_quantity] — null when stock isn't tracked
+ * @property {"no"|"notify"|"yes"} [backorders]
+ * @property {boolean} [sold_individually] — caps quantity at 1
+ * @property {boolean} [virtual]
+ * @property {boolean} [downloadable] — the files themselves are never public
+ * @property {number} [average_rating]
+ * @property {number} [rating_count]
+ * @property {number} [total_sales]
+ * @property {number|null} [weight]
+ * @property {{length: number, width: number, height: number}} [dimensions]
+ * @property {string[]} [upsell_ids]
+ * @property {string[]} [cross_sell_ids]
+ * @property {string} [created_date]
+ * @property {string} [updated_date]
+ */
+
+/**
+ * One stocked combination of a product's axes. `get-product` only, publishable
+ * only — a product with attributes is sellable **only** through a variation id.
+ * Bind the UI to `resolveSelection`'s view, not to this list.
+ *
+ * @typedef {object} StorefrontVariation
+ * @property {string} id
+ * @property {string} product_id
+ * @property {Array<{attribute_id: string, name: string, option: string}>} attributes
+ * @property {"publish"|"private"|"draft"} [status]
+ * @property {string} [sku]
+ * @property {number|null} [price]
+ * @property {number|null} [regular_price]
+ * @property {number|null} [sale_price]
+ * @property {boolean} [on_sale]
+ * @property {ProductImage|string|null} [image] — variation-owned, usually **not** in `product.images`
+ * @property {"instock"|"outofstock"|"onbackorder"} [stock_status]
+ * @property {"yes"|"no"|"parent"} [manage_stock]
+ * @property {number|null} [stock_quantity]
+ * @property {"no"|"notify"|"yes"} [backorders]
+ * @property {number|null} [weight]
+ * @property {{length: number, width: number, height: number}} [dimensions]
+ * @property {string} [description]
+ * @property {boolean} [virtual]
+ * @property {boolean} [downloadable]
+ */
+
+/**
+ * An upsell / cross-sell tile. Deliberately thin — and note `image` is a plain
+ * URL **string** here, not the `{src, name, alt}` object `images[]` carries.
+ *
+ * @typedef {object} ProductSummary
+ * @property {string} id
+ * @property {string} name
+ * @property {string} slug
+ * @property {number|null} price
+ * @property {boolean} on_sale
+ * @property {string} image — URL, `""` when the product has no image
+ * @property {"instock"|"outofstock"|"onbackorder"} stock_status
+ */
+
+/**
+ * One approved review. Reviewer emails are never public.
+ *
+ * @typedef {object} ProductReview
+ * @property {string} id
+ * @property {string} reviewer — display name
+ * @property {string} review
+ * @property {number} rating — 0–5
+ * @property {boolean} verified — the reviewer bought it
+ * @property {string} created_date
+ */
+
+/**
+ * The paged review block that rides along with `get-product`.
+ *
+ * @typedef {object} ProductReviews
+ * @property {ProductReview[]} items
+ * @property {number} page
+ * @property {number} per_page
+ * @property {boolean} has_next
+ * @property {number} average_rating
+ * @property {number} rating_count
+ */
+
+export {};