@runwell/shopify-toolkit 0.1.0 → 0.3.0

package/modules/gift-with-purchase/assets/runwell-gwp.js

@@ -0,0 +1,42 @@
+/* Runwell gift-with-purchase auto-adder. When the cart drawer renders
+   a [data-runwell-gwp] element AND the configured gift product is not
+   already in cart, this script POSTs to /cart/add.js to add it.
+   Quantity is locked to 1. The merchant should also create a
+   "Gift" discount in Shopify that makes the gift product 100% off when
+   cart total >= threshold (so the auto-added line is free). */
+(function () {
+  if (typeof window === 'undefined') return;
+
+  function autoAddGift() {
+    var unlocked = document.querySelector('.runwell-gwp--unlocked');
+    if (!unlocked) return;
+    var giftHandle = unlocked.getAttribute('data-gift-handle');
+    if (!giftHandle) return;
+    if (window._runwellGwpAdded) return;
+    window._runwellGwpAdded = true;
+
+    fetch('/products/' + giftHandle + '.js')
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (product) {
+        if (!product) return;
+        var variantId = product.variants && product.variants[0] && product.variants[0].id;
+        if (!variantId) return;
+        return fetch('/cart/add.js', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
+          body: JSON.stringify({ id: variantId, quantity: 1, properties: { _runwell_gift: '1' } })
+        });
+      })
+      .then(function () {
+        if (typeof window.fetchCart === 'function') window.fetchCart();
+        document.dispatchEvent(new CustomEvent('runwell:cart:refresh'));
+      })
+      .catch(function () { window._runwellGwpAdded = false; });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoAddGift);
+  } else {
+    autoAddGift();
+  }
+})();

package/modules/gift-with-purchase/module.json

@@ -0,0 +1,32 @@
+{
+  "name": "gift-with-purchase",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Auto-add a gift product to the cart when total clears a threshold. Shows progress message before unlock and confirmation after. Combine with a 100%-off discount on the gift SKU so it lands free.",
+  "files": {
+    "snippets": ["snippets/runwell-gwp.liquid"],
+    "assets": ["assets/runwell-gwp.js"]
+  },
+  "config": {
+    "schema": {
+      "threshold_cents": { "type": "number", "default": 10000, "label": "Spend threshold in cents (e.g. 10000 = $100)" },
+      "gift_handle": { "type": "string", "default": "free-gift", "label": "Product handle for the gift" },
+      "unlocked_message": { "type": "string", "default": "You earned a free gift." },
+      "locked_message_suffix": { "type": "string", "default": "a free gift." }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-gift-product",
+      "label": "Create the gift product",
+      "url": "https://admin.shopify.com/store/{store_handle}/products/new",
+      "summary": "Create a product matching the gift_handle config (default: free-gift). Set a baseline price (e.g. $10) so it shows value. Inventory: enough for forecast monthly volume."
+    },
+    {
+      "id": "create-gift-discount",
+      "label": "Create the 100% off discount on the gift product",
+      "url": "https://admin.shopify.com/store/{store_handle}/discounts/new",
+      "summary": "Discount type: Amount off products. Code or Automatic: Automatic preferred. Value: 100%. Applies to: Specific products > select the gift product. Minimum requirement: Subtotal >= $100 (matching threshold_cents). Customer eligibility: All customers. So the auto-added gift line lands free at checkout."
+    }
+  ]
+}

package/modules/gift-with-purchase/snippets/runwell-gwp.liquid

@@ -0,0 +1,30 @@
+{%- comment -%}
+  Runwell gift-with-purchase. Shows a "free gift unlocked" message in
+  the cart drawer when cart total clears the threshold. The actual gift
+  product gets auto-added via runwell-gwp.js (cart.js write).
+  Render inside cart-drawer.liquid:
+
+  {% render 'runwell-gwp' %}
+{%- endcomment -%}
+
+{%- assign threshold_cents = {{config.threshold_cents}} -%}
+{%- assign gift_handle = '{{config.gift_handle}}' -%}
+{%- assign cart_handles = cart.items | map: 'handle' -%}
+
+{%- if cart.total_price >= threshold_cents -%}
+  <div class="runwell-gwp runwell-gwp--unlocked" data-runwell-gwp data-gift-handle="{{ gift_handle }}">
+    <p class="runwell-gwp__msg">{{config.unlocked_message}}</p>
+    {%- unless cart_handles contains gift_handle -%}
+      <p class="runwell-gwp__detail">Adding to your bag now.</p>
+    {%- endunless -%}
+  </div>
+{%- elsif cart.item_count > 0 -%}
+  {%- assign remaining = threshold_cents | minus: cart.total_price -%}
+  <div class="runwell-gwp runwell-gwp--locked">
+    <p class="runwell-gwp__msg">
+      Spend <strong>{{ remaining | money }}</strong> more for {{config.locked_message_suffix}}
+    </p>
+  </div>
+{%- endif -%}
+
+<script src="{{ 'runwell-gwp.js' | asset_url }}" defer="defer"></script>

