@occluze/tether 0.5.0 → 0.6.0

package/src/analytics.js

@@ -0,0 +1,232 @@
+/**
+ * Analytics, as an optional part (loaded when config.analytics is set).
+ *
+ *   analytics: {
+ *     dataLayer: true,        // GA4 / Google Tag Manager ecommerce events (window.dataLayer)
+ *     shopify: true,          // Shopify's own analytics (experimental, see docs/analytics.md)
+ *     onEvent(name, data) {}, // any other tool: Meta, TikTok, Plausible, …
+ *   }
+ *
+ * Events: view_item (the page's product), view_item_list (lists), add_to_cart / remove_from_cart
+ * (from the cart's changes, so quick +/- and JS calls count too), view_cart (cart opened),
+ * begin_checkout, search (search as you type). Purchases happen on Shopify's checkout: use
+ * Shopify's Google & YouTube app or a checkout pixel for those.
+ *
+ * Shopify analytics: Tether sets up the same event bus Hydrogen uses (window.Shopify.analytics) and
+ * loads Shopify's consent script and shopify.js, which build and send the events. Nothing is sent
+ * before the Customer Privacy API allows analytics.
+ */
+import { cfg, log, reportError } from './config.js';
+import { gql } from './client.js';
+import { sel } from './dom.js';
+import { Cart } from './cart.js';
+
+const num = (m) => (m ? parseFloat(m.amount) : 0);
+const id = (gid) => String(gid || '').split('/').pop();
+
+// ---------------------------------------------------------------- shapes
+
+function itemFromVariant(p, v, quantity = 1, index) {
+  return {
+    item_id: v?.sku || id(v?.id) || id(p.id),
+    item_name: p.title,
+    item_variant: v?.title === 'Default Title' ? undefined : v?.title,
+    item_brand: p.vendor || undefined,
+    item_category: p.productType || undefined,
+    price: num(v?.price || p.priceRange?.minVariantPrice),
+    quantity,
+    ...(index != null ? { index } : {}),
+  };
+}
+
+function itemFromLine(l, quantity = l.quantity) {
+  const m = l.merchandise || {};
+  return itemFromVariant({ ...(m.product || {}), title: m.product?.title }, m, quantity);
+}
+
+const value = (items) => Math.round(items.reduce((s, i) => s + (i.price || 0) * (i.quantity || 1), 0) * 100) / 100;
+
+// ---------------------------------------------------------------- GA4 / GTM
+
+function ga(event, ecommerce) {
+  const name = typeof cfg.analytics.dataLayer === 'string' ? cfg.analytics.dataLayer : 'dataLayer';
+  const dl = (window[name] = window[name] || []);
+  if (ecommerce) dl.push({ ecommerce: null }); // Google: clear the previous ecommerce object first
+  dl.push(ecommerce ? { event, ecommerce } : { event });
+}
+
+// ---------------------------------------------------------------- Shopify analytics (Hydrogen's bus)
+
+let bus = null;
+
+function shopifyBus(shopId) {
+  const destinations = [];
+  const buffer = [];
+  const privacy = () => window.Shopify?.customerPrivacy;
+  const canTrack = () => {
+    try {
+      const p = privacy();
+      return p?.consentStatus === 'loaded' && p.currentVisitorConsent?.()?.analytics !== 'no' && Boolean(p.analyticsProcessingAllowed?.());
+    } catch { return false; }
+  };
+  const config = { shop: { shopId, channel: 'headless' }, consent: { mode: cfg.analytics.shopify?.consent || 'no-banner' } };
+  const deliver = () => {
+    if (!canTrack()) return;
+    destinations.forEach((d) => {
+      while (d.next < buffer.length) {
+        const { event, payload } = buffer[d.next++];
+        (d.subs.get(event) || []).forEach((cb) => { try { cb(payload, d.context); } catch (err) { reportError(err, `analytics ${d.name}`); } });
+      }
+    });
+  };
+  const api = {
+    getConfig: () => config,
+    publish(event, payload = {}) {
+      buffer.push({ event, payload: { shop: config.shop, url: window.location.href, ...payload } });
+      if (buffer.length > 500) { buffer.shift(); destinations.forEach((d) => { d.next = Math.max(0, d.next - 1); }); }
+      deliver();
+    },
+    addDestination(dest) {
+      const tag = `hydrogen:${dest.name}`;
+      const d = {
+        name: dest.name, next: 0, subs: new Map(),
+        context: {
+          getTrackingValues: () => {
+            const i = canTrack() ? privacy()?.__internal : null;
+            return { uniqueToken: i?.uniqueToken?.({ generateFallback: true, tag }) ?? '', visitToken: i?.visitToken?.({ generateFallback: true, tag }) ?? '' };
+          },
+        },
+      };
+      const subscribe = (event, cb) => {
+        if (!d.subs.has(event)) d.subs.set(event, new Set());
+        d.subs.get(event).add(cb);
+        return () => d.subs.get(event)?.delete(cb);
+      };
+      Promise.resolve(dest.setup?.({ subscribe, getConfig: api.getConfig })).then(() => { destinations.push(d); deliver(); })
+        .catch((err) => reportError(err, `analytics ${dest.name}`));
+      return () => { const i = destinations.indexOf(d); if (i >= 0) destinations.splice(i, 1); };
+    },
+  };
+  document.addEventListener('consentTrackingApiLoaded', deliver);
+  document.addEventListener('visitorConsentCollected', deliver);
+  return api;
+}
+
+function loadScript(src) {
+  const s = document.createElement('script');
+  s.src = src;
+  s.async = true;
+  document.head.appendChild(s);
+}
+
+async function startShopify() {
+  if (window.Shopify?.analytics) { bus = window.Shopify.analytics; return; } // already set up (e.g. by the theme)
+  const data = await gql('query TetherShopId { shop { id } }', {}, { context: false });
+  const country = String(cfg.country || 'US').toUpperCase();
+  const S = (window.Shopify = window.Shopify || {});
+  Object.assign(S, {
+    country,
+    locale: (cfg.locale || 'en').split('-')[0].toLowerCase(), // required by Shopify's script
+    shop: cfg.domain,
+    routes: { root: '/', match: () => ({ pageTemplateName: mainProduct() ? 'product' : 'page' }), ...(S.routes || {}) },
+  });
+  const proxy = cfg.analytics.shopify?.proxy; // same-origin Storefront API path, for exact visitor counts
+  S.customerPrivacy = {
+    ...(S.customerPrivacy || {}),
+    config: proxy
+      ? { isHeadless: true, asyncConsent: true, asyncVisitorState: true, consentDomain: window.location.host }
+      : { isHeadless: true, storefrontAccessToken: cfg.token, checkoutRootDomain: cfg.domain },
+  };
+  bus = shopifyBus(data.shop.id);
+  S.analytics = bus;
+  loadScript(cfg.analytics.shopify?.consent === 'default-banner'
+    ? 'https://cdn.shopify.com/shopifycloud/privacy-banner/storefront-banner.js'
+    : 'https://cdn.shopify.com/shopifycloud/consent-tracking-api/v0.2/consent-tracking-api.js');
+  loadScript('https://cdn.shopify.com/storefront/analytics/shopify.js');
+  log('shopify analytics ready', data.shop.id);
+}
+
+const productPayload = (p, v, quantity = 1) => ({
+  id: p.id, title: p.title, price: v.price, vendor: p.vendor || '', variantId: v.id, variantTitle: v.title,
+  quantity, sku: v.sku || undefined, productType: p.productType || undefined,
+});
+
+function analyticsLine(l) {
+  const m = l.merchandise || {};
+  return { id: l.id, quantity: l.quantity, merchandise: { id: m.id, title: m.title, price: m.price, sku: m.sku, product: { id: m.product?.id, title: m.product?.title, vendor: m.product?.vendor || '', handle: m.product?.handle } } };
+}
+
+// ---------------------------------------------------------------- what happened on the page
+
+function mainProduct() {
+  const el = document.querySelector(sel('product'));
+  return el && !el.closest(`${sel('collection')},${sel('products')},${sel('recommendations')}`) ? window.Tether?.getScope(el) : null;
+}
+
+const send = (name, data, shopifyEvent, shopifyPayload) => {
+  if (cfg.analytics.dataLayer) ga(name, data);
+  if (bus && shopifyEvent) bus.publish(shopifyEvent, shopifyPayload);
+  try { cfg.analytics.onEvent?.(name, data); } catch (err) { reportError(err, 'analytics onEvent'); }
+};
+
+let lastLines = null; // variant id -> line, to turn cart changes into add/remove events
+let viewed = new WeakSet();
+
+function handle(e) {
+  const name = e.type.slice(cfg.prefix.length + 1);
+  const d = e.detail || {};
+  if (name === 'product-ready') {
+    const scope = d.scope;
+    if (!scope || viewed.has(scope.root) || mainProduct() !== scope) return;
+    viewed.add(scope.root);
+    const v = scope.variant || d.product.variants.nodes[0];
+    const items = [itemFromVariant(d.product, v)];
+    send('view_item', { currency: v?.price?.currencyCode, value: value(items), items }, 'product_viewed', { products: [productPayload(d.product, v)] });
+  } else if (name === 'list-ready') {
+    const items = (d.products || []).slice(0, 200).map((p, i) => itemFromVariant(p, p.variants?.nodes?.[0], 1, i));
+    const list = { item_list_id: d.collection?.handle || 'products', item_list_name: d.collection?.title || 'Products' };
+    send('view_item_list', { ...list, items }, d.collection ? 'collection_viewed' : null, d.collection ? { collection: { id: d.collection.id, handle: d.collection.handle } } : null);
+  } else if (name === 'cart-updated') {
+    const cart = d.cart;
+    const now = new Map((cart?.lines?.nodes || []).map((l) => [l.merchandise?.id, l]));
+    if (lastLines && d.reason !== 'load' && d.reason !== 'pending') {
+      const currency = cart?.cost?.totalAmount?.currencyCode;
+      now.forEach((l, k) => {
+        const diff = l.quantity - (lastLines.get(k)?.quantity || 0);
+        if (diff > 0) {
+          const items = [itemFromLine(l, diff)];
+          send('add_to_cart', { currency, value: value(items), items }, 'product_added_to_cart', {
+            cart, prevCart: lastCart, currentLine: analyticsLine(l), prevLine: lastLines.get(k) ? analyticsLine(lastLines.get(k)) : undefined,
+          });
+        }
+      });
+      lastLines.forEach((l, k) => {
+        const diff = l.quantity - (now.get(k)?.quantity || 0);
+        if (diff > 0) { const items = [itemFromLine(l, diff)]; send('remove_from_cart', { currency, value: value(items), items }); }
+      });
+    }
+    lastLines = now;
+    lastCart = cart;
+  } else if (name === 'cart-toggled' && d.open) {
+    const items = Cart.lines.map((l) => itemFromLine(l));
+    send('view_cart', { currency: Cart.state?.cost?.totalAmount?.currencyCode, value: value(items), items });
+  } else if (name === 'checkout') {
+    const items = (d.cart?.lines?.nodes || []).map((l) => itemFromLine(l));
+    const coupon = (d.cart?.discountCodes || []).filter((c) => c.applicable).map((c) => c.code).join(',') || undefined;
+    send('begin_checkout', { currency: d.cart?.cost?.totalAmount?.currencyCode, value: value(items), coupon, items });
+  } else if (name === 'search' && d.term) {
+    send('search', { search_term: d.term }, 'search_viewed', { searchTerm: d.term });
+  } else if (name === 'page') {
+    viewed = new WeakSet();
+    if (bus) bus.publish('page_viewed', {});
+  }
+}
+let lastCart = null;
+
+/** Called by the core with the events it buffered while this part loaded. */
+export async function startAnalytics(queue) {
+  if (cfg.analytics.shopify) await startShopify().catch((err) => reportError(err, 'shopify analytics'));
+  if (bus) bus.publish('page_viewed', {});
+  queue.splice(0).forEach(handle);
+  queue.push = (e) => { handle(e); return 0; }; // from now on, handle events as they come
+}

