@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-vibe-headless/references/storefront/app/lib/storeImage.js

@@ -10,6 +10,43 @@ export function storeImage(value) {
   return url;
 }
 
+// A Wix media id (e.g. "abc123~mv2.jpg") is NOT a URL — build the static CDN url for it.
+export function wixMediaUrl(mediaId) {
+  if (!mediaId || typeof mediaId !== "string") return null;
+  if (mediaId.startsWith("http") || mediaId.startsWith("//")) return storeImage(mediaId);
+  return `https://static.wixstatic.com/media/${mediaId}`;
+}
+
+// The media id inside a Wix image url (…/media/<id>/v1/… or a bare …/media/<id>). Compare two urls of
+// the SAME image that differ only in sizing/format params by their id, not full-string equality.
+export function wixMediaId(url) {
+  const m = typeof url === "string" && url.match(/\/media\/([^/?]+)/);
+  return m ? m[1] : url;
+}
+
+// The image assigned to a product OPTION CHOICE (e.g. a colour swatch). The storefront fetches with the
+// PRODUCT_CHOICES_MEDIA_REFERENCES field, so Wix returns the choice image at choice.media.items[].mediaId
+// and returns choice.linkedMedia EMPTY. Read media.items — do NOT switch this to choice.linkedMedia even
+// if a direct admin/API probe shows linkedMedia populated: a probe made WITHOUT that field mask returns
+// linkedMedia, but the storefront requests the mask, which blanks linkedMedia and returns media.items.
+export function choiceImage(choice) {
+  const mediaId = choice?.media?.items?.[0]?.mediaId;
+  return mediaId ? wixMediaUrl(mediaId) : null;
+}
+
+// The image for a resolved VARIANT (a full choice combination). Wix computes variant.media from the
+// picked choices' media, so this is the exact image for the current selection — prefer it over a
+// single choice's image once all options are chosen.
+// ⚠️ Read `media.image.url` (the URL the API already returns), or build from `media.id` — the
+// `~mv2` file id. NOT `media.uploadId`: that's a dashed GUID (the id the file was uploaded with),
+// and https://static.wixstatic.com/media/<uploadId> is a 403. Variants without media (a fresh
+// template's demo products) return null, and the caller falls back to the choice's own image.
+export function variantImage(variant) {
+  const m = variant?.media;
+  if (!m) return null;
+  return storeImage(m.image?.url) || wixMediaUrl(m.id) || storeImage(m.thumbnail?.url);
+}
+
 // The main catalog image for a product (grid tiles, cart fallbacks).
 export function productImage(product) {
   return storeImage(product?.media?.main?.image?.url);

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-cart.js

@@ -7,20 +7,22 @@ import { wixApiRequest } from "./wix-client.js";
 const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
 
 /**
- * Wix eCom Cart — key fields for building a cart UI.
+ * Wix eCom Cart V2 — key fields for building a cart UI.
  * Full model: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/get-current-cart.md
  *
- *   id {string}, currency {string},
+ *   id {string} — the cart id IS the checkout id (currency lives under businessInfo.currencyCode / customerInfo.currencyCode, not at the cart root),
  *   lineItems[].id {string} — lineItemId for update/remove (NOT catalogItemId),
- *   lineItems[].quantity {number},
- *   lineItems[].catalogReference.catalogItemId {string},
- *   lineItems[].productName.original {string},
- *   lineItems[].price.formattedAmount {string} — after discounts with currency symbol,
- *   lineItems[].fullPrice.formattedAmount {string} — before discount (strikethrough),
- *   lineItems[].descriptionLines {array} — human-readable option/modifier labels:
+ *   lineItems[].quantityInfo.confirmedQuantity {number},
+ *   lineItems[].source.catalogReference.catalogItemId {string} — NOT top-level in V2,
+ *   lineItems[].name.original {string},
+ *   lineItems[].pricing.unitPrice {ConvertedMoney} — per-unit price after discounts,
+ *   lineItems[].pricing.totalPrice {ConvertedMoney} — line total after discounts,
+ *     ConvertedMoney is { amount, convertedAmount } with NO formatted string — `amount` is in the
+ *     site currency, `convertedAmount` in the display currency; format the number client-side.
+ *   lineItems[].attributes.descriptionLines {array} — human-readable option/modifier labels:
  *     [{ name: { original }, plainText: { original } OR colorInfo: { original, code } }],
- *   lineItems[].image.url {string},
- *   lineItems[].availability.status {string} — "AVAILABLE"|"NOT_AVAILABLE"|"PARTIALLY_AVAILABLE"|"NOT_FOUND"
+ *   lineItems[].attributes.image {object} — { id, url, height, width, altText } (use .url),
+ *   lineItems[].status {string} — "IN_STOCK"|"PARTIALLY_IN_STOCK"|"OUT_OF_STOCK"|"REMOVED_FROM_CATALOG"
  */
 
 /**
@@ -52,20 +54,22 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
 
   const catalogReference = { appId: STORES_APP_ID, catalogItemId };
   if (Object.keys(catalogReferenceOptions).length) catalogReference.options = catalogReferenceOptions;
-  const res = await wixApiRequest("/ecom/v1/carts/current/add-to-cart", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/add-line-items", {
     method: "POST",
-    body: { lineItems: [{ catalogReference, quantity }] },
+    body: { catalogItems: [{ catalogReference, quantity }] },
   });
+  // V2 nests the reference under `source` — a top-level lineItem.catalogReference no longer exists.
   const line = (res?.cart?.lineItems ?? []).find(
-    (l) => l.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.catalogReference?.options?.variantId === variantId),
+    (l) => l.source?.catalogReference?.catalogItemId === catalogItemId && (!variantId || l.source?.catalogReference?.options?.variantId === variantId),
   );
-  // Wix returns 200 even when the line is silently rejected — guard both signals:
-  // 1. availability.status set to something other than AVAILABLE
-  // 2. no matching line at all (quantity 0 / line absent)
-  if (line?.availability?.status && line.availability.status !== "AVAILABLE") {
-    throw new Error(`Item not available for sale (status: ${line.availability.status}). Is it in stock?`);
+  // Cart V2 rejects an unbuyable line with an explicit error rather than silently dropping it, but
+  // guard both signals defensively:
+  // 1. status set to something other than IN_STOCK
+  // 2. no matching line at all (confirmed quantity 0 / line absent)
+  if (line?.status && line.status !== "IN_STOCK") {
+    throw new Error(`Item not available for sale (status: ${line.status}). Is it in stock?`);
   }
-  if (!line || line.quantity === 0) {
+  if (!line || line.quantityInfo?.confirmedQuantity === 0) {
     // A missing line usually means a required selection wasn't sent — a mandatory modifier
     // (pass modifierChoices/customTextFields) or the variantId for a product with options —
     // not necessarily out of stock. Verify every required choice is included in this call.
@@ -81,7 +85,7 @@ export async function addToCart(catalogItemId, variantId, quantity = 1, { modifi
 /** Read the visitor's current cart. Returns null if no cart exists yet. */
 export async function getCurrentCart() {
   try {
-    const res = await wixApiRequest("/ecom/v1/carts/current", { method: "GET" });
+    const res = await wixApiRequest("/ecom/v2/carts/current", { method: "GET" });
     return res?.cart ?? null;
   } catch {
     return null;
@@ -89,7 +93,9 @@ export async function getCurrentCart() {
 }
 
 /**
- * Create a checkout from the current cart and return the hosted checkout URL.
+ * Start the hosted checkout for the current cart and return its URL.
+ * In Cart V2 the cart id IS the checkout id — there is no separate checkout-creation call; the
+ * redirect session is created straight from the current cart's id.
  * Throws on empty cart, unavailable lines, or a missing redirect URL.
  * Usage: window.location.href = await checkout()
  * @returns {Promise<string>}
@@ -98,22 +104,16 @@ export async function checkout() {
   const cart = await getCurrentCart();
   const lines = cart?.lineItems ?? [];
   if (!lines.length) throw new Error("Cannot check out: the cart is empty.");
-  const unavailable = lines.filter((l) => l.availability?.status && l.availability.status !== "AVAILABLE");
+  const unavailable = lines.filter((l) => l.status && l.status !== "IN_STOCK");
   if (unavailable.length) {
-    const names = unavailable.map((l) => l.productName?.original ?? l.catalogReference?.catalogItemId).join(", ");
+    const names = unavailable.map((l) => l.name?.original ?? l.source?.catalogReference?.catalogItemId).join(", ");
     throw new Error(`Cannot check out: ${unavailable.length} item(s) not available — ${names}.`);
   }
-
-  const checkoutRes = await wixApiRequest("/ecom/v1/carts/current/create-checkout", {
-    method: "POST",
-    body: { channelType: "WEB" },
-  });
-  const checkoutId = checkoutRes?.checkoutId;
-  if (!checkoutId) throw new Error("Failed to create checkout from the current cart.");
+  if (!cart.id) throw new Error("Failed to check out: the current cart has no id.");
 
   const redirect = await wixApiRequest("/headless/v1/redirect-session", {
     method: "POST",
-    body: { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl: window.location.href } },
+    body: { ecomCheckout: { checkoutId: cart.id }, callbacks: { postFlowUrl: window.location.href } },
   });
   const url = redirect?.redirectSession?.fullUrl;
   if (!url) throw new Error("Failed to create the checkout redirect session.");
@@ -122,13 +122,13 @@ export async function checkout() {
 
 /**
  * Update the quantity of a cart line. lineItemId is cart.lineItems[].id, not catalogItemId.
- * Wix caps the result at remaining stock — returned quantity may be lower than requested.
+ * Cart V2 rejects an over-stock quantity with an explicit error rather than clamping it.
  * @returns {Promise<object>} Updated cart.
  */
 export async function updateCartItemQuantity(lineItemId, quantity) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/update-line-items-quantity", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/update-line-items", {
     method: "POST",
-    body: { lineItems: [{ id: lineItemId, quantity }] },
+    body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] },
   });
   return res?.cart;
 }
