@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-replatform/scripts/visual-qa.mjs

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, normalizeUrl, parseArgs, readJson, resolveOutputDir, writeJson } from "./lib/common.mjs";
+import { verifyFrozenManifest } from "./lib/extraction-contract.mjs";
+
+async function main() {
+  const args = parseArgs();
+  const url = normalizeUrl(args._[0] || args.url).toString();
+  const outputDir = resolveOutputDir(url, args.out);
+  const report = await visualQa({ outputDir });
+  await writeJson(path.join(docsDir(outputDir), "qa", "visual-qa.json"), report);
+  if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else console.log(`Visual QA heuristic score: ${report.score}/100`);
+}
+
+export async function visualQa({ outputDir }) {
+  const dir = docsDir(outputDir);
+  const latest = await safeRead(path.join(dir, "extraction", "latest.json"), null);
+  if (!latest?.captureId) return missingManifestReport();
+  const extractionDir = path.join(dir, "extraction", latest.captureId);
+  const integrity = await verifyFrozenManifest(extractionDir);
+  const observations = path.join(extractionDir, "observations");
+  const page = await safeRead(path.join(observations, "page.json"), {});
+  const seo = await safeRead(path.join(observations, "seo.json"), {});
+  const sourceMap = { pages: [page], seo };
+  const interactionMap = await safeRead(path.join(observations, "interaction-map.json"), { interactions: [], structural: {} });
+  const sceneContract = await safeRead(path.join(observations, "scene-contract.json"), { scenes: [] });
+  const controlStateContract = await safeRead(path.join(observations, "control-state-contract.json"), { controls: [] });
+  const visualAssets = await safeRead(path.join(observations, "visual-assets.json"), { logos: [], icons: [] });
+  const layoutBlueprint = await safeRead(path.join(observations, "layout-blueprint.json"), { pages: [] });
+  const buildPlan = await safeRead(path.join(dir, "build", "build-plan.json"), { units: [] });
+  const ledger = await safeRead(path.join(dir, "build", "section-implementation.json"), { units: [] });
+  const specIndex = await safeRead(path.join(extractionDir, "spec-index.json"), {});
+  const extractionGaps = await safeRead(path.join(extractionDir, "extraction-gaps.json"), { gaps: [] });
+  const chromePages = (sourceMap.pages || []).filter((page) => page.chrome);
+  const implementationText = await readImplementationText(outputDir);
+  const chromeWarnings = chromeReviewWarnings({ chromePages, implementationText });
+  const repeaterWarnings = repeaterReviewWarnings({ pages: sourceMap.pages || [], implementationText });
+  const interactionWarnings = interactionReviewWarnings({ pages: sourceMap.pages || [], interactionMap, implementationText });
+  const checks = [];
+  checks.push(check("frozen manifest integrity", integrity.ok && integrity.manifest.manifestHash === latest.manifestHash, 20, integrity.failures));
+  checks.push(check("home build plan matches manifest", buildPlan.manifestHash === latest.manifestHash, 10));
+  checks.push(check("every planned unit has a build ledger entry", buildPlan.units?.every((unit) => ledger.units?.some((entry) => entry.id === unit.id && entry.specHash === unit.hash)), 10));
+  checks.push(check("source pages extracted", sourceMap.pages?.length > 0, 10));
+  checks.push(check("text content captured", sourceMap.pages?.some((p) => p.sections?.some((s) => s.text?.length > 80)), 15));
+  checks.push(check("seo captured", Boolean(sourceMap.seo?.title || sourceMap.pages?.some((p) => p.seo?.title)), 10));
+  checks.push(check("screenshots captured or fallback recorded", sourceMap.pages?.some((p) => Object.keys(p.screenshots || {}).length > 0 || p.extractionWarnings?.length), 5));
+  checks.push(check("stateful scene contract generated", Array.isArray(sceneContract.scenes) && sceneContract.scenes.length > 0, 10));
+  checks.push(check("control state contract generated", Array.isArray(controlStateContract.controls) && controlStateContract.controls.length > 0, 10));
+  checks.push(check("source logo assets materialized", (visualAssets.logos || []).length > 0 && (visualAssets.logos || []).every((logo) => Boolean(logo.localPath || logo.sourceUrl)), 10));
+  checks.push(check("important text geometry captured", (layoutBlueprint.pages || []).some((page) => page.sections?.some((section) => section.regions?.some((region) => region.textGeometry?.lineCount))), 10));
+  checks.push(check("chrome evidence captured or fallback warning recorded", chromeEvidenceAvailable(sourceMap.pages), 10));
+  checks.push(check("repeaters preserved or manually flagged", !repeaterWarnings.some((warning) => warning.kind === "collapsed-repeater"), 5, repeaterWarnings.filter((warning) => warning.kind === "collapsed-repeater").map((warning) => warning.message)));
+  checks.push(check("repeater headings preserved or manually flagged", !repeaterWarnings.some((warning) => warning.kind === "missing-repeater-headings"), 5, repeaterWarnings.filter((warning) => warning.kind === "missing-repeater-headings").map((warning) => warning.message)));
+  checks.push(check("multi-image repeaters preserved or manually flagged", !repeaterWarnings.some((warning) => warning.kind === "collapsed-multi-image-repeater"), 5, repeaterWarnings.filter((warning) => warning.kind === "collapsed-multi-image-repeater").map((warning) => warning.message)));
+  checks.push(check("dropdown hierarchy preserved or manually flagged", !chromeWarnings.some((warning) => warning.kind === "flattened-dropdown"), 10, chromeWarnings.filter((warning) => warning.kind === "flattened-dropdown").map((warning) => warning.message)));
+  checks.push(check("sticky header footprint reviewed", !chromeWarnings.some((warning) => warning.kind === "sticky-header-footprint"), 5, chromeWarnings.filter((warning) => warning.kind === "sticky-header-footprint").map((warning) => warning.message)));
+  checks.push(check("seo-only hero text reviewed", !chromeWarnings.some((warning) => warning.kind === "seo-only-hero-text"), 5, chromeWarnings.filter((warning) => warning.kind === "seo-only-hero-text").map((warning) => warning.message)));
+  checks.push(check("core interaction evidence consumed", !interactionWarnings.some((warning) => warning.kind !== "manual-interaction-review"), 20, interactionWarnings.filter((warning) => warning.kind !== "manual-interaction-review").map((warning) => warning.message)));
+  checks.push(check("source footer content preserved", !interactionWarnings.some((warning) => warning.kind === "missing-footer-content" || warning.kind === "clone-process-copy"), 10, interactionWarnings.filter((warning) => warning.kind === "missing-footer-content" || warning.kind === "clone-process-copy").map((warning) => warning.message)));
+  const rawScore = checks.reduce((sum, item) => sum + (item.pass ? item.points : 0), 0);
+  const possiblePoints = checks.reduce((sum, item) => sum + item.points, 0);
+  const unitAcceptance = await acceptanceResults({
+    extractionDir,
+    buildPlan,
+    ledger,
+    specIndex,
+    gaps: extractionGaps.gaps || [],
+  });
+  return {
+    score: possiblePoints ? Math.round((rawScore / possiblePoints) * 100) : 0,
+    rawScore,
+    possiblePoints,
+    checks,
+    unitAcceptance,
+    pageAcceptance: checks.map(({ name, pass, warnings = [] }) => ({
+      criterion: name,
+      status: pass ? "verified" : "failed-or-pending",
+      warnings,
+    })),
+    warnings: [...chromeWarnings, ...repeaterWarnings, ...interactionWarnings].map((warning) => warning.message),
+    manifestHash: latest.manifestHash,
+    provisionalUnits: buildPlan.units?.filter((unit) => unit.status === "provisional").map((unit) => unit.id) || [],
+    note: "Frozen-spec preflight only. Run browser-backed result comparison and report unresolved local gaps without blocking unrelated units.",
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+async function acceptanceResults({ extractionDir, buildPlan, ledger, specIndex, gaps }) {
+  const gapById = new Map(gaps.map((gap) => [gap.id, gap]));
+  const ledgerById = new Map((ledger.units || []).map((entry) => [entry.id, entry]));
+  const results = [];
+  for (const unit of buildPlan.units || []) {
+    const relativePath = specIndex[unit.id];
+    const spec = relativePath ? await safeRead(path.join(extractionDir, relativePath), {}) : {};
+    const ledgerEntry = ledgerById.get(unit.id);
+    const ownedGaps = (unit.gapRefs || []).map((id) => gapById.get(id)).filter(Boolean);
+    const unresolvedGapRefs = ownedGaps
+      .filter((gap) => !["resolved", "user-accepted"].includes(gap.status))
+      .map((gap) => gap.id);
+    const viewports = Object.values(ledgerEntry?.verification || {});
+    const browserVerified = viewports.length > 0 && viewports.every((status) => status === "passed");
+    const implementationMatches = Boolean(ledgerEntry && ledgerEntry.specHash === unit.hash);
+    const required = Array.isArray(spec.acceptance?.required) ? spec.acceptance.required : [];
+    const criteria = required.map((criterion) => ({
+      criterion,
+      status: !implementationMatches
+        ? "not-implemented"
+        : unresolvedGapRefs.length
+          ? "provisional-gap-backed"
+          : browserVerified
+            ? "verified"
+            : "pending-browser-verification",
+      ...(unresolvedGapRefs.length ? { gapRefs: unresolvedGapRefs } : {}),
+    }));
+    results.push({
+      unitId: unit.id,
+      specHash: unit.hash,
+      implementationMatches,
+      status: criteria.length && criteria.every((entry) => entry.status === "verified")
+        ? "verified"
+        : unresolvedGapRefs.length
+          ? "provisional"
+          : implementationMatches
+            ? "verification-pending"
+            : "not-implemented",
+      criteria,
+      sourceAssertions: spec.acceptance?.sourceAssertions || [],
+      gapRefs: unresolvedGapRefs,
+    });
+  }
+  return results;
+}
+
+function missingManifestReport() {
+  return {
+    score: 0,
+    rawScore: 0,
+    possiblePoints: 20,
+    checks: [{ name: "frozen manifest integrity", pass: false, points: 20, warnings: ["No frozen extraction manifest exists."] }],
+    warnings: ["No frozen extraction manifest exists."],
+    provisionalUnits: [],
+    note: "Extraction must freeze before build QA.",
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function interactionReviewWarnings({ pages, interactionMap, implementationText }) {
+  const warnings = [];
+  if (!implementationText) return [{ kind: "manual-interaction-review", message: "No implementation source exists yet; verify every core interaction after UI code is written." }];
+  const required = new Set((pages || []).flatMap((page) => page.interactionDiscovery?.requiredBehaviors || []));
+  const media = interactionMap.structural?.media || (pages || []).flatMap((page) => page.interactionDiscovery?.media || []);
+  for (const item of media.filter((entry) => entry.src && entry.role === "background")) {
+    if (!mediaReferenced(implementationText, item.src)) {
+      warnings.push({ kind: "missing-embedded-media", message: `Required ${item.provider || item.tag} background media is not referenced by the implementation: ${item.src}` });
+    }
+  }
+  if (required.has("preserve-carousel-card-expansion") && !(/carousel|story-rail|rail-track|case-card/i.test(implementationText) && /overflow-x|overflow\s*:\s*auto|scrollLeft|scrollWidth|translateX/i.test(implementationText) && /active|expanded/i.test(implementationText))) {
+    warnings.push({ kind: "flattened-carousel", message: "Source carousel has an active-card expansion state, but implementation does not show an overflowing rail with active/expanded state handling." });
+  }
+  if (required.has("preserve-scroll-expanded-section-state") && !(/position\s*:\s*(sticky|fixed)|scrolltrigger|intersectionobserver/i.test(implementationText) && /scroll/i.test(implementationText))) {
+    warnings.push({ kind: "flattened-scroll-state", message: "Source scroll-state section is required, but implementation does not show pinned/sticky scroll-state handling." });
+  }
+  if (/this cloned homepage|development reconstruction|first-pass clone|video background unavailable/i.test(implementationText)) {
+    warnings.push({ kind: "clone-process-copy", message: "Implementation contains clone/migration-process copy that must not appear on a migrated source page." });
+  }
+  for (const page of pages || []) {
+    const legalText = String(page.footer?.legalText || "").replace(/\s+/g, " ").trim();
+    const meaningful = legalText.split(/(?<=[.!?])\s+/).find((sentence) => sentence.length >= 80);
+    if (meaningful && !implementationText.includes(meaningful.slice(0, 80))) {
+      warnings.push({ kind: "missing-footer-content", message: "Source footer legal text was extracted but is not present in implementation source." });
+    }
+  }
+  return warnings;
+}
+
+function mediaReferenced(implementationText, source) {
+  const canonicalSource = canonicalMediaUrl(source);
+  if (implementationText.includes(source) || implementationText.includes(canonicalSource)) return true;
+  return canonicalSource ? implementationText.includes(canonicalSource.replace(/&amp;/g, "&")) : false;
+}
+
+function canonicalMediaUrl(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return raw;
+  try {
+    const url = new URL(raw);
+    url.search = url.search.replace(/\?([^?]*)\?/g, "?$1&");
+    return url.toString();
+  } catch {
+    return raw.replace(/\?([^?]*)\?/g, "?$1&");
+  }
+}
+
+function repeaterReviewWarnings({ pages, implementationText }) {
+  const warnings = [];
+  for (const page of pages || []) {
+    for (const warning of page.repeaterDiagnostics?.warnings || []) {
+      warnings.push({
+        kind: "manual-repeater-review",
+        message: `Source page ${page.path || page.url}: ${warning}`,
+      });
+    }
+    for (const repeater of page.repeaters || []) {
+      if (!implementationText) {
+        warnings.push({
+          kind: "manual-repeater-review",
+          message: `Source page ${page.path || page.url} has structured repeater content (${repeater.itemCount || repeater.items?.length || 0} items); verify the implementation consumes repeaters instead of flattening the content.`,
+        });
+        continue;
+      }
+      const headings = (repeater.items || []).map((item) => item.heading).filter(Boolean);
+      const matchedHeadings = headings.filter((heading) => implementationText.includes(heading)).length;
+      const hasRepeaterStructure = /\brepeaters\b|\bstories\b|\bitems\b|\bmap\s*\(/.test(implementationText);
+      if (headings.length && matchedHeadings < Math.min(3, headings.length)) {
+        warnings.push({
+          kind: "missing-repeater-headings",
+          message: `Source page ${page.path || page.url} has ${headings.length} repeater heading(s), but fewer than ${Math.min(3, headings.length)} appear in implementation files.`,
+        });
+      }
+      if (matchedHeadings >= Math.min(3, headings.length) && !hasRepeaterStructure) {
+        warnings.push({
+          kind: "collapsed-repeater",
+          message: `Source page ${page.path || page.url} has structured repeater items, but implementation files contain multiple repeater headings without an obvious repeated-content structure.`,
+        });
+      }
+      if ((repeater.schema?.maxImagesPerItem || 0) > 1) {
+        const supportsMultipleImages = /\bimages\b|\bgallery\b|\bcarousel\b|map\s*\(\s*\(?image\b|image[s2-9]/.test(implementationText);
+        if (!supportsMultipleImages) {
+          warnings.push({
+            kind: "collapsed-multi-image-repeater",
+            message: `Source page ${page.path || page.url} has repeater items with up to ${repeater.schema.maxImagesPerItem} images each, but implementation files do not show an obvious multi-image item structure.`,
+          });
+        }
+      }
+    }
+  }
+  return warnings;
+}
+
+function check(name, pass, points, warnings = []) {
+  return { name, pass: Boolean(pass), points, ...(warnings.length ? { warnings } : {}) };
+}
+
+async function existsJsonOrText(filePath) {
+  try {
+    await import("node:fs/promises").then(({ access }) => access(filePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function safeRead(filePath, fallback) {
+  try {
+    return await readJson(filePath);
+  } catch {
+    return fallback;
+  }
+}
+
+function chromeEvidenceAvailable(pages = []) {
+  return pages.some((page) => {
+    if (!page.chrome) return false;
+    if (page.chrome.warnings?.length) return true;
+    return Boolean(page.chrome.header?.variants?.length || page.chrome.navigation?.length || page.chrome.heroEvidence);
+  });
+}
+
+function chromeReviewWarnings({ chromePages, implementationText }) {
+  const warnings = [];
+  if (!chromePages.length) {
+    warnings.push({
+      kind: "manual-chrome-review",
+      message: "No chrome evidence is available; manually review header behavior, menu hierarchy, logo size, and hero text before completion.",
+    });
+    return warnings;
+  }
+  for (const page of chromePages) {
+    for (const warning of page.chrome?.warnings || []) {
+      warnings.push({ kind: "manual-chrome-review", message: warning });
+    }
+    const dropdowns = (page.chrome?.navigation || []).filter((item) => item.children?.length);
+    if (dropdowns.length && implementationText) {
+      for (const dropdown of dropdowns) {
+        const childLabels = dropdown.children.map((child) => child.label).filter(Boolean);
+        const hasStructuredChildren = /children\s*[:=]|\bsubmenu\b|\bdropdown\b|<details\b|aria-haspopup/.test(implementationText);
+        const flattenedCount = childLabels.filter((label) => implementationText.includes(label)).length;
+        if (!hasStructuredChildren && flattenedCount >= Math.min(3, childLabels.length)) {
+          warnings.push({
+            kind: "flattened-dropdown",
+            message: `Navigation dropdown "${dropdown.label || dropdown.href}" has ${childLabels.length} source child item(s), but implementation files contain child labels without an obvious submenu structure.`,
+          });
+        }
+      }
+    } else if (dropdowns.length && !implementationText) {
+      warnings.push({
+        kind: "manual-chrome-review",
+        message: `Source navigation has dropdowns (${dropdowns.map((item) => item.label || item.href).join(", ")}); verify implementation preserves them as submenus after UI code exists.`,
+      });
+    }
+
+    const variants = page.chrome?.header?.variants || [];
+    const initial = variants.find((variant) => variant.name === "initial");
+    const scrolled = variants.find((variant) => variant.name === "scrolled");
+    const viewportHeight = page.chrome?.viewport?.height || 1200;
+    const limit = page.chrome?.header?.maxStickyViewportRatio || 0.16;
+    if (implementationText && initial?.height && initial.height / viewportHeight > limit && /position\s*:\s*sticky|position\s*:\s*fixed/.test(implementationText)) {
+      const hasCompactState = /scrolled|compact|is-sticky|shrink|small-header|sticky-header/.test(implementationText);
+      if (!hasCompactState && (!scrolled?.height || scrolled.height < initial.height * 0.75)) {
+        warnings.push({
+          kind: "sticky-header-footprint",
+          message: `Source initial header is large (${initial.height}px); implementation appears to use sticky/fixed positioning without an obvious compact scrolled state.`,
+        });
+      }
+    }
+
+    const seoOnly = page.chrome?.heroEvidence?.forbiddenSeoOnlyText || [];
+    if (implementationText && seoOnly.some((text) => text.length > 12 && implementationText.includes(text))) {
+      warnings.push({
+        kind: "seo-only-hero-text",
+        message: "Implementation contains SEO-only title/tagline text that was not confirmed as visible first-viewport hero content.",
+      });
+    } else if (!implementationText && seoOnly.length) {
+      warnings.push({
+        kind: "manual-chrome-review",
+        message: "SEO-only title/tagline text was detected; verify it is not rendered as hero copy without visual source evidence.",
+      });
+    }
+  }
+  return warnings;
+}
+
+async function readImplementationText(outputDir) {
+  const srcDir = path.join(outputDir, "src");
+  const files = await listSourceFiles(srcDir);
+  const chunks = [];
+  for (const file of files.slice(0, 80)) {
+    try {
+      const { readFile } = await import("node:fs/promises");
+      chunks.push(await readFile(file, "utf8"));
+    } catch {
+      // Ignore unreadable generated files during heuristic QA.
+    }
+  }
+  return chunks.join("\n").slice(0, 500000);
+}
+
+async function listSourceFiles(dir) {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) files.push(...await listSourceFiles(fullPath));
+      else if (/\.(astro|tsx?|jsx?|css|scss)$/.test(entry.name)) files.push(fullPath);
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/skills/wix-headless-templates/donations/INSTRUCTIONS.md

@@ -6,8 +6,19 @@ typed end-to-end. **The presentation is yours**: you design and implement the ca
 campaigns index, the campaign page's layout around the shipped form, the home page and the brand. You
 never write checkout logic; you never skip designing.
 
+Read [Donations experience](../../wix-headless/references/inline-recipes/experience-donations.md)
+before designing the donor surfaces. If that sibling skill is not installed, read the
+[published overlay](https://www.wix.com/skills/wix-headless/references/inline-recipes/experience-donations.md).
+It supplies the short,
+framework-independent page/form quality bar; the code contracts below supply the implementation.
+Apply its intent/draft recovery requirements in the UI layer: extend the supplied form/store where
+needed, retaining its validation and checkout exports. In-memory defaults alone do not survive an
+external checkout. Do not put donor notes in route parameters or reset them on an unverified return.
+
 A donation is an eCom cart (Cart V2) with one line that references the campaign; in V2 the cart IS the
 checkout, so the cart's id is the id the redirect session takes — there is no separate checkout entity.
+The cart's donation `options.amount` is a **number**, even though campaign price amounts are strings.
+Omit `options.frequency` for one-time giving; send only `WEEK`, `MONTH`, `YEAR` for recurring giving.
 Wix's hosted checkout takes the payment and the donor's details, and the eCom order is the receipt. The campaign entity carries
 **no description and no slug**: the story on a campaign page is the site's own copy, and routes key by
 the campaign id (`/donate/<id>`).
@@ -65,23 +76,9 @@ Astro stack additionally gets:
 
 Plus the **theme** (`@theme` block, one edit) and the **chrome** (`SiteLayout`, one pass).
 
-### What a complete donations site shows (recommended defaults)
-
-Defaults for a brief that says nothing about them; the prompt wins where it differs. Look at the
-campaigns before designing (how many, goals or not, frequencies, presets, images).
-
-- **Campaign page:** the Donate CTA and the amount picker in the first screen at 390px wide; the
-  frequency picker only when the campaign offers more than one frequency (the form decides); the
-  custom amount only when enabled; the story after the form on phones, beside it on desktop.
-- **Closed campaigns** (goal reached / expired): the progress and a closing message — never a Donate
-  button. `DonateForm` renders your `children` then; the card shows the state, not a CTA.
-- **Goal figures only from the DTO:** raised, target, percent, count, time left come from the metrics
-  API and the owner's goal. A campaign without a goal shows no progress; a goal whose raised total
-  couldn't be read shows the target alone.
-- **Copy:** nothing the owner didn't supply — no donor counts beyond `donationCount`, no "tax
-  deductible", no urgency the owner didn't set, no Wix IDs in visible text.
-- **Thank-you page:** the shipped island's rules — thanks with the order's facts when they can be
-  read, thanks without them otherwise, never "paid" unless the order says so.
+The shared Donations experience overlay above owns page composition, mobile density, truthful
+progress/copy and return-state quality. The contracts below own the wiring; apply both rather than
+maintaining a second set of design rules here.
 
 ### The contracts your components consume (tested and work as they are; read the source when something is off or the brief wants more)
 
@@ -107,7 +104,8 @@ campaigns before designing (how many, goals or not, frequencies, presets, images
 //   submitting, error, available /* campaign.acceptsDonations */,
 //   selectPreset(n), selectCustom(), setCustomAmount(text), setFrequency(f), setCoverFee(b), setNote(s),
 //   donate(): Promise<void> }  // resolves as the browser navigates to the hosted checkout (or with
-//                              // messages showing); rejects with a visitor-facing message — surface it
+//                              // messages showing); rejects with the original diagnostic error;
+//                              // render state.error for the visitor, not the raw API response
 // <DonateForm campaign={c} options? children? className? buttonClassName? /> wraps it: you only place
 // it; it decides what to render, what to say, and shows its own errors.
 
@@ -288,6 +286,18 @@ Wix as a return target must be one the host serves (SKILL.md step 1) — pass it
 - **Browsing and donating need no login.** They run on the visitor session the shipped client already
   holds; don't gate campaigns behind sign-in.
 
+## Verify the donation handoff
+
+Before calling this build working, follow the bounded anonymous API smoke test in
+[How to Code Donations](../../wix-headless/references/inline-recipes/how-to-code-donations.md#5-verify-before-handoff):
+campaign read → one Cart V2 → calculated line/totals → redirect session, using the same visitor.
+Use the sibling file when installed, otherwise
+`https://www.wix.com/skills/wix-headless/references/inline-recipes/how-to-code-donations.md`.
+Do not add a V1 Create Checkout step. A local test or a session URL is not proof of payment. Report
+API, hosted-checkout and payment verification separately; no payment without explicit authorization.
+For `ITEM_NOT_FOUND_IN_CATALOG`, inspect numeric amount, app/campaign IDs and frequency first, not
+reinstallation or premium. Keep sanitized error code/body/stage for diagnosis; do not swallow failures.
+
 ## Out of scope (don't improvise these)
 
 A donor's history or receipts page (member-only order reads), managing a recurring donation (Wix's
@@ -308,16 +318,19 @@ Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the
 | Accept payments — connect a payment method | `wix-cashier/payments` |
 | Upgrade the plan — online payments need premium | full URL: `https://www.wix.com/upgrade/website?metaSiteId={siteId}` |
 
-**Taking real donations needs a connected payment method plus a premium plan.** Until both are done, a visitor who reaches hosted checkout sees **"We can't accept online payments. Contact us for help with your order."** Recurring frequencies (`WEEK`/`MONTH`/`YEAR`) additionally need a
+**Taking real donations needs a connected payment method plus a payments-capable plan.** Cart/session
+creation can succeed before these are ready; it does not prove a charge can succeed. Do not use a
+premium explanation for a malformed catalog reference. A visitor can encounter an unavailable-payments
+message at hosted checkout until setup is complete. Recurring frequencies (`WEEK`/`MONTH`/`YEAR`) additionally need a
 payment provider that supports recurring payments. Mention it; don't treat it as a code failure. The
 cover-fee 2.9% is added to every recurring charge.
 
 ## Seeding
 
 Per `seed/SEED.md` — plain-data `plan.json` into `seed-donations.mjs` from the project root. Seed one
-campaign that exercises every form branch (3 presets with impact text, one-time + monthly, a goal with
-an end date, a custom amount with a minimum, note and cover-fee on, a cover image); a second campaign
-only when the brief lists several causes.
+approved cause for a new setup unless the brief lists several. Do not invent impact claims, goals or
+deadlines to exercise every form branch, and never reseed for a frontend-only request. Optional form
+states can be tested in local fixtures. Ongoing edits use the shared management recipe linked there.
 
 ## Caveats — verified against the SDK, not yet against a live site
 
@@ -344,5 +357,5 @@ first real site and read the owning file if one bites.
   provisions eCom, is unverified; the seed installs both and reports each result.
 - **Dashboard route.** The `app/<appDefId>` link redirects to the app's slug route; the slug itself
   was not resolved live.
-- The `donorCoveringFees` option key and the fixed 2.9% come from the Wix widget's source, not a
-  public reference page.
+- The `donorCoveringFees` flag, 2.9% and one-time frequency omission are documented in the public
+  [donation eCommerce integration](https://dev.wix.com/docs/api-reference/business-solutions/donations/donation-campaigns/e-commerce-integration-with-donation-campaigns).

package/skills/wix-headless-templates/donations/app/components/donations/DonateForm.tsx

@@ -8,7 +8,7 @@
 // donations (goal reached / expired) it renders `children` — your closing message — or nothing.
 // The redirect itself is useDonation → donationCheckoutUrl; nothing here builds a URL or marks
 // anything paid.
-import type { ReactNode } from "react";
+import { useId, type ReactNode } from "react";
 import { useDonation, type UseDonationOptions } from "../../hooks/donations/useDonation";
 import type { CampaignDetail } from "../../wix/donations/types";
 
@@ -23,7 +23,7 @@ export interface DonateFormProps {
 }
 
 const choice = (selected: boolean) =>
-  `cursor-pointer rounded-md border px-4 py-3 text-sm transition-colors ${
+  `relative block cursor-pointer rounded-md border px-4 py-3 text-sm transition-colors focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-primary ${
     selected ? "border-primary bg-primary text-primary-foreground" : "border-border bg-background text-foreground hover:bg-secondary"
   }`;
 
@@ -36,10 +36,10 @@ export default function DonateForm({
 }: DonateFormProps) {
   const d = useDonation(campaign, options);
   const o = campaign.options;
+  const fid = `donate-${campaign.id}-${useId()}`;
   if (!d.available) return children ? <>{children}</> : null;
 
   const show = (field: keyof typeof d.messages) => (d.showErrors && d.messages[field] ? d.messages[field] : null);
-  const fid = `donate-${campaign.id}`;
 
   return (
     <form
@@ -47,43 +47,65 @@ export default function DonateForm({
       noValidate
       onSubmit={(e) => {
         e.preventDefault();
-        void d.donate().catch(() => {});
+        const form = e.currentTarget;
+        void d.donate().then(() => {
+          if (!d.valid) {
+            // Wait for the store's validation state to render; do not steal focus while typing.
+            requestAnimationFrame(() => form.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus());
+          }
+        }).catch((error) => {
+          // The store shows a recoverable message; keep safe diagnostics, not donor data or tokens.
+          console.error("Donation checkout failed", {
+            stage: error?.stage ?? "checkout",
+            status: error?.status,
+            code: error?.body?.details?.applicationError?.code ?? error?.details?.applicationError?.code ?? error?.body?.code,
+          });
+        });
       }}
     >
       {o.frequencies.length > 1 && (
-        <fieldset>
+        <fieldset disabled={d.submitting}>
           <legend className="eyebrow mb-2">How often</legend>
-          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" role="radiogroup">
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
             {o.frequencies.map((f) => (
-              <button key={f.value} type="button" role="radio" aria-checked={d.frequency === f.value} className={choice(d.frequency === f.value)} onClick={() => d.setFrequency(f.value)}>
+              <label key={f.value} className={choice(d.frequency === f.value)}>
+                <input type="radio" name={`${fid}-frequency`} value={f.value} checked={d.frequency === f.value}
+                  onChange={() => d.setFrequency(f.value)} className="sr-only"
+                  aria-invalid={!!show("frequency")} aria-describedby={show("frequency") ? `${fid}-frequency-error` : undefined} />
                 {f.label}
-              </button>
+              </label>
             ))}
           </div>
-          {show("frequency") && <p className="mt-2 text-sm text-destructive" role="alert">{show("frequency")}</p>}
+          {show("frequency") && <p id={`${fid}-frequency-error`} className="mt-2 text-sm text-destructive" role="alert">{show("frequency")}</p>}
         </fieldset>
       )}
 
       {(o.presets.length > 0 || o.customAmount.enabled) && (
-        <fieldset>
+        <fieldset disabled={d.submitting}>
           <legend className="eyebrow mb-2">Amount</legend>
-          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3" role="radiogroup">
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">
             {o.presets.map((p) => {
               const selected = !d.customMode && d.presetAmount === p.amount;
               return (
-                <button key={p.amount} type="button" role="radio" aria-checked={selected} className={`${choice(selected)} text-left`} onClick={() => d.selectPreset(p.amount)}>
+                <label key={p.amount} className={`${choice(selected)} text-left`}>
+                  <input type="radio" name={`${fid}-amount-choice`} value={p.amount} checked={selected}
+                    onChange={() => d.selectPreset(p.amount)} className="sr-only"
+                    aria-invalid={!!show("amount")} aria-describedby={show("amount") ? `${fid}-amount-error` : undefined} />
                   <span className="block text-base font-semibold">{p.label}</span>
                   {p.impact && <span className={`mt-0.5 block text-xs ${selected ? "opacity-80" : "text-muted-foreground"}`}>{p.impact}</span>}
-                </button>
+                </label>
               );
             })}
             {o.customAmount.enabled && o.presets.length > 0 && (
-              <button type="button" role="radio" aria-checked={d.customMode} className={choice(d.customMode)} onClick={() => d.selectCustom()}>
+              <label className={choice(d.customMode)}>
+                <input type="radio" name={`${fid}-amount-choice`} value="custom" checked={d.customMode}
+                  onChange={() => d.selectCustom()} className="sr-only"
+                  aria-invalid={!!show("amount")} aria-describedby={show("amount") ? `${fid}-amount-error` : undefined} />
                 Other amount
-              </button>
+              </label>
             )}
           </div>
-          {show("amount") && <p className="mt-2 text-sm text-destructive" role="alert">{show("amount")}</p>}
+          {show("amount") && <p id={`${fid}-amount-error`} className="mt-2 text-sm text-destructive" role="alert">{show("amount")}</p>}
           {d.customMode && (
             <div className="mt-3">
               <label htmlFor={`${fid}-amount`} className="sr-only">
@@ -95,19 +117,20 @@ export default function DonateForm({
                   id={`${fid}-amount`}
                   inputMode="decimal"
                   autoComplete="off"
-                  className="w-full bg-transparent py-3 text-base text-foreground outline-none"
+                  className="min-w-0 flex-1 bg-transparent py-3 text-base text-foreground outline-none focus-visible:ring-2 focus-visible:ring-primary"
                   placeholder={o.customAmount.minLabel ? `${o.customAmount.minLabel} or more` : "Enter an amount"}
                   value={d.customAmount}
                   onChange={(e) => d.setCustomAmount(e.target.value)}
                   aria-invalid={!!show("customAmount")}
+                  aria-describedby={show("customAmount") || o.customAmount.minLabel || o.customAmount.maxLabel ? `${fid}-custom-help` : undefined}
                 />
               </div>
               {(o.customAmount.minLabel || o.customAmount.maxLabel) && !show("customAmount") && (
-                <p className="mt-1 text-xs text-muted-foreground">
+                <p id={`${fid}-custom-help`} className="mt-1 text-xs text-muted-foreground">
                   {[o.customAmount.minLabel && `Minimum ${o.customAmount.minLabel}`, o.customAmount.maxLabel && `Maximum ${o.customAmount.maxLabel}`].filter(Boolean).join(" · ")}
                 </p>
               )}
-              {show("customAmount") && <p className="mt-1 text-sm text-destructive" role="alert">{show("customAmount")}</p>}
+              {show("customAmount") && <p id={`${fid}-custom-help`} className="mt-1 text-sm text-destructive" role="alert">{show("customAmount")}</p>}
             </div>
           )}
         </fieldset>
@@ -115,7 +138,7 @@ export default function DonateForm({
 
       {o.askCoverFee && (
         <label className="flex items-start gap-3 text-sm text-foreground">
-          <input type="checkbox" className="mt-0.5" checked={d.coverFee} onChange={(e) => d.setCoverFee(e.target.checked)} />
+          <input type="checkbox" className="mt-0.5" checked={d.coverFee} disabled={d.submitting} onChange={(e) => d.setCoverFee(e.target.checked)} />
           <span>
             {d.feeLabel ? `Add ${d.feeLabel} to cover the processing fees` : "Cover the processing fees (2.9%)"}
             {d.frequency && d.frequency !== "ONE_TIME" && <span className="text-muted-foreground"> — on every payment</span>}
@@ -132,14 +155,17 @@ export default function DonateForm({
             id={`${fid}-note`}
             rows={3}
             maxLength={o.commentMaxLength}
-            className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none"
+            className="w-full rounded-md border border-border bg-background px-3 py-2 text-sm text-foreground outline-none focus-visible:ring-2 focus-visible:ring-primary"
             value={d.note}
             onChange={(e) => d.setNote(e.target.value)}
+            disabled={d.submitting}
+            aria-invalid={!!show("note")}
+            aria-describedby={`${fid}-note-hint${show("note") ? ` ${fid}-note-error` : ""}`}
           />
-          <p className="mt-1 text-right text-xs text-muted-foreground">
+          <p id={`${fid}-note-hint`} className="mt-1 text-right text-xs text-muted-foreground">
             {d.note.length}/{o.commentMaxLength}
           </p>
-          {show("note") && <p className="text-sm text-destructive" role="alert">{show("note")}</p>}
+          {show("note") && <p id={`${fid}-note-error`} className="text-sm text-destructive" role="alert">{show("note")}</p>}
         </div>
       )}