@base44/app-plugin-commerce 0.2.1 → 0.2.3

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

@@ -32,19 +32,45 @@ try {
     store_name: "Aurora Threads",
     currency: "EUR",
     products: [
-      { name: "Classic T-Shirt",
-        sku: "TEE-CLASSIC",                        // optional; makes re-runs idempotent
-        regular_price: 19.99,
-        stock_quantity: 50,                        // implies manage_stock
-        categories: ["Clothing"],                  // get-or-created by display name
-        ribbons: ["Best Seller"],
-        images: ["https://…/tee.jpg"],             // URLs or { src, alt } — see Images below
-        short_description: "A soft, breathable everyday tee.",
-        description: "<p>Cut from combed cotton…</p>",     // HTML, rendered as rich text
-      },
+      // ── 1. Minimal. `name` is the only required key; a real store wants a
+      //       price too, and everything else below is opt-in.
+      { name: "Linen Scarf", regular_price: 45 },
+
+      // ── 2. Every product key the seeder accepts, on one product. Take the
+      //       lines a product actually needs and drop the rest — there is no
+      //       "complete" product to fill in.
       { name: "Runner Sneaker",
-        sku: "SNK-RUN",
+        sku: "SNK-RUN",                            // optional; makes re-runs idempotent
+        slug: "runner-sneaker",                    // derived from name when omitted
+        status: "publish",                         // draft | pending | private | publish (seeder defaults to publish)
+        featured: true,                            // → useProductList({ featured: true }) rails
+
         regular_price: 89,                         // inherited by variations that don't override
+        sale_price: 79,                            // sets on_sale; the storefront strikes through regular_price
+        date_on_sale_from: "2026-03-01T00:00:00Z", // optional sale window (omit → sale is open-ended)
+        date_on_sale_to: "2026-03-31T23:59:59Z",
+
+        stock_quantity: 12,                        // implies manage_stock: true
+        manage_stock: true,                        // only needed to force tracking with no quantity
+        low_stock_amount: 3,                       // overrides the store's threshold
+        backorders: "no",                          // no | notify | yes
+        sold_individually: false,                  // true → max 1 per order (kills the qty stepper)
+
+        short_description: "Cushioned everyday runner.",
+        description: "<p>Cut from recycled knit…</p>",      // HTML, rendered as rich text
+        images: ["https://…/sneaker.jpg"],         // URLs or { src, alt } — see Images below
+
+        categories: ["Shoes"],                     // get-or-created by display name
+        ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
+
+        // Descriptive properties → the spec table (`productSpecs(product)`).
+        // NOT variant axes and NOT ribbons: they describe the product, they
+        // don't select anything. Values are strings; a leading `_` hides a row.
+        meta_data: [
+          { key: "Material", value: "Recycled knit upper" },
+          { key: "Care", value: "Machine wash cold" },
+        ],
+
         attributes: [                              // the axes → one selector each in the storefront
           { name: "Size", options: ["41", "42"] },
           { name: "Color", options: ["Black", "White"] },
@@ -55,6 +81,21 @@ try {
           { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
             image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
         ],
+
+        weight: 0.8,                               // store's weight/dimension units
+        dimensions: { length: 30, width: 20, height: 12 },
+        tax_status: "taxable",                     // taxable | none
+        tax_group: "Products",                     // a tax group from the matched location
+
+        virtual: false,                            // true → no shipping (a service, a booking)
+        downloadable: false,                       // ↓ the three download keys apply only when true
+        downloads: [{ name: "Care guide", file_url: "https://…/care.pdf" }],
+        download_limit: 3,                         // -1 / omit = unlimited
+        download_expiry: 30,                       // days after purchase
+
+        // Accepted, but they take Product *ids* — which only exist after this
+        // call. Cross-link in a later admin-products update, not here.
+        upsell_ids: [], cross_sell_ids: [],
       },
     ],
     coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],
@@ -69,6 +110,8 @@ try {
 
 **Running this through a code-execution tool? Return `res.data`, never the raw response.** `invoke` resolves to the raw HTTP response, which carries circular request/response objects — `return res` (or stringifying a thrown error whole) fails with `Converting circular structure to JSON` *even when the seed succeeded*, and a thrown error needs `e.response?.data` for the same reason.
 
+**The two products above are the range, not a template.** `name` is the only required key: every other line is opt-in, and each product in the array picks its own set independently — a plain product stays two keys long next to a fully specified one, and the fields it omits simply don't apply to it (no attributes ⇒ it sells no variants; no `meta_data` ⇒ no spec table; no `downloads` ⇒ nothing to deliver). Seed each product with the keys its own catalog entry actually has, and leave the rest out rather than padding with empty values.
+
 Reference taxonomy by **display name** (categories, ribbons, attributes, options) — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface instead of vanishing.
 
 **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry after a timeout, or to seed into a store that already has products. **Limits:** ≤100 products, ≤500 variations per call, ≤50 per product, ≤50 locations. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]`, a modified schema **422** `schema_incompatible` — both before anything is written.
@@ -76,8 +119,8 @@ Reference taxonomy by **display name** (categories, ribbons, attributes, options
 The response reports everything; these matter downstream:
 
 ```jsonc
-{ "catalog": { "products_created": 2, "variations_created": 3,
-    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 3 }] },
+{ "catalog": { "products_created": 2, "variations_created": 2,
+    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 2 }] },
   "store_name": { "value": "Aurora Threads", "action": "created" },
   "payment_methods": null,          // null = the default (offline on, card off)
   "warnings": [] }                  // always present; read it — see the shipping section