@@ -139,7 +139,7 @@ export async function updateCartItemQuantity(lineItemId, quantity) {
  * @returns {Promise<object>} Updated cart.
  */
 export async function removeFromCart(lineItemId) {
-  const res = await wixApiRequest("/ecom/v1/carts/current/remove-line-items", {
+  const res = await wixApiRequest("/ecom/v2/carts/current/remove-line-items", {
     method: "POST",
     body: { lineItemIds: [lineItemId] },
   });

package/skills/wix-vibe-headless/references/storefront/app/rest/wix-store-catalog.js

@@ -30,12 +30,13 @@ import { wixApiRequest } from "./wix-client.js";
  *   options {array} — product options e.g. Size, Color:
  *     [{ id, name, optionRenderType "TEXT_CHOICES"|"COLOR_CHOICES"|"SWATCH_CHOICES",
  *        choicesSettings.choices [{ choiceId, key, name, inStock, visible, choiceType, colorCode,
- *                                   linkedMedia }] }],
+ *                                   media }] }],
  *     A COLOR/SWATCH option's choices carry choiceType "ONE_COLOR" and colorCode "#395E55" — render
- *     those as real colour swatches, not text pills. linkedMedia [{ image.url }] holds that colour's
- *     photos, so selecting a swatch can move the gallery to the matching shot. visible false is a
- *     retired choice the merchant no longer sells: filter it out. (TEXT_CHOICES choices are
- *     choiceType "CHOICE_TEXT" with no colorCode.)
+ *     those as real colour swatches, not text pills. A choice's photo is at media.items[].mediaId (a
+ *     bare Wix media id — build https://static.wixstatic.com/media/<id>); use choiceImage() from
+ *     lib/storeImage to resolve it. Needs the PRODUCT_CHOICES_MEDIA_REFERENCES field (requested by
+ *     getProductBySlug below). visible false is a retired choice the merchant no longer sells: filter
+ *     it out. (TEXT_CHOICES choices are choiceType "CHOICE_TEXT" with no colorCode.)
  *   modifiers {array} — non-variant customizations (engraving, gift wrap):
  *     [{ id, name, mandatory, modifierRenderType "TEXT_CHOICES"|"FREE_TEXT",
  *        key, choicesSettings.choices, freeTextSettings.key }],