package/modules/loyalty-tiers/README.md

@@ -0,0 +1,45 @@
+# loyalty-tiers
+
+Lifetime-spend tier card on the customer account page. Combined with Shopify Flow auto-tagging and tag-targeted discounts, replaces Smile.io / Yotpo Loyalty / LoyaltyLion. App-free.
+
+## Why tiers, not points
+
+Points-based loyalty needs:
+- Real-time balance updates (Shopify Flow runs are async, lagging 1 to 5 minutes)
+- A custom redemption endpoint that issues unique discount codes
+- Customer education that's expensive at low scale
+
+Tiers deliver the same psychological lever (status + reward) using only Shopify primitives: `customer.total_spent`, customer tags, Shopify Flow, tag-targeted discounts.
+
+## Files
+
+- `sections/runwell-tier-card.liquid`. Tier card section that renders on the customer account template.
+
+## How to use
+
+1. Run the merchant admin steps in `module.json`:
+   - Create Shopify Flow workflows that auto-tag customers as their lifetime spend crosses the thresholds
+   - Create tier-targeted discount codes (TIER_INSIDER 10%, TIER_FOUNDER 15%)
+   - Add the tier card section to `templates/customers/account.json`
+2. Sync: `runwell-shopify sync`
+3. The tier card renders for any logged-in customer; tier auto-derives from `customer.total_spent`
+
+## Default tiers
+
+| Tier | Threshold | Perk |
+|---|---|---|
+| Curator | $0 (everyone) | Free ship over $75, 30-day returns |
+| Insider | $250 | 10% off code (auto-applied via tag), first-look on new arrivals |
+| Founder | $750 | 15% off code, free shipping always, free sample |
+
+## Config
+
+All tier names, thresholds, and perk percentages are configurable per client. See `module.json` config schema.
+
+## Replaces
+
+Smile.io, Yotpo Loyalty, Stamped Loyalty, LoyaltyLion (display layer; rewards still issued via Shopify Discounts).
+
+## Plan requirement
+
+Works on **Shopify Basic and up**. Shopify Flow is included free on all plans (with a daily action limit).

package/modules/loyalty-tiers/module.json

@@ -0,0 +1,40 @@
+{
+  "name": "loyalty-tiers",
+  "version": "0.1.0",
+  "category": "customer",
+  "description": "Lifetime-spend tier card on the customer account page. Combined with Shopify Flow auto-tagging and tag-targeted discounts, replaces Smile.io / Yotpo Loyalty / LoyaltyLion. App-free.",
+  "files": {
+    "sections": ["sections/runwell-tier-card.liquid"]
+  },
+  "config": {
+    "schema": {
+      "tier_0_name": { "type": "string", "default": "Curator" },
+      "tier_1_name": { "type": "string", "default": "Insider" },
+      "tier_1_threshold": { "type": "number", "default": 250 },
+      "tier_1_perk_pct": { "type": "number", "default": 10 },
+      "tier_2_name": { "type": "string", "default": "Founder" },
+      "tier_2_threshold": { "type": "number", "default": 750 },
+      "tier_2_perk_pct": { "type": "number", "default": 15 }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-tier-tags-and-flows",
+      "label": "Create Shopify Flow workflows for tier auto-tagging",
+      "url": "https://admin.shopify.com/store/{store_handle}/apps",
+      "summary": "Apps > Shopify Flow > Create workflow. Trigger: Order paid. Filter: customer.amount_spent.amount >= 250. Action: Add customer tag runwell-tier-insider + send email. Repeat for >= 750 with runwell-tier-founder."
+    },
+    {
+      "id": "create-tier-discounts",
+      "label": "Create tier-targeted discount codes",
+      "url": "https://admin.shopify.com/store/{store_handle}/discounts/new",
+      "summary": "Two discount codes: TIER_INSIDER (10%) targeting customers tagged runwell-tier-insider, TIER_FOUNDER (15%) targeting customers tagged runwell-tier-founder. Both: amount off order, sitewide, no min, unlimited uses, automatic per customer."
+    },
+    {
+      "id": "add-tier-card-to-account",
+      "label": "Add the tier card to customer account",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Edit the customer/account.json template (or via theme editor on the Customer account template). Add the Runwell tier card section before the order list."
+    }
+  ]
+}

