@wix/agent-skills 1.33.1 → 1.35.0

package/skills/wix-replatform/resources/rp-target-wix/lib/tax-build.js

@@ -0,0 +1,231 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+
+// rp-target-wix — the DETERMINISTIC WooCommerce tax-rate -> Wix Tax payload builder.
+//
+// Mirrors wix-build.js's role for Stores products: everything here implements, as plain code,
+// the mapping rules already recorded as prose in domains/tax/{domain.json,entities/*.json}. Do
+// not re-derive these rules by LLM judgement per project — read them here, and if a rule changes,
+// change it here and in the domain JSON's mappingGuidance together, since they must stay the same
+// fact stated twice (once for humans, once as code).
+//
+// Scope: Tax Groups / Tax Regions / Manual Tax Mappings only. Tax Settings is a single
+// site-level upsert (see domains/tax/entities/tax-settings.json) with no payload-shaping
+// logic worth a builder — just a boolean passthrough.
+
+// ISO 3166-1 alpha-2 countries Wix accepts a `subdivision` for (dev.wix.com Tax Region object,
+// verified live 2026-08-12). Any other country must omit subdivision (or pass '*').
+const SUBDIVISION_ELIGIBLE_COUNTRIES = new Set([
+  'AU', 'BR', 'CA', 'FR', 'DE', 'IN', 'IT', 'MX', 'NL', 'PT', 'ES', 'AE', 'GB', 'US',
+]);
+
+// Countries Tax Region create rejects outright (dev.wix.com, "embargoed-countries-rejected").
+const EMBARGOED_COUNTRIES = new Set(['CU', 'IR', 'KP', 'SY']);
+
+// WooCommerce's `state` column format varies by version/site — sometimes bare ("NY"), sometimes
+// country-prefixed ("US-NY"). Wix stores ISO 3166-2 WITHOUT the country prefix. Never invent a
+// subdivision for a country outside the eligible set — pass none (country-level region) instead.
+function normalizeSubdivision(country, rawState) {
+  const countryCode = String(country || '').trim().toUpperCase();
+  if (isBlank(rawState)) return undefined;
+  if (!SUBDIVISION_ELIGIBLE_COUNTRIES.has(countryCode)) return undefined;
+  const raw = String(rawState).trim().toUpperCase();
+  const prefix = `${countryCode}-`;
+  return raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+}
+
+// WooCommerce `rate` is a PERCENTAGE (e.g. "7.5000"). Wix `taxRate` is a decimal-string FRACTION
+// with at most 6 decimal places (e.g. "0.075"). A number, integer, or percent-string all 400.
+function toWixTaxRateFraction(percentage) {
+  const n = Number(percentage);
+  if (!Number.isFinite(n)) {
+    throw new Error(`toWixTaxRateFraction: "${percentage}" is not a finite number`);
+  }
+  let fixed = (n / 100).toFixed(6);
+  if (fixed.includes('.')) {
+    fixed = fixed.replace(/0+$/, '');
+    if (fixed.endsWith('.')) fixed += '0';
+  }
+  return fixed;
+}
+
+// One Wix Tax Region per distinct (country, subdivision) pair — a source can have several rate
+// rows (standard/reduced/zero) sharing one region, which fan out to separate Manual Tax Mappings
+// against that ONE region rather than one region each.
+function groupTaxRatesByRegion(taxRates) {
+  const regions = new Map();
+  for (const rate of taxRates || []) {
+    const country = String(rate.country || '').trim().toUpperCase();
+    if (!country) continue;
+    const subdivision = normalizeSubdivision(country, rate.state);
+    const key = taxRegionDedupeKey({ country, subdivision });
+    if (!regions.has(key)) {
+      regions.set(key, { country, subdivision, rates: [] });
+    }
+    regions.get(key).rates.push(rate);
+  }
+  return [...regions.values()];
+}
+
+function taxRegionDedupeKey({ country, subdivision }) {
+  return `${String(country || '').trim().toUpperCase()}|${subdivision || ''}`;
+}
+
+function isEmbargoedCountry(country) {
+  return EMBARGOED_COUNTRIES.has(String(country || '').trim().toUpperCase());
+}
+
+// `appId` must be resolved live per site via listTaxCalculators/resolveManualTaxCalculatorAppId
+// in wix-writers.js — never hardcoded here, since it's installation-scoped and differs per site.
+function buildTaxRegionInput({ country, subdivision }, { appId, taxIncludedInPrice = false }) {
+  if (!appId) throw new Error('buildTaxRegionInput: appId is required (resolve live, never hardcode)');
+  const taxRegion = { country: String(country).trim().toUpperCase(), appId, taxIncludedInPrice };
+  if (subdivision) taxRegion.subdivision = subdivision;
+  return taxRegion;
+}
+
+function buildTaxGroupInput({ name }) {
+  if (isBlank(name)) throw new Error('buildTaxGroupInput: name is required');
+  return { name: String(name).trim() };
+}
+
+// `taxGroupId`/`taxRegionId` must already exist — resolve both from their own crosswalks before
+// calling. `taxName` is cosmetic (shown at checkout) and never affects the calculated amount.
+function buildManualTaxMappingInput(rate, { taxGroupId, taxRegionId }) {
+  if (!taxGroupId) throw new Error('buildManualTaxMappingInput: taxGroupId is required');
+  if (!taxRegionId) throw new Error('buildManualTaxMappingInput: taxRegionId is required');
+  const mapping = {
+    taxGroupId,
+    taxRegionId,
+    taxRate: toWixTaxRateFraction(rate.rate),
+  };
+  if (!isBlank(rate.name)) mapping.taxName = String(rate.name).trim();
+  return mapping;
+}
+
+// Create Manual Tax Mapping 409s on a duplicate (taxRegionId, taxGroupId, taxName, taxType,
+// jurisdiction, jurisdictionType) — dedupe on that composite key before creating, since
+// WooCommerce rows differing only in `priority` (no Wix equivalent) would otherwise re-collide.
+//
+// LIVE-VERIFIED 2026-08-15: Query Manual Tax Mapping returns the STRING "UNDEFINED" for an unset
+// `jurisdictionType` (not "" and not the field's absence), while a freshly-built mappingInput that
+// never sets the field is plain JS `undefined` — so comparing a fetched mapping against a
+// newly-built one for the same (region, group) 409'd instead of correctly deduping. Normalize both
+// "" and "UNDEFINED" to the same bucket so a fetched existing mapping and a freshly-built one that
+// both mean "no jurisdictionType" produce the same key.
+function normalizeDedupeField(value) {
+  const s = String(value || '').trim();
+  return s === 'UNDEFINED' ? '' : s;
+}
+function manualTaxMappingDedupeKey({ taxRegionId, taxGroupId, taxName, taxType, jurisdiction, jurisdictionType }) {
+  return [
+    taxRegionId,
+    taxGroupId,
+    normalizeDedupeField(taxName),
+    normalizeDedupeField(taxType),
+    normalizeDedupeField(jurisdiction),
+    normalizeDedupeField(jurisdictionType),
+  ].join('|');
+}
+
+// The four Wix "default" tax groups every site has (VERIFIED live 2026-08-12 via
+// List Default Tax Groups: "Shipping and delivery", "Products", "Services", "Cancellation
+// fees" — see tax-group.json's query-tax-groups-excludes-defaults pitfall). WooCommerce has no
+// equivalent split: a `class: "standard"` rate (or a blank class) is the store's ONE general
+// rate, not a products-only rate — WooCommerce's own `shipping` boolean on a tax rate row
+// exists specifically because the rate is meant to reach beyond products. Wix's
+// Products/Shipping and delivery/Services/Cancellation fees groups are BILLING categories, not
+// TAX-RATE categories, so mapping a standard rate to "Products" only silently zero-rates every
+// other category in that region — a group with no manual tax mapping calculates to EXACTLY
+// ZERO tax (VERIFIED live 2026-08-12, see manual-tax-mapping.json's
+// unmapped-tax-group-calculates-to-exactly-zero-tax finding). That is undercharging, not a
+// faithful migration, so a standard-class rate must get one mapping per default group.
+const DEFAULT_GROUP_NAMES = ['Products', 'Shipping and delivery', 'Services', 'Cancellation fees'];
+
+// Which already-created Wix tax groups a WooCommerce rate's Manual Tax Mapping(s) should
+// target. `defaultGroups` is List Default Tax Groups' result; `customGroups` is this project's
+// own created-group tracking, each carrying the `sourceTaxClass` it was created for (from
+// planCustomTaxGroups's plan — a plain Query Tax Groups result has no such field, since Wix
+// itself doesn't know why a custom group exists).
+//
+// A `standard` (or blank) class rate targets every DEFAULT group — never a class-specific
+// custom group (a reduced-rate/zero-rate group exists so a product TAGGED with that class gets
+// a different rate than the store's general one, not the same rate broadened everywhere), and
+// never the Tax Exempt group (no mapping is how exempt is represented at all — this falls out
+// naturally here since Tax Exempt's `sourceTaxClass` is null and no rate's class is ever null).
+// A non-standard class rate targets ONLY its own matching custom group.
+//
+// List Default Tax Groups' own schema (dev.wix.com, checked 2026-08-15) has no locale-invariant
+// key for "which billing category is this" — a TaxGroup is only {id, name, revision, dates}, and
+// the docs' own worked example returns a completely different default set ("Standard Tax") than
+// a live site returns, confirming `name` genuinely varies per site/locale and isn't a fixed
+// constant. `name` is matched here anyway because it's the ONLY field the API offers for this —
+// but matching zero (or some but not all four) of DEFAULT_GROUP_NAMES on a translated or
+// differently-configured site must never fall through to a silent partial fan-out: that would
+// reproduce the exact silent-undercharging bug this function exists to fix, just triggered by
+// site language/config instead of an incomplete implementation. Fail loudly instead, so a human
+// resolves the real name mismatch before any mapping is created.
+function groupsForRate(rate, { defaultGroups = [], customGroups = [] } = {}) {
+  const taxClass = String(rate?.class || 'standard').trim() || 'standard';
+  if (taxClass === 'standard') {
+    const matched = defaultGroups.filter((group) => DEFAULT_GROUP_NAMES.includes(String(group?.name || '').trim()));
+    if (matched.length !== DEFAULT_GROUP_NAMES.length) {
+      const foundNames = matched.map((group) => group.name);
+      const missing = DEFAULT_GROUP_NAMES.filter((name) => !foundNames.includes(name));
+      throw new Error(
+        `groupsForRate: expected all ${DEFAULT_GROUP_NAMES.length} default tax groups (${DEFAULT_GROUP_NAMES.join(', ')}), `
+        + `found only ${matched.length} (missing: ${missing.join(', ')}). This site's default tax group names may be `
+        + 'translated or otherwise non-standard -- resolve the real names via List Default Tax Groups before mapping, '
+        + 'do not silently map to a partial set.',
+      );
+    }
+    return matched;
+  }
+  return customGroups.filter((group) => group?.sourceTaxClass === taxClass);
+}
+
+// Only create a custom tax group when a real per-product signal exists — never speculatively,
+// just because wc/v3/taxes/classes lists WooCommerce's unused defaults (reduced-rate/zero-rate).
+// `products` here is the discovered wc/v3/products record shape (`tax_class`, `tax_status`).
+function planCustomTaxGroups(products) {
+  const plans = [];
+  const classesInUse = new Set();
+  let hasExempt = false;
+  for (const product of products || []) {
+    const taxClass = String(product.tax_class || 'standard').trim() || 'standard';
+    if (taxClass !== 'standard') classesInUse.add(taxClass);
+    if (String(product.tax_status || 'taxable').trim() === 'none') hasExempt = true;
+  }
+  for (const taxClass of classesInUse) {
+    plans.push({ name: taxClass, sourceTaxClass: taxClass, reason: 'non-default WooCommerce tax_class actually assigned to at least one product' });
+  }
+  if (hasExempt) {
+    plans.push({ name: 'Tax Exempt', sourceTaxClass: null, exempt: true, reason: 'at least one product has tax_status=none — dedicated group, deliberately no manual tax mapping in any region' });
+  }
+  return plans;
+}
+
+// "No source has any tax-rate rows" is the majority case — the
+// correct action is to create nothing speculative, not to pre-create empty regions/mappings.
+function shouldSkipTaxDomain(taxRates) {
+  return !Array.isArray(taxRates) || taxRates.length === 0;
+}
+
+module.exports = {
+  SUBDIVISION_ELIGIBLE_COUNTRIES,
+  EMBARGOED_COUNTRIES,
+  normalizeSubdivision,
+  toWixTaxRateFraction,
+  groupTaxRatesByRegion,
+  taxRegionDedupeKey,
+  isEmbargoedCountry,
+  buildTaxRegionInput,
+  buildTaxGroupInput,
+  buildManualTaxMappingInput,
+  manualTaxMappingDedupeKey,
+  DEFAULT_GROUP_NAMES,
+  groupsForRate,
+  planCustomTaxGroups,
+  shouldSkipTaxDomain,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/url-mapper-transport.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const WRITER_ROOT = '/_api/url-mapper/writer/v1/url-mapping';
+
+function createUrlMapperTransport({ send, inspectDestination }) {
+  if (typeof send !== 'function' || typeof inspectDestination !== 'function') throw new Error('authenticated sender and destination inspection required');
+  return {
+    inspectDestination,
+    async read(key) {
+      const result = await send({ method: 'GET', path: `${WRITER_ROOT}/${encodeURIComponent(key)}` });
+      if (result && (result.code === 'URL_MAPPER_NOT_FOUND' || result.status === 404)) return null;
+      const mapping = result && (result.urlMapping || result.mappingRecord || result);
+      if (!mapping || typeof mapping.mapping !== 'string' || typeof mapping.pageIdentifier !== 'string') {
+        throw new Error(`URL Mapper read-back for ${key} lacks saved mapping or page identifier`);
+      }
+      return mapping;
+    },
+    async write(payload, capability, { mode }) {
+      if (!capability || payload.key !== capability.key || payload.urlMapping?.pageIdentifier !== capability.pageIdentifier) {
+        throw new Error('URL Mapper payload differs from capability knowledge');
+      }
+      if (!['create', 'update'].includes(mode)) throw new Error('URL Mapper write mode required');
+      return send({ method: mode === 'create' ? 'POST' : 'PUT', path: `${WRITER_ROOT}/${encodeURIComponent(payload.key)}`, body: payload });
+    },
+  };
+}
+
+module.exports = { WRITER_ROOT, createUrlMapperTransport };

package/skills/wix-replatform/resources/rp-target-wix/lib/value-utils.js

@@ -0,0 +1,14 @@
+'use strict';
+
+// Shared scalar-value helpers used across the rp-target-wix builders (tax-build.js,
+// shipping-build.js, gift-card-build.js, ...). Kept tiny and dependency-free on purpose — this is
+// not a general utils dumping ground, just the one helper that was independently duplicated
+// byte-for-byte in three builder files.
+
+function isBlank(value) {
+  return value == null || String(value).trim() === '';
+}
+
+module.exports = {
+  isBlank,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/variant-correlation.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Shared deterministic one-to-one comparison; response order is never an identity.
+function resolveInventoryRows(canonical, target) {
+  if (!target || !target.id || !Array.isArray(target.variantsInfo?.variants)) throw new Error('Target product omitted variant identities');
+  // Stores V3 may re-case option and choice names on write ("ALTERNATIV" reads back
+  // "Alternativ", "10m" reads back "10M"; LIVE-VERIFIED 2026-10-15), so names match
+  // case-insensitively. A case-only collision still fails below as an ambiguous match.
+  const key = (choices) => JSON.stringify(choices.map(c => [String(c.optionName).toLowerCase(), String(c.choiceName).toLowerCase()]).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))));
+  const targetByChoices = new Map();
+  for (const variant of target.variantsInfo.variants) {
+    if (!variant.id) throw new Error('Target variant omitted identity');
+    const choices = (variant.choices || []).map(c => {
+      if (c.optionChoiceNames) return c.optionChoiceNames;
+      const options = (target.options || []).filter(o => o.id === c.optionChoiceIds?.optionId);
+      if (options.length !== 1) throw new Error('Target option identity is missing or ambiguous');
+      const values = (options[0].choicesSettings?.choices || []).filter(v => v.choiceId === c.optionChoiceIds.choiceId);
+      if (values.length !== 1) throw new Error('Target choice identity is missing or ambiguous');
+      return { optionName: options[0].name, choiceName: values[0].name };
+    });
+    const identity = key(choices);
+    if (targetByChoices.has(identity)) throw new Error('Ambiguous target variant choices');
+    targetByChoices.set(identity, variant.id);
+  }
+  const matched = new Set();
+  return canonical.variants.map(variant => {
+    const variantId = targetByChoices.get(key(variant.choices));
+    if (!variantId || matched.has(variantId)) throw new Error('Source variant has no unique target match');
+    matched.add(variantId);
+    return { productId: target.id, variantId, inventory: { inStock: variant.inStock } };
+  });
+}
+
+module.exports = { resolveInventoryRows };

