@runwell/shopify-toolkit 0.23.0 → 0.24.0

package/modules/runwell-bundle-system/sections/runwell-bundle-pdp-banner.liquid

@@ -10,7 +10,8 @@
 {%- if settings.bundle_system__surface_5_pdp_banner_enabled == false -%}
   {%- comment -%} Tenant has disabled this surface. {%- endcomment -%}
 {%- else -%}
-  {%- assign bundle_index = shop.metaobjects.bundle_index.entries.value -%}
+  {%- assign bundle_index_instance = shop.metaobjects.bundle_index.values | first -%}
+  {%- assign bundle_index = bundle_index_instance.entries.value -%}
   {%- assign matching_handles = '' -%}
   {%- if bundle_index and bundle_index.products -%}
     {%- assign matching_handles = bundle_index.products[product.handle] -%}

package/modules/runwell-bundle-system/sections/runwell-bundle-pdp-pairs-with.liquid

@@ -12,7 +12,8 @@
 {%- if settings.bundle_system__surface_2_pdp_pairs_with_enabled == false -%}
   {%- comment -%} Tenant has disabled this surface. {%- endcomment -%}
 {%- else -%}
-  {%- assign bundle_index = shop.metaobjects.bundle_index.entries.value -%}
+  {%- assign bundle_index_instance = shop.metaobjects.bundle_index.values | first -%}
+  {%- assign bundle_index = bundle_index_instance.entries.value -%}
   {%- assign matching_handles = '' -%}
   {%- if bundle_index and bundle_index.products -%}
     {%- assign matching_handles = bundle_index.products[product.handle] -%}

package/modules/runwell-bundle-system/sections/runwell-bundle-pdp.liquid

@@ -112,6 +112,8 @@
   "presets": [
     { "name": "Bundle PDP", "category": "Runwell" }
   ],
-  "templates": ["product.bundle"]
+  "enabled_on": {
+    "templates": ["product"]
+  }
 }
 {% endschema %}

package/modules/runwell-bundle-system/sections/runwell-bundle-quantity-builder.liquid