@@ -97,7 +140,7 @@ locations: [
 ```
 
 - **`continents: ["EU"]`** spares you a 51-code country list. The seven codes are `AF` `AN` `AS` `EU` `NA` `OC` `SA`, and `EU` is the *continent* Europe, not the European Union. An unknown code fails `400 invalid_payload` with the known list.
-- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`.
+- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`, and there is **no country code that means "everywhere"**: `countries: ["*"]`/`["ALL"]`/`["ROW"]`, and alpha-3 codes like `["USA"]`, are rejected **400** (every scope code is validated against the matcher's own country/continent/state data).
 - Other scopes: `countries: ["IL", "DE"]`, or explicit `regions: [{ type: "state", code: "US:CA" }]`. Matching is **country + state only** — no postcode or city rules exist.
 - One matched location supplies **both** the shipping rates and the tax groups: `shipping_rates: [{ name, cost, free_over? }]`, `tax_groups: [{ name, rates: [{ name, rate }] }]`, `shipping_tax: { type: "percent"|"fixed", value }`.
 
@@ -133,16 +176,16 @@ Both failure modes are silent at seed time and visible only in the store, so che
 
 | What the request says | Decision |
 |---|---|
-| A provider is named or a key handed over ("connect Stripe") | wire it, then enable `card` — whenever convenient; it blocks nothing |
-| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: ask for the provider + key **after** the store works |
+| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient; it blocks nothing |
+| Selling online implied, no provider named | cards are a reasonable read of *what* to offer, never of *when*: raise the provider **after** the store works |
 | Paid another way (transfer, COD, invoice, pickup, quotes) | nothing to do — the default already is exactly this |
 | Payments not mentioned at all | leave the default and **mention it at handover** |
 
-**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so asking a user to fetch a secret key before their store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
+**Timing: late, never the opening move.** Payments have no dependency edge into anything — the admin, the seed and the entire buy path down to `place-order` work with no provider — so putting the provider connection before the store exists only stalls the build. Any instruction that treats a payment provider as a required install step is superseded by this section.
 
 **Say where payments landed** in your handover summary, including "offline only, cards off". A store's owner should never discover their payment configuration from a customer who couldn't pay.
 
-*Only for a store that opted into cards:* wiring is a **file copy, not code you write** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation; copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy), store the provider secret as an app secret, register `https://<app-domain>/functions/commerce/payment-webhook` with the provider, then enable the gateway. Steps, other providers and the webhook model: [`../references/online-payments.md`](../references/online-payments.md).
+*Only for a store that opted into cards:* **if it is Stripe, the code is already written** — `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation, used **as-is**. Copy it over `base44/shared/commerce/card-payment.ts` (`fs.copyFileSync`, whole file — never a partial edit, which leaves duplicate exports and breaks every commerce function's deploy) and enable the gateway with `payment_methods: ["offline", "card"]`. Nothing in it needs filling in and no key belongs in the code; it reads the credential the app's Stripe connection publishes. Any other provider means implementing four functions in that one file — [`../references/online-payments.md`](../references/online-payments.md).
 
 ## Done — forget this file
 
@@ -150,7 +193,7 @@ Both failure modes are silent at seed time and visible only in the store, so che
 - [ ] `warnings` in the response is empty, or every warning is deliberate and stated to the user.
 - [ ] Shipping is expressed in `locations` (with a catch-all if the store ships worldwide), not patched into entities afterwards.
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
-- [ ] Cards are either off, or on with a provider wired (file copied whole, secret stored, webhook registered).
+- [ ] Cards are either off, or on with the provider file copied whole and the `card` gateway enabled.
 - [ ] Product slugs from `catalog.products[]` recorded, and the storefront links by them.
 - [ ] If the brief named tiered rates, each named region prices to its rate (the `set-shipping-address` check above).
 

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

@@ -1,7 +1,7 @@
 ---
 stage: reference
 read_when: "You are asking which fields a card or a product page can actually show, or hit a variant edge case (unavailable combinations, attributes with no variations, price ranges, linkable selections)."
-skip_when: "The listing and product page render correctly from useProductList / useProduct and the blocks — the quick start in ../install/02-storefront.md covers the happy path."
+skip_when: "The listing and product page render correctly from useProductList / useProduct and the render-model helpers — the quick start in ../install/02-storefront.md covers the happy path."
 forget_when: "Cards and the product page render the fields you intended, variant selection resolves to a variation, and add-to-cart succeeds."
 carry_forward:
   - "There is no product `type` field: a non-empty `attributes[]` is what makes a product sell variants, and such a product is only sellable via a `variation_id`."
@@ -31,7 +31,7 @@ A listing **row** is the product record itself (minus paywalled fields) plus res
 | `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`; every entry is an **object** — §2 |
 | `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
 | `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`<ProductSpecsBlock/>` renders them) |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into spec-table rows) |
 | **`ribbons`** (resolved), `ribbon_ids`, `category_ids` | ✅ | ✅ | Rows carry `{id, name}` ribbons; `get-product` returns the full records |
 | **`categories`** (resolved) | ❌ *ids only* | ✅ | §6 to add them to rows |
 | **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | Why a product with variants can't be fully priced from a row |
@@ -53,14 +53,14 @@ A product with attributes is **only** sellable through a variant: `add-item` wit
 Three rules used to be prose here and are now enforced by exports — use them and they can't drift between views:
 
 - **From-price.** `admin-products` (and the seeder) roll a parent's `regular_price`/`price`/`on_sale` up from the cheapest publishable variant on every save, so the parent price is real, sortable and filterable — but it is the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` accept **either** a listing row or a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range on an unresolved page, the exact price once resolved.
-- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` and `<ProductGalleryBlock/>` build on them. Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string, and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`), and an empty array is the *render your placeholder* signal — `useProductGallery` builds on them (`hasImages`). Passing the object itself to an `<img src>` fails the load and shows the placeholder for every product in the store.
 - **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is a spec table — never a selector, never a ribbon.
 
 ## 3. What each view renders
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page. The card is deliberately the one thing no block ships — it is the most identity-defining component in a storefront.
+**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page — like every other piece of storefront UI, the card is entirely yours to design.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except layout and styling has a block: `<ProductGalleryBlock/>`, `<VariantSelectorBlock/>`, `<AddToCartBlock/>`, `<ProductSpecsBlock/>`, `<BreadcrumbsBlock/>`, `<ReviewsBlock/>`, `<ProductStripBlock/>`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
 
 ## 4. Ribbons — in **both** views
 
