@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/compose.mjs

@@ -0,0 +1,83 @@
+// Compose a vertical's project: the blank scaffold (`blank/project`, what `wix create` copies plus
+// what the CLI's extender adds), the vertical deployed into it by the skill's own deploy script,
+// and a package-lock.json, so `wix create --template-path skills/wix-headless-templates/<vertical>/project`
+// yields the whole first vertical and `npm ci` installs it without resolving.
+//
+//   node skills/wix-headless-templates/compose.mjs [<vertical> …] [--relock] [--lock-from <package-lock.json>]
+//
+//   no vertical      every vertical (a folder with an app/)
+//   default          the project's existing lock is kept; a project without one gets a fresh
+//                    resolution (`npm install --package-lock-only`)
+//   --relock         resolve a fresh lock even when one exists
+//   --lock-from      use this lock (one vertical only)
+// Tarball URLs are written in registry.npmjs.org form whatever registry resolved them; npm
+// substitutes the configured registry at install time. The root entry of the lock is brought in
+// line with package.json (install/lock.mjs), and the result is checked: every dependency in
+// package.json is in the lock's root entry with the same range, or the script exits 1.
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { listVerticals } from "../wix-headless-kit/install/templates.mjs";
+import { syncLockRoot } from "../wix-headless-kit/install/lock.mjs";
+
+const TEMPLATES = dirname(fileURLToPath(import.meta.url));
+const DEPLOY = resolve(TEMPLATES, "..", "wix-headless-kit", "install", "deploy.mjs");
+const argv = process.argv.slice(2);
+const flag = (n) => { const i = argv.indexOf(`--${n}`); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : null; };
+const relock = argv.includes("--relock");
+const lockFrom = flag("lock-from");
+const skip = new Set(["--relock", "--lock-from", lockFrom].filter(Boolean));
+const requested = argv.filter((a) => !skip.has(a));
+const all = listVerticals(TEMPLATES);
+const verticals = requested.length ? requested : all;
+for (const v of verticals) if (!all.includes(v)) { console.error(`unknown vertical "${v}" — ${all.join(", ")}`); process.exit(1); }
+if (lockFrom && verticals.length !== 1) { console.error("--lock-from takes exactly one vertical"); process.exit(1); }
+
+const canonical = (lock) => {
+  for (const [key, p] of Object.entries(lock.packages ?? {})) {
+    if (!key || !p.resolved || !/^https?:\/\//.test(p.resolved)) continue;
+    const name = key.slice(key.lastIndexOf("node_modules/") + "node_modules/".length);
+    p.resolved = `https://registry.npmjs.org/${name}/-/${basename(new URL(p.resolved).pathname)}`;
+  }
+  return lock;
+};
+
+let failed = false;
+for (const v of verticals) {
+  const project = join(TEMPLATES, v, "project");
+  const lockPath = join(project, "package-lock.json");
+  const kept = !relock && !lockFrom && existsSync(lockPath) ? readFileSync(lockPath, "utf8") : null;
+  rmSync(project, { recursive: true, force: true });
+  cpSync(join(TEMPLATES, "blank", "project"), project, { recursive: true });
+  const d = spawnSync("node", [DEPLOY, v, "--stack", "astro"], { cwd: project, encoding: "utf8" });
+  let deployed = {};
+  try { deployed = JSON.parse(d.stdout); } catch { /* below */ }
+  if (d.status !== 0 || deployed.error) { console.log(JSON.stringify({ vertical: v, error: deployed.error ?? (d.stderr || d.stdout).slice(-400) })); failed = true; continue; }
+  let lock = "kept";
+  if (kept) writeFileSync(lockPath, kept);
+  else if (lockFrom) { cpSync(resolve(lockFrom), lockPath); lock = `from ${lockFrom}`; }
+  else {
+    const tmp = mkdtempSync(join(tmpdir(), "compose-"));
+    cpSync(join(project, "package.json"), join(tmp, "package.json"));
+    const r = spawnSync("npm", ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: tmp, encoding: "utf8", timeout: 600_000 });
+    if (r.status !== 0) { console.log(JSON.stringify({ vertical: v, error: `lock resolution failed: ${(r.stderr || r.stdout).slice(-400)}` })); failed = true; rmSync(tmp, { recursive: true, force: true }); continue; }
+    writeFileSync(lockPath, JSON.stringify(canonical(JSON.parse(readFileSync(join(tmp, "package-lock.json"), "utf8"))), null, 2) + "\n");
+    rmSync(tmp, { recursive: true, force: true });
+    lock = "resolved";
+  }
+  const sync = syncLockRoot(project);
+  // the project is a template: nothing site-specific, nothing generated
+  for (const f of ["wix.config.json", ".env.local", ".env", "AGENTS.md", "CLAUDE.md", ".gemini", "node_modules", ".wix", ".astro", "dist"]) rmSync(join(project, f), { recursive: true, force: true });
+  const lockRoot = JSON.parse(readFileSync(lockPath, "utf8")).packages?.[""] ?? {};
+  const pkg = JSON.parse(readFileSync(join(project, "package.json"), "utf8"));
+  const diff = [];
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const [n, r] of Object.entries(pkg[field] ?? {})) if (lockRoot[field]?.[n] !== r) diff.push(`${n}: package.json ${r}, lock ${lockRoot[field]?.[n] ?? "absent"}`);
+    for (const n of Object.keys(lockRoot[field] ?? {})) if (!(n in (pkg[field] ?? {}))) diff.push(`${n}: only in the lock`);
+  }
+  if (diff.length) failed = true;
+  console.log(JSON.stringify({ vertical: v, lock, promoted: sync?.promoted ?? [], packages: Object.keys(JSON.parse(readFileSync(lockPath, "utf8")).packages ?? {}).length, depsAdded: deployed.depsAdded, astroConfig: deployed.astroConfig, ...(diff.length ? { error: `lock root out of line: ${diff.join("; ")}` } : {}) }));
+}
+process.exit(failed ? 1 : 0);

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

