@base44/app-plugin-commerce 0.6.7 → 0.6.9

package/base44/entities/commerce.ProductReview.jsonc

@@ -24,7 +24,7 @@
     },
     "review": {
       "type": "string",
-      "description": "Review content"
+      "description": "Review text. May be empty for a stars-only review (submit-review requires text or a rating, not both)."
     },
     "rating": {
       "type": "integer",
@@ -38,7 +38,7 @@
       "description": "Derived: reviewer purchased the product. Set by commerce/storefront-catalog submit-review."
     }
   },
-  "required": ["product_id", "review"],
+  "required": ["product_id"],
   "rls": {
     "read": { "user_condition": { "role": "admin" } },
     "create": { "user_condition": { "role": "admin" } },

package/base44/functions/commerce/storefront-catalog/entry.ts

@@ -396,12 +396,16 @@ async function submitReview(sr: any, p: any, user: any): Promise<any> {
   const review = String(p.review ?? "").trim();
   const rating = p.rating == null ? null : Math.floor(Number(p.rating));
 
-  if (!review) {
-    throw new HttpError(400, "review is required.", "review_incomplete");
-  }
   if (rating != null && (rating < 0 || rating > 5)) {
     throw new HttpError(400, "Rating must be between 0 and 5.", "invalid_rating");
   }
+  // Text or stars — either alone is a valid review. Requiring text rejected
+  // every stars-only submission from a form that treats the write-up as
+  // optional, with a 400 the customer can't act on. Rating 0 is "unrated"
+  // (the aggregates ignore it), so it can't stand in for the missing text.
+  if (!review && !(rating != null && rating >= 1)) {
+    throw new HttpError(400, "A review needs text or a star rating.", "review_incomplete");
+  }
 
   const verified = await hasPurchased(sr, reviewerEmail, product.id);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -118,14 +118,14 @@ batch (above).
 | Topic | Open when | Size |
 |---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 35K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 37K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
-| [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
+| [`references/reviews.md`](./references/reviews.md) | review policies (open by default; login-gated, verified buyers), moderation | 6K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |
 | [`references/emails.md`](./references/emails.md) | order-email recipients, subjects, the log | 5K |
 | [`references/admin-product-form.md`](./references/admin-product-form.md) | editing the shipped product editor | 6K |

package/skills/commerce/docs/api-storefront.md

@@ -114,14 +114,14 @@ This is the **only** way a storefront can enumerate ribbons (the entity is admin
 No payload. Returns `{ "attributes": [ { ...attribute, "terms": [ ...values ] } ] }` — each attribute (`id, name, code, order`) with its values (`id, attribute_id, name, order, count`), both sorted by `order`; for filter UIs. Filter with `list-products` `attribute_id` (id or attribute **name**) + `attribute_term` (the value name); `code` is the stable key for a URL.
 
 ### `submit-review`
-**Payload:** `{ product_id, email?, reviewer?, review, rating? }` — `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
+**Payload:** `{ product_id, email?, reviewer?, review?, rating? }` — at least one of `review` (text) or `rating` (1–5); `email` is required for guests (`400 email_required`); a signed-in caller's session email always wins.
 
 > A React storefront reaches this call as `submitReview` (and the paginated list as `getProductReviews`) on the client from `@/commerce/storefront`'s `useStorefront()`, with the list itself already riding along on the product; policies and moderation are [`../references/reviews.md`](../references/reviews.md). Read on for the raw contract.
 
-**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. `rating` is optional (0–5). `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
+**Public by default: anyone can review with an email address — no login.** A guest passes `email`; for a signed-in caller the session email always wins (the payload cannot impersonate). `reviewer` is the display name only, defaulting to the account's `full_name` then the email's local part. **Text or stars — either alone is valid**: `rating` is 0–5 (0 = unrated, so a stars-only submission needs 1–5); `review_incomplete` fires only when both are missing. `verified` is derived from the email's order history. Status is `hold` unless `products.auto_approve_reviews` — the one server-side switch, so a hardcoded "awaiting approval" message is wrong when it is on. Stricter policies (login-gated, verified buyers only, rating required) are the storefront's own gate around this call — the server accepts any valid email: [`../references/reviews.md`](../references/reviews.md).
 
 **Response:** `{ "review_id", "status": "hold"|"approved", "verified": true }`
-**Errors:** `404 not_found`, `400 email_required|review_incomplete|invalid_rating`.
+**Errors:** `404 not_found`, `400 email_required|review_incomplete` (neither text nor stars)`|invalid_rating`.
 
 ---
 

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

@@ -156,9 +156,13 @@ Build your layout from — all optional, **not one component style**:
 - **Variant selector** — `variantAxes(view, p.pick)`, one entry per axis:
 
   ```jsx
+  const SWATCH = { Ivory: "#F2EDE4", "Obsidian Black": "#101014" };   // this catalog's colour names → CSS
   {variantAxes(view, p.pick).map((axis) => (
     <fieldset key={axis.key}>{/* label from axis.name / axis.selectedOption */}
-      {axis.options.map((o) => (
+      {axis.options.map((o) => /colou?r/i.test(axis.name) ? (
+        <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}
+                className="swatch" style={{ background: SWATCH[o.value] }} title={o.value} aria-label={o.value} />
+      ) : (
         <button key={o.value} disabled={o.disabled} aria-pressed={o.selected} onClick={o.pick}>
           {o.value}{/* o.outOfStock → mark visibly */}
         </button>
@@ -167,7 +171,7 @@ Build your layout from — all optional, **not one component style**:
   ))}
   ```
 
-  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. **Render each axis by what it is** — swatches for a colour axis, chips with a size guide beside a size axis; every axis as the identical chip row is a generated-page tell. That differentiation is semantic — what the control *shows* — built from your classes, not extra chrome around each row.
+  ⚑ **One control per axis, never a list of variations**, and ⚑ **an unbuyable option renders `disabled`, never hidden** (`outOfStock` stays visible, just marked). `view.missingAxes` names what's unpicked. ⚑ **Pick the control per attribute, as the branch above does**: a colour axis as colour circles (the name stays reachable — `title`, `aria-label`, and the axis label showing `selectedOption`), size chips beside a size guide, a select for a long list; a specialty control where it genuinely fits, not on every axis — but every axis as the same bare chip row is the flattest page this kit produces. Any control keeps the contract: disabled, out-of-stock marked, selection visible.
 - **Buy box** — one button, and **you supply its four words**:
 
   ```jsx
@@ -190,7 +194,7 @@ Build your layout from — all optional, **not one component style**:
 
   ⚑ **Never `.map()` the whole list into one grey label/value table** — that is the single most reliable tell of a generated product page. Design the two or three rows that carry *this* catalog's meaning as what they are (a weight set in the display face, a composition as bars, a provenance beside its place); let the rest fall through to the 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. Branch on `s.key` too where one particular modifier deserves its own treatment regardless of type. ⚑ **Look a spec up with `findSpec(rows, "care")`** (ignores case, spaces, `_`, `-`): meta keys are free text (`care`, `Care`, `Care Instructions`), so `rows.find(s => s.label === "Care")` silently never matches and renders the fallback forever. `[]` means no section at all.
 - **Breadcrumbs** — from `categories` (`/collection?category_id=${c.id}`); skip on a flat catalog. Ribbons (`productRibbons(product)`) are labels, not breadcrumbs.
-- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()`, open to guests. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
+- **Reviews, only if the store wants them** — no review UI is a complete outcome (then no star ratings on cards either: an average of nothing is `0`). `p.reviews` arrives with the product as `{ items, page, per_page, has_next }`; submitting is `submitReview` off `useStorefront()` — text or stars, either alone submits. ⚑ **The form renders for every visitor by default** (guests supply an email; hide the field when signed in) — login-gate it only when the store asks. ⚑ Derive the confirmation from the response's `status` (`"approved"` vs `"hold"`) — a hardcoded "awaiting approval" lies to every store that auto-approves — and refresh the list after, or the review doesn't appear. Field codes, policies and moderation: [`../references/reviews.md`](../references/reviews.md).
 - **Title** — give each page type its own `<title>` and description; a store whose every page shares one static title is invisible to search. Nothing here emits structured data either — if the store wants rich results, emit your own `Product`/`Offer` JSON-LD from `product` and `view.display` (price, currency, availability).
 
 ## Cart / bag
@@ -249,7 +253,7 @@ import { CheckoutProvider, useCheckoutContext, AddressFields, ShippingMethodPick
 
 `useCheckout` reprices shipping/tax from the address automatically (debounced, never on a half-typed address), derives the shipping and payment choices, gates the button, and `placeOrder()` handles **both** navigations — online gateway → provider redirect, everything else → `/order-received` — as **full page loads** (`<CheckoutProvider options={{ orderReceivedPath: null }}>` for a router transition instead). `CheckoutProvider` shares it across the page's regions.
 
-⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
+⚑ Rules: render each picker's `hint` and every branch; a single shipping or payment option still *shows* what it is — never a picker of one, never "nothing selected". ⚑ Picks are instant: both pickers reflect a click immediately (shipping optimistically), and `mustChoose` stays true after a choice — the radios keep rendering, still changeable; never disable options while `syncing`/`choosing` (the hint covers it). Render `addressError` on the address fields. ⚑ Payment methods, currency and countries come from `useStoreInfo()`/`useCountries()` only — `cart.payment_gateways` is always `undefined`, and a default store offers `offline` only, so never hardcode a card option.
 
 ⚑ **A disabled place-order button must say why** — the silent disabled button is the most common checkout dead end. `blockers` is an array of codes; write one line per code, in the store's voice, anchored near the field that fixes it: `empty_cart` (bag is empty) · `billing_incomplete` (required address fields — `missingBillingFields` names them) · `shipping_address_incomplete` (the separate delivery address) · `shipping_address_required` (no address to price yet) · `shipping_method_required` (choose a delivery option) · `shipping_not_available` (this address can't be delivered to) · `payment_method_required` (choose how to pay) · `cart_loading` / `shipping_recalculating` (transient — a quiet "one moment", not an error).
 
@@ -282,7 +286,7 @@ function CheckoutForm() {
                 {m.title} {m.costLabel}
               </label>
             ))}
-            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}
+            {!mustChoose && chosen && <p>{chosen.title} {chosen.costLabel}</p>}{/* the lone option */}
           </fieldset>
         )}
       </ShippingMethodPicker>