@@ -73,7 +73,7 @@ Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categorie
 
 ## 5. Variant selection
 
-The one interaction agents reliably get wrong. `<VariantSelectorBlock view={view} onPick={pick} />` encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable is rendered **disabled, not removed**. Take the block; drop to the hook only for different *structure* (`renderOption` covers swatches).
+The one interaction agents reliably get wrong. `variantAxes(view, pick)` hands you the render-ready model that encodes the rule: **one control per axis, never a list of variations** (`Red / S`, `Red / M`, … is `n × m` noise that hides the product's structure), and an option that isn't buyable renders **disabled, not removed** (`o.disabled`; `o.outOfStock` stays visible, just marked). Map it to any control — buttons, swatches, dropdowns — and call `o.pick()` on select.
 
 Underneath, `useProduct` composes the framework-free helpers in `src/commerce/utils/variants.js` — `defaultSelection` → `selectOption` on a click → `resolveSelection` for the view. Every `product.attributes[]` entry is an **axis** in `position` order; every `variations[]` record is one combination. Bind the UI to `view`, not to `product.*`, or a selection changes nothing:
 

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

@@ -2,9 +2,10 @@
 stage: reference
 read_when: "The store opted into card payments and you are wiring the provider NOW."
 skip_when: "The store takes offline payments (the default) — nothing here applies; the decision itself lives in ../install/03-data.md."
-forget_when: "A test payment reaches /order-received as paid, or the provider file is copied, the secret stored, the webhook registered and the `card` gateway enabled."
+forget_when: "A test payment reaches /order-received as paid, or the provider file is copied and the `card` gateway is enabled."
 carry_forward:
   - "Wiring a provider = replace shared/commerce/card-payment.ts WHOLE (copy the shipped card-payment.<provider>.ts over it) — a partial edit breaks every commerce function's deploy with duplicate exports."
+  - "Stripe: the shipped card-payment.stripe.ts is used as-is once the app is connected to Stripe — connecting is outside the kit. Enabling the `card` gateway is the seed call."
   - "Only the provider can say an order is paid: confirmation always goes through checkCardPaymentPaid against the provider's API."
 ---
 
@@ -34,11 +35,9 @@ fs.copyFileSync(
 );
 ```
 
-Then three steps, in order:
+…and **enable the gateway**: `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }`. The `card` row is seeded off, so that call is what makes card payment visible at checkout — the usual reason a wired provider "doesn't show up".
 
-1. **Secret** — store the merchant's Stripe **secret key** as the `STRIPE_SECRET_KEY` app secret (backend env; never in code, never in an entity) and redeploy the backend functions so they see it. Test keys (`sk_test_…`) work end to end.
-2. **Webhook endpoint** — register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for `checkout.session.completed` (dashboard, or `POST https://api.stripe.com/v1/webhook_endpoints` with `url` + `enabled_events[]` using the same secret key). **There is no signing secret to store**: the shipped `parseWebhook` treats events as nudges verified against Stripe's API (see below).
-3. **Enable the gateway** — `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }`. It is seeded off, so none of the above is visible at checkout until this runs.
+That is the whole of it. The file expects the app to be connected to Stripe and reads the secret key that connection publishes; **connecting the app is outside this kit and not described here.** Nothing in the file needs filling in, and no key belongs in the code. A missing key is not silent — checkout answers `503 no_card_payment_provider`.
 
 A kit update re-copies `shared/commerce/` and restores the stub — re-run the copy after updating. A different provider ships the same way (`card-payment.<provider>.ts` beside the stub); until one does, implement the four functions against its API per the rules below, with the Stripe file as the worked model.
 
