@wix/agent-skills 1.0.0

package/skills/wix-headless/templates/ecom/components-ecom.css

@@ -0,0 +1,215 @@
+/* src/styles/components-ecom.css
+ *
+ * Ecom-pack component CSS. Owned by the ecom Phase 3 components agent.
+ *
+ * This file is the SINGLE source of truth for ecom-component classes.
+ * The designer's global.css does NOT publish .cart-summary, .cart-total,
+ * .cart-empty, or .checkout-btn — those all live here. See
+ * references/shared/STYLING.md § "Component-specific CSS is owned by the
+ * component, not the designer".
+ *
+ * Class groups in this file:
+ * - .cart-summary / .cart-total / .cart-empty / .checkout-btn → /cart page summary panel and empty state
+ * - .cart-item / .cart-item-* / .qty-* → CartView.tsx line items
+ * - .cart-discount / .cart-applied-discounts → CartView.tsx discount rows
+ * - .cart-badge / .cart-badge-* → CartBadge.tsx (mounted in Navigation)
+ *
+ * Tailwind v4 requires @reference in non-entrypoint CSS files that use @apply
+ * — without these, utilities like `size-6` fail at build with "Cannot apply
+ * unknown utility class". Do not remove.
+ */
+@reference "tailwindcss";
+@reference "./global.css";
+
+/* =========================================================================
+   Cart summary panel + total + checkout button + empty state.
+   Owned here, NOT in global.css. The .checkout-btn extends .btn-primary
+   (which IS designer-owned) and adds full-width + :disabled treatment.
+   ========================================================================= */
+.cart-summary {
+  background: var(--color-paper-warm, var(--color-cream));
+  border: 1px solid var(--color-rule);
+  padding: var(--spacing-xl);
+  border-radius: var(--radius-md);
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-sm);
+}
+@media (min-width: 768px) {
+  .cart-summary {
+    position: sticky;
+    top: var(--spacing-xl);
+  }
+}
+
+.cart-empty {
+  text-align: center;
+  padding-block: var(--spacing-3xl);
+  color: var(--color-mute);
+}
+.cart-empty .checkout-btn {
+  display: inline-flex;
+  width: auto;
+  max-width: 18rem;
+}
+
+/* .checkout-btn composes the designer's `btn` @utility primitive plus the brand's
+   primary fill. Do NOT use `@apply btn-primary` here — Tailwind v4 only @applies
+   utilities declared with `@utility` (which `btn` is in global.css), not plain
+   custom classes like `.btn-primary` (which is just a regular CSS rule). The build
+   fails with "Cannot apply unknown utility class `btn-primary`" if you try.
+   The Phase 3 agent's brand-token swap (bark → navy/charcoal/coral/etc.) adapts
+   the var names without changing the composition shape. an earlier run on 2026-04-30 hit
+   this; the recovery cost ~1 min and a rebuild. */
+.checkout-btn {
+  @apply btn;
+  background: var(--color-bark);
+  color: var(--color-cream);
+  box-shadow: var(--shadow-sm);
+  width: 100%;
+  margin-top: var(--spacing-md);
+}
+.checkout-btn:hover:not(:disabled) {
+  background: var(--color-tobacco);
+  box-shadow: var(--shadow-md);
+}
+.checkout-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* --- Cart badge icon safety net --- */
+/* CartBadge.tsx renders an inline SVG bag icon + optional count span. The designer
+   owns .cart-badge in global.css; these rules guarantee an icon-button layout
+   (relative positioning anchor, centered icon, count pill overlap) even if the
+   designer's rule is purely aesthetic. */
+.cart-badge {
+  @apply relative inline-flex items-center justify-center;
+}
+.cart-badge-icon {
+  @apply size-6 shrink-0;
+}
+.cart-badge-count {
+  @apply absolute -top-1 -right-2 min-w-5 h-5 px-1 inline-flex items-center justify-center rounded-full bg-bark text-cream text-xs font-body tabular-nums leading-none;
+}
+
+/* --- Cart layout safety net --- */
+/* .cart-item is a global contract class styled by the designer in global.css.
+   These rules ensure the row layout works even if the designer omits flex. */
+.cart-item {
+  @apply flex flex-row gap-md;
+}
+.cart-item-image {
+  @apply shrink-0;
+}
+/* Clickable image + name link back to /products/<slug>.
+   At-rest underline + pointer cursor so the link is discoverable without
+   hovering (critical on touch). Muted rule-color underline keeps visual
+   weight in line with the body text; hover/focus escalates to tobacco. */
+.cart-item-image-link {
+  @apply block shrink-0 cursor-pointer;
+}
+.cart-item-image-link:hover .cart-item-image,
+.cart-item-image-link:focus-visible .cart-item-image {
+  @apply border-ink;
+}
+.cart-item-name-link {
+  @apply text-inherit cursor-pointer no-underline;
+  /* border-bottom is more predictable than text-decoration-line for inline
+     <a> inside <h3> (no text-decoration inheritance quirks). Muted ink at
+     rest, tobacco on hover. */
+  border-bottom: 1px solid var(--color-muted);
+  padding-bottom: 1px;
+  transition: color 150ms ease, border-color 150ms ease;
+}
+.cart-item-name-link:hover,
+.cart-item-name-link:focus-visible {
+  @apply text-tobacco outline-none;
+  border-bottom-color: var(--color-tobacco);
+}
+.cart-item-info {
+  @apply flex-1 min-w-0;
+}
+
+/* --- Description lines & modifiers --- */
+.cart-item-option {
+  @apply text-sm text-bark/70 font-body my-0.5;
+}
+.cart-item-modifiers {
+  @apply mt-1;
+}
+
+/* --- Quantity stepper --- */
+.cart-item-qty {
+  @apply inline-flex items-center gap-sm mt-sm w-fit;
+}
+.qty-btn {
+  @apply size-7 inline-flex items-center justify-center border border-bark rounded bg-transparent text-bark cursor-pointer font-body text-base leading-none;
+}
+.qty-btn:disabled {
+  @apply opacity-30 cursor-not-allowed;
+}
+.qty-value {
+  @apply font-body text-sm min-w-6 text-center tabular-nums;
+}
+
+/* --- Unavailable state --- */
+.cart-item-unavailable {
+  @apply text-sm text-red-600 font-medium font-body;
+}
+
+/* --- Price + remove --- */
+.cart-item-actions {
+  @apply flex flex-col items-end gap-1 shrink-0;
+}
+.cart-item-prices {
+  @apply flex items-center gap-sm;
+}
+.cart-item-full-price {
+  @apply text-sm text-bark/70 line-through font-body;
+}
+.cart-item-unit-price {
+  @apply font-body font-semibold whitespace-nowrap;
+}
+.cart-item-line-total {
+  @apply font-body text-xs text-bark/70 m-0;
+}
+.cart-item-remove {
+  @apply text-sm bg-transparent border-none text-bark/60 font-body cursor-pointer underline;
+}
+
+/* --- Cart summary: discount + total rows ---
+   Subtotal uses the designer's .cart-subtotal contract class in global.css.
+   These rows appear only when priceSummary exposes a discount or a total
+   that differs from subtotal (see CartView.tsx extractSummary). */
+.cart-discount {
+  @apply flex items-baseline justify-between gap-sm font-body text-sm mt-sm;
+}
+.cart-discount-name {
+  @apply text-xs text-bark/60;
+}
+.cart-discount-amount {
+  @apply whitespace-nowrap;
+}
+.cart-total {
+  border-top: 1px solid var(--color-rule);
+  padding-top: var(--spacing-md);
+  margin-top: var(--spacing-sm);
+  font-family: var(--font-display);
+  font-size: 1.25rem;
+  font-weight: 500;
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+}
+
+/* Applied-discounts row — name-only (no amount) for cases where the API
+   reports a promo NAME via appliedDiscounts[].discountName but no cart-level
+   amount in priceSummary.discount (common for line-item automatic discounts
+   — the savings already show inline via fullPrice/price strikethrough). */
+.cart-applied-discounts {
+  @apply flex items-baseline justify-between gap-sm font-body text-sm mt-sm;
+}
+.cart-applied-discounts-name {
+  @apply text-right text-bark/80 italic;
+}

