@base44/app-plugin-commerce 0.2.5 → 0.2.7

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

@@ -12,19 +12,17 @@ carry_forward:
 
 # 03 — Store data
 
-A fresh install has **no settings and no catalog**. One admin-only, idempotent call to `commerce/seed-store` creates both: the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`), the two gateway rows (`offline` enabled, `card` disabled), and — from the payload — the catalog, coupons and shipping locations. Nothing in [`./02-storefront.md`](./02-storefront.md) waits on it: fire it when the image URLs are back and pick the response up when you need the slugs.
+A fresh install has **no settings and no catalog**. One admin-only, idempotent call to `commerce/seed-store` creates both: the six settings groups, the two gateway rows (`offline` enabled, `card` disabled), and — from the payload — the catalog, coupons and shipping locations. Nothing in [`./02-storefront.md`](./02-storefront.md) waits on it: fire it when the image URLs are back.
 
-| Mode | Body | Products created |
-|---|---|---|
-| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | yours — categories, ribbons, attributes, variants, all in this one call |
-| **Demo data** | `{ store_name, with_sample_data: true }` | 10 generic demo products (skipped if any product exists) |
-| **No products** | `{ store_name }` | none — defaults only |
-
-`with_sample_data` cannot be combined with `products` (**400** `invalid_payload`). Never calling the function leaves the operator the admin's first-run "Set up your store" screen.
+| Mode | Body |
+|---|---|
+| **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) |
+| **Demo data** | `{ store_name, with_sample_data: true }` — 10 generic products; cannot combine with `products` (**400**) |
+| **No products** | `{ store_name }` — defaults only |
 
-**`store_name` is required on a first seed** (**400** `store_name_required`) — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). It becomes the email sender name and the public shop name. **`currency`** is an ISO code (`"EUR"`); prices are *formatted* per the viewer's locale, so there is nothing else to set. Explicit values always win, first seed and re-runs alike.
+**`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.
 
