@runwell/shopify-toolkit 0.21.0 → 0.24.0

package/modules/scratch-popup/module.json

@@ -0,0 +1,128 @@
+{
+  "name": "scratch-popup",
+  "version": "0.1.0",
+  "status": "ready",
+  "category": "conversion",
+  "description": "Mystery-discount scratch popup. Email capture + foil-card scratch-to-reveal that unlocks a unique discount code per visitor. KH-validated alternative to spin-the-wheel.",
+  "files": {
+    "sections": [
+      "sections/runwell-scratch-popup.liquid"
+    ],
+    "assets": [
+      "assets/runwell-scratch-popup.js",
+      "assets/runwell-scratch-popup.css"
+    ]
+  },
+  "depends_on": {
+    "scopes": [
+      "write_discounts",
+      "read_discounts",
+      "write_customers",
+      "read_customers"
+    ]
+  },
+  "config": {
+    "schema": {
+      "enabled": {
+        "type": "boolean",
+        "default": false,
+        "label": "Enable scratch popup"
+      },
+      "triggers.first_visit_delay_sec": {
+        "type": "number",
+        "default": 8,
+        "label": "First-visit delay (seconds)"
+      },
+      "triggers.exit_intent": {
+        "type": "boolean",
+        "default": true,
+        "label": "Trigger on exit intent"
+      },
+      "triggers.manual_cta_selector": {
+        "type": "string",
+        "default": null,
+        "label": "Manual CTA selector (optional)"
+      },
+      "email_gate": {
+        "type": "boolean",
+        "default": true,
+        "label": "Require email before scratch"
+      },
+      "scratch_threshold_pct": {
+        "type": "number",
+        "default": 60,
+        "label": "Foil-erase percentage before auto-reveal"
+      },
+      "tiers": {
+        "type": "array",
+        "default": [
+          { "code_prefix": "MYSTERY10", "percentage": 10, "probability": 0.60 },
+          { "code_prefix": "MYSTERY15", "percentage": 15, "probability": 0.30 },
+          { "code_prefix": "MYSTERY20", "percentage": 20, "probability": 0.10 }
+        ],
+        "label": "Discount tiers + probability"
+      },
+      "expiry_days": {
+        "type": "number",
+        "default": 30,
+        "label": "Discount-code expiry"
+      },
+      "copy.heading": {
+        "type": "string",
+        "default": "Scratch to reveal your discount",
+        "label": "Modal heading"
+      },
+      "copy.subheading": {
+        "type": "string",
+        "default": "One scratch, one code, just for you.",
+        "label": "Modal subheading"
+      },
+      "copy.email_placeholder": {
+        "type": "string",
+        "default": "you@email.com",
+        "label": "Email field placeholder"
+      },
+      "copy.email_cta": {
+        "type": "string",
+        "default": "Continue",
+        "label": "Email CTA"
+      },
+      "copy.reveal_cta": {
+        "type": "string",
+        "default": "Shop now",
+        "label": "Post-reveal CTA"
+      },
+      "copy.post_reveal_subheading": {
+        "type": "string",
+        "default": "Code copied. Also sent to your inbox.",
+        "label": "Post-reveal subheading"
+      },
+      "design.foil_color": {
+        "type": "color",
+        "default": "#C8B89A",
+        "label": "Foil color"
+      },
+      "design.foil_texture_url": {
+        "type": "string",
+        "default": null,
+        "label": "Optional foil texture image URL"
+      },
+      "design.accent_color": {
+        "type": "color",
+        "default": "#5B7A3E",
+        "label": "Accent color"
+      },
+      "design.card_radius_px": {
+        "type": "number",
+        "default": 16,
+        "label": "Card corner radius (px)"
+      },
+      "klaviyo_list_id": {
+        "type": "string",
+        "default": null,
+        "label": "Klaviyo list ID (optional)"
+      }
+    }
+  },
+  "spec": "SPEC.md"
+}