package/skills/wix-headless/templates/ecom/discounts.ts

@@ -0,0 +1,71 @@
+// Live discount-rule fetch + per-product matching for storefront indicators.
+// Owned by the ecom pack because Wix Discount Rules is an @wix/ecom primitive.
+// Consumers: stores pack (ProductCard ribbon, product-detail offer callout,
+// home featured grid). Future ecom-using verticals (bookings, events) can
+// reuse the same util without change.
+//
+// Gotchas encoded here — do not remove:
+//  1. queryDiscountRules needs ECOM.DISCOUNT_RULES_READ — must be called via
+//     auth.elevate(), otherwise a visitor client returns no rules silently.
+//  2. Scope objects are returned with `_id` (underscore), not `id`. Check both.
+//  3. "All products" scope shape: { _id: "all_<appDefId>", catalogItemFilter:
+//     { catalogAppId, catalogItemIds: [] } }. Empty array + app id = applies
+//     to every product.
+
+import { discountRules } from "@wix/ecom";
+import { auth } from "@wix/essentials";
+
+export interface DiscountOffer {
+  id: string;
+  name: string;
+  offer: string;
+  targetType: string;
+}
+
+function applies(scopes: any[] | undefined, productId: string): boolean {
+  if (!scopes || scopes.length === 0) return false;
+  for (const s of scopes) {
+    const scopeId = s?._id ?? s?.id;
+    if (typeof scopeId === "string" && scopeId.startsWith("all_")) return true;
+    const ids = s?.catalogItemFilter?.catalogItemIds;
+    if (Array.isArray(ids) && ids.length === 0 && s?.catalogItemFilter?.catalogAppId) return true;
+    if (Array.isArray(ids) && ids.includes(productId)) return true;
+  }
+  return false;
+}
+
+function ruleApplies(rule: any, productId: string): boolean {
+  const values = rule?.discounts?.values ?? [];
+  for (const v of values) {
+    if (v?.targetType === "SPECIFIC_ITEMS") {
+      if (applies(v?.specificItemsInfo?.scopes, productId)) return true;
+    } else if (v?.targetType === "BUY_X_GET_Y") {
+      if (applies(v?.buyXGetYInfo?.customerBuys?.scopes, productId)) return true;
+      if (applies(v?.buyXGetYInfo?.customerGets?.scopes, productId)) return true;
+    }
+  }
+  return false;
+}
+
+export async function fetchLiveOffers(): Promise<any[]> {
+  try {
+    const elevated = auth.elevate(discountRules.queryDiscountRules);
+    const res: any = await elevated({ paging: { limit: 50 } } as any);
+    const list = res?.discountRules ?? res?.items ?? [];
+    return list.filter((r: any) => r?.active !== false && r?.status !== "EXPIRED");
+  } catch (err) {
+    console.error("[discounts] queryDiscountRules failed:", err);
+    return [];
+  }
+}
+
+export function offersForProduct(rules: any[], productId: string): DiscountOffer[] {
+  return rules
+    .filter((r) => ruleApplies(r, productId))
+    .map((r) => ({
+      id: r._id ?? r.id,
+      name: r.name ?? "",
+      offer: (r.offer ?? r.name ?? "").toString(),
+      targetType: r?.discounts?.values?.[0]?.targetType ?? "",
+    }));
+}