package/modules/loyalty-tiers/sections/runwell-tier-card.liquid

@@ -0,0 +1,86 @@
+{%- comment -%}
+  Runwell loyalty tier card. Renders on the customer account page
+  showing current tier + progress to next tier. Drives spend tiers via
+  Shopify Flow workflows that auto-tag customers (see admin_steps).
+  Replaces Smile.io / Yotpo Loyalty / LoyaltyLion display layer.
+{%- endcomment -%}
+
+{%- if customer != blank -%}
+  {%- assign spend = customer.total_spent | divided_by: 100.0 -%}
+  {%- assign current_tier = section.settings.tier_0_name -%}
+  {%- assign current_perk_pct = section.settings.tier_0_perk -%}
+  {%- assign next_threshold = section.settings.tier_1_threshold -%}
+  {%- assign next_tier = section.settings.tier_1_name -%}
+
+  {%- if spend >= section.settings.tier_2_threshold -%}
+    {%- assign current_tier = section.settings.tier_2_name -%}
+    {%- assign current_perk_pct = section.settings.tier_2_perk -%}
+    {%- assign next_threshold = 0 -%}
+    {%- assign next_tier = blank -%}
+  {%- elsif spend >= section.settings.tier_1_threshold -%}
+    {%- assign current_tier = section.settings.tier_1_name -%}
+    {%- assign current_perk_pct = section.settings.tier_1_perk -%}
+    {%- assign next_threshold = section.settings.tier_2_threshold -%}
+    {%- assign next_tier = section.settings.tier_2_name -%}
+  {%- endif -%}
+
+  <section class="runwell-tier" aria-labelledby="runwell-tier-heading">
+    <div class="runwell-tier__inner">
+      <header class="runwell-tier__header">
+        <p class="runwell-tier__eyebrow">{{ section.settings.eyebrow }}</p>
+        <h2 id="runwell-tier-heading" class="runwell-tier__name">{{ current_tier }}</h2>
+        {%- if current_perk_pct > 0 -%}
+          <p class="runwell-tier__perk">{{ current_perk_pct }}% off every order, applied automatically at checkout.</p>
+        {%- endif -%}
+      </header>
+
+      {%- if next_tier != blank -%}
+        {%- assign remaining = next_threshold | minus: spend -%}
+        {%- assign pct = spend | times: 100.0 | divided_by: next_threshold -%}
+        {%- if pct > 100 -%}{%- assign pct = 100 -%}{%- endif -%}
+        <div class="runwell-tier__progress">
+          <p class="runwell-tier__progress-label">${{ remaining | round }} to <strong>{{ next_tier }}</strong></p>
+          <div class="runwell-tier__progress-track" aria-hidden="true">
+            <div class="runwell-tier__progress-fill" style="width: {{ pct }}%"></div>
+          </div>
+        </div>
+      {%- else -%}
+        <p class="runwell-tier__topped">You're at the top tier. Welcome to the inside.</p>
+      {%- endif -%}
+
+      <ul class="runwell-tier__perks-list">
+        <li>Free shipping over $75</li>
+        <li>30-day satisfaction promise</li>
+        {%- if customer.tags contains 'runwell-tier-insider' or customer.tags contains 'runwell-tier-founder' -%}
+          <li>First-look access on new arrivals</li>
+        {%- endif -%}
+        {%- if customer.tags contains 'runwell-tier-founder' -%}
+          <li>Free shipping always</li>
+          <li>Free sample with every order</li>
+        {%- endif -%}
+      </ul>
+    </div>
+  </section>
+{%- endif -%}
+
+{% schema %}
+{
+  "name": "Runwell tier card",
+  "tag": "section",
+  "class": "section-runwell-tier",
+  "settings": [
+    { "type": "text", "id": "eyebrow", "label": "Eyebrow", "default": "Your tier" },
+    { "type": "text", "id": "tier_0_name", "label": "Tier 0 name", "default": "Curator" },
+    { "type": "number", "id": "tier_0_perk", "label": "Tier 0 perk %", "default": 0 },
+    { "type": "text", "id": "tier_1_name", "label": "Tier 1 name", "default": "Insider" },
+    { "type": "number", "id": "tier_1_threshold", "label": "Tier 1 spend threshold ($)", "default": 250 },
+    { "type": "number", "id": "tier_1_perk", "label": "Tier 1 perk %", "default": 10 },
+    { "type": "text", "id": "tier_2_name", "label": "Tier 2 name", "default": "Founder" },
+    { "type": "number", "id": "tier_2_threshold", "label": "Tier 2 spend threshold ($)", "default": 750 },
+    { "type": "number", "id": "tier_2_perk", "label": "Tier 2 perk %", "default": 15 }
+  ],
+  "presets": [
+    { "name": "Runwell tier card" }
+  ]
+}
+{% endschema %}