-Full field contract — every payload key, every response field, all error codes: [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store). Here is the working call.
+The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, dimensions…) is in [`../docs/api-admin.md`](../docs/api-admin.md#commerceseed-store) — open it only if the catalog needs one of those:
 
 ```js
 try {
@@ -32,78 +30,43 @@ try {
     store_name: "Aurora Threads",
     currency: "EUR",
     products: [
-      // ── 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 },
+      { name: "Linen Scarf", regular_price: 45 },     // minimal is complete
 
-      // ── 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",                            // 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",
-
+        regular_price: 89,
+        sale_price: 79,                            // sets on_sale; storefront strikes regular_price
         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)
-
+        sold_individually: false,                  // true → max 1 per order (no qty stepper)
         short_description: "Cushioned everyday runner.",
-        description: "<p>Cut from recycled knit…</p>",      // HTML, rendered as rich text
+        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 product page's spec rows
-        // (`productSpecs(product)`, which types each one so a weight can render
-        // as a figure and a composition as bars). NOT variant axes and NOT
-        // ribbons: they describe the product, they don't select anything.
-        // Values are strings; a leading `_` hides a row.
+        // Descriptive properties → the product page's spec rows (productSpecs
+        // types each one). NOT variant axes, NOT ribbons. Strings; `_` hides.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Weight", value: "248 g" },        // "<number> <unit>" → a numeric row
-          { key: "Care", value: "Machine wash cold" },
+          { key: "Weight", value: "248 g" },       // "<number> <unit>" → a numeric row
         ],
 
-        attributes: [                              // the axes → one selector each in the storefront
+        attributes: [                              // the axes → one selector each
           { name: "Size", options: ["41", "42"] },
           { name: "Color", options: ["Black", "White"] },
         ],
         default_options: { Size: "42", Color: "Black" },
-        variations: [                              // omit entirely → all 4 combos auto-generated
+        variations: [                              // omit entirely → all combos auto-generated
           { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
           { 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 }],
     //   ONLY with a coupon field in the cart or checkout (see ./02-storefront.md)
-    // locations: [ … ],   // shipping — the next section; passing any makes them the store's ONLY ones
+    // locations: [ … ],   // shipping — next section; passing any makes them the store's ONLY ones
   });
   return res.data;                 // ← the { success, data } envelope: plain JSON
 } catch (e) {
@@ -111,29 +74,23 @@ 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.
+**Running this through a code-execution tool? Return `res.data`, never the raw response** — the raw response carries circular objects and fails `Converting circular structure to JSON` *even when the seed succeeded*; a thrown error needs `e.response?.data` for the same reason.
 
-Reference taxonomy by **display name** (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.
+Reference taxonomy by **display name** — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's price up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface. **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry. **Limits:** ≤100 products, ≤500 variations, ≤50 locations per call. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]` before anything is written.
 
 The response reports everything; these matter downstream:
 
 ```jsonc
-{ "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" },
+{ "catalog": { "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 2 }] },
   "payment_methods": null,          // null = the default (offline on, card off)
-  "warnings": [] }                  // always present; read it — see the shipping section
+  "warnings": [] }                  // always present; read it — see shipping
 ```
 
-Link pages by the **`slug`** from `catalog.products[]`; never mirror the seed in client-side constants (the database is the source of truth and a mirror diverges the first time the merchant edits a product).
+Link pages by the **`slug`** from `catalog.products[]`; never mirror the seed in client-side constants (the database is the source of truth and a mirror diverges on the first merchant edit).
 
 ## Shipping — declare it in the seed call
 
-**Seed-time `locations` is THE way to configure shipping.** Each location is a scope plus its rates and taxes, locations match in `order` ascending, and `order` defaults to the payload position — so the array reads as the priority. "€20 in Europe, €100 everywhere else" is two locations:
+Each location is a scope plus its rates and taxes; locations match in payload order. "€20 in Europe, €100 everywhere else" is two locations:
 
 ```js
 locations: [
@@ -142,63 +99,40 @@ 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`, 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 }`.
-
-**The catch-all trap.** Passing any `locations` suppresses the seeded "Rest of the world" fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. That is plausibly intended, so it is not an error — it comes back in the response as `warnings: ["no_catchall_location: …"]`. Read `warnings` on every seed and either add a `rest_of_world` location or state the restriction to the user.
-
-Patching `commerce.ShippingTaxLocation` records afterwards is the **harder, day-2 route** — you must mint stable rate `id`s yourself, and there is no admin function for it. Do shipping in the seed payload. For continent codes in full, state-level regions, tax-group binding, free-over thresholds, VAT-on-shipping and day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
+- **`continents: ["EU"]`** spares you a 51-country list — and `EU` is the *continent* Europe, not the European Union.
+- **`rest_of_world: true`** is the catch-all. There is **no country code meaning "everywhere"** (`["*"]`, `["ALL"]`, alpha-3 like `["USA"]` all fail **400**); other scopes are `countries: ["IL", "DE"]` or `regions: [{ type: "state", code: "US:CA" }]`. Matching is country + state only.
+- A matched location supplies **both** shipping rates and tax groups (`tax_groups`, `shipping_tax`, `free_over` — see the reference below).
 
-**Tiered rates are worth one assertion**, because a wrong zone looks exactly like a right one until a customer in the wrong country pays. The cart prices from an address, so ask it directly — no UI needed:
+**The catch-all trap.** Passing any `locations` suppresses the seeded worldwide fallback, so scoped locations with nothing behind them mean every other address gets `shipping_not_available` at checkout. Plausibly intended, so it is a warning, not an error: **read `warnings` on every seed** and either add a `rest_of_world` location or state the restriction to the user. If the brief named tiered rates, assert them once by pricing a cart against one address per zone (`set-shipping-address` → `available_shipping_methods`; a `[]` means no location matched).
 
-```js
-// one item in the cart, then price it for each country the brief names
-for (const country of ["DE", "AU"]) {
-  const { data } = await base44.functions.invoke("commerce/storefront-cart", {
-    action: "set-shipping-address", cart_token, address: { country, city: "x" },
-  });
-  console.log(country, data.data.available_shipping_methods.map((m) => m.cost));
-}
-// DE → [20], AU → [100] for the payload above. A [] means no location matched
-// that address — the catch-all is missing.
-```
+Continent codes in full, state regions, tax binding, VAT-on-shipping, day-2 edits: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md).
 
 ## Images
 
-Every product needs at least one, and **the URL you seed is the URL the store serves** — there are no placeholders to swap later. Resolve each to its **final, permanent URL before seeding**: the app's image generation, `base44.integrations.Core.UploadFile({ file })` → public URL, or stable public stock URLs (`seed-store/sample-data.ts` shows a working pattern). Match the image to the product.
-
-Both failure modes are silent at seed time and visible only in the store, so check now: a **temporary or signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile`, and spot-check that one or two URLs resolve (200, image content type). Seeding without an image and setting it later through the admin API is allowed, but it is an open debt — track every imageless product and close it before handover.
+**The URL you seed is the URL the store serves.** Resolve each to its final, permanent URL before seeding: the app's image generation, or `base44.integrations.Core.UploadFile({ file })` → public URL. A temporary/**signed** URL (expiry params in the query string are the tell) must be re-hosted via `UploadFile` first — the failure is silent at seed time and visible only in the store. Seeding imageless and patching later is allowed but is open debt; close it before handover.
 
 ## Payments — the decision
 
