@runwell/shopify-toolkit 0.23.0 → 0.24.0

package/modules/scratch-popup/SPEC.md

@@ -0,0 +1,120 @@
+# scratch-popup module (spec)
+
+> Status: spec (no code yet). Validated 2026-05-11 against `_knowledge-hub/marketing/2026-03-07-rating-email-capture-popups-for-ecommerce-stores.md` and the Claspo popup benchmark (11.29% scratch card vs 3.53% standard popup; 3.2x lift). First implementation target: Lushi v2 storefront.
+
+## What
+
+A gamified email-capture popup. Visitor sees a foil-textured card with a scratch-to-reveal mechanic. They enter their email, scratch the foil with mouse or finger, and a discount code is revealed underneath. Replaces the "type email get 15% off" mechanic with something more interactive and curiosity-driven.
+
+Sibling module to `exit-intent` (same display-layer wiring). The two can run together: scratch-popup as the primary email-capture path, exit-intent as the fallback for visitors who dismiss the scratch card.
+
+## Why
+
+Cited in our internal Knowledge Hub (Patrick Franco, Shopify email marketing): "mystery discount creates a lot of curiosity and is very interactive for cold traffic". Same source rates spin-the-wheel as gimmicky and to be avoided. Mystery-scratch occupies the "great" tier alongside bundle discounts and free-gift popups.
+
+External benchmark (Claspo, 779M popup impressions analyzed): scratch card average conversion 11.29% vs. 3.53% for standard static popups (3.2x lift). Treat as a directional ceiling, not a guarantee.
+
+## UX flow
+
+1. Trigger: visitor lands and meets one of:
+   - First-time visitor + 8s on site (configurable)
+   - Exit intent (mouse to top of viewport on desktop, scroll-up 30% on mobile)
+   - Tenant-configurable manual trigger (e.g., "Try your luck" CTA button)
+2. Modal opens. Foil card with prompt "Scratch to reveal your discount". Email field above, foil below.
+3. Email gate first (configurable; default ON). Visitor enters email + clicks Continue. Email stored in Shopify Customer + Klaviyo (if wired).
+4. Foil layer activates. Visitor drags mouse or swipes finger across the foil. Pixel by pixel erase via HTML5 Canvas `destination-out` composite.
+5. Once a threshold percentage of pixels is erased (default 60%), the foil auto-fades and reveals the discount code.
+6. Discount code displays + auto-copies to clipboard + sends to the email entered. Code is ALSO bound to that email so it cannot be shared.
+7. CTA: "Shop now" (closes modal, applies discount via cart). Visitor can also dismiss.
+8. Session flag (`runwell_scratch_played=true`) stored. Visitor cannot re-trigger the scratch on the same session OR with the same email.
+
+## Discount tiers (probability table, configurable)
+
+Default schema:
+```jsonc
+[
+  { "code_prefix": "MYSTERY10", "percentage": 10, "probability": 0.60 },
+  { "code_prefix": "MYSTERY15", "percentage": 15, "probability": 0.30 },
+  { "code_prefix": "MYSTERY20", "percentage": 20, "probability": 0.10 }
+]
+```
+
+- Total probability must sum to 1.0 (validated on config load).
+- Each tenant can override.
+- Server picks the tier on email submit, generates a unique code via Shopify Admin `discountCodeBasicCreate` (scope `write_discounts`, already live on Runwell Ops), and returns the code to the client.
+- Code is one-use, bound to the customer email (Shopify `discountCustomerSelection: { customers: { add: [<customer-id>] } }`), 30-day expiry.
+
+## Tenant config (runwell.config.json)
+
+```jsonc
+{
+  "modules": {
+    "scratch-popup": {
+      "enabled": true,
+      "triggers": {
+        "first_visit_delay_sec": 8,
+        "exit_intent": true,
+        "manual_cta_selector": null
+      },
+      "email_gate": true,
+      "scratch_threshold_pct": 60,
+      "tiers": [
+        { "code_prefix": "MYSTERY10", "percentage": 10, "probability": 0.60 },
+        { "code_prefix": "MYSTERY15", "percentage": 15, "probability": 0.30 },
+        { "code_prefix": "MYSTERY20", "percentage": 20, "probability": 0.10 }
+      ],
+      "expiry_days": 30,
+      "copy": {
+        "heading": "Scratch to reveal your discount",
+        "subheading": "One scratch, one code, just for you.",
+        "email_placeholder": "you@email.com",
+        "email_cta": "Continue",
+        "reveal_cta": "Shop now",
+        "post_reveal_subheading": "Code copied. Also sent to your inbox."
+      },
+      "design": {
+        "foil_color": "#C8B89A",
+        "foil_texture_url": null,
+        "accent_color": "#5B7A3E",
+        "card_radius_px": 16
+      },
+      "klaviyo_list_id": null
+    }
+  }
+}
+```
+
+## Technical components
+
+| Piece | Implementation |
+|---|---|
+| Liquid section | `sections/runwell-scratch-popup.liquid`. Renders the modal shell, hidden by default. Pulls config from `runwell.config.json` via the toolkit's standard config-injection pattern. |
+| CSS | `assets/runwell-scratch-popup.css`. Modal backdrop, card layout, foil container, responsive breakpoints, reduced-motion fallback. |
+| JS | `assets/runwell-scratch-popup.js`. Trigger logic, modal lifecycle, email validation, fetch to backend for code, Canvas scratch interaction with pointer + touch events, threshold detection, reveal animation, session-flag storage. |
+| Backend (Shopify Function or API endpoint) | Email -> tier selection (weighted random) -> `discountCodeBasicCreate` mutation -> return code. Lives in the toolkit's standard backend wiring (look at `exit-intent` for the pattern). |
+| Accessibility fallback | If reduced-motion or no canvas support: render a "Reveal" button that bypasses scratch and goes straight to step 7. |
+| Analytics | Fire toolkit's standard `runwell:popup:shown`, `runwell:popup:email_submit`, `runwell:popup:scratch_started`, `runwell:popup:scratch_revealed`, `runwell:popup:code_applied` events. Tenant analytics integration picks them up. |
+
+## Open questions
+
+- Email gate before or after scratch? Default ON (before) reduces abuse and improves email quality. Tenant can disable.
+- One scratch per email or one per session? Default: one per email per 30 days, server-enforced.
+- Klaviyo integration: same wiring as `exit-intent` (KLAVIYO_PUBLIC_KEY in env). Or per-tenant API key in tenant config.
+- Discount stacking: should scratch code stack with auto-applied promotions? Default: no, but tenant can override per discount tier.
+
+## Out of scope
+
+- Random non-discount rewards (free gift, free shipping, $X off). Future iteration if mystery-discount converts.
+- Multi-step quizzes ("answer 3 questions then scratch"). Different module, larger spec.
+- Storefront wheel/spin variants (KH says skip; we agree).
+
+## First implementation target
+
+Lushi v2 storefront. After the bundle-system rollout lands (BS-601..606). Coordinate with Lushi v2 launch sequencing.
+
+## Related
+
+- `_clients/capital-v/lushi/tickets/mystery-scratch-popup.md` (the originating ticket)
+- `_knowledge-hub/marketing/2026-03-07-rating-email-capture-popups-for-ecommerce-stores.md` (validation)
+- `modules/exit-intent/` (wiring pattern; sibling module)
+- `infrastructure/scripts/shopify/shopify-discount-create.sh` (server-side discount code generation)