package/modules/product-badges/README.md

@@ -0,0 +1,35 @@
+# product-badges
+
+Tag-driven product card badges (Best seller / New / Editor's pick). Renders inside the card-product snippet.
+
+## Files
+
+- `snippets/runwell-product-badges.liquid`
+
+## How to use
+
+In `snippets/card-product.liquid` near the existing `card__badge` block:
+
+```liquid
+{% render 'runwell-product-badges', product: card_product %}
+```
+
+## Tags
+
+- Tag a product with `best-seller` to render the Best seller badge
+- Tag with `new` for the New badge
+- Tag with `editor-pick` for the Editor's pick badge
+
+Tags are added in Shopify admin: Products > {product} > Tags.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `label_best_seller` | `Best seller` | Localise per locale |
+| `label_new` | `New` | Localise per locale |
+| `label_editor_pick` | `Editor's pick` | Localise per locale |
+
+## Replaces
+
+Badge widgets in Vitals, BSS, and similar.

package/modules/product-badges/module.json

@@ -0,0 +1,16 @@
+{
+  "name": "product-badges",
+  "version": "0.1.0",
+  "category": "social-proof",
+  "description": "Tag-driven badges on product cards (Best seller, New, Editor's pick). Native, no app.",
+  "files": {
+    "snippets": ["snippets/runwell-product-badges.liquid"]
+  },
+  "config": {
+    "schema": {
+      "label_best_seller": { "type": "string", "default": "Best seller" },
+      "label_new": { "type": "string", "default": "New" },
+      "label_editor_pick": { "type": "string", "default": "Editor's pick" }
+    }
+  }
+}

package/modules/product-badges/snippets/runwell-product-badges.liquid

@@ -0,0 +1,19 @@
+{%- comment -%}
+  Runwell product badges. Renders one badge per product card based on
+  product tags. Use inside snippets/card-product.liquid:
+
+  {% render 'runwell-product-badges', product: card_product %}
+
+  Tag-driven for v1 (best-seller, new, editor-pick). Future variants
+  could read from a metafield to support custom labels per product.
+{%- endcomment -%}
+
+{%- if product != blank -%}
+  {%- if product.tags contains 'best-seller' -%}
+    <span class="badge badge--bottom-left runwell-badge runwell-badge--best">{{config.label_best_seller}}</span>
+  {%- elsif product.tags contains 'new' -%}
+    <span class="badge badge--bottom-left runwell-badge runwell-badge--new">{{config.label_new}}</span>
+  {%- elsif product.tags contains 'editor-pick' -%}
+    <span class="badge badge--bottom-left runwell-badge runwell-badge--editor">{{config.label_editor_pick}}</span>
+  {%- endif -%}
+{%- endif -%}

package/modules/quantity-breaks/README.md

@@ -0,0 +1,33 @@
+# quantity-breaks
+
+Tiered quantity-discount display on the PDP. Reads breaks from product metafield `runwell.quantity_breaks`. Replaces volume discount apps for the display layer.
+
+## Files
+
+- `snippets/runwell-quantity-breaks.liquid`. PDP snippet rendering the tier table.
+
+## How to use
+
+1. Run admin steps in `module.json`:
+   - Define the `runwell.quantity_breaks` metafield (Settings > Custom data > Products)
+   - Set the metafield value per product (JSON: `[{qty: 2, discount_pct: 10}, ...]`)
+   - Create a Shopify Function discount that mirrors the metafield to actually apply the discount at checkout
+2. Render the snippet in `sections/main-product.liquid` near the price block:
+   ```liquid
+   {% render 'runwell-quantity-breaks', product: product %}
+   ```
+
+## Display only by default
+
+This module is display-only. The actual discount enforcement is a Shopify Functions discount the merchant configures separately. Without the function, the table renders but the cart will not apply the savings.
+
+## Replaces
+
+Volume discount apps (Bold Quantity Breaks, Discount Master) for the display layer. The discount engine is replaced by Shopify Functions (free, native).
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `eyebrow` | `Buy more, save more` | Tag above the tier list |
+| `fineprint` | `Discount applied automatically at checkout.` | Microcopy under the tier list |

package/modules/quantity-breaks/module.json

@@ -0,0 +1,35 @@
+{
+  "name": "quantity-breaks",
+  "version": "0.1.0",
+  "category": "catalog",
+  "description": "Tiered quantity-discount display on the PDP. Reads breaks from product metafield runwell.quantity_breaks. The actual discount is applied via Shopify Functions configured per merchant.",
+  "files": {
+    "snippets": ["snippets/runwell-quantity-breaks.liquid"]
+  },
+  "config": {
+    "schema": {
+      "eyebrow": { "type": "string", "default": "Buy more, save more" },
+      "fineprint": { "type": "string", "default": "Discount applied automatically at checkout." }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "define-breaks-metafield",
+      "label": "Define the runwell.quantity_breaks product metafield",
+      "url": "https://admin.shopify.com/store/{store_handle}/settings/custom_data/products/metafields",
+      "summary": "Settings > Custom data > Products > Add definition. Namespace: runwell. Key: quantity_breaks. Type: JSON. Validation: must be a list of {qty, discount_pct}."
+    },
+    {
+      "id": "set-product-breaks",
+      "label": "Set quantity breaks per product",
+      "url": "https://admin.shopify.com/store/{store_handle}/products",
+      "summary": "Edit each product where quantity discounts apply. In the Metafields section, set runwell.quantity_breaks to a JSON value like: [{\"qty\": 2, \"discount_pct\": 10}, {\"qty\": 3, \"discount_pct\": 15}]."
+    },
+    {
+      "id": "create-discount-function",
+      "label": "Create a Shopify Functions discount that mirrors the metafield",
+      "url": "https://shopify.dev/docs/apps/build/discounts/sample-apps",
+      "summary": "Build a Shopify Function (or use an existing free Functions app like 'Volume Discount Builder') that reads runwell.quantity_breaks per line item and applies the matching discount. Without this, the metafield is display-only."
+    }
+  ]
+}

package/modules/quantity-breaks/snippets/runwell-quantity-breaks.liquid

@@ -0,0 +1,28 @@
+{%- comment -%}
+  Runwell quantity breaks display. Shows tiered "buy more, save more"
+  pricing on the PDP. Reads from product metafield runwell.quantity_breaks
+  which is a JSON list of {qty, discount_pct}. The actual discount is
+  applied via Shopify Functions (configured per merchant) so the cart
+  reflects the savings at checkout.
+  Render inside main-product.liquid:
+  {% render 'runwell-quantity-breaks', product: product %}
+{%- endcomment -%}
+
+{%- if product != blank -%}
+  {%- assign breaks = product.metafields.runwell.quantity_breaks.value -%}
+  {%- if breaks != blank and breaks.size > 0 -%}
+    <div class="runwell-qty-breaks" aria-label="Quantity savings">
+      <p class="runwell-qty-breaks__eyebrow">{{config.eyebrow}}</p>
+      <ul class="runwell-qty-breaks__list">
+        {%- for tier in breaks -%}
+          <li class="runwell-qty-breaks__item">
+            <span class="runwell-qty-breaks__qty">{{ tier.qty }}+</span>
+            <span class="runwell-qty-breaks__discount">{{ tier.discount_pct }}% off</span>
+            {%- assign tier_price = product.price | times: 100.0 | minus: product.price | times: tier.discount_pct | divided_by: 100.0 -%}
+          </li>
+        {%- endfor -%}
+      </ul>
+      <p class="runwell-qty-breaks__fineprint">{{config.fineprint}}</p>
+    </div>
+  {%- endif -%}
+{%- endif -%}

package/modules/quick-view/README.md

@@ -0,0 +1,36 @@
+# quick-view
+
+Modal product quick-view. Click an eye icon on a product card; modal opens with image, variant picker, qty, ATC. Replaces Globo Quick View, Pagefly QV, Vitals QV.
+
+## Files
+
+- `assets/runwell-quickview.js`. Core modal + variant logic.
+- `snippets/runwell-quickview-modal.liquid`. Single shared modal shell rendered once at body end.
+- `snippets/runwell-quickview-trigger.liquid`. Eye icon trigger to drop into card-product.
+
+## How to use
+
+1. Sync: `runwell-shopify sync`
+2. Render the modal shell once (typically at the end of `<body>` in `layout/theme.liquid`):
+   ```liquid
+   {% render 'runwell-quickview-modal' %}
+   ```
+3. Add the trigger inside `snippets/card-product.liquid` near the product image:
+   ```liquid
+   {% render 'runwell-quickview-trigger', handle: card_product.handle %}
+   ```
+4. Style the modal in your brand stylesheet using the `.runwell-quickview` selectors.
+
+## Behaviour
+
+- Click trigger: fetches `/products/{handle}.js` (cached after first call)
+- Renders title, price, short description, variant picker, ATC button
+- Variant change updates price + variant id
+- ATC posts to `/cart/add.js`, closes modal, dispatches `runwell:cart:open` event
+- ESC + backdrop click close
+- Single variant: no picker, just ATC
+- All-variants-out-of-stock: ATC disabled "Sold out"
+
+## Replaces
+
+Globo Quick View, Pagefly QV, Vitals QV.

package/modules/quick-view/assets/runwell-quickview.js

@@ -0,0 +1,153 @@
+/* Runwell quick-view modal. Click an eye icon on a product card to
+   open a modal with image, variant picker, qty, ATC. ATC posts to
+   /cart/add.js and opens the cart drawer on success.
+   Replaces Globo Quick View / Pagefly QV / Vitals QV. */
+(function () {
+  if (typeof window === 'undefined') return;
+
+  var modal = null;
+  var cache = {};
+  var lastTrigger = null;
+
+  function ensureModal() {
+    if (modal) return modal;
+    modal = document.querySelector('[data-runwell-quickview-modal]');
+    return modal;
+  }
+
+  function open(handle, trigger) {
+    var m = ensureModal();
+    if (!m) return;
+    lastTrigger = trigger;
+    m.setAttribute('aria-hidden', 'false');
+    m.classList.add('is-open');
+    document.body.classList.add('runwell-quickview-open');
+    var body = m.querySelector('[data-runwell-quickview-body]');
+    if (body) body.innerHTML = '<div class="runwell-quickview__loading">Loading...</div>';
+
+    var p = cache[handle] ? Promise.resolve(cache[handle]) :
+      fetch('/products/' + handle + '.js').then(function (r) { return r.json(); }).then(function (j) { cache[handle] = j; return j; });
+    p.then(function (product) { renderProduct(body, product); }).catch(function () {
+      if (body) body.innerHTML = '<p class="runwell-quickview__error">Could not load this product.</p>';
+    });
+  }
+
+  function close() {
+    var m = ensureModal();
+    if (!m) return;
+    m.setAttribute('aria-hidden', 'true');
+    m.classList.remove('is-open');
+    document.body.classList.remove('runwell-quickview-open');
+    if (lastTrigger) lastTrigger.focus();
+  }
+
+  function renderProduct(host, product) {
+    if (!host || !product) return;
+    var firstImage = product.images && product.images[0];
+    var imageHtml = firstImage ? '<img src="' + firstImage + '" alt="' + (product.title || '').replace(/"/g, '&quot;') + '" loading="lazy">' : '';
+    var price = (product.price / 100).toFixed(2);
+    var availableVariants = (product.variants || []).filter(function (v) { return v.available; });
+    var firstVariant = availableVariants[0] || product.variants[0];
+    var soldOut = !firstVariant || !firstVariant.available;
+
+    var variantPickerHtml = '';
+    if (product.variants && product.variants.length > 1) {
+      variantPickerHtml = '<div class="runwell-quickview__variants">' +
+        product.variants.map(function (v) {
+          var sel = v.id === firstVariant.id ? ' is-selected' : '';
+          var disabled = v.available ? '' : ' disabled';
+          return '<button type="button" class="runwell-quickview__variant' + sel + '" data-variant-id="' + v.id + '"' + disabled + '>' + v.title + '</button>';
+        }).join('') +
+        '</div>';
+    }
+
+    host.innerHTML =
+      '<div class="runwell-quickview__media">' + imageHtml + '</div>' +
+      '<div class="runwell-quickview__details">' +
+        '<h2 class="runwell-quickview__title">' + product.title + '</h2>' +
+        '<p class="runwell-quickview__price" data-runwell-quickview-price>$' + price + '</p>' +
+        (product.description ? '<div class="runwell-quickview__desc">' + product.description.slice(0, 220) + (product.description.length > 220 ? '...' : '') + '</div>' : '') +
+        variantPickerHtml +
+        '<form class="runwell-quickview__form" data-runwell-quickview-form>' +
+          '<input type="hidden" name="id" value="' + (firstVariant ? firstVariant.id : '') + '" data-runwell-quickview-variant-input>' +
+          '<button type="submit" class="runwell-quickview__atc"' + (soldOut ? ' disabled' : '') + '>' +
+            (soldOut ? 'Sold out' : 'Add to cart') +
+          '</button>' +
+          '<a class="runwell-quickview__pdp" href="/products/' + product.handle + '">View full product &rarr;</a>' +
+        '</form>' +
+      '</div>';
+
+    bindVariantPicker(host, product);
+    bindAtc(host);
+  }
+
+  function bindVariantPicker(host, product) {
+    var buttons = host.querySelectorAll('[data-variant-id]');
+    var input = host.querySelector('[data-runwell-quickview-variant-input]');
+    var priceEl = host.querySelector('[data-runwell-quickview-price]');
+    buttons.forEach(function (b) {
+      b.addEventListener('click', function (e) {
+        e.preventDefault();
+        if (b.disabled) return;
+        buttons.forEach(function (x) { x.classList.remove('is-selected'); });
+        b.classList.add('is-selected');
+        var id = parseInt(b.getAttribute('data-variant-id'), 10);
+        if (input) input.value = id;
+        var v = product.variants.find(function (x) { return x.id === id; });
+        if (v && priceEl) priceEl.textContent = '$' + (v.price / 100).toFixed(2);
+      });
+    });
+  }
+
+  function bindAtc(host) {
+    var form = host.querySelector('[data-runwell-quickview-form]');
+    if (!form) return;
+    form.addEventListener('submit', function (e) {
+      e.preventDefault();
+      var fd = new FormData(form);
+      fetch('/cart/add.js', {
+        method: 'POST',
+        body: fd,
+        headers: { 'Accept': 'application/json' }
+      }).then(function (r) { return r.json(); }).then(function () {
+        close();
+        var openCart = document.querySelector('cart-drawer');
+        if (openCart && typeof openCart.open === 'function') openCart.open();
+        else document.dispatchEvent(new CustomEvent('runwell:cart:open'));
+      }).catch(function () {});
+    });
+  }
+
+  function bindTriggers() {
+    document.querySelectorAll('[data-runwell-quickview]').forEach(function (btn) {
+      if (btn.dataset.runwellQvBound === '1') return;
+      btn.dataset.runwellQvBound = '1';
+      btn.addEventListener('click', function (e) {
+        e.preventDefault();
+        var handle = btn.getAttribute('data-handle');
+        if (handle) open(handle, btn);
+      });
+    });
+  }
+
+  function bindModalControls() {
+    var m = ensureModal();
+    if (!m) return;
+    m.querySelectorAll('[data-runwell-quickview-close]').forEach(function (el) {
+      el.addEventListener('click', close);
+    });
+    document.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape' && m.classList.contains('is-open')) close();
+    });
+  }
+
+  function init() {
+    bindTriggers();
+    bindModalControls();
+  }
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/modules/quick-view/module.json

@@ -0,0 +1,14 @@
+{
+  "name": "quick-view",
+  "version": "0.1.0",
+  "category": "conversion",
+  "description": "Modal product quick-view triggered from product cards. Variant picker + ATC. App-free replacement for Globo QV / Pagefly QV / Vitals QV.",
+  "files": {
+    "assets": ["assets/runwell-quickview.js"],
+    "snippets": [
+      "snippets/runwell-quickview-modal.liquid",
+      "snippets/runwell-quickview-trigger.liquid"
+    ]
+  },
+  "config": { "schema": {} }
+}