package/src/astro.js

@@ -65,7 +65,10 @@ export default function tether(options = {}) {
         injectScript('head-inline', 'window.TETHER_INTEGRATION="astro";');
         injectScript('page', [
           "import Tether from '@occluze/tether';",
-          `Tether.init({ ...${JSON.stringify({ autoMount: false, ...config })}, ...(window.TETHER_CONFIG || {}) }).then(() => Tether.mount(document));`,
+          // As the base config (like window.TETHER_CONFIG), not as overrides: a visitor's saved market
+          // (country, money format) then wins over the defaults, as on a plain script-tag site.
+          `window.TETHER_CONFIG = { ...${JSON.stringify({ autoMount: false, ...config })}, ...(window.TETHER_CONFIG || {}) };`,
+          'Tether.init().then(() => Tether.mount(document));',
         ].join('\n'));
       },
     },

package/src/cart.js

@@ -29,7 +29,7 @@ export function toLineInput(input, quantity = 1, opts = {}) {
 
 function mutation(name, args, inner) {
   return `mutation Tether_${name}(${args}) {
-  ${name}(${inner}) { cart { ...TetherCart } userErrors { field message } warnings { code message } }
+  ${name}(${inner}) { cart { ...TetherCart } userErrors { field message } warnings { code message target } }
 }
 ${cartFragment()}`;
 }
@@ -47,7 +47,8 @@ function ariaState(open) {
     if (!d.hasAttribute('role')) d.setAttribute('role', 'dialog');
     if (!d.hasAttribute('aria-label') && !d.hasAttribute('aria-labelledby')) d.setAttribute('aria-label', get(d, 'cart-label') || 'Cart');
     d.setAttribute('aria-modal', String(open));
-    if (!d.classList.contains(cfg.cartDrawerOpenClass)) d.setAttribute('aria-hidden', 'true');
+    // Closed: hidden from screen readers and out of the Tab order (inert), like a closed dialog.
+    if (!d.classList.contains(cfg.cartDrawerOpenClass)) { d.setAttribute('aria-hidden', 'true'); if (cfg.cartFocus !== false) d.inert = true; }
   });
 }
 