package/skills/commerce/references/reviews.md

@@ -5,6 +5,7 @@ skip_when: "The product page already renders `p.reviews` and submits through `su
 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: the list arrives with the product, submitting is one client call. The confirmation copy must come from the submit response's `status`, never hardcoded."
+  - "The review form renders for every visitor by default — guests included, with an email field. Login-gating is an explicit store request, implemented as one conditional around the form."
 ---
 
 # Reviews
@@ -16,7 +17,7 @@ Reviews are **part of the happy path**, not an extra: the backend always shipped
 Both live on the storefront client in `@/commerce/utils` — in React, `useStorefront()` is that client:
 
 - **`getProductReviews(slugOrRef, { page, per_page })`** → `{ items, page, per_page, has_next, average_rating, rating_count }`. The same reviews `get-product` returns — page or refresh the list without re-fetching the page; `useProduct(slug, { reviewsPerPage })` sizes the first one.
-- **`submitReview({ product_id, review, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. `review` is the body text and is required; `rating` is optional, **0–5**; `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
+- **`submitReview({ product_id, review?, rating?, reviewer?, email? })`** → `{ review_id, status, verified }`. **Text or stars — at least one**: `review` is the body text, `rating` is **1–5 stars** (0 counts as unrated); stars-only and text-only are both valid, only both missing rejects. `reviewer` is the display name. It **rejects** with `email_required` | `review_incomplete` (neither text nor stars) | `invalid_rating` | `not_found` — catch it, read `storefrontErrorCode(e)`, and land each code on its own field, so a failed submit says what to fix instead of resolving into nothing. After an approved submission, refresh the list yourself so the review actually appears.
 
 ## What ships
 
