@base44/app-plugin-commerce 0.2.1 → 0.2.2

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

@@ -2,9 +2,10 @@
 stage: reference
 read_when: "The store opted into card payments and you are wiring the provider NOW."
 skip_when: "The store takes offline payments (the default) — nothing here applies; the decision itself lives in ../install/03-data.md."
-forget_when: "A test payment reaches /order-received as paid, or the provider file is copied, the secret stored, the webhook registered and the `card` gateway enabled."
+forget_when: "A test payment reaches /order-received as paid, or the provider file is copied and the `card` gateway is enabled."
 carry_forward:
   - "Wiring a provider = replace shared/commerce/card-payment.ts WHOLE (copy the shipped card-payment.<provider>.ts over it) — a partial edit breaks every commerce function's deploy with duplicate exports."
+  - "Stripe: the shipped card-payment.stripe.ts is used as-is once the app is connected to Stripe — connecting is outside the kit. Enabling the `card` gateway is the seed call."
   - "Only the provider can say an order is paid: confirmation always goes through checkCardPaymentPaid against the provider's API."
 ---
 
@@ -34,11 +35,9 @@ fs.copyFileSync(
 );
 ```
 
-Then three steps, in order:
+…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".
 
-1. **Secret** — store the merchant's Stripe **secret key** as the `STRIPE_SECRET_KEY` app secret (backend env; never in code, never in an entity) and redeploy the backend functions so they see it. Test keys (`sk_test_…`) work end to end.
-2. **Webhook endpoint** — register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for `checkout.session.completed` (dashboard, or `POST https://api.stripe.com/v1/webhook_endpoints` with `url` + `enabled_events[]` using the same secret key). **There is no signing secret to store**: the shipped `parseWebhook` treats events as nudges verified against Stripe's API (see below).
-3. **Enable the gateway** — `commerce/seed-store` with `{ payment_methods: ["offline", "card"] }`. It is seeded off, so none of the above is visible at checkout until this runs.
+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`.
 
 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.
 
@@ -56,7 +55,7 @@ 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 secret yet answers a clean 503 instead of failing to boot every function that imports it. Env vars are injected at deploy time: after adding a secret, redeploy.
+- **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.
 - **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.
 - **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.

package/skills/commerce/references/reviews.md

@@ -1,15 +1,15 @@
 ---
 stage: reference
-read_when: "You need review behaviour beyond dropping in <ReviewsBlock/> — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
-skip_when: "<ReviewsBlock product={p}/> or useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
+read_when: "You need review behaviour beyond useProductReviews — moderation, auto-approval, a customer's own reviews, or a policy the three built-in ones don't cover."
+skip_when: "useProductReviews is on the product page — that is list + submit + policy + the right confirmation copy already."
 forget_when: "A review submits, appears (or is held) as the store's auto-approve setting dictates, and the aggregate rating renders."
 carry_forward:
-  - "Reviews are part of the happy path: one block. The confirmation copy must come from the submit response, never hardcoded."
+  - "Reviews are part of the happy path: one hook. The confirmation copy must come from the submit response, never hardcoded."
 ---
 
 # Reviews
 
-Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and now the UI does too. Unless the store explicitly doesn't want them, put them on the product page — it is one line: `<ReviewsBlock product={product} />` (plus `policy` / `user` below). For custom markup take the hook it composes, `useProductReviews(product, { policy, user, requireRating, perPage })` — the list, the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc.
+Reviews are **part of the happy path**, not an extra: the backend always shipped complete, and the whole UI contract is one hook. Unless the store explicitly doesn't want them, put them on the product page: `useProductReviews(product, { policy, user, requireRating, perPage })` — the list with paging (`items`, `hasNext`/`loadMore`), the aggregates (`averageRating`, `ratingCount`), the whole form contract (`form`/`setField`/`fieldErrors`/`valid`/`submit`/`message`) and the policy gate (`canReview`, `reviewBlockedReason`, `requiresEmail`); exact shapes in its JSDoc. The markup around it — stars, rows, the form — is yours, like all storefront UI.
 
 ## What ships
 
@@ -20,7 +20,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 
 ## The `policy` prop
 
-`policy` is the store's review rule as one prop, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`<ReviewsBlock product={p} policy="login" user={user} />`) — the stricter policies need it:
+`policy` is the store's review rule as one option, replacing the patterns a storefront used to implement by hand. Pass your app's current user alongside it (`useProductReviews(product, { policy: "login", user })`) — the stricter policies need it:
 
 | `policy` | Who may submit | Blocked as |
 |---|---|---|

package/src/commerce/admin/README.md

@@ -4,8 +4,11 @@ React admin UI for the Base44 commerce template. Copy this
 folder into a Base44 app built on the default template (Vite + React +
 Tailwind + shadcn/ui + React Router) to get a full store back office.
 
-> Install, mounting & role setup: [`.agents/skills/commerce/install/01-install.md`](../../../.agents/skills/commerce/install/01-install.md) · architecture & operations: the commerce skill, [`.agents/skills/commerce/SKILL.md`](../../../.agents/skills/commerce/SKILL.md)
-> API references: [`.agents/skills/commerce/docs/api-admin.md`](../../../.agents/skills/commerce/docs/api-admin.md), [`.agents/skills/commerce/docs/api-storefront.md`](../../../.agents/skills/commerce/docs/api-storefront.md)
+> Docs live in the commerce skill, and every path below is **relative to that
+> skill folder** (`.agents/skills/commerce/` once installed): install, mounting
+> and role setup are `install/01-install.md`; the map for everything else is
+> `SKILL.md`; the API references are `docs/api-admin.md` and
+> `docs/api-storefront.md`.
 
 ## Mounting
 
@@ -39,7 +42,7 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    sample data when the store has no products yet. If `commerce/seed-store` was
    already run during installation — including when an agent generated a real
    catalog — the store counts as ready and this screen never shows; see
-   `.agents/skills/commerce/install/03-data.md`.
+   the commerce skill's install/03-data.md.
 
 ## External touchpoints
 

package/src/commerce/admin/layout/AuthGuard.jsx

@@ -24,7 +24,7 @@ const AUTH_CHECK_TIMEOUT_MS = 8000;
 
 /**
  * Blocks the admin UI unless the caller is an authenticated user with
- * role === "admin". Do NOT weaken this check — see .agents/skills/commerce/install/01-install.md.
+ * role === "admin". Do NOT weaken this check — see the commerce skill's install/01-install.md.
  * (Server-side RLS + requireAdmin() in functions enforce this independently.)
  *
  * Timing out resolves to **no user**, i.e. the sign-in screen — it never grants

package/src/commerce/admin/pages/products/Reviews.jsx

@@ -263,7 +263,7 @@ export default function Reviews() {
 /**
  * The one server-enforced review setting: everything else (login-gating,
  * verified-buyers-only, required ratings) is storefront policy — see
- * .agents/skills/commerce/references/reviews.md.
+ * the commerce skill's references/reviews.md.
  */
 function AutoApproveToggle() {
   const settings = useSettings();

package/src/commerce/admin/pages/settings/InventorySettings.jsx

@@ -51,7 +51,7 @@ export default function InventorySettings() {
             <p className="text-xs text-muted-foreground">
               Hold stock for unpaid orders for this many minutes. When the limit is reached, the
               pending order is cancelled and its stock released. Release runs opportunistically —
-              see .agents/skills/commerce/references/operations.md.
+              see the commerce skill's references/operations.md.
             </p>
           </div>
 

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -209,7 +209,7 @@ export default function PaymentsSettings() {
                   wiring one means implementing the four functions in
                   shared/commerce/card-payment.ts (rules, and a Stripe
                   implementation to paste, in
-                  .agents/skills/commerce/references/online-payments.md; the
+                  the commerce skill's references/online-payments.md; the
                   payment webhook is premade). Enabled without that, picking it
                   at checkout answers 503 no_card_payment_provider.
                   Deliberately not shown to the store operator — it's developer

package/src/commerce/storefront/index.js

@@ -1,15 +1,20 @@
 /**
- * Storefront React layer — hooks and ready-made blocks for the shopfront you
- * build. Ships with the Base44 Commerce Template next to the framework-free
- * `@/commerce/utils` (which it builds on); needs React and nothing else.
+ * Storefront React layer — **headless**: hooks and render-prop components that
+ * own the store's logic and hand you the data; they render nothing and carry
+ * no styling. Every element, class and word of copy in the storefront is
+ * written by you, against these APIs. Ships with the Base44 Commerce Template
+ * next to the framework-free `@/commerce/utils` (which it builds on); needs
+ * React and nothing else.
  *
- * **Two tiers.** The *identity* surfaces are yours to design — home, the
- * collection grid, the product page's layout, the product card, the theme. The
- * *commodity* surfaces ship as working blocks that inherit your theme —
- * checkout, cart lines, totals, coupon field, reviews, order-received, and the
- * product page's internals. Restyle or replace them; never hand-roll their
- * logic. Blocks are compositions of the hooks below, so outgrowing one means
- * rewriting a single region against an API you already know.
+ * The split: **logic is premade, UI never is.** Checkout repricing, variant
+ * resolution, cart state, review policies, order-return verification — done
+ * here, and hand-rolling any of it is where storefront bugs cluster. What a
+ * checkout or a product page *looks like* is the store's identity, and no two
+ * stores should share it — so nothing here emits markup. Each hook returns a
+ * complete view-model (statuses to branch on, ready-to-map arrays, handlers,
+ * error objects), and each doc comment states the render rules that keep the
+ * 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"):
@@ -18,40 +23,47 @@
  *   import { base44 } from "@/api/base44Client";
  *   <StorefrontProvider base44={base44}> <Routes>…</Routes> </StorefrontProvider>
  *
- * ## Blocks (drop in, then restyle)
- * `CheckoutBlock` · `CartLinesBlock` · `TotalsBlock` · `CouponFieldBlock` ·
- * `QuantityStepper` · `OrderReceivedBlock` · `ReviewsBlock` ·
- * `AddressFieldsBlock` · `VariantSelectorBlock` · `AddToCartBlock` ·
- * `ProductGalleryBlock` · `ProductSpecsBlock` · `BreadcrumbsBlock` ·
- * `ProductStripBlock` (needs your `renderCard` — no default card ships).
- *
  * ## Hooks
  * - `useStorefront` / `useStoreInfo` / `useFormatMoney` / `useMoney` — the
  *     shared client, cached store info (the ONLY source of payment gateways,
  *     currency and countries), money in the store's currency.
  * - `useProductList` / `useCategories` / `useRibbons` — a listing with paging,
  *     filters, `refreshing`, and failure as a visible state.
- * - `useProduct` / `useAddToCart` / `useProductPrice` / `useProductGallery` —
- *     the product page: fetch + variant selection + quantity + price + gallery,
- *     race-safe, with `status: "not_found"` and add-to-cart errors handled.
+ * - `useProduct` / `useAddToCart` / `useAddToCartButton` / `useProductPrice` /
+ *     `useProductGallery` — the product page: fetch + variant selection +
+ *     quantity + price + gallery, race-safe, with `status: "not_found"` and
+ *     every add-to-cart failure handled. `variantAxes(view, pick)` (from
+ *     `@/commerce/utils`, re-exported here) turns the resolved view into a
+ *     render-ready model for the selector you write.
  * - `useProductReviews` — the review list and the submit form, with the store's
- *     policy as a prop.
+ *     policy as a prop and field errors matching the server's codes.
  * - `useCart` / `useCartLine` / `useCoupon` — the shared cart (branch on
  *     `status`, render `lines` and `notices`), quantity steppers that clamp and
  *     recover, and the coupon field a store with coupons must have.
  * - `useCheckout` / `CheckoutProvider` / `useCheckoutContext` — the guided
  *     checkout: address state with automatic debounced shipping/tax
  *     recalculation, shipping and payment choice, a `canPlaceOrder` gate with
- *     named blockers, `placeOrder` with the online-payment redirect handled.
+ *     named blockers, `placeOrder` with both navigations handled (online →
+ *     provider redirect, manual → `/order-received`).
  * - `useAddressForm` / `useCountries` / `useTotalsLines` /
- *     `useCheckoutBlockers` — the address form as fields (state included,
- *     country options never null), one totals projection for cart and order,
- *     and blocker codes turned into copy.
- * - `ShippingMethodPicker` / `PaymentMethodPicker` — headless (render-prop)
- *     wrappers over the two choices that are store data, never hardcoded.
- * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
+ *     `useCheckoutBlockers` — the address form as a field spec you map to your
+ *     own inputs (state included, country options never null), one totals
+ *     projection for cart and order, and blocker codes turned into copy.
+ * - `useOrderReturn` — the mandatory `/order-received` page in one hook:
+ *     status, order, `lines`, `paymentLink`, `paymentInstructions`, noindex.
  * - `useStorefrontSeo` + `productSeo` / `collectionSeo` / `orderSeo` — titles,
  *     meta and product structured data; receipts are `noindex`.
+ *
+ * ## Render-prop components (headless — children is a function, no markup ships)
+ * - `ShippingMethodPicker` / `PaymentMethodPicker` — the two checkout choices
+ *     that are store data, never hardcoded, with their branching enumerated.
+ * - `CartLine` — per-line `useCartLine` binding for your cart rows, so a
+ *     `lines.map(...)` never calls a hook in a loop.
+ *
+ * ## 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.
  */
 export {
   StorefrontProvider,
@@ -62,7 +74,7 @@ export {
   useCart,
 } from "./StorefrontProvider";
 export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
-export { useOrderReturn } from "./useOrderReturn";
+export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
 export {
   REQUIRED_BILLING_FIELDS,
@@ -73,18 +85,18 @@ export {
 
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
-export { useProduct, useAddToCart } from "./useProduct";
+export { useProduct, useAddToCart, useAddToCartButton } from "./useProduct";
 export { useProductPrice, useMoney } from "./useProductPrice";
 export { useProductGallery } from "./useProductGallery";
 export { useProductReviews } from "./useProductReviews";
 
 // ── cart & checkout ────────────────────────────────────────────────────────
-export { useCartLine, useCoupon } from "./useCartLine";
+export { useCartLine, useCoupon, CartLine } from "./useCartLine";
 export { useAddressForm, useCountries } from "./useAddressForm";
 export { useTotalsLines, useCheckoutBlockers, blockerMessage } from "./useTotalsLines";
 
 // ── SEO ────────────────────────────────────────────────────────────────────
 export { useStorefrontSeo, productSeo, collectionSeo, orderSeo } from "./useStorefrontSeo";
 
-// ── blocks (default markup for the commodity surfaces) ─────────────────────
-export * from "./blocks";
+// ── view-model helpers (framework-free, from @/commerce/utils) ─────────────
+export { variantAxes, productSpecs } from "@/commerce/utils";

package/src/commerce/storefront/useCartLine.js

@@ -107,6 +107,43 @@ export function useCartLine(line, { debounceMs = 250 } = {}) {
   };
 }
 
+/**
+ * CartLine — headless per-line binding for the rows of a cart you render
+ * yourself. It renders **nothing**: the render function you pass as `children`
+ * receives the `useCartLine` controls for that line and returns your markup.
+ * It exists so a `lines.map(...)` doesn't tempt a hook call inside a loop:
+ *
+ *   const { lines } = useCart();
+ *   {lines.map(line => (
+ *     <CartLine key={line.item_key} line={line}>
+ *       {(l) => (
+ *         <li>
+ *           {line.name} {line.attributesLabel}
+ *           <button onClick={l.decrease} disabled={!l.canDecrease || l.pending}>−</button>
+ *           {l.quantity}
+ *           <button onClick={l.increase} disabled={!l.canIncrease || l.pending}>+</button>
+ *           <button onClick={l.remove}>Remove</button>
+ *           {l.error && <p role="alert">{l.error.message}</p>}
+ *         </li>
+ *       )}
+ *     </CartLine>
+ *   ))}
+ *
+ * Equivalent to extracting your own row component that calls `useCartLine` —
+ * use whichever reads better in your page.
+ *
+ * @param {{line: object, options?: {debounceMs?: number},
+ *   children: (controls: object) => React.ReactNode}} props
+ */
+export function CartLine({ line, options, children }) {
+  const controls = useCartLine(line, options);
+  if (typeof children !== "function") {
+    throw new Error("<CartLine> is headless: pass a render function as its only child.");
+  }
+  if (!line) return null;
+  return children(controls);
+}
+
 /**
  * useCoupon — the coupon field. Small, and the difference between a store that
  * can honour its own discounts and one that cannot.

package/src/commerce/storefront/useCheckout.jsx

@@ -1,6 +1,7 @@
 import React, { createContext, useCallback, useContext, useEffect, useState } from "react";
 import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useStorefrontState } from "./StorefrontProvider";
+import { orderReceivedUrl } from "./useOrderReturn";
 import {
   REQUIRED_BILLING_FIELDS,
   isShippingAddressComplete,
@@ -62,10 +63,15 @@ function resolvePaymentMethod(gateways, picked) {
  * - **The gate.** `canPlaceOrder` + `blockers` say exactly what still stands
  *   between the customer and the order — drive the button's disabled state
  *   and the "what's missing" hints from them instead of re-deriving.
- * - **placeOrder.** Sends the order, clears the shared cart, and (by default)
- *   redirects to the provider's payment page when the gateway is online.
- *   Resolves to `{ ok: true, result }` or `{ ok: false, error }`; a manual-
- *   gateway result carries `result.payment_instructions` to render.
+ * - **placeOrder.** Sends the order, clears the shared cart, and navigates:
+ *   an online gateway redirects to the provider's payment page
+ *   (`redirectToPayment`), everything else lands on the order-received page
+ *   (`orderReceivedPath`, default `/order-received`) — which is where a manual
+ *   order's payment instructions are rendered, so the offline default confirms
+ *   properly with no extra wiring. Resolves to `{ ok: true, result }` or
+ *   `{ ok: false, error }`. Pass `orderReceivedPath: null` to handle the
+ *   result yourself (a manual-gateway result carries
+ *   `result.payment_instructions`).
  *
  * Blocker codes, in the order checked: `cart_loading`, `empty_cart`,
  * `billing_incomplete`, `shipping_address_incomplete`, `shipping_recalculating`,
@@ -73,7 +79,8 @@ function resolvePaymentMethod(gateways, picked) {
  * `shipping_not_available`, `payment_method_required`.
  *
  * Options: `debounceMs` (600), `addressComplete` (predicate overriding the
- * country+city rule), `requiredBillingFields`, `redirectToPayment` (true).
+ * country+city rule), `requiredBillingFields`, `redirectToPayment` (true),
+ * `orderReceivedPath` ("/order-received"; null disables the navigation).
  */
 export function useCheckout(options = {}) {
   const {
@@ -81,6 +88,7 @@ export function useCheckout(options = {}) {
     addressComplete = isShippingAddressComplete,
     requiredBillingFields = REQUIRED_BILLING_FIELDS,
     redirectToPayment = true,
+    orderReceivedPath = "/order-received",
   } = options;
 
   const { client, info, cart, runCart, clearCart } = useStorefrontState();
@@ -204,6 +212,10 @@ export function useCheckout(options = {}) {
           typeof window !== "undefined"
         ) {
           window.location.assign(result.payment.checkout_url);
+        } else if (orderReceivedPath && !result.payment && typeof window !== "undefined") {
+          // A manual/offline order settles nothing online — land it on the
+          // order-received page, where its payment instructions are rendered.
+          window.location.assign(orderReceivedUrl(result, orderReceivedPath));
         }
         return { ok: true, result };
       } catch (e) {
@@ -224,7 +236,7 @@ export function useCheckout(options = {}) {
         setPlacing(false);
       }
     },
-    [placing, client, paymentMethod, billing, shipToDifferent, shipping, clearCart, redirectToPayment, runCart],
+    [placing, client, paymentMethod, billing, shipToDifferent, shipping, clearCart, redirectToPayment, orderReceivedPath, runCart],
   );
 
   return {

package/src/commerce/storefront/useOrderReturn.js

@@ -1,29 +1,36 @@
 import { useCallback, useEffect, useState } from "react";
-import { storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
+import { orderLines, storefrontErrorCode, storefrontErrorMessage } from "@/commerce/utils";
 import { useStorefrontState } from "./StorefrontProvider";
+import { orderSeo, useStorefrontSeo } from "./useStorefrontSeo";
 
 /**
  * useOrderReturn — the whole `/order-received` page in one hook. Mount the
  * route (it is mandatory — every payment link returns here) and branch on
- * `status`:
+ * `status`; the markup for every state is yours to write:
  *
- *   const { status, order, paymentLink, paymentInstructions, error, reload } =
- *     useOrderReturn();
- *   // "loading"   → spinner
- *   // "paid"      → thank-you + order summary (the order is now marked paid)
- *   // "unpaid"    → card order: offer paymentLink.url to pay now;
+ *   const { status, order, lines, paymentLink, paymentInstructions, error,
+ *     reload } = useOrderReturn();
+ *   // "loading"   → confirming copy (never an empty page)
+ *   // "paid"      → thank-you + order number + summary (the order is now paid)
+ *   // "unpaid"    → card order: link paymentLink.url to pay now;
  *   //               manual order: render paymentInstructions
- *   //               ({ description, account_details })
+ *   //               ({ description, account_details }) — these ARE how the
+ *   //               customer pays; a page that drops them strands the order
  *   // "cancelled" → payment was cancelled — offer paymentLink.url or support
  *   // "error"     → render error.message with a retry via reload()
  *
+ * `lines` are the order's items in the decorated cart-line shape, so the same
+ * row markup renders the bag and the confirmation; totals come from
+ * `useTotalsLines(order)`. The page is marked `noindex` automatically — a
+ * receipt carrying an order key must not rank (`seo: false` opts out).
+ *
  * It reads `order_id`/`order_key`/`payment` from the URL itself and verifies
  * with the payment provider server-side — safe and idempotent on every visit.
  *
  * `order` carries FLAT totals — `order.total`, `order.shipping_total`,
  * `order.total_tax`; there is no `order.totals` object on it.
  */
-export function useOrderReturn({ auto = true } = {}) {
+export function useOrderReturn({ auto = true, seo = true } = {}) {
   const { client } = useStorefrontState();
   const [result, setResult] = useState({ status: auto ? "loading" : "idle" });
 
@@ -52,5 +59,24 @@ export function useOrderReturn({ auto = true } = {}) {
     if (auto) reload();
   }, [auto, reload]);
 
-  return { ...result, reload };
+  useStorefrontSeo(seo ? orderSeo(result.order ?? null) : null);
+
+  return { ...result, lines: orderLines(result.order ?? null), reload };
+}
+
+/**
+ * The URL a just-placed manual/offline order should land on: the order-received
+ * page, carrying the id + key `useOrderReturn` reads back. `useCheckout` builds
+ * this itself by default (`orderReceivedPath`); use it directly only in a
+ * custom `placeOrder` flow.
+ *
+ * @param {{order_id: string, order_key: string}} result from `placeOrder`
+ * @param {string} [path]
+ */
+export function orderReceivedUrl(result, path = "/order-received") {
+  const q = new URLSearchParams({
+    order_id: result?.order_id ?? "",
+    order_key: result?.order_key ?? "",
+  });
+  return `${path}?${q}`;
 }

package/src/commerce/storefront/useProduct.js

@@ -225,3 +225,71 @@ export function useAddToCart() {
 
   return { add, adding, error, lastAdded, reset };
 }
+
+/**
+ * useAddToCartButton — the buy button's whole state machine, ready to bind to
+ * markup you write. Pass the entire `useProduct` result:
+ *
+ *   const p = useProduct(slug);
+ *   const buy = useAddToCartButton(p, { onAdded: () => navigate("/bag") });
+ *   <button disabled={buy.disabled} onClick={buy.add}>
+ *     {buy.adding ? "Adding…" : buy.soldOut ? "Sold out"
+ *       : buy.needsSelection ? "Select options" : "Add to bag"}
+ *   </button>
+ *   {buy.error && <p role="alert">{buy.error.message}</p>}
+ *
+ * What it wires so a hand-written buy box can't drop it: the button is gated on
+ * `view.purchasable`; a rejected add (sold out, stale variant) lands in `error`
+ * instead of leaving the button stuck on "Adding…"; a stale-variant rejection
+ * reloads the product; and the quantity controls respect `sold_individually`
+ * and tracked stock (`showQuantity` is false when only 1 can be bought — render
+ * no stepper then). Every label and every element is yours.
+ *
+ * @param {object} product the whole `useProduct` result
+ * @param {{onAdded?: (cart: object) => void}} [options]
+ * @returns {{add: () => Promise<object>, adding: boolean, error: object|null,
+ *   reset: () => void, disabled: boolean, soldOut: boolean,
+ *   needsSelection: boolean, purchasable: boolean,
+ *   quantity: number, setQuantity: (n: number) => void, increase: () => void,
+ *   decrease: () => void, canIncrease: boolean, canDecrease: boolean,
+ *   maxQuantity: number, showQuantity: boolean}}
+ */
+export function useAddToCartButton(product, { onAdded } = {}) {
+  const { add, adding, error, reset } = useAddToCart();
+  const view = product?.view ?? null;
+
+  const submit = useCallback(async () => {
+    if (!view) return { ok: false, error: { code: "no_product", message: "Product not loaded." } };
+    const res = await add(view.addToCart, product.quantity);
+    if (res.ok) onAdded?.(res.cart);
+    else if (res.error?.shouldReload) product.reload?.();
+    return res;
+  }, [add, view, product, onAdded]);
+
+  // A variable product with an incomplete selection isn't sold out — it needs
+  // a pick; only a resolved (or simple) unpurchasable view reads as sold out.
+  const soldOut = view
+    ? view.isVariable
+      ? view.complete && !view.purchasable
+      : !view.purchasable
+    : false;
+
+  return {
+    add: submit,
+    adding,
+    error,
+    reset,
+    disabled: !view?.purchasable || adding,
+    soldOut,
+    needsSelection: Boolean(view?.isVariable && !view.complete),
+    purchasable: Boolean(view?.purchasable),
+    quantity: product?.quantity ?? 1,
+    setQuantity: product?.setQuantity ?? (() => {}),
+    increase: product?.incQuantity ?? (() => {}),
+    decrease: product?.decQuantity ?? (() => {}),
+    canIncrease: Boolean(product?.canIncrease),
+    canDecrease: (product?.quantity ?? 1) > 1,
+    maxQuantity: product?.maxQuantity ?? 1,
+    showQuantity: (product?.maxQuantity ?? 1) > 1,
+  };
+}

package/src/commerce/utils/index.js

@@ -13,10 +13,10 @@
  *   checkout/return-page calls. Create ONE instance and import it everywhere.
  * - `variants.js` — variant selection: map attribute selections (Size, Color)
  *   to a `ProductVariation` and back, per-option availability, variant price
- *   ranges. See `.agents/skills/commerce/references/catalog-rendering.md`.
+ *   ranges. See the commerce skill's references/catalog-rendering.md.
  * - `shipping-promos.js` — read the store's real free-shipping configuration so
  *   "Free shipping over €150" copy states a configured rule, not an invented
- *   number. See `.agents/skills/commerce/docs/api-storefront.md`.
+ *   number. See the commerce skill's docs/api-storefront.md.
  * - `price.js` — `productPrice`: the from-price and price-range rules, encoded
  *   once so a card and a product page cannot disagree.
  * - `totals.js` — `cartTotalsLines` / `orderTotalsLines` / `orderLines` /
@@ -25,12 +25,14 @@
  * - `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.
  *
  * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
