@base44/app-plugin-commerce 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -107,10 +107,10 @@ so you can answer "would that file help?" without paying for it.
 | Topic | Open when | Already covered without opening | Size |
 |---|---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — it routes you to 02 and 03 | — | 8K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | — | 14K |
-| [`install/03-data.md`](./install/03-data.md) | seeding the catalog, shipping, payments decision | — | 14K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages — cart-drawer behaviour and driving the storefront from a browser script are in here too, not in a separate reference | — | 38K |
+| [`install/03-data.md`](./install/03-data.md) | seeding the catalog, shipping, payments decision | — | 18K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write, or "which entity holds X" | function-mediated flows never need it; the addressing rule is above | 11K |
-| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | the install's product list/page chunks already render correct cards, prices and selectors | 12K |
+| [`references/catalog-rendering.md`](./references/catalog-rendering.md) | which fields each catalog call returns, variant edge cases | the install's product list/page chunks already render correct cards, prices and selectors | 13K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond the standard recipe, taxes, editing locations later | "€X in a region, €Y worldwide" is inline in `install/03-data.md` | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | the store opted into cards and you are wiring the provider **now** | the decision and its timing are in `install/03-data.md`; wiring Stripe is a one-file copy, not code to write | 9K |
 | [`references/reviews.md`](./references/reviews.md) | moderation, or a policy beyond the `policy` prop | `useProductReviews` covers list + form + policies | 4K |

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

@@ -54,49 +54,93 @@ layout — get hooks only, on purpose: reference markup there would make every
 store look the same, and their design is the work only you can do. Either way
 the hooks are high-level enough that a page is a handful of calls plus your
 markup — writing more code than the budgets at the bottom allow means you are
-re-deriving logic a hook already owns. Everything imports from
-`@/commerce/storefront`.
+re-deriving logic a hook already owns.
+
+**One import path: `@/commerce/storefront`.** Each section below opens with its
+page's exact import line — **copy it verbatim** instead of assembling one from
+memory, then delete any name you don't end up using. `variantAxes` and
+`productSpecs` live in `@/commerce/utils` but are re-exported here, so a React
+page never imports from `@/commerce/utils` directly; `useStoreInfo` is the name
+most often left out, and it is the only source of store name and currency.
 
 ## Setup — once
 
+Nearly every store has shared chrome (a nav with a cart badge, a footer), so
+**start from the layout route** — a pathless `<Route>` whose element is your
+layout, rendering `<Outlet/>` where the page goes. It also keeps the admin
+outside the storefront's provider and chrome:
+
 ```jsx
+import { Routes, Route, Outlet } from "react-router-dom";
 import { StorefrontProvider } from "@/commerce/storefront";
 import { base44 } from "@/api/base44Client";
+import AdminApp from "@/commerce/admin";
+
+// StoreLayout is YOURS: <Nav/> (its cart badge calls useCart) + <Outlet/> + <Footer/>.
+function StoreLayout() { return <><Nav /><Outlet /><Footer /></>; }
 
 <BrowserRouter>
-  <StorefrontProvider base44={base44}>     {/* wraps <Routes> — never a child of it */}
-    <Routes>                               {/* ONE <Routes> — merge new pages into the app's */}
+  <Routes>                                {/* ONE <Routes> — merge new pages into the app's */}
+    <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
       <Route path="/" element={<Home />} />
       <Route path="/product/:slug" element={<ProductPage />} />
       <Route path="/bag" element={<Bag />} />
       <Route path="/checkout" element={<Checkout />} />
       <Route path="/order-received" element={<OrderReceived />} />
-      <Route path="/store-admin/*" element={<AdminApp />} />
-    </Routes>
-  </StorefrontProvider>
+    </Route>
+    <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
+  </Routes>
 </BrowserRouter>
 ```
 
+⚑ **The nesting is provider → layout → `<Outlet/>`, never the reverse.** A
+layout that renders the provider *inside* itself leaves the nav above (or
+outside) it, so the header badge and the cart page read different carts — and a
+`useCart` in the nav throws outright. The provider goes on the layout route's
+element, wrapping your layout component.
+
+**No shared chrome** (each page draws its own header, or there is one page)?
+Then wrap `<Routes>` directly and skip the layout route:
+
+```jsx
+<StorefrontProvider base44={base44}>     {/* wraps <Routes> — never a child of it */}
+  <Routes>…</Routes>
+</StorefrontProvider>
+```
+
+> ⚠ **`<Routes>` accepts only `<Route>` children.** Putting the provider inside
+> it — the natural reading of "wrap the storefront routes" — throws at render:
+> `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`.
+> A pathless layout route (above) is the one place a wrapper is legal.
+
 The provider owns the shared client, the store-info cache and **one** shared
 cart, so a header badge, a drawer and the checkout render the same state. Never
 mount a second provider, and never touch the `cart_token` — the provider owns
 its whole lifecycle.
 