@@ -0,0 +1,318 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-quantity-builder.liquid.
+
+  Mode A bundle PDP surface. Renders a product image gallery beside a
+  quantity-tier picker, sale-prefix headline, FOMO countdown + scarcity,
+  rating row, trust badges row, and an ATC that can append a free gift
+  product when the selected tier opts into one.
+
+  Everything bundle-specific is read from `product.metafields.runwell.*`:
+    bundle_quantity_tiers   [{qty, discount_pct, label?, popular?,
+                              free_shipping?, free_gift?}]
+    bundle_sale_prefix      "Spring Sculpting Sale"
+    bundle_fomo_mode        none | discount | scarcity | both
+    bundle_fomo_cycle_days  number (rolling deadline cycle)
+    bundle_fomo_stock_count number
+    bundle_rating_score     "4.8/5"
+    bundle_rating_count     "2,400+"
+    bundle_free_gift_handle product handle (real $0 product); the section
+                            adds a hidden form input + the ATC JS appends
+                            it as a second /cart/add line when a free_gift
+                            tier is selected.
+
+  Section settings cover what's tenant/page level (color scheme, padding,
+  trust badge copy, toggles). Per-tier data is metafield-driven so admin
+  changes flow without re-deploying the theme.
+
+  Replaces the legacy modules/bundle-builder/sections/runwell-bundle-builder
+  section. CSS class prefix kept stable (.runwell-bundle-quantity-builder)
+  with the same visual structure to preserve tenant calibration.
+{%- endcomment -%}
+
+{{ 'runwell-bundle-quantity-builder.css' | asset_url | stylesheet_tag }}
+
+{%- assign product = section.settings.product -%}
+{%- if product == blank -%}
+  <div class="runwell-bundle-quantity-builder runwell-bundle-quantity-builder--empty page-width">
+    <p>Select a product in the section editor to render the bundle builder.</p>
+  </div>
+{%- else -%}
+
+  {%- assign mf = product.metafields.runwell -%}
+  {%- assign tiers = mf.bundle_quantity_tiers.value -%}
+  {%- assign sale_prefix = mf.bundle_sale_prefix.value | default: section.settings.sale_prefix -%}
+  {%- assign fomo_mode = mf.bundle_fomo_mode.value | default: 'none' -%}
+  {%- assign fomo_cycle_days = mf.bundle_fomo_cycle_days.value | default: 30 -%}
+  {%- assign fomo_stock_count = mf.bundle_fomo_stock_count.value | default: 0 -%}
+  {%- assign rating_score = mf.bundle_rating_score.value -%}
+  {%- assign rating_count = mf.bundle_rating_count.value -%}
+  {%- assign free_gift_handle = mf.bundle_free_gift_handle.value -%}
+  {%- assign free_gift_product = blank -%}
+  {%- if free_gift_handle != blank -%}
+    {%- assign free_gift_product = all_products[free_gift_handle] -%}
+  {%- endif -%}
+
+  <section
+    class="runwell-bundle-quantity-builder color-{{ section.settings.color_scheme }}"
+    style="padding-top: {{ section.settings.padding_top }}px; padding-bottom: {{ section.settings.padding_bottom }}px;"
+    data-runwell-bundle-quantity-builder
+    data-product-handle="{{ product.handle }}"
+    {%- if free_gift_product != blank %} data-free-gift-variant-id="{{ free_gift_product.selected_or_first_available_variant.id }}"{%- endif -%}
+  >
+    <div class="page-width">
+      <div class="runwell-bundle-quantity-builder__grid">
+
+        {%- comment -%} Gallery: prefers product.media; falls back to featured_image. {%- endcomment -%}
+        <div class="runwell-bundle-quantity-builder__media">
+          {%- assign media_items = product.media -%}
+          {%- if media_items.size > 0 -%}
+            <div class="runwell-bundle-quantity-builder__slideshow" data-slideshow>
+              {%- for media in media_items -%}
+                <div
+                  class="runwell-bundle-quantity-builder__slide {% if forloop.first %}runwell-bundle-quantity-builder__slide--active{% endif %}"
+                  data-slide="{{ forloop.index0 }}"
+                >
+                  {{ media | image_url: width: 1200 | image_tag:
+                    class: 'runwell-bundle-quantity-builder__img',
+                    loading: forloop.first | default: 'eager',
+                    sizes: '(min-width: 990px) 50vw, 100vw',
+                    alt: media.alt | default: product.title
+                  }}
+                </div>
+              {%- endfor -%}
+            </div>
+            {%- if media_items.size > 1 -%}
+              <div class="runwell-bundle-quantity-builder__thumbnails" data-thumbnails>
+                {%- for media in media_items -%}
+                  <button
+                    class="runwell-bundle-quantity-builder__thumb {% if forloop.first %}runwell-bundle-quantity-builder__thumb--active{% endif %}"
+                    type="button"
+                    data-thumb="{{ forloop.index0 }}"
+                    aria-label="View image {{ forloop.index }}"
+                  >
+                    {{ media | image_url: width: 160, height: 160, crop: 'center' | image_tag: loading: 'lazy', alt: '' }}
+                  </button>
+                {%- endfor -%}
+              </div>
+            {%- endif -%}
+          {%- elsif product.featured_image -%}
+            <div class="runwell-bundle-quantity-builder__slideshow">
+              <div class="runwell-bundle-quantity-builder__slide runwell-bundle-quantity-builder__slide--active">
+                {{ product.featured_image | image_url: width: 1200 | image_tag:
+                  class: 'runwell-bundle-quantity-builder__img',
+                  loading: 'eager',
+                  alt: product.title
+                }}
+              </div>
+            </div>
+          {%- else -%}
+            <div class="runwell-bundle-quantity-builder__slideshow">
+              <div class="runwell-bundle-quantity-builder__slide runwell-bundle-quantity-builder__slide--active">
+                <div class="runwell-bundle-quantity-builder__img runwell-bundle-quantity-builder__img--placeholder" aria-label="No image"></div>
+              </div>
+            </div>
+          {%- endif -%}
+        </div>
+
+        <div class="runwell-bundle-quantity-builder__info">
+
+          {%- if section.settings.show_rating and rating_score != blank -%}
+            <div class="runwell-bundle-quantity-builder__rating">
+              <span class="runwell-bundle-quantity-builder__stars" aria-hidden="true">&#9733;&#9733;&#9733;&#9733;&#9733;</span>
+              <span class="runwell-bundle-quantity-builder__rating-text">
+                Rated {{ rating_score }}{%- if rating_count != blank %} ({{ rating_count }} Reviews){%- endif -%}
+              </span>
+            </div>
+          {%- endif -%}
+
+          <h2 class="runwell-bundle-quantity-builder__title h1">{{ product.title }}</h2>
+
+          {%- if fomo_mode != 'none' or sale_prefix != blank -%}
+            {%- assign show_scarcity = false -%}
+            {%- if fomo_mode == 'scarcity' or fomo_mode == 'both' -%}
+              {%- if fomo_stock_count > 0 -%}{%- assign show_scarcity = true -%}{%- endif -%}
+            {%- endif -%}
+
+            {%- assign sale_text = sale_prefix -%}
+            {%- if fomo_mode == 'discount' or fomo_mode == 'both' -%}
+              {%- assign now_epoch = 'now' | date: '%s' | plus: 0 -%}
+              {%- assign cycle_seconds = fomo_cycle_days | times: 86400 -%}
+              {%- assign cycle_position = now_epoch | modulo: cycle_seconds -%}
+              {%- assign remaining_seconds = cycle_seconds | minus: cycle_position -%}
+              {%- assign end_epoch = now_epoch | plus: remaining_seconds -%}
+              {%- assign end_date = end_epoch | date: '%B %e' | strip -%}
+              {%- if sale_prefix != blank -%}
+                {%- capture sale_text -%}{{ sale_prefix }}: Ends {{ end_date }}{%- endcapture -%}
+              {%- else -%}
+                {%- capture sale_text -%}Ends {{ end_date }}{%- endcapture -%}
+              {%- endif -%}
+            {%- endif -%}
+
+            {%- if sale_text != blank -%}
+              <div class="runwell-bundle-quantity-builder__sale-heading">
+                <span class="runwell-bundle-quantity-builder__sale-line"></span>
+                <span class="runwell-bundle-quantity-builder__sale-text">{{ sale_text }}</span>
+                <span class="runwell-bundle-quantity-builder__sale-line"></span>
+              </div>
+            {%- endif -%}
+
+            {%- if show_scarcity -%}
+              <div class="runwell-bundle-quantity-builder__scarcity">
+                <span class="runwell-bundle-quantity-builder__scarcity-dot"></span>
+                Only {{ fomo_stock_count }} left in stock
+              </div>
+            {%- endif -%}
+          {%- endif -%}
+
+          {%- if tiers and tiers.size > 0 -%}
+            {%- assign has_popular = false -%}
+            {%- for t in tiers -%}
+              {%- if t.popular -%}{%- assign has_popular = true -%}{%- endif -%}
+            {%- endfor -%}
+
+            <form
+              action="{{ routes.cart_add_url }}"
+              method="post"
+              enctype="multipart/form-data"
+              class="runwell-bundle-quantity-builder__form"
+              data-runwell-bundle-form
+            >
+              <input type="hidden" name="form_type" value="product">
+              <input type="hidden" name="utf8" value="✓">
+              <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
+
+              <fieldset class="runwell-bundle-quantity-builder__options" aria-label="Choose quantity">
+                <legend class="visually-hidden">Choose quantity</legend>
+                {%- for t in tiers -%}
+                  {%- assign is_default = false -%}
+                  {%- if has_popular and t.popular -%}
+                    {%- assign is_default = true -%}
+                  {%- elsif has_popular == false and forloop.first -%}
+                    {%- assign is_default = true -%}
+                  {%- endif -%}
+
+                  {%- assign tier_label = t.label -%}
+                  {%- if tier_label == blank -%}
+                    {%- capture tier_label -%}{{ t.qty }}x {{ product.title }}{%- endcapture -%}
+                  {%- endif -%}
+
+                  {%- assign discount_amount = product.price | times: t.discount_pct | divided_by: 100 -%}
+                  {%- assign per_unit_price = product.price | minus: discount_amount -%}
+                  {%- assign total_price = per_unit_price | times: t.qty -%}
+                  {%- assign full_price = product.price | times: t.qty -%}
+                  {%- assign savings = full_price | minus: total_price -%}
+
+                  <label
+                    class="runwell-bundle-quantity-builder__option {% if t.popular %}runwell-bundle-quantity-builder__option--popular{% endif %} {% if is_default %}runwell-bundle-quantity-builder__option--selected{% endif %}"
+                    data-tier-qty="{{ t.qty }}"
+                    data-tier-free-gift="{{ t.free_gift | default: false }}"
+                  >
+                    {%- if t.popular -%}
+                      <span class="runwell-bundle-quantity-builder__popular-badge">MOST POPULAR</span>
+                    {%- endif -%}
+                    <input
+                      type="radio"
+                      name="quantity"
+                      value="{{ t.qty }}"
+                      class="runwell-bundle-quantity-builder__option-input"
+                      data-runwell-tier-radio
+                      {% if is_default %}checked{% endif %}
+                    >
+                    <span class="runwell-bundle-quantity-builder__option-radio" aria-hidden="true"></span>
+                    <span class="runwell-bundle-quantity-builder__option-content">
+                      <span class="runwell-bundle-quantity-builder__option-header">
+                        <span class="runwell-bundle-quantity-builder__option-title">{{ tier_label }}</span>
+                        <span class="runwell-bundle-quantity-builder__option-pricing">
+                          <span class="runwell-bundle-quantity-builder__option-price">{{ total_price | money_without_trailing_zeros }}</span>
+                          {%- if savings > 0 -%}
+                            <span class="runwell-bundle-quantity-builder__option-compare">{{ full_price | money_without_trailing_zeros }}</span>
+                          {%- endif -%}
+                        </span>
+                      </span>
+                      {%- if savings > 0 or t.free_shipping -%}
+                        <span class="runwell-bundle-quantity-builder__option-badges">
+                          {%- if savings > 0 -%}
+                            <span class="runwell-bundle-quantity-builder__badge runwell-bundle-quantity-builder__badge--save">SAVE {{ savings | money_without_trailing_zeros }}</span>
+                          {%- endif -%}
+                          {%- if t.free_shipping -%}
+                            <span class="runwell-bundle-quantity-builder__badge runwell-bundle-quantity-builder__badge--shipping">FREE SHIPPING</span>
+                          {%- endif -%}
+                        </span>
+                      {%- endif -%}
+                      {%- if t.free_gift and free_gift_product != blank -%}
+                        <span class="runwell-bundle-quantity-builder__free-gift">
+                          <span class="runwell-bundle-quantity-builder__gift-icon" aria-hidden="true">&#127873;</span>
+                          <span>+ Free {{ free_gift_product.title }} for a limited time.</span>
+                        </span>
+                      {%- endif -%}
+                    </span>
+                  </label>
+                {%- endfor -%}
+              </fieldset>
+
+              <button
+                type="submit"
+                class="runwell-bundle-quantity-builder__atc button button--full-width"
+                data-runwell-bundle-atc
+                {% if product.selected_or_first_available_variant.available == false %}disabled{% endif %}
+              >
+                <span class="runwell-bundle-quantity-builder__atc-text">
+                  {% if product.selected_or_first_available_variant.available %}ADD TO CART{% else %}SOLD OUT{% endif %}
+                </span>
+                <span class="runwell-bundle-quantity-builder__atc-loading" style="display:none;" aria-hidden="true">Adding…</span>
+              </button>
+            </form>
+          {%- else -%}
+            <p class="runwell-bundle-quantity-builder__empty">
+              No quantity tiers configured. Set
+              <code>runwell.bundle_quantity_tiers</code> on this product
+              to enable the bundle builder.
+            </p>
+          {%- endif -%}
+
+          {%- if section.settings.show_trust_badges -%}
+            <div class="runwell-bundle-quantity-builder__trust">
+              {%- if section.settings.trust_1 != blank -%}<span>&#9989; {{ section.settings.trust_1 }}</span>{%- endif -%}
+              {%- if section.settings.trust_2 != blank -%}<span>&#9989; {{ section.settings.trust_2 }}</span>{%- endif -%}
+              {%- if section.settings.trust_3 != blank -%}<span>&#9989; {{ section.settings.trust_3 }}</span>{%- endif -%}
+            </div>
+          {%- endif -%}
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <script src="{{ 'runwell-bundle-system.js' | asset_url }}" defer="defer"></script>
+{%- endif -%}
+
+{% schema %}
+{
+  "name": "Bundle quantity builder",
+  "tag": "section",
+  "class": "section-runwell-bundle-quantity-builder",
+  "settings": [
+    { "type": "header", "content": "Source product" },
+    { "type": "product", "id": "product", "label": "Product", "info": "The bundle reads runwell.bundle_quantity_tiers + sale_prefix + rating + free gift handle from this product's metafields." },
+
+    { "type": "header", "content": "Sale prefix fallback" },
+    { "type": "text", "id": "sale_prefix", "label": "Sale prefix fallback", "info": "Used only when the product has no runwell.bundle_sale_prefix metafield set." },
+
+    { "type": "header", "content": "Rating display" },
+    { "type": "checkbox", "id": "show_rating", "label": "Show star rating", "default": true },
+
+    { "type": "header", "content": "Trust badges" },
+    { "type": "checkbox", "id": "show_trust_badges", "label": "Show trust badges", "default": true },
+    { "type": "text", "id": "trust_1", "label": "Badge 1", "default": "90-Day Guarantee" },
+    { "type": "text", "id": "trust_2", "label": "Badge 2", "default": "Easy Returns" },
+    { "type": "text", "id": "trust_3", "label": "Badge 3", "default": "Free Shipping" },
+
+    { "type": "header", "content": "Layout" },
+    { "type": "color_scheme", "id": "color_scheme", "label": "Color scheme", "default": "scheme-1" },
+    { "type": "range", "id": "padding_top", "label": "Top padding", "min": 0, "max": 160, "step": 4, "default": 40, "unit": "px" },
+    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "min": 0, "max": 160, "step": 4, "default": 40, "unit": "px" }
+  ],
+  "presets": [
+    { "name": "Bundle: quantity builder", "category": "Runwell" }
+  ]
+}
+{% endschema %}

