@base44/app-plugin-commerce 0.2.2 → 0.2.4

package/base44/functions/commerce/seed-store/seed-catalog.ts

@@ -19,6 +19,7 @@
  */
 import { HttpError } from "../../../shared/commerce/auth.ts";
 import { CONTINENTS } from "../../../shared/commerce/data/continents.ts";
+import { COUNTRIES } from "../../../shared/commerce/data/countries.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { scanAll } from "../../../shared/commerce/scan.ts";
 import {
@@ -188,6 +189,56 @@ export function normalizeCatalogPayload(body: any): CatalogSpec | null {
   };
 }
 
+const REGION_TYPES = ["country", "continent", "state"];
+
+/**
+ * Validate one region code against the static data the matcher uses, so a code
+ * that can never match is a 400 instead of a silently dead location.
+ *
+ * This exists because "everywhere else" has no country code, and a caller
+ * reaching for one anyway — `countries: ["*"]`, `["ALL"]`, `["ROW"]`, or an
+ * alpha-3 `["USA"]` — used to be accepted verbatim. The store then shipped with
+ * a location matching no address on earth, and the admin's country picker had
+ * nothing to select for it: an empty filter, no error anywhere. The catch-all
+ * is `rest_of_world: true`, and the error below says so.
+ */
+function checkRegionCode(
+  type: string,
+  code: string,
+  path: string,
+  err: (p: string, e: string) => void,
+): boolean {
+  const catchAllHint =
+    ` To cover every address no other location claims, pass rest_of_world: true instead of a placeholder code.`;
+  if (type === "continent") {
+    if (CONTINENTS.some((c) => c.code === code)) return true;
+    err(path, `unknown continent code: ${code} — known: ${CONTINENTS.map((c) => `${c.code} (${c.name})`).join(", ")}.${catchAllHint}`);
+    return false;
+  }
+  if (type === "country") {
+    if (COUNTRIES.some((c) => c.code === code)) return true;
+    err(path, `unknown country code: ${code} — must be an ISO 3166-1 alpha-2 code (US, IL, DE, not USA).${catchAllHint}`);
+    return false;
+  }
+  // state: "US:CA" — the country half must exist, and must declare states when
+  // the template ships them (US, CA, AU); elsewhere state is free text.
+  const [country, state] = code.split(":");
+  if (!state) {
+    err(path, `state region "${code}" must be COUNTRY:STATE — e.g. US:CA`);
+    return false;
+  }
+  const known = COUNTRIES.find((c) => c.code === country);
+  if (!known) {
+    err(path, `state region "${code}" names an unknown country: ${country} — must be an ISO 3166-1 alpha-2 code`);
+    return false;
+  }
+  if (known.states?.length && !known.states.some((s) => s.code === state)) {
+    err(path, `unknown ${known.name} state: ${state} — known: ${known.states.map((s) => s.code).join(", ")}`);
+    return false;
+  }
+  return true;
+}
+
 /**
  * A caller location is Wix-shaped: a scope (countries as ISO codes, whole
  * continents, explicit regions, or `rest_of_world` for the catch-all), shipping
@@ -219,19 +270,26 @@ function normalizeLocation(l: any, index: number, path: string, err: (p: string,
   const regions: any[] = [];
   for (const c of l.countries ?? []) {
     const code = String(c ?? "").trim().toUpperCase();
-    if (code) regions.push({ type: "country", code });
+    if (!code) continue;
+    if (!checkRegionCode("country", code, `${path}.countries`, err)) continue;
+    regions.push({ type: "country", code });
   }
   for (const c of l.continents ?? []) {
     const code = String(c ?? "").trim().toUpperCase();
     if (!code) continue;
-    if (!CONTINENTS.some((continent) => continent.code === code)) {
-      err(`${path}.continents`, `unknown continent code: ${code} — known: ${CONTINENTS.map((continent) => `${continent.code} (${continent.name})`).join(", ")}`);
-      continue;
-    }
+    if (!checkRegionCode("continent", code, `${path}.continents`, err)) continue;
     regions.push({ type: "continent", code });
   }
   for (const r of l.regions ?? []) {
-    if (r?.type && r?.code) regions.push({ type: String(r.type), code: String(r.code).toUpperCase() });
+    if (!r?.type || !r?.code) continue;
+    const type = String(r.type);
+    const code = String(r.code).toUpperCase();
+    if (!REGION_TYPES.includes(type)) {
+      err(`${path}.regions`, `unknown region type: ${type} — known: ${REGION_TYPES.join(", ")}`);
+      continue;
+    }
+    if (!checkRegionCode(type, code, `${path}.regions`, err)) continue;
+    regions.push({ type, code });
   }
   // The catch-all is defined by having NO regions, so a scoped "rest of the
   // world" is a contradiction, not a merge: silently dropping either half would

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.2",
+  "version": "0.2.4",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

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

@@ -9,6 +9,7 @@ carry_forward:
   - "/order-received is mandatory and renders useOrderReturn's states, including paymentInstructions — how a normal (offline) customer learns how to pay."
   - "Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design."
   - "Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations."
+  - "Every hook on a page goes above its status guards — a hook after an early return crashes with \"Rendered more hooks than during the previous render\"."
 ---
 
 # 02 — Storefront
@@ -22,9 +23,20 @@ One split decides everything here: **the logic is premade, the UI never is.**
   a hook does.**
 - **UI — yours, always.** Every element, class, layout and word of copy on
   every page. Nothing in `@/commerce/storefront` renders markup or carries CSS,
-  and this file deliberately doesn't hand you page bodies either — the design
-  is the part of the storefront only you can do, and it should be designed,
-  not assembled.
+  so there is no component to drop in and nothing to restyle — the design is
+  the part of the storefront only you can do, and it should be designed, not
+  assembled.
+
+## Before you begin
+
+**Decide how the store looks as if this kit did not exist** — identity, type,
+palette, spacing, the shape of a card, how a checkout is laid out — from the
+brief and your own judgement. Then use this file for **how to wire it**:
+everything below is implementation reference and **none of it is design input**.
+The bare tags, flat structure and placeholder copy show where the data goes in
+the fewest characters; they are not a look to adopt, keep or tweak. The finished
+store should look like what you would have built with no kit at all — the kit's
+only job is to make it cost far less code.
 
 Each hook returns a complete view-model — a `status` to branch on,
 ready-to-map arrays, handlers, error objects — and its **doc comment (JSDoc) is
@@ -93,14 +105,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
@@ -110,16 +132,34 @@ beside a product need no query: `p.upsells` / `p.crossSells` from `useProduct`.
 
 `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. Destructure `{ product, view, price, categories }`
-and build your layout from:
+404 page, not a spinner.
+
+⚑ **Call every hook above the status guards.** This page needs more than one,
+and a hook placed after an early `return` runs on some renders but not others —
+React then throws *"Rendered more hooks than during the previous render"* the
+moment the product resolves. All of these tolerate a null/loading product
+precisely so they can sit at the top:
+
+```jsx
+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 }));
+
+if (p.status === "loading")   return /* your loading state */;
+if (p.status === "not_found") return /* your 404 */;
+const { product, view, price, categories } = p;
+```
+
+(`variantAxes` and `productSpecs` are plain functions, not hooks — they can go
+anywhere.) Build your layout from:
 
 - **Price** — `price.label`, plus `price.compareAtLabel` (struck through) when
   on sale. Never read `product.price` directly — the parent's price is a
   rolled-up from-price.
-- **Gallery** — `useProductGallery(product, view)` → `{ hasImages, images,
-  active, activeIndex, setActiveIndex, next, prev }`. The active image already
-  follows the variant selection; `hasImages: false` means render your
-  placeholder.
+- **Gallery** — `g` from above → `{ hasImages, images, active, activeIndex,
+  setActiveIndex, next, prev }`. The active image already follows the variant
+  selection; `hasImages: false` means render your placeholder.
 - **Variant selector** — `variantAxes(view, p.pick)` → one entry per axis:
   `{ key, name, selectedOption, options: [{ value, selected, disabled,
   outOfStock, pick }] }`. Map it to any control — buttons, swatches, a dropdown.
@@ -141,22 +181,34 @@ and build your layout from:
     </fieldset>
   ))}
   ```