package/skills/wix-replatform/resources/rp-target-wix/lib/wix-build.js

@@ -13,6 +13,7 @@
 // worse artifact than the twenty lines it replaces. The spec still owns WHICH canonical fields
 // route through them, so coverage reporting stays complete.
 
+const { inventoryForVariant } = require('./stores-inventory.js');
 const { STORES_V3_TARGET, CATEGORY_TARGET, CANONICAL_FIELDS } = require('./wix-target-spec.js');
 
 // --- coercion --------------------------------------------------------------
@@ -27,13 +28,51 @@ function money(amount) {
 // Wix rejects a slug containing ^!“”$%&'*+,.:;<>=?@\/()[]{}_|` ~#. Vendors mint illegal ones
 // routinely — Shopify turns a decimal size into an underscore (ph-5_5), which 400s the whole
 // bulk batch, so this runs on EVERY slug rather than being a vendor quirk.
+//
+// CORRECTED 2026-09-27: this used to collapse to `[^a-z0-9-]+` — an ASCII allowlist that also
+// stripped every non-Latin letter (Hebrew, Chinese, Cyrillic, ...), silently sanitizing an
+// all-non-Latin slug down to near-empty. Confirmed live: non-Latin (e.g. Hebrew)
+// product slugs written via direct PATCH read back byte-identical (see
+// domains/stores/entities/product.json's wordpress-percent-encoded-slug pitfall, which only
+// documents Wix stripping literal '%', never a non-Latin-letter rejection). Stripping non-Latin
+// letters here would otherwise silently defeat decodeWpSlug's percent-decode for every non-Latin
+// source site: decode restores the real non-Latin text, then this function threw it away again.
+//
+// REWRITTEN 2026-09-29: a hand
+// enumerated punctuation BLOCKLIST is what the comment above still describes Wix's actual rule as
+// -- but successive checks each found a DIFFERENT class of character neither this
+// blocklist nor its two follow-on patches (C0/C1 control bytes, then Cf zero-width/format chars)
+// happened to cover, most recently other Unicode symbols/punctuation entirely outside all three
+// enumerations (™, §, •, an em dash, ½, ...). A blocklist enumeration is structurally incomplete
+// by construction -- there is always a next uncovered class -- so this is now the other shape of
+// the same rule, an ALLOWLIST of what to KEEP: Unicode letters (\p{L}, live-verified safe: the non-Latin
+// slugs above), combining marks (\p{M}, so a decomposed accented letter written as base +
+// combining accent, e.g. "e" + U+0301, survives as one unit instead of splitting into a hyphen),
+// and decimal digits (\p{Nd} specifically, not the broader \p{N} -- Unicode "Other Number" also
+// covers vulgar fractions and Roman numerals like "½"/"Ⅷ", which are exactly the kind of
+// symbol-shaped character this rewrite exists to stop assuming is a safe slug character just
+// because it happens to be a "number"). Everything outside that set -- known punctuation, control
+// bytes, format chars, or a class nobody has hit yet -- becomes a hyphen. An allowlist by category
+// is exhaustive; a blocklist enumeration cannot be, which is the whole reason this needed a 4th
+// patch after three were already shipped.
+const WIX_SLUG_ILLEGAL_CHARS = /[^\p{L}\p{M}\p{Nd}-]/gu;
 function toWixSlug(raw) {
   const slug = String(raw == null ? '' : raw)
     .toLowerCase()
-    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/[\s_]+/g, '-')
+    .replace(WIX_SLUG_ILLEGAL_CHARS, '-')
     .replace(/-{2,}/g, '-')
     .replace(/^-+|-+$/g, '');
-  if (!slug) throw new Error(`toWixSlug: "${raw}" sanitizes to an empty slug`);
+  // Non-empty is not enough: \p{M} combining marks (kept above for a decomposed accented
+  // letter, base + combining accent) also cover invisible marks like emoji variation selectors
+  // (U+FE0F etc), so an emoji/symbol-only title -- "heavy black heart" + VS-16, say -- can
+  // sanitize to a slug made of nothing but an invisible character. Require the survivor to carry
+  // at least one actual letter or digit; anything else is the same "no usable slug" case as
+  // sanitizing to empty, and gets the same deterministic-source-id-fallback treatment from the
+  // caller.
+  if (!slug || !/[\p{L}\p{Nd}]/u.test(slug)) {
+    throw new Error(`toWixSlug: "${raw}" sanitizes to an empty slug`);
+  }
   return slug;
 }
 
