@runwell/shopify-toolkit 0.21.0 → 0.24.0

package/modules/runwell-bundle-system/snippets/runwell-bundle-byob-picker-grid.liquid

@@ -0,0 +1,72 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-byob-picker-grid.liquid.
+  Mode C, default layout. Flat checkbox grid of all candidates. Min/max
+  picks enforced via JS.
+
+  Inputs:
+    bundle_byob_candidates, bundle_byob_min_picks, bundle_byob_max_picks,
+    bundle_byob_required_handles, bundle_pricing_model, bundle_pricing_value.
+{%- endcomment -%}
+
+{%- if bundle_byob_candidates and bundle_byob_candidates.size > 0 -%}
+  {%- assign required_handles = '' -%}
+  {%- if bundle_byob_required_handles -%}
+    {%- capture required_handles -%}
+      {%- for r in bundle_byob_required_handles -%}{{ r.handle }},{%- endfor -%}
+    {%- endcapture -%}
+  {%- endif -%}
+
+  <div
+    class="runwell-bundle-system__byob-picker runwell-bundle-system__byob-picker--grid"
+    data-runwell-byob-picker
+    data-byob-layout="grid"
+    data-byob-min="{{ bundle_byob_min_picks }}"
+    data-byob-max="{{ bundle_byob_max_picks }}"
+    data-byob-pricing-model="{{ bundle_pricing_model }}"
+    data-byob-pricing-value="{{ bundle_pricing_value | json | escape }}"
+  >
+    {%- for candidate in bundle_byob_candidates -%}
+      {%- assign is_required = false -%}
+      {%- if required_handles contains candidate.handle -%}{%- assign is_required = true -%}{%- endif -%}
+      {%- assign is_available = candidate.available | default: true -%}
+
+      <label
+        class="runwell-bundle-system__byob-candidate{% if is_required %} runwell-bundle-system__byob-candidate--required{% endif %}{% unless is_available %} runwell-bundle-system__byob-candidate--unavailable{% endunless %}"
+        data-handle="{{ candidate.handle }}"
+        data-price="{{ candidate.price }}"
+        data-variant-id="{{ candidate.selected_or_first_available_variant.id }}"
+      >
+        <input
+          type="checkbox"
+          class="runwell-bundle-system__byob-input"
+          name="byob-pick"
+          value="{{ candidate.handle }}"
+          {% if is_required %}checked disabled{% endif %}
+          {% unless is_available %}disabled{% endunless %}
+        >
+        <span class="runwell-bundle-system__byob-candidate-media">
+          {%- if candidate.featured_image -%}
+            {{ candidate.featured_image | image_url: width: 240 | image_tag:
+              width: 120,
+              height: 120,
+              loading: 'lazy',
+              class: 'runwell-bundle-system__byob-candidate-thumb',
+              alt: candidate.title
+            }}
+          {%- endif -%}
+        </span>
+        <span class="runwell-bundle-system__byob-candidate-body">
+          <span class="runwell-bundle-system__byob-candidate-title">{{ candidate.title }}</span>
+          <span class="runwell-bundle-system__byob-candidate-price">{{ candidate.price | money }}</span>
+          {%- if is_required -%}
+            <span class="runwell-bundle-system__byob-candidate-badge">Always included</span>
+          {%- elsif is_available == false -%}
+            <span class="runwell-bundle-system__byob-candidate-badge">Sold out</span>
+          {%- endif -%}
+        </span>
+      </label>
+    {%- endfor -%}
+  </div>
+{%- else -%}
+  <p class="runwell-bundle-system__empty">No BYOB candidates configured for this bundle.</p>
+{%- endif -%}

package/modules/runwell-bundle-system/snippets/runwell-bundle-byob-picker-radio.liquid

