@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-vibe-headless/references/pricing-plans/INSTRUCTIONS.md

@@ -1,127 +1,250 @@
+# Wix Pricing Plans — ready-made client
 
-# Wix Pricing Plans Skill
+The Plans & Pricing client is **shipped as real files**, not snippets to regenerate. It's a complete
+plans table + plan detail + members-only hosted checkout + "my plans" area, styled with your app's
+design tokens (base44's `src/index.css` — the shadcn palette the design phase already set). Copy it
+into the app and wire the routes — you generate almost none of the plans code (the destructure
+shapes, the price/billing-cycle field paths, the hosted checkout redirect, the anonymous `[]` case
+all ship and are correct).
 
-> **Source files (in this skill):** the shared transport `references/shared/wix-client.js` and this vertical's `references/pricing-plans/wix-pricing-plans.js`. Copy **both** into your app's `src/rest/` side by side — the helper does `import { wixApiRequest } from "./wix-client.js"`, so they must land in the same folder.
+Talks to Wix directly over the public `WIX_CLIENT_ID` (anonymous visitor tokens). Never mock plans;
+never hand-build a `/checkout` or purchase URL — purchasing always goes through the Wix-hosted
+**redirect-session** (which also handles member login/signup and payment).
 
-Builds a real, client-only Wix pricing-plans / membership front end. The browser talks to Wix
-directly over a public `WIX_CLIENT_ID`. Never mock plans; never hand-build a `/checkout` or
-purchase URL — purchasing always goes through the Wix-hosted **redirect-session** (which also
-handles member login and payment).
+## Prerequisites
+- The site's **Wix Pricing Plans** app is the read/checkout target. It's installed and seeded
+  separately (see **Seeding** below), in parallel with this build — so it may have no plans at build
+  time; the client renders the shipped empty state until plans land.
+- The public headless **`WIX_CLIENT_ID`** from your prompt (buyer-facing, safe to hardcode/commit).
+- **Purchasing is members-only, via Wix-hosted checkout.** The hosted flow handles member
+  login/signup + the order form + payment, then returns to your site. The deployed app domain must
+  be allow-listed on the OAuth client for that return to work — a **separate Wix setup flow the user
+  completes later**, out of scope here. If the return fails before that setup is done, that's
+  expected; flag it and continue.
 
-## When to use
-- User wants a "Plans & Pricing", membership, or subscription page on a Wix site.
-- User asks to "connect Wix pricing plans" or sell memberships / subscriptions / paid plans.
-- Replacing placeholder/mock plans with live Wix data.
-- Adding a plan detail page, a buy/subscribe button, or a "my plans" area over existing plans.
+## STEP 1 — The client is already in `src/`
+The install step (base44.md STEP 1) deployed the whole Plans & Pricing UI client + REST scaffolds
+into `src/` (imports use the `@/` alias → `src/`). Here's every file and what it is — **this is your
+map, so you don't need to open them:**
 
-## Prerequisites
-1. A Wix site with **Pricing Plans installed and at least one plan created** (this skill does
-   NOT provision — it's read-only over the plans the merchant added in the dashboard).
-2. The site's public headless **`WIX_CLIENT_ID`**, provided in the handoff prompt (the Wix
-   Business Manager surfaces a copyable prompt with the id filled in — see the router `SKILL.md`). Paste
-   it into `src/rest/wix-client.js` in place of the placeholder. It is a buyer-facing credential
-   (it only mints anonymous visitor tokens), **not** a secret, so hardcoding/committing it is fine.
-3. **Purchasing a plan is members-only and uses Wix-hosted checkout.** The hosted flow handles
-   member login/signup + the order form + payment, then returns to your site. The deployed app
-   domain must be allow-listed on the OAuth client for that return to work — this is a **separate
-   Wix setup flow the user completes later**, out of this skill's scope. If the return fails
-   before that setup is done, that's expected; flag it and continue.
-4. To actually charge for paid plans, the site needs a payment method connected and (where
-   applicable) tax/business-address configured in the Wix dashboard. Free plans work without this.
-
-## The API (copy as-is; do not re-derive it)
-This skill ships only the REST layer — no UI components. Build the page's UI however the project
-wants; wire it to these two snippets. Copy them into the app (e.g. `src/api/`) and only adjust
-import paths:
-- `src/rest/wix-client.js` — visitor-token mint/refresh + transport. Set `WIX_CLIENT_ID` to the
-  id from the prompt (replace the `<YOUR-CLIENT-ID>` placeholder). The visitor refresh token is
-  persisted to localStorage; after a hosted checkout the same identity returns as a logged-in
-  member. Do not re-mint anonymously per load.
-- `src/rest/wix-pricing-plans.js` — exports:
-  - **Plans:** `queryPlans`, `getPlanById`, `getPlanBySlug`
-  - **Purchase:** `checkout`
-  - **Member:** `getMyPlanOrders`
-
-The Plan and Order shapes are documented as JSDoc comments at the top of `wix-pricing-plans.js`.
-Read them before building the UI — pricing has several models (recurring subscription,
-single-payment-for-duration, single-payment-unlimited, free, plus free trials) and the JSDoc
-shows exactly how to read price, cycle, and trial for display.
-
-## How to wire it (UI is the project's choice)
-- **Plans grid** — `queryPlans()` for the listing (PUBLIC plans only); pass `nextCursor` back as
-  `cursor` to load the next page. For each plan render `name`, `description`, `perks[].description`
-  as feature bullets, and the price from `pricingVariants[0]` (see the JSDoc "Reading the price"
-  notes: `pricingStrategies[0].flatRate.amount` + plan `currency`, plus `billingCycle` for
-  recurring and `freeTrialDays` for trials). Show a "Subscribe"/"Buy" button only when
-  `plan.buyable` is true.
-- **Plan detail** — `getPlanBySlug(slug)` keyed off the URL slug (or `getPlanById(id)`); returns
-  null on miss — show a not-found state, never invent a plan. Render perks, the full price/billing
-  summary, free-trial note, and `termsAndConditions` if present.
-- **Purchase** — `window.location.href = await checkout(planId, { thankYouPageUrl })`. This
-  redirects to Wix-hosted checkout, which logs the member in (or signs them up), collects the
-  order form, and takes payment. On success Wix returns to `thankYouPageUrl` with a
-  `?planOrderId=<GUID>` query param (and `wixMemberLoggedIn`); on abandon/interrupt it returns to
-  `postFlowUrl` (defaults to the current page). Never create the order or build the URL yourself.
-- **My plans / confirmation** — `getMyPlanOrders()` for the logged-in member's purchases; filter
-  with `{ orderStatuses: ["ACTIVE"] }` for current memberships. After returning from checkout,
-  re-fetch (e.g. on mount + `visibilitychange`, or when `planOrderId` is in the URL) to show the
-  new order. Returns `[]` for anonymous visitors — show a "log in to see your plans" state, and wire
-  that log-in via the **members** vertical (`references/members/`) so they can sign in on your own UI.
-- **Empty state** — if `queryPlans()` returns no plans, show an empty state telling the user to
-  create plans in their Wix dashboard. Never invent plans.
-
-## Hard rules (do not violate)
-- ✅ Purchase ONLY via `checkout()` (`/headless/v1/redirect-session` with `paidPlansCheckout`),
-  then redirect to `redirectSession.fullUrl`.
-- ❌ Never hand-build a checkout, purchase, or `/plans-checkout` URL; never call create-order
-  directly from the client to "skip" the hosted flow.
-- ❌ Never mock plans — render live Wix data or the empty state.
-- ❌ Never invent perks, prices, trials, testimonials, or member counts. Render only what the
-  plan object returns; empty perks → no feature list.
-- ✅ Set `WIX_CLIENT_ID` from the prompt's value (public client id — safe to hardcode).
-- ✅ Treat plan objects as display-only — never compute the final charge; Wix settles price, tax,
-  proration, and schedule during hosted checkout.
-- ✅ Show the buy button only when `plan.buyable` is true; otherwise the plan is merchant-assigned.
-- The engine fails loudly on purpose: `checkout()` throws if it can't create the redirect session.
-  A green path means it really reached Wix-hosted checkout — don't swallow these.
-
-## Beyond the snippets
-The snippets cover the common plans paths. If you hit a use case they don't cover, make the call
-yourself with `wixApiRequest` — but look up the exact endpoint, HTTP method, and request body in
-the **official Wix API reference** first; never guess:
-- Pricing Plans API reference: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans.md
-- Orders (cancel / pause / resume a member's order, price preview): https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders.md
-- Headless redirect session (login, logout, other checkouts): https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-
-Common genuine gaps and where to look:
-- **Cancel / pause / resume** a member's subscription → Orders API (`request-cancellation`,
-  `pause-order`, `resume-order`). Gate on `plan.buyerCanCancel`.
-- **Member login / logout** outside of a purchase → use the **members** vertical
-  (`references/members/INSTRUCTIONS.md`) for *custom* login (email+password / Google / Facebook / SSO)
-  on your own UI — so a member can log in *before* subscribing and see "my plans" without going through
-  a purchase. Pair it with this vertical whenever plans need a real account surface.
-- **Coupons / custom start date** at purchase → covered by the hosted checkout; for a fully
-  custom flow see Create Online Order in the Orders reference.
-
-Keep the snippets as the default for everything they already do; reach for the API reference only
-for the gap.
+| file | what it is |
+|---|---|
+| `hooks/usePlans.js` | plans-listing data — first page, cursor paging, `subscribe(plan)` checkout |
+| `hooks/usePlanDetail.js` | plan-detail data — plan-by-slug + `notFound` + `subscribe()` checkout |
+| `hooks/useMyPlans.js` | member's orders + auto re-sync on return from checkout |
+| `components/PlanPrice.jsx` | price label — reads amount / cycle / free-trial (display only) |
+| `components/PlanCard.jsx` | plan card — name, description, price, perks, Subscribe (when `buyable`) |
+| `components/PlanGrid.jsx` | responsive plans grid + empty state |
+| `components/OrderCard.jsx` | one member order row for the "my plans" list |
+| `components/WixManageBanner.jsx` | preview-only manage banner — drop it into your Layout (STEP 4) |
+| `pages/Plans.jsx` | the plans-table route (`/plans`) — grid + paging + checkout |
+| `pages/PlanDetail.jsx` | the plan-detail route (`/plans/:slug`) — perks, terms, checkout |
+| `pages/MyPlans.jsx` | the member's memberships + post-checkout confirmation (`/my-plans`) |
+| `rest/wix-config.js` | **you set the ids here** (STEP 2) |
+| `rest/wix-client.js` + `rest/wix-pricing-plans.js` | REST transport + plans/orders/checkout helpers |
+
+They're already in place — go **straight to theming + wiring**, nothing to verify first. **Don't
+`read_file` the shipped page/component/hook source to inspect it** — the table above says what each
+is and every field shape you need is in the snippets below. Read a shipped file's source **only** on
+a real fallback — a runtime error, or a field the snippets don't cover (see "Fallback only" at the
+end). (Files missing? the install's `deploy` result lists what it wrote; re-run install, or copy
+`references/pricing-plans/app/` → `src/`.)
+
+## STEP 2 — Credentials
+Write `src/rest/wix-config.js` with your `WIX_CLIENT_ID` and `WIX_METASITE_ID` from the prompt — the
+one place both ids live.
+
+## STEP 3 — Theme (nothing to style on the shipped components)
+The shipped components carry **no palette of their own** — they render from base44's design tokens
+in `src/index.css` (`:root`/`.dark`: `--background`, `--foreground`, `--card`, `--primary`,
+`--muted`, `--border`, `--radius`, `--font-*`) via shadcn Tailwind classes (`bg-card`,
+`text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `rounded-lg`,
+`font-display`). Those tokens are **already set to the brand by the design phase**, so the shipped
+pages are themed with zero work here. To adjust the palette, edit `index.css` (`:root` **and**
+`.dark`) — the base44 way; **never add a parallel theme file (e.g. a `theme.css`) or restyle the
+shipped JSX.** Build the Home/Header you add (STEP 4) from the **same** base44 tokens/classes so it
+matches automatically. A dark brand is just base44's dark palette in `index.css` — no per-component work.
+
+## STEP 4 — Wire routes + provider (surgical `find_replace` on `src/App.jsx`, never a rewrite)
+**No file reads needed to wire this.** Every shipped page and `WixManageBanner` is a default export that takes **no props** — wire them exactly as the snippet shows; nothing in those files needs looking up.
+`App.jsx` carries required platform auth scaffolding (`AuthProvider`/`useAuth`) — edit it in, don't
+replace it. Pricing Plans needs **no** cross-page provider (checkout is a redirect, not client
+state) — so unlike the storefront there's no `<CartProvider>` to wrap.
+- Put your **header + footer in a `Layout`** that renders `<Outlet/>` between them, and nest every
+  route under one pathless `<Route element={<Layout/>}>`. Your brand chrome then wraps **every**
+  page — including the shipped `Plans` / `PlanDetail` / `MyPlans` — so you **never edit the shipped
+  pages to add a header/footer** (they render inside `<Outlet/>` as-is).
+- **Pin the top chrome as one fixed block.** Put `<WixManageBanner/>` (shipped, preview-only) **above**
+  your `<Header/>` inside a single `position:fixed` top region — the header itself is plain in-flow
+  markup, the region owns the fixing — so banner + header ride together (no scroll drift/gap). Pad
+  the content by the region's **ResizeObserver-measured** height so it clears the chrome and
+  self-corrects when the banner is dismissed.
+- Routes under the Layout: `/plans` → `Plans`, `/plans/:slug` → `PlanDetail`, `/my-plans` →
+  `MyPlans` (all shipped, as-is). **You add `/` → your own Home** page.
+
+```jsx
+import { useRef, useState, useEffect } from "react";
+import { Routes, Route, Outlet } from "react-router-dom";
+import WixManageBanner from "@/components/WixManageBanner";   // shipped, preview-only · default export, no props
+import Plans from "@/pages/Plans";                     // shipped · default export, no props
+import PlanDetail from "@/pages/PlanDetail";           // shipped · default export, no props
+import MyPlans from "@/pages/MyPlans";                 // shipped · default export, no props
+import Home from "@/pages/Home";       // YOU build
+import Header from "@/components/Header";   // YOU build — plain in-flow markup, NOT position:fixed
+import Footer from "@/components/Footer";   // YOU build
+
+function Layout() {
+  const topRef = useRef(null);
+  const [offset, setOffset] = useState(0);
+  useEffect(() => {                                  // measure the fixed region → pad content below it
+    const ro = new ResizeObserver(() => setOffset(topRef.current?.offsetHeight ?? 0));
+    if (topRef.current) ro.observe(topRef.current);
+    return () => ro.disconnect();
+  }, []);
+  return (<>
+    <div ref={topRef} style={{ position: "fixed", top: 0, left: 0, right: 0, zIndex: 50 }}>
+      <WixManageBanner />                    {/* null on the published site / when dismissed */}
+      <Header />                             {/* your brand header, in-flow inside this fixed block */}
+    </div>
+    <div style={{ paddingTop: offset }}>     {/* clears the chrome; shrinks when the banner is dismissed */}
+      <Outlet />                             {/* shipped Plans/PlanDetail/MyPlans render here, untouched */}
+      <Footer />
+    </div>
+  </>);
+}
+
+<Routes>
+  <Route element={<Layout />}>                                {/* chrome wraps all */}
+    <Route path="/" element={<Home />} />                      {/* yours */}
+    <Route path="/plans" element={<Plans />} />                {/* shipped, as-is */}
+    <Route path="/plans/:slug" element={<PlanDetail />} />     {/* shipped, as-is */}
+    <Route path="/my-plans" element={<MyPlans />} />           {/* shipped, as-is */}
+  </Route>
+</Routes>
+```
+
+## What you build (not shipped)
+The **home / landing page**, the **`Header`** and a **`Footer`** — the two you drop into the
+`Layout` (STEP 4) so they wrap every route — plus the overall brand story, styled with the same
+base44 tokens/classes. **Compose the shipped pieces** — a "featured plans" strip is just `queryPlans` +
+the shipped `PlanGrid`; the nav is links to `/plans` and `/my-plans`:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Link } from "react-router-dom";
+import { queryPlans, checkout } from "@/rest/wix-pricing-plans";
+import PlanGrid from "@/components/PlanGrid";
+
+// Responsive header: choose ONE branch with a state flag (mount each nav item once).
+// Do NOT render a desktop nav AND a mobile nav toggled by `hidden md:flex` / `md:hidden`:
+// these navs are inline-styled, and an inline `display` beats a Tailwind class, so `hidden`
+// never applies — BOTH branches render. One branch = one nav.
+export function Header() {
+  const [mobile, setMobile] = useState(() => window.innerWidth < 768);
+  useEffect(() => {
+    const onResize = () => setMobile(window.innerWidth < 768);
+    window.addEventListener("resize", onResize);            // keep it reactive to viewport changes
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+  return (
+    <nav style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+      {/* brand/logo */}
+      {mobile
+        ? <YourMenu />                                       // your hamburger + the same links
+        : <div style={{ display: "flex", gap: 24 }}><Link to="/plans">Plans</Link><Link to="/my-plans">My plans</Link></div>}
+    </nav>
+  );
+}
+
+export function Featured() {                                // on your home page
+  const [plans, setPlans] = useState([]);
+  // NB: queryPlans returns { plans, nextCursor } — destructure the array.
+  useEffect(() => { queryPlans({ limit: 3 }).then(({ plans }) => setPlans(plans)); }, []);
+  const subscribe = async (plan) =>
+    { window.location.href = await checkout(plan.id, { thankYouPageUrl: `${window.location.origin}/my-plans` }); };
+  return <PlanGrid plans={plans} onSubscribe={subscribe} empty="Plans coming soon." />;
+}
+```
+Everything reads base44's design tokens (`index.css`), so your home/nav match the shipped pages automatically.
+
+**Editing a component and the change doesn't show? It's the preview, not your code.** The dev
+preview can serve a stale module after a write. Before diagnosing a visual bug you just "fixed", do
+a fresh full navigate/reload of the preview and re-check — don't keep rewriting correct code against
+a stale render.
+
+## Using the client from your own UI
+
+```jsx
+// Every list helper returns an object — destructure it (a bare `.map` on the return throws):
+const { plans, nextCursor } = await queryPlans({ limit: 24 });   // PUBLIC plans only
+// Page: pass nextCursor back as `cursor`.
+const { plans: more } = await queryPlans({ cursor: nextCursor });
+
+// Price is DISPLAY-ONLY — never compute a final charge (Wix settles price, tax, schedule at checkout):
+const v = plan.pricingVariants[0];
+const amount = v.pricingStrategies[0].flatRate.amount;   // decimal STRING e.g. "20.00"; "0" = free (a string — don't === 0)
+const cycle  = v.billingTerms.billingCycle;              // { period:"DAY"|"WEEK"|"MONTH"|"YEAR", count } — recurring only
+const trial  = v.freeTrialDays;                          // free-trial length
+// Pair `amount` with `plan.currency` (ISO-4217, e.g. "USD"). Show the buy button only when plan.buyable.
+
+// Purchase — members-only, hosted; redirect to the returned URL, never hand-build it:
+window.location.href = await checkout(plan.id, { thankYouPageUrl: `${window.location.origin}/my-plans` });
+// On success Wix returns to thankYouPageUrl with ?planOrderId=<GUID> (+ wixMemberLoggedIn); on abandon → postFlowUrl.
+
+// Member's memberships — resolves to [] for anonymous visitors (never throws):
+const orders = await getMyPlanOrders({ orderStatuses: ["ACTIVE"] });   // omit orderStatuses for all
+
+// Plan image: plan.image is a WixMedia object { id, width, height, altText } with NO .url. The shipped
+// cards render text only to avoid this. To show it, resolve the WixMedia `id` to a URL (wix-docs),
+// or omit — never <img src={plan.image}> / <img src={plan.image.url}> (undefined / [object Object]).
+```
+
+## Extending the client
+Beyond the shipped pages: **cancel / pause / resume** a member's subscription → Orders API
+(`request-cancellation`, `pause-order`, `resume-order`); gate on `plan.buyerCanCancel`. **Custom
+member login / logout** (so a member can log in *before* subscribing and see "my plans" without a
+purchase) → pair the **members** vertical (`references/members/INSTRUCTIONS.md`). For anything the
+snippets don't cover, make the call yourself with `wixApiRequest` — but look up the exact endpoint,
+method, and body first (never guess):
+- Pricing Plans: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans.md
+- Orders: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders.md
+- Headless redirect session: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+
+Fallback only — when you hit an error or need something not shown here: read the relevant shipped
+file under `src/`, or look it up via the **`wix-docs`** skill.
+
+## Hard rules
+- Set `WIX_CLIENT_ID` (STEP 2) — not the placeholder.
+- Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
+- Header/footer live in a `Layout` around `<Outlet/>` (STEP 4) — never edit the shipped
+  `Plans`/`PlanDetail`/`MyPlans` to add chrome.
+- The Layout's fixed top region owns positioning: `<WixManageBanner/>` above `<Header/>`; your
+  `Header` is plain in-flow markup (not `position:fixed`).
+- Purchase goes through the shipped `checkout()` (redirect-session) — never a hand-built URL.
+- Treat plan objects as display-only — show the buy button only when `plan.buyable`; never compute
+  the final charge. Never invent perks, prices, trials, testimonials, or member counts.
+- Render live Wix data or the shipped empty state — never mock plans.
 
 ## Point the user to their dashboard
-In some cases, users need to access the Wix dashboard in order to edit the pricing plans content for their site. To facilitate this, provide the user with deep links directly to the relevant dashboard pages. For pricing plans data those pages are:
-- **Pricing Plans** — `https://manage.wix.com/dashboard/{metaSiteId}/pricing-plans` (`Dashboard → Pricing Plans`) → **+ Create Plan** (set the name, pricing model, perks, and connect the plan to the content/services it unlocks)
+Provide deep links so the owner can edit content (substitute the site's `metaSiteId`):
+- **Pricing Plans** — `https://manage.wix.com/dashboard/{metaSiteId}/pricing-plans` (`Dashboard →
+  Pricing Plans`) → **+ Create Plan** (set the name, pricing model, perks, and connect the plan to
+  the content/services it unlocks)
 
-Substitute the site's `metaSiteId` to complete the links (you have it from the handoff / `ListWixSites`). Include the in-dashboard navigation as a fallback.
+## Seeding
+Seed plans per `seed/SEED.md` (the build-time setup module) — separate from this client build; run
+in parallel.
 
-## Verification checklist (before declaring done)
-- [ ] `WIX_CLIENT_ID` set to the prompt's value (not the `<YOUR-CLIENT-ID>` placeholder)
+## Verify (before declaring done)
+- [ ] Client files copied into `src/`; `WIX_CLIENT_ID` set (not the placeholder).
+- [ ] Brand palette lives in `index.css` (`:root`/`.dark`); no parallel theme file; shipped components/pages not restyled or rewritten.
+- [ ] Opened the vertical's data route(s) (not just the home page) and confirmed the shipped
+      components render themed (surface, text, brand) with images.
+- [ ] `Layout` (fixed `<WixManageBanner/>` + `<Header/>` region, then `<Outlet/>` + Footer) wraps
+      all routes; shipped `Plans`/`PlanDetail`/`MyPlans` untouched; content clears the fixed chrome.
 - [ ] Plans list renders live data; price, billing cycle, and free trial read correctly across
-      pricing models (recurring, single-payment, free)
-- [ ] Plan detail loads by slug and shows a not-found state on a bad slug
-- [ ] Buy button shown only for `buyable` plans
-- [ ] Purchase redirects via redirect-session `fullUrl` (no hand-built URL) and reaches
-      Wix-hosted login + payment
-- [ ] On return, the new order appears via `getMyPlanOrders()` (and a "log in" state shows for
-      anonymous visitors)
-- [ ] Empty state shown when `queryPlans()` returns no plans
-- [ ] No mock plans, perks, or prices anywhere
-- [ ] Told the user at least once that they can continue setting up their plans in the dashboard and provided deep links.
+      pricing models (recurring, single-payment, free); buy button only for `buyable` plans.
+- [ ] Plan detail loads by slug and shows a not-found state on a bad slug.
+- [ ] Purchase redirects via the redirect-session `fullUrl` (no hand-built URL) and reaches
+      Wix-hosted login + payment; on return the new order appears on `/my-plans`.
+- [ ] Empty catalog shows the shipped empty state; no mock plans anywhere.

package/skills/wix-vibe-headless/references/pricing-plans/app/components/OrderCard.jsx

@@ -0,0 +1,35 @@
+// Member plan-order row — pure UI for the "My plans" screen. Renders only fields the Order object
+// actually returns (planName, status, start/end dates); for anything else (amount paid, next-billing)
+// look it up in the Orders API reference (wix-docs) — never invent it. Styled with base44 design
+// tokens (shadcn Tailwind classes).
+
+// Each status carries its OWN text colour: a shared `text-primary-foreground` over a varying
+// background is unreadable the moment the two tokens are close in value — on the default light
+// palette --primary-foreground (98%) over --muted (96.1%) is white on white, so PAUSED and ENDED
+// vanished. A background token and its foreground token always travel together.
+const STATUS_STYLE = {
+  ACTIVE: "bg-primary text-primary-foreground",
+  PAUSED: "bg-muted text-foreground",
+  ENDED: "bg-muted text-foreground",
+  CANCELED: "bg-destructive text-destructive-foreground",
+};
+const STATUS_FALLBACK = "bg-muted text-foreground";
+
+export default function OrderCard({ order }) {
+  return (
+    <li className="list-none flex flex-wrap items-center gap-3 bg-card text-foreground border border-border rounded-lg shadow-sm p-4">
+      <span className="font-display font-semibold flex-1">{order.planName}</span>
+      <span className={`text-[13px] font-semibold px-2.5 py-0.5 rounded-full ${STATUS_STYLE[order.status] || STATUS_FALLBACK}`}>{order.status}</span>
+      {order.startDate && (
+        <span className="text-muted-foreground text-[13px]">
+          from {new Date(order.startDate).toLocaleDateString()}
+        </span>
+      )}
+      {order.endDate && (
+        <span className="text-muted-foreground text-[13px]">
+          until {new Date(order.endDate).toLocaleDateString()}
+        </span>
+      )}
+    </li>
+  );
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/components/PlanCard.jsx

@@ -0,0 +1,48 @@
+// Plan card — pure UI. Styled with base44 design tokens (shadcn Tailwind classes) — re-skin via the
+// app's design tokens (src/index.css :root/.dark), not this JSX. Renders name, description, price,
+// perks as feature bullets, and a Subscribe button ONLY when plan.buyable is true (otherwise the
+// plan is merchant-assigned). The card links to the plan detail route by slug. `onSubscribe(plan)`
+// runs the hosted checkout.
+//
+// plan.image is a WixMedia object { id, width, height, altText } with NO .url — its id must be
+// resolved to a URL before it can render. Rendering plan text only here avoids that trap; see
+// INSTRUCTIONS ("Plan image") for the resolve-or-omit fallback if you want the image.
+import { Link } from "react-router-dom";
+import PlanPrice from "./PlanPrice";
+
+export default function PlanCard({ plan, onSubscribe, featured = false }) {
+  return (
+    <div className={`flex flex-col gap-4 bg-card text-foreground border ${featured ? "border-primary" : "border-border"} rounded-lg overflow-hidden shadow-sm p-6`}>
+      <div>
+        <h3 className="m-0 mb-1 font-display text-[20px] font-bold">
+          {plan.name}
+        </h3>
+        {plan.description && (
+          <p className="m-0 text-muted-foreground leading-[1.5]">{plan.description}</p>
+        )}
+      </div>
+
+      <PlanPrice plan={plan} />
+
+      {(plan.perks || []).length > 0 && (
+        <ul className="m-0 p-0 list-none flex flex-col gap-2">
+          {plan.perks.map((perk) => (
+            <li key={perk.id} className="flex gap-2 text-foreground leading-[1.4]">
+              <span className="text-primary" aria-hidden>✓</span>
+              <span>{perk.description}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div className="mt-auto flex flex-col gap-2">
+        {plan.buyable && (
+          <button onClick={() => onSubscribe?.(plan)}
+            className="py-3 px-6 cursor-pointer bg-primary text-primary-foreground rounded-sm text-[15px] font-semibold">Subscribe</button>
+        )}
+        <Link to={`/plans/${plan.slug}`}
+          className="text-center py-2.5 px-6 no-underline text-foreground border border-border rounded-sm text-sm font-semibold">View details</Link>
+      </div>
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/components/PlanGrid.jsx

@@ -0,0 +1,16 @@
+// Responsive plans grid + empty state. Styled with base44 design tokens (shadcn Tailwind classes).
+// Renders the shipped empty state when there are no plans — never invent plans.
+import PlanCard from "./PlanCard";
+
+export default function PlanGrid({ plans, onSubscribe, empty = "No plans yet." }) {
+  if (!plans?.length) {
+    return (
+      <p className="text-muted-foreground p-4 text-center">{empty}</p>
+    );
+  }
+  return (
+    <div className="grid gap-4 items-stretch [grid-template-columns:repeat(auto-fill,minmax(280px,1fr))]">
+      {plans.map((plan) => <PlanCard key={plan.id} plan={plan} onSubscribe={onSubscribe} />)}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/components/PlanPrice.jsx

@@ -0,0 +1,35 @@
+// Plan price label — display only. The price is a decimal STRING at
+// pricingVariants[0].pricingStrategies[0].flatRate.amount ("0" = free); the recurring cycle is
+// nested at billingTerms.billingCycle; free-trial length at pricingVariants[0].freeTrialDays. These
+// exact paths are load-bearing — keep them. Never compute a final charge (Wix settles price, tax,
+// and schedule at hosted checkout). Styled with base44 design tokens (shadcn Tailwind classes).
+
+function readPrice(plan) {
+  const v = plan?.pricingVariants?.[0];
+  const amount = v?.pricingStrategies?.[0]?.flatRate?.amount;   // decimal STRING e.g. "20.00"; "0" = free
+  if (amount == null) return null;
+  const cycle = v?.billingTerms?.billingCycle;                  // { period, count } for recurring; absent otherwise
+  return { amount, isFree: amount === "0", cycle, freeTrialDays: v?.freeTrialDays };
+}
+
+export default function PlanPrice({ plan }) {
+  const p = readPrice(plan);
+  if (!p) return null;
+  if (p.isFree) {
+    return <span className="font-display text-[28px] font-bold">Free</span>;
+  }
+  const per = p.cycle ? ` / ${p.cycle.count} ${p.cycle.period.toLowerCase()}` : "";   // e.g. "/ 1 month"
+  return (
+    <span>
+      <span className="font-display text-[28px] font-bold">
+        {p.amount} {plan.currency}
+      </span>
+      {per && <span className="text-muted-foreground text-sm">{per}</span>}
+      {p.freeTrialDays ? (
+        <span className="block text-primary text-[13px] mt-1">
+          {p.freeTrialDays}-day free trial
+        </span>
+      ) : null}
+    </span>
+  );
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/hooks/useMyPlans.js

@@ -0,0 +1,25 @@
+// useMyPlans — "My plans" logic, no markup: load the logged-in member's orders and re-sync on
+// visibilitychange so a plan bought via hosted checkout shows up on return. getMyPlanOrders()
+// resolves to an ARRAY ([] for anonymous visitors — never throws), so the view can show a
+// "log in to see your plans" state. Keep the visibilitychange re-sync — it is load-bearing.
+import { useState, useEffect, useCallback } from "react";
+import { getMyPlanOrders } from "@/rest/wix-pricing-plans";
+
+export function useMyPlans({ orderStatuses = ["ACTIVE"] } = {}) {
+  const [orders, setOrders] = useState([]);
+  const [loaded, setLoaded] = useState(false);
+
+  const refresh = useCallback(() => {
+    // [] for anonymous visitors (no member context) — never throws.
+    getMyPlanOrders({ orderStatuses }).then((o) => { setOrders(o); setLoaded(true); });
+  }, [orderStatuses]);
+
+  useEffect(() => {                                   // load once + re-sync on return from hosted checkout
+    refresh();
+    const onVisible = () => document.visibilityState === "visible" && refresh();
+    document.addEventListener("visibilitychange", onVisible);
+    return () => document.removeEventListener("visibilitychange", onVisible);
+  }, [refresh]);
+
+  return { orders, loaded, refresh };
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/hooks/usePlanDetail.js

@@ -0,0 +1,28 @@
+// usePlanDetail — plan-detail logic, no markup: load a single PUBLIC plan by its URL slug, expose a
+// notFound flag (getPlanBySlug returns null on a miss — show a not-found state, never invent a
+// plan), and start the members-only hosted checkout. Mirrors the storefront's useProductDetail.
+// The detail page only renders what this returns.
+import { useState, useEffect } from "react";
+import { getPlanBySlug, checkout } from "@/rest/wix-pricing-plans";
+
+export function usePlanDetail(slug) {
+  const [plan, setPlan] = useState(null);
+  const [notFound, setNotFound] = useState(false);
+
+  useEffect(() => {
+    setPlan(null);
+    setNotFound(false);
+    getPlanBySlug(slug).then((p) => {
+      if (!p) return setNotFound(true);
+      setPlan(p);
+    });
+  }, [slug]);
+
+  // members-only, Wix-hosted checkout; on success Wix returns to thankYouPageUrl with ?planOrderId=<GUID>
+  async function subscribe() {
+    if (!plan) return;
+    window.location.href = await checkout(plan.id, { thankYouPageUrl: `${window.location.origin}/my-plans` });
+  }
+
+  return { plan, notFound, subscribe };
+}