@base44/app-plugin-commerce 0.3.2 → 0.3.4

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/package.json

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

@@ -112,7 +112,7 @@ Open a file when its work starts — not while planning.
 | [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 33K |
 | [`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) | 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 |

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/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 it **once** as design classes ([below](#design-language--once-before-any-page)) — 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) — 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
 
@@ -70,7 +70,7 @@ function StoreLayout() {
 
 The cost driver of a generated storefront is not wiring — it is decoration repeated inline. Encode identity **once**: in `index.css`, set the palette and type scale, then define the store's recurring surfaces as **10–15 composable classes** in Tailwind's components layer, named in *this* store's language (`.panel`, `.btn-cta`, `.label-mono`, `.field`, `.choice-row`, a heading scale, a price style — whatever *this* store repeats). Pages then carry short class names plus a couple of layout utilities. ⚑ **A utility run that appears twice becomes a class.**
 
-The store's words work the same way: the states these hooks hand you recur across pages (an empty bag, an unbuyable product, an undeliverable address), so write that copy once in the store's voice — a small map per surface, as the sections below show. It is the half of a store's identity a kit cannot ship: "Add to bag" in every store built from this plugin is how they end up reading alike.
+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 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.
 
@@ -90,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. |
@@ -103,23 +104,23 @@ Everything below is already unwrapped — no `.data`, no envelope. `formatMoney`
 ## 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.
@@ -172,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).
 
@@ -217,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 answers `400 variation_required`, so link those tiles to the product page instead.
+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
 
@@ -351,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…) lives in `api-admin.md` — open it only if the catalog needs one:
+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, upsells…) lives in `api-admin.md` — open it only if the catalog needs one:
 
 ```js
 try {
@@ -45,10 +45,14 @@ try {
         categories: ["Shoes"],                     // get-or-created by display name
         ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
 
+        weight: 0.248,                             // real fields, in the store's units —
+        dimensions: { length: 31, width: 12, height: 11 },   // never a meta_data row
+
         // Descriptive spec rows (productSpecs). NOT axes, NOT ribbons; `_` hides.
+        // Qualities only — a weight or a size here is a string nothing can read.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Weight",   value: "248 g" },
+          { key: "Care",     value: "Machine wash cold" },
         ],
 
         attributes: [                              // the axes → one selector each
@@ -57,8 +61,9 @@ try {
         ],
         default_options: { Size: "42", Color: "Black" },
         variations: [                              // omit entirely → all combos auto-generated
-          { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
+          { options: { Size: "41", Color: "Black" }, stock_quantity: 4, weight: 0.242 },
           { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
+            weight: 0.254,                          // per variant, never inherited from the parent
             image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
         ],
       },
@@ -136,9 +141,4 @@ Online card payments are **off by default**: the seeded store takes the manual `
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
 - [ ] Cards off, or on with the provider file copied whole.
 
-Record these lines in your working notes; do not re-read this file.
-
-- Product slugs come from the seed response's `catalog.products[]` — link pages by slug, never by a client-side map.
-- Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer.
-- Turning card payments on or off later is one more seed call: `{ payment_methods: ["offline", "card"] }`.
-- Seed-time `locations` is THE shipping path; patching `commerce.ShippingTaxLocation` is the day-2 route.
+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/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

@@ -55,6 +55,8 @@ A kit update re-copies `shared/commerce/` and restores the stub — re-run the c
 
 Checkout (`place-order`, `card` gateway) creates the order `pending`, runs `createCardPayment`, stores its `reference` on the order and redirects to `url`; return URLs carry `order_id`/`order_key`/`payment=`. Confirmation is **two idempotent paths** (the second a no-op): the customer return (`/order-received` → `commerce/payments` `complete-return` → `checkCardPaymentPaid` → `processing` with all side-effects; `useOrderReturn` is that page in one hook) and the webhook (covers the closed tab). `create-link` mints a fresh page for any unpaid order the same way; `admin-refunds` `refund_payment: true` calls `refundCardPayment` **before** writing locally (unimplemented → `501`; record without the flag instead). Gateway enabled with no provider behind it → `503 no_card_payment_provider`; every other payment option is **manual** (on-hold, the option's description as payment instructions) and needs no code.
 
+⚑ **Card payment cannot complete in the preview pane.** Providers serve their payment page `frame-ancestors 'none'`, so the redirect dead-ends in the frame. `useCheckout`'s `placeOrder` refuses up front — `{ ok: false, error: { code: "card_payment_in_preview" } }`, nothing created — because `place-order` takes the order and its stock hold *before* minting the payment page, and an attempt that dies at the redirect would strand an unpayable order. Manual gateways are unaffected. **Test card checkout in the published store**; a card flow that appears to do nothing in preview and works published is this, not broken provider wiring.
+
 ## Implementation rules
 
 For a **custom** provider (the shipped files already obey all of these):

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/useCheckout.jsx

@@ -9,6 +9,22 @@ import {
   shippingSlice,
 } from "./address";
 
+/**
+ * Card payment cannot complete in the app builder's preview pane. The
+ * provider's payment page is a full-page redirect and providers serve theirs
+ * `frame-ancestors 'none'`, so the redirect navigates the pane, the provider
+ * refuses to render in it, and checkout looks like it silently did nothing. A
+ * storefront runs framed in exactly one place, so "framed" is read as "preview".
+ */
+function inPreview() {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+
 const EMPTY_ADDRESS = Object.freeze({
   first_name: "",
   last_name: "",
@@ -70,6 +86,12 @@ function resolvePaymentMethod(gateways, picked) {
  *   handle the result yourself (a manual result carries
  *   `result.payment_instructions`).
  *
+ *   **A card order will not place from the preview pane** — providers refuse to
+ *   be framed, so the redirect can only dead-end there. `placeOrder` resolves
+ *   `{ ok: false, error: { code: "card_payment_in_preview" } }` without
+ *   creating anything; manual gateways are unaffected. Test card checkout in
+ *   the published store.
+ *
  *   Both navigations are **full page loads** (`window.location.assign`): the
  *   provider hop leaves the app, and the receipt boots from the URL alone
  *   (`order_id` + `order_key`), so a reload there is correct and shareable.
@@ -215,6 +237,18 @@ export function useCheckout(options = {}) {
   const placeOrder = useCallback(
     async (extra = {}) => {
       if (placing) return { ok: false, error: { code: "placing", message: "Order already being placed." } };
+      // Refuse a card checkout from the preview pane before the network, not
+      // after it: `place-order` creates the order and takes its stock hold
+      // *before* the payment page exists, so an attempt that can only die at
+      // the redirect would strand a real pending order nobody can pay.
+      if (paymentMethod === "card" && inPreview()) {
+        const error = {
+          code: "card_payment_in_preview",
+          message: "Card payment can't be completed in preview. Open the published store to pay.",
+        };
+        setOrderError(error);
+        return { ok: false, error };
+      }
       // Safe as `onClick={checkout.placeOrder}`: a DOM/React event is not
       // `extra`. Spreading one into the order payload would send a circular
       // SyntheticEvent as order fields — an explicit object still forwards.

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 {};