package/modules/runwell-bundle-system/snippets/runwell-bundle-card.liquid

@@ -13,8 +13,21 @@
 
 {%- if bundle_product != blank -%}
   {%- assign card_variant = variant | default: 'default' -%}
-  {%- assign product = bundle_product -%}
-  {% render 'runwell-bundle-data', product: bundle_product %}
+
+  {%- comment -%}
+    Inline metafield reads. Liquid `render` is scope-isolated, so calling
+    `render 'runwell-bundle-data'` does not leak its assigns back here.
+    We read the values directly off the bundle product to keep the card
+    self-contained.
+  {%- endcomment -%}
+  {%- assign card_mf = bundle_product.metafields.runwell -%}
+  {%- assign bundle_savings_pct = card_mf.bundle_savings_pct.value | default: 0 -%}
+  {%- assign bundle_components = card_mf.bundle_components.value -%}
+  {%- assign bundle_cross_supplier = card_mf.bundle_cross_supplier.value | default: false -%}
+  {%- assign bundle_supplier_count = card_mf.bundle_supplier_count.value | default: 1 -%}
+  {%- assign bundle_price = bundle_product.price -%}
+  {%- assign bundle_subtotal = bundle_product.compare_at_price | default: bundle_product.price -%}
+
   {%- assign component_count = 0 -%}
   {%- if bundle_components and bundle_components.size > 0 -%}
     {%- assign component_count = bundle_components.size -%}