package/modules/scratch-popup/sections/runwell-scratch-popup.liquid

@@ -0,0 +1,184 @@
+{%- comment -%}
+  Runwell scratch popup. Mystery-discount email capture with foil
+  scratch-to-reveal mechanic. KH-validated alternative to spin-the-wheel.
+
+  Discount codes are pre-created on the store via
+  `infrastructure/scripts/shopify/shopify-discount-create.sh`. Tier codes here
+  must match the codes created on the store side. Default codes:
+    MYSTERY10 (10% off, once-per-customer)
+    MYSTERY15 (15% off, once-per-customer)
+    MYSTERY20 (20% off, once-per-customer)
+{%- endcomment -%}
+{{ 'runwell-scratch-popup.css' | asset_url | stylesheet_tag }}
+
+<div
+  class="runwell-scratch"
+  data-runwell-scratch
+  data-tier1-code="{{ section.settings.tier1_code }}"
+  data-tier1-pct="{{ section.settings.tier1_pct }}"
+  data-tier1-prob="{{ section.settings.tier1_prob }}"
+  data-tier2-code="{{ section.settings.tier2_code }}"
+  data-tier2-pct="{{ section.settings.tier2_pct }}"
+  data-tier2-prob="{{ section.settings.tier2_prob }}"
+  data-tier3-code="{{ section.settings.tier3_code }}"
+  data-tier3-pct="{{ section.settings.tier3_pct }}"
+  data-tier3-prob="{{ section.settings.tier3_prob }}"
+  data-trigger-delay-sec="{{ section.settings.trigger_delay_sec }}"
+  data-exit-intent="{{ section.settings.exit_intent }}"
+  data-scratch-threshold-pct="{{ section.settings.scratch_threshold_pct }}"
+  style="--runwell-scratch-foil: {{ section.settings.foil_color }}; --runwell-scratch-accent: {{ section.settings.accent_color }};"
+  aria-hidden="true"
+  role="dialog"
+  aria-labelledby="runwell-scratch-title"
+>
+  <div class="runwell-scratch__backdrop" data-runwell-scratch-close></div>
+
+  <div class="runwell-scratch__panel">
+    <button class="runwell-scratch__close" type="button" data-runwell-scratch-close aria-label="Close">&times;</button>
+
+    {%- if section.settings.eyebrow != blank -%}
+      <p class="runwell-scratch__eyebrow">{{ section.settings.eyebrow }}</p>
+    {%- endif -%}
+
+    <h2 id="runwell-scratch-title" class="runwell-scratch__heading">{{ section.settings.heading }}</h2>
+
+    {%- if section.settings.subheading != blank -%}
+      <p class="runwell-scratch__subheading">{{ section.settings.subheading }}</p>
+    {%- endif -%}
+
+    {%- comment -%}
+      Flow (corrected 2026-05-11 after live-vendor research):
+        1. SCRATCH    - foil card visible immediately; visitor scratches it
+        2. EMAIL      - card stays as trophy; "Won X% off! Email me my code" form appears
+        3. REVEALED   - code shown with Copy + Shop now (auto-applies via cart URL)
+
+      The scratch is the dopamine hook that earns the email. Showing the email
+      field first kills the mechanic. Pattern matches Knowband, Poptin,
+      AppSetup, CI Scratch, Triggerbee, Winify, Superpop.
+    {%- endcomment -%}
+
+    {%- comment -%} STEP 1 (default visible): scratch surface {%- endcomment -%}
+    <div class="runwell-scratch__step runwell-scratch__step--scratch" data-runwell-scratch-step="scratch">
+      <div class="runwell-scratch__card">
+        <div class="runwell-scratch__reveal" data-runwell-scratch-reveal>
+          <p class="runwell-scratch__reveal-eyebrow">You won</p>
+          <p class="runwell-scratch__reveal-pct" data-runwell-scratch-pct>--%</p>
+          <p class="runwell-scratch__reveal-fineprint">off your order</p>
+        </div>
+        <canvas class="runwell-scratch__canvas" data-runwell-scratch-canvas></canvas>
+        <button
+          type="button"
+          class="runwell-scratch__a11y-reveal"
+          data-runwell-scratch-a11y-reveal
+          aria-label="Reveal discount (accessibility)"
+        >
+          Or tap to reveal
+        </button>
+      </div>
+      <p class="runwell-scratch__scratch-prompt">{{ section.settings.scratch_prompt }}</p>
+    </div>
+
+    {%- comment -%} STEP 2: email capture (after scratch reveals the discount amount) {%- endcomment -%}
+    <div class="runwell-scratch__step runwell-scratch__step--email" data-runwell-scratch-step="email" hidden>
+      <div class="runwell-scratch__card runwell-scratch__card--trophy" data-runwell-scratch-trophy>
+        <p class="runwell-scratch__reveal-eyebrow">You won</p>
+        <p class="runwell-scratch__reveal-pct" data-runwell-scratch-pct-trophy>--%</p>
+        <p class="runwell-scratch__reveal-fineprint">off your order</p>
+      </div>
+      <p class="runwell-scratch__email-prompt">{{ section.settings.email_prompt }}</p>
+      <div class="runwell-scratch__form" data-runwell-scratch-form>
+        <input type="hidden" data-runwell-scratch-tags value="newsletter, scratch-popup">
+        <label class="visually-hidden" for="runwell-scratch-email">Email</label>
+        <input
+          id="runwell-scratch-email"
+          type="email"
+          name="contact[email]"
+          placeholder="{{ section.settings.email_placeholder }}"
+          required
+          data-runwell-scratch-email
+        >
+        <button
+          type="button"
+          class="runwell-scratch__cta runwell-scratch__cta--email"
+          data-runwell-scratch-email-submit
+        >
+          {{ section.settings.email_cta_text }}
+        </button>
+      </div>
+      <p class="runwell-scratch__fineprint">No spam. One use per customer.</p>
+    </div>
+
+    {%- comment -%} STEP 3: code revealed + auto-apply CTA {%- endcomment -%}
+    <div class="runwell-scratch__step runwell-scratch__step--revealed" data-runwell-scratch-step="revealed" hidden>
+      <div class="runwell-scratch__card runwell-scratch__card--trophy">
+        <p class="runwell-scratch__reveal-eyebrow">You won</p>
+        <p class="runwell-scratch__reveal-pct" data-runwell-scratch-pct-final>--%</p>
+        <p class="runwell-scratch__reveal-fineprint">off your order</p>
+      </div>
+      <p class="runwell-scratch__revealed-heading">{{ section.settings.revealed_heading }}</p>
+      <div class="runwell-scratch__code-display">
+        <span data-runwell-scratch-code-display>------</span>
+        <button type="button" class="runwell-scratch__copy" data-runwell-scratch-copy aria-label="Copy code">Copy</button>
+      </div>
+      <a
+        href="{{ section.settings.reveal_cta_url | default: '/collections/all' }}"
+        class="runwell-scratch__cta runwell-scratch__cta--reveal"
+        data-runwell-scratch-shop
+      >
+        {{ section.settings.reveal_cta_text }}
+      </a>
+      <p class="runwell-scratch__fineprint">{{ section.settings.revealed_subheading }}</p>
+    </div>
+  </div>
+</div>
+
+<script src="{{ 'runwell-scratch-popup.js' | asset_url }}" defer="defer"></script>
+
+{% schema %}
+{
+  "name": "Runwell scratch popup",
+  "tag": "section",
+  "class": "section-runwell-scratch",
+  "settings": [
+    { "type": "header", "content": "Copy" },
+    { "type": "text", "id": "eyebrow", "label": "Eyebrow", "default": "A little surprise" },
+    { "type": "text", "id": "heading", "label": "Heading", "default": "Scratch to reveal your discount" },
+    { "type": "textarea", "id": "subheading", "label": "Subheading", "default": "Scratch the foil card below to see how much you saved." },
+    { "type": "text", "id": "scratch_prompt", "label": "Scratch prompt (under the card)", "default": "Drag or tap to scratch" },
+    { "type": "text", "id": "email_prompt", "label": "Email prompt (after scratch)", "default": "Where should we send your code?" },
+    { "type": "text", "id": "email_placeholder", "label": "Email placeholder", "default": "you@email.com" },
+    { "type": "text", "id": "email_cta_text", "label": "Email CTA", "default": "Email me my code" },
+    { "type": "text", "id": "revealed_heading", "label": "Revealed heading", "default": "Here is your code." },
+    { "type": "textarea", "id": "revealed_subheading", "label": "Revealed fineprint", "default": "Copied and sent to your inbox. One use per customer. Auto-applies at checkout." },
+    { "type": "text", "id": "reveal_cta_text", "label": "Revealed CTA", "default": "Shop now" },
+    { "type": "url", "id": "reveal_cta_url", "label": "Revealed CTA URL (discount auto-appends)" },
+
+    { "type": "header", "content": "Tier 1 (most likely)" },
+    { "type": "text", "id": "tier1_code", "label": "Code (must exist as Shopify discount)", "default": "MYSTERY10" },
+    { "type": "range", "id": "tier1_pct", "label": "Percentage off", "min": 1, "max": 50, "step": 1, "default": 10 },
+    { "type": "range", "id": "tier1_prob", "label": "Probability (%)", "min": 0, "max": 100, "step": 5, "default": 60 },
+
+    { "type": "header", "content": "Tier 2 (mid)" },
+    { "type": "text", "id": "tier2_code", "label": "Code", "default": "MYSTERY15" },
+    { "type": "range", "id": "tier2_pct", "label": "Percentage off", "min": 1, "max": 50, "step": 1, "default": 15 },
+    { "type": "range", "id": "tier2_prob", "label": "Probability (%)", "min": 0, "max": 100, "step": 5, "default": 30 },
+
+    { "type": "header", "content": "Tier 3 (rare)" },
+    { "type": "text", "id": "tier3_code", "label": "Code", "default": "MYSTERY20" },
+    { "type": "range", "id": "tier3_pct", "label": "Percentage off", "min": 1, "max": 50, "step": 1, "default": 20 },
+    { "type": "range", "id": "tier3_prob", "label": "Probability (%)", "min": 0, "max": 100, "step": 5, "default": 10 },
+
+    { "type": "header", "content": "Triggers" },
+    { "type": "range", "id": "trigger_delay_sec", "label": "First-visit delay (seconds)", "min": 0, "max": 60, "step": 1, "default": 8 },
+    { "type": "checkbox", "id": "exit_intent", "label": "Also trigger on exit intent", "default": true },
+    { "type": "range", "id": "scratch_threshold_pct", "label": "Foil-erase % before auto-reveal", "min": 30, "max": 90, "step": 5, "default": 60 },
+
+    { "type": "header", "content": "Design" },
+    { "type": "color", "id": "foil_color", "label": "Foil color", "default": "#C8B89A" },
+    { "type": "color", "id": "accent_color", "label": "Accent color", "default": "#5B7A3E" }
+  ],
+  "presets": [
+    { "name": "Runwell scratch popup" }
+  ]
+}
+{% endschema %}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runwell/shopify-toolkit",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "description": "Reusable Shopify theme modules from Runwell. Replaces typically app-driven features (reviews, wishlist, urgency, FAQ, post-purchase upsell, exit popups, free-ship progress, sticky ATC, testimonials, badges, bundles) with native Liquid + JS + CSS that ship across multiple client themes via a config-driven sync CLI.",
   "type": "module",
   "main": "lib/index.js",