@runwell/shopify-toolkit 0.18.0 → 0.23.0

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

@@ -0,0 +1,117 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-pdp.liquid.
+  Bundle PDP section. Used on templates/product.bundle.json (auto-assigned
+  to products with the runwell.bundle_mode metafield set). Routes to a
+  mode-specific snippet based on bundle_mode.
+
+  See _clients/capital-v/lushi/specs/bundle-system/spec.md sections 3, 5.
+{%- endcomment -%}
+
+{%- comment -%} v2: render runwell-subscription-picker here when bundle_subscription_enabled. Per BS-13 the subscription_* metafields ship in v1 inactive so v2 wires without a schema migration. {%- endcomment -%}
+
+{% render 'runwell-bundle-data', product: product %}
+
+<section
+  class="runwell-bundle-system runwell-bundle-system--mode-{{ bundle_mode | replace: '_', '-' }} color-{{ section.settings.color_scheme }}"
+  style="padding-top: {{ section.settings.padding_top }}px; padding-bottom: {{ section.settings.padding_bottom }}px;"
+>
+  <div class="runwell-bundle-system__inner page-width">
+    <div class="runwell-bundle-system__gallery">
+      {%- if product.featured_image -%}
+        {{ product.featured_image | image_url: width: 800 | image_tag:
+          loading: 'eager',
+          width: product.featured_image.width,
+          height: product.featured_image.height,
+          sizes: '(min-width: 1024px) 50vw, 100vw',
+          class: 'runwell-bundle-system__gallery-image'
+        }}
+      {%- endif -%}
+    </div>
+
+    <div class="runwell-bundle-system__details">
+      {%- if section.settings.sale_prefix != blank -%}
+        <p class="runwell-bundle-system__sale-prefix">{{ section.settings.sale_prefix }}</p>
+      {%- endif -%}
+
+      <h1 class="runwell-bundle-system__title">{{ product.title }}</h1>
+
+      {%- if product.description != blank -%}
+        <div class="runwell-bundle-system__description rte">{{ product.description }}</div>
+      {%- endif -%}
+
+      {%- if bundle_mode == 'quantity_tiers' -%}
+        {% render 'runwell-bundle-quantity-tiers',
+          product: product,
+          bundle_mode: bundle_mode,
+          bundle_pricing_model: bundle_pricing_model,
+          bundle_quantity_tiers: bundle_quantity_tiers,
+          section: section
+        %}
+      {%- elsif bundle_mode == 'multi_product' or bundle_mode == 'mix_match' -%}
+        {% render 'runwell-bundle-multi-product',
+          product: product,
+          bundle_mode: bundle_mode,
+          bundle_pricing_model: bundle_pricing_model,
+          bundle_components: bundle_components,
+          bundle_subtotal: bundle_subtotal,
+          bundle_price: bundle_price,
+          bundle_savings_amount: bundle_savings_amount,
+          bundle_savings_pct: bundle_savings_pct
+        %}
+      {%- elsif bundle_mode == 'byob' -%}
+        {% render 'runwell-bundle-byob-picker',
+          product: product,
+          bundle_pricing_model: bundle_pricing_model,
+          bundle_pricing_value: bundle_pricing_value,
+          bundle_byob_candidates: bundle_byob_candidates,
+          bundle_byob_min_picks: bundle_byob_min_picks,
+          bundle_byob_max_picks: bundle_byob_max_picks,
+          bundle_byob_layout: bundle_byob_layout,
+          bundle_byob_categories: bundle_byob_categories,
+          bundle_byob_required_handles: bundle_byob_required_handles
+        %}
+      {%- endif -%}
+
+      {%- if bundle_fomo_mode != 'none' and bundle_fomo_mode != blank -%}
+        {% render 'runwell-bundle-fomo',
+          bundle_fomo_mode: bundle_fomo_mode,
+          bundle_fomo_cycle_days: bundle_fomo_cycle_days,
+          bundle_fomo_stock_count: bundle_fomo_stock_count
+        %}
+      {%- endif -%}
+
+      {%- if bundle_free_gift_enabled -%}
+        {% render 'runwell-bundle-free-gift',
+          bundle_free_gift_handle: bundle_free_gift_handle
+        %}
+      {%- endif -%}
+
+      {%- if bundle_cross_supplier and bundle_supplier_count > 1 -%}
+        {% render 'runwell-bundle-cross-supplier',
+          bundle_supplier_count: bundle_supplier_count
+        %}
+      {%- endif -%}
+    </div>
+  </div>
+</section>
+
+{{ 'runwell-bundle-system.css' | asset_url | stylesheet_tag }}
+<script src="{{ 'runwell-bundle-system.js' | asset_url }}" defer="defer"></script>
+
+{% schema %}
+{
+  "name": "Bundle PDP",
+  "tag": "section",
+  "class": "section-runwell-bundle-pdp",
+  "settings": [
+    { "type": "text", "id": "sale_prefix", "label": "Sale prefix (above title)", "default": "Limited time offer" },
+    { "type": "color_scheme", "id": "color_scheme", "label": "Color scheme", "default": "scheme-1" },
+    { "type": "range", "id": "padding_top", "label": "Top padding", "min": 0, "max": 100, "step": 4, "default": 40, "unit": "px" },
+    { "type": "range", "id": "padding_bottom", "label": "Bottom padding", "min": 0, "max": 100, "step": 4, "default": 40, "unit": "px" }
+  ],
+  "presets": [
+    { "name": "Bundle PDP", "category": "Runwell" }
+  ],
+  "templates": ["product.bundle"]
+}
+{% endschema %}

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