-- **Buy box** — `useAddToCartButton(p, { onAdded })` → `{ add, adding, error,
-  disabled, soldOut, needsSelection, quantity, increase, decrease, canIncrease,
-  canDecrease, showQuantity }`. It gates on purchasability, recovers from every
-  add failure and clamps quantity to stock and `sold_individually`. ⚑ Render
-  `error.message` inline; ⚑ `showQuantity: false` means no stepper (only 1 can
-  be bought); the button label should reflect `adding`/`soldOut`/
-  `needsSelection` — the words are yours.
+- **Buy box** — `buy` from above → `{ add, adding, error, disabled, soldOut,
+  needsSelection, quantity, increase, decrease, canIncrease, canDecrease,
+  showQuantity }`. It gates on purchasability, recovers from every add failure
+  and clamps quantity to stock and `sold_individually`. ⚑ Render `error.message`
+  inline; ⚑ `showQuantity: false` means no stepper (only 1 can be bought); the
+  button label should reflect `adding`/`soldOut`/`needsSelection` — the words
+  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.
+  `meta_data` (Material, Care, Provenance). `[]` means no section at all.
 - **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 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.
 
 ### Reviews — optional
 
@@ -244,7 +296,10 @@ 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.
@@ -327,18 +382,18 @@ function CheckoutForm() {
 }
 
 function AddressFields({ which }) {
-  const { fields, set, countriesLoading } = useAddressForm(which);
-  return fields.map((f) => (
+  const { fields, countriesLoading } = useAddressForm(which);
+  return fields.map((f) => (        /* each field carries its own setter: f.set */
     <label key={f.key}>
       {f.label}{f.required && " *"}
       {f.type === "select" ? (
-        <select value={f.value} onChange={(e) => set(f.key, e.target.value)} autoComplete={f.autoComplete}>
+        <select value={f.value} onChange={(e) => f.set(e.target.value)} autoComplete={f.autoComplete}>
           <option value="">{f.key === "country" && countriesLoading ? "Loading…" : `Select ${f.label}`}</option>
           {f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
         </select>
       ) : (
         <input type={f.type} value={f.value} required={f.required}
-               onChange={(e) => set(f.key, e.target.value)} autoComplete={f.autoComplete} />
+               onChange={(e) => f.set(e.target.value)} autoComplete={f.autoComplete} />
       )}
       {f.error && <span role="alert">{f.error}</span>}
     </label>
@@ -401,8 +456,8 @@ useStorefrontSeo(collectionSeo({ title, products: list.products }));      // col
 // order-received is already noindex via useOrderReturn
 ```
 
-It is a hook — call it above the page's early returns (the builders tolerate a
-null product).
+The `*Seo` builders tolerate a null product, so this sits with the other hooks
+above the status guards.
 
 ## Per-page output budgets
 
@@ -419,7 +474,29 @@ null product).
 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, two things make a
+working storefront look broken under a script:
+
+- **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
 
@@ -431,9 +508,8 @@ error recovery. Go back to the hook and delete your version.
 - [ ] `/order-received` renders `useOrderReturn`'s states **including `paymentInstructions`**.
 - [ ] Variant options render one control per axis; unbuyable options are disabled, not hidden.
 - [ ] No hook logic was re-implemented by hand (address fields, quantity clamps, totals rows, shipping/payment branching).
-- [ ] The storefront looks designed — the reference implementations above were adapted into this store's design, not shipped bare.
+- [ ] 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.
 - [ ] 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.
 
@@ -442,3 +518,4 @@ Record these lines in your working notes; do not re-read this file.
 - `/order-received` is mandatory and renders `useOrderReturn`'s states, including `paymentInstructions` — how a normal (offline) customer learns how to pay.
 - Branch cart/list/product UI on `status`, never on `isEmpty`/nullable data — `isEmpty` is false while loading by design.
 - Variant options that aren't buyable render disabled, never hidden; one control per axis, never a list of variations.
+- Every hook on a page goes above its status guards — a hook after an early return crashes with "Rendered more hooks than during the previous render".

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

@@ -32,19 +32,45 @@ try {
     store_name: "Aurora Threads",
     currency: "EUR",
     products: [
-      { name: "Classic T-Shirt",
-        sku: "TEE-CLASSIC",                        // optional; makes re-runs idempotent
-        regular_price: 19.99,
-        stock_quantity: 50,                        // implies manage_stock
-        categories: ["Clothing"],                  // get-or-created by display name
-        ribbons: ["Best Seller"],
-        images: ["https://…/tee.jpg"],             // URLs or { src, alt } — see Images below
-        short_description: "A soft, breathable everyday tee.",
-        description: "<p>Cut from combed cotton…</p>",     // HTML, rendered as rich text
-      },
+      // ── 1. Minimal. `name` is the only required key; a real store wants a
+      //       price too, and everything else below is opt-in.
+      { name: "Linen Scarf", regular_price: 45 },
+
+      // ── 2. Every product key the seeder accepts, on one product. Take the
+      //       lines a product actually needs and drop the rest — there is no
+      //       "complete" product to fill in.
       { name: "Runner Sneaker",
-        sku: "SNK-RUN",
+        sku: "SNK-RUN",                            // optional; makes re-runs idempotent
+        slug: "runner-sneaker",                    // derived from name when omitted
+        status: "publish",                         // draft | pending | private | publish (seeder defaults to publish)
+        featured: true,                            // → useProductList({ featured: true }) rails
+
         regular_price: 89,                         // inherited by variations that don't override
+        sale_price: 79,                            // sets on_sale; the storefront strikes through regular_price
+        date_on_sale_from: "2026-03-01T00:00:00Z", // optional sale window (omit → sale is open-ended)
+        date_on_sale_to: "2026-03-31T23:59:59Z",
+
+        stock_quantity: 12,                        // implies manage_stock: true
+        manage_stock: true,                        // only needed to force tracking with no quantity
+        low_stock_amount: 3,                       // overrides the store's threshold
+        backorders: "no",                          // no | notify | yes
+        sold_individually: false,                  // true → max 1 per order (kills the qty stepper)
+
+        short_description: "Cushioned everyday runner.",
+        description: "<p>Cut from recycled knit…</p>",      // HTML, rendered as rich text
+        images: ["https://…/sneaker.jpg"],         // URLs or { src, alt } — see Images below
+
+        categories: ["Shoes"],                     // get-or-created by display name
+        ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
+
+        // Descriptive properties → the spec table (`productSpecs(product)`).
+        // NOT variant axes and NOT ribbons: they describe the product, they
+        // don't select anything. Values are strings; a leading `_` hides a row.
+        meta_data: [
+          { key: "Material", value: "Recycled knit upper" },
+          { key: "Care", value: "Machine wash cold" },
+        ],
+
         attributes: [                              // the axes → one selector each in the storefront
           { name: "Size", options: ["41", "42"] },
           { name: "Color", options: ["Black", "White"] },
@@ -55,6 +81,21 @@ try {
           { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
             image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
         ],
+
+        weight: 0.8,                               // store's weight/dimension units
+        dimensions: { length: 30, width: 20, height: 12 },
+        tax_status: "taxable",                     // taxable | none
+        tax_group: "Products",                     // a tax group from the matched location
+
+        virtual: false,                            // true → no shipping (a service, a booking)
+        downloadable: false,                       // ↓ the three download keys apply only when true
+        downloads: [{ name: "Care guide", file_url: "https://…/care.pdf" }],
+        download_limit: 3,                         // -1 / omit = unlimited
+        download_expiry: 30,                       // days after purchase
+
+        // Accepted, but they take Product *ids* — which only exist after this
+        // call. Cross-link in a later admin-products update, not here.
+        upsell_ids: [], cross_sell_ids: [],
       },
     ],
     coupons: [{ code: "WELCOME10", discount_type: "percent", amount: 10 }],
@@ -69,6 +110,8 @@ try {
 
 **Running this through a code-execution tool? Return `res.data`, never the raw response.** `invoke` resolves to the raw HTTP response, which carries circular request/response objects — `return res` (or stringifying a thrown error whole) fails with `Converting circular structure to JSON` *even when the seed succeeded*, and a thrown error needs `e.response?.data` for the same reason.
 
+**The two products above are the range, not a template.** `name` is the only required key: every other line is opt-in, and each product in the array picks its own set independently — a plain product stays two keys long next to a fully specified one, and the fields it omits simply don't apply to it (no attributes ⇒ it sells no variants; no `meta_data` ⇒ no spec table; no `downloads` ⇒ nothing to deliver). Seed each product with the keys its own catalog entry actually has, and leave the rest out rather than padding with empty values.
+
 Reference taxonomy by **display name** (categories, ribbons, attributes, options) — existing records are matched case-insensitively and reused. The seeder derives slugs, checks SKU uniqueness, prices variations, and **rolls the parent's `price`/`regular_price`/`on_sale` up from the cheapest publishable variant** — never set a variant parent's price yourself. Unknown keys are rejected, so typos surface instead of vanishing.
 
 **Idempotency:** a product whose `sku` (or derived slug) exists is skipped and reported — safe to retry after a timeout, or to seed into a store that already has products. **Limits:** ≤100 products, ≤500 variations per call, ≤50 per product, ≤50 locations. Bad payloads fail **400** `invalid_payload` with `errors: [{ path, error }]`, a modified schema **422** `schema_incompatible` — both before anything is written.
@@ -76,8 +119,8 @@ Reference taxonomy by **display name** (categories, ribbons, attributes, options
 The response reports everything; these matter downstream:
 
 ```jsonc
-{ "catalog": { "products_created": 2, "variations_created": 3,
-    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 3 }] },
+{ "catalog": { "products_created": 2, "variations_created": 2,
+    "products": [{ "name": "Runner Sneaker", "id": "…", "slug": "runner-sneaker", "variation_count": 2 }] },
   "store_name": { "value": "Aurora Threads", "action": "created" },
   "payment_methods": null,          // null = the default (offline on, card off)
   "warnings": [] }                  // always present; read it — see the shipping section
@@ -97,7 +140,7 @@ locations: [
 ```
 
 - **`continents: ["EU"]`** spares you a 51-code country list. The seven codes are `AF` `AN` `AS` `EU` `NA` `OC` `SA`, and `EU` is the *continent* Europe, not the European Union. An unknown code fails `400 invalid_payload` with the known list.
-- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`.
+- **`rest_of_world: true`** is the catch-all — the location that matches every address no other location claims. It cannot also carry `countries`/`continents`/`regions`, and there is **no country code that means "everywhere"**: `countries: ["*"]`/`["ALL"]`/`["ROW"]`, and alpha-3 codes like `["USA"]`, are rejected **400** (every scope code is validated against the matcher's own country/continent/state data).
 - Other scopes: `countries: ["IL", "DE"]`, or explicit `regions: [{ type: "state", code: "US:CA" }]`. Matching is **country + state only** — no postcode or city rules exist.
 - One matched location supplies **both** the shipping rates and the tax groups: `shipping_rates: [{ name, cost, free_over? }]`, `tax_groups: [{ name, rates: [{ name, rate }] }]`, `shipping_tax: { type: "percent"|"fixed", value }`.
 

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

@@ -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` 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.
+
 ## 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/skills/commerce/references/shipping-and-tax.md

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

package/src/commerce/storefront/index.js

@@ -63,7 +63,8 @@
  * ## 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, keyed so each
+ *     can be rendered its own way.
  */
 export {
   StorefrontProvider,

package/src/commerce/storefront/useAddressForm.js

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

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/storefront/useProduct.js

@@ -245,6 +245,10 @@ export function useAddToCart() {
  * and tracked stock (`showQuantity` is false when only 1 can be bought — render
  * no stepper then). Every label and every element is yours.
  *
+ * A not-yet-loaded product is fine (`disabled: true`), so call this next to
+ * `useProduct` **above** the page's `loading`/`not_found` guards — a hook below
+ * an early return breaks the hook order the next render.
+ *
  * @param {object} product the whole `useProduct` result
  * @param {{onAdded?: (cart: object) => void}} [options]
  * @returns {{add: () => Promise<object>, adding: boolean, error: object|null,

package/src/commerce/storefront/useProductGallery.js

@@ -19,6 +19,10 @@ import { imageIndex, productImages } from "@/commerce/utils";
  * moves the active image to the variation's own picture while a manual pick
  * still wins until the selection changes again** — highlight, not replace.
  *
+ * A null/not-yet-loaded product is fine (`hasImages: false`), so call this with
+ * the other hooks **above** the page's `loading`/`not_found` guards — a hook
+ * below an early return breaks the hook order the next render.
+ *
  * @param {object} product
  * @param {object|null} [view] a `resolveSelection` view; its
  *   `display.image` is the variation's image

package/src/commerce/utils/index.js

@@ -25,7 +25,8 @@
  * - `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, keyed so each
+ *   can be rendered its own way.
  *
  * 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,16 +1,22 @@
 /**
- * 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).
  *
  * 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:
+ * 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>}
  *
+ * 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.
+ *
  * @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.

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