-**The rule, in full.** Online card payments are **off by default**: `commerce/seed-store` enables the manual `offline` method and leaves the `card` gateway disabled. Offline-only is a complete, payable store — the order goes on-hold with the gateway's description rendered as payment instructions on `/order-received`, which needs no code and no credentials. **Enable `card` only if a payment provider is wired, or will be in the same stretch of work:** enabled means offered, and an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it. Enabling and wiring are two halves of one step; neither half is useful alone.
+Online card payments are **off by default**: the seeded store takes the manual `offline` method and is complete and payable — the order goes on-hold and `/order-received` renders the gateway's payment instructions, no code, no credentials. **Enable `card` only if a provider is wired in the same stretch of work**: an enabled card option with nothing behind it answers **`503 no_card_payment_provider`** the moment a customer picks it.
 
-**`payment_methods` is the on/off switch.** Pass gateway slugs and the listed gateways are enabled while **every other row is disabled** — `["offline"]`, `["card"]` (card-only) or both, with no `commerce.PaymentGateway` reads or writes of your own. Omit it and the store stays offline-only. It is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later on/off switch. Unknown slugs fail `400 invalid_payload` with the known list.
+`payment_methods` is the on/off switch — the listed slugs are enabled, every other row disabled; it is idempotent and needs no catalog, so `{ payment_methods: ["offline", "card"] }` alone is the later switch.
 
-| What the request says | Decision |
+| The request says | Decision |
 |---|---|
-| 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 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.
+| A provider is named ("use Stripe") | copy the provider file, enable `card` — whenever convenient |
+| Selling online implied, no provider named | raise the provider **after** the store works |
+| Paid another way (transfer, COD, invoice, pickup) | nothing to do — the default is exactly this |
+| Payments not mentioned | leave the default, **state it at handover** |
 