package/modules/scratch-popup/assets/runwell-scratch-popup.css

@@ -0,0 +1,315 @@
+/* Runwell scratch popup. Modal layout with email gate -> foil scratch surface -> revealed code.
+   Two CSS variables drive the brand colors: --runwell-scratch-foil (the scratch overlay) and
+   --runwell-scratch-accent (CTAs, highlights). Set on the root element via inline style from
+   the section's color settings. */
+
+.runwell-scratch {
+  position: fixed;
+  inset: 0;
+  z-index: 999;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  padding: 1.5rem;
+}
+
+.runwell-scratch.is-open { display: flex; }
+
+.runwell-scratch__backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.6);
+  backdrop-filter: blur(4px);
+}
+
+.runwell-scratch__panel {
+  position: relative;
+  background: #FFFFFF;
+  color: var(--runwell-primary, #1A1A1A);
+  max-width: 460px;
+  width: 100%;
+  padding: 2.5rem 2rem 2rem;
+  border-radius: 12px;
+  box-shadow: 0 24px 60px rgba(0, 0, 0, 0.35);
+  text-align: center;
+}
+
+.runwell-scratch__close {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.8rem;
+  background: transparent;
+  border: 0;
+  font-size: 1.8rem;
+  font-weight: 300;
+  color: currentColor;
+  cursor: pointer;
+  line-height: 1;
+}
+
+.runwell-scratch__eyebrow {
+  font-size: 0.75rem;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  font-weight: 700;
+  margin: 0 0 0.6rem 0;
+  opacity: 0.6;
+  color: var(--runwell-scratch-accent);
+}
+
+.runwell-scratch__heading {
+  font-family: var(--font-heading-family, serif);
+  font-style: normal;
+  font-weight: 400;
+  font-size: 1.7rem;
+  line-height: 1.15;
+  margin: 0 0 0.8rem 0;
+}
+
+.runwell-scratch__subheading {
+  font-size: 0.95rem;
+  line-height: 1.55;
+  margin: 0 0 1.6rem 0;
+  opacity: 0.8;
+}
+
+.runwell-scratch__step { animation: runwellScratchFade 0.25s ease-out both; }
+@keyframes runwellScratchFade {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+/* ---------- Step 1: email gate ---------- */
+.runwell-scratch__form {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.8rem;
+}
+
+.runwell-scratch__form input[type="email"] {
+  flex: 1;
+  min-width: 200px;
+  padding: 0.85rem 1rem;
+  border: 1px solid rgba(0, 0, 0, 0.25);
+  border-radius: 6px;
+  font-size: 0.95rem;
+  background: #FFFFFF;
+  transition: border-color 0.2s ease;
+}
+
+.runwell-scratch__form input[type="email"].is-invalid {
+  border-color: #C0392B;
+  animation: runwellScratchShake 0.4s ease;
+}
+@keyframes runwellScratchShake {
+  0%, 100% { transform: translateX(0); }
+  20%, 60% { transform: translateX(-4px); }
+  40%, 80% { transform: translateX(4px); }
+}
+
+.runwell-scratch__email-prompt {
+  font-size: 1rem;
+  font-weight: 600;
+  margin: 0 0 0.6rem 0;
+  color: var(--runwell-scratch-accent, #1A1A1A);
+}
+
+.runwell-scratch__cta {
+  background: var(--runwell-scratch-accent, #1A1A1A);
+  color: #FFFFFF;
+  border: 0;
+  padding: 0.85rem 1.4rem;
+  font-weight: 700;
+  font-size: 0.95rem;
+  border-radius: 6px;
+  cursor: pointer;
+  text-decoration: none;
+  display: inline-block;
+}
+
+.runwell-scratch__cta:hover { filter: brightness(0.92); }
+
+.runwell-scratch__cta--reveal {
+  display: block;
+  margin: 1rem auto 0;
+  max-width: 280px;
+  text-align: center;
+}
+
+.runwell-scratch__fineprint {
+  font-size: 0.75rem;
+  margin-top: 0.4rem;
+  opacity: 0.55;
+}
+
+/* ---------- Step 1: scratch surface ---------- */
+.runwell-scratch__scratch-prompt {
+  font-size: 0.85rem;
+  margin: 0.6rem 0 0 0;
+  opacity: 0.6;
+  letter-spacing: 0.05em;
+}
+
+.runwell-scratch__card {
+  position: relative;
+  width: 100%;
+  height: 220px;
+  margin: 0.6rem 0 0;
+  border-radius: 12px;
+  overflow: hidden;
+  background: #FFFFFF;
+  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.15);
+  user-select: none;
+  touch-action: none;
+}
+
+/* Trophy variant: the same card, shown smaller after the scratch so it sits as
+   a header above the email form / code display. No canvas, just the reveal. */
+.runwell-scratch__card--trophy {
+  height: 110px;
+  background: #FFFFFF;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.10);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.1rem;
+  margin: 0 0 1rem;
+  color: var(--runwell-scratch-accent, #1A1A1A);
+}
+
+.runwell-scratch__card--trophy .runwell-scratch__reveal-pct {
+  font-size: 1.9rem;
+}
+
+.runwell-scratch__reveal {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.2rem;
+  background: #FFFFFF;
+  color: var(--runwell-scratch-accent, #1A1A1A);
+}
+
+.runwell-scratch__reveal-eyebrow {
+  font-size: 0.65rem;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  font-weight: 700;
+  margin: 0;
+  opacity: 0.65;
+}
+
+.runwell-scratch__reveal-pct {
+  font-size: 3rem;
+  font-weight: 800;
+  margin: 0;
+  line-height: 1;
+}
+
+.runwell-scratch__reveal-fineprint {
+  font-size: 0.75rem;
+  margin: 0;
+  opacity: 0.6;
+}
+
+.runwell-scratch__canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  cursor: grab;
+}
+
+.runwell-scratch__canvas:active { cursor: grabbing; }
+
+.runwell-scratch__card.is-revealed .runwell-scratch__canvas {
+  animation: runwellScratchFadeOut 0.4s ease-out forwards;
+  pointer-events: none;
+}
+@keyframes runwellScratchFadeOut {
+  to { opacity: 0; }
+}
+
+.runwell-scratch__a11y-reveal {
+  position: absolute;
+  bottom: 0.5rem;
+  right: 0.6rem;
+  background: rgba(255, 255, 255, 0.85);
+  border: 1px solid rgba(0, 0, 0, 0.15);
+  font-size: 0.7rem;
+  padding: 0.25rem 0.55rem;
+  border-radius: 4px;
+  cursor: pointer;
+  z-index: 2;
+}
+
+/* ---------- Step 3: revealed ---------- */
+.runwell-scratch__revealed-heading {
+  font-family: var(--font-heading-family, serif);
+  font-size: 1.5rem;
+  font-weight: 400;
+  margin: 0 0 0.4rem 0;
+}
+
+.runwell-scratch__revealed-subheading {
+  font-size: 0.9rem;
+  margin: 0 0 1rem 0;
+  opacity: 0.75;
+}
+
+.runwell-scratch__code-display {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin: 0 0 0.8rem 0;
+  padding: 0.8rem 1rem;
+  background: rgba(0, 0, 0, 0.03);
+  border-radius: 8px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  font-size: 1.3rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+}
+
+.runwell-scratch__copy {
+  background: transparent;
+  border: 1px solid var(--runwell-scratch-accent, #1A1A1A);
+  color: var(--runwell-scratch-accent, #1A1A1A);
+  padding: 0.35rem 0.7rem;
+  border-radius: 4px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  cursor: pointer;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+}
+
+.runwell-scratch__copy.is-copied {
+  background: var(--runwell-scratch-accent, #1A1A1A);
+  color: #FFFFFF;
+}
+
+/* ---------- Reduced motion ---------- */
+@media (prefers-reduced-motion: reduce) {
+  .runwell-scratch__step,
+  .runwell-scratch__card.is-revealed .runwell-scratch__canvas {
+    animation: none;
+  }
+}
+
+/* ---------- Mobile ---------- */
+@media (max-width: 540px) {
+  .runwell-scratch { padding: 1rem; }
+  .runwell-scratch__panel { padding: 2rem 1.3rem 1.6rem; }
+  .runwell-scratch__heading { font-size: 1.45rem; }
+  .runwell-scratch__card { height: 150px; }
+  .runwell-scratch__reveal-pct { font-size: 2.1rem; }
+}
+
+body.runwell-scratch-open { overflow: hidden; }