@@ -0,0 +1,25 @@
+{
+  "$comment": "Theme customizer settings patch. runwell-shopify sync appends this group to tenant config/settings_schema.json. Site-wide defaults; section-level overrides live in each section's schema.",
+  "spec_ref": "_clients/capital-v/lushi/specs/bundle-system/spec.md#10-settings-schema-for-theme-customizer",
+  "name": "Bundle system",
+  "settings": [
+    { "type": "header", "content": "Display surfaces" },
+    { "type": "checkbox", "id": "bundle_system__surface_1_collection_page_enabled", "label": "/bundles collection page", "default": true },
+    { "type": "checkbox", "id": "bundle_system__surface_2_pdp_pairs_with_enabled", "label": "PDP 'Pairs well with' widget", "default": true },
+    { "type": "checkbox", "id": "bundle_system__surface_3_home_stacks_enabled", "label": "Home page curated stacks", "default": true },
+    { "type": "checkbox", "id": "bundle_system__surface_4_cart_drawer_xsell_enabled", "label": "Cart drawer bundle cross-sell", "default": true },
+    { "type": "checkbox", "id": "bundle_system__surface_5_pdp_banner_enabled", "label": "PDP bundle banner", "default": true },
+    { "type": "checkbox", "id": "bundle_system__surface_6_collection_filter_enabled", "label": "Collection page bundles filter", "default": false },
+    { "type": "header", "content": "Default copy" },
+    { "type": "text", "id": "bundle_system__surface_2_eyebrow", "label": "Surface 2 eyebrow", "default": "Pairs well with" },
+    { "type": "text", "id": "bundle_system__surface_2_heading", "label": "Surface 2 heading", "default": "Complete the routine" },
+    { "type": "text", "id": "bundle_system__surface_3_eyebrow", "label": "Surface 3 eyebrow", "default": "Editor's picks" },
+    { "type": "text", "id": "bundle_system__surface_3_heading", "label": "Surface 3 heading", "default": "Curated stacks" },
+    { "type": "text", "id": "bundle_system__surface_4_eyebrow", "label": "Surface 4 eyebrow", "default": "Complete the stack" },
+    { "type": "text", "id": "bundle_system__surface_4_cta", "label": "Surface 4 CTA", "default": "Add bundle and save" },
+    { "type": "text", "id": "bundle_system__surface_5_copy_template", "label": "Surface 5 copy template", "default": "Save {savings_pct}% when bundled" },
+    { "type": "text", "id": "bundle_system__cross_supplier_disclosure", "label": "Cross-supplier disclosure", "default": "This bundle ships in {n} packages." },
+    { "type": "header", "content": "Layout" },
+    { "type": "range", "id": "bundle_system__home_strip_position", "label": "Home strip position (1-10)", "min": 1, "max": 10, "step": 1, "default": 3 }
+  ]
+}

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