@@ -0,0 +1,77 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-byob-picker-radio.liquid.
+  Mode C, one-pick-per-category layout. Total picks equals category count.
+  Each category renders as a radio group; total picks across categories
+  is the category count exactly.
+
+  Inputs:
+    bundle_byob_candidates, bundle_byob_categories ([{label, handles}]),
+    bundle_byob_required_handles, bundle_pricing_model, bundle_pricing_value.
+{%- endcomment -%}
+
+{%- if bundle_byob_categories and bundle_byob_categories.size > 0 -%}
+  {%- assign required_handles = '' -%}
+  {%- if bundle_byob_required_handles -%}
+    {%- capture required_handles -%}
+      {%- for r in bundle_byob_required_handles -%}{{ r.handle }},{%- endfor -%}
+    {%- endcapture -%}
+  {%- endif -%}
+  {%- assign cat_count = bundle_byob_categories.size -%}
+
+  <div
+    class="runwell-bundle-system__byob-picker runwell-bundle-system__byob-picker--radio"
+    data-runwell-byob-picker
+    data-byob-layout="radio"
+    data-byob-min="{{ cat_count }}"
+    data-byob-max="{{ cat_count }}"
+    data-byob-pricing-model="{{ bundle_pricing_model }}"
+    data-byob-pricing-value="{{ bundle_pricing_value | json | escape }}"
+  >
+    {%- for category in bundle_byob_categories -%}
+      {%- assign cat_idx = forloop.index -%}
+      <fieldset class="runwell-bundle-system__byob-radio-group">
+        <legend class="runwell-bundle-system__byob-radio-legend">{{ category.label }}</legend>
+        {%- for handle in category.handles -%}
+          {%- assign candidate = all_products[handle] -%}
+          {%- if candidate != blank -%}
+            {%- assign is_required = false -%}
+            {%- if required_handles contains handle -%}{%- assign is_required = true -%}{%- endif -%}
+            <label
+              class="runwell-bundle-system__byob-candidate runwell-bundle-system__byob-candidate--radio{% if is_required %} runwell-bundle-system__byob-candidate--required{% endif %}"
+              data-handle="{{ candidate.handle }}"
+              data-price="{{ candidate.price }}"
+              data-variant-id="{{ candidate.selected_or_first_available_variant.id }}"
+              data-category="{{ category.label | escape }}"
+            >
+              <input
+                type="radio"
+                class="runwell-bundle-system__byob-input"
+                name="byob-pick-cat-{{ cat_idx }}"
+                value="{{ candidate.handle }}"
+                {% if is_required or forloop.first %}checked{% endif %}
+                {% unless candidate.available %}disabled{% endunless %}
+              >
+              <span class="runwell-bundle-system__byob-candidate-media">
+                {%- if candidate.featured_image -%}
+                  {{ candidate.featured_image | image_url: width: 240 | image_tag:
+                    width: 80,
+                    height: 80,
+                    loading: 'lazy',
+                    class: 'runwell-bundle-system__byob-candidate-thumb',
+                    alt: candidate.title
+                  }}
+                {%- endif -%}
+              </span>
+              <span class="runwell-bundle-system__byob-candidate-body">
+                <span class="runwell-bundle-system__byob-candidate-title">{{ candidate.title }}</span>
+                <span class="runwell-bundle-system__byob-candidate-price">{{ candidate.price | money }}</span>
+              </span>
+            </label>
+          {%- endif -%}
+        {%- endfor -%}
+      </fieldset>
+    {%- endfor -%}
+  </div>
+{%- else -%}
+  <p class="runwell-bundle-system__empty">Radio layout requires bundle_byob_categories.</p>
+{%- endif -%}

package/modules/runwell-bundle-system/snippets/runwell-bundle-byob-picker.liquid

@@ -0,0 +1,71 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-byob-picker.liquid.
+  Mode C router. Reads bundle_byob_layout and delegates to one of
+  three layout snippets:
+    - grid (default)
+    - accordion
+    - radio (one pick per category)
+
+  Inputs (all forwarded to the layout snippet):
+    product, bundle_pricing_model, bundle_pricing_value,
+    bundle_byob_candidates, bundle_byob_min_picks, bundle_byob_max_picks,
+    bundle_byob_layout, bundle_byob_categories, bundle_byob_required_handles.
+
+  Fallback: if layout == 'radio' but no categories are set, falls back
+  to grid and emits a console warning client side.
+{%- endcomment -%}
+
+{%- assign layout = bundle_byob_layout | default: 'grid' -%}
+{%- if layout == 'radio' and bundle_byob_categories == blank -%}
+  {%- assign layout = 'grid' -%}
+{%- endif -%}
+
+{% render 'runwell-bundle-byob-summary',
+  bundle_pricing_model: bundle_pricing_model,
+  bundle_pricing_value: bundle_pricing_value,
+  bundle_byob_min_picks: bundle_byob_min_picks,
+  bundle_byob_max_picks: bundle_byob_max_picks
+%}
+
+{%- form 'product', product, class: 'runwell-bundle-system__form runwell-bundle-system__byob-form', novalidate: 'novalidate' -%}
+  {%- if layout == 'grid' -%}
+    {% render 'runwell-bundle-byob-picker-grid',
+      bundle_byob_candidates: bundle_byob_candidates,
+      bundle_byob_min_picks: bundle_byob_min_picks,
+      bundle_byob_max_picks: bundle_byob_max_picks,
+      bundle_byob_required_handles: bundle_byob_required_handles,
+      bundle_pricing_model: bundle_pricing_model,
+      bundle_pricing_value: bundle_pricing_value
+    %}
+  {%- elsif layout == 'accordion' -%}
+    {% render 'runwell-bundle-byob-picker-accordion',
+      bundle_byob_candidates: bundle_byob_candidates,
+      bundle_byob_min_picks: bundle_byob_min_picks,
+      bundle_byob_max_picks: bundle_byob_max_picks,
+      bundle_byob_categories: bundle_byob_categories,
+      bundle_byob_required_handles: bundle_byob_required_handles,
+      bundle_pricing_model: bundle_pricing_model,
+      bundle_pricing_value: bundle_pricing_value
+    %}
+  {%- elsif layout == 'radio' -%}
+    {% render 'runwell-bundle-byob-picker-radio',
+      bundle_byob_candidates: bundle_byob_candidates,
+      bundle_byob_categories: bundle_byob_categories,
+      bundle_byob_required_handles: bundle_byob_required_handles,
+      bundle_pricing_model: bundle_pricing_model,
+      bundle_pricing_value: bundle_pricing_value
+    %}
+  {%- endif -%}
+
+  <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
+
+  <button
+    type="submit"
+    name="add"
+    class="runwell-bundle-system__atc button button--primary button--full-width"
+    data-runwell-byob-atc
+    disabled
+  >
+    <span class="runwell-bundle-system__atc-label">Add to cart</span>
+  </button>
+{%- endform -%}