@@ -52,6 +91,34 @@ function isBlank(value) {
   return value == null || value === '' || (Array.isArray(value) && value.length === 0);
 }
 
+// Classification is deliberately based on visible text, while the value returned to Wix retains
+// its source HTML. WooCommerce descriptions regularly contain empty wrappers, &nbsp;, or the
+// stock "Lorem ipsum" filler; importing any of those is equivalent to importing no copy.
+function normalizedDescriptionText(value) {
+  return String(value == null ? '' : value)
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&(nbsp|#0*160|#x0*a0);/gi, ' ')
+    .replace(/&(amp|quot|#0*39|#x0*27);/gi, ' ')
+    .normalize('NFKC')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function isPlaceholderDescription(value) {
+  return normalizedDescriptionText(value).toLowerCase().startsWith('lorem ipsum');
+}
+
+// Wix Stores has one product description, whereas WooCommerce supplies a short, above-the-fold
+// body and a long body. Preserve each non-placeholder source body in source reading order. The
+// horizontal rule is intentional content structure, not a visual approximation with blank lines.
+function composeProductDescription({ description, shortDescription } = {}) {
+  const long = normalizedDescriptionText(description) && !isPlaceholderDescription(description) ? description : undefined;
+  const short = normalizedDescriptionText(shortDescription) && !isPlaceholderDescription(shortDescription) ? shortDescription : undefined;
+  if (short && long) return `${short}\n<hr />\n${long}`;
+  return short || long;
+}
+
 // --- structural builders ---------------------------------------------------
 // Option definitions are derived from the variants' own choices, so a value that never occurs
 // cannot produce a phantom choice. Order is first-seen, which preserves the source's ordering.
@@ -73,7 +140,7 @@ function buildOptions(product) {
 // A variant references its option choices BY NAME; the API returns server-assigned choice ids.
 // An empty `choices: []` is the correct encoding of "this product has no real options" — it must
 // produce a single default variant, never a synthetic one-choice option.
-function buildVariants(product, { inStock = true } = {}) {
+function buildVariants(product, { inStock } = {}) {
   return (product.variants || []).map((variant) => {
     const out = {
       visible: coerceBoolean(variant.visible, true),
@@ -85,8 +152,9 @@ function buildVariants(product, { inStock = true } = {}) {
         },
       })),
       price: buildVariantPrice(variant),
-      inventoryItem: { inStock },
     };
+    const inventory = inventoryForVariant(variant, { inStock });
+    if (inventory) out.inventoryItem = inventory;
     if (!isBlank(variant.sku)) out.sku = String(variant.sku);
     // Weight is expected already converted to the site's unit by the adapter; the canonical field
     // carries a number, not a unit-bearing string.
@@ -127,16 +195,57 @@ function buildVariantPrice(variant) {
 // product's main media, so caller-side ordering matters.
 // TRAP: reading these back needs `?fields=MEDIA_ITEMS_INFO`; a plain GET returns only media.main
 // and looks empty even on a successful ingest.
+//
+// The url this emits is a REQUEST TO FETCH, not a stored file. Wix returns 200 before it has
+// fetched anything, and a failed background fetch drops the item and leaves the product with an
+// EMPTY gallery — silently, and after the old image was already replaced. A caller
+// that writes this media and trusts the 200 has not finished; use
+// `patchStoresProductMediaVerified` or run an equivalent read-back sweep.
+//
+// `image.url` MUST arrive already resolved to the source's original, maximum-resolution file and
+// already percent-encoded. Wix copies exactly the one file this URL points at and
+// generates every derivative from it, with no way to raise the quality afterwards — so a crop
+// passed here is that product's permanent ceiling. Do not "helpfully" reach back to a raw source
+// field such as `src` here; the source adapter owns that choice and knows which of the several
+// URLs the source offered is the biggest.
 function buildMedia(product) {
   const items = (product.images || [])
     .filter((image) => image && image.fetchable !== false && !isBlank(image.url))
-    .map((image) => ({ url: image.url, ...(isBlank(image.altText) ? {} : { altText: image.altText }) }));
+    .map((image) => ({
+      url: image.url,
+      ...(isBlank(image.altText) ? {} : { altText: image.altText }),
+      ...(isBlank(image.displayName) ? {} : { displayName: image.displayName }),
+    }));
   return items.length ? { itemsInfo: { items } } : null;
 }
 
-// Emit a title tag only when it differs from the product name — a duplicate tag says nothing and
-// is pure noise in the payload.
-function buildSeoData(product) {
+// A product that carries `seoEvidence` (an evidence-contract source such as Yoast on
+// WooCommerce) emits a tag ONLY for a proven per-field override, or for the owner's explicit
+// `materialize` choice via `seoPlan` (rp-target-wix/lib/product-seo.js planProductSeo). Its
+// `seoTitle`/`seoDescription` are ignored: on such sources those are rendered template output,
+// and writing them turns an inherited pattern into a hard per-product override. A proven override
+// is written even when it equals the product name.
+//
+// A product WITHOUT `seoEvidence` is the legacy CSV path (Shopify/Magento/BigCommerce SEO
+// columns are authored per-product values): unchanged, including the duplicate-of-name skip.
+function buildSeoData(product, { seoPlan } = {}) {
+  if (product.seoEvidence !== undefined && product.seoEvidence !== null) {
+    let tags;
+    if (seoPlan) {
+      if (seoPlan.productId !== undefined && product.sourceId != null && String(seoPlan.productId) !== String(product.sourceId)) {
+        throw new Error(`buildSeoData: seoPlan for ${seoPlan.productId} passed for product ${product.sourceId}`);
+      }
+      tags = seoPlan.tags;
+    } else {
+      tags = [];
+      const ev = product.seoEvidence;
+      if (ev.title && ev.title.state === 'override' && !isBlank(ev.title.value)) tags.push({ type: 'title', children: String(ev.title.value) });
+      if (ev.description && ev.description.state === 'override' && !isBlank(ev.description.value)) {
+        tags.push({ type: 'meta', props: { name: 'description', content: String(ev.description.value) } });
+      }
+    }
+    return tags.length ? { tags: tags.map((tag) => JSON.parse(JSON.stringify(tag))) } : null;
+  }
   const tags = [];
   if (!isBlank(product.seoTitle) && String(product.seoTitle).trim() !== String(product.name || '').trim()) {
     tags.push({ type: 'title', children: String(product.seoTitle) });
@@ -158,19 +267,56 @@ function setPath(target, path, value) {
   cursor[parts[parts.length - 1]] = value;
 }
 
+// `sourceDeclaredOptionNames` says which options the SOURCE declared, independent of
+// whether any variant choices could be resolved from them. `choices: []` must keep meaning "no
+// real options", so a product that declared options yet built none is a LOST-options product,
+// and it throws unless the caller passes the user's own recorded decision for THIS product. The
+// decision is bound twice (key and value both name `product.sourceId`), so product A's entry can
+// never be replayed for B, even by rebuilding the key from B's id.
+function isValidOptionLossDecision(product, decision) {
+  if (!decision || typeof decision !== 'object') return false;
+  const { key, entry } = decision;
+  const sourceId = product.sourceId == null ? '' : String(product.sourceId);
+  if (!sourceId.trim() || key !== `optionLoss:${sourceId}`) return false;
+  if (!entry || typeof entry !== 'object' || entry.source !== 'user') return false;
+  const value = entry.value;
+  if (!value || typeof value !== 'object') return false;
+  if (value.accept !== 'default-variant' || value.sourceProductId !== sourceId) return false;
+  const declared = product.sourceDeclaredOptionNames;
+  const accepted = value.declaredOptionNames;
+  return (
+    Array.isArray(accepted) &&
+    accepted.length === declared.length &&
+    accepted.every((name, index) => name === declared[index])
+  );
+}
+
+function assertDeclaredOptionsResolved(product, options, optionLossDecision) {
+  const declared = product.sourceDeclaredOptionNames;
+  if (declared === undefined || declared === null) return;
+  if (!Array.isArray(declared)) {
+    throw new Error(`buildProduct: "${product.name}" sourceDeclaredOptionNames must be an array of option names`);
+  }
+  if (!declared.length || options.length) return;
+  if (isValidOptionLossDecision(product, optionLossDecision)) return;
+  throw new Error(
+    `buildProduct: "${product.name}" (${product.sourceId}) declared options [${declared.join(', ')}] but resolved to zero; record the loss in mapping-gaps.json (no valid human optionLoss decision for this product).`,
+  );
+}
+
 // Builds the Stores V3 create body from a canonical product record.
-// `options.inStock` exists because availability is frequently the ONLY importable inventory signal
-// (most vendor exports carry no quantity column); sending quantity 0 would mark a whole catalog
-// out of stock, so the caller states the intent explicitly.
-function buildProduct(product, { inStock = true, target = STORES_V3_TARGET } = {}) {
+// Explicit variant stock wins. A caller may supply an approved fallback for missing stock;
+// there is no implicit availability default. Codegen reports variants without stock evidence.
+function buildProduct(product, { inStock, target = STORES_V3_TARGET, optionLossDecision, seoPlan } = {}) {
   if (isBlank(product.name)) throw new Error('buildProduct: product.name is required');
   const body = { ...target.constants };
+  const composedDescription = composeProductDescription(product);
 
   // Spec-driven scalars.
   for (const [canonicalPath, fieldSpec] of Object.entries(target.fields)) {
     if (!fieldSpec.payloadPath) continue; // structural: handled below
     const key = canonicalPath.replace(/^product\./, '');
-    let value = product[key];
+    let value = canonicalPath === 'product.description' ? composedDescription : product[key];
     const def = CANONICAL_FIELDS[canonicalPath] || {};
     if (isBlank(value) && def.default !== undefined) value = def.default;
     if (isBlank(value) && typeof value !== 'boolean') continue;
@@ -189,10 +335,11 @@ function buildProduct(product, { inStock = true, target = STORES_V3_TARGET } = {
 
   // Structural builders, declared in the spec via `via`.
   const options = buildOptions(product);
+  assertDeclaredOptionsResolved(product, options, optionLossDecision);
   if (options.length) body.options = options;
   const media = buildMedia(product);
   if (media) body.media = media;
-  const seoData = buildSeoData(product);
+  const seoData = buildSeoData(product, { seoPlan });
   if (seoData) body.seoData = seoData;
   body.variantsInfo = { variants: buildVariants(product, { inStock }) };
   if (!body.variantsInfo.variants.length) {
@@ -204,7 +351,7 @@ function buildProduct(product, { inStock = true, target = STORES_V3_TARGET } = {
 // --- category --------------------------------------------------------------
 // Categories are created depth-ascending so a parent id is always resolvable. Dedupe against a
 // live site must key on name + PARENT, never name alone: a real tree repeats a name at different
-// depths (e.g. "Shampoo & Conditioner" under two different parents).
+// depths (e.g. "Accessories" under two different parents).
 function buildCategory(category, { categoryIdByPath = new Map(), target = CATEGORY_TARGET } = {}) {
   if (isBlank(category.name)) throw new Error('buildCategory: category.name is required');
   const body = { ...target.constants };
@@ -226,7 +373,11 @@ function buildCategory(category, { categoryIdByPath = new Map(), target = CATEGO
 module.exports = {
   money,
   toWixSlug,
+  WIX_SLUG_ILLEGAL_CHARS,
   coerceBoolean,
+  normalizedDescriptionText,
+  isPlaceholderDescription,
+  composeProductDescription,
   buildOptions,
   buildVariants,
   buildVariantPrice,