package/skills/wix-headless/templates/ecom/thank-you.astro

@@ -0,0 +1,24 @@
+---
+import Layout from "../layouts/Layout.astro";
+
+const orderId = Astro.url.searchParams.get("orderId");
+---
+
+<Layout title="Thank You">
+  <main class="py-4xl">
+    <div class="max-w-prose mx-auto px-xl text-center flex flex-col gap-lg">
+      <h1 class="font-display text-5xl">Thank You!</h1>
+      <p class="text-ink-soft">Your order has been placed successfully.</p>
+      {orderId && <p class="text-mute text-sm tracking-wide">Order ID: {orderId}</p>}
+      <a href="/products" class="btn-primary self-center mt-md">Continue Shopping</a>
+    </div>
+  </main>
+</Layout>
+
+<script>
+  import { trackEvent } from "../utils/analytics";
+  const orderId = new URLSearchParams(window.location.search).get("orderId");
+  if (orderId) {
+    trackEvent("Purchase", { id: orderId, origin: "Thank You Page" });
+  }
+</script>

package/skills/wix-headless/templates/gift-cards/GiftCardPurchase.tsx

@@ -0,0 +1,172 @@
+import { useState } from "react";
+import { currentCart } from "@wix/ecom";
+import { trackEvent } from "../utils/analytics";
+import {
+  WIX_GIFT_CARDS_APP_ID,
+  type GiftCardProduct,
+  type GiftCardPresetVariant,
+} from "../utils/gift-cards";
+
+interface GiftCardPurchaseProps {
+  product: GiftCardProduct;
+}
+
+// catalogReference shape captured from a real paid Wix-Editor order:
+//   { appId: WIX_GIFT_CARDS_APP_ID,
+//     catalogItemId: <giftCardProduct.id>,
+//     options: { variantId, quantity, currency, giftingInfo, wixGiftCardsAppNewCatalog: true } }
+// On ORDER_PAID, Wix's gift-card backend auto-issues a redeemable card with
+// source: "ORDER" and emails the recipient — no follow-up API call needed.
+export default function GiftCardPurchase({ product }: GiftCardPurchaseProps) {
+  const [variantId, setVariantId] = useState<string>(product.presetVariants[0]?.id ?? "");
+  const [recipientFirstName, setRecipientFirstName] = useState("");
+  const [recipientLastName, setRecipientLastName] = useState("");
+  const [recipientEmail, setRecipientEmail] = useState("");
+  const [greetingMessage, setGreetingMessage] = useState("");
+  const [status, setStatus] = useState<"idle" | "adding" | "added" | "error">("idle");
+  const [error, setError] = useState<string | null>(null);
+
+  const selectedVariant: GiftCardPresetVariant | undefined =
+    product.presetVariants.find((v) => v.id === variantId);
+
+  const emailValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(recipientEmail);
+  const canSubmit =
+    !!selectedVariant &&
+    recipientFirstName.trim().length > 0 &&
+    emailValid &&
+    status !== "adding";
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!canSubmit || !selectedVariant) return;
+    setStatus("adding");
+    setError(null);
+    try {
+      const { cart } = await currentCart.addToCurrentCart({
+        lineItems: [
+          {
+            catalogReference: {
+              appId: WIX_GIFT_CARDS_APP_ID,
+              catalogItemId: product.id,
+              options: {
+                variantId: selectedVariant.id,
+                quantity: 1,
+                giftingInfo: {
+                  recipientInfo: {
+                    email: recipientEmail.trim(),
+                    firstName: recipientFirstName.trim(),
+                    lastName: recipientLastName.trim(),
+                  },
+                  greetingMessage: greetingMessage.trim(),
+                },
+                wixGiftCardsAppNewCatalog: true,
+              } as Record<string, unknown>,
+            },
+            quantity: 1,
+          },
+        ],
+      });
+      window.dispatchEvent(new CustomEvent("cart-updated", { detail: { cart, delta: 1 } }));
+      trackEvent("AddToCart", {
+        id: product.id,
+        name: product.name,
+        price: Number(selectedVariant.price.amount),
+        quantity: 1,
+        variant: selectedVariant.price.formattedAmount,
+        origin: "Gift Card Page",
+      });
+      setStatus("added");
+      window.location.href = "/cart";
+    } catch (err: any) {
+      console.error("[gift-cards] addToCurrentCart failed:", err);
+      setError(err?.message ?? "Could not add the gift card to your cart. Please try again.");
+      setStatus("error");
+    }
+  };
+
+  return (
+    <form className="gift-card-form" onSubmit={handleSubmit} noValidate>
+      <fieldset className="gift-card-fieldset">
+        <legend className="option-label">Amount</legend>
+        <div className="gift-card-amounts">
+          {product.presetVariants.map((v) => {
+            const sel = v.id === variantId;
+            return (
+              <button
+                key={v.id}
+                type="button"
+                onClick={() => setVariantId(v.id)}
+                className={`option-pill${sel ? " selected" : ""}`}
+                aria-pressed={sel}
+              >
+                {v.price.formattedAmount}
+              </button>
+            );
+          })}
+        </div>
+      </fieldset>
+
+      <div className="gift-card-grid">
+        <label className="gift-card-field">
+          <span className="option-label">Recipient first name *</span>
+          <input
+            type="text"
+            value={recipientFirstName}
+            onChange={(e) => setRecipientFirstName(e.target.value)}
+            required
+            autoComplete="off"
+          />
+        </label>
+
+        <label className="gift-card-field">
+          <span className="option-label">Recipient last name</span>
+          <input
+            type="text"
+            value={recipientLastName}
+            onChange={(e) => setRecipientLastName(e.target.value)}
+            autoComplete="off"
+          />
+        </label>
+
+        <label className="gift-card-field gift-card-field-wide">
+          <span className="option-label">Recipient email *</span>
+          <input
+            type="email"
+            value={recipientEmail}
+            onChange={(e) => setRecipientEmail(e.target.value)}
+            required
+            autoComplete="off"
+          />
+        </label>
+
+        <label className="gift-card-field gift-card-field-wide">
+          <span className="option-label">Personal message</span>
+          <textarea
+            value={greetingMessage}
+            onChange={(e) => setGreetingMessage(e.target.value.slice(0, 500))}
+            maxLength={500}
+            rows={3}
+            placeholder="A short note to the recipient…"
+          />
+          <span className="gift-card-counter">{greetingMessage.length} / 500</span>
+        </label>
+      </div>
+
+      {error && <p className="gift-card-error" role="alert">{error}</p>}
+
+      <button
+        type="submit"
+        disabled={!canSubmit}
+        className="add-to-cart-btn"
+      >
+        {status === "adding"
+          ? "Adding…"
+          : status === "added"
+            ? "Added ✓"
+            : selectedVariant
+              ? `Add ${selectedVariant.price.formattedAmount} gift card to cart`
+              : "Add to cart"}
+      </button>
+    </form>
+  );
+}