@@ -25,17 +26,17 @@ Both live on the storefront client in `@/commerce/utils` — in React, `useStore
 - `storefront-account` `my-reviews` lists a signed-in customer's own — what a "My reviews" account tab renders from;
 - moderation is in the admin (Products → Reviews); `commerce/admin-reviews` recalculates the product's rating on every status change.
 
-## The policy is the store's
+## The policy is the store's — and open is the default
 
-Which visitors may submit is a gate **you** render, in your own words. The three patterns worth knowing:
+Which visitors may submit is a gate **you** render, in your own words — and **the default is no gate at all**. Build the form for every visitor, signed in or not (that is the server's own rule); a review form a guest cannot use is a policy the store has to ask for, never something to add on your own initiative. The two stricter patterns are each one small change away when the store does ask:
 
 | Policy | Who may submit | How you implement it |
 |---|---|---|
-| **Open** (the server's own rule) | anyone with a valid email | render the form for everyone; the email field is required for guests |
-| **Login-gated** | a signed-in visitor only | render the form only when your app has a user; otherwise your "sign in to review" line |
+| **Open — the default** | anyone with a valid email | render the form for everyone; the email field is required for guests, hidden when signed in |
+| **Login-gated** | a signed-in visitor only | one conditional around the same form: render it when your app has a user, otherwise your "sign in to review" line |
 | **Verified buyers** | someone whose own orders include a `processing`/`completed` order for this product | check `storefront-account` `my-orders` for the product, gate on the result |
 
-Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side), and make the stars mandatory by validating before you call. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
+Policies are **UI-side by design**: the server accepts any valid email, so a stricter rule is exactly this gate — and a policy that must hold against handcrafted API calls too belongs in a backend function of your own wrapping `submit-review`. Either way: hide the email field for a signed-in visitor (the session's email wins server-side). The server needs only one of text/stars — if your form makes either (or both) mandatory, validate before you call, so the customer meets your words rather than a raw 400. An honest middle ground for most stores: accept everything and render the `verified` flag as a "Verified purchase" badge.
 
 ## Auto-approval and moderation
 

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

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef, useState } from "react";
-import { NavLink, useLocation } from "react-router-dom";
+import { Link, NavLink, useLocation } from "react-router-dom";
 import { Badge } from "@/components/ui/badge";
 import {
   BadgePercent,
@@ -9,6 +9,7 @@ import {
   Settings,
   ShoppingCart,
   Sparkles,
+  Store,
   Users,
 } from "lucide-react";
 import { call } from "../lib/api";
@@ -105,8 +106,17 @@ export default function Sidebar({ onNavigate, onOpenBot }) {
           </div>
         ))}
       </nav>
-      {onOpenBot && (
-        <div className="border-t p-3">
+      <div className="space-y-0.5 border-t p-3">
+        {/* The way back out — the storefront the merchant is managing. */}
+        <Link
+          to="/"
+          onClick={onNavigate}
+          className="flex items-center gap-2.5 rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        >
+          <Store className="h-4 w-4 shrink-0" />
+          <span className="flex-1">View storefront</span>
+        </Link>
+        {onOpenBot && (
           <button
             type="button"
             onClick={onOpenBot}
@@ -115,8 +125,8 @@ export default function Sidebar({ onNavigate, onOpenBot }) {
             <Sparkles className="h-4 w-4 shrink-0 text-primary" />
             <span className="flex-1 text-left">StoreAdmin bot</span>
           </button>
-        </div>
-      )}
+        )}
+      </div>
     </div>
   );
 }

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

@@ -137,7 +137,10 @@ export default function Reviews() {
         label: "Review",
         render: (row) => (
           <div className="max-w-md">
-            <p className="line-clamp-2 text-sm">{row.review}</p>
+            {/* A rating-only review is valid — say so, or the row reads as blank. */}
+            {row.review
+              ? <p className="line-clamp-2 text-sm">{row.review}</p>
+              : <p className="text-sm italic text-muted-foreground">Rating only — no text</p>}
             {row.verified && <span className="text-xs text-green-700">✓ Verified owner</span>}
           </div>
         ),

package/src/commerce/storefront/pickers.jsx

@@ -50,12 +50,20 @@ function resolveCheckout(name, prop, ctx) {
  *   chosen         the chosen/auto-selected entry, or null
  *   selected       alias of `chosen` (the name the payment picker uses)
  *   choose         (id) => Promise
- *   mustChoose     status === "choice_required" → render methods as a picker
+ *   mustChoose     more than one method → render methods as a picker
  *   single         exactly one method offered — already chosen
+ *   choosing       a pick is in flight — `selected` already reflects it
  *   syncing        an address edit is being repriced
  *   hint           { code, severity, serverMessage } | null (see above)
  *   addressError   { code, message } | null — the server's own words
  *
+ * `mustChoose` stays true after a choice is made — with several methods the
+ * radios keep rendering, the chosen one checked, so the customer can change
+ * their mind; collapsing a made choice to static text strands it. A pick
+ * reflects in `selected` from the click (optimistically, while the priced view
+ * catches up), so never disable the options while `choosing`/`syncing` — the
+ * hint line is the affordance for that, not a locked control.
+ *
  * `single` and `mustChoose` are never both true, and `single` guarantees
  * `chosen` — a single option still *shows* what it is (title + `costLabel`),
  * never a picker of one. Never render `cart.chosen_shipping_method` directly:
@@ -70,6 +78,7 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     chosenShippingMethod: chosen,
     singleShippingMethod: single,
     chooseShippingMethod: choose,
+    shippingChoicePending: choosing,
     shippingSyncing: syncing,
     addressError,
   } = checkout;
@@ -96,8 +105,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
     chosen: decoratedChosen,
     selected: decoratedChosen,
     choose,
-    mustChoose: status === "choice_required",
+    // True whenever there is a real choice — including after one is made, so a
+    // made choice stays changeable instead of collapsing to static text.
+    mustChoose: status === "choice_required" || methods.length > 1,
     single: single ?? (methods.length === 1), // fallback: a hand-built checkout object
+    choosing: choosing ?? false,
     syncing,
     hint,
     addressError,
@@ -119,9 +131,11 @@ export function ShippingMethodPicker({ checkout: checkoutProp, children }) {
  *
  * `single` guarantees `value` and `selected` — never render the one-gateway
  * branch as "nothing selected yet" — and both re-resolve when store info
- * changes. A default-seeded store offers `offline` only, so never hardcode a
- * card option. Titles and descriptions are the admin's copy: render them, don't
- * invent your own.
+ * changes. A pick is plain local state: it reflects the instant it is clicked,
+ * with no server round trip — so never disable these options while the cart is
+ * repricing elsewhere. A default-seeded store offers `offline` only, so never
+ * hardcode a card option. Titles and descriptions are the admin's copy: render
+ * them, don't invent your own.
  */
 export function PaymentMethodPicker({ checkout: checkoutProp, children }) {
   const checkout = resolveCheckout("PaymentMethodPicker", checkoutProp, useCheckoutContextOptional());

package/src/commerce/storefront/useCheckout.jsx

@@ -69,6 +69,10 @@ function resolvePaymentMethod(gateways, picked) {
  *   `not_needed` (virtual cart — render nothing). `singleShippingMethod` flags
  *   the one-option case and `chosenShippingMethod` is filled for it, so a single
  *   option is never left unselected and never rendered as a picker of one.
+ *   **A pick applies optimistically**: `chosenShippingMethod` reflects it from
+ *   the click, while the priced view catches up in the background
+ *   (`shippingChoicePending` is true for that window) — a radio that waits for
+ *   the server to look checked reads as a picker that ignored the click.
  * - **Payment choice.** `paymentMethods` come from store info (their ONLY
  *   source — `cart.payment_gateways` is always undefined). One enabled gateway
  *   is selected from the first render that has store info. The selection is
@@ -193,18 +197,33 @@ export function useCheckout(options = {}) {
   const shippingStatus = cart?.shipping_status ?? null;
   const shippingMethods = cart?.available_shipping_methods ?? [];
   const singleShippingMethod = shippingMethods.length === 1;
+  // The optimistic pick: `choose-shipping-method` is a priced round trip, and a
+  // radio that only looks checked once the response lands reads as a picker
+  // that ignored the click. The pick covers exactly the in-flight window — it
+  // clears when its own call settles, so the confirmed view (or, on failure,
+  // the cart's stored choice) takes back over without a flicker.
+  const [pickedShippingMethod, setPickedShippingMethod] = useState("");
   // The backend auto-selects when it offers exactly one rate (`auto_selected`)
   // and echoes it back on the cart, so the lookup normally finds it. The
   // fallback covers the seam where a freshly repriced address offers one rate
   // the cart's stored id hasn't caught up with: a single option is selected,
   // and must read as selected, from the moment it is offered.
   const chosenShippingMethod =
+    shippingMethods.find((m) => m.id === pickedShippingMethod) ??
     shippingMethods.find((m) => m.id === cart?.chosen_shipping_method) ??
     (singleShippingMethod ? shippingMethods[0] : null);
   const chooseShippingMethod = useCallback(
-    (methodId) => runCart(() => client.chooseShippingMethod(methodId)),
+    (methodId) => {
+      setPickedShippingMethod(methodId);
+      return runCart(() => client.chooseShippingMethod(methodId)).finally(() =>
+        // Only the call's own pick is cleared — a newer click stays optimistic
+        // until its own call settles (the queue serializes them in order).
+        setPickedShippingMethod((cur) => (cur === methodId ? "" : cur)),
+      );
+    },
     [client, runCart],
   );
+  const shippingChoicePending = !!pickedShippingMethod;
 
   // ── payment choice (gateways live on store info ONLY) ────────────────────
   // The pick is state; the *method* is derived, so a lone gateway is selected
@@ -224,9 +243,14 @@ export function useCheckout(options = {}) {
   else if (!cart || !cart.items?.length) blockers.push("empty_cart");
   if (missingBilling.length) blockers.push("billing_incomplete");
   if (shipToDifferent && !complete) blockers.push("shipping_address_incomplete");
-  if (syncPending || syncing) blockers.push("shipping_recalculating");
+  if (syncPending || syncing || shippingChoicePending) blockers.push("shipping_recalculating");
   if (shippingStatus === "missing_address") blockers.push("shipping_address_required");
-  if (shippingStatus === "choice_required") blockers.push("shipping_method_required");
+  // A pick in flight already shows as selected — flagging "choose one" over a
+  // visibly chosen radio contradicts the screen; the transient code above
+  // covers the window, and the blocker returns if the pick fails.
+  if (shippingStatus === "choice_required" && !shippingChoicePending) {
+    blockers.push("shipping_method_required");
+  }
   if (shippingStatus === "none_available" || addressError?.code === "shipping_not_available") {
     blockers.push("shipping_not_available");
   }
@@ -322,6 +346,7 @@ export function useCheckout(options = {}) {
     chosenShippingMethod,
     singleShippingMethod,
     chooseShippingMethod,
+    shippingChoicePending,
     // payment choice
     paymentMethods,
     paymentMethod,

package/src/commerce/utils/storefront.js

@@ -111,7 +111,9 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
     /**
      * Submit a review. `email` is required for a guest and ignored for a
      * signed-in caller (the session's email always wins, so nobody can
-     * review as someone else). `rating` is optional, 0–5.
+     * review as someone else). At least one of `review` (the text) or
+     * `rating` (1–5 stars) is required — a stars-only submission is valid,
+     * and so is text-only; only both missing rejects (`review_incomplete`).
      *
      * Resolves to `{ review_id, status, verified }` — **`status` is
      * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`