@runwell/shopify-toolkit 0.18.0 → 0.21.0

package/modules/runwell-bundle-system/assets/runwell-bundle-system.js

@@ -0,0 +1,287 @@
+/* runwell-bundle-system: assets/runwell-bundle-system.js.
+
+   Two responsibilities in v1:
+   1. FOMO countdown ticker for the discount-deadline strip on bundle PDPs.
+      Cycles every fomo_cycle_days days. No external libs; tabular-nums
+      keeps the digits from jumping.
+   2. Mode A radio change handler: keeps the ATC button label in sync
+      with the selected quantity (purely UX; the form submission carries
+      the qty as a hidden input).
+
+   Surface 4 (cart drawer cross-sell) JS lives here too once BS-6 ships.
+*/
+
+(function () {
+  'use strict';
+
+  function pad(n) {
+    return n < 10 ? '0' + n : '' + n;
+  }
+
+  function startCountdown(el) {
+    const cycleDays = parseInt(el.dataset.fomoCycleDays || '30', 10);
+    if (!cycleDays || cycleDays <= 0) return;
+
+    const cycleMs = cycleDays * 24 * 60 * 60 * 1000;
+    const epoch = new Date('2026-01-01T00:00:00Z').getTime();
+    const timeEl = el.querySelector('[data-runwell-fomo-time]');
+    if (!timeEl) return;
+
+    function tick() {
+      const now = Date.now();
+      const elapsedInCycle = (now - epoch) % cycleMs;
+      const remainingMs = cycleMs - elapsedInCycle;
+      const days = Math.floor(remainingMs / (24 * 60 * 60 * 1000));
+      const hours = Math.floor((remainingMs % (24 * 60 * 60 * 1000)) / (60 * 60 * 1000));
+      const minutes = Math.floor((remainingMs % (60 * 60 * 1000)) / (60 * 1000));
+
+      if (days > 0) {
+        timeEl.textContent = days + 'd ' + pad(hours) + 'h ' + pad(minutes) + 'm';
+      } else {
+        const seconds = Math.floor((remainingMs % (60 * 1000)) / 1000);
+        timeEl.textContent = pad(hours) + 'h ' + pad(minutes) + 'm ' + pad(seconds) + 's';
+      }
+    }
+
+    tick();
+    setInterval(tick, 1000);
+  }
+
+  function initFomo() {
+    document
+      .querySelectorAll('[data-runwell-fomo]')
+      .forEach(function (el) {
+        const mode = el.dataset.fomoMode;
+        if (mode === 'discount' || mode === 'both') startCountdown(el);
+      });
+  }
+
+  function initTierSync() {
+    document
+      .querySelectorAll('.runwell-bundle-system__tiers')
+      .forEach(function (fieldset) {
+        fieldset.addEventListener('change', function (e) {
+          if (!e.target.matches('.runwell-bundle-system__tier-input')) return;
+          fieldset
+            .querySelectorAll('.runwell-bundle-system__tier')
+            .forEach(function (label) {
+              const input = label.querySelector('.runwell-bundle-system__tier-input');
+              label.classList.toggle('is-selected', input.checked);
+            });
+        });
+      });
+  }
+
+  function initFilterChip() {
+    document
+      .querySelectorAll('[data-runwell-bundle-filter-chip]')
+      .forEach(function (chip) {
+        const section = chip.closest('.runwell-bundle-collection--filter-chip');
+        if (!section) return;
+        const handlesAttr = section.dataset.bundleHandles || '';
+        const bundleHandles = handlesAttr
+          .split(',')
+          .map(function (h) { return h.trim(); })
+          .filter(Boolean);
+
+        function applyFilter(active) {
+          chip.setAttribute('aria-pressed', active ? 'true' : 'false');
+          const cards = document.querySelectorAll(
+            '.product-grid .product-card, .grid__item .card-wrapper, [data-product-handle]'
+          );
+          cards.forEach(function (card) {
+            const handle =
+              card.dataset.productHandle ||
+              (card.querySelector('[data-product-handle]') || {}).dataset?.productHandle ||
+              '';
+            const tags = (card.dataset.tags || '').toLowerCase();
+            const isBundle = bundleHandles.indexOf(handle) !== -1 || tags.indexOf('bundle') !== -1;
+            card.style.display = active && !isBundle ? 'none' : '';
+          });
+          const url = new URL(window.location.href);
+          if (active) {
+            url.searchParams.set('filter', 'bundle');
+          } else {
+            url.searchParams.delete('filter');
+          }
+          window.history.replaceState({}, '', url);
+        }
+
+        chip.addEventListener('click', function () {
+          const active = chip.getAttribute('aria-pressed') === 'true';
+          applyFilter(!active);
+        });
+
+        const initial = new URL(window.location.href).searchParams.get('filter') === 'bundle';
+        if (initial) applyFilter(true);
+      });
+  }
+
+  /* ---------- Surface 4: cart drawer bundle cross-sell ---------- */
+
+  function readBundleIndex() {
+    const el = document.querySelector('[data-runwell-bundle-index]');
+    if (!el) return null;
+    try {
+      return JSON.parse(el.textContent || '{}');
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function findBundleMatch(cartHandles, bundleIndex) {
+    if (!bundleIndex || !bundleIndex.products || !bundleIndex.bundles) return null;
+    const candidates = new Set();
+    cartHandles.forEach(function (h) {
+      (bundleIndex.products[h] || []).forEach(function (b) {
+        candidates.add(b);
+      });
+    });
+    let best = null;
+    candidates.forEach(function (bundleHandle) {
+      const bundle = bundleIndex.bundles[bundleHandle];
+      if (!bundle || !bundle.components) return;
+      const compHandles = Object.keys(bundle.components);
+      const inCart = compHandles.filter(function (h) {
+        return cartHandles.indexOf(h) !== -1;
+      });
+      if (inCart.length >= 1 && inCart.length < compHandles.length) {
+        if (!best || inCart.length > best.matchCount) {
+          best = { bundleHandle: bundleHandle, matchCount: inCart.length, total: compHandles.length };
+        }
+      }
+    });
+    return best;
+  }
+
+  function fetchCart() {
+    return fetch('/cart.js', { headers: { Accept: 'application/json' } })
+      .then(function (r) { return r.json(); })
+      .catch(function () { return { items: [] }; });
+  }
+
+  function fetchBundleProduct(handle) {
+    return fetch('/products/' + handle + '.js', { headers: { Accept: 'application/json' } })
+      .then(function (r) { return r.json(); })
+      .catch(function () { return null; });
+  }
+
+  function renderCard(slot, bundleProduct, eyebrow, cta) {
+    if (!bundleProduct) return;
+    slot.innerHTML =
+      '<p class="runwell-bundle-cart-xsell__eyebrow">' + escapeHtml(eyebrow) + '</p>' +
+      '<div class="runwell-bundle-cart-xsell__card">' +
+        (bundleProduct.featured_image
+          ? '<img class="runwell-bundle-cart-xsell__thumb" loading="lazy" width="60" height="60" alt="" src="' + bundleProduct.featured_image + '">'
+          : '') +
+        '<div class="runwell-bundle-cart-xsell__details">' +
+          '<p class="runwell-bundle-cart-xsell__name">' + escapeHtml(bundleProduct.title) + '</p>' +
+          '<p class="runwell-bundle-cart-xsell__price">' + formatMoney(bundleProduct.price) + '</p>' +
+        '</div>' +
+        '<button type="button" class="runwell-bundle-cart-xsell__cta" data-runwell-bundle-cta data-bundle-handle="' + bundleProduct.handle + '" data-bundle-variant-id="' + bundleProduct.variants[0].id + '">' + escapeHtml(cta) + '</button>' +
+      '</div>';
+  }
+
+  function escapeHtml(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  function formatMoney(cents) {
+    return '$' + (cents / 100).toFixed(2);
+  }
+
+  function addBundleAndRemoveComponents(variantId, componentHandles, cart) {
+    const updates = {};
+    if (cart && cart.items) {
+      cart.items.forEach(function (item) {
+        if (componentHandles.indexOf(item.handle) !== -1) {
+          updates[item.key] = 0;
+        }
+      });
+    }
+    return fetch('/cart/add.js', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ id: variantId, quantity: 1 })
+    })
+      .then(function (r) { return r.json(); })
+      .then(function () {
+        if (Object.keys(updates).length === 0) return null;
+        return fetch('/cart/update.js', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+          body: JSON.stringify({ updates: updates })
+        }).then(function (r) { return r.json(); });
+      })
+      .then(function () {
+        document.dispatchEvent(new CustomEvent('cart:refresh'));
+      });
+  }
+
+  function initCartXsell() {
+    const slot = document.querySelector('[data-runwell-bundle-xsell-slot]');
+    if (!slot) return;
+    const bundleIndex = readBundleIndex();
+    if (!bundleIndex) return;
+
+    function evaluate() {
+      fetchCart().then(function (cart) {
+        const cartHandles = (cart.items || []).map(function (i) { return i.handle; });
+        if (cartHandles.length === 0) {
+          slot.innerHTML = '';
+          return;
+        }
+        const match = findBundleMatch(cartHandles, bundleIndex);
+        if (!match) {
+          slot.innerHTML = '';
+          return;
+        }
+        fetchBundleProduct(match.bundleHandle).then(function (bp) {
+          if (!bp || !bp.variants || bp.variants.length === 0) {
+            slot.innerHTML = '';
+            return;
+          }
+          renderCard(slot, bp, slot.dataset.eyebrow || 'Complete the stack', slot.dataset.cta || 'Add bundle and save');
+          document.dispatchEvent(new CustomEvent('runwell:bundle-xsell-active', { detail: { bundleHandle: match.bundleHandle } }));
+
+          const cta = slot.querySelector('[data-runwell-bundle-cta]');
+          if (cta) {
+            cta.addEventListener('click', function () {
+              const vid = parseInt(cta.dataset.bundleVariantId, 10);
+              const handle = cta.dataset.bundleHandle;
+              const bundle = bundleIndex.bundles[handle];
+              const componentHandles = bundle ? Object.keys(bundle.components) : [];
+              cta.disabled = true;
+              addBundleAndRemoveComponents(vid, componentHandles, cart).catch(function () {
+                cta.disabled = false;
+              });
+            });
+          }
+        });
+      });
+    }
+
+    evaluate();
+    ['cart:updated', 'cart:refresh', 'cart:change'].forEach(function (evt) {
+      document.addEventListener(evt, evaluate);
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () {
+      initFomo();
+      initTierSync();
+      initFilterChip();
+      initCartXsell();
+    });
+  } else {
+    initFomo();
+    initTierSync();
+    initFilterChip();
+    initCartXsell();
+  }
+})();

