@base44/app-plugin-commerce 0.2.3 → 0.2.5

package/base44/shared/commerce/card-payment.stripe.ts

@@ -16,9 +16,9 @@
  * makes card payment visible at checkout.
  *
  * That is the whole job. This file assumes the app is connected to Stripe and
- * reads the secret key the connection publishes (`stripeSecret()` below); how
- * the app gets connected is not this file's concern and nothing here needs
- * filling in.
+ * reads the secret key that connection publishes from **Base44 secrets**
+ * (`secrets.get("STRIPE_SECRET_KEY")`); how the app gets connected is not this
+ * file's concern and nothing here needs filling in.
  *
  * NEVER patch this file (or the stub it replaces) with partial edits. A
  * find_replace that leaves the originals behind gives every commerce function a
@@ -39,9 +39,14 @@
  * `card-payment.<provider>.ts` next to the stub. `references/online-payments.md`
  * has the rules; this file is the worked model.
  */
-import Stripe from "npm:stripe@18";
+import { secrets } from "base44:runtime";
 import { HttpError } from "./auth.ts";
 
+/** Stripe's REST API, called directly — no SDK to bundle in the function. */
+const STRIPE_API = "https://api.stripe.com/v1";
+/** Pinned, so a Stripe API release can never change the shapes read below. */
+const STRIPE_VERSION = "2025-10-29.clover";
+
 /** A hosted payment page for one order. */
 export interface CardPaymentPage {
   /** Where the customer goes to pay. */
@@ -52,37 +57,75 @@ export interface CardPaymentPage {
 }
 
 /**
- * Credentials come from backend env, never an entity and never the client. Read
- * lazily (per call, not at module load) so a store that has the file but not yet
- * the secret answers a clean 503 at checkout instead of failing to boot every
- * commerce function that imports it.
+ * Credentials come from **Base44 secrets**, never an entity, never backend
+ * source, never the client. Read lazily (per call, not at module load) so a
+ * store that has the file but not yet the secret answers a clean 503 at
+ * checkout instead of failing to boot every commerce function that imports it.
  */
+const secret = (name: string): string => {
+  try {
+    return String(secrets.get(name) ?? "");
+  } catch {
+    return "";
+  }
+};
+
 /**
- * Stripe's secret key, as published to the backend environment by the app's
- * Stripe connection. The names below are the conventional ones; if the key
- * arrives under a different name, this list is the only thing to change.
+ * Stripe's secret key, as published to the app's secrets by its Stripe
+ * connection. The names below are the conventional ones; if the key arrives
+ * under a different name, this list is the only thing to change.
  */
-const STRIPE_KEY_VARS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
+const STRIPE_KEY_SECRETS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
 
-const stripeSecret = () => {
-  for (const name of STRIPE_KEY_VARS) {
-    const value = Deno.env.get(name);
+const stripeKey = (): string => {
+  for (const name of STRIPE_KEY_SECRETS) {
+    const value = secret(name);
     if (value) return value;
   }
-  return null;
+  // The client is told only that cards are unavailable — which secret is
+  // missing is backend configuration, and naming it to a storefront visitor
+  // maps out the app's secrets for them. The detail goes to the log instead.
+  console.error(
+    `Stripe is not configured — no secret key found (looked for ${STRIPE_KEY_SECRETS.join(", ")}).`,
+  );
+  throw new HttpError(
+    503,
+    "Card payments are not available right now.",
+    "no_card_payment_provider",
+  );
 };
 
-const stripe = () => {
-  const key = stripeSecret();
-  if (!key) {
-    throw new HttpError(
-      503,
-      `Card payments are not configured — no Stripe secret key in the backend environment (looked for ${STRIPE_KEY_VARS.join(", ")}).`,
-      "no_card_payment_provider",
-    );
+/**
+ * The Base44 app this payment belongs to. Stamped on every payment's metadata
+ * as `base44_app_id`, which is how the platform attributes a Stripe payment
+ * back to this app — send it on every call that creates money movement.
+ */
+const base44AppId = (): string => secret("BASE44_APP_ID") || String(Deno.env.get("BASE44_APP_ID") ?? "");
+
+/**
+ * One Stripe REST call. A body makes it a POST (form-encoded, with an
+ * idempotency key); no body is a GET.
+ *
+ * Stripe's own error text stays in the log: it describes backend configuration
+ * (keys, account state, API parameters), so the caller gets a flat message.
+ */
+async function stripeCall(path: string, body?: URLSearchParams): Promise<any> {
+  const headers: Record<string, string> = {
+    "Authorization": `Bearer ${stripeKey()}`,
+    "Stripe-Version": STRIPE_VERSION,
+  };
+  if (body) {
+    headers["Content-Type"] = "application/x-www-form-urlencoded";
+    headers["Idempotency-Key"] = crypto.randomUUID();
   }
-  return new Stripe(key);
-};
+  const res = await fetch(`${STRIPE_API}${path}`, { method: body ? "POST" : "GET", headers, body });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) {
+    console.error(`Stripe ${path} failed (${res.status}):`, JSON.stringify(data?.error ?? {}));
+    throw new HttpError(502, "The payment provider could not process this request.", "payment_provider_error");
+  }
+  return data;
+}
 
 // Stripe amounts are in minor units; these currencies have none, so ×100 would
 // charge a hundred times the total.
@@ -102,27 +145,34 @@ export async function createCardPayment(
 ): Promise<CardPaymentPage> {
   // order_id + order_key in the metadata is how the premade payment-webhook
   // names the order when Stripe's event arrives, and what checkCardPaymentPaid
-  // compares against — keep it on both objects (the session's own metadata is
-  // not copied to the payment intent).
-  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
-  const session = await stripe().checkout.sessions.create({
-    mode: "payment",
-    line_items: [{
-      quantity: 1,
-      price_data: {
-        currency: String(order.currency || "USD").toLowerCase(),
-        product_data: { name: `Order #${order.order_number}` },
-        unit_amount: minorUnits(order.total, order.currency),
-      },
-    }],
-    customer_email: opts.customerEmail || undefined,
-    metadata,
-    payment_intent_data: { metadata },
-    success_url: opts.successUrl,
-    cancel_url: opts.cancelUrl,
-  });
-  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
-  return { url: session.url, reference: session.id };
+  // compares against; base44_app_id attributes the payment to this app. Keep
+  // all of it on both objects (the session's own metadata is not copied to the
+  // payment intent).
+  const metadata: Record<string, string> = {
+    order_id: String(order.id),
+    order_key: String(order.order_key),
+  };
+  const appId = base44AppId();
+  if (appId) metadata.base44_app_id = appId;
+
+  const params = new URLSearchParams();
+  params.set("mode", "payment");
+  params.set("line_items[0][quantity]", "1");
+  params.set("line_items[0][price_data][currency]", String(order.currency || "USD").toLowerCase());
+  params.set("line_items[0][price_data][unit_amount]", String(minorUnits(order.total, order.currency)));
+  params.set("line_items[0][price_data][product_data][name]", `Order #${order.order_number}`);
+  if (opts.customerEmail) params.set("customer_email", opts.customerEmail);
+  params.set("client_reference_id", String(order.id));
+  params.set("success_url", opts.successUrl);
+  params.set("cancel_url", opts.cancelUrl);
+  for (const [key, value] of Object.entries(metadata)) {
+    params.set(`metadata[${key}]`, value);
+    params.set(`payment_intent_data[metadata][${key}]`, value);
+  }
+
+  const session = await stripeCall("/checkout/sessions", params);
+  if (!session?.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
+  return { url: session.url, reference: String(session.id) };
 }
 
 /**
@@ -131,10 +181,10 @@ export async function createCardPayment(
  * the admin's "Check payment" button.
  */
 export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
-  const session = await stripe().checkout.sessions.retrieve(reference);
+  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(reference)}`);
   // The payment must be for THIS order — stops a reference to some other
   // (genuinely paid) session being replayed against a different order.
-  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
+  return session?.payment_status === "paid" && session?.metadata?.order_id === String(order.id);
 }
 
 /**
@@ -149,15 +199,18 @@ export async function refundCardPayment(_sr: any, _order: any, opts: {
 }): Promise<{ refund_id: string }> {
   // The stored reference is the Checkout Session; the refundable object is the
   // payment intent behind it, which only exists once the session was paid.
-  const session = await stripe().checkout.sessions.retrieve(opts.reference);
-  if (!session.payment_intent) {
+  const session = await stripeCall(`/checkout/sessions/${encodeURIComponent(opts.reference)}`);
+  if (!session?.payment_intent) {
     throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
   }
-  const refund = await stripe().refunds.create({
-    payment_intent: String(session.payment_intent),
-    amount: minorUnits(opts.amount, opts.currency),
-  });
-  return { refund_id: refund.id };
+  const params = new URLSearchParams();
+  params.set("payment_intent", String(session.payment_intent));
+  params.set("amount", String(minorUnits(opts.amount, opts.currency)));
+  const appId = base44AppId();
+  if (appId) params.set("metadata[base44_app_id]", appId);
+
+  const refund = await stripeCall("/refunds", params);
+  return { refund_id: String(refund.id) };
 }
 
 /** What parseWebhook distills an event into — the premade webhook's contract. */

package/base44/shared/commerce/card-payment.ts

@@ -34,8 +34,11 @@
  * Until implemented, the Credit Card checkout option answers
  * 503 `no_card_payment_provider`.
  *
- * Credentials belong in backend secrets/env (e.g. Deno.env.get("...")) —
- * never in an entity and never from the client.
+ * Credentials belong in Base44 secrets (`secrets.get("...")` from
+ * `base44:runtime`) — never in an entity, never in the code, never from the
+ * client. When one is missing, log which one and answer the caller with the
+ * flat 503 below: the storefront must not learn the names of the app's
+ * secrets.
  */
 import { HttpError } from "./auth.ts";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.3",
+  "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
@@ -105,14 +149,24 @@ resets to page 1 and keeps the current rows on screen (`refreshing`) while the
 page loads. `useCategories()` / `useRibbons()` → `{ items }` (arrays, children
 nested).
 
-Your card renders `name`, `images[0]?.src` (⚑ **images are `{src,name,alt}`
+Your card can render `name`, `images[0]?.src` (⚑ **images are `{src,name,alt}`
 objects and the array may be empty — render a placeholder, never a broken
 `<img>`**), `useProductPrice(row).label` (already "From €19.99" when the
 product sells variants — there is no product `type` flag), `on_sale`,
 `short_description`, `stock_status`, `average_rating`/`rating_count`,
-`ribbons`. Full field matrix:
+`ribbons` — and a row carries the whole product record, so `weight`,
+`dimensions`, `attributes[]` and `meta_data` are there too. Full field matrix:
 [`../references/catalog-rendering.md`](../references/catalog-rendering.md).
 
+That is an inventory of what you *can* show, not a card design and not a list
+to render in order. An even grid of identical cards, each with the same
+name/price/stars trio, is where a generated store lands by default and almost
+never where this catalog belongs: give the grid a rhythm (a hero piece spanning
+two columns, an editorial break between rows, a denser tile for a large
+catalog), and lead each card with the one or two fields *these* products are
+judged on — carat weight, focal length, edition size, ABV — read off
+`meta_data` via `productSpecs(row)`, not the fields every store shows.
+
 **Rails** (featured row, "new in") are the same hook with a filter
 (`{ featured: true, per_page: 4 }`). ⚑ Any filter may legitimately match
 nothing — render *nothing* then, never a heading over an empty row. Upsells
@@ -120,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.
@@ -134,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 */;
@@ -180,13 +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). `[]` 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.
+All optional — include what this store's products actually have — and each is
+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
 
@@ -208,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
@@ -223,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
@@ -241,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>
@@ -266,15 +384,50 @@ 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
 shipping and payment choices, gates the button (`canPlaceOrder` +
 `useCheckoutBlockers()` in words), and `placeOrder()` handles **both**
 navigations — online gateway → provider redirect, everything else →
-`/order-received`. The address form comes from `useAddressForm(which)` as a
+`/order-received`. Both are **full page loads** (`window.location.assign`),
+which is why the order-received page boots from the URL alone; pass
+`orderReceivedPath: null` and `navigate(orderReceivedUrl(result))` if you want
+a router transition instead. The address form comes from `useAddressForm(which)` as a
 field spec (`state` collected, country options never null); the two
 store-data choices come through the headless `ShippingMethodPicker` /
 `PaymentMethodPicker`, whose render props enumerate every branch.
@@ -378,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),
@@ -439,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 |
@@ -449,21 +606,70 @@ above the status guards.
 These budgets assume the hooks carry the logic and your markup carries only the
 design. Over budget ⇒ you are re-implementing something a hook does — an
 address spec, a quantity clamp, totals math, variant resolution, add-to-cart
-error recovery. Go back to the hook and delete your version.
+error recovery. Go back to the hook and delete your version. Design detail is
+not what pushes a page over: giving a colour axis swatches or a composition
+modifier bars costs a few hundred characters, and that is what the budget is
+for.
+
+## If you drive 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 — 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
+  `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`
+  (above), 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).
 
 ## 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.
+- [ ] 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.
-- [ ] A real purchase completes in the preview — pick a variant, add it, check out, place an offline order, land on `/order-received`.
 
 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 |
@@ -54,14 +54,18 @@ Three rules used to be prose here and are now enforced by exports — use them a
 
 - **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 a spec table — never a selector, never a ribbon.
+- **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.
 
-## 3. What each view renders
+## 3. What each view *can* render
 
-**Card:** image, name, `price.label`, sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page — like every other piece of storefront UI, the card is entirely yours to design.
+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.
+
+**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.
 
 **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` 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
 
 Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.

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

@@ -37,7 +37,7 @@ fs.copyFileSync(
 
 …and **enable the gateway**: `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }`. The `card` row is seeded off, so that call is what makes card payment visible at checkout — the usual reason a wired provider "doesn't show up".
 
-That is the whole of it. The file expects the app to be connected to Stripe and reads the secret key that connection publishes; **connecting the app is outside this kit and not described here.** Nothing in the file needs filling in, and no key belongs in the code. A missing key is not silent — checkout answers `503 no_card_payment_provider`.
+That is the whole of it. The file expects the app to be connected to Stripe and reads the secret key that connection publishes from the app's secrets (`secrets.get("STRIPE_SECRET_KEY")`); **connecting the app is outside this kit and not described here.** Nothing in the file needs filling in, and no key belongs in the code. A missing key is not silent — checkout answers `503 no_card_payment_provider`, with the name of the missing secret in the function log only.
 
 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.
 
@@ -55,9 +55,10 @@ With the gateway enabled and no provider behind it, picking Credit card answers
 For a **custom** provider (the shipped files already obey all of these):
 
 - **Write `card-payment.ts` whole** — one write of the complete file, never a `find_replace` into the stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"). The fix is always the whole-file write — which is also why the shipped provider files exist.
-- **Credentials come from backend env** (`Deno.env.get(...)`) — never an entity, never the client — and are read **lazily inside the call**, so a store with the file but no credential yet answers a clean 503 instead of failing to boot every function that imports it.
+- **Credentials come from Base44 secrets** (`import { secrets } from "base44:runtime"` → `secrets.get("STRIPE_SECRET_KEY")`) — never an entity, never the code, never the client — and are read **lazily inside the call**, so a store with the file but no credential yet answers a clean 503 instead of failing to boot every function that imports it.
+- **Never tell the caller what is misconfigured.** Secret names, provider error text and account state go to `console.error`; the storefront gets a flat `503 no_card_payment_provider` / `502` with no detail. A checkout page that names the missing secret hands a visitor a map of the app's configuration.
 - **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference` **and** check the payment names this order (its metadata `order_id` vs `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
-- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` **and** `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
+- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` **and** `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against. Stamp the app id alongside them (`base44_app_id`, from `secrets.get("BASE44_APP_ID")`), which is how the platform attributes the payment back to this app.
 - **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.
 

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,7 +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` → spec-table rows.
+ * - `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/storefront/useCheckout.jsx

@@ -73,6 +73,17 @@ function resolvePaymentMethod(gateways, picked) {
  *   result yourself (a manual-gateway result carries
  *   `result.payment_instructions`).
  *
+ *   Both navigations are **full page loads** (`window.location.assign`), not
+ *   router transitions: the provider hop has to leave the app, and the
+ *   order-received page is built to boot from the URL alone (`order_id` +
+ *   `order_key`), so a reload there is correct and shareable. Consequences
+ *   worth knowing: React state does not survive it, and a browser script
+ *   driving checkout loses its page context at this point — the order is
+ *   still placed, so verify by navigating fresh to
+ *   `orderReceivedUrl(result)`. For a client-side transition instead, pass
+ *   `orderReceivedPath: null` and `navigate(orderReceivedUrl(result))`
+ *   yourself.
+ *
  * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
  * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
  * `shipping_address_required`, `shipping_method_required`,

package/src/commerce/utils/index.js

@@ -25,7 +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` → spec-table rows.
+ * - `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,26 +1,115 @@
 /**
- * Product spec rows — the descriptive properties a product page lists in a
- * table (Material, Care, Fit).
+ * Product spec rows — the descriptive properties a product page shows
+ * (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:
  *
- *   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.
+ *
+ * ```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;
 }

package/src/commerce/utils/variants.js

@@ -41,8 +41,10 @@ export function attributeKey(attribute) {
 
 /**
  * The product's variation axes: every `attributes` entry, ordered by `position`.
- * These become the selectors on the product page. Descriptive properties are not
- * attributes — they are `meta_data` entries and belong in a spec table.
+ * These become the selectors on the product page — one control per axis, in
+ * whatever form suits the axis (swatches for a colour, chips for a size).
+ * Descriptive properties are not attributes: they are `meta_data` entries, read
+ * with `productSpecs`, and they never select anything.
  *
  * @param {object} product
  * @returns {Array<object>} the `product.attributes` entries