-*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).
+*Cards only:* **if it is Stripe the code is already written** — copy `base44/shared/commerce/card-payment.stripe.ts` over `base44/shared/commerce/card-payment.ts` **whole** (`fs.copyFileSync`; a partial edit breaks every function's deploy), then enable via `payment_methods`. Nothing needs filling in. Any other provider: [`../references/online-payments.md`](../references/online-payments.md).
 
 ## Done — forget this file
 
-- [ ] `commerce/seed-store` returned success and reported the catalog — real products, final permanent image URLs.
-- [ ] `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.
+- [ ] Seed returned success — real products, final permanent image URLs; slugs recorded and pages link by them.
+- [ ] `warnings` is empty, or every warning is deliberate and stated to the user.
+- [ ] Shipping expressed in `locations` (catch-all present if the store ships worldwide); named tiers asserted.
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
-- [ ] 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).
+- [ ] Cards off, or on with the provider file copied whole.
 
 Record these lines in your working notes; do not re-read this file.
 

package/skills/commerce/references/admin-product-form.md

@@ -67,3 +67,29 @@ Attribute and value *records* are shared between products, so the **Manage attri
 dialog saves them immediately, unlike the rest of the form which batches until Save. There
 are no Attributes or Ribbons pages in the side menu: attributes are reachable only from
 here, ribbons from the `TaxonomyPanel` card in the product sidebar.
+
+## Taxonomy cascade semantics (`save-term` / `delete-term`)
+
+What `commerce/admin-products` `save-term`/`delete-term` do beyond the plain upsert/delete
+(signatures and the per-taxonomy field table: [`../docs/api-admin.md`](../docs/api-admin.md#commerceadmin-products)).
+These rules apply whenever you build custom taxonomy tooling against those actions — the
+shipped dialogs already obey them.
+
+- Only a category has a slug, derived from its name and made unique; its `parent_id`
+  pointing at itself is coerced to `""` (`categoryWithDescendants` would loop). An
+  attribute's **`code`** is derived from the name and made unique — it is the key a
+  storefront filter URL should carry.
+- Creating a **ribbon** is get-or-create: a name that already exists case-insensitively
+  returns the existing record instead of splitting the ribbon in two.
+- Renaming an **attribute value** rewrites `attributes[].options` and `default_attributes`
+  on every product using it, and the matching `option` on their variations — products
+  store a value by name, so the rename would otherwise orphan them.
+- Deleting an **attribute** always deletes its terms (a term outliving its attribute is
+  unreachable); `detach: true` additionally strips the attribute from every product's
+  `attributes[]`. For a category or ribbon, products keep the id by default (the
+  storefront skips ids that no longer resolve); `detach: true` strips it from every
+  product first.
+- **For an attribute *value* `detach` is a no-op** — deleting a value leaves its name in
+  every product's `attributes[].options` and leaves the variations that use it in place,
+  so remove the value from the products first (or expect variants the storefront can no
+  longer resolve).

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

@@ -50,21 +50,21 @@ There is **no product `type` field**. `attributes[]` tells the shapes apart:
 
 A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, with no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident (§5 covers rendering that state).
 
-Three rules used to be prose here and are now enforced by exports — use them and they can't drift between views:
+Three rules are 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` 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 descriptive — never a selector, never a ribbon. How each modifier *renders* is a design decision (§3); what it can never become is a control.
+- **From-price.** A parent's `regular_price`/`price`/`on_sale` are rolled up from the cheapest publishable variant on every save (by `admin-products` and the seeder) — real, sortable, filterable, but the **lowest** price, not *the* price. `productPrice(rowOrView, {formatMoney})` / `useProductPrice(rowOrView)` take a listing row **or** a `resolveSelection` view and return `{label, compareAtLabel, onSale, isFrom, isRange, min, max}`: "From €19.99" on a card, a range unresolved, the exact price resolved.
+- **Images are objects, and may be absent.** Every stored image is `{src, name, alt}`, never a URL string — passing the object itself to `<img src>` fails the load — and `images` can legitimately be empty. `productImages(product)` / `normalizeImage(entry)` return clean entries (non-empty `src`, defaulted `alt`); an empty array means *render your placeholder* (`useProductGallery` builds on them, `hasImages`).
+- **Modifiers are not attributes.** `meta_data` (Material, Care, GTIN) is descriptive — never a selector, never a ribbon; how it renders is a design decision (§3), a control is what it can never become.
 
 ## 3. What each view *can* render
 
-Both lists below are field inventories — what the data supports — **not a layout and not an order**. Read them for availability, then design the surface; a store that renders exactly these fields in exactly this sequence is the generic storefront every generated catalog produces.
+Both lists below are field inventories — what the data supports — **not a layout and not an order**; a store rendering exactly these fields in exactly this sequence is the generic storefront every generated catalog produces.
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`) that says more about *this* catalog than a star average does. Link the whole card to the product page; the card, the grid's rhythm and whether every card is even the same size are yours.
+**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons — plus anything else on the row (`weight`, `dimensions`, `meta_data` via `productSpecs`). Link the whole card to the product page; the layout is yours.
 
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCartButton`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
+**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells. Everything except the markup has a hook or helper: `useProductGallery`, `variantAxes(view, pick)`, `useAddToCart`, `productSpecs(product)`, `useProductReviews`, `p.upsells`/`p.crossSells`.
 
-**Attributes and modifiers are individually designable.** `variantAxes` exposes `axis.key`/`axis.name`, and `productSpecs` exposes `key`/`label` plus an inferred `type` — `numeric` (with `number`/`unit` split out), `duration`, `location`, `list` (with `items`), `text` — precisely so a page can branch on *which* one it is: colour as swatches, size as chips next to a size guide, a `list` "Composition" as bars, a `location` "Provenance" as a located line, a `numeric` "Weight" as a figure in the display face, "Certification" as a seal. One uniform chip row for every axis and one grey label/value table for every modifier is a default, not a requirement — pick the two or three that carry the product's meaning, give them real treatment, and let the remainder fall back to a plain row. The rules in §5 govern selector *behaviour* (one control per axis, unbuyable disabled), never its form, and they hold whatever the control looks like.
+**Attributes and modifiers are individually designable.** `productSpecs` rows carry `key`/`label`/`titleLabel` (display-cased) plus an inferred `type` (`numeric` with `number`/`unit` split out, `duration`, `location`, `list` with `items`, `text`); `useProductSpecs(product, { pick })` is the React wrapper, its get/pick case/underscore-insensitive. Branch on `type`/`key` instead of mapping everything into one uniform chip row per axis and one grey label/value table — the design guidance is [`../install/02-storefront.md`](../install/02-storefront.md)'s; §5's rules govern selector *behaviour*, never its form.
 
 ## 4. Ribbons — in **both** views
 
@@ -99,7 +99,7 @@ Three decisions the helpers can't make for you:
 
 **Attributes but no usable variations** — what attaching an attribute and stopping leaves behind — deliberately gets no parent fallback, because `add-item` would reject it: empty `axes[].options`, `purchasable: false`, `addToCart: null`. Render it as unavailable rather than painting empty selector groups, and guard the label (with no attributes at all `missingAxes[0]?.name` is `undefined` → "Select a undefined").
 
-**Add to cart** goes through `useAddToCart()`, which never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → `shouldReload: true`, refetch). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
+**Add to cart** goes through `useAddToCart(product)`, whose `addToCart()` never throws and maps the codes: `variation_required` (a page bug — empty `variation_id` on a product with attributes), `out_of_stock` / `insufficient_stock`, and `variation_not_found` (the catalog changed under the page → the hook reloads the product itself). `product.sold_individually` caps quantity at 1, already reflected in `useProduct().maxQuantity`. Two behaviors that matter only if you hand-roll the view model: non-publishable variations never leak an option into the UI, and an empty `option` on a variation axis means **"any"**.
 
 ## 6. Adding a `get-product`-only field to the listing
 

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