@@ -69,6 +70,10 @@ export const Cart = {
   get count() { return this.state?.totalQuantity || 0; },
 
   lastError: null,
+  /** Set by the account part while a customer is logged in (Customer Account API token). */
+  customerAccessToken: null,
+  /** line id -> { qty, done }: what quick +/- clicks asked for, shown until Shopify has answered. */
+  pendingQty: new Map(),
   /** Shopify's notes on the last change, e.g. less stock than asked: [{ code, message }]. */
   warnings: [],
   /** true once the saved cart (or the absence of one) is known. */
@@ -76,7 +81,9 @@ export const Cart = {
 
   _take(payload, name) {
     const p = unwrap(payload, name);
-    this.warnings = p.warnings || [];
+    // Shopify can repeat a warning per line or code: each message once.
+    this.warnings = (p.warnings || []).filter((w, i, all) => all.findIndex((x) => x.message === w.message) === i)
+      .map((w) => ({ ...w, message: (typeof cfg.warningText === 'function' && cfg.warningText(w)) || w.message }));
     if (this.warnings.length) emit('cart-warning', { warnings: this.warnings });
     return p.cart;
   },
@@ -99,6 +106,8 @@ export const Cart = {
   _commit(cart, reason) {
     this.state = cart;
     if (cart?.id) this._setId(cart.id);
+    // Other tabs reload the cart (storage event); the count also shows at once on the next page.
+    try { localStorage.setItem(`${cfg.storageKey}:seen`, `${Date.now()}|${cart?.totalQuantity || 0}`); } catch { /* private mode */ }
     this.render();
     emit('cart-updated', { cart, reason });
     return cart;
@@ -107,6 +116,13 @@ export const Cart = {
   async init() {
     const id = this.id();
     if (!id) { this.state = null; this.loaded = true; this.render(); emit('cart-updated', { cart: null, reason: 'load' }); return null; }
+    // Until the saved cart has loaded, show its last known count instead of the page's 0.
+    if (!this.loaded) {
+      try {
+        const n = (localStorage.getItem(`${cfg.storageKey}:seen`) || '').split('|')[1];
+        if (n) qsa(document, sel('cart-count')).forEach((el) => { if (/^\s*0?\s*$/.test(el.textContent)) el.textContent = n; });
+      } catch { /* private mode */ }
+    }
     try {
       const data = await gql(`query TetherCart($id: ID!) { cart(id: $id) { ...TetherCart } }\n${cartFragment()}`, { id });
       if (!data.cart) { this._setId(null); this.state = null; } else this.state = data.cart;
@@ -124,7 +140,10 @@ export const Cart = {
   },
 
   async _create(input = {}) {
-    const buyerIdentity = cfg.country ? { countryCode: String(cfg.country).toUpperCase() } : undefined;
+    const buyerIdentity = cfg.country || this.customerAccessToken ? {
+      ...(cfg.country ? { countryCode: String(cfg.country).toUpperCase() } : {}),
+      ...(this.customerAccessToken ? { customerAccessToken: this.customerAccessToken } : {}),
+    } : undefined;
     const data = await gql(
       mutation('cartCreate', '$input: CartInput!', 'input: $input'),
       { input: { buyerIdentity, ...input } },
@@ -186,6 +205,26 @@ export const Cart = {
     ));
   },
 
+  /**
+   * +1 / -1 for a line. Quick clicks add up: each builds on the quantity the last click asked for,
+   * which shows at once (tether-line="quantity", Cart.lines) until Shopify has answered.
+   */
+  changeQuantity(lineId, delta) {
+    const current = this.lines.find((l) => l.id === lineId);
+    if (!current) return Promise.resolve(this.state);
+    const target = Math.max(0, (this.pendingQty.get(lineId)?.qty ?? current.quantity) + delta);
+    const job = { qty: target, done: false };
+    this.pendingQty.set(lineId, job);
+    this.render();
+    emit('cart-updated', { cart: this.state, reason: 'pending' });
+    return this.updateLine(lineId, target).finally(() => {
+      if (this.pendingQty.get(lineId) === job) { this.pendingQty.delete(lineId); this.render(); emit('cart-updated', { cart: this.state, reason: 'settled' }); }
+    });
+  },
+
+  /** Quantity to show for a line: the one asked for while an update is on its way. */
+  quantityOf(line) { return this.pendingQty.get(line.id)?.qty ?? line.quantity; },
+
   removeLine(lineIds) {
     const ids = Array.isArray(lineIds) ? lineIds : [lineIds];
     return this._queue(async () => this._commit(
@@ -227,9 +266,17 @@ export const Cart = {
     ));
   },
 
-  applyDiscount(code) {
+  /**
+   * Adds a code. A code Shopify doesn't accept isn't kept in the cart (it would warn on every change):
+   * it's removed again and the promise rejects with code INVALID_DISCOUNT.
+   */
+  async applyDiscount(code) {
     const current = (this.state?.discountCodes || []).map((d) => d.code);
-    return this.setDiscountCodes([...new Set([...current, code])]);
+    const cart = await this.setDiscountCodes([...new Set([...current, code])]);
+    const hit = (cart?.discountCodes || []).find((d) => d.code.toLowerCase() === String(code).toLowerCase());
+    if (hit?.applicable) return cart;
+    await this.removeDiscount(code).catch(() => {});
+    throw new TetherError(`Discount code not valid: ${code}`, { code: 'INVALID_DISCOUNT' });
   },
 
   removeDiscount(code) {
@@ -263,7 +310,8 @@ export const Cart = {
 
     try {
       const data = await gql('query TetherCheckout($id: ID!) { cart(id: $id) { checkoutUrl } }', { id });
-      const url = data.cart?.checkoutUrl;
+      let url = (this.beforeCheckout && await this.beforeCheckout().catch(() => null)) || data.cart?.checkoutUrl;
+      if (url && this.customerAccessToken) url += `${url.includes('?') ? '&' : '?'}logged_in=true`;
       if (!url) throw new TetherError('No checkoutUrl (cart empty or expired)');
       emit('checkout', { url, cart: this.state });
       if (tab && !tab.closed) tab.location.href = url;
@@ -280,12 +328,18 @@ export const Cart = {
 
   drawers() { return qsa(document, sel('cart-drawer')); },
 
-  isOpen() { return this.drawers().some((d) => d.classList.contains(cfg.cartDrawerOpenClass)); },
+  /** Without a tether-cart-drawer (a React/Svelte/Vue cart), open/close still work: as state for subscribe. */
+  _open: false,
+  isOpen() {
+    const ds = this.drawers();
+    return ds.length ? ds.some((d) => d.classList.contains(cfg.cartDrawerOpenClass)) : this._open;
+  },
 
   open() {
     if (this.isOpen()) return;
+    this._open = true;
     const ds = this.drawers().filter((d) => get(d, 'cart-drawer') !== 'manual');
-    ds.forEach((d) => { d.classList.add(cfg.cartDrawerOpenClass); d.setAttribute('aria-hidden', 'false'); });
+    ds.forEach((d) => { d.inert = false; d.classList.add(cfg.cartDrawerOpenClass); d.setAttribute('aria-hidden', 'false'); });
     ariaState(true);
     if (cfg.cartFocus !== false && ds[0]) {
       // Move focus into the cart (after the open transition has made it visible).
@@ -302,9 +356,10 @@ export const Cart = {
 
   close() {
     if (!this.isOpen()) return;
+    this._open = false;
     const ds = this.drawers();
     const hadFocus = ds.some((d) => d.contains(document.activeElement));
-    ds.forEach((d) => { d.classList.remove(cfg.cartDrawerOpenClass); d.setAttribute('aria-hidden', 'true'); });
+    ds.forEach((d) => { d.classList.remove(cfg.cartDrawerOpenClass); d.setAttribute('aria-hidden', 'true'); if (cfg.cartFocus !== false) d.inert = true; });
     ariaState(false);
     if (hadFocus && returnFocus?.isConnected) returnFocus.focus({ preventScroll: true });
     returnFocus = null;
@@ -397,7 +452,7 @@ function lineValue(line, key) {
     case 'compare-at-price': return formatMoney(line.cost?.compareAtAmountPerQuantity || m.compareAtPrice);
     case 'line-total': return formatMoney(line.cost?.totalAmount);
     case 'line-subtotal': return formatMoney(line.cost?.subtotalAmount);
-    case 'quantity': return line.quantity;
+    case 'quantity': return Cart.quantityOf(line);
     case 'plan': return plan?.name || '';
     case 'plan-description': return plan?.description || '';
     case 'components': return (line.lineComponents || [])
@@ -434,11 +489,19 @@ function renderLine(node, line) {
     return undefined;
   });
 
+  // Shopify's note about this line (e.g. less stock than asked): class is-warning, tether-line="warning".
+  const warning = Cart.warnings.find((w) => w.target === line.id);
+  node.classList.toggle('is-warning', Boolean(warning));
+  const pending = Cart.pendingQty.has(line.id);
+  node.classList.toggle('is-busy', pending);
+  if (pending) node.setAttribute('aria-busy', 'true'); else node.removeAttribute('aria-busy');
+  qsa(node, sel('line', 'warning')).forEach((el) => setTextTracked(el, warning?.message || ''));
   const lineConds = {
     subscription: isSub,
     'one-time': !isSub,
     'on-sale': parseFloat(line.cost?.compareAtAmountPerQuantity?.amount) > parseFloat(line.cost?.amountPerQuantity?.amount),
     'has-components': (line.lineComponents || []).length > 0,
+    warning: Boolean(warning),
   };
   qsa(node, sel('line-show')).forEach((el) => {
     const k = get(el, 'line-show');

package/src/client.js

@@ -48,7 +48,12 @@ export async function request(conf, query, variables = {}, { context = true } =
     throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
   }
 
-  const body = JSON.stringify({ query: context ? withContext(query, conf) : query, variables });
+  // Shopify caches the response of an identical query text (prices included, for hours after a
+  // change). A time bucket in a comment keeps answers at most maxAge seconds old (default 60).
+  let text = context ? withContext(query, conf) : query;
+  const age = conf.maxAge ?? 60;
+  if (age > 0 && !/^\s*mutation\b/.test(text)) text += ` #${Math.floor(Date.now() / (age * 1000))}`;
+  const body = JSON.stringify({ query: text, variables });
   let attempt = 0;
 
   for (;;) {
@@ -89,8 +94,8 @@ export async function request(conf, query, variables = {}, { context = true } =
         return request(conf, query.replace(/\bquantityAvailable\b/g, ''), variables, { context });
       }
       // An older apiVersion without cart warnings (before 2024-07): retry without them.
-      if (json.errors.some((e) => /'warnings'/.test(e.message || '')) && /warnings \{ code message \}/.test(query)) {
-        return request(conf, query.replace(/ warnings \{ code message \}/g, ''), variables, { context });
+      if (json.errors.some((e) => /'warnings'/.test(e.message || '')) && /warnings \{ code message target \}/.test(query)) {
+        return request(conf, query.replace(/ warnings \{ code message target \}/g, ''), variables, { context });
       }
       const throttled = json.errors.some((e) => e.extensions?.code === 'THROTTLED');
       if (throttled && attempt++ < conf.retries) { await sleep(500 * 2 ** attempt); continue; }

package/src/collection.js

@@ -5,9 +5,10 @@
  * quick-add with a subscription toggle).
  */
 import { reportError } from './config.js';
-import { attr, sel, get, has, scoped, emit, setText, setImage, repeat, notifyLayoutChanged, busy } from './dom.js';
-import { getProducts, getRecommendations, getProduct } from './loader.js';
-import { setScopeStatus, isNotFound } from './status.js';
+import { TetherError } from './client.js';
+import { attr, sel, get, has, scoped, emit, setText, setImage, repeat, notifyLayoutChanged, busy, show } from './dom.js';
+import { getProducts, getRecommendations } from './loader.js';
+import { setScopeStatus, isNotFound, resolveProductKey } from './status.js';
 
 export const listSelector = () => `${sel('collection')},${sel('products')},${sel('recommendations')}`;
 
@@ -46,9 +47,12 @@ export class ListScope {
     const stale = () => token !== this.loadToken;
     try {
       if (has(this.root, 'recommendations')) {
-        const key = get(this.root, 'recommendations');
-        const base = await getProduct(key);
-        const recs = await getRecommendations(base.id, get(this.root, 'intent') || 'RELATED');
+        // A handle, url:handle (one dynamic product page), or empty inside a product: that product.
+        let { key } = resolveProductKey(this.root, window.location, 'recommendations');
+        const scope = this.root.closest(sel('product'));
+        if (!key && scope) ({ key } = resolveProductKey(scope));
+        if (!key) throw new TetherError('No product for recommendations', { code: 'NOT_FOUND' });
+        const recs = await getRecommendations(key, get(this.root, 'intent') || 'RELATED');
         if (stale()) return;
         const limit = parseInt(get(this.root, 'limit') || '', 10);
         this.products = limit ? recs.slice(0, limit) : recs;
@@ -66,7 +70,8 @@ export class ListScope {
       if (stale()) return;
       // Keep what's already rendered on a failed "load more"; otherwise show the error state.
       if (!more) setScopeStatus(this.root, isNotFound(err) ? 'not-found' : 'error', err);
-      reportError(err, 'list load failed');
+      // A missing product for recommendations is a page detail, not an error to report.
+      if (!(isNotFound(err) && has(this.root, 'recommendations'))) reportError(err, 'list load failed');
       emit('error', { error: err, context: 'list' }, this.root);
     }
   }
@@ -95,10 +100,10 @@ export class ListScope {
     const empty = this.products.length === 0;
     this.$(sel('show')).forEach((el) => {
       const k = get(el, 'show');
-      if (k === 'list-empty') el.style.display = empty ? '' : 'none';
-      if (k === 'list-filled') el.style.display = empty ? 'none' : '';
+      if (k === 'list-empty') show(el, empty);
+      if (k === 'list-filled') show(el, !empty);
     });
-    this.$(sel('load-more')).forEach((el) => { el.style.display = this.pageInfo?.hasNextPage ? '' : 'none'; });
+    this.$(sel('load-more')).forEach((el) => show(el, Boolean(this.pageInfo?.hasNextPage)));
     notifyLayoutChanged('list');
   }
 }

package/src/config.js

@@ -36,6 +36,9 @@ export const DEFAULTS = {
 
   // Subscriptions
   defaultPurchase: 'one-time', // 'one-time' | 'subscription'
+  variantUrl: false, // true: ?variant= follows the visitor's choice on the main product (shareable links)
+  maxAge: 60, // seconds a Shopify answer may be cached (0 = Shopify's own caching, can be hours)
+  lowStock: 5, // tether-show="low-stock" at this many or fewer (needs inventory access)
 
   // Mounting
   autoMount: true,            // mount document on DOMContentLoaded

package/src/diagnose.js

@@ -63,7 +63,7 @@ export function checkMarkup(root = document) {
   });
 
   const known = new Set([
-    'in-stock', 'out-of-stock', 'backorder', 'low-stock', 'on-sale', 'not-on-sale', 'has-variants', 'single-variant',
+    'in-stock', 'out-of-stock', 'backorder', 'low-stock', 'plenty-in-stock', 'on-sale', 'not-on-sale', 'has-variants', 'single-variant',
     'subscription-available', 'subscription-unavailable', 'subscription-only', 'one-time-available',
     'subscription-selected', 'one-time-selected', 'has-savings', 'loading', 'ready', 'error', 'not-found',
     'cart-empty', 'cart-filled', 'cart-has-subscription', 'cart-no-subscription', 'cart-has-discount', 'cart-error', 'cart-warning',
@@ -107,7 +107,8 @@ export async function diagnose({ root = document, silent = false, version, now =
       autoMount: cfg.autoMount, observe: cfg.observe, onError: typeof cfg.onError === 'function',
     },
     apiVersion: apiVersionStatus(cfg.apiVersion, now),
-    market: cfg.markets?.detect ? detectMarket(cfg.markets) : null,
+    // The market in use (a visitor's choice included), plus what detection would pick.
+    market: { country: cfg.country || null, language: cfg.language || null, locale: cfg.locale || null, detected: cfg.markets?.detect ? detectMarket(cfg.markets) : null },
     reachable: false,
     shop: null,
     latencyMs: null,
@@ -141,6 +142,14 @@ export async function diagnose({ root = document, silent = false, version, now =
           const plans = allPlans(p);
           report.products.push({ key: keys[i], handle: p.handle, title: p.title, plans: plans.length, requiresSellingPlan: p.requiresSellingPlan });
           plans.forEach((pl) => report.sellingPlans.push({ product: p.handle, group: pl.group?.name, plan: pl.name, id: pl.id }));
+          // Options a visitor can't choose on this page (they get the first available variant's value).
+          qsa(root, sel('product')).filter((el) => resolveProductKey(el).key === keys[i] && el.querySelector(sel('add-to-cart'))).forEach((el) => {
+            const shown = new Set(qsa(el, `${sel('option-list')},select${sel('option')}`).map((x) => get(x, 'option-list') || get(x, 'option')));
+            if (!shown.size && qsa(el, `select${sel('variant-select')}`).length) return;
+            (p.options || []).filter((o) => o.optionValues.length > 1 && !shown.has(o.name)).forEach((o) => {
+              report.problems.push({ level: 'warn', message: `Product "${p.handle}": option "${o.name}" (${o.optionValues.length} values) has no tether-option-list, so visitors can't choose it.` });
+            });
+          });
         } else {
           report.products.push({ key: keys[i], error: r.reason?.message });
           report.problems.push({ level: 'error', message: `Product "${keys[i]}": ${r.reason?.message}. Is it published to the Headless channel?` });

package/src/dom.js

@@ -33,6 +33,12 @@ export function emit(name, detail, target = document) {
   target.dispatchEvent(new CustomEvent(`${cfg.prefix}:${name}`, { detail, bubbles: true }));
 }
 
+/** 30 -> "30%" (en, nl) or "30 %" (de, fr), in the configured locale. */
+export function formatPercent(n, locale = cfg.locale) {
+  if (!n) return '';
+  try { return new Intl.NumberFormat(locale || undefined, { style: 'percent', maximumFractionDigits: 0 }).format(n / 100); } catch { return `${n}%`; }
+}
+
 export function formatMoney(money) {
   if (!money) return '';
   if (typeof cfg.formatMoney === 'function') return cfg.formatMoney(money, cfg.locale);
@@ -168,7 +174,7 @@ function template(container) {
 /** Rebuilds the list on every render. Fine for images, tags, options. */
 export function repeat(container, items, render) {
   const tpl = template(container);
-  if (!tpl) { warn('repeater without a template child', container); return; }
+  if (!tpl) { if (items.length) warn('repeater without a template child', container); return; }
   container.innerHTML = '';
   items.forEach((item, i) => {
     const node = tpl.cloneNode(true);

package/src/extras.js

@@ -0,0 +1,63 @@
+/**
+ * Optional part with features that load when first needed: bundles (on the first "add set"
+ * click), tab sync (on the first change in another tab) and shareable variant links (on the
+ * first variant change, with variantUrl or tether-variant-url).
+ */
+import { cfg, warn, reportError } from './config.js';
+import { sel, get, has, qsa, emit, parseJSONAttr, toAttributes } from './dom.js';
+import { scopes } from './product.js';
+import { Cart } from './cart.js';
+
+/**
+ * [tether-group] + [tether-group-add]: adds every product scope inside the group in one request.
+ * Bundles, build-a-box, "complete the set". Lines get attribute _group (and tether-line-attributes).
+ */
+export async function addGroup(btn) {
+  const group = btn.closest(sel('group'));
+  if (!group) return null;
+  const name = get(group, 'group');
+  const extra = toAttributes(parseJSONAttr(group, 'line-attributes'));
+  const groupAttrs = name ? [{ key: '_group', value: name }, ...extra] : extra;
+  const lines = qsa(group, sel('product'))
+    .map((el) => scopes.get(el))
+    .filter((s) => s && s.variant?.availableForSale && s.quantity > 0)
+    .map((s) => {
+      const l = s.getLine();
+      l.attributes = [...(l.attributes || []), ...groupAttrs];
+      return l;
+    });
+  if (!lines.length) { warn('group-add: nothing selected'); return null; }
+  try {
+    const cart = await Cart.add(lines);
+    emit('group-added', { group: name, lines }, group);
+    return cart;
+  } catch (err) { reportError(err, 'group add'); return null; }
+}
+
+/** Another tab changed the cart (reload it here) or the visitor's market (follow it). */
+export function onStorage(e) {
+  if (e.key === cfg.storageKey || e.key === `${cfg.storageKey}:seen`) Cart.init();
+  else if (e.key === `${cfg.prefix}:market:${cfg.domain}` && e.newValue) {
+    try {
+      const m = JSON.parse(e.newValue);
+      if (m?.country) window.Tether?.setCountry(m.country, { language: m.language ?? null, locale: m.locale, remember: false }).catch(() => {});
+    } catch { /* ignore */ }
+  }
+}
+
+const urlKeys = new WeakMap(); // scope root -> last variant|plan, so the first render doesn't write
+
+/** ?variant= (and selling_plan=) follow the visitor's choice. */
+export function writeVariantUrl(root, { variant, sellingPlanId }) {
+  const key = `${variant.id}|${sellingPlanId || ''}`;
+  const before = urlKeys.get(root);
+  urlKeys.set(root, key);
+  if (!before || before === key) return;
+  if (!has(root, 'variant-url') && !(cfg.variantUrl && document.querySelector(sel('product')) === root)) return;
+  try {
+    const u = new URL(window.location.href);
+    u.searchParams.set('variant', variant.id.split('/').pop());
+    if (sellingPlanId) u.searchParams.set('selling_plan', sellingPlanId.split('/').pop()); else u.searchParams.delete('selling_plan');
+    window.history.replaceState(window.history.state, '', u);
+  } catch { /* ignore */ }
+}