@base44/app-plugin-commerce 0.2.3 → 0.2.4

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.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

@@ -105,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
@@ -181,12 +191,24 @@ anywhere.) Build your layout from:
 - **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
 
@@ -274,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.
@@ -449,7 +474,29 @@ 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, 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
 
@@ -461,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 carries the design you settled on before reading this file — no page ships the reference snippets' bare structure or placeholder copy.
+- [ ] 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.
 

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/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/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,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