package/skills/wix-headless/templates/gift-cards/_home-teaser-snippet.astro

@@ -0,0 +1,42 @@
+{/*
+  index.astro contribution. Insert the block below immediately AFTER the
+  `<!-- home:gift-cards -->` marker. ALSO add to the file's frontmatter
+  (above the `---` close):
+
+      import { getGiftCardProduct } from "../utils/gift-cards";
+      import { resolveWixImageUrl } from "../utils/wix-image";
+
+      const giftCardProduct = await getGiftCardProduct();
+      const giftCardImage = giftCardProduct
+        ? resolveWixImageUrl(giftCardProduct.image, 800, 600)
+        : null;
+
+  If `resolveWixImageUrl` is already imported by the stores patcher, do not
+  re-import — Astro frontmatter is TypeScript and duplicate imports build-fail.
+
+  The "A gift, considered" eyebrow can be replaced with brand-appropriate copy
+  during adaptation; keep the structure as-is.
+*/}
+{giftCardProduct && (
+  <section class="py-3xl md:py-4xl">
+    <a href="/gift-cards" class="max-w-wide mx-auto px-xl grid grid-cols-1 md:grid-cols-2 gap-xl md:gap-3xl items-center group">
+      <div class="aspect-[4/3] bg-cream rounded-sm overflow-hidden">
+        {giftCardImage && (
+          <img
+            src={giftCardImage}
+            alt={giftCardProduct.image?.altText || giftCardProduct.name}
+            loading="lazy"
+            decoding="async"
+            class="w-full h-full object-cover"
+          />
+        )}
+      </div>
+      <div class="flex flex-col gap-md">
+        <p class="eyebrow">A gift, considered</p>
+        <h2 class="font-display text-3xl leading-tight">{giftCardProduct.name}</h2>
+        <p class="text-ink-soft leading-relaxed">{giftCardProduct.description}</p>
+        <span class="text-sm tracking-wide uppercase mt-sm">Send a gift card →</span>
+      </div>
+    </a>
+  </section>
+)}

package/skills/wix-headless/templates/gift-cards/_nav-snippet.astro

@@ -0,0 +1,11 @@
+{/*
+  Navigation.astro contribution. Insert the line below immediately AFTER the
+  `<!-- nav:links -->` marker. ALSO add to the file's frontmatter:
+
+      import { getGiftCardProduct } from "../utils/gift-cards";
+      const giftCardsEnabled = (await getGiftCardProduct()) !== null;
+
+  Wrap the await in try/catch only if other awaits in the file are also
+  guarded (the helper itself never throws). The snippet itself is one line.
+*/}
+{giftCardsEnabled && <a href="/gift-cards">Gift Cards</a>}