@@ -56,7 +55,7 @@ With the gateway enabled and no provider behind it, picking Credit card answers
 For a **custom** provider (the shipped files already obey all of these):
 
 - **Write `card-payment.ts` whole** — one write of the complete file, never a `find_replace` into the stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"). The fix is always the whole-file write — which is also why the shipped provider files exist.
-- **Credentials come from backend env** (`Deno.env.get(...)`) — never an entity, never the client — and are read **lazily inside the call**, so a store with the file but no secret yet answers a clean 503 instead of failing to boot every function that imports it. Env vars are injected at deploy time: after adding a secret, redeploy.
+- **Credentials come from backend env** (`Deno.env.get(...)`) — never an entity, never the client — and are read **lazily inside the call**, so a store with the file but no credential yet answers a clean 503 instead of failing to boot every function that imports it.
 - **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference` **and** check the payment names this order (its metadata `order_id` vs `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
 - **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` **and** `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
 - **Amounts**: `order.total` is in display units (`12.34`) with `order.currency`; convert to the provider's minor units yourself, remembering the zero-decimal currencies.

package/skills/commerce/references/reviews.md

@@ -1,15 +1,15 @@
 ---
 stage: reference
-read_when: "You need review behaviour beyond dropping in <ReviewsBlock/> — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
-skip_when: "<ReviewsBlock product={p}/> or useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
+read_when: "You need review behaviour beyond useProductReviews — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
+skip_when: "useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
-  - "Reviews are part of the happy path: one block. The confirmation copy must come from the submit response, never hardcoded."
+  - "Reviews are part of the happy path: one hook. The confirmation copy must come from the submit response, never hardcoded."
 ---
 
 # Reviews
 
-Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and now the UI does too. Unless the store explicitly doesn't want them, put them on the product page — it is one line: `<ReviewsBlock product={product} />` (plus `policy` / `user` below). For custom markup take the hook it composes, `useProductReviews(product, { policy, user, requireRating, perPage })` — the list, the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc.
+Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the whole UI contract is one hook. Unless the store explicitly doesn't want them, put them on the product page: `useProductReviews(product, { policy, user, requireRating, perPage })` — the list with paging (`items`, `hasNext`/`loadMore`), the aggregates (`averageRating`, `ratingCount`), the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc. The markup around it — stars, rows, the form — is yours, like all storefront UI.
 
 ## What ships
 
@@ -20,7 +20,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 
 ## The `policy` prop
 
-`policy` is the store's review rule as one prop, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`<ReviewsBlock product={p} policy="login" user={user} />`) — the stricter policies need it:
+`policy` is the store's review rule as one option, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`useProductReviews(product, { policy: "login", user })`) — the stricter policies need it:
 
 | `policy` | Who may submit | Blocked as |
 |---|---|---|

package/skills/commerce/references/shipping-and-tax.md

@@ -103,6 +103,8 @@ A payload carrying `locations` **suppresses** the seeded "Rest of the world" fal
 
 `rest_of_world: true` is the catch-all *instead of* a scope — combining it with `countries`/`continents`/`regions` is a payload error, not a merge. (An empty `regions: []` still works and means the same.)
 
+**There is no country code for "everywhere".** `countries: ["*"]`, `["ALL"]`, `["ROW"]` and alpha-3 codes like `["USA"]` are all rejected **400** `invalid_payload` — every scope code is checked against the same static data the matcher uses (`US`/`IL`/`DE` for countries, the seven continent codes, `US:CA` for states), so a code that could never match a real address fails at seed time instead of creating a location that silently matches nothing.
+
 ## Day-2 edits
 
 No admin function owns locations, so there are two routes: **direct CRUD** on `commerce.ShippingTaxLocation` (admin-only RLS, bracket syntax — [`../docs/entities.md`](../docs/entities.md)), where `shipping_rates` is written whole so you must **mint stable `id`s yourself and never renumber existing ones** (orders reference them); or **the merchant's screen**, admin → Settings → Shipping & Tax (`settings/shipping-tax`), which edits regions, rates, groups and shipping tax directly.

package/src/commerce/admin/README.md

@@ -4,8 +4,11 @@ React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
 Tailwind + shadcn/ui + React Router) to get a full store back office.
 
-> Install, mounting & role setup: [`.agents/skills/commerce/install/01-install.md`](../../../.agents/skills/commerce/install/01-install.md) · architecture & operations: the commerce skill, [`.agents/skills/commerce/SKILL.md`](../../../.agents/skills/commerce/SKILL.md)
-> API references: [`.agents/skills/commerce/docs/api-admin.md`](../../../.agents/skills/commerce/docs/api-admin.md), [`.agents/skills/commerce/docs/api-storefront.md`](../../../.agents/skills/commerce/docs/api-storefront.md)
+> Docs live in the commerce skill, and every path below is **relative to that
+> skill folder** (`.agents/skills/commerce/` once installed): install, mounting
+> and role setup are `install/01-install.md`; the map for everything else is
+> `SKILL.md`; the API references are `docs/api-admin.md` and
+> `docs/api-storefront.md`.
 
 ## Mounting
 
@@ -39,7 +42,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
    catalog — the store counts as ready and this screen never shows; see
-   `.agents/skills/commerce/install/03-data.md`.
+   the commerce skill's install/03-data.md.
 
 ## External touchpoints
 

package/src/commerce/admin/layout/AuthGuard.jsx