@@ -0,0 +1,348 @@
+# Donations — playbook
+
+The donations machinery ships as files — campaign reads (list + by id, with goal progress), the exact
+donation → hosted-checkout sequence, the donate form, the goal progress block, the thank-you island,
+typed end-to-end. **The presentation is yours**: you design and implement the campaign card and the
+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.
+
+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.
+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>`).
+
+## The file map (deployed into `src/`)
+
+**On Astro and React the shipped files are tested and work as they are** — this table and the
+contracts below are everything you need to use them, so don't spend the run reading their source;
+wire them and build your surfaces. Reading them is the right move when something is off (a runtime
+error, a field this playbook doesn't cover) or when the brief wants a behaviour they don't offer —
+then read the file that owns it and change or extend it. On `lib`, `static`, and a port the
+components don't deploy at all, and each wiring section below opens with the files to read before
+writing their equivalents. Files you edit: `SiteLayout.astro`, `styles/global.css`, and the story
+copy on the campaign page. Files you **create** (skeletons below): your campaigns index island (or
+Astro markup), your campaign page layout, and your home page.
+
+| file | what it is |
+|---|---|
+| `wix/config.ts` · `wix/sdk.ts` | shared auth seam (deploy configures it — nothing to set by hand) |
+| `wix/media.ts` · `wix/money.ts` | `imgAttrs(url, sizes, ratio)` — every `<img>` attribute for a DTO image: `<img {...imgAttrs(c.imageUrl, "50vw", 9 / 16)} alt={c.name} />`; `imgSrc()` / `imgSrcSet()` underneath |
+| `wix/donations/types.ts` | the DTOs (`CampaignSummary`, `CampaignDetail`, `GoalProgress`, `DonationOptions`, `DonationReceipt`) — contracts inlined below |
+| `wix/donations/campaigns.ts` | `fetchCampaigns`, `fetchCampaign(id)`, `fetchDefaultCampaign` — the transport; the rules and DTO mappers are in `donations-core.ts` beside it (shared with the REST layer) |
+| `wix/donations/donate.ts` | `donationCheckoutUrl(campaignId, input)` — the donation cart + hosted redirect session; `fetchDonationReceipt(orderId)` — the thank-you page's order read; bodies in `donations-core.ts` |
+| `wix/donations/donation-store.ts` · `campaigns-store.ts` · `receipt-store.ts` | the form, listing and receipt state machines, framework-free (`createDonationStore(campaign)`, `createCampaignsStore()`, `createReceiptStore()` — `getState`/`subscribe` + actions, one instance per surface); the hooks below bind them to React, every other stack uses them directly |
+| `hooks/donations/useDonation.ts` | React binding of `donation-store.ts`: the donate form's state and actions — contract below |
+| `hooks/donations/useCampaigns.ts` | React binding of `campaigns-store.ts`: the listing — contract below |
+| `hooks/donations/useDonationReceipt.ts` | React binding of `receipt-store.ts`: reads `?orderId=` and the order — contract below |
+| `components/donations/DonateForm.tsx` | the donate form for one campaign — frequency picker only when > 1 frequency, presets with impact text, "Other amount" only when enabled (min/max messages), the cover-fee checkbox with the computed 2.9% only when asked, the note only when enabled, the live "Donate $25 Monthly" label, "Redirecting…" in flight, errors after the first attempt, the closed state as `children` — **wire as-is** (`<DonateForm client:load campaign={campaign}>closing message</DonateForm>`) |
+| `components/donations/GoalProgress.tsx` | raised of target, the bar at Wix's rounded percent, donation count, time left ("3 days left" / hours on the last day / "Ended") — renders nothing without a goal; no hooks, so it renders on the server — **wire as-is** on cards, the campaign page, a home strip (`compact` for cards) |
+| `components/donations/DonationReceipt.tsx` | the hosted checkout's thank-you island — reads `?orderId=`, shows the order's facts only when the order could be read, an honest thank-you otherwise, a neutral page on a direct visit — **wire as-is** (`client:only="react"`) |
+| `styles/global.css` | **the design system**: Tailwind v4 + the `@theme` token block (colors, radii, fonts — shared across verticals). Everything, shipped and yours, styles from these tokens |
+
+Astro stack additionally gets:
+
+| file | what it is |
+|---|---|
+| `layouts/SiteLayout.astro` | site chrome — **yours to brand** (keep the `seo-tags` slot + global.css import; it takes `image` for `og:image`). If another vertical is also deployed, its layout won — add a Donate nav link there |
+| `components/donations/CampaignPage.astro` | **REFERENCE** campaign surface: cover, name, `story` prop, `GoalProgress`, `DonateForm` with the closed-state message — redesign it (it is mounted by both pages below); pass the campaign's story copy through `story` |
+| `pages/donate/index.astro` | SSR campaigns index — **keep the frontmatter** (one campaign → renders `CampaignPage` directly, the Wix widget's default-campaign rule); the card markup is yours |
+| `pages/donate/[id].astro` | SSR campaign page, a real 404 on a missing or archived id — **keep the frontmatter** (plain `<title>`/`<meta>`/`og:image` from the DTO: Donations has no owner-editable SEO item type, so campaign pages don't appear in the Wix SEO panel or sitemap) |
+| `pages/donate/thank-you.astro` | the hosted checkout's return (`?orderId=`) — **keep the route**; the shipped redirect callbacks point at it |
+
+## What you build — the design job
+
+1. **The campaign card + campaigns index** — your tile (cover, name, the shipped `GoalProgress compact`,
+   a Donate link; a closed campaign reads "Goal reached" / "Ended", never "Donate") and grid rhythm, an
+   honest empty state. The index page ships with SSR data; render it in Astro markup or swap in an
+   island on `useCampaigns`.
+2. **The campaign page's layout** — cover, name, the story (your copy from the brief — the API has none),
+   `GoalProgress`, and the shipped `DonateForm` as the giving column; design it for the brand (a
+   sticky form column, an editorial split, a full-bleed cover). Donation logic never leaves the shipped
+   component and hook.
+3. **The home page** — hero, a featured campaign strip (`fetchCampaigns({ limit: 1 })` in frontmatter →
+   name, `GoalProgress`, CTA to `/donate/<id>`), brand story.
+
+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 contracts your components consume (tested and work as they are; read the source when something is off or the brief wants more)
+
+```ts
+// CampaignSummary (cards, strips) — display-ready:
+// { id, name, status /* "collecting" | "goalReached" | "expired" */, acceptsDonations,
+//   imageUrl /* "" when none */,
+//   goal: GoalProgress | null /* null = no goal */ }
+// GoalProgress: { raised /* "$1,250" | "" when unreadable */, target /* "$20,000" */,
+//   raisedAmount, targetAmount /* numbers for bar math only */, percent /* may exceed 100 */,
+//   donationCount, reached, endDate /* ISO | null */, ended, lastDay, daysLeft, hoursLeft }
+// CampaignDetail adds options: { currency /* "" when unknown */, presets: [{ amount, label, impact }],
+//   customAmount: { enabled, min, max, minLabel, maxLabel }, frequencies: [{ value, label }],
+//   askCoverFee, feeRate /* 0.029 */, commentsEnabled, commentMaxLength /* 100 */ }
+
+// useCampaigns({ initialCampaigns? }) →
+// { campaigns: CampaignSummary[]|null /* null = loading → skeletons; [] after a failed load, with error */, error }
+
+// useDonation(campaign, { origin?, paths? }?) →
+// { frequency, presetAmount, customMode, customAmount /* text */, coverFee, note,
+//   amount, fee, feeLabel, total, totalLabel, buttonLabel /* "Donate $25 Monthly" */,
+//   errors, messages /* per field, visitor-facing */, showErrors /* after the first attempt */, valid,
+//   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
+// <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.
+
+// useDonationReceipt(orderId?) → { orderId /* "" on a direct visit */, loading, receipt: DonationReceipt|null }
+// DonationReceipt: { orderNumber, donorFirstName, donorLastName, amount /* formatted */, paid, campaignId }
+```
+
+### The islands you create — skeletons
+
+The pages ship; the surfaces they render are yours. Hooks first, branches after (an early return
+above a hook changes hook order between renders and React throws). `client:load` islands render on
+the server too — render every state totally; nothing in a render path may throw.
+
+```tsx
+// src/components/donations/CampaignsGrid.tsx — YOU build it when the index wants client state;
+// pages/donate/index.astro can mount it with the SSR campaigns instead of its Astro card markup.
+import { useCampaigns } from "../../hooks/donations/useCampaigns";
+import GoalProgress from "./GoalProgress";
+import type { CampaignSummary } from "../../wix/donations/types";
+
+export default function CampaignsGrid(props: { initialCampaigns?: CampaignSummary[] /* SSR prop — pass straight to useCampaigns */ }) {
+  const { campaigns, error } = useCampaigns(props);
+  // …you implement the render:
+  //   • error → a short inline message
+  //   • campaigns === null → skeleton cards; [] → your honest empty state
+  //   • else YOUR grid of YOUR cards: cover via imgAttrs(c.imageUrl, "33vw", 9 / 16) only when
+  //     non-empty, the name (wraps — `min-w-0 break-words`), <GoalProgress goal={c.goal} compact />,
+  //     a link to `/donate/${c.id}` reading "Donate" only when c.acceptsDonations ("Goal reached" /
+  //     "Ended" otherwise) as the card's LAST ROW (`mt-auto`); never a button inside the card's <a>.
+}
+```
+
+```astro
+// src/components/donations/CampaignPage.astro — ships as a reference; REDESIGN it in place (both
+// pages mount it). Keep: <GoalProgress goal={campaign.goal} /> and
+// <DonateForm client:load campaign={campaign}>{closing message}</DonateForm>. Yours: the cover
+// (a bounded band on phones — `max-h-[40vh]`, not a full-screen hero), the name, the story prop
+// (your copy), the arrangement (the form in the first screen at 390px).
+```
+
+### The reference files for stacks where the components don't deploy
+
+On `lib`, `static`, and a port, nothing under `components/` or `hooks/` arrives. The state machines
+behind the hooks do arrive — `wix/donations/donation-store.ts`, `campaigns-store.ts`,
+`receipt-store.ts` — so you never rewrite them: create a store per surface, `subscribe`, render from
+`getState()`, call its actions. Their `*State` interfaces are the render contract; read those. What
+you write is the rendering — grid, card, campaign page, the form, the thank-you page — and for that
+read first:
+
+1. `components/donations/DonateForm.tsx` — the form as working code: which controls appear for which
+   options, the preset/custom switch, the fee line, the note counter, when messages show, the
+   in-flight label, the inline error, the closed state.
+2. `components/donations/GoalProgress.tsx` — the progress block's text rules (`timeLeftLabel`).
+3. `components/donations/DonationReceipt.tsx` — the thank-you page's three honest states.
+
+Under `templates/donations/app/`.
+
+### Wiring — Astro (default)
+
+1. Set the `@theme` tokens (one edit); brand `SiteLayout.astro` (one pass — merge into the other
+   vertical's layout instead if both are deployed).
+2. Redesign `components/donations/CampaignPage.astro` around the two shipped components and pass the
+   campaign's story through `story`; restyle the card markup in `pages/donate/index.astro` (or mount
+   your `CampaignsGrid` there with `initialCampaigns`). Author your surfaces in as few messages as
+   possible — batch multiple Writes per message.
+3. Write `pages/index.astro` (home) — it exists from the scaffold; Read it before overwriting.
+
+### Wiring — another JS framework (`--stack lib`: Vue, Svelte, Solid, plain Vite)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs donations --stack lib` put the data layer in `src/wix/` and nothing else: `sdk.ts` (the
+visitor client, configured with the public client id), `media.ts`, `money.ts`, and `wix/donations/` —
+`campaigns.ts`, `donate.ts`, `types.ts`, `donations-core.ts`, and the three stores. None of it is
+React. The hooks and components don't ship on this stack; the stores replace the hooks, and you write
+the components in your framework to the contracts on this page:
+
+- bind the stores with your framework's external-store primitive (Vue: `shallowRef` updated in
+  `subscribe`; Svelte: `readable(store.getState(), (set) => store.subscribe(() => set(store.getState())))`;
+  Solid: a signal set in `subscribe`). `createCampaignsStore({ initialCampaigns? })` per listing
+  (`start()` when mounted, `stop()` when unmounted), `createDonationStore(campaign, { paths? })` per
+  campaign surface (`donate()` navigates the document itself), `createReceiptStore()` on the thank-you
+  page (`start()` once mounted). State in, actions out — exactly the hooks' contracts above;
+- your form to the `DonateForm.tsx` contract: the controls the options allow, `buttonLabel` on the
+  CTA, disabled with "Redirecting…" while `submitting`, `messages` once `showErrors`, `error` inline,
+  the closed state when `available` is false.
+
+Routes `/donate`, `/donate/:id` (via `fetchCampaign`, null → your 404), `/donate/thank-you`; dev server
+on 4321; a static build goes through `npx @wix/cli@latest release` with `site.outputDirectory` pointing
+at the build folder, an SSR build is hosted by you. Page title from the DTO's `name`; the description
+is your copy — campaigns carry no `seoData`.
+
+### Wiring — static site (`--stack static`, no bundler)
+
+Read the reference files listed above before writing any surface.
+
+`deploy.mjs donations --stack static --out site` put the REST layer in `site/js/wix/` (browser ESM,
+the `.ts` beside each `.js` for reading). Everything the visitor loads lives under `site/` — pages,
+styles, `js/` — and `wix.config.json`'s `site.outputDirectory` is `"./site"`; the project root
+(config, plan, seed output) is never the upload. Same function names and DTOs as the table above, so
+the contracts on this page hold unchanged: `fetchCampaigns`, `fetchCampaign` from
+`./js/wix/campaigns.js`; `donationCheckoutUrl`, `fetchDonationReceipt` from `./js/wix/donate.js`. The
+state machines ship too: `createCampaignsStore` from `./js/wix/campaigns-store.js`,
+`createDonationStore` from `./js/wix/donation-store.js`, `createReceiptStore` from
+`./js/wix/receipt-store.js`. No components ship — you write the rendering in plain JS: one render
+function per surface that reads `getState()`, called from `subscribe`, with the CTA calling
+`donate()`. Pages are `donate.html`, `campaign.html?id=…` and `thank-you.html` (Wix static hosting
+serves files, not directories — name the file and link to it); pass
+`createDonationStore(campaign, { paths: { thankYou: "/thank-you.html", campaign: "/campaign.html?id=" + id } })`
+so the hosted checkout returns to your files; the campaign page reads the id, `fetchCampaign`, renders
+its not-found state on null, and sets `document.title` from the DTO's `name`. The visitor token
+persists in `localStorage` on its own; never mint per page. `npx @wix/cli@latest release` uploads `site/`.
+
+### Wiring — server-rendered, another language (Flask, Laravel, Rails, …)
+
+Read the reference files listed above before writing any surface.
+
+Run `deploy.mjs donations --stack static` in the project folder anyway: `js/wix/` is both the
+browser-side code and the readable spec. Then split by where the call runs. **Reads on the server:**
+port `js/wix/campaigns.ts` and `donations-core.ts` to your language — the same functions returning
+the same DTO shapes as dicts (the literal bodies are in the file), one anonymous visitor token per
+process for these public reads (mint and refresh per `client.ts`) — and render the index and the
+campaign page in your templates to the contracts above, so campaign names and goals are in the HTML.
+**Donating in the browser:** the form on `./js/wix/donation-store.js` (pass the campaign DTO rendered
+into the page as JSON), exactly as the static wiring above — the checkout and the redirect session are
+created by the visitor's own token from the page, so the server never handles per-visitor tokens; the
+thank-you page mounts `createReceiptStore()` the same way. Routes stay `/donate`, `/donate/<id>`,
+`/donate/thank-you`. Add your public https origin to the OAuth app's allowed domains before the hosted
+checkout can return.
+
+**Pre-rendered (Frozen-Flask, Pelican, any static-site generator) → Wix-hosted.** Same port for the
+reads, run at build time with one anonymous token; the generator emits `/donate` and one page per
+campaign from `fetchCampaigns()` (at most 100 — one call). Goal progress is frozen at build time —
+say so to the owner, or render `GoalProgress` client-side from a `fetchCampaign` on load. Run
+`deploy.mjs donations --stack static --out <build dir>` so `js/wix/` is inside the output the pages
+import from, point `site.outputDirectory` at that folder, `wix release`. Pages sit at different depths
+(`/`, `/donate/…`): give the templates one base path to `js/wix/` (root-relative `/js/wix/…`), never a
+relative `./js/wix/`. The frozen page is the first paint; the form still runs client-side through
+`createDonationStore()`. Close with the live URL, the rebuild + release command, and one line for the
+owner: dashboard edits to campaigns reach the site when that command runs; donating is live regardless.
+
+### Wiring — React SPA (Vite etc.)
+
+Import `./styles/global.css` once at the app entry (needs `@tailwindcss/vite` in the vite plugins —
+deploy added the dep). Routes: `/donate` → your grid (`useCampaigns()` fetches client-side when no
+`initialCampaigns` is passed); `/donate/:id` → `fetchCampaign(id)` client-side, then your page around
+`<DonateForm campaign={c} />` (null → your not-found state); `/donate/thank-you` → `<DonationReceipt />`.
+Deploy wrote the public client id into `wix/config.ts`; nothing else to configure.
+
+Routes on Wix hosting: the host serves files only, so a clean route answers 404 when loaded directly —
+hash routes, or one HTML file per route, decided before the first route is written; any URL handed to
+Wix as a return target must be one the host serves (SKILL.md step 1) — pass it through `paths`.
+
+## Hard rules
+
+- **Donate only through the shipped exports** — `DonateForm` / `useDonation` / `donationCheckoutUrl`
+  own the checkout line and the hosted redirect session. Never hand-build a checkout URL, never create
+  an order, never mark anything paid.
+- **Never promise a completed donation from the return URL.** `postFlowUrl` (the campaign page) is
+  hit on abandon too; landing on `/donate/thank-you?orderId=` is the success redirect. The thank-you
+  page reads the order when it can and degrades to a thank-you without order facts otherwise — never
+  an invented amount, name or "paid".
+- **Amounts are display-only.** `label`, `target`, `raised`, `amount` come pre-formatted from the API;
+  the only computed money is the fee preview — Wix's fixed 2.9% — and the button total. Wix prices
+  the line, tax and schedule at the hosted checkout.
+- **No invented goal numbers.** Progress renders only from `goal`; a campaign without one has none.
+- **The form is the shipped `DonateForm`** — it alone decides which controls appear (frequencies,
+  presets, custom amount, fee, note) and when a campaign is closed; a page never rebuilds that.
+- **The story copy is yours, the campaign data isn't.** The API has no description: write the cause's
+  story from the brief; never fabricate figures, beneficiaries or urgency.
+- Don't wrap shipped calls in your own API routes — they run client-side by design.
+- Where the shipped components deploy (Astro, React): theme via the `@theme` tokens, and your markup
+  uses Tailwind utilities on the same tokens — one design system across shipped and written code. No
+  parallel theme files, no hardcoded palette values. Where they don't (`lib`, `static`, a port): style
+  with whatever your stack does well, on one token set of your own.
+- Live data or an honest empty state — never mock campaigns, amounts, or progress.
+- **Call every hook before any conditional return.** Hooks first, branches after.
+- **Browsing and donating need no login.** They run on the visitor session the shipped client already
+  holds; don't gate campaigns behind sign-in.
+
+## Out of scope (don't improvise these)
+
+A donor's history or receipts page (member-only order reads), managing a recurring donation (Wix's
+emails and hosted member flows do that), campaign creation or editing from the site (owner-only —
+server-side per `templates/shared/CUSTOM_OPERATIONS.md`, or the dashboard). If the user asks for a
+donor account area, deploy the `members` vertical beside this one rather than shipping code that
+returns nothing for visitors.
+
+## Point the user to their dashboard
+
+Hand the owner these links — `{siteId}` is `siteId` in `wix.config.json` (the deploy JSON prints it as
+`dashboardUrl`).
+
+| page | `https://manage.wix.com/dashboard/{siteId}/` + |
+|---|---|
+| Donations (campaigns, settings) | `app/333b456e-dd48-4d6b-b32b-9fd48d74e163` (redirects to the app's own route) |
+| Orders — every donation is an eCom order | `ecom-platform/orders-list` |
+| 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
+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.
+
+## Caveats — verified against the SDK, not yet against a live site
+
+The shipped code guards each of these, so a refusal degrades instead of breaking; confirm them on the
+first real site and read the owning file if one bites.
+
+- **Visitor reads.** Whether an anonymous visitor token may query campaigns and read `/metrics` is
+  unverified. Metrics are caught per campaign: a refusal leaves `goal.raised` "" (the target still
+  shows) and `options.currency` "" (the button reads "Donate" without an amount; preset labels still
+  carry the API's own formatted amounts). If the campaign query itself is refused, the pages render
+  their empty state.
+- **Create Cart is the whole path (Cart V2).** `donationCheckoutUrl` creates one fresh cart with the
+  donation line (`cart.source.channelType: WEB`, the donor note as `cart.note`) and hands that cart's
+  id straight to the redirect session — the cart is the checkout, so there is no separate Create
+  Checkout call and nothing merges into a storefront visitor's current cart.
+- **Site currency.** Comes from the metrics response ("returns only the site's default currency");
+  On a campaign nobody has donated to yet the metrics carry no currency either, so the transports read the site's currency once from the eCommerce settings (BUSINESS_INFO); unknown → "".
+- **Reading the order on the thank-you page.** `GET /ecom/v1/orders/{id}` with the visitor's token is
+  unverified; any failure → `receipt` null and the page thanks without order facts.
+- **`orderId` spelling.** The redirect-session contract appends `orderId`; the Wix widget's own success
+  URL uses `orderid`. Both are read.
+- **Cover image update shape** (seed) — inferred from the SDK; a failed attach is reported, never fatal.
+- **App installation** (seed) — installing Donations through the installer API, and whether it
+  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.

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

@@ -0,0 +1,155 @@
+// The donate form for one campaign — wire as-is on the campaign page (and a home strip). It owns
+// the rules a rewritten form gets wrong: the frequency picker only when the campaign offers more
+// than one frequency, the preset amounts with the owner's impact text, "Other amount" only when
+// the owner enabled it (with the campaign's min/max in the messages), the cover-fee checkbox with
+// the computed 2.9% only when the owner asks, the note only when comments are enabled (with its
+// counter), the live "Donate $25 Monthly" label, "Redirecting…" while the hosted checkout starts,
+// errors shown after the first attempt, the failure inline. For a campaign that isn't accepting
+// 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 { useDonation, type UseDonationOptions } from "../../hooks/donations/useDonation";
+import type { CampaignDetail } from "../../wix/donations/types";
+
+export interface DonateFormProps {
+  campaign: CampaignDetail;
+  /** origin / return paths for the hosted flow — see donate.ts; omit for the defaults. */
+  options?: UseDonationOptions;
+  /** Rendered instead of the form when the campaign isn't accepting donations. */
+  children?: ReactNode;
+  className?: string;
+  buttonClassName?: string;
+}
+
+const choice = (selected: boolean) =>
+  `cursor-pointer rounded-md border px-4 py-3 text-sm transition-colors ${
+    selected ? "border-primary bg-primary text-primary-foreground" : "border-border bg-background text-foreground hover:bg-secondary"
+  }`;
+
+export default function DonateForm({
+  campaign,
+  options,
+  children,
+  className = "grid gap-6",
+  buttonClassName = "w-full rounded-control bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50",
+}: DonateFormProps) {
+  const d = useDonation(campaign, options);
+  const o = campaign.options;
+  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
+      className={className}
+      noValidate
+      onSubmit={(e) => {
+        e.preventDefault();
+        void d.donate().catch(() => {});
+      }}
+    >
+      {o.frequencies.length > 1 && (
+        <fieldset>
+          <legend className="eyebrow mb-2">How often</legend>
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" role="radiogroup">
+            {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)}>
+                {f.label}
+              </button>
+            ))}
+          </div>
+          {show("frequency") && <p className="mt-2 text-sm text-destructive" role="alert">{show("frequency")}</p>}
+        </fieldset>
+      )}
+
+      {(o.presets.length > 0 || o.customAmount.enabled) && (
+        <fieldset>
+          <legend className="eyebrow mb-2">Amount</legend>
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3" role="radiogroup">
+            {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)}>
+                  <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>
+              );
+            })}
+            {o.customAmount.enabled && o.presets.length > 0 && (
+              <button type="button" role="radio" aria-checked={d.customMode} className={choice(d.customMode)} onClick={() => d.selectCustom()}>
+                Other amount
+              </button>
+            )}
+          </div>
+          {show("amount") && <p 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">
+                Amount{o.currency ? ` in ${o.currency}` : ""}
+              </label>
+              <div className="flex items-center gap-2 rounded-md border border-border bg-background px-3">
+                {o.currency && <span className="text-sm text-muted-foreground">{o.currency}</span>}
+                <input
+                  id={`${fid}-amount`}
+                  inputMode="decimal"
+                  autoComplete="off"
+                  className="w-full bg-transparent py-3 text-base text-foreground outline-none"
+                  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")}
+                />
+              </div>
+              {(o.customAmount.minLabel || o.customAmount.maxLabel) && !show("customAmount") && (
+                <p 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>}
+            </div>
+          )}
+        </fieldset>
+      )}
+
+      {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)} />
+          <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>}
+          </span>
+        </label>
+      )}
+
+      {o.commentsEnabled && (
+        <div>
+          <label htmlFor={`${fid}-note`} className="eyebrow mb-2 block">
+            Leave a note <span className="font-normal normal-case tracking-normal">(optional)</span>
+          </label>
+          <textarea
+            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"
+            value={d.note}
+            onChange={(e) => d.setNote(e.target.value)}
+          />
+          <p 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>}
+        </div>
+      )}
+
+      <div className="grid gap-2">
+        <button type="submit" disabled={d.submitting} aria-busy={d.submitting} className={buttonClassName}>
+          {d.submitting ? "Redirecting…" : d.buttonLabel}
+        </button>
+        {d.error && <p className="text-sm text-destructive" role="alert">{d.error}</p>}
+        <p className="text-center text-xs text-muted-foreground">Secure payment on the next step.</p>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,46 @@
+// The hosted checkout's thank-you island — wire as-is on /donate/thank-you (mount client:only: it
+// reads the browser URL). It owns the honesty rules: landing here with `?orderId=` is Wix's
+// success redirect, so it thanks the donor; the order's facts (name, amount, order number, paid or
+// pending) appear only when the order could be read; a direct visit with no order id gets a neutral
+// thank-you and a link back — never an invented receipt, never "paid" unless the order says PAID.
+import { useDonationReceipt } from "../../hooks/donations/useDonationReceipt";
+
+export interface DonationReceiptProps {
+  /** Where "Back to campaigns" points. */
+  campaignsHref?: string;
+  className?: string;
+}
+
+export default function DonationReceipt({ campaignsHref = "/donate", className = "mx-auto max-w-lg py-16 text-center" }: DonationReceiptProps) {
+  const { orderId, loading, receipt } = useDonationReceipt();
+
+  if (!orderId) {
+    return (
+      <div className={className}>
+        <h1 className="text-2xl font-semibold tracking-tight">Thank you for your support</h1>
+        <a href={campaignsHref} className="mt-6 inline-block text-sm text-foreground underline">
+          See the campaigns
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} aria-busy={loading}>
+      {receipt?.orderNumber && <p className="eyebrow">Order {receipt.orderNumber}</p>}
+      <h1 className="mt-2 text-2xl font-semibold tracking-tight">
+        {receipt?.donorFirstName ? `Thank you, ${receipt.donorFirstName}` : "Thank you for your donation"}
+      </h1>
+      {receipt && (
+        <p className="mt-3 text-sm text-muted-foreground">
+          {receipt.amount ? `Your donation of ${receipt.amount} ` : "Your donation "}
+          {receipt.paid ? "has been received." : "is being processed — payment is pending."}
+        </p>
+      )}
+      {!receipt && !loading && <p className="mt-3 text-sm text-muted-foreground">Your donation has been submitted.</p>}
+      <a href={campaignsHref} className="mt-6 inline-block text-sm text-muted-foreground underline">
+        Back to campaigns
+      </a>
+    </div>
+  );
+}