package/modules/runwell-bundle-system/module.json

@@ -0,0 +1,126 @@
+{
+  "name": "runwell-bundle-system",
+  "version": "0.1.0",
+  "category": "catalog",
+  "source": "runwell",
+  "base": "bundle-system",
+  "description": "Configurable bundles engine. Single-product quantity tiers (Mode A), curated multi-product (Mode B), mix-and-match (Mode C, v1.5), subscription bundles (Mode D, v2). Reads per-bundle config from product metafields runwell.bundle_*. Sits on top of Shopify's free first-party Bundles app for inventory and cart math. Replaces the legacy bundle-builder module.",
+  "replaces": ["bundle-builder"],
+  "files": {
+    "sections": [
+      "sections/runwell-bundle-pdp.liquid",
+      "sections/runwell-bundle-pdp-pairs-with.liquid",
+      "sections/runwell-bundle-home-stacks.liquid",
+      "sections/runwell-bundle-cart-xsell.liquid",
+      "sections/runwell-bundle-pdp-banner.liquid",
+      "sections/runwell-bundle-collection.liquid"
+    ],
+    "snippets": [
+      "snippets/runwell-bundle-card.liquid",
+      "snippets/runwell-bundle-quantity-tiers.liquid",
+      "snippets/runwell-bundle-multi-product.liquid",
+      "snippets/runwell-bundle-pricing.liquid",
+      "snippets/runwell-bundle-cross-supplier.liquid",
+      "snippets/runwell-bundle-fomo.liquid",
+      "snippets/runwell-bundle-free-gift.liquid",
+      "snippets/runwell-bundle-data.liquid"
+    ],
+    "assets": [
+      "assets/runwell-bundle-system.css",
+      "assets/runwell-bundle-system.js"
+    ]
+  },
+  "config": {
+    "schema": {
+      "surface_1_collection_page_enabled": { "type": "boolean", "default": true, "label": "Enable /bundles collection page" },
+      "surface_2_pdp_pairs_with_enabled": { "type": "boolean", "default": true, "label": "Enable PDP 'Pairs well with' widget" },
+      "surface_3_home_stacks_enabled": { "type": "boolean", "default": true, "label": "Enable home page curated stacks strip" },
+      "surface_4_cart_drawer_xsell_enabled": { "type": "boolean", "default": true, "label": "Enable cart drawer bundle cross-sell" },
+      "surface_5_pdp_banner_enabled": { "type": "boolean", "default": true, "label": "Enable PDP bundle banner" },
+      "surface_6_collection_filter_enabled": { "type": "boolean", "default": false, "label": "Enable bundles filter on collection pages" },
+      "surface_2_eyebrow": { "type": "string", "default": "Pairs well with", "label": "Surface 2 eyebrow copy" },
+      "surface_2_heading": { "type": "string", "default": "Complete the routine", "label": "Surface 2 heading copy" },
+      "surface_3_eyebrow": { "type": "string", "default": "Editor's picks", "label": "Surface 3 eyebrow copy" },
+      "surface_3_heading": { "type": "string", "default": "Curated stacks", "label": "Surface 3 heading copy" },
+      "surface_4_eyebrow": { "type": "string", "default": "Complete the stack", "label": "Surface 4 eyebrow copy" },
+      "surface_4_cta": { "type": "string", "default": "Add bundle and save", "label": "Surface 4 CTA label" },
+      "surface_5_copy_template": { "type": "string", "default": "Save {savings_pct}% when bundled", "label": "Surface 5 copy template (use {savings_pct} or {savings_amount})" },
+      "cross_supplier_disclosure": { "type": "string", "default": "This bundle ships in {n} packages.", "label": "Cross-supplier disclosure text" },
+      "home_strip_position": { "type": "number", "default": 3, "label": "Position of home page bundle strip in templates/index.json" }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "install-shopify-bundles",
+      "label": "Install Shopify's free Bundles app",
+      "url": "https://apps.shopify.com/shopify-bundles",
+      "summary": "Install the Bundles app made by Shopify (free, first-party). Required for bundle inventory deduction and cart line-item math. The runwell-bundle-system module sits on top of this; it does not replace it."
+    },
+    {
+      "id": "define-bundle-metafields",
+      "label": "Define the runwell.bundle_* product metafield definitions",
+      "url": "https://admin.shopify.com/store/{store_handle}/settings/custom_data/products/metafields",
+      "summary": "Settings > Custom data > Products > Add definition. See modules/runwell-bundle-system/admin-metafields.json for the full list of 19 definitions (namespace, key, type, validations, defaults). Mirrors spec.md section 2.1."
+    },
+    {
+      "id": "create-bundle-index-metaobject",
+      "label": "Create the bundle_index shop metaobject definition",
+      "url": "https://admin.shopify.com/store/{store_handle}/settings/custom_data/metaobjects",
+      "summary": "Settings > Custom data > Metaobjects > Add definition. Type: bundle_index. Field: entries (JSON). One instance per shop. Used by the PDP 'Pairs well with' widget to avoid N+1 reads. See modules/runwell-bundle-system/admin-metafields.json -> shop_metaobjects."
+    },
+    {
+      "id": "create-first-bundle-product",
+      "label": "Create your first bundle product",
+      "url": "https://admin.shopify.com/store/{store_handle}/products/new",
+      "summary": "Use the Shopify Bundles app to create the bundle (Apps > Bundles > Create). The app creates a bundle product. SKU convention: BUNDLE-<handle>. Then open the bundle product, scroll to Metafields, and fill the runwell.bundle_* fields per the bundle's mode."
+    },
+    {
+      "id": "configure-quantity-tier-discount-function",
+      "label": "Create a Shopify Functions discount for quantity-tier mode (Mode A only)",
+      "url": "https://shopify.dev/docs/apps/build/discounts/sample-apps",
+      "summary": "Build a Shopify Function (or use an existing Functions app like 'Volume Discount Builder') that reads runwell.bundle_quantity_tiers per line item and applies the matching discount. Required only for Mode A (single-product quantity tiers). Mode B uses Shopify Bundles app native pricing."
+    },
+    {
+      "id": "configure-free-gift-discount",
+      "label": "Create the 100% off discount on the gift product (free-gift bundles only)",
+      "url": "https://admin.shopify.com/store/{store_handle}/discounts/new",
+      "summary": "Per gift-with-purchase module convention. Discount type: Amount off products. Automatic. 100%. Applies to: the gift product (matching bundle_free_gift_handle). Minimum requirement: bundle in cart. So the gift line lands free at checkout."
+    },
+    {
+      "id": "create-bundles-collection-page-template",
+      "label": "Create the /bundles collection page template (Surface 1)",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Online Store > Themes > Customize > Templates > Add template. Type: page. Name: bundles. Add the runwell-bundle-collection section. Then create a Page in Online Store > Pages > Add page. Title: Bundles. URL handle: bundles. Template: page.bundles."
+    },
+    {
+      "id": "add-home-stacks-section",
+      "label": "Add the curated stacks section to the home page (Surface 3)",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Theme customizer > Home page > Add section > runwell-bundle-home-stacks. Position per home_strip_position config (default: 3rd section)."
+    },
+    {
+      "id": "add-pdp-pairs-with-section",
+      "label": "Add the PDP 'Pairs well with' widget (Surface 2)",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Theme customizer > Products > Default product > Add section > runwell-bundle-pdp-pairs-with. The section auto-shows only on PDPs of products that appear in at least one bundle."
+    },
+    {
+      "id": "add-pdp-banner-section",
+      "label": "Add the PDP bundle banner (Surface 5)",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Theme customizer > Products > Default product > Add block (inside main-product) > runwell-bundle-pdp-banner. Position near the buy box. Section auto-shows only on PDPs of products that appear in at least one bundle."
+    },
+    {
+      "id": "verify-cart-drawer-coordination",
+      "label": "Verify cart drawer bundle cross-sell coordinates with cart-cross-sell (Surface 4)",
+      "url": "https://admin.shopify.com/store/{store_handle}/themes",
+      "summary": "Theme customizer > Cart drawer. Confirm the runwell-cart-bundle-xsell snippet renders before runwell-cart-xsell. The bundle xsell suppresses the single-product xsell when a bundle match is found; falls back when no match. No merchant action beyond install order."
+    },
+    {
+      "id": "rebuild-bundle-index",
+      "label": "Rebuild the bundle_index metaobject after creating or editing bundles",
+      "url": "https://admin.shopify.com/store/{store_handle}/apps",
+      "summary": "Run runwell-shopify rebuild-bundle-index from the toolkit CLI, or trigger the Shopify Flow workflow shipped with this module. Updates the reverse mapping used by Surface 2. Re-run any time a bundle's components change."
+    }
+  ]
+}

