@occluze/tether 0.4.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

@@ -0,0 +1,76 @@
+/**
+ * Astro integration: Tether on every page, configured from .env.
+ *
+ *   // astro.config.mjs
+ *   import { defineConfig } from 'astro/config';
+ *   import tether from '@occluze/tether/astro';
+ *   export default defineConfig({ integrations: [tether({ country: 'NL', locale: 'nl-NL' })] });
+ *
+ *   // .env
+ *   PUBLIC_SHOPIFY_DOMAIN=your-store.myshopify.com
+ *   PUBLIC_SHOPIFY_STOREFRONT_TOKEN=your-public-storefront-token
+ *
+ * Options are Tether's config (domain and token override .env). Functions (onError, formatMoney,
+ * hooks) can't be passed here: set them in window.TETHER_CONFIG in your layout, it is merged in.
+ * View Transitions (<ClientRouter />) work without extra code.
+ */
+
+const ENV_KEYS = {
+  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
+  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
+};
+
+/** .env files the way Vite reads them (later files win), plus process.env on top. */
+async function readEnv(command, root) {
+  const mode = command === 'dev' ? 'development' : 'production';
+  const out = {};
+  try {
+    const { readFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    for (const name of ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]) {
+      let text;
+      try { text = await readFile(join(root, name), 'utf8'); } catch { continue; }
+      for (const line of text.split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*?)\s*$/.exec(line);
+        if (!m || line.trim().startsWith('#')) continue;
+        let v = m[2];
+        const q = /^(["'])(.*?)\1/.exec(v); // "quoted" (a # comment may follow)
+        v = q ? q[2] : v.replace(/\s+#.*$/, '');
+        out[m[1]] = v;
+      }
+    }
+  } catch { /* not in Node: nothing to read */ }
+  return { ...out, ...process.env };
+}
+
+export default function tether(options = {}) {
+  const { inject = true, ...config } = options;
+  return {
+    name: '@occluze/tether',
+    hooks: {
+      'astro:config:setup': async ({ injectScript, command, config: astroConfig, logger }) => {
+        const root = astroConfig?.root ? decodeURIComponent(new URL(astroConfig.root).pathname) : process.cwd();
+        const env = await readEnv(command, root);
+        for (const [key, names] of Object.entries(ENV_KEYS)) {
+          if (!config[key]) config[key] = names.map((n) => env[n]).find(Boolean);
+        }
+        const bad = Object.entries(config).filter(([, v]) => typeof v === 'function').map(([k]) => k);
+        bad.forEach((k) => delete config[k]);
+        if (bad.length) logger.warn(`${bad.join(', ')}: functions can't be passed here. Set them in window.TETHER_CONFIG in your layout.`);
+        if (!config.domain || !config.token) {
+          logger.warn('No Shopify store configured: set PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN in .env (the public Storefront API token).');
+        }
+        if (!inject) return;
+        // Before any module runs: window.TETHER_CONFIG in the layout doesn't auto-start a second init.
+        injectScript('head-inline', 'window.TETHER_INTEGRATION="astro";');
+        injectScript('page', [
+          "import Tether from '@occluze/tether';",
+          // 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 } }
+  ${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,23 @@ 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. */
+  loaded: false,
+
+  _take(payload, name) {
+    const p = unwrap(payload, name);
+    // 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;
+  },
 
   _queue(fn) {
     const run = this._chain.then(fn, fn).then((value) => {
@@ -88,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;
@@ -95,7 +115,14 @@ export const Cart = {
 
   async init() {
     const id = this.id();
-    if (!id) { this.state = null; this.render(); return null; }
+    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;
@@ -106,17 +133,22 @@ export const Cart = {
       if (isMissingCart(err)) this._setId(null);
       this.state = null;
     }
+    this.loaded = true;
     this.render();
+    emit('cart-updated', { cart: this.state, reason: 'load' }); // islands (cart.subscribe) hear the loaded cart
     return this.state;
   },
 
   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 } },
     );
-    return unwrap(data.cartCreate, 'cartCreate').cart;
+    return this._take(data.cartCreate, 'cartCreate');
   },
 
   /** Runs a cart mutation; creates a fresh cart if ours expired. */
@@ -125,7 +157,7 @@ export const Cart = {
     if (!cartId) return createInput ? this._create(createInput) : null;
     try {
       const data = await gql(mutation(name, `$cartId: ID!, ${args}`, `cartId: $cartId, ${inner}`), { ...variables, cartId });
-      return unwrap(data[name], name).cart;
+      return this._take(data[name], name);
     } catch (err) {
       if (createInput && isMissingCart(err)) {
         log('cart expired, creating a new one');
@@ -173,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(
@@ -214,13 +266,22 @@ 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) {
-    return this.setDiscountCodes((this.state?.discountCodes || []).map((d) => d.code).filter((c) => c !== code));
+    const k = String(code).toLowerCase();
+    return this.setDiscountCodes((this.state?.discountCodes || []).map((d) => d.code).filter((c) => c.toLowerCase() !== k));
   },
 
   /** { countryCode, email, phone } — changes currency/prices for that market. */
@@ -243,13 +304,14 @@ export const Cart = {
    */
   async checkout(target = cfg.checkoutTarget) {
     const id = this.id();
-    if (!id) return null;
+    if (!id || (this.state && !this.count)) return null; // nothing to check out
     const tab = target === '_blank' ? window.open('', '_blank') : null;
     if (tab) { try { tab.opener = null; } catch { /* ignore */ } }
 
     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;
@@ -266,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).
@@ -288,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;
@@ -300,6 +369,18 @@ export const Cart = {
 
   toggle() { if (this.isOpen()) this.close(); else this.open(); },
 
+  /**
+   * For framework islands (React, Svelte, Vue): fn(cart, { open }) now and on every change.
+   * Returns a function that stops listening.
+   */
+  subscribe(fn) {
+    const call = () => fn(this.state, { open: this.isOpen(), count: this.count, loaded: this.loaded, warnings: this.warnings });
+    const h = () => call();
+    ['cart-updated', 'cart-toggled'].forEach((e) => document.addEventListener(`${cfg.prefix}:${e}`, h));
+    call();
+    return () => ['cart-updated', 'cart-toggled'].forEach((e) => document.removeEventListener(`${cfg.prefix}:${e}`, h));
+  },
+
   // -------------------------------------------------------------- render
 
   render() {
@@ -321,11 +402,17 @@ export const Cart = {
       'cart-no-subscription': !hasSub,
       'cart-has-discount': (cart?.discountCodes || []).some((d) => d.applicable),
       'cart-error': Boolean(this.lastError),
+      'cart-warning': this.warnings.length > 0,
     };
+    qsa(document, sel('cart-warning')).forEach((el) => setTextTracked(el, [...new Set(this.warnings.map((w) => w.message))].join(' ')));
     qsa(document, sel('show')).forEach((el) => {
       const k = get(el, 'show');
       if (k in conds && !el.closest(sel('product'))) show(el, conds[k]);
     });
+    qsa(document, sel('checkout')).forEach((el) => {
+      el.classList.toggle('is-disabled', !count);
+      el.setAttribute('aria-disabled', String(!count));
+    });
 
     qsa(document, `textarea${sel('cart-note')},input${sel('cart-note')}`).forEach((el) => {
       if (document.activeElement !== el) el.value = cart?.note || '';
@@ -365,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 || [])
@@ -388,17 +475,33 @@ function renderLine(node, line) {
   qsa(node, sel('line')).forEach((el) => {
     const key = get(el, 'line');
     if (key === 'image') return setImage(el, m.image?.url || m.product?.featuredImage?.url, m.product?.title);
-    if (key === 'url') return el.setAttribute('href', productUrl(m.product?.handle, m.product?.id));
+    if (key === 'url') {
+      const u = productUrl(m.product?.handle, m.product?.id);
+      const q = new URLSearchParams();
+      if (m.id) q.set('variant', String(m.id).split('/').pop());
+      const plan = line.sellingPlanAllocation?.sellingPlan?.id;
+      if (plan) q.set('selling_plan', plan.split('/').pop());
+      const qs = q.toString();
+      return el.setAttribute('href', qs ? `${u}${u.includes('?') ? '&' : '?'}${qs}` : u);
+    }
     const v = lineValue(line, key);
     if (v !== undefined) setTextTracked(el, v);
     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');