package/modules/runwell-bundle-system/snippets/runwell-bundle-byob-summary.liquid

@@ -0,0 +1,39 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-byob-summary.liquid.
+  Live counter + price for Mode C BYOB. Numbers update from JS on every
+  selection change. Static fallback on first render shows zeros.
+
+  Inputs:
+    bundle_pricing_model, bundle_pricing_value,
+    bundle_byob_min_picks, bundle_byob_max_picks.
+{%- endcomment -%}
+
+<div
+  class="runwell-bundle-system__byob-summary"
+  data-runwell-byob-summary
+  data-byob-min="{{ bundle_byob_min_picks }}"
+  data-byob-max="{{ bundle_byob_max_picks }}"
+  data-byob-pricing-model="{{ bundle_pricing_model }}"
+  data-byob-pricing-value="{{ bundle_pricing_value | json | escape }}"
+>
+  <p class="runwell-bundle-system__byob-counter" data-runwell-byob-counter>
+    <span data-runwell-byob-selected>0</span>
+    <span class="runwell-bundle-system__byob-counter-of">of</span>
+    <span data-runwell-byob-target>{{ bundle_byob_max_picks }}</span>
+    <span class="runwell-bundle-system__byob-counter-label">selected</span>
+  </p>
+
+  <div class="runwell-bundle-system__byob-pricing">
+    <span class="runwell-bundle-system__byob-pricing-subtotal" data-runwell-byob-subtotal hidden>
+      <s data-runwell-byob-subtotal-amount>{{ 0 | money }}</s>
+    </span>
+    <span class="runwell-bundle-system__byob-pricing-current" data-runwell-byob-total>{{ 0 | money }}</span>
+    <span class="runwell-bundle-system__byob-pricing-badge" data-runwell-byob-savings hidden>
+      Save <span data-runwell-byob-savings-amount></span>
+    </span>
+  </div>
+
+  <p class="runwell-bundle-system__byob-helper" data-runwell-byob-helper>
+    Pick at least <strong>{{ bundle_byob_min_picks }}</strong>{% if bundle_byob_max_picks != bundle_byob_min_picks %}, up to <strong>{{ bundle_byob_max_picks }}</strong>{% endif %} to continue.
+  </p>
+</div>

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/runwell-bundle-system/snippets/runwell-bundle-data.liquid

@@ -32,6 +32,14 @@
 {%- assign bundle_supplier_count = mf.bundle_supplier_count.value | default: 1 -%}
 {%- assign bundle_savings_pct_pre = mf.bundle_savings_pct.value -%}
 
+{%- comment -%} Mode C BYOB metafields (BS-201..BS-203). {%- endcomment -%}
+{%- assign bundle_byob_candidates = mf.bundle_byob_candidates.value -%}
+{%- assign bundle_byob_min_picks = mf.bundle_byob_min_picks.value | default: 1 -%}
+{%- assign bundle_byob_max_picks = mf.bundle_byob_max_picks.value | default: 3 -%}
+{%- assign bundle_byob_layout = mf.bundle_byob_layout.value | default: 'grid' -%}
+{%- assign bundle_byob_categories = mf.bundle_byob_categories.value -%}
+{%- assign bundle_byob_required_handles = mf.bundle_byob_required_handles.value -%}
+
 {%- comment -%} Compute subtotal for multi_product mode by walking components. {%- endcomment -%}
 {%- assign bundle_subtotal = 0 -%}
 {%- if bundle_components and bundle_components.size > 0 -%}

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)

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)