@wix/agent-skills 1.19.1 → 1.19.2

package/skills/wix-manage/references/sites/upload-static-site.md

@@ -1,53 +1,283 @@
 ---
 name: "Upload a Website or HTML Files"
-description: Get a user's ready-made website live on Wix when they already have the site files — an index.html, a zip, or a static build exported from an AI builder or any other tool — by sending them to the Wix Headless drop page, where they upload the files and instantly get a live hosted site they can claim into their account. Use whenever the user wants to upload, publish, or host their own HTML/CSS/JS files as a NEW site. Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
+description: Publish a user's ready-made website — an index.html, a static build, or a zip exported from an AI builder or any other tool — as a new live Wix site. Covers both ways to get there — handing the user the Wix Headless drop page, and calling the Wix Headless instant-site REST API yourself when you can reach the files and make outbound HTTPS requests. When you also hold the user's identity, covers putting the published site straight into their Wix account and reading back its final live URL. Use whenever the user wants to upload, publish, deploy, or host their own HTML/CSS/JS as a NEW site, including files generated for them earlier in the conversation, or to update a site already published this way (iterate on the same site instead of creating another). Not for migrating a live store/site from another platform by URL or from CSV exports (use Site Import), not for adding HTML or custom code into an existing Wix site, and not for uploading images or documents to a site's media files.
 ---
 
 # Upload a Website or HTML Files
 
-The user already has a finished website as files — hand-written HTML, a zip
-export, or the output of an AI site builder — and wants it live on Wix as a
-new site. There is no API call to make. Send them to the upload page and
-explain the flow:
+The user has a finished website as files — hand-written HTML, a static build, a
+zip, or the output of an AI site builder — and wants it live on Wix as a new
+site. There are two ways to get there.
 
