@runwell/shopify-toolkit 0.18.0 → 0.23.0

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

@@ -0,0 +1,444 @@
+/* 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);
+    });
+  }
+
+  /* ---------- Mode C BYOB ---------- */
+
+  function parsePricingValue(raw) {
+    if (raw == null || raw === '') return null;
+    try { return JSON.parse(raw); } catch (e) { return null; }
+  }
+
+  function computeByobPrice(subtotalCents, pricingModel, pricingValue) {
+    if (pricingModel === 'fixed_bundle_price' || pricingModel === 'fixed_price') {
+      const v = typeof pricingValue === 'object' && pricingValue !== null
+        ? (pricingValue.amount || pricingValue.price || 0)
+        : pricingValue;
+      return Math.max(0, parseInt(v, 10) || 0);
+    }
+    if (pricingModel === 'percent_off_subtotal') {
+      const pct = typeof pricingValue === 'object' && pricingValue !== null
+        ? (pricingValue.pct || pricingValue.percent || 0)
+        : pricingValue;
+      const discounted = subtotalCents * (1 - (parseFloat(pct) || 0) / 100);
+      return Math.max(0, Math.round(discounted));
+    }
+    if (pricingModel === 'dollar_off_subtotal') {
+      const off = typeof pricingValue === 'object' && pricingValue !== null
+        ? (pricingValue.amount || pricingValue.off || 0)
+        : pricingValue;
+      return Math.max(0, subtotalCents - (parseInt(off, 10) || 0));
+    }
+    return subtotalCents;
+  }
+
+  function formatByobMoney(cents) {
+    return '$' + (cents / 100).toFixed(2);
+  }
+
+  function initByob() {
+    document
+      .querySelectorAll('[data-runwell-byob-picker]')
+      .forEach(function (picker) {
+        const form = picker.closest('form');
+        if (!form) return;
+        const root = form.parentElement || form;
+        const summary = root.querySelector('[data-runwell-byob-summary]');
+        const atc = form.querySelector('[data-runwell-byob-atc]');
+
+        const layout = picker.dataset.byobLayout;
+        const min = parseInt(picker.dataset.byobMin, 10) || 0;
+        const max = parseInt(picker.dataset.byobMax, 10) || 0;
+        const pricingModel = picker.dataset.byobPricingModel;
+        const pricingValue = parsePricingValue(picker.dataset.byobPricingValue);
+
+        function getSelected() {
+          return Array.from(picker.querySelectorAll('.runwell-bundle-system__byob-input:checked'))
+            .map(function (input) {
+              const label = input.closest('.runwell-bundle-system__byob-candidate');
+              return {
+                handle: label.dataset.handle,
+                price: parseInt(label.dataset.price, 10) || 0,
+                variantId: label.dataset.variantId,
+                category: label.dataset.category || null,
+                input: input
+              };
+            });
+        }
+
+        function updateAccordionCounts() {
+          if (layout !== 'accordion') return;
+          picker.querySelectorAll('.runwell-bundle-system__byob-accordion').forEach(function (acc) {
+            const count = acc.querySelectorAll('.runwell-bundle-system__byob-input:checked').length;
+            const badge = acc.querySelector('[data-runwell-byob-cat-count]');
+            if (badge) badge.textContent = count;
+          });
+        }
+
+        function enforceMax(selected) {
+          if (layout === 'radio') return;
+          if (selected.length <= max) return;
+          const overflow = selected.slice(max);
+          overflow.forEach(function (s) {
+            if (!s.input.disabled) s.input.checked = false;
+          });
+        }
+
+        function render() {
+          let selected = getSelected();
+          enforceMax(selected);
+          selected = getSelected();
+
+          const count = selected.length;
+          const subtotal = selected.reduce(function (acc, s) { return acc + s.price; }, 0);
+          const total = computeByobPrice(subtotal, pricingModel, pricingValue);
+          const savings = Math.max(0, subtotal - total);
+
+          if (summary) {
+            const selEl = summary.querySelector('[data-runwell-byob-selected]');
+            const totalEl = summary.querySelector('[data-runwell-byob-total]');
+            const subEl = summary.querySelector('[data-runwell-byob-subtotal]');
+            const subAmt = summary.querySelector('[data-runwell-byob-subtotal-amount]');
+            const savEl = summary.querySelector('[data-runwell-byob-savings]');
+            const savAmt = summary.querySelector('[data-runwell-byob-savings-amount]');
+            const helper = summary.querySelector('[data-runwell-byob-helper]');
+
+            if (selEl) selEl.textContent = count;
+            if (totalEl) totalEl.textContent = formatByobMoney(total);
+            const isFixed = pricingModel === 'fixed_bundle_price' || pricingModel === 'fixed_price';
+            if (savings > 0 && !isFixed) {
+              if (subEl) { subEl.hidden = false; if (subAmt) subAmt.textContent = formatByobMoney(subtotal); }
+              if (savEl) { savEl.hidden = false; if (savAmt) savAmt.textContent = formatByobMoney(savings); }
+            } else {
+              if (subEl) subEl.hidden = true;
+              if (savEl) savEl.hidden = true;
+            }
+            if (helper) helper.style.display = count >= min ? 'none' : '';
+          }
+
+          if (atc) {
+            const ok = count >= min && count <= max;
+            atc.disabled = !ok;
+          }
+          updateAccordionCounts();
+        }
+
+        picker.addEventListener('change', function (e) {
+          if (!e.target.matches('.runwell-bundle-system__byob-input')) return;
+          render();
+        });
+
+        form.addEventListener('submit', function (e) {
+          const selected = getSelected();
+          if (selected.length < min || selected.length > max) {
+            e.preventDefault();
+            return;
+          }
+          e.preventDefault();
+          const items = selected.map(function (s) {
+            return { id: parseInt(s.variantId, 10), quantity: 1 };
+          });
+          fetch('/cart/add.js', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+            body: JSON.stringify({ items: items })
+          })
+            .then(function (r) { return r.json(); })
+            .then(function () {
+              document.dispatchEvent(new CustomEvent('cart:refresh'));
+              window.location.href = '/cart';
+            })
+            .catch(function () {
+              if (atc) atc.disabled = false;
+            });
+        });
+
+        render();
+      });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () {
+      initFomo();
+      initTierSync();
+      initFilterChip();
+      initCartXsell();
+      initByob();
+    });
+  } else {
+    initFomo();
+    initTierSync();
+    initFilterChip();
+    initCartXsell();
+    initByob();
+  }
+})();

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

@@ -0,0 +1,137 @@
+{
+  "name": "runwell-bundle-system",
+  "version": "0.3.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",
+      "snippets/runwell-bundle-byob-picker.liquid",
+      "snippets/runwell-bundle-byob-picker-grid.liquid",
+      "snippets/runwell-bundle-byob-picker-accordion.liquid",
+      "snippets/runwell-bundle-byob-picker-radio.liquid",
+      "snippets/runwell-bundle-byob-summary.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-byob-mode",
+      "label": "Configure a BYOB (Mode C) bundle product",
+      "url": "https://admin.shopify.com/store/{store_handle}/products",
+      "summary": "Mode C only. Set bundle_mode = 'byob'. Required: bundle_byob_candidates (list of product references), bundle_byob_min_picks, bundle_byob_max_picks, bundle_pricing_model (fixed_bundle_price / percent_off_subtotal / dollar_off_subtotal), bundle_pricing_value. Optional: bundle_byob_layout (grid default, accordion, radio), bundle_byob_categories (JSON), bundle_byob_required_handles. Install a Shopify Functions discount that mirrors the pricing model so the savings apply at checkout."
+    },
+    {
+      "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."
+    }
+  ]
+}