-> ⚠ **`<Routes>` accepts only `<Route>` children.** Nesting the provider inside
-> it — the natural reading of "wrap the storefront routes" — throws at render:
-> `Error: [StorefrontProvider] is not a <Route> component. All component children of <Routes> must be a <Route> or <React.Fragment>`.
-> To scope the provider to storefront routes only, use a pathless **layout
-> route**, the one place a wrapper is legal:
-> ```jsx
-> <Route element={<StorefrontProvider base44={base44}><Outlet /></StorefrontProvider>}>
->   <Route path="/" element={<Home />} />
->   <Route path="/checkout" element={<Checkout />} />
-> </Route>
-> <Route path="/store-admin/*" element={<AdminApp />} />   {/* outside the provider */}
-> ```
-
 ## Product list / collection
 
+```jsx
+import { useProductList, useCategories, useProductPrice, useStoreInfo, useStorefrontSeo, collectionSeo, productSpecs } from "@/commerce/storefront";
+```
+
+(Drop `useCategories` with no filter bar, `productSpecs` if the card shows no
+modifiers. Add `useRibbons` for a ribbon filter.) The top of the component,
+before any markup — every hook above the guards, and `products` derived once:
+
+```jsx
+const list = useProductList({ per_page: 24 });
+const { settings } = useStoreInfo();
+useStorefrontSeo(collectionSeo({ title: "…", products: list.products, storeName: settings?.store_name }));
+
+if (list.status === "loading") return /* your loading state */;
+if (list.status === "error")   return /* your failure state, with a retry calling list.reload() */;
+const products = list.products;   // always an array — never null, so no defensive `?? []`
+```
+
+The same opening carries a home page's rails and a search results page — only
+the params and your markup change.
+
 `useProductList(params)` → `{ status, products, hasNext, next, refreshing,
 setParams, reload }`. ⚑ `status` is `"loading" | "ready" | "empty" | "error"`
 — branch on it, so a failed request renders as a failure instead of an empty
@@ -130,6 +174,13 @@ beside a product need no query: `p.upsells` / `p.crossSells` from `useProduct`.
 
 ## Product page
 
+```jsx
+import { useProduct, useProductGallery, useAddToCartButton, useStoreInfo, useStorefrontSeo, productSeo, variantAxes, productSpecs } from "@/commerce/storefront";
+```
+
+(Add `useProductReviews` only if the store has reviews; drop `productSpecs` if
+these products carry no modifiers.)
+
 `useProduct(slug)` (or `{ id }`) owns fetch + variant selection + quantity +
 price, race-safe, selection mirrored to the URL. ⚑ `status: "not_found"` is a
 404 page, not a spinner.
@@ -144,7 +195,8 @@ precisely so they can sit at the top:
 const p = useProduct(slug);
 const g = useProductGallery(p.product, p.view);
 const buy = useAddToCartButton(p, { onAdded: () => navigate("/bag") });
-useStorefrontSeo(productSeo(p.product, p.view, { storeName, currency }));
+const { settings } = useStoreInfo();   // the ONLY source of store name + currency
+useStorefrontSeo(productSeo(p.product, p.view, { storeName: settings?.store_name, currency: settings?.currency }));
 
 if (p.status === "loading")   return /* your loading state */;
 if (p.status === "not_found") return /* your 404 */;
@@ -190,25 +242,42 @@ anywhere.) Build your layout from:
   are yours.
 - **Description** — `product.description` is HTML; render as rich text
   (`dangerouslySetInnerHTML`), `short_description` above it.