- * layers hooks and ready-made UI blocks on top of this module, and a hook that
- * pre-composes these helpers is the difference between a rule that holds and a
- * rule you have to remember. Use this module directly for non-React code, and
- * inside your own custom logic.
+ * layers headless hooks on top of this module, and a hook that pre-composes
+ * these helpers is the difference between a rule that holds and a rule you
+ * have to remember. Neither layer ships any UI: all markup and styling belong
+ * to the storefront you build. Use this module directly for non-React code,
+ * and inside your own custom logic.
  */
 export * from "./storefront.js";
 export * from "./variants.js";
@@ -39,3 +41,4 @@ export * from "./price.js";
 export * from "./totals.js";
 export * from "./address-spec.js";
 export * from "./images.js";
+export * from "./specs.js";

package/src/commerce/utils/shipping-promos.js

@@ -23,8 +23,8 @@
  * `available_shipping_methods` after `set-shipping-address` — that is computed
  * by the same engine and needs no extra exposure.
  *
- * Framework-free and dependency-free. See
- * `.agents/skills/commerce/docs/api-storefront.md` for the surrounding rules.
+ * Framework-free and dependency-free. See the commerce skill's
+ * docs/api-storefront.md for the surrounding rules.
  */
 
 /**

package/src/commerce/utils/specs.js

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