@@ -41,14 +41,9 @@ That is the whole of it. The file expects the app to be connected to Stripe and
 
 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.
 
-## How the premade flow works
+## The premade flow
 
-1. **Checkout** (`place-order` with the `card` gateway): the order is created `pending`, `createCardPayment` runs, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
-2. **Confirmation — two idempotent paths**, whichever runs second is a no-op: the **customer return** (`/order-received` calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid` and on true moves the order to `processing`, firing the stock/email/webhook side-effects — `useOrderReturn` is that page in one hook), and the **webhook**, which covers the buyer who pays and closes the tab.
-3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order through the same `createCardPayment` — the admin's payment-link button and order-received's "Pay now".
-4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's dashboard.
-
-With the gateway enabled and no provider behind it, picking Credit card answers `503 no_card_payment_provider` — implement the file, or switch the option off in Settings → Payments. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions and the operator moves it on when the money arrives. Those need no code, and the admin can add more of them.
+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.
 
 ## Implementation rules
 
@@ -62,12 +57,6 @@ For a **custom** provider (the shipped files already obey all of these):
 - **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.
 - The helpers in `shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
-## `parseWebhook` in depth
-
-`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
-
-- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret: the premade flow verifies through `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction — a forged call can at worst trigger a re-check, and the `order_key` match stops an event being aimed at another order. This is what the shipped Stripe file does.
-- **The signature-verified fast path** (optional): verify the signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference`; the premade code then trusts it without the API round-trip. **`paid: true` from an unverified body is the one way to break this design.** Set `reference` only from a verified event; otherwise leave it unset and the flow uses the reference stored on the order at checkout.
-- Return **`null`** for events that aren't about one of this store's payments; the function answers 200 so the provider doesn't retry.
+## `parseWebhook`, briefly
 
-Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
+Premade `commerce/payment-webhook` feeds `parseWebhook(req, payload)` the raw request and body (exact bytes, so signature schemes work); it returns `CardWebhookEvent | null` — `null` = not this store's payment, answered 200 (no retry). The secure default (what the shipped Stripe file does) is the **nudge**: read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }` — no signing secret, since payment is verified through `checkCardPaymentPaid` against the provider's API and the `order_key` match stops an event aimed at another order. Optionally verify the signature over the raw `payload` bytes and return `paid: true` + the event's `reference` to skip that round-trip — **`paid: true` (or a `reference`) from an unverified body is the one way to break this design.** Everything after `parseWebhook` — lookup, `order_key` match, idempotent confirmation, progression — is premade either way.

package/skills/commerce/references/operations.md

@@ -32,13 +32,31 @@ Every action above is guarded by `requireAdmin()`, so each workflow must run wit
 
 - **Pagination.** SDK `filter`/`list` cap at 5,000 records/page and there is **no total-count API**. Server-side scans use paged loops (`shared/commerce/scan.ts` `scanAll`, page size 500); admin lists and `useProductList` use limit+skip with a `limit+1` "has-next" probe — the UI shows *Page N ‹ ›*, never a total.
 - **Search** is server-side (`search` actions scan + JS-filter) because entity `filter` is exact-match only.
-- **Reports** scan on demand — fine to ~10k orders per range. `commerce/admin-reports` `summary`/`sales`/`top-sellers` scan `commerce.Order` (+ `commerce.OrderRefund`) filtered to counted orders (`date_paid` set, or status `processing`/`completed`); net sales = gross − refunds − tax − shipping. Beyond that, cache `summary` and materialize an `OrderStats` entity (one record per day per status, summed totals) updated on each order transition.
+- **Reports** scan on demand — fine to ~10k orders per range. `commerce/admin-reports` `summary`/`sales`/`top-sellers` scan `commerce.Order` (+ `commerce.OrderRefund`) filtered to counted orders (`date_paid` set, or status `processing`/`completed`); net sales = gross − refunds − tax − shipping. Beyond that, cache `summary` and materialize an `OrderStats` entity (one record per day per status, summed totals) updated on each order transition. The full action table is below.
 - **No transactions.** Four consequences, all documented in code:
   - `nextOrderNumber` is `max(order_number)+1` with a small retry; two concurrent checkouts could theoretically collide — acceptable for typical volume, or front it with a counter entity.
   - Stock decrement is last-write-wins; oversell is possible on simultaneous checkouts of the last unit. The hold mechanism (`hold_stock_minutes`) mitigates it; a stricter reserve step is yours to add.
   - Denormalized counters (`usage_count`, `total_sales`, `orders_count`, term `count`) can drift; the recount actions above repair them.
   - **Record size.** Orders embed their line/shipping/tax/fee/coupon lines, so orders with hundreds of distinct line items push against per-record size limits.
 
+### `commerce/admin-reports` actions
+
+The complete payload/return contract (invocation: [`../docs/api-admin.md`](../docs/api-admin.md#commerceadmin-reports)):
+
+| Action | Payload | Returns |
+|---|---|---|
+| `summary` | — | `{ sales_today, sales_month, orders_by_status, low_stock_count, out_of_stock_count, top_seller }` where `sales_*` = `{ gross_sales, net_sales, orders, items, tax, shipping, discount, refunds }` |
+| `sales` | `{ date_min?, date_max?, interval? }` (`day`\|`week`\|`month`) | `{ totals: <agg>, series: [{ period, ...agg }] }` (net = gross − refunds − tax − shipping) |
+| `top-sellers` | `{ date_min?, date_max?, limit? }` | `{ rows: [{ product_id, name, sku, quantity, net_revenue }] }` |
+| `stock` | — | `{ low_stock: [...], out_of_stock: [...] }` |
+| `orders-totals` | — | `{ [status]: count }` |
+| `products-totals` | — | `{ total, by: { [status]: count } }` |
+| `customers-totals` | — | `{ total, guests, registered, paying }` |
+| `coupons-totals` | — | `{ total, by: { [discount_type]: count } }` |
+| `reviews-totals` | — | `{ total, by: { [status]: count } }` |
+| `categories-totals` / `ribbons-totals` | — | `{ total, terms: [{ id, name, count }] }` |
+| `attributes-totals` | — | `{ total, attributes: [{ id, name, terms }] }` |
+
 ## Webhooks (outbound)
 
 Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).

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

@@ -0,0 +1,47 @@
+---
+read_when: "You are about to drive the storefront from a browser script — adding to the cart, stepping quantities, filling the checkout, placing an order."
+skip_when: "You are not scripting the storefront."
+---
+
+# Driving the storefront from a browser script
+
+Whatever you choose to check and however you check it, these are what make a
+working storefront look broken under a script. The common cause is acting
+faster than the cart settles: the hooks are optimistic and debounced, so the
+DOM is briefly right about the *intent* and wrong about the *state*.
+
+- **Wait for the cart, then for each row.** Two waits, neither optional. Before
+  the first action, wait for the initial load to settle — `status` leaves
+  `"loading"` exactly once, so the signal is the loaded UI (a row, or the empty
+  state), never a fixed sleep. Then after every stepper click wait for **that
+  row**: the click starts a 250ms debounce before the request even leaves, so
+  reading the quantity or total straight after gives the optimistic number and
+  stale totals, and two quick clicks send **one** request for the final number.
+  Wait for the row's busy state to clear (`aria-busy`, re-enabled buttons)
+  before reading or clicking again.
+- **Scope actions to the visible drawer.** With a drawer, the page can hold two
+  "Remove" buttons for one line — drawer and cart page behind it. A drawer built
+  on `useCartUI` is unmounted while closed, so its copies can't be hit by
+  mistake — but still query inside the open drawer's container, not the
+  document. A click that seems to do nothing usually hit a hidden copy.
+- **Remove lines one at a time.** Clicking every "Remove" in one pass fails on
+  its own terms: cart calls are serialized, each removal re-renders the list,
+  and buttons collected up front are detached by the time the loop reaches
+  them. Remove one, wait for the row to disappear, then the next.
+- **Verify the checkout navigation before cleaning up.** Confirm you are on
+  `/checkout` — URL plus a field of the form on screen — before emptying the
+  cart or moving on. Tearing the cart down while still on the cart page, or
+  mid-navigation, produces an empty checkout that reads as a routing bug.
+- **Filling the checkout.** Every field is a controlled React input, so writing
+  `el.value` changes nothing React sees. Use the harness's own fill (it
+  dispatches `input` + `change`) — never lift the native setter off
+  `HTMLInputElement.prototype` and call `descriptor.set(v)`: detached from the
+  element it throws `Illegal invocation`, and the workaround it is reaching for
+  is what the fill helper already does.
+- **`placeOrder` ends the page.** It navigates with `window.location.assign`,
+  so a script that placed an order loses its page context and can land back at
+  `/` — while the order itself was created normally. That is the hard
+  navigation, not a broken redirect. The confirmation is reachable at any time
+  from a fresh navigation to `/order-received?order_id=…&order_key=…` (the ids
+  come back in `placeOrder`'s result, and `commerce/admin-orders` `search` has
+  the order either way).

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -205,8 +205,10 @@ export function useFormatMoney() {
  * - `lines` are `cart.items` decorated with what a renderer needs and would
  *   otherwise re-derive: `attributesLabel` ("Size: 42 · Color: Ivory" — the raw
  *   `attributes` is an **array** of `{name, option}`, never a map),
- *   `image` normalized to `{src, alt}` or null, `purchasable` as a boolean with
- *   `unavailableReason` beside it, and the quantity bounds.
+ *   `image` normalized to `{src, alt}` or null, money pre-formatted
+ *   (`totalLabel`, `subtotalLabel`, `unitPriceLabel` — no `useFormatMoney`
+ *   needed in a row), `purchasable` as a boolean with `unavailableReason`
+ *   beside it, and the quantity bounds.
  * - `notices` normalizes `coupon_notices` + `removed_items` into one list —
  *   render it, or a line that auto-dropped vanishes with no explanation.
  * - `mutationError` is the last failed mutation (insufficient stock, an expired
@@ -286,6 +288,9 @@ export function useCart() {
           ...item,
           attributesLabel: attributesLabel(item.attributes),
           image: item.image ? { src: item.image, alt: item.name ?? "" } : null,
+          totalLabel: item.total != null ? formatMoney(item.total) : "",
+          subtotalLabel: item.subtotal != null ? formatMoney(item.subtotal) : "",
+          unitPriceLabel: item.price != null ? formatMoney(item.price) : "",
           maxQuantity,
           canIncrease: item.quantity < maxQuantity,
           canDecrease: item.quantity > 1,
@@ -293,7 +298,7 @@ export function useCart() {
           unavailableReason: purchasable ? null : (item.purchasable?.error ?? null),
         };
       }),
-    [items],
+    [items, formatMoney],
   );
 
   const notices = useMemo(

package/src/commerce/storefront/cartUI.jsx

@@ -0,0 +1,118 @@
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { useLocation } from "react-router-dom";
+
+/**
+ * Cart drawer/panel state, headless: `open` plus the handlers to change it,
+ * and the two behaviors every drawer needs but a hand-written one forgets —
+ * it closes when the route changes (`closeOnNavigate`) and it opens when an
+ * item lands in the cart (`openOnAdd`, wired through `useAddToCart` /
+ * `useUpsell`; pass false for a navigate-to-bag flow). Esc closes it. You own
+ * every element, class and attribute.
+ *
+ * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
+ * layout. Then the layout renders off `open`:
+ *
+ *   function StoreLayout() {
+ *     const ui = useCartUI();
+ *     const { itemCount } = useCart();
+ *     return (<>
+ *       <header>… <button type="button" onClick={ui.toggleCart}
+ *                         aria-expanded={ui.open}>Bag ({itemCount})</button></header>
+ *       <Outlet />
+ *       {ui.open && (<>
+ *         <div onClick={ui.closeCart} aria-hidden="true" className="…" />
+ *         <aside role="dialog" aria-modal="true" aria-label="Cart" className="…">
+ *           <button type="button" onClick={ui.closeCart} aria-label="Close cart">×</button>
+ *           {…your cart rows: useCart + CartLine…}
+ *         </aside>
+ *       </>)}
+ *     </>);
+ *   }
+ *
+ * ⚑ **Render the drawer conditionally (`{ui.open && …}`), as above.** The
+ * classic drawer bug is a panel that is translated off-screen but still
+ * mounted: its buttons stay clickable, tab-able and visible to screen readers.
+ * Unmounting it when closed is the trivial fix. If you keep it mounted to
+ * animate the slide, that concern is yours again — set the `inert` attribute
+ * while closed.
+ *
+ * The overlay is a click-away surface (`aria-hidden`, no tab stop needed) —
+ * it is not the close control; a named close button inside the panel is.
+ *
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
+ * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`
+ * integrates without requiring the provider).
+ *
+ * A store whose cart is a page, not a drawer, skips this provider entirely.
+ */
+
+const CartUIContext = createContext(null);
+
+/** Internal: closes the drawer whenever the route changes (needs a Router above). */
+function CloseOnNavigate({ close }) {
+  const { pathname } = useLocation();
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    close();
+  }, [pathname, close]);
+  return null;
+}
+
+/**
+ * @param {{closeOnNavigate?: boolean, openOnAdd?: boolean,
+ *   children: React.ReactNode}} props
+ */
+export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, children }) {
+  const [open, setOpen] = useState(false);
+  const openCart = useCallback(() => setOpen(true), []);
+  const closeCart = useCallback(() => setOpen(false), []);
+  const toggleCart = useCallback(() => setOpen((o) => !o), []);
+
+  // Esc closes — the keyboard's way out is Esc and the named close button.
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open]);
+
+  const value = useMemo(
+    () => ({
+      open,
+      openCart,
+      closeCart,
+      toggleCart,
+      onItemAdded: openOnAdd ? openCart : null,
+    }),
+    [open, openCart, closeCart, toggleCart, openOnAdd],
+  );
+
+  return (
+    <CartUIContext.Provider value={value}>
+      {closeOnNavigate && <CloseOnNavigate close={closeCart} />}
+      {children}
+    </CartUIContext.Provider>
+  );
+}
+
+/** The nearest <CartUIProvider>'s controls; throws without one. */
+export function useCartUI() {
+  const ctx = useContext(CartUIContext);
+  if (!ctx) {
+    throw new Error(
+      "useCartUI needs a <CartUIProvider> above it — mount it once inside <StorefrontProvider>, around your layout.",
+    );
+  }
+  return ctx;
+}
+
+/** Internal-ish: null instead of throwing, for optional integrations. */
+export function useCartUIOptional() {
+  return useContext(CartUIContext);
+}