-- **Specs** — `productSpecs(product)` → `[{ key, label, value }]` from
-  `meta_data` (Material, Care, Provenance). `[]` means no section at all.
+- **Specs** — `productSpecs(product)` → `[{ key, label, value, type, number,
+  unit, items }]` from `meta_data` (Material, Care, Provenance, Weight). `[]`
+  means no section at all. ⚑ **Don't `.map()` it into one uniform label/value
+  table** — that is the most reliable tell of a generated product page. Every
+  row's `type` is inferred for you so the branch point is already there:
+  `"numeric"` (with `number` and `unit` split out), `"duration"`, `"location"`,
+  `"list"` (with `items`), `"text"`.
+
+  ```jsx
+  // ❌ what a generated store ships: one grey table, every store the same
+  <dl>{specs.map((s) => <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>)}</dl>
+
+  // ✅ the figures read as figures, the rest falls through to a plain row
+  {productSpecs(product).map((s) =>
+    s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />  // 0.75 ct, set large
+  : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />                             // 70% wool / 30% cashmere
+  : s.type === "location" ? <Sourced key={s.key} place={s.value} />                             // a located line, a pin
+  :                         <Row     key={s.key} label={s.label} value={s.value} />)}
+  ```
+
+  Design the two or three that carry *this* product's meaning; branch on `s.key`
+  instead when one particular modifier deserves its own treatment. And they need
+  not sit in one block — a spec can go under the gallery, beside the price, or
+  inside the description.
 - **Breadcrumbs** — build from `categories`
   (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons are
   labels, not breadcrumbs.
 
 All optional — include what this store's products actually have — and each is
-one hook, **not one component style**. The tell of a generated product page is
-that every axis is the same chip row and every modifier the same grey
-label/value line. Branch on what they are: `variantAxes` gives you `axis.key` /
-`axis.name`, `productSpecs` gives you `key` / `label`, so a colour axis can be
-swatches in the real colours, a size axis chips with a size guide beside them,
-a material axis a small sample image; a "Composition" modifier can be bars, a
-"Provenance" a map pin, a "Certification" a seal, a "Weight" a figure set in
-the display face. Design the two or three that carry this product's meaning,
-let the rest fall back to a plain row, and don't feel obliged to keep them in
-one block — a spec can sit under the gallery, beside the price, or inside the
-description. The ⚑ rules above (one control per axis, unbuyable options
-disabled) constrain the *behaviour* of a selector, never its form.
+one hook, **not one component style**. The same rule the specs bullet states
+applies to the axes: `variantAxes` gives you `axis.key` / `axis.name` so a
+colour axis can be swatches in the real colours, a size axis chips with a size
+guide beside them, a material axis a small sample image — every axis rendered as
+the identical chip row is the other half of the generated-page tell. The ⚑ rules
+above (one control per axis, unbuyable options disabled) constrain the
+*behaviour* of a selector, never its form.
 
 ### Reviews — optional
 
@@ -230,6 +299,10 @@ approval", so render `message`, never your own text. `policy` is
 
 ## Cart / bag
 
+```jsx
+import { useCart, CartLine, useTotalsLines, useCoupon, useFormatMoney } from "@/commerce/storefront";
+```
+
 A cart *page* is optional: a store selling one made-to-order piece reads better
 as buy-now straight to checkout. The surface is four hooks: `useCart()`
 (`status`, `lines`, `notices`), `CartLine` (headless render-prop binding
@@ -245,6 +318,26 @@ the checkout): coupons are admin-only data, redeemable only through a field the
 customer types into — if no field exists anywhere, don't seed coupons and don't
 write "use WELCOME10" in the copy.
 
+⚑ **`pending` is one row's flag, and it stays up until that update finishes.**
+The window is not the click: `increase`/`decrease` set the optimistic number and
+start a 250ms debounce, `pending` goes true when the request leaves, and returns
+to false **only after the new cart view has landed** — so `pending === false`
+with no `error` means that row's quantity and the totals are settled, not just
+that a request returned. (`remove()` skips the debounce, `pending` immediately.)
+So **disable and mark only that row** — `disabled={l.pending}` on its own
+controls, `aria-busy` on the row — since `pending` says nothing about the other
+lines, and stalling the whole cart over one 250ms stepper reads as a broken page.
+And note **`status` never returns to `"loading"` for a mutation**: it settles
+once, on first load, then only moves between `"empty"` and `"ready"`. There is
+deliberately no cart-wide busy flag — `status` is the page's shape, `pending` is
+"did that change land".
+
+⚑ **Repeated controls need unique accessible names.** A three-line cart renders
+three buttons named "Remove", and "+" or "×" alone names nothing at all — put the
+line in the label (``aria-label={`Remove ${line.name}`}``, likewise ±, and a
+drawer's close button). Identical or empty names are ambiguous to a screen reader
+and to anything driving the page by name.
+
 **Reference implementation** — read once for the wiring, then write your own
 page: the structure below is correct, the presentation is deliberately absent.
 Restyle, rearrange, split into your own components; the ⚑ rules are the part
@@ -263,12 +356,15 @@ function Bag() {
       {lines.map((line) => (
         <CartLine key={line.item_key} line={line}>
           {(l) => (   /* line: name, attributesLabel, image, total — l: the controls */
-            <li>
+            <li aria-busy={l.pending}>       {/* busy scope is THIS row, never the cart */}
               {line.name} {line.attributesLabel}
-              <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+              <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}
+                      aria-label={`Decrease quantity of ${line.name}`}>−</button>
               {l.quantity}
-              <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
-              <button onClick={l.remove}>Remove</button>
+              <button onClick={l.increase} disabled={!l.canIncrease || l.pending}
+                      aria-label={`Increase quantity of ${line.name}`}>+</button>
+              <button onClick={l.remove} disabled={l.pending}
+                      aria-label={`Remove ${line.name}`}>Remove</button>
               {formatMoney(line.total)}
               {l.error && <p role="alert">{l.error.message}</p>}
             </li>
@@ -288,8 +384,40 @@ function Bag() {
 No shipping estimator here — checkout reprices shipping and tax from the
 address.
 
+### If the cart is a drawer
+
+Same hooks, same rows — a drawer only adds what a cart *page* gets for free:
+
+**Close it on navigation.** A product link or "Checkout" inside the drawer
+changes the route with the drawer still open, leaving it hanging over the new
+page. One effect covers every link inside, so no link has to remember:
+
+```jsx
+const { pathname } = useLocation();
+useEffect(() => { setOpen(false); }, [pathname]);
+```
+
+**A closed drawer must be inert, not just invisible.** Hidden with `opacity` or
+`translate`, its buttons stay focusable and clickable — Tab walks into an
+invisible cart, and a click lands on a "Remove" nobody can see. Either don't
+render it (`{open && <Drawer/>}`) or, if it stays mounted for the transition, use
+`hidden` / `visibility: hidden` / `inert`. ⚑ Never `aria-hidden` alone: that
+hides it from a screen reader while leaving it fully clickable.
+
+**The backdrop is not the close button.** Both close the drawer; only one is a
+control. Name the visible button (`aria-label="Close cart"`) and leave the
+backdrop an unnamed overlay — `onClick={close}`, `aria-hidden="true"`, no tab
+stop. Two elements named "Close cart" are ambiguous to a screen reader and to
+anything driving the page; the keyboard's way out is Esc and the button.
+
 ## Checkout
 
+```jsx
+import { CheckoutProvider, useCheckoutContext, useCheckoutBlockers, useAddressForm, ShippingMethodPicker, PaymentMethodPicker, useCart, useTotalsLines, useCoupon, useFormatMoney } from "@/commerce/storefront";
+```
+
+(`useCoupon` only if the coupon field lives here rather than in the cart.)
+
 The state machine is `useCheckout`, shared across the page's regions by
 `CheckoutProvider` + `useCheckoutContext()`. It reprices shipping/tax from the
 address automatically (debounced, never on a half-typed address), derives the
@@ -403,6 +531,10 @@ function AddressFields({ which }) {
 
 ## Order received
 
+```jsx
+import { useOrderReturn, useTotalsLines, useFormatMoney } from "@/commerce/storefront";
+```
+
 **Mandatory route** — every payment link returns here, and confirming is what
 marks a card order paid. `useOrderReturn()` is the whole page's logic: it reads
 `order_id`/`order_key` from the URL, verifies with the provider (idempotent),
@@ -464,7 +596,7 @@ above the status guards.
 | Page | budget (chars) | rationale |
 |---|---|---|
 | Checkout | ≤ 5K | your markup over the reference above — the logic is all hook calls |
-| Cart / bag | ≤ 3K | `useCart` + `CartLine` rows + totals + coupon + empty state |
+| Cart / bag | ≤ 3K | `useCart` + `CartLine` rows + totals + coupon + empty state — a drawer is its own component with its own 3K, not an extension of this one |
 | Order-received | ≤ 2.5K | five states + payment instructions + summary |
 | Product page | ≤ 5K | your layout and type around `useProduct`, `variantAxes`, `useAddToCartButton`, the gallery |
 | Collection | ≤ 3K | `useProductList` + custom card + pagination controls |
@@ -481,9 +613,33 @@ for.
 
 ## If you drive the storefront from a browser script
 
-Whatever you choose to check and however you check it, two things make a
-working storefront look broken under a 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 — and a
+  closed-but-mounted drawer keeps its copies clickable. Query inside the open
+  drawer's container, not the document. A click that seems to do nothing usually
+  hit the 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
@@ -501,14 +657,18 @@ working storefront look broken under a script:
 ## Done — forget this file
 
 - [ ] Catalog UI exists in whatever form fits the store (list, product pages, or both), plus a checkout, plus `/order-received`.
-- [ ] **One** `<StorefrontProvider>` above every storefront route, wrapping `<Routes>` (or a layout route's `<Outlet/>`); one client, no hand-rolled `cart_token`.
+- [ ] **One** `<StorefrontProvider>` above every storefront route — on the layout route's element, wrapping the layout that renders `<Outlet/>` (or wrapping `<Routes>` if the store has no shared chrome); one client, no hand-rolled `cart_token`.
+- [ ] Every page's imports came from its section's import line above: one path (`@/commerce/storefront`), nothing imported from `@/commerce/utils`, and no imported name — React's included — left unused.
 - [ ] Pages branch on `status`; no page maps a possibly-null list or shows an empty state while loading.
 - [ ] Gateways/currency/countries read from `useStoreInfo()` only.
 - [ ] If the store has coupons, a coupon field (`useCoupon`) exists in the cart or the checkout.
 - [ ] `/order-received` renders `useOrderReturn`'s states **including `paymentInstructions`**.
 - [ ] Variant options render one control per axis; unbuyable options are disabled, not hidden.
+- [ ] Cart rows scope their busy state to the row (`l.pending` + `aria-busy`), and every repeated control (remove, ±, a drawer's close) has a unique accessible name.
+- [ ] A cart drawer closes on route change, is **inert** when closed (not merely invisible), and its backdrop is not a second control named "Close cart".
 - [ ] No hook logic was re-implemented by hand (address fields, quantity clamps, totals rows, shipping/payment branching).
-- [ ] The storefront carries the design you settled on before reading this file — no page ships the reference snippets' bare structure or placeholder copy, and the attributes and modifiers that matter to these products are designed rather than poured into one uniform block.
+- [ ] The storefront carries the design you settled on before reading this file — no page ships the reference snippets' bare structure or placeholder copy.
+- [ ] Specs and axes are rendered by what they are (`productSpecs`' `type`/`key`, `axis.key`) — not one uniform label/value table and one identical chip row.
 - [ ] Every page is within its budget above.
 
 Record these lines in your working notes; do not re-read this file.

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

@@ -63,11 +63,14 @@ try {
         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.
+        // 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.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
+          { key: "Weight", value: "248 g" },        // "<number> <unit>" → a numeric row
           { key: "Care", value: "Machine wash cold" },
         ],
 

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

@@ -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** (`productSpecs(product)` turns them into spec-table rows) |
+| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive **modifiers** (`productSpecs(product)` turns them into typed spec rows) |
 | **`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 |
@@ -64,7 +64,7 @@ Both lists below are field inventories — what the data supports — **not a la
 
 **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`.
 
-**Attributes and modifiers are individually designable.** `variantAxes` exposes `axis.key`/`axis.name` and `productSpecs` exposes `key`/`label` precisely so a page can branch on *which* one it is: colour as swatches, size as chips next to a size guide, "Composition" as bars, "Provenance" as a located line, "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.** `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.
 
 ## 4. Ribbons — in **both** views
 

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -19,14 +19,24 @@ import {
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
  *
  * Mount it once, above every storefront page (product list, product page,
- * cart, checkout, order-received) — it wraps <Routes>, it is NOT a <Route>:
+ * cart, checkout, order-received). It is NOT a <Route>. A store with shared
+ * chrome — nearly all of them — mounts it on a pathless layout route, wrapping
+ * the layout that renders <Outlet/>, which keeps the nav's cart badge and the
+ * page on one cart and leaves the admin outside:
  *
  *   import { base44 } from "@/api/base44Client";
+ *   <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
+ *     <Route path="/" element={<Home />} /> …
+ *   </Route>
+ *
+ * With no shared layout it can wrap <Routes> directly instead:
+ *
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * Inside <Routes> it throws ("is not a <Route> component"), since React Router
- * allows only <Route>/<Fragment> children there. To cover just some routes,
- * use a pathless layout route: element={<StorefrontProvider …><Outlet/></…>}.
+ * As a child of <Routes> it throws ("is not a <Route> component"), since React
+ * Router allows only <Route>/<Fragment> children there. Never the other way
+ * round either: a layout that renders the provider inside itself puts the nav
+ * outside it, so the badge and the cart page read different carts.
  *
  * or, if other modules also need the raw client, create it once and share it:
  *
@@ -128,7 +138,7 @@ export function useStorefrontState() {
   const ctx = useContext(StorefrontContext);
   if (!ctx) {
     throw new Error(
-      "Storefront hooks need a <StorefrontProvider> above them — mount it once around your <Routes> (it wraps the router; it is not a <Route>, and inside <Routes> React Router rejects it).",
+      "Storefront hooks need a <StorefrontProvider> above them — mount it once on a pathless layout route, wrapping the layout component that renders <Outlet/> (or, with no shared layout, around your <Routes>). It is never a <Route> itself: as a child of <Routes>, React Router rejects it.",
     );
   }
   return ctx;
@@ -204,6 +214,28 @@ export function useFormatMoney() {
  *   `useCartLine`/`useAddToCart` can handle failures locally.
  * - `applyCoupon(code)` resolves to `{ ok, cart }` or `{ ok: false, code,
  *   message }` — an invalid code is expected flow, not an exception.
+ *
+ * ## When `status` settles — and what it does not cover
+ *
+ * `status` is `"loading"` for exactly one thing: the **first** `getCart()` of
+ * the session has not resolved yet (internally, `cart === undefined`). It
+ * settles once, to `"empty"` or `"ready"`, and after that:
+ *
+ * - **A mutation never returns it to `"loading"`.** Adding, updating, removing
+ *   or couponing leaves `status` as it was, previous numbers on screen, until
+ *   the new view lands. There is no cart-wide busy flag by design: a page-wide
+ *   spinner for a 250ms quantity step is worse than the stale number, and the
+ *   right busy scope is the row (`useCartLine`'s `pending`) or the control that
+ *   started it.
+ * - `"empty"` therefore means *loaded, with no items* — including after
+ *   checkout consumes the cart — never "still arriving".
+ * - It flips `"empty"` → `"ready"` when the first line lands, so a header badge
+ *   and a drawer switch states off the same signal.
+ *
+ * So branch **`status`** for the page's loading/empty/ready shape, and watch
+ * **`useCartLine().pending`** (or your own flag around `addItem`) for "did that
+ * change land". Anything waiting on a mutation — a queued follow-up action, a
+ * script driving the page — waits on the second, never the first.
  */
 export function useCart() {
   const { client, cart, cartError, mutationError, runCart } = useStorefrontState();

package/src/commerce/storefront/index.js

@@ -16,12 +16,16 @@
  * 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"):
+ * Setup (once, above every storefront route — on a pathless layout route,
+ * wrapping the layout that renders <Outlet/>; as a child of <Routes> React
+ * Router throws "is not a <Route> component"):
  *
  *   import { StorefrontProvider } from "@/commerce/storefront";
  *   import { base44 } from "@/api/base44Client";
- *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
+ *   <Route element={<StorefrontProvider base44={base44}><StoreLayout /></StorefrontProvider>}>
+ *     <Route path="/" element={<Home />} /> …
+ *   </Route>
+ *   // no shared layout? <StorefrontProvider …> <Routes>…</Routes> </StorefrontProvider>
  *
  * ## Hooks
  * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
@@ -63,8 +67,10 @@
  * ## 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` → descriptive rows, keyed so each
- *     can be rendered its own way.
+ * - `productSpecs(product)` — `meta_data` → descriptive rows carrying an
+ *     inferred `type` (`numeric` with `number`/`unit` split out, `duration`,
+ *     `location`, `list` with `items`, `text`), so a weight can be a figure and
+ *     a composition bars instead of every modifier being one grey table row.
  */
 export {
   StorefrontProvider,

package/src/commerce/storefront/useCartLine.js

@@ -20,6 +20,37 @@ import { useCart } from "./StorefrontProvider";
  * request per settle instead of one per click; and `sold_individually` is
  * respected, so a one-per-customer product has no working "+".
  *
+ * ## When `pending` settles — the exact window
+ *
+ * `pending` is this line's own flag, not the cart's, and it is **not** true for
+ * the whole gesture:
+ *
+ * 1. **Click → `pending` stays `false`.** `increase`/`decrease` only set the
+ *    optimistic `quantity` and (re)start a `debounceMs` (250ms) timer. Nothing
+ *    is in flight yet, and a further click restarts the timer, so a burst of
+ *    clicks sends **one** request for the final number.
+ * 2. **Debounce elapses → `pending` becomes `true`** and the request goes out.
+ *    `remove()` skips this step: it cancels the timer and goes `pending`
+ *    immediately.
+ * 3. **`pending` returns to `false` only after the server's new cart view has
+ *    been published to the provider** — the awaited mutation resolves through
+ *    the provider's serialized queue, which sets the shared cart state before
+ *    the await returns. So `pending === false` with `error === null` means this
+ *    row's quantity, the cart's totals and any dependent badge are settled, not
+ *    merely that the request finished.
+ *
+ * Two consequences worth designing for. **Disable and mark only this row**
+ * (`disabled={!l.canIncrease || l.pending}`) — `pending` says nothing about the
+ * other lines, and greying the whole cart because one stepper is busy makes a
+ * 250ms update look like a page-wide stall. And **`pending` is the only
+ * mutation-settled signal**: `useCart().status` never returns to `"loading"`
+ * for a mutation (see its doc comment), so a caller that needs to know an
+ * update landed — a script driving the page, a queued follow-up action — waits
+ * on this flag, per row, and not on cart `status`.
+ *
+ * On failure `pending` returns to `false`, the optimistic quantity rolls back
+ * to what the server still holds, and `error` is `{ code, message }`.
+ *
  * @param {object} line a decorated line from `useCart().lines` (a raw
  *   `cart.items[n]` works too — it just has no `maxQuantity` hint)
  * @param {{debounceMs?: number}} [options]

package/src/commerce/utils/index.js

@@ -25,8 +25,9 @@
  * - `address-spec.js` — `addressFieldSpec`: the checkout address form as data,
  *   with country/state options that are always arrays.
  * - `images.js` — `productImages`: images normalized to `{src, name, alt}`.
- * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows, keyed so each
- *   can be rendered its own way.
+ * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows with an inferred
+ *   `type` (numeric/duration/location/list/text), so each can be rendered as
+ *   what it is rather than as another label/value row.
  *
  * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
  * layers headless hooks on top of this module, and a hook that pre-composes

package/src/commerce/utils/specs.js

@@ -1,32 +1,115 @@
 /**
  * Product spec rows — the descriptive properties a product page shows
- * (Material, Care, Fit, Provenance, Composition).
+ * (Material, Care, Fit, Provenance, Composition, Weight).
  *
  * These live in `product.meta_data` (the admin's *Modifiers* section) and are
  * **not** attributes and not ribbons: they describe the product, they don't
  * select a variant. Hidden keys (leading `_`) and empty values are skipped.
- * You render the rows yourself, and `key` is there so you don't have to render
- * them all the same way — a uniform list is the fallback, not the target:
  *
- *   const specs = productSpecs(product);
- *   {specs.length > 0 && <dl>{specs.map(s =>
- *     <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>)}</dl>}
+ * Each row carries a `type` — inferred from the value (and, for `"location"`,
+ * the key) — so the rendering decision is already made for you. **A `.map()`
+ * into one uniform label/value table is the fallback, not the target:** the
+ * types exist because a carat weight and a care instruction are not the same
+ * kind of fact and should not look alike.
  *
- * Branch on `s.key` to give the ones that carry this product's meaning their
- * own treatment (a composition as bars, a provenance as a located line, a
- * weight set in the display face) and let the rest fall through to the row
- * above.
+ * ```jsx
+ * // ❌ every product in every store, identical: one grey table
+ * <dl>{productSpecs(product).map((s) => (
+ *   <div key={s.key}><dt>{s.label}</dt><dd>{s.value}</dd></div>))}</dl>
+ *
+ * // ✅ branch on type — the figures read as figures, the rest stays a row
+ * {productSpecs(product).map((s) =>
+ *   s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />
+ * : s.type === "location" ? <Sourced key={s.key} place={s.value} />          // a located line, a pin
+ * : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />          // composition, materials
+ * : s.type === "duration" ? <Lead    key={s.key} label={s.label} value={s.value} />
+ * :                         <Row     key={s.key} label={s.label} value={s.value} />)}
+ * ```
+ *
+ * Design the two or three that carry *this* product's meaning (a weight set in
+ * the display face, a provenance beside a map, a composition as bars) and let
+ * the remainder fall through to the plain row. `key` is still there too, for
+ * when one particular modifier of this catalog deserves its own treatment
+ * regardless of type. And the rows need not sit in one block — a spec can go
+ * under the gallery, beside the price, or inside the description.
  *
  * @param {object} product
- * @returns {Array<{key: string, label: string, value: string}>} `[]` when the
- *   product has no visible meta_data — render nothing, not an empty section.
+ * @returns {Array<{key: string, label: string, value: string,
+ *   type: "numeric"|"duration"|"location"|"list"|"text",
+ *   number: number|null, unit: string|null, items: string[]}>}
+ *   `[]` when the product has no visible meta_data — render nothing, not an
+ *   empty section. `number`/`unit` are set for `numeric` and `duration`
+ *   (`unit` is `""` for a bare number), `items` for `list`, and are
+ *   `null`/`[]` otherwise. `value` is always the store's own text, unchanged —
+ *   the extra fields are there to render *with*, never a replacement for it.
  */
 export function productSpecs(product) {
   return (product?.meta_data ?? [])
     .filter((m) => m?.key && !String(m.key).startsWith("_") && m.value != null && m.value !== "")
-    .map((m) => ({
-      key: String(m.key),
-      label: String(m.key).replace(/_/g, " "),
-      value: String(m.value),
-    }));
+    .map((m) => {
+      const key = String(m.key);
+      const value = String(m.value);
+      return { key, label: key.replace(/_/g, " "), value, ...classify(key, value) };
+    });
+}
+
+const LOCATION_KEY =
+  /(origin|provenance|made[\s_-]?in|country|region|sourced|source|location|city|terroir|appellation|distillery|winery|atelier|workshop)/i;
+
+const DURATION_UNIT =
+  /^(sec|secs|second|seconds|min|mins|minute|minutes|hr|hrs|hour|hours|day|days|week|weeks|month|months|year|years|yr|yrs)$/i;
+
+/** Infer the render-relevant shape of one spec value. Never throws. */
+function classify(key, raw) {
+  const value = raw.trim();
+  const plain = { type: "text", number: null, unit: null, items: [] };
+
+  if (LOCATION_KEY.test(key)) return { ...plain, type: "location" };
+
+  const qty = parseQuantity(value);
+  if (qty) {
+    const type = DURATION_UNIT.test(qty.unit) ? "duration" : "numeric";
+    return { ...plain, type, number: qty.number, unit: qty.unit };
+  }
+
+  const items = parseList(value);
+  if (items) return { ...plain, type: "list", items };
+
+  return plain;
+}
+
+/** "0.75 ct" → {number: 0.75, unit: "ct"}; "18" → {number: 18, unit: ""}. */
+function parseQuantity(value) {
+  const m = /^([-+]?[\d.,]+)\s*(.*)$/.exec(value);
+  if (!m) return null;
+  const number = toNumber(m[1]);
+  if (number === null) return null;
+  const unit = m[2].trim();
+  // A unit is a word or two of symbols/letters. Anything longer is prose that
+  // happens to start with a number ("2 pieces, hand-cut in the studio").
+  if (unit && (!/^[\p{L}%°µ"'/²³.\- ]{1,12}$/u.test(unit) || unit.split(/\s+/).length > 2)) return null;
+  return { number, unit };
+}
+
+/** Grouped thousands are separators; a lone comma between digits is a decimal. */
+function toNumber(raw) {
+  let s = raw.replace(/\s/g, "");
+  if (/^[-+]?\d{1,3}(,\d{3})+(\.\d+)?$/.test(s)) s = s.replace(/,/g, "");
+  else if (/^[-+]?\d+,\d+$/.test(s)) s = s.replace(",", ".");
+  else if (s.includes(",")) return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** "70% wool / 30% cashmere" → ["70% wool", "30% cashmere"]. */
+function parseList(value) {
+  const parts = value
+    .split(/\s*[,;|·•/]\s*/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.length < 2) return null;
+  // Short fragments with words in them — not a sentence that happens to have commas.
+  if (parts.some((p) => p.length > 24 || p.split(/\s+/).length > 3 || /[.!?]/.test(p))) return null;
+  if (!parts.some((p) => /\p{L}/u.test(p))) return null;
+  return parts;
 }