@@ -0,0 +1,84 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-byob-picker-accordion.liquid.
+  Mode C, accordion layout. Candidates grouped by bundle_byob_categories.
+  One category open at a time. Total picks across all categories
+  enforced via JS.
+
+  Inputs:
+    bundle_byob_candidates, bundle_byob_min_picks, bundle_byob_max_picks,
+    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 -%}
+
+  <div
+    class="runwell-bundle-system__byob-picker runwell-bundle-system__byob-picker--accordion"
+    data-runwell-byob-picker
+    data-byob-layout="accordion"
+    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 category in bundle_byob_categories -%}
+      <details class="runwell-bundle-system__byob-accordion" {% if forloop.first %}open{% endif %}>
+        <summary class="runwell-bundle-system__byob-accordion-summary">
+          <span class="runwell-bundle-system__byob-accordion-label">{{ category.label }}</span>
+          <span class="runwell-bundle-system__byob-accordion-count" data-runwell-byob-cat-count>0</span>
+        </summary>
+        <div class="runwell-bundle-system__byob-accordion-body">
+          {%- 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{% 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="checkbox"
+                  class="runwell-bundle-system__byob-input"
+                  name="byob-pick"
+                  value="{{ candidate.handle }}"
+                  {% if is_required %}checked disabled{% 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: 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>
+                  {%- endif -%}
+                </span>
+              </label>
+            {%- endif -%}
+          {%- endfor -%}
+        </div>
+      </details>
+    {%- endfor -%}
+  </div>
+{%- else -%}
+  <p class="runwell-bundle-system__empty">Accordion layout requires bundle_byob_categories. Falling back to grid layout via runwell-bundle-byob-picker.liquid.</p>
+{%- endif -%}

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

@@ -0,0 +1,70 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-card.liquid.
+  Shared bundle card UI used by Surfaces 1, 2, 3, 4, 6.
+
+  Inputs:
+    bundle_product   (the bundle product to render; required)
+    variant          ('compact' | 'default' | 'hero'; default 'default')
+
+  Renders a self-contained card linking to /products/<bundle_handle>.
+  Loads the bundle's metafields locally via runwell-bundle-data so the
+  card has access to savings, supplier count, and component count.
+{%- endcomment -%}
+
+{%- if bundle_product != blank -%}
+  {%- assign card_variant = variant | default: 'default' -%}
+  {%- assign product = bundle_product -%}
+  {% render 'runwell-bundle-data', product: bundle_product %}
+  {%- assign component_count = 0 -%}
+  {%- if bundle_components and bundle_components.size > 0 -%}
+    {%- assign component_count = bundle_components.size -%}
+  {%- endif -%}
+
+  <a
+    href="{{ bundle_product.url }}"
+    class="runwell-bundle-card runwell-bundle-card--{{ card_variant }}"
+    data-bundle-handle="{{ bundle_product.handle }}"
+  >
+    <div class="runwell-bundle-card__media">
+      {%- if bundle_product.featured_image -%}
+        {{ bundle_product.featured_image | image_url: width: 600 | image_tag:
+          width: 300,
+          height: 300,
+          loading: 'lazy',
+          class: 'runwell-bundle-card__image',
+          alt: bundle_product.title,
+          sizes: '(min-width: 1024px) 25vw, 50vw'
+        }}
+      {%- endif -%}
+
+      {%- if bundle_savings_pct > 0 and card_variant != 'compact' -%}
+        <span class="runwell-bundle-card__badge">Save {{ bundle_savings_pct }}%</span>
+      {%- endif -%}
+    </div>
+
+    <div class="runwell-bundle-card__body">
+      <h3 class="runwell-bundle-card__title">{{ bundle_product.title }}</h3>
+
+      {%- if component_count > 0 and card_variant != 'compact' -%}
+        <p class="runwell-bundle-card__meta">
+          {{ component_count }}{% if component_count == 1 %} item{% else %} items{% endif %}
+          {%- if bundle_cross_supplier %} &middot; ships in {{ bundle_supplier_count }} packages{%- endif -%}
+        </p>
+      {%- endif -%}
+
+      <div class="runwell-bundle-card__price-row">
+        <span class="runwell-bundle-card__price">{{ bundle_price | money }}</span>
+        {%- if bundle_subtotal > bundle_price -%}
+          <span class="runwell-bundle-card__strikethrough">{{ bundle_subtotal | money }}</span>
+        {%- endif -%}
+        {%- if bundle_savings_pct > 0 and card_variant == 'compact' -%}
+          <span class="runwell-bundle-card__badge runwell-bundle-card__badge--inline">Save {{ bundle_savings_pct }}%</span>
+        {%- endif -%}
+      </div>
+
+      {%- if card_variant == 'hero' or card_variant == 'default' -%}
+        <span class="runwell-bundle-card__cta button button--secondary">View bundle</span>
+      {%- endif -%}
+    </div>
+  </a>
+{%- endif -%}

package/modules/runwell-bundle-system/snippets/runwell-bundle-cross-supplier.liquid

@@ -0,0 +1,18 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-cross-supplier.liquid.
+  Customer-facing disclosure when a bundle ships from multiple suppliers.
+  Copy template comes from the theme customizer setting
+  bundle_system__cross_supplier_disclosure (default: "This bundle ships
+  in {n} packages."), with {n} replaced by bundle_supplier_count.
+
+  Inputs:
+    bundle_supplier_count
+{%- endcomment -%}
+
+{%- assign template = settings.bundle_system__cross_supplier_disclosure | default: 'This bundle ships in {n} packages.' -%}
+{%- assign disclosure = template | replace: '{n}', bundle_supplier_count -%}
+
+<p class="runwell-bundle-system__cross-supplier" role="note">
+  <span class="runwell-bundle-system__cross-supplier-icon" aria-hidden="true">i</span>
+  <span class="runwell-bundle-system__cross-supplier-text">{{ disclosure }}</span>
+</p>

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

@@ -0,0 +1,75 @@
+{%- comment -%}
+  runwell-bundle-system: runwell-bundle-data.liquid.
+  Single read point for all runwell.bundle_* product metafields. Other
+  snippets and sections read the bundle_* Liquid variables this snippet
+  emits. Liquid has no first-class object literal so we emit flat vars
+  (bundle_mode, bundle_quantity_tiers, etc.) into the parent scope.
+
+  Usage:
+    {% render 'runwell-bundle-data', product: product %}
+    {{ bundle_mode }}
+    {% for tier in bundle_quantity_tiers %} ... {% endfor %}
+
+  See _clients/capital-v/lushi/specs/bundle-system/spec.md sections 2.1-2.2.
+{%- endcomment -%}
+
+{%- assign mf = product.metafields.runwell -%}
+
+{%- assign bundle_mode = mf.bundle_mode.value | default: 'multi_product' -%}
+{%- assign bundle_pricing_model = mf.bundle_pricing_model.value | default: 'fixed_price' -%}
+{%- assign bundle_pricing_value = mf.bundle_pricing_value.value -%}
+{%- assign bundle_components = mf.bundle_components.value -%}
+{%- assign bundle_quantity_tiers = mf.bundle_quantity_tiers.value -%}
+{%- assign bundle_show_in_catalog = mf.bundle_show_in_catalog.value | default: true -%}
+{%- assign bundle_surfaces_enabled = mf.bundle_surfaces_enabled.value -%}
+{%- assign bundle_copy = mf.bundle_copy.value -%}
+{%- assign bundle_free_gift_enabled = mf.bundle_free_gift_enabled.value | default: false -%}
+{%- assign bundle_free_gift_handle = mf.bundle_free_gift_handle.value | default: '' -%}
+{%- assign bundle_fomo_mode = mf.bundle_fomo_mode.value | default: 'none' -%}
+{%- assign bundle_fomo_cycle_days = mf.bundle_fomo_cycle_days.value | default: 30 -%}
+{%- assign bundle_fomo_stock_count = mf.bundle_fomo_stock_count.value | default: 0 -%}
+{%- assign bundle_cross_supplier = mf.bundle_cross_supplier.value | default: false -%}
+{%- 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 -%}
+  {%- for c in bundle_components -%}
+    {%- assign comp_product = all_products[c.product_handle] -%}
+    {%- assign comp_qty = c.qty | default: 1 -%}
+    {%- assign comp_line = comp_product.price | times: comp_qty -%}
+    {%- assign bundle_subtotal = bundle_subtotal | plus: comp_line -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- assign bundle_price = product.price -%}
+{%- assign bundle_savings_amount = 0 -%}
+{%- if bundle_subtotal > bundle_price -%}
+  {%- assign bundle_savings_amount = bundle_subtotal | minus: bundle_price -%}
+{%- endif -%}
+
+{%- assign bundle_savings_pct = 0 -%}
+{%- if bundle_savings_pct_pre -%}
+  {%- assign bundle_savings_pct = bundle_savings_pct_pre -%}
+{%- elsif bundle_subtotal > 0 -%}
+  {%- assign bundle_savings_pct = bundle_savings_amount | times: 100 | divided_by: bundle_subtotal -%}
+{%- endif -%}
+
+{%- comment -%}
+  v2 only fields (BS-13). Parsed but unused in v1.
+    bundle_subscription_enabled, bundle_subscription_interval,
+    bundle_subscription_discount_pct, bundle_subscription_badge_copy.
+{%- endcomment -%}
+{%- assign bundle_subscription_enabled = mf.subscription_enabled.value | default: false -%}
+{%- assign bundle_subscription_interval = mf.subscription_interval.value -%}
+{%- assign bundle_subscription_discount_pct = mf.subscription_discount_pct.value -%}
+{%- assign bundle_subscription_badge_copy = mf.subscription_badge_copy.value | default: '' -%}