@@ -85,7 +86,18 @@ export async function queryProducts({ limit = 100, cursor } = {}) {
 export async function getProductBySlug(slug) {
   const res = await wixApiRequest(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, {
     method: "GET",
-    query: { fields: ["CURRENCY", "PLAIN_DESCRIPTION", "MEDIA_ITEMS_INFO"] },
+    // PRODUCT_CHOICES_MEDIA_REFERENCES → choice.media.items[].mediaId (the per-colour photos, needed
+    // for the swatch→gallery swap); VARIANT_OPTION_CHOICE_NAMES → variant choice names. Without these
+    // the choice media / variant data come back null.
+    query: {
+      fields: [
+        "CURRENCY",
+        "PLAIN_DESCRIPTION",
+        "MEDIA_ITEMS_INFO",
+        "PRODUCT_CHOICES_MEDIA_REFERENCES",
+        "VARIANT_OPTION_CHOICE_NAMES",
+      ],
+    },
   });
   return res?.product ?? null;
 }

package/skills/wix-vibe-headless/references/storefront/seed/SEED.md

@@ -4,6 +4,10 @@ Seed a Wix Stores catalog by **calling `seed-store.js`** — don't hand-write th
 a build-time module (run via `exec_tool`, not shipped in the app) that abstracts every Wix Stores
 seed operation. Load it and call **`setupStore` — the one-call path** — with plain data.
 
+**Match each product's type to what the buyer receives** (the example shows both). *Access* — a
+membership, or an online course/program the buyer enrolls in — isn't a store product at all; that's
+the `pricing-plans` vertical, not here.
+
 ```js
 // build-time exec_tool
 const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
@@ -22,12 +26,15 @@ const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
 // generate_image runs in the background while you build, so the urls are ready by seed time.
 const result = await seed.setupStore(ctx, {
   products: [
+    // physical — a shipped item: carries `quantity` (the default type)
     { name: "The Glam Rocker", description: "Sequin-studded velvet legend…", price: 49.99, quantity: 12, imageUrl: imageUrls[0] },
     // a product with buyer choices — see "Options, variants and sale prices" below
     { name: "The Understudy", description: "…", price: 245, quantity: 8, imageUrl: imageUrls[1],
       options: [{ name: "Color", type: "color", choices: [{ name: "Ink", colorCode: "#1B1B2F" }, { name: "Bone", colorCode: "#EDE6D6" }] }] },
     // a product on sale — compareAtPrice drives the strikethrough + the tile's percent-off badge
     { name: "Encore Jacket", description: "…", price: 68, compareAtPrice: 129, quantity: 5, imageUrl: imageUrls[2] },
+    // digital — a file the buyer downloads & keeps (ebook, PDF, video): `digitalFileUrl`, NO `quantity`
+    { name: "Backstage Guide", description: "…", price: 12, digitalFileUrl: "https://…/guide.pdf" },
   ],
   categories: { "Legends": ["The Glam Rocker"], "Rising Stars": [] },   // omit if the brief names none
 });
@@ -37,13 +44,15 @@ const result = await seed.setupStore(ctx, {
 **Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
 "sample" data, don't reset. Just add.
 
-## Options, variants and sale prices
+## How many, and exercising the UI
+
+**Default to 3 products** unless the brief asks for a specific catalog — the seed shows the shape,
+not a full inventory; the owner adds the rest later, from the Wix dashboard or by asking you for more.
 
 The shipped storefront renders colour options as real swatches, shows a size/colour summary on each
 tile, and puts a percent-off badge on a discounted product. A catalog of plain single-price products
-leaves all of that invisible, so **seed a catalog that exercises it**: unless the brief says
-otherwise, give at least one product a colour option and put one product on sale. Keep it truthful
-to the business — a ceramics studio has glaze colours, a bakery does not.
+leaves all of that invisible, so **make those 3 exercise it**: unless the brief says otherwise, give
+at least one product a colour option and put one product on sale. Keep it truthful to the business.
 
 ```js
 options: [
@@ -60,13 +69,27 @@ options: [
 - `compareAtPrice` (> `price`) is the "was" price: strikethrough on the PDP and a `−N%` badge on the
   tile, computed from the two amounts. It works with or without options.
 
+## Digital downloads
+
+**Pick the product type from what the buyer receives.** A shipped physical item is the default. A
+**downloadable file the buyer keeps** — ebook, PDF guide, template, preset pack, printable, music
+track, downloadable video — is a **digital** product: pass its file as `digitalFileUrl`. Selling
+*access* rather than a file — a membership, subscription, or an online course/program the buyer
+enrolls in — is **Pricing Plans**, not a Stores product, so it isn't seeded here.
+
+`digitalFileUrl` (plus `digitalFileName` when the url carries no filename) makes a product a digital
+download — uploaded and created with both the file and stock, which is what the cart requires
+(`quantity` is ignored). It's also the only way in: a file-less digital product is created
+successfully, reads back healthy, and is then rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`.
+
 Two things this module does **not** seed, so don't try:
 
 - **Ribbons** ("New", "Best Seller"). The tile renders `product.ribbon` when it's there, but ribbons
   are set in the Wix dashboard — tell the merchant that's where to add them.
-- **Per-choice linked media** (`linkedMedia`), which is what makes picking a colour swap the gallery
-  photo. Seeded swatches select and price correctly; the gallery just doesn't follow the colour until
-  the merchant links photos to choices in the dashboard.
+- **Per-choice media** — the photo that makes picking a choice swap the gallery image. Seeded swatches
+  select and price correctly; the gallery follows a choice once photos are linked to it (Wix dashboard,
+  or the wix-manage "Update Product with Options" recipe → Choice & variant fields). The shipped PDP then
+  follows automatically — `choiceImage()` reads it back at `media.items[].mediaId`.
 
 ## Escape hatch — individual functions
 Reach for the functions below only when the one-call `setupStore` doesn't fit (partial re-seed, custom

package/skills/wix-vibe-headless/references/storefront/seed/seed-store.js

@@ -149,15 +149,16 @@ function buildOptions(options = []) {
 }
 
 // full Cartesian product of variants, each priced/stocked from the product; visible:true baked in
-function expandVariants(options = [], { price, compareAtPrice, quantity }) {
+function expandVariants(options = [], { price, compareAtPrice, quantity }, digitalFileId) {
   const base = {
     price: {
       actualPrice: { amount: String(price) },
       ...(compareAtPrice ? { compareAtPrice: { amount: String(compareAtPrice) } } : {}),
     },
     visible: true,
-    physicalProperties: {},
-    inventoryItem: { quantity: quantity ?? 0, preorderInfo: { enabled: false } },
+    ...(digitalFileId
+      ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem: { inStock: true } }
+      : { physicalProperties: {}, inventoryItem: { quantity: quantity ?? 0, preorderInfo: { enabled: false } } }),
   };
   if (!options.length) return [base];
   let combos = [[]];
@@ -170,6 +171,33 @@ function expandVariants(options = [], { price, compareAtPrice, quantity }) {
   return combos.map((choices) => ({ ...base, choices }));
 }
 
+// A digital variant is SELLABLE only with BOTH a file and stock: without the file the cart rejects
+// it as ITEM_NOT_FOUND_IN_CATALOG, without stock as "exceeds available inventory" — and either way
+// the product reads back visible and in the catalog, so nothing surfaces until a buyer tries to buy.
+// `digitalFileUrl` is the only way into DIGITAL here, which makes the file-less product unbuildable.
+// The bytes are PUT, not imported by url: an uploaded file is READY at once, while an imported one
+// stays PENDING and the cart rejects the product until it settles.
+const FILE_MIME = { pdf: "application/pdf", zip: "application/zip", epub: "application/epub+zip",
+  mp3: "audio/mpeg", wav: "audio/wav", mp4: "video/mp4", png: "image/png", jpg: "image/jpeg" };
+
+async function uploadDigitalFile(ctx, url, fileName) {
+  const mimeType = FILE_MIME[(fileName.split(".").pop() || "").toLowerCase()];
+  if (!mimeType) throw new Error(`digitalFileName needs one of these extensions (${Object.keys(FILE_MIME).join(", ")}): ${fileName}`);
+  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
+  const src = await fetch(url);
+  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}`);
+  const res = await fetch(uploadUrl, {
+    method: "PUT", headers: { "Content-Type": mimeType }, body: Buffer.from(await src.arrayBuffer()),
+  });
+  const json = await res.json().catch(() => ({}));
+  const id = (json.file || json)?.id;
+  if (!res.ok || !id) throw new Error(`digital file upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
+  return id;
+}
+
+const digitalFileName = (p) =>
+  p.digitalFileName || decodeURIComponent(new URL(p.digitalFileUrl).pathname.split("/").pop() || "");
+
 // ---- exported operations ----
 
 async function installStoresApp(ctx) {
@@ -193,7 +221,10 @@ async function listProducts(ctx) {
 /**
  * Bulk-create products.
  * @param products [{ name, description, price, compareAtPrice?, quantity,
- *   options?: [{ name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}] }] }]
+ *   options?: [{ name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}] }],
+ *   digitalFileUrl?, digitalFileName? }]
+ *   digitalFileUrl: makes the product a DIGITAL download — the file is uploaded and the variant
+ *   created with both the file and stock (see uploadDigitalFile). `quantity` is ignored.
  *   description: plain text, or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`) — converted to
  *   Wix rich text here, so the storefront renders paragraphs and bold rather than tag text.
  *   options = ONLY things the buyer selects-and-buys (Size, Color) -> become variants.
@@ -202,17 +233,20 @@ async function listProducts(ctx) {
  * @returns [{ id, slug, revision }]
  */
 async function bulkCreateProducts(ctx, products) {
+  const fileIds = await Promise.all(products.map((p) =>
+    p.digitalFileUrl ? uploadDigitalFile(ctx, p.digitalFileUrl, digitalFileName(p)) : null));
   const body = {
     returnEntity: true,
     products: products.map((p, i) => ({
       name: p.name,
-      productType: "PHYSICAL",
-      physicalProperties: {},
+      // DIGITAL drops physicalProperties and can't be POS-visible (DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS).
+      ...(fileIds[i]
+        ? { productType: "DIGITAL" }
+        : { productType: "PHYSICAL", physicalProperties: {}, visibleInPos: true }),
       visible: true,
-      visibleInPos: true,
       description: mkDesc(p.description, i),
       options: buildOptions(p.options),
-      variantsInfo: { variants: expandVariants(p.options, p) },
+      variantsInfo: { variants: expandVariants(p.options, p, fileIds[i]) },
     })),
   };
   const r = await req(ctx, "/stores/v3/bulk/products-with-inventory/create", { body });
@@ -221,6 +255,7 @@ async function bulkCreateProducts(ctx, products) {
     id: x.item?.id, slug: x.item?.slug, revision: x.item?.revision,
     variantId: x.item?.variantsInfo?.variants?.[0]?.id,
     hasOptions: (products[i]?.options?.length ?? 0) > 0,
+    isDigital: !!fileIds[i],
     quantity: products[i]?.quantity ?? 0,
   }));
   await stockOptionlessProducts(ctx, created);
@@ -233,7 +268,7 @@ async function bulkCreateProducts(ctx, products) {
 // are already stocked by the create above, so they're skipped. Backfills the default variantId from a
 // query if the create response didn't return it.
 async function stockOptionlessProducts(ctx, created) {
-  const need = created.filter((p) => !p.hasOptions && p.id);
+  const need = created.filter((p) => !p.hasOptions && !p.isDigital && p.id); // digital variants ship inStock from the create
   if (!need.length) return;
   const missing = need.filter((p) => !p.variantId).map((p) => p.id);
   if (missing.length) {
@@ -300,7 +335,8 @@ async function attachProductImages(ctx, items) {
  * the DEFAULT path — call it once instead of the individual functions.
  *
  * @param plan {{
- *   products: [{ name, description, price, compareAtPrice?, quantity, options?, imageUrl?, altText? }],
+ *   products: [{ name, description, price, compareAtPrice?, quantity, options?, imageUrl?, altText?,
+ *                digitalFileUrl?, digitalFileName? }],
  *   categories?: { [categoryName]: string[] },   // map of category name -> product NAMES in it
  * }}
  * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number }

package/skills/wix-app/references/editor-react-component/A11Y-REVIEW-REFERENCE.md

@@ -1,172 +0,0 @@
-# Editor React Component A11y Review Reference
-
-Use this reference for decisions that require code inspection after running the scanners in [`A11Y-REVIEW.md`](A11Y-REVIEW.md). The scanner output owns rule-specific context: rule ID, location, message, resolution path, evidence, and confidence. Do not maintain a separate rule catalog here.
-
-## Scanner Result Handling
-
-Treat every scanner finding as a lead until the component implementation confirms how the flagged behavior reaches the rendered element.
-
-1. Read the full finding, including evidence and confidence when present.
-2. Trace the component topology through local wrappers, shared primitives, and package implementations.
-3. Deduplicate findings that identify the same issue at the same location.
-4. Assign a verdict: `confirmed`, `false-positive`, or `not-relevant`.
-5. Fix confirmed issues inline, then re-run both scanners on changed JSX files.
-
-When both scanners flag the same issue, keep the finding with the strongest semantic evidence. The scanners complement each other; a finding from one scanner is not automatically stronger because of its tier.
-
-## Confidence Model
-
-### High
-
-Use high confidence when the code and scanner evidence unambiguously show the violation, for example:
-
-- the flagged rendered element and static props establish the behavior directly
-- the component implementation resolves to the flagged semantic element
-- an explicit polymorphic prop establishes the rendered element
-
-Fix high-confidence findings immediately.
-
-### Medium
-
-Use medium confidence when:
-
-- props strongly imply the rendered semantics
-- the implementation only partially resolves but preserves likely semantics
-- the component name, props, and surrounding evidence strongly agree
-
-Read the surrounding code. If it confirms the inference, fix the issue. If it contradicts the inference, discard the finding. If the implementation remains unresolved, treat it as low confidence.
-
-### Low
-
-Use low confidence when:
-
-- only weak heuristics support the semantic guess
-- the implementation cannot be resolved
-- runtime props or spreads can materially change the rendered semantics
-
-Continue tracing the code. Fix only after the issue is confirmed; otherwise leave the code unchanged.
-
-### Confidence vs. Actionability
-
-Confidence answers whether the issue is real. It does not decide whether a confirmed fix is safe.
-
-- Confirmed + safe/local fix: fix now.
-- Confirmed + risky behavior change or non-local refactor: leave unchanged.
-- Unconfirmed or ambiguous: leave unchanged.
-
-If the violation is visible in the code and has a localized, behavior-preserving fix, treat it as confirmed and apply the fix.
-
-Valid reasons to leave code unchanged:
-
-- semantics remain ambiguous after reading the available code
-- product intent cannot be derived from the code
-- the fix requires a risky behavior change or a non-local refactor
-
-Do not leave a confirmed safe/local issue unchanged because it is low severity, secondary, shared, or outside the first file in scope.
-
-## Semantic Resolution
-
-Resolve the rendered behavior in this order:
-
-1. The flagged JSX element and its static props
-2. Explicit polymorphic props such as `as="a"` or `component="button"`
-3. The local component implementation
-4. Installed package source or declarations in `node_modules`
-5. Prop evidence such as `href`, `to`, `src`, `alt`, and `role`
-6. Component-name heuristics
-
-For local imports, follow the exported component's rendered root. Continue through local or package components until the semantics resolve or the evidence becomes too weak.
-
-For package imports, resolve the import from `node_modules` and inspect its exported entry point. If the package hides its rendered semantics, use prop and naming evidence without assigning more confidence than the evidence supports.
-
-## Tier 2 Manual Review Checklist
-
-Run this checklist after scanner findings are triaged. Tier 2 is required even when both scanners return zero findings.
-
-### Semantic Targeting
-
-- Do ARIA attributes land on the semantically correct element instead of a layout wrapper?
-- Do labels, descriptions, and roles reach the actual interactive or landmark element?
-- Do wrappers preserve the semantics exposed by their API?
-
-### Icon-Only and Visual-Only States
-
-- Do icon-only buttons, links, or controls have an accessible name?
-- If visible text is hidden, is it visually hidden in an accessibility-safe way instead of removed from the accessibility tree?
-- Do meaningful icons or images expose accessible text when needed?
-
-### CSS and Hidden Content
-
-- Does `display: none` remove content that should remain available to assistive technology?
-- Are hidden or collapsed states consistent across visuals, focusability, and the accessibility tree?
-- Do conditional classes or CSS variables create states where labels or instructions disappear from assistive technology?
-
-### Decorative vs. Meaningful Content
-
-- Are decorative separators, ornaments, and repeated icons hidden from assistive technology?
-- Are meaningful visuals, status icons, or graphics named appropriately?
-
-### Focus and Interaction Consistency
-
-- Can hidden or collapsed items still receive focus?
-- Do interactive-looking elements expose the correct role and keyboard behavior?
-- Do disabled, inert, or collapsed states behave consistently for keyboard users and assistive technology?
-- Search all in-scope files for `onClick` on elements without built-in interaction (`div`, `span`, `section`, `header`, `footer`, `li`, `td`, and similar tags). Include conditional patterns such as `{...(condition && { onClick: handler })}`. Verify that each match also has the required `role`, `tabIndex`, and keyboard handler (`onKeyDown` or `onKeyUp`). A missing combination is a high-confidence finding.
-- Before fixing missing keyboard semantics, check for nested interactive children, existing focus management, and the condition that enables interaction. Use the [pre-fix checks](#pre-fix-checks-for-adding-button-semantics-to-a-non-interactive-element).
-
-### Structural Semantics
-
-- Are landmarks, headings, and list semantics preserved through wrappers and layout components?
-- When the component implements breadcrumbs, tabs, menus, dialogs, or similar patterns, do the expected semantics reach the rendered structure?
-
-### Editor React Component Contracts
-
-- Are ARIA attributes routed through the typed `a11y` prop and converted at the correct element?
-- Do icon-only labels come from `constants.ts` or user-configurable `a11y` instead of hardcoded strings?
-- Does the component preserve direction support and isolate each `ReactNode` content prop with `dir="ltr"`?
-- Do extension overrides preserve a11y-relevant manifest fields generated from JSX?
-
-## Fix Principles
-
-- Use the rule ID, message, and evidence emitted by the scanner as the rule-specific fix context.
-- Read the surrounding code before editing.
-- Preserve visual and runtime behavior.
-- Prefer the smallest correct change and avoid unrelated refactors.
-- Fix the semantic owner: the component root, the correct inner element, a shared base, or the call site that supplies the value.
-- When a wrapper already accepts and forwards a required prop, fix the call site. When it does not, update the wrapper contract and forwarding before fixing the call site.
-- Do not hardcode reusable accessibility values such as alternative text. Accept them through the component API when they depend on consumer content.
-- Route Editor React Component ARIA through `a11y` and `convertA11yKeysToHtmlFormat(a11y)` according to [`ACCESSIBILITY.md`](ACCESSIBILITY.md).
-
-## Pre-Fix Checks for Adding Button Semantics to a Non-Interactive Element
-
-Before adding `role="button"`, `tabIndex`, and keyboard handlers to an element such as `<div>`, verify all four conditions below.
-
-### 1. Interactive Children
-
-Check whether the element conditionally or unconditionally contains `<a>`, `<button>`, `<input>`, `<Link>`, or a component that resolves to an interactive element. Button semantics on the parent would create nested interaction.
-
-If interactive children are possible, either exclude that branch from the parent's interaction condition or use a separate control element.
-
-### 2. Existing Focus Management
-
-Check whether the element already receives `tabIndex` from another source, such as `getTabIndexAttribute`, an a11y prop spread, or an interactions framework. Determine the prop merge order and keep one source authoritative.
-
-When an existing a11y spread should win, place the conditional interaction spread before it so `tabIndex: 0` only acts as a fallback.
-
-### 3. Interaction Condition
-
-Read the full boolean expression that enables interaction. Verify that it:
-
-- excludes states that already render an interactive child
-- excludes editor preview, externally controlled, disabled, or reduced-motion states when required
-- uses explicit comparisons such as `=== undefined` or `=== true` when `true`, `false`, and `undefined` have different meanings
-
-Fix a fragile condition as part of the accessibility change. Correct semantics attached to the wrong state are still incorrect behavior.
-
-### 4. Accessible Name Scope
-
-Decide whether an accessible label names the interaction or the component as a whole. Keep a component-level label outside the interaction condition so it persists in non-interactive states. Apply an action-specific label only while that action is available.
-
-## After Fixing
-
-Re-run both scanners on changed `.tsx` / `.jsx` files. Continue with `npx wix build`, `npx wix generate manifest`, and the project's TypeScript check as required by [`A11Y-REVIEW.md`](A11Y-REVIEW.md#phase-5-verify).