@base44/app-plugin-commerce 0.2.2 → 0.2.3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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
@@ -110,16 +122,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,13 +171,13 @@ 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
@@ -327,18 +357,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 +431,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
 
@@ -431,7 +461,7 @@ 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.
 - [ ] 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`.
 
@@ -442,3 +472,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/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/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/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