@runwell/shopify-toolkit 0.1.0 → 0.2.0

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": {} }
+}

package/modules/quick-view/snippets/runwell-quickview-modal.liquid

@@ -0,0 +1,14 @@
+{%- comment -%}
+  Runwell quick-view modal shell. Render once at end of layout/theme.liquid:
+  {% render 'runwell-quickview-modal' %}
+{%- endcomment -%}
+
+<div class="runwell-quickview" data-runwell-quickview-modal aria-hidden="true" role="dialog" aria-labelledby="runwell-qv-title">
+  <div class="runwell-quickview__backdrop" data-runwell-quickview-close></div>
+  <div class="runwell-quickview__panel">
+    <button class="runwell-quickview__close" type="button" data-runwell-quickview-close aria-label="Close">&times;</button>
+    <div class="runwell-quickview__body" data-runwell-quickview-body></div>
+  </div>
+</div>
+
+<script src="{{ 'runwell-quickview.js' | asset_url }}" defer="defer"></script>

package/modules/quick-view/snippets/runwell-quickview-trigger.liquid

@@ -0,0 +1,19 @@
+{%- comment -%}
+  Runwell quick-view trigger button. Render inside card-product.liquid
+  near the product image:
+
+  {% render 'runwell-quickview-trigger', handle: card_product.handle %}
+{%- endcomment -%}
+
+<button
+  type="button"
+  class="runwell-quickview-trigger"
+  data-runwell-quickview
+  data-handle="{{ handle }}"
+  aria-label="Quick view"
+>
+  <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
+    <path d="M12 5C7 5 3 12 3 12s4 7 9 7 9-7 9-7-4-7-9-7zm0 11a4 4 0 110-8 4 4 0 010 8z" fill="currentColor"/>
+    <circle cx="12" cy="12" r="2" fill="#FFFFFF"/>
+  </svg>
+</button>

package/modules/subscriptions/README.md