+## The two paths
+
+**[Path A — hand the user the drop page](#path-a--hand-the-user-the-drop-page).**
+One URL; the user uploads in the browser and gets a live site. This works for
+**any** agent and any user — it's the default. Reach for it whenever you can't
+clearly do Path B.
+
+**[Path B — publish the files yourself](#path-b--publish-the-files-yourself).**
+Three calls put the site live without the user touching a browser. Available only
+when **both** hold: you can read the file bytes (you generated them here, or
+they're reachable from where you run), **and** you can do a `multipart/form-data`
+file upload from a shell (`curl` or equivalent). Reaching APIs *only* through the
+Wix API-call/execute-API tools does **not** count — they can't upload a local
+file.
+
+Prefer Path B when you can genuinely do it — the user gets a live site without
+uploading anything themselves. Otherwise, and by default, take Path A. Decide
+honestly: if you can't read the bytes or can't upload from a shell, hand over the
+drop page rather than attempting Path B and reporting an upload you couldn't
+perform.
+
+## Path A — hand the user the drop page
+
+Send the user here:
+
+```
+https://www.wix.com/headless/drop?utm_campaign=mcp&agent=<your-agent-id>
+```
+
+**Keep `utm_campaign=mcp`** (the drop-flow referral tag — don't change it) **and set
+`agent` to your own identifier** — the coding agent or tool you are (e.g.
+`claude-code`, `cursor`, `codex-cli`, `windsurf`, `github-copilot`, or your product's
+name). Hand the URL with `agent` filled in and both params intact. There the user drags
+in their files (no login), Wix hosts them immediately on a live URL, and a banner
+offers to sign in and keep the site. Tell them the requirements from
+[What the upload accepts](#what-the-upload-accepts-and-how-it-fails) so it doesn't
+fail on the first try.
+
+## Path B — publish the files yourself
+
+> **Run every call from your shell with `curl` — not the Wix API-call/execute-API
+> tools.** The upload (step 2) and the download in
+> [Add a backend](#keep-building-add-a-backend-when-you-need-one) move a **file**
+> to or from disk; those tools proxy JSON and can't (hand-building a multipart
+> body inline silently drops every image and font). Create and release are plain
+> JSON and would work through anything, but the upload needs a real file client
+> anyway, so keep it all in the shell. **None of steps 1–3 (or the download) need
+> auth — they're anonymous.** Only [claim](#4-put-the-site-in-the-users-account)
+> needs the user's identity.
+
+```
+Base URL: https://www.wixapis.com/headless-business-setup
+```
+
+Generate `anonymousId` yourself — any UUID, **once per site, not once per
+request** — and reuse it (with the returned `metaSiteId`) for every call for that
+site, including later changes ([Iterate](#iterate-while-anonymous-dont-create-a-new-site)).
+**Finish within one hour of step 1**: after that the record expires and every
+later step, claim included, returns `404`.
+
+### 1. Create the site
+
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID"
+```
+
+```json
+{ "metaSiteId": "f0ad8672-09e9-4111-b6fe-070c70bd2df5",
+  "projectId":  "54528d34-b23c-4fbe-b07d-2c522350abd7" }
+```
+
+Keep both: `metaSiteId` addresses the site in every later call; `projectId`
+builds the save link in step 3b.
+
+### 2. Upload the files
+
+One `multipart/form-data` request carrying every file. Each file is a part named
+`files` whose **filename is its path relative to the site root** — that is how
+subdirectories survive; with `curl`, set it explicitly with `;filename=` whenever
+it isn't just the basename. A single `.zip` part works too — send it alone and
+it's unpacked server-side, a single wrapping folder stripped.
+
+```bash
+AGENT=claude-code   # ← replace with your own identifier (see note below)
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/upload?campaign=mcp&agent=$AGENT" \
+  -F "files=@index.html;filename=index.html" \
+  -F "files=@assets/styles.css;filename=assets/styles.css" \
+  -F "files=@assets/logo.png;filename=assets/logo.png"
+```
+
+```json
+{ "uploadId": "03244542-d820-42f6-acfa-166c6658b1a6" }
+```
+
+Keep `campaign=mcp` (the drop-flow referral tag — don't change it) and set
+`agent=$AGENT` to **your own identifier**: the coding agent or tool performing this
+drop, so the upload is attributed to the real client. Use a short, stable,
+lowercase-hyphenated slug — e.g. `claude-code`, `cursor`, `codex-cli`, `windsurf`,
+`github-copilot`, or your product's name; if you genuinely can't name yourself, use
+`unknown-agent`. Send the **same** `agent` on every upload for this site, matching
+the `agent` you'd use in Path A. Nothing is live yet; this only stages and validates.
+
+### 3. Release — the site goes live
+
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/release" \
+  -H 'Content-Type: application/json' \
+  -d "{\"uploadId\":\"$UPLOAD_ID\"}"
 ```
-https://www.wix.com/headless/drop?utm_campaign=mcp
+
+```json
+{ "siteUrl": "https://instant-hguwrvtcrniw-headlessstack-140d.wix-site-host.com" }
 ```
 
-**Always give the URL exactly as written above, including the
-`utm_campaign=mcp` query parameter.** It attributes the visit to an
-assistant/MCP referral; dropping or rewriting it breaks that attribution.
+The site is live at `siteUrl` immediately.
+
+#### Iterate while anonymous (don't create a new site)
+
+Simple static changes — new copy, another page, a different look — happen here,
+**while the site is still anonymous**, and this is the only window for them:
+re-run steps 2–3 with the **same `anonymousId` and `metaSiteId`**; the upload
+replaces the site's contents and `siteUrl` stays the same. Send the full file set
+each time (release replaces, it doesn't merge). Don't go back to step 1 — a fresh
+site per change leaves the user a trail of abandoned sites on changing URLs; only
+create another for a genuinely separate site.
+
+So **iterate first, claim last**: refine on the same ids until the site is right,
+*then* finish. Once claimed, these anonymous endpoints stop working and the only
+way to keep changing the site in code is a headless project
+([Keep building](#keep-building-add-a-backend-when-you-need-one)).
+
+**When the site is final, finish based on identity:**
+
+- **You have the user's access token** — claim it into their account (step 4).
+  Don't stop at a temporary site: an unclaimed site expires, so saving it is part
+  of publishing, not an extra favour to ask about.
+- **You have no user identity** — stop here; this is a finished, legitimate result
+  (exactly what the drop page produces for every visitor). Give the user `siteUrl`
+  plus the save link, which is how the site survives:
+
+  ```
+  https://www.wix.com/live-headless-site/{projectId}?anonymousId={anonymousId}
+  ```
 
-## What happens on that page
+  That page shows the site with a countdown and signs the user in to keep it.
+  Treat the link as a secret — whoever opens it while signed in to Wix claims the
+  site into *their* account — so give it only to the user who asked.
 
-1. The user drags in their files (or a zip) — no login needed.
-2. Wix hosts them immediately on a live URL they can open and share.
+### 4. Put the site in the user's account
 
-## Tell the user before they upload
+```bash
+curl -sS -X POST \
+  "https://www.wixapis.com/headless-business-setup/v1/headless-business/anonymous/$ANONYMOUS_ID/$META_SITE_ID/claim" \
+  -H "Authorization: Bearer $ACCESS_TOKEN"
+```
+
+Returns `{}` on success; needs a user or account-level identity (else
+`UNAUTHENTICATED`). It consumes the anonymous record, so it's the last call that
+works against these endpoints — do it after the release, never before.
+
+**The site's URL changes here.** The step-3 host stops resolving — the free host
+is scoped to the owning account and re-minted under the user's. Read the new one
+in step 5; never repeat the step-3 URL after a claim.
+
+### 5. Read the site's final URL
+
+[Query Sites](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites)
+filtered to the **`HEADLESS` namespace** — headless sites are omitted from the
+default query, so the filter is required, and an `id` filter is rejected, so match
+the id yourself.
+
+```bash
+curl -sS -X POST "https://www.wixapis.com/site-list/v2/sites/query" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"query":{"filter":{"namespace":"HEADLESS"},"cursorPaging":{"limit":100}}}'
+```
+
+Find the entry whose `id` equals your `metaSiteId`, read `viewUrl` (page with
+`metadata.cursors.next` if needed):
+
+```json
+{ "id": "f0ad8672-09e9-4111-b6fe-070c70bd2df5",
+  "displayName": "Snake", "published": true, "namespace": "HEADLESS",
+  "viewUrl": "https://instant-hguwrvtcrniw-ayalg5-1406.wix-site-host.com/" }
+```
+
+Give the user two links: `viewUrl` for the live site, and its dashboard at
+`https://manage.wix.com/dashboard/{metaSiteId}` to manage it.
+
+### What the upload accepts, and how it fails
+
+The requirements below apply to both paths — an upload that breaks them is why a
+release never happens:
+
+- **A top-level HTML file is required.** It needn't be named `index.html` (a lone
+  top-level HTML of any name becomes the homepage), but once there's more than
+  one, an `index.html` must be among them.
+- **3 MB per file, 20 MB per site.**
+- **Static files only** — HTML, CSS, JS, images, fonts. Framework source that
+  needs a build step (a `package.json`, React/Vue sources) must be built first;
+  upload the build output.
+
+On Path B, failures come back as HTTP 400 with a code in
+`details.applicationError.code`: `MISSING_INDEX_HTML` (add a top-level HTML),
+`FILE_TOO_LARGE` (a file over 3 MB), `TOTAL_TOO_LARGE` (bundle over 20 MB). A
+`404` after step 1 means the one-hour window passed or the site was already
+claimed — start again from step 1.
+
+**If Path B fails for any reason you can't quickly fix — a rejected upload, an
+error, a call you can't make — fall back to [Path A](#path-a--hand-the-user-the-drop-page):
+give the user the drop-page link so they can finish in the browser.** Never leave
+them with a failed publish and no way forward; the drop page reaches the same
+result without the step that broke.
+
+## Keep building: add a backend when you need one
+
+The drop flow publishes **static** files. When the site needs a real backend —
+stores, payments, bookings, a CMS, members, forms — it becomes a **Wix Headless
+project**. This is a solution the user chooses when the need appears, not a
+required step: a static site is a finished result on its own.
+
+Offer it once the site is claimed/owned and you're in a coding environment with a
+shell. It keeps the **same site, appId and URL** (the downloaded project already
+carries a `wix.config.json` binding it), and is released with the Wix CLI from
+then on:
+
+```bash
+curl -sSL -o project.zip \
+  "https://www.wix.com/_api/wixstro-deployments/v1/instant-sites/$META_SITE_ID/download.zip"
+unzip project.zip -d project      # index.html + assets + wix.config.json
+```
 
-Share the requirements that match their situation — these are the common
-reasons an upload fails:
+Then follow `https://wix.com/headless/skill.md`: it turns the static files into a
+headless project (`@wix/sdk` + the business solutions the site needs), bound to
+the same site.
 
-- The upload must contain an **HTML file at the top level of the site's
-  files**. It does not need to be named `index.html` — a single HTML file of
-  any name is served as the homepage — and a zip or folder that wraps
-  everything in one top-level folder (e.g. `my-site/index.html`) is unwrapped
-  automatically.
-- Size limits: **3 MB per file, 20 MB total.**
-- **Static files only** — HTML, CSS, JavaScript, and assets. If the user has
-  framework source code that needs a build step (a `package.json`, React/Vue
-  source, etc.), they must run their build first and upload the build output
-  folder's contents, not the source.
+This is the only way to keep changing a **claimed** site in code, and it's why it
+needs `wix login`: re-releasing to a claimed site is authenticated *and*
+file-based, and an authenticated file operation needs the token in your **shell**
+(via `wix login`), not injected into a tool — the API-call/execute-API tools carry
+the auth but can't do file operations. There's no lighter "re-upload static to my
+claimed site" shortcut.
 
 ## Route the request correctly
 
-| The user has… | Do this |
-|---|---|
-| Site files on their machine (HTML/zip/AI-builder export), wants a new site | This recipe — send them to the drop URL above |
-| A live site or store on another platform (a URL), or CSV/TSV exports, and wants content/products migrated | [Site Import](site-import.md) |
-| An existing Wix site they want to add HTML, an embed, or custom code into | Not this recipe — that's embedding custom code in the site editor |
-| Images, videos, or documents to add to a site | [Upload Media to Wix](../media/upload-media-to-wix.md) — media goes to the site's media files, not a new site |
+- **You can't read the files, can't make HTTP calls, or have no shell
+  (API-call/execute-API tools only, which can't upload a file)** — Path A, the
+  drop page. It's also the default whenever Path B isn't clearly available, and
+  the fallback whenever Path B fails partway — hand over the link, don't leave the
+  user stuck.
+- **Files you generated here or can read, and you can upload from a shell** —
+  Path B. If you hold the user's identity, claim it into their account and return
+  the live URL + dashboard.
+- **A change to a site you published this way here** —
+  [iterate in place](#iterate-while-anonymous-dont-create-a-new-site) on the same ids.
+- **A published anonymous site the user wants to keep** — steps 4–5 with their
+  identity, else the step-3 save link.
+- **A claimed site that now needs a backend** (stores, bookings, CMS, members,
+  forms) — [add a backend](#keep-building-add-a-backend-when-you-need-one).
+- **Migrating a live site/store from another platform by URL, or CSV/TSV
+  exports** — [Site Import](site-import.md).
+- **Adding HTML, an embed, or code to an existing Wix site** — not this recipe
+  (that's custom code in the editor).
+- **Images, videos, or documents for a site** —
+  [Upload Media to Wix](../media/upload-media-to-wix.md).
 
-Do not try to perform the upload for the user through an API, and do not
-create a site for them with other site-creation tools instead — the drop page
-is the flow.
+Don't create the site with other tools (meta-site templates, headless-business
+provisioning) — those make an empty site, not a published copy of the user's files.

package/skills/wix-vibe-headless/references/storefront/INSTRUCTIONS.md

@@ -103,18 +103,22 @@ export default function ProductCard({ product }) {
   const {
     isSoldOut, isPreorder, isPartiallyOutOfStock, // booleans
     leftBadges,       // [{ type: 'pre-order'|'sold-out'|'limited-stock', label }]
-    promoBadge,       // { type: 'discount'|'ribbon', label } | null
-    priceDisplay,     // formatted price or min–max range; may be undefined if absent
-    compareAtDisplay, // formatted compare-at price | null
+    ribbons,          // every merchant ribbon label, primary first — render ALL of them, one shared style
+    promoBadge,       // { type: 'ribbon', label } | null — the primary ribbon, for a single-badge slot
+    priceDisplay,     // the price the buyer pays (discounted when an automatic discount applies), or a min–max range
+    compareAtDisplay, // struck "was" price | null — never beside a range (the PDP shows the real comparison)
     colors,           // hex colour strings
     optionLabel,      // e.g. "3 sizes · 2 materials", or ""
     isQuickAddable,   // no product options and not sold out; does NOT check modifiers
+    directAddVariantId, // the variant a quick-add sends; null when not quick-addable
     image, hoverImage,// normalised primary / second gallery URL | null
   } = useProductCard(product);
   // Render your card.
 }
 ```
-For quick-add, call `addToCart(product.id)` only when `isQuickAddable` and no mandatory
+A ribbon is a label, never proof of a price: don't render a "Sale" badge from `compareAtDisplay`,
+and don't compute a percent-off — the hook deliberately doesn't. For quick-add, call
+`addToCart(product.id, directAddVariantId)` only when `isQuickAddable` and no mandatory
 modifier needs input (`product.modifiers` entries have a `mandatory` boolean). Otherwise link to `/product/${product.slug}` for selection, including
 pre-orders. Listing results have no full variants; the PDP hook loads and resolves them.
 Use cart-context `loading` to disable repeated adds. Failures open the shipped drawer with
@@ -198,15 +202,19 @@ export default function ProductDetail() {
   // d contains:
   // product: Wix product | null; .name, .slug, .plainDescription (HTML)
   // notFound: boolean; error: string | null (load error); retry: () => void
-  // price, compareAtPrice: formatted strings ("" if absent), follow the selected variant
+  // price: formatted — the product's min–max range until every option is picked, then the selected
+  //   variant's price (an automatic discount beats the regular price); compareAtPrice: the struck
+  //   "was" price, "" when none. discountNames: automatic-discount names, product level.
   // options, modifiers: arrays consumed by useVariantOptions above
-  // selectedOptions: { [optionId]: choiceId }; selectOption(optionId, choiceId)
+  // selectedOptions: { [optionId]: choiceId } — starts EMPTY (no pre-picked choice); selectOption(optionId, choiceId)
   // modifierValues: { [key]: value }; setModifier(key, value)
   // variant: resolved variant | null; null if required choices are missing or no match exists
   // focusMediaUrl: selected choice image, then variant image, or null
-  // quantity, setQuantity(n): number (may be "" mid-edit)
-  // inStock, canAdd, adding: booleans
-  // submit: async () => adds product + resolved variant + quantity + modifiers
+  // quantity, setQuantity(n): number (may be "" mid-edit); resets to 1 when an option changes
+  // inStock, isPreorder, canAdd, adding: booleans — a pre-order variant IS addable
+  // blockedReason: string | null — why the buy button is disabled ("Choose Size", "Out of stock");
+  //   render it next to the action as neutral guidance, not an error, until the buyer tries to buy
+  // submit: async () => adds product + resolved variant + quantity + modifiers (+ preorder)
   // resolves undefined on success, null on failure (not a cart object or a boolean)
   // Replace these placeholders with your error, not-found, and loading UI.
   if (d.error) return null; // show d.error and offer d.retry()
@@ -220,24 +228,28 @@ export default function ProductDetail() {
 ```
 - Render `product.plainDescription` as HTML; strike `compareAtPrice` only when present and different from `price`.
 - Make the gallery follow `focusMediaUrl` when the selected option changes.
-- Render the option/modifier controls below; show a selection hint when `options.length && !variant`.
-- Keep quantity at least 1. Disable adding when `!canAdd || adding`; call `submit()` only with a loaded product and `canAdd`. `submit()` coerces quantity to at least 1 but does not itself enforce `canAdd`.
-- `canAdd` checks variant resolution, variant stock, and mandatory modifier values. `inStock` defaults to true without a resolved variant; use `canAdd` for the full gate.
+- Render the option/modifier controls below; mark choices whose `inStock` is false; show `d.blockedReason` beside the button while it's disabled.
+- Label the action by state: `isPreorder` → "Pre-order"; otherwise "Add to cart". Keep quantity at least 1. Disable adding when `!canAdd || adding`; call `submit()` only with a loaded product and `canAdd`. `submit()` coerces quantity to at least 1 but does not itself enforce `canAdd`.
+- `canAdd` checks variant resolution, availability (in stock or pre-orderable), and mandatory modifier values. `inStock` defaults to true without a resolved variant; use `canAdd` for the full gate.
+- Render the PDP gallery from `images` — every image reachable (thumbnails, arrows, or a swipeable rail), not just the first; a single-image product gets no empty strip.
 - `submit()` resets `adding` after completion and preserves the cart result: `undefined` on success, `null` on failure. Add failures live in `useCart().error`, not the PDP load `error`; the shipped drawer opens to display them.
 
-For an optional **Buy Now** button, check the add result before checkout:
+For an optional **add and check out** shortcut, check the add result before checkout:
 ```jsx
 // Inside ProductDetail, with the other hooks above any conditional returns:
 const { checkout, loading: cartLoading } = useCart(); // named import from @/context/CartContext
-async function buyNow() {
+async function addAndCheckout() {
   if (!d.product || !d.canAdd || d.adding || cartLoading) return;
   const result = await d.submit();
   if (result === null) return; // add failed; preserve its error and do not check out the old cart
   await checkout();
 }
-// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={buyNow}>Buy now</button>
+// <button disabled={!d.canAdd || d.adding || cartLoading} onClick={addAndCheckout}>Add and check out</button>
 ```
-For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
+This adds to the shopper's **current cart** and checks that cart out — so label it that way. A true
+**Buy Now** (skip the cart, buy just this item) needs a standalone cart handed to the redirect session;
+it is not shipped, and routing "Buy now" through the current cart is wrong (it would carry whatever the
+cart already holds). For direct `addToCart(...)` calls, use the same `result === null` check before checkout.
 A resolved promise alone does not mean success; a truthiness check also rejects successful `undefined`.
 
 ### Variant and modifier controls
@@ -277,14 +289,17 @@ within `CartProvider` (the PDP hook calls it for you).
 
 ```js
 const { addToCart, isOpen, setIsOpen, loading, error, clearError } = useCart();
-// addToCart(productId, variantId?, qty = 1, { modifierChoices?, customTextFields? }?)
+// addToCart(productId, variantId?, qty = 1, { modifierChoices?, customTextFields?, subscriptionOptionId?, preorder? }?)
 // isOpen: boolean; setIsOpen(true): open the drawer; setIsOpen(false): close it
 // loading: mutation-in-progress boolean; disable repeated adds while true
 // error: string | null; clearError(): clears it
 ```
-`addToCart` uses `product.id` and the resolved `variant.id` when needed. Extras are string maps:
+`addToCart` uses `product.id` and the resolved `variant.id` when needed. Extras: string maps
 `modifierChoices: { [modifier.key]: choiceKey }` and
-`customTextFields: { [modifier.freeTextSettings.key]: userInput }`; include mandatory values.
+`customTextFields: { [modifier.freeTextSettings.key]: userInput }` (include mandatory values);
+`preorder: true` for a pre-order variant (the PDP hook sets it); `subscriptionOptionId` for a chosen
+recurring plan (omit for one-time). The shipped PDP hook doesn't render subscriptions — add that
+only when the catalog has `subscriptionPricesInfo`, requiring an explicit plan choice.
 
 The context's add/remove/update/checkout methods return promises resolving to `undefined` on
 success or `null` on failure, storing the failure in `error`. They clear the previous error and
@@ -298,8 +313,10 @@ Only use these additional contracts if you choose to render your own cart surfac
 from the same `useCart()` context; mutation results and error handling are described above.
 
 ```js
-const { cart, itemCount, removeItem, updateQuantity, checkout, refreshCart } = useCart();
+const { cart, summary, itemCount, removeItem, updateQuantity, checkout, refreshCart } = useCart();
 // cart: server cart | null; itemCount: sum of confirmed line quantities
+// summary: the estimate's { priceSummary: { subtotal, discount, total } } | null — refreshed with the cart;
+//   subtotal is after discounts, discount is the CART-level discount only; both ConvertedMoney
 // removeItem(lineItemId); updateQuantity(lineItemId, qty)
 // checkout(); refreshCart()
 ```
@@ -307,7 +324,8 @@ For custom cart presentation, `cart?.lineItems ?? []` is the list. Each line has
 `name.original`, and optional `attributes.image.url`. Option/modifier labels are in
 `attributes.descriptionLines`: `[{ name: { original }, plainText?: { original },
 colorInfo?: { original, code } }]`; use `plainText.original` or `colorInfo.original` for the value.
-Update/remove use the line's `id`, not a catalog product id.
+Update/remove use the line's `id`, not a catalog product id. Show each line's `attributes.descriptionLines`
+(the chosen options and text) — a shopper verifies the configuration in the cart, not the checkout.
 
 Normalize custom cart images with `storeImage(line.attributes?.image?.url)` (see **Images**).
 
@@ -320,10 +338,10 @@ Cart money is `{ amount, convertedAmount }`, with no formatted string. `amount`
 currency; `convertedAmount` is in display currency. Format
 `money.convertedAmount ?? money.amount` with `Intl.NumberFormat` and
 `cart.customerInfo?.currencyCode ?? cart.businessInfo?.currencyCode` (the shipped drawer falls
-back to `USD`). Use server `cart.subtotal` and line `pricing.totalPrice`; never sum lines yourself.
-The cart has no `subtotalAfterDiscounts`, `discount`, or `appliedDiscounts`; discounted summary
-totals require a currentCartV2 estimate/calculate `summary.priceSummary`, which these helpers do
-not fetch. Tax and shipping resolve at checkout.
+back to `USD`). Use `summary.priceSummary.subtotal` (after discounts) with `cart.subtotal` as the
+fallback while `summary` is null, a Discount row only when `priceSummary.discount` is above zero, and
+line `pricing.totalPrice`; never sum lines yourself. Shipping and tax resolve at checkout — say
+"calculated at checkout", never a hardcoded charge, threshold, or a made-up zero.
 
 Line `quantityInfo.confirmedQuantity` is the current quantity; `availableQuantity` caps increases
 when finite. `status` can be `IN_STOCK`, `PARTIALLY_IN_STOCK`, `OUT_OF_STOCK`, or
@@ -416,6 +434,28 @@ function Layout() {
 }
 ```
 
+## What a complete storefront shows
+
+The wiring above is necessary, not sufficient. These are defaults for when the brief doesn't say
+otherwise — whatever the user asked for in their prompt wins over any line here. Look at the
+catalog before designing — categories, assortment size, media, options, sales — and design for this
+store, not for a stereotype of its category. Then:
+
+- **Home:** what the store sells and one shopping action in the first screen; real products from
+  the catalog under truthful headings; not a repeat of the shop page.
+- **Shop:** a real product card — image, name, price, link — in the first screen; sort and the
+  filters the catalog supports; loading, empty, no-results, and error states that look different.
+- **Product page:** image, name, price, the first choice, and the buy button with `blockedReason`
+  in the first screen; every ribbon; every image reachable in the gallery.
+- **Cart:** the shipped drawer — it opens after every add, and checkout is a button in it.
+- **Overlays you build** (quick-add, mobile nav, filters): mount at the document root, lock
+  background scroll, close on Escape, return focus on close — as the shipped `CartDrawer` does.
+- **Copy:** nothing the merchant didn't supply — no invented reviews, scarcity, or delivery
+  promises; no Wix IDs or technical words in visible text.
+
+Pre-order ships (`isPreorder`). Subscriptions, product groups, promotions, and notify-me are built
+only when the catalog has them — never fabricated; consult the documentation skill for their endpoints.
+
 ## Missing capabilities
 For anything these interfaces do not cover, consult the official Wix API documentation using
 the documentation skill available in your environment.
@@ -425,4 +465,6 @@ shipped file; catalog and cart helpers link their API references inline.
 ## Hard rules
 - Header/footer live in a `Layout` around `<Outlet/>` (see **Routes and provider**) — keep shared chrome out of individual pages.
 - Checkout goes through the shipped cart (redirect-session) — never a hand-built `/checkout` URL.
-- Render live Wix data or your empty state — never mock products.
+- Render live Wix data or your empty state — never mock products, reviews, ratings, or counts.
+- Prices and ribbons come from the hooks as-is: no computed percent-off, no "Sale" badge inferred from a compare-at price, no struck price beside a range.
+- Cart totals come from `summary`/`cart` — never summed or hardcoded in the client; shipping and tax say "calculated at checkout".

package/skills/wix-vibe-headless/references/storefront/app/components/CartDrawer.jsx

@@ -5,15 +5,14 @@
 // • prices come from the SERVER cart. In Cart V2 each line total is `pricing.totalPrice`, a
 //   ConvertedMoney { amount, convertedAmount } with NO formatted string — format it yourself with the
 //   cart's currency (see formatCartMoney). Never compute a total in the client: tax, shipping and
-//   promotions are resolved server-side, so the cart's `subtotal` is the only figure safe to show
-//   pre-checkout. The V2 cart has no `subtotalAfterDiscounts`/`discount`/`appliedDiscounts` — the
-//   discounted total comes from a currentCartV2 estimate/calculate `summary.priceSummary`, not the
-//   cart; absent that call, show the raw `subtotal`.
+//   promotions are resolved server-side. The V2 cart has no `subtotalAfterDiscounts`/`discount` —
+//   the after-discount subtotal and the cart-level discount come from the estimate the context keeps
+//   in `summary.priceSummary`; the raw cart `subtotal` is the fallback while it's unknown.
 // • `quantityInfo.availableQuantity` caps the stepper, so exceeding stock is refused here rather than
 //   at checkout.
 // • `status` is flagged per line here because checkout() refuses the whole cart when any item isn't
 //   IN_STOCK — showing it on the row is what makes that refusal understandable.
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useCart } from "@/context/CartContext";
 import { storeImage } from "@/lib/storeImage";
 
@@ -26,28 +25,41 @@ function formatCartMoney(money, cart) {
 }
 
 export default function CartDrawer() {
-  const { cart, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
+  const { cart, summary, isOpen, setIsOpen, removeItem, updateQuantity, checkout, loading, error, clearError } = useCart();
   const lineItems = cart?.lineItems ?? [];
-  // The V2 cart carries only a raw `subtotal` (ConvertedMoney); discounted totals live on an
-  // estimate/calculate `summary.priceSummary`, which this cart helper doesn't fetch — so show `subtotal`.
-  const subtotal = formatCartMoney(cart?.subtotal, cart);
+  // Totals come from the estimate the context keeps next to the cart (after-discount subtotal, the
+  // cart-level discount). While it's unknown, or if it failed, fall back to the cart's raw subtotal.
+  // Delivery and tax are NOT in here — they resolve at checkout, and the footer says so.
+  const subtotal = formatCartMoney(summary?.priceSummary?.subtotal ?? cart?.subtotal, cart);
+  const discountAmount = Number(summary?.priceSummary?.discount?.convertedAmount ?? summary?.priceSummary?.discount?.amount ?? 0);
+  const discount = discountAmount > 0 ? formatCartMoney(summary.priceSummary.discount, cart) : "";
   const unavailable = lineItems.filter((li) => li.status && li.status !== "IN_STOCK");
 
-  // Escape closes the drawer while it's open — expected of anything modal, and the only way out for
-  // keyboard users (the backdrop click is pointer-only).
+  // The overlay contract, verified in the browser rather than assumed from CSS: Escape closes (the
+  // backdrop click is pointer-only), the page behind stops scrolling, focus moves into the panel on
+  // open and returns to whatever opened it on close.
+  const panelRef = useRef(null);
   useEffect(() => {
     if (!isOpen) return;
+    const opener = document.activeElement;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    panelRef.current?.focus();
     const onKey = (e) => e.key === "Escape" && setIsOpen(false);
     document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = previousOverflow;
+      if (opener instanceof HTMLElement) opener.focus();
+    };
   }, [isOpen, setIsOpen]);
 
   if (!isOpen) return null;
 
   return (
     <div onClick={() => setIsOpen(false)} className="fixed inset-0 z-50 bg-black/40 flex justify-end">
-      <aside onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
-        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body">
+      <aside ref={panelRef} tabIndex={-1} onClick={(e) => e.stopPropagation()} role="dialog" aria-modal="true" aria-label="Your cart"
+        className="w-[min(420px,100%)] h-full flex flex-col bg-background text-foreground border-l border-border font-body outline-none">
         <header className="flex justify-between items-center p-4 border-b border-border">
           <strong className="font-display">Your cart{lineItems.length ? ` (${lineItems.length})` : ""}</strong>
           <button onClick={() => setIsOpen(false)} aria-label="Close cart"
@@ -123,6 +135,12 @@ export default function CartDrawer() {
 
         {lineItems.length > 0 && (
           <footer className="p-4 border-t border-border flex flex-col gap-3">
+            {discount && (
+              <div className="flex justify-between items-baseline text-sm">
+                <span className="text-muted-foreground">Discount</span>
+                <span>−{discount}</span>
+              </div>
+            )}
             {subtotal && (
               <div className="flex justify-between items-baseline">
                 <span className="text-muted-foreground">Subtotal</span>