package/modules/runwell-bundle-system/qa/mobile-checklist.md

@@ -0,0 +1,105 @@
+# Mobile QA checklist: runwell-bundle-system v1
+
+Real-device QA at 375px viewport for every enabled bundle surface. Runs on Lushi staging after BS-15 wires the module. Must pass before any production deploy.
+
+## Environment
+
+- Real iPhone (iPhone 12 or newer; iOS 17+).
+- Safari (not Chrome iOS; Safari is the rendering engine on iOS).
+- Lushi staging dev store URL.
+- 3 sample bundles configured per BS-15.
+
+## Per-surface checks
+
+### Surface 1: /bundles collection page
+
+- [ ] Page loads without console errors.
+- [ ] Single-column grid at 375px.
+- [ ] Hero card variant renders for the first bundle when `feature_first_bundle` is on.
+- [ ] Card spacing 24px on mobile.
+- [ ] Sticky page heading visible while scrolling.
+- [ ] All cards tappable; tap routes to bundle PDP.
+- [ ] Strikethrough subtotal + savings badge legible.
+
+### Surface 2: PDP "Pairs well with"
+
+- [ ] Renders below buy box on a non-bundle PDP with matching bundles.
+- [ ] Self-suppresses on a non-bundle PDP without matching bundles.
+- [ ] Card width 96% of viewport.
+- [ ] Eyebrow and heading legible.
+- [ ] Tap routes to bundle PDP.
+
+### Surface 3: home page curated stacks
+
+- [ ] Vertical stack (no horizontal carousel) at 375px.
+- [ ] All 3 to 4 cards visible without horizontal swipe.
+- [ ] Section heading and eyebrow at top.
+- [ ] Background band setting respected (white / oat / celadon-tint).
+- [ ] Each card tappable; tap routes to bundle PDP.
+
+### Surface 4: cart drawer bundle xsell
+
+- [ ] Drawer opens, bundle xsell card visible at top of xsell area.
+- [ ] cart-cross-sell does NOT also render (coordination contract).
+- [ ] CTA "Add bundle and save" visible and tappable.
+- [ ] Tap CTA: in-cart components removed, bundle product added, drawer refreshes.
+- [ ] Performance: match logic runs in under 100ms.
+
+### Surface 5: PDP bundle banner
+
+- [ ] Renders near buy box on non-bundle PDPs with matches.
+- [ ] 44px height enforced.
+- [ ] Tap routes to bundle PDP.
+- [ ] Copy template `{savings_pct}` resolved to actual value.
+- [ ] Background brand-tinted (celadon by default), contrast text legible.
+
+### Surface 6: collection page bundles filter
+
+Skipped for Lushi v1 (no collection pages enabled). Re-enable once Lushi has a /collections/skincare or similar.
+
+- [ ] Filter chip + 2 pinned cards render above the collection grid.
+- [ ] Chip tap filters grid to bundles only.
+- [ ] Chip tap again clears the filter.
+- [ ] URL syncs `?filter=bundle`.
+
+### Bundle PDP, Mode A (Lusha pattern, when v1.1 enables)
+
+- [ ] Radio picker tappable.
+- [ ] Selected tier visually distinct (brand-color border).
+- [ ] Per-tier price + savings badge legible.
+- [ ] FOMO countdown updates (every second when sub-day; every minute when day+).
+- [ ] Sticky ATC at bottom of viewport when scrolled past buy box.
+
+### Bundle PDP, Mode B (Lushi pattern)
+
+- [ ] Component breakdown list legible.
+- [ ] Component thumbnails 60px square (80px at 1024px+).
+- [ ] Cross-supplier disclosure renders when `bundle_cross_supplier` is on and `bundle_supplier_count > 1`.
+- [ ] Strikethrough subtotal + savings badge correct per pricing model.
+- [ ] ATC adds bundle to cart.
+
+## Cross-cutting checks
+
+- [ ] No horizontal scroll on any surface.
+- [ ] All tap targets >= 44px.
+- [ ] Brand fonts loaded; no FOUT.
+- [ ] Lighthouse mobile score >= 80 on bundle PDP and /bundles page.
+- [ ] Total module byte footprint under 80KB combined (Liquid + CSS + JS, pre-minification).
+- [ ] No console errors on any surface.
+
+## Screenshot capture
+
+Per surface, capture 3 states:
+1. Default render.
+2. Interaction state (tap-active, modal open, etc.).
+3. Edge case (no matches, out of stock, cross-supplier disclosure visible).
+
+File path: `_clients/capital-v/lushi/qa/bundle-system-mobile-YYYY-MM-DD/surface-N-state.png`.
+
+## Sign-off
+
+- [ ] All applicable checks above passed.
+- [ ] Screenshots captured and committed.
+- [ ] Any failures logged as follow-up issues and resolved before BS-15 sign-off.
+- [ ] Lighthouse mobile scores documented in the QA handoff doc.
+- [ ] QA owner + date: ___________________

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