@@ -24,7 +24,7 @@ const AUTH_CHECK_TIMEOUT_MS = 8000;
 
 /**
  * Blocks the admin UI unless the caller is an authenticated user with
- * role === "admin". Do NOT weaken this check — see .agents/skills/commerce/install/01-install.md.
+ * role === "admin". Do NOT weaken this check — see the commerce skill's install/01-install.md.
  * (Server-side RLS + requireAdmin() in functions enforce this independently.)
  *
  * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants

package/src/commerce/admin/pages/products/Reviews.jsx

@@ -263,7 +263,7 @@ export default function Reviews() {
 /**
  * The one server-enforced review setting: everything else (login-gating,
  * verified-buyers-only, required ratings) is storefront policy — see
- * .agents/skills/commerce/references/reviews.md.
+ * the commerce skill's references/reviews.md.
  */
 function AutoApproveToggle() {
   const settings = useSettings();

package/src/commerce/admin/pages/settings/InventorySettings.jsx

@@ -51,7 +51,7 @@ export default function InventorySettings() {
             <p className="text-xs text-muted-foreground">
               Hold stock for unpaid orders for this many minutes. When the limit is reached, the
               pending order is cancelled and its stock released. Release runs opportunistically —
-              see .agents/skills/commerce/references/operations.md.
+              see the commerce skill's references/operations.md.
             </p>
           </div>
 

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -209,7 +209,7 @@ export default function PaymentsSettings() {
                   wiring one means implementing the four functions in
                   shared/commerce/card-payment.ts (rules, and a Stripe
                   implementation to paste, in
-                  .agents/skills/commerce/references/online-payments.md; the
+                  the commerce skill's references/online-payments.md; the
                   payment webhook is premade). Enabled without that, picking it
                   at checkout answers 503 no_card_payment_provider.
                   Deliberately not shown to the store operator — it's developer

package/src/commerce/storefront/index.js

@@ -1,15 +1,20 @@
 /**
- * Storefront React layer — hooks and ready-made blocks for the shopfront you
- * build. Ships with the Base44 Commerce Template next to the framework-free
- * `@/commerce/utils` (which it builds on); needs React and nothing else.
+ * Storefront React layer — **headless**: hooks and render-prop components that
+ * own the store's logic and hand you the data; they render nothing and carry
+ * no styling. Every element, class and word of copy in the storefront is
+ * written by you, against these APIs. Ships with the Base44 Commerce Template
+ * next to the framework-free `@/commerce/utils` (which it builds on); needs
+ * React and nothing else.
  *
- * **Two tiers.** The *identity* surfaces are yours to design — home, the
- * collection grid, the product page's layout, the product card, the theme. The
- * *commodity* surfaces ship as working blocks that inherit your theme —
- * checkout, cart lines, totals, coupon field, reviews, order-received, and the
- * product page's internals. Restyle or replace them; never hand-roll their
- * logic. Blocks are compositions of the hooks below, so outgrowing one means
- * rewriting a single region against an API you already know.
+ * The split: **logic is premade, UI never is.** Checkout repricing, variant
+ * resolution, cart state, review policies, order-return verification — done
+ * here, and hand-rolling any of it is where storefront bugs cluster. What a
+ * checkout or a product page *looks like* is the store's identity, and no two
+ * stores should share it — so nothing here emits markup. Each hook returns a
+ * complete view-model (statuses to branch on, ready-to-map arrays, handlers,
+ * error objects), and each doc comment states the render rules that keep the
+ * store correct (e.g. an unbuyable variant option renders *disabled, not
+ * hidden*; a receipt page must render `paymentInstructions`).
  *
  * Setup (once, above every storefront route — it wraps <Routes>; placed as a
  * child of <Routes> React Router throws "is not a <Route> component"):
@@ -18,40 +23,47 @@
  *   import { base44 } from "@/api/base44Client";
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * ## Blocks (drop in, then restyle)
- * `CheckoutBlock` · `CartLinesBlock` · `TotalsBlock` · `CouponFieldBlock` ·
- * `QuantityStepper` · `OrderReceivedBlock` · `ReviewsBlock` ·
- * `AddressFieldsBlock` · `VariantSelectorBlock` · `AddToCartBlock` ·
- * `ProductGalleryBlock` · `ProductSpecsBlock` · `BreadcrumbsBlock` ·
- * `ProductStripBlock` (needs your `renderCard` — no default card ships).
- *
  * ## Hooks
  * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
  *     shared client, cached store info (the ONLY source of payment gateways,
  *     currency and countries), money in the store's currency.
  * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
  *     filters, `refreshing`, and failure as a visible state.
- * - `useProduct` / `useAddToCart` / `useProductPrice` / `useProductGallery` —
- *     the product page: fetch + variant selection + quantity + price + gallery,
- *     race-safe, with `status: "not_found"` and add-to-cart errors handled.
+ * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `useProductPrice` /
+ *     `useProductGallery` — the product page: fetch + variant selection +
+ *     quantity + price + gallery, race-safe, with `status: "not_found"` and
+ *     every add-to-cart failure handled. `variantAxes(view, pick)` (from
+ *     `@/commerce/utils`, re-exported here) turns the resolved view into a
+ *     render-ready model for the selector you write.
  * - `useProductReviews` — the review list and the submit form, with the store's
- *     policy as a prop.
+ *     policy as a prop and field errors matching the server's codes.
  * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
  *     `status`, render `lines` and `notices`), quantity steppers that clamp and
  *     recover, and the coupon field a store with coupons must have.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
  *     checkout: address state with automatic debounced shipping/tax
  *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
- *     named blockers, `placeOrder` with the online-payment redirect handled.
+ *     named blockers, `placeOrder` with both navigations handled (online →
+ *     provider redirect, manual → `/order-received`).
  * - `useAddressForm` / `useCountries` / `useTotalsLines` /
- *     `useCheckoutBlockers` — the address form as fields (state included,
- *     country options never null), one totals projection for cart and order,
- *     and blocker codes turned into copy.
- * - `ShippingMethodPicker` / `PaymentMethodPicker` — headless (render-prop)
- *     wrappers over the two choices that are store data, never hardcoded.
- * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
+ *     `useCheckoutBlockers` — the address form as a field spec you map to your
+ *     own inputs (state included, country options never null), one totals
+ *     projection for cart and order, and blocker codes turned into copy.
+ * - `useOrderReturn` — the mandatory `/order-received` page in one hook:
+ *     status, order, `lines`, `paymentLink`, `paymentInstructions`, noindex.
  * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
  *     meta and product structured data; receipts are `noindex`.
+ *
+ * ## Render-prop components (headless — children is a function, no markup ships)
+ * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
+ *     that are store data, never hardcoded, with their branching enumerated.
+ * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
+ *     `lines.map(...)` never calls a hook in a loop.
+ *
+ * ## Helpers re-exported from `@/commerce/utils`
+ * - `variantAxes(view, pick)` — axes → options with selected/disabled/stock
+ *     state derived, for the variant selector you write.
+ * - `productSpecs(product)` — `meta_data` → spec-table rows.
  */
 export {
   StorefrontProvider,
@@ -62,7 +74,7 @@ export {
   useCart,
 } from "./StorefrontProvider";
 export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
-export { useOrderReturn } from "./useOrderReturn";
+export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
 export {
   REQUIRED_BILLING_FIELDS,
@@ -73,18 +85,18 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart } from "./useProduct";
+export { useProduct, useAddToCart, useAddToCartButton } from "./useProduct";
 export { useProductPrice, useMoney } from "./useProductPrice";
 export { useProductGallery } from "./useProductGallery";
 export { useProductReviews } from "./useProductReviews";
 
 // ── cart & checkout ────────────────────────────────────────────────────────
-export { useCartLine, useCoupon } from "./useCartLine";
+export { useCartLine, useCoupon, CartLine } from "./useCartLine";
 export { useAddressForm, useCountries } from "./useAddressForm";
 export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotalsLines";
 
 // ── SEO ────────────────────────────────────────────────────────────────────
 export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
 
-// ── blocks (default markup for the commodity surfaces) ─────────────────────
-export * from "./blocks";
+// ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
+export { variantAxes, productSpecs } from "@/commerce/utils";

package/src/commerce/storefront/useAddressForm.js

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useCallback, useMemo } from "react";
 import { addressFieldSpec } from "@/commerce/utils";
 import { useStoreInfo } from "./StorefrontProvider";
 import { useCheckoutContext } from "./useCheckout";
@@ -22,24 +22,47 @@ export function useCountries() {
   return { countries: list, options, loading, error };
 }
 
+/**
+ * Read the new value out of whatever a field's `set` was handed. All three
+ * forms an onChange is plausibly written as work, so a field setter can't be
+ * called "wrong":
+ *
+ *   f.set(e.target.value)        // the value
+ *   f.set(e)                     // the change event  (onChange={f.set})
+ *   f.set(f.key, e.target.value) // key + value, mirroring the top-level set()
+ */
+function newValue(args) {
+  if (args.length >= 2) return args[1];
+  const first = args[0];
+  if (first && typeof first === "object" && "target" in first) return first.target?.value ?? "";
+  return first;
+}
+
 /**
  * useAddressForm — the checkout address form as a field list bound to the
  * guided checkout. Needs a `<CheckoutProvider>` above it.
  *
- *   const { fields, set } = useAddressForm("billing");
+ * Every field is **self-contained** — it carries its own setter, so a `.map`
+ * never has to reach back out of the loop:
+ *
+ *   const { fields } = useAddressForm("billing");
  *   {fields.map(f => (
  *     <label key={f.key}>
  *       {f.label}{f.required && " *"}
  *       {f.type === "select"
- *         ? <select value={f.value} onChange={e => set(f.key, e.target.value)}>
+ *         ? <select value={f.value} onChange={e => f.set(e.target.value)}>
  *             {f.options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
  *           </select>
  *         : <input type={f.type} value={f.value} autoComplete={f.autoComplete}
- *                  onChange={e => set(f.key, e.target.value)} />}
+ *                  onChange={e => f.set(e.target.value)} />}
  *       {f.error && <span role="alert">{f.error}</span>}
  *     </label>
  *   ))}
  *
+ * `f.set` also accepts the raw event (`onChange={f.set}`) or a `(key, value)`
+ * pair; the hook's top-level `set(key, value)` is still there for code that
+ * writes a field outside the map.
+ *
  * Editing a field is all it takes to trigger the shipping/tax recalculation —
  * `useCheckout` debounces and calls `set-shipping-address` once the address is
  * complete enough to price. Two things the field list gets right that a
@@ -49,6 +72,11 @@ export function useCountries() {
  *
  * @param {"billing"|"shipping"} [which]
  * @param {{includeState?: boolean, includePhone?: boolean, includeCompany?: boolean}} [options]
+ * @returns {{fields: Array<{key: string, label: string, type: string,
+ *   value: string, required: boolean, options: Array<object>, error: string|null,
+ *   autoComplete: string, colSpan: number, set: (...args: any[]) => void}>,
+ *   set: (key: string, value: any) => void, values: object, missing: Array<string>,
+ *   complete: boolean, error: object|null, countriesLoading: boolean}}
  */
 export function useAddressForm(which = "billing", options = {}) {
   const checkout = useCheckoutContext();
@@ -56,9 +84,11 @@ export function useAddressForm(which = "billing", options = {}) {
 
   const isBilling = which === "billing";
   const values = isBilling ? checkout.billing : checkout.shipping;
-  const set = isBilling
-    ? (key, value) => checkout.updateBilling({ [key]: value })
-    : (key, value) => checkout.updateShipping({ [key]: value });
+  const { updateBilling, updateShipping } = checkout;
+  const set = useCallback(
+    (key, value) => (isBilling ? updateBilling({ [key]: value }) : updateShipping({ [key]: value })),
+    [isBilling, updateBilling, updateShipping],
+  );
 
   // `place-order` only enforces required fields on billing; a separate shipping
   // address is priced, not validated field-by-field.
@@ -75,6 +105,9 @@ export function useAddressForm(which = "billing", options = {}) {
     return spec.map((f) => ({
       ...f,
       value: values?.[f.key] ?? "",
+      // Self-contained: the field knows its own key, so a .map never has to
+      // reach back out to the hook's set() (and can't pass the wrong key).
+      set: (...args) => set(f.key, newValue(args)),
       // The address-level error ("we don't ship there") belongs on country.
       error:
         f.key === "country" && checkout.addressError?.code === "shipping_not_available"
@@ -82,7 +115,7 @@ export function useAddressForm(which = "billing", options = {}) {
           : null,
     }));
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [countries, values, isBilling, checkout.addressError, JSON.stringify(options)]);
+  }, [countries, values, isBilling, set, checkout.addressError, JSON.stringify(options)]);
 
   return {
     fields,