@@ -0,0 +1,37 @@
+# subscriptions
+
+Brand-styled subscribe-and-save picker on top of Shopify's native Selling Plan API. Replaces Recharge / Bold Subscriptions / Appstle / Loop for the storefront display layer. Customer subscription management uses Shopify's native customer account.
+
+## Files
+
+- `snippets/runwell-subscription-picker.liquid`. Radio picker between one-time and subscribe-and-save.
+
+## How to use
+
+1. Run the merchant admin steps in `module.json` (install Shopify's free Subscriptions app, create a Selling Plan Group)
+2. Render the picker in `sections/main-product.liquid` BEFORE the `buy_buttons` block:
+   ```liquid
+   {% render 'runwell-subscription-picker', product: product %}
+   ```
+3. The picker emits a `selling_plan` form input that Dawn's buy-buttons snippet picks up automatically when present
+4. Style `.runwell-sub` selectors in your brand stylesheet
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `one_time_label` | `One-time purchase` | Label for the no-subscription option |
+| `subscribe_label` | `Subscribe and save` | Label for the subscription option |
+| `fineprint` | `Cancel anytime. Skip a delivery from your account.` | Microcopy under the picker |
+
+## Why no app
+
+Shopify ships native subscription primitives (Selling Plan API, native customer-account subscription tab) since 2021. The free Shopify Subscriptions app is the canonical UI for managing Selling Plan Groups. We use that for management; this module handles the storefront PDP picker.
+
+## Replaces
+
+Recharge, Bold Subscriptions, Appstle, Loop (display layer only; the management UX is Shopify's native account tab).
+
+## Plan requirement
+
+Works on **Shopify Basic and up**. The free Shopify Subscriptions app is required.

package/modules/subscriptions/module.json

@@ -0,0 +1,36 @@
+{
+  "name": "subscriptions",
+  "version": "0.1.0",
+  "category": "catalog",
+  "description": "Brand-styled subscribe-and-save picker that wraps Shopify's native Selling Plan API. Replaces Recharge / Bold Subscriptions / Appstle for the storefront display layer; subscription management still uses Shopify's native customer account.",
+  "files": {
+    "snippets": ["snippets/runwell-subscription-picker.liquid"]
+  },
+  "config": {
+    "schema": {
+      "one_time_label": { "type": "string", "default": "One-time purchase" },
+      "subscribe_label": { "type": "string", "default": "Subscribe and save" },
+      "fineprint": { "type": "string", "default": "Cancel anytime. Skip a delivery from your account." }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "install-shopify-subscriptions",
+      "label": "Install Shopify's free Subscriptions app",
+      "url": "https://apps.shopify.com/shopify-subscriptions",
+      "summary": "Install the Subscriptions app made by Shopify (free, first-party). Required to expose Selling Plan Groups."
+    },
+    {
+      "id": "create-selling-plan-group",
+      "label": "Create a Selling Plan Group",
+      "url": "https://admin.shopify.com/store/{store_handle}/apps",
+      "summary": "Apps > Subscriptions > Create plan. Name 'Subscribe and save'. Add delivery options every 30/60/90 days. Apply 15% discount on subscription orders. Apply to selected products."
+    },
+    {
+      "id": "enable-customer-account-tab",
+      "label": "Verify Subscriptions tab on customer account",
+      "url": "https://admin.shopify.com/store/{store_handle}/settings/customer_accounts",
+      "summary": "Settings > Customer accounts > Customize. Confirm the Subscriptions section is enabled. Customers will see skip/cancel/change frequency from /account."
+    }
+  ]
+}

package/modules/subscriptions/snippets/runwell-subscription-picker.liquid

@@ -0,0 +1,35 @@
+{%- comment -%}
+  Runwell subscription picker. Brand-styled radio between one-time and
+  subscribe-and-save when a product has selling_plan_groups configured.
+  Render inside main-product.liquid where the buy buttons live, BEFORE
+  the buy_buttons block:
+
+  {% render 'runwell-subscription-picker', product: product %}
+
+  Requires:
+  - Shopify Subscriptions app installed (free, made by Shopify)
+  - At least one Selling Plan Group attached to the product
+{%- endcomment -%}
+
+{%- if product != blank and product.selling_plan_groups.size > 0 -%}
+  {%- assign group = product.selling_plan_groups[0] -%}
+  <fieldset class="runwell-sub" data-runwell-subscription-picker>
+    <legend class="visually-hidden">Purchase type</legend>
+    <label class="runwell-sub__option">
+      <input type="radio" name="selling_plan" value="" checked>
+      <span class="runwell-sub__title">{{config.one_time_label}}</span>
+      <span class="runwell-sub__price">{{ product.price | money }}</span>
+    </label>
+    {%- for plan in group.selling_plans -%}
+      <label class="runwell-sub__option runwell-sub__option--featured">
+        <input type="radio" name="selling_plan" value="{{ plan.id }}">
+        <span class="runwell-sub__title">
+          {{config.subscribe_label}}
+          <span class="runwell-sub__discount">{{ plan.price_adjustments[0].value }}% off</span>
+        </span>
+        <span class="runwell-sub__detail">{{ plan.name }}</span>
+      </label>
+    {%- endfor -%}
+    <p class="runwell-sub__fineprint">{{config.fineprint}}</p>
+  </fieldset>
+{%- endif -%}

package/modules/wishlist/README.md

@@ -0,0 +1,48 @@
+# wishlist
+
+Native wishlist using localStorage. Replaces Wishlist Plus, Wishlist King, Globo Wishlist. App-free.
+
+## Files
+
+- `assets/runwell-wishlist.js`. Core storage + UI logic. ~120 LOC, no dependencies.
+- `snippets/runwell-wishlist-icon.liquid`. Heart button to drop into card-product or main-product.
+- `sections/runwell-wishlist-page.liquid`. Section that hydrates the dedicated wishlist page.
+- `templates/page.wishlist.json`. Page template wiring the section to the `/pages/wishlist` URL.
+
+## How to use
+
+1. Sync the module: `runwell-shopify sync`
+2. Add the heart icon wherever a product is listed:
+   ```liquid
+   {% render 'runwell-wishlist-icon', handle: card_product.handle %}
+   ```
+3. Create the Wishlist page in admin (see admin_steps in module.json):
+   - Pages > Add page > Title "Wishlist" > Visible > Theme template "page.wishlist" > Save
+4. Visit `/pages/wishlist` to see the saved items hydrate from localStorage.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `max_items` | `100` | Max items kept in localStorage. Excess trimmed FIFO. |
+
+## Storage
+
+| Surface | Mechanism |
+|---|---|
+| Guest user | `localStorage["runwell_wishlist"] = ["handle-1", ...]` |
+| Logged-in customer | localStorage only in v0.1; metafield sync is v0.2 (requires App Proxy) |
+
+## Events
+
+The module dispatches `runwell:wishlist:change` on `document` whenever an item is added or removed. Useful if you want to update a header counter:
+
+```js
+document.addEventListener('runwell:wishlist:change', function (e) {
+  console.log('count:', e.detail.count);
+});
+```
+
+## Replaces
+
+Wishlist Plus, Wishlist King, Globo Wishlist (display layer; the metafield sync option in those apps is the only feature not yet built).

package/modules/wishlist/assets/runwell-wishlist.js

@@ -0,0 +1,112 @@
+/* Runwell wishlist. localStorage-backed for guests; reads/writes
+   customer metafield lushi.wishlist when logged in (writes require an
+   App Proxy; v1 ships localStorage only, sync to metafield is v0.2).
+   Replaces Wishlist Plus, Wishlist King, Globo Wishlist. */
+(function () {
+  if (typeof window === 'undefined') return;
+  var KEY = 'runwell_wishlist';
+  var MAX = 100;
+
+  function read() {
+    try { return JSON.parse(localStorage.getItem(KEY) || '[]'); } catch (e) { return []; }
+  }
+  function write(list) {
+    try { localStorage.setItem(KEY, JSON.stringify(list.slice(0, MAX))); } catch (e) {}
+  }
+  function has(handle) { return read().indexOf(handle) !== -1; }
+  function add(handle) {
+    var list = read().filter(function (h) { return h !== handle; });
+    list.unshift(handle);
+    write(list);
+    fire('add', handle);
+  }
+  function remove(handle) {
+    var list = read().filter(function (h) { return h !== handle; });
+    write(list);
+    fire('remove', handle);
+  }
+  function toggle(handle) {
+    if (has(handle)) { remove(handle); return false; }
+    add(handle); return true;
+  }
+  function fire(action, handle) {
+    var event = new CustomEvent('runwell:wishlist:change', { detail: { action: action, handle: handle, count: read().length } });
+    document.dispatchEvent(event);
+  }
+
+  function bindButtons() {
+    document.querySelectorAll('[data-runwell-wishlist]').forEach(function (btn) {
+      if (btn.dataset.runwellWishlistBound === '1') return;
+      btn.dataset.runwellWishlistBound = '1';
+      var handle = btn.getAttribute('data-handle');
+      if (!handle) return;
+      function refresh() {
+        if (has(handle)) {
+          btn.setAttribute('aria-pressed', 'true');
+          btn.classList.add('is-saved');
+        } else {
+          btn.setAttribute('aria-pressed', 'false');
+          btn.classList.remove('is-saved');
+        }
+      }
+      btn.addEventListener('click', function (e) {
+        e.preventDefault();
+        toggle(handle);
+        refresh();
+      });
+      refresh();
+    });
+  }
+
+  function renderPage() {
+    var host = document.querySelector('[data-runwell-wishlist-page]');
+    if (!host) return;
+    var handles = read();
+    var grid = host.querySelector('[data-runwell-wishlist-grid]');
+    var emptyState = host.querySelector('[data-runwell-wishlist-empty]');
+    if (!handles.length) {
+      if (emptyState) emptyState.style.display = '';
+      if (grid) grid.style.display = 'none';
+      return;
+    }
+    if (emptyState) emptyState.style.display = 'none';
+    if (grid) grid.style.display = '';
+
+    Promise.all(handles.map(function (h) {
+      return fetch('/products/' + h + '.js').then(function (r) { return r.ok ? r.json() : null; }).catch(function () { return null; });
+    })).then(function (products) {
+      if (!grid) return;
+      grid.innerHTML = products.filter(Boolean).map(function (p) {
+        var img = p.featured_image ? '<img src="' + p.featured_image + '" alt="' + p.title + '" loading="lazy">' : '';
+        var price = (p.price / 100).toFixed(2);
+        return '<a class="runwell-wishlist__card" href="/products/' + p.handle + '">' +
+                 '<div class="runwell-wishlist__media">' + img + '</div>' +
+                 '<div class="runwell-wishlist__title">' + p.title + '</div>' +
+                 '<div class="runwell-wishlist__price">$' + price + '</div>' +
+                 '<button type="button" class="runwell-wishlist__remove" data-handle="' + p.handle + '" aria-label="Remove from wishlist">Remove</button>' +
+               '</a>';
+      }).join('');
+
+      grid.querySelectorAll('.runwell-wishlist__remove').forEach(function (btn) {
+        btn.addEventListener('click', function (e) {
+          e.preventDefault();
+          remove(btn.getAttribute('data-handle'));
+          renderPage();
+        });
+      });
+    });
+  }
+
+  window.runwellWishlist = { has: has, add: add, remove: remove, toggle: toggle, list: read };
+
+  function init() {
+    bindButtons();
+    renderPage();
+  }
+  document.addEventListener('runwell:wishlist:change', bindButtons);
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();

package/modules/wishlist/module.json

@@ -0,0 +1,25 @@
+{
+  "name": "wishlist",
+  "version": "0.1.0",
+  "category": "customer",
+  "description": "Native wishlist using localStorage. Heart icon on cards + dedicated /pages/wishlist page. v1 ships localStorage; metafield sync via App Proxy is v0.2. Replaces Wishlist Plus, Wishlist King, Globo Wishlist.",
+  "files": {
+    "assets": ["assets/runwell-wishlist.js"],
+    "snippets": ["snippets/runwell-wishlist-icon.liquid"],
+    "sections": ["sections/runwell-wishlist-page.liquid"],
+    "templates": ["templates/page.wishlist.json"]
+  },
+  "config": {
+    "schema": {
+      "max_items": { "type": "number", "default": 100 }
+    }
+  },
+  "admin_steps": [
+    {
+      "id": "create-wishlist-page",
+      "label": "Create the wishlist page in Shopify admin",
+      "url": "https://admin.shopify.com/store/{store_handle}/pages/new",
+      "summary": "Create a Page with title 'Wishlist'. Set visibility Visible. In the Theme template dropdown, select 'page.wishlist'. Save."
+    }
+  ]
+}