@@ -0,0 +1,59 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-cart-xsell.liquid.
+  Surface 4: cart drawer bundle cross-sell. Suggests "complete the
+  stack" when 1 to N-1 components of a defined bundle sit in cart.
+
+  How it wires:
+  1. This section emits a JSON island with the bundle_index forward and
+     reverse maps so the JS does not need a network round trip.
+  2. The section also emits an empty <div> slot that JS fills with a
+     bundle card (rendered via Section Rendering API call when a match
+     is detected).
+  3. JS dispatches `runwell:bundle-xsell-active` when it injects content
+     so the cart-cross-sell snippet can short-circuit.
+
+  Coordination contract: see modules/cart-cross-sell/snippets/runwell-cart-xsell.liquid
+  for the receiving guard. See _clients/capital-v/lushi/specs/bundle-system/spec.md
+  section 6.1.
+{%- endcomment -%}
+
+{%- if settings.bundle_system__surface_4_cart_drawer_xsell_enabled == false -%}
+  {%- comment -%} Tenant has disabled this surface. {%- endcomment -%}
+{%- else -%}
+  {%- assign bundle_index = shop.metaobjects.bundle_index.entries.value -%}
+  {%- assign render_slot = false -%}
+  {%- if bundle_index and bundle_index.products and bundle_index.bundles -%}
+    {%- assign render_slot = true -%}
+  {%- endif -%}
+
+  {%- if render_slot -%}
+    <aside
+      class="runwell-bundle-cart-xsell"
+      data-runwell-bundle-xsell-slot
+      data-eyebrow="{{ section.settings.eyebrow | escape }}"
+      data-cta="{{ section.settings.cta | escape }}"
+    ></aside>
+
+    <script type="application/json" data-runwell-bundle-index>
+      {{ bundle_index | json }}
+    </script>
+
+    {{ 'runwell-bundle-system.css' | asset_url | stylesheet_tag }}
+    <script src="{{ 'runwell-bundle-system.js' | asset_url }}" defer="defer"></script>
+  {%- endif -%}
+{%- endif -%}
+
+{% schema %}
+{
+  "name": "Bundle cart cross-sell",
+  "tag": "section",
+  "class": "section-runwell-bundle-cart-xsell",
+  "settings": [
+    { "type": "text", "id": "eyebrow", "label": "Eyebrow", "default": "Complete the stack" },
+    { "type": "text", "id": "cta", "label": "CTA label", "default": "Add bundle and save" }
+  ],
+  "presets": [
+    { "name": "Bundle: cart drawer cross-sell", "category": "Runwell" }
+  ]
+}
+{% endschema %}