package/modules/runwell-bundle-system/snippets/runwell-bundle-cart-xsell.liquid

@@ -0,0 +1,85 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-cart-xsell.liquid (snippet).
+
+  Surface 4 (bundle xsell), placed INLINE inside a tenant's cart-drawer
+  snippet. Companion to sections/runwell-bundle-cart-xsell.liquid for
+  tenants whose cart drawer lives outside the section-group renderer
+  (e.g. Dawn-shape themes that {% render 'cart-drawer' %} from layout).
+
+  Drops a self-refreshing slot. The JS hook in assets/runwell-bundle-system.js
+  refetches this slot on /cart/{add,change,update,clear} responses.
+
+  Expected usage inside cart-drawer.liquid:
+
+      {%- if cart.item_count > 0 -%}
+        {% render 'runwell-bundle-cart-xsell',
+            fallback_snippet: 'runwell-cart-xsell',
+            eyebrow: 'Complete the stack' %}
+      {%- endif -%}
+
+  Inputs (all optional):
+    fallback_snippet  name of a snippet to render when no bundle match
+    eyebrow           label above the bundle card (default "Complete the stack")
+    cta_label         CTA copy passed through to the card (display-only)
+{%- endcomment -%}
+
+{%- assign xsell_eyebrow = eyebrow | default: 'Complete the stack' -%}
+
+{%- comment -%} Build cart_handles via capture+split: cart.items | map: 'handle' returns empty strings on Dawn-shape themes. {%- endcomment -%}
+{%- capture xsell_cart_handles_csv -%}
+  {%- for item in cart.items -%}{{ item.product.handle }}|{%- endfor -%}
+{%- endcapture -%}
+{%- assign xsell_cart_handles = xsell_cart_handles_csv | strip | split: '|' -%}
+
+{%- assign xsell_index_instance = shop.metaobjects.bundle_index.values | first -%}
+{%- assign xsell_index = xsell_index_instance.entries.value -%}
+
+{%- assign xsell_handle = '' -%}
+{%- assign xsell_score = 0 -%}
+
+{%- if xsell_index and xsell_index.bundles -%}
+  {%- for entry in xsell_index.bundles -%}
+    {%- assign candidate_handle = entry[0] -%}
+    {%- assign candidate_components = entry[1].components -%}
+    {%- if xsell_cart_handles contains candidate_handle -%}{%- continue -%}{%- endif -%}
+
+    {%- assign overlap = 0 -%}
+    {%- assign component_total = 0 -%}
+    {%- for c in candidate_components -%}
+      {%- assign component_total = component_total | plus: 1 -%}
+      {%- if xsell_cart_handles contains c[0] -%}
+        {%- assign overlap = overlap | plus: 1 -%}
+      {%- endif -%}
+    {%- endfor -%}
+
+    {%- if overlap > 0 and overlap < component_total and overlap > xsell_score -%}
+      {%- assign xsell_score = overlap -%}
+      {%- assign xsell_handle = candidate_handle -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+<div id="CartDrawer-XsellSlot" data-runwell-xsell-slot>
+  {%- if xsell_handle != '' -%}
+    {%- assign xsell_product = all_products[xsell_handle] -%}
+    {%- if xsell_product != blank and xsell_product.handle != blank -%}
+      <div class="runwell-bundle-cart-xsell" data-runwell-bundle-xsell>
+        <p class="runwell-bundle-cart-xsell__eyebrow">{{ xsell_eyebrow }}</p>
+        {% render 'runwell-bundle-card', bundle_product: xsell_product, variant: 'compact' %}
+        <p class="runwell-bundle-cart-xsell__hint">
+          You already have {{ xsell_score }} of these. Save by getting the full stack.
+        </p>
+      </div>
+    {%- endif -%}
+  {%- elsif fallback_snippet != blank -%}
+    {%- comment -%}
+      No bundle match: tenants opt into a fallback snippet (e.g. simple
+      cart-cross-sell). The snippet renders into the same slot so the
+      refresh hook can swap it out later when a bundle match arrives.
+    {%- endcomment -%}
+    {% render fallback_snippet %}
+  {%- endif -%}
+</div>
+
+{{ 'runwell-bundle-system.css' | asset_url | stylesheet_tag }}
+<script src="{{ 'runwell-bundle-system.js' | asset_url }}" defer="defer"></script>

package/modules/scratch-popup/README.md

@@ -0,0 +1,88 @@
+# scratch-popup
+
+Mystery-discount scratch popup. Email capture + foil-card scratch-to-reveal that unlocks a discount code per visitor.
+
+**Status:** ready (v0.1.0). Liquid section + CSS + JS implementation complete. See `SPEC.md` for the design doc.
+
+## Install on a tenant store
+
+### 1. Create the 3 discount codes on the store
+
+Use the toolkit's helper script (requires the now-live `write_discounts` scope on Runwell Ops):
+
+```
+bash infrastructure/scripts/shopify/shopify-discount-create.sh <store> MYSTERY10 10 \
+  --title "Mystery discount 10%" --once-per-customer
+
+bash infrastructure/scripts/shopify/shopify-discount-create.sh <store> MYSTERY15 15 \
+  --title "Mystery discount 15%" --once-per-customer
+
+bash infrastructure/scripts/shopify/shopify-discount-create.sh <store> MYSTERY20 20 \
+  --title "Mystery discount 20%" --once-per-customer
+```
+
+Tenant can use any codes / percentages; just make sure the section settings match.
+
+### 2. Drop the section into the theme
+
+Add the `Runwell scratch popup` section to a layout that loads on every page (typically the theme.liquid or the index template). Section presets are pre-filled with the MYSTERY10/15/20 defaults.
+
+### 3. Configure (section settings)
+
+| Setting group | Notes |
+|---|---|
+| Copy | Eyebrow, heading, subheading, button labels |
+| Tier 1 / 2 / 3 | Code (must match step 1), percentage, probability (must sum to 100) |
+| Triggers | First-visit delay (default 8s), exit intent toggle, scratch threshold (default 60%) |
+| Design | Foil color, accent color |
+
+### 4. Verify
+
+- Open the storefront in an incognito window.
+- After the configured delay, the modal appears.
+- Enter an email + click Continue. Email lands in Shopify Customers list with tags `newsletter, scratch-popup`.
+- Scratch the foil. After ~60% erased, the discount auto-reveals.
+- Copy button copies the code. Shop now applies the code at checkout.
+
+## Suppression
+
+Session flag stored at `localStorage.runwell_scratch_seen` for 30 days after reveal or dismiss. Visitor sees the popup once per 30-day window per device.
+
+## What it replaces
+
+| Replaces | Notes |
+|---|---|
+| Privy / Justuno "Spin to win" | KH (Patrick Franco) and Claspo benchmark both say spin-the-wheel is gimmicky and underperforms. |
+| Fixed "10% off" / WELCOME15 popups | Mystery mechanic creates curiosity; perceived value is higher. |
+| Generic "enter email for updates" forms | Forms with no incentive are dead weight. |
+
+## Why mystery-scratch, not spin-the-wheel
+
+Cited in `_knowledge-hub/marketing/2026-03-07-rating-email-capture-popups-for-ecommerce-stores.md`:
+
+- Mystery discount: **Great** (creates curiosity, interactive for cold traffic)
+- Spin the wheel: **Avoid** (feels gimmicky now)
+- Free gift, bundle discount: Great
+- Plain "enter email for updates": Avoid
+
+Plus Claspo benchmark (779M popup impressions): scratch card 11.29% conversion vs. 3.53% baseline (3.2x lift).
+
+## Scopes required on the app installing this module
+
+| Scope | Used for |
+|---|---|
+| `write_discounts` | Generate one-time discount codes per visitor email |
+| `read_discounts` | Look up + dedupe existing codes |
+| `write_customers` | Bind discount code to the captured email |
+| `read_customers` | Email dedup |
+
+All four are live on Runwell Ops (`runwell-ops-3`).
+
+## First implementation target
+
+Lushi v2 storefront. See `claude-PM/_clients/capital-v/lushi/tickets/mystery-scratch-popup.md`.
+
+## Related modules
+
+- `exit-intent` (sibling display-layer module; pattern to lift from)
+- `cart-cross-sell` (also a conversion-category module)