@occluze/tether 0.3.6 → 0.5.0

package/package.json

@@ -1,32 +1,59 @@
 {
   "name": "@occluze/tether",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "description": "Free, open-source alternative to Smootify and Storesynk (Shopyflow): Shopify products, cart and subscriptions in Webflow with HTML attributes. Optional Shopify to Webflow CMS sync.",
   "type": "module",
-  "main": "dist/tether.esm.js",
-  "module": "dist/tether.esm.js",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
   "exports": {
-    ".": "./dist/tether.esm.js",
-    "./presets/barba": "./dist/presets/barba.esm.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./server": {
+      "types": "./types/server.d.ts",
+      "default": "./dist/esm/server.js"
+    },
+    "./astro": {
+      "types": "./types/astro.d.ts",
+      "default": "./dist/esm/astro.js"
+    },
+    "./presets/barba": {
+      "types": "./types/barba.d.ts",
+      "default": "./dist/presets/barba.esm.js"
+    },
+    "./dist/*": "./dist/*"
   },
   "files": [
     "dist",
     "src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "types/index.d.ts",
+    "types/barba.d.ts",
+    "types/server.d.ts",
+    "types/astro.d.ts"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "dev": "node scripts/build.mjs --watch",
-    "test": "node --test test/*.test.js server/test/*.test.js",
-    "smoke": "node scripts/smoke.mjs"
+    "test": "node --test test/*.test.js server/test/*.test.js && npm run test:types",
+    "smoke": "node scripts/smoke.mjs",
+    "pretest": "node scripts/build.mjs",
+    "presmoke": "node scripts/build.mjs",
+    "test:types": "tsc -p types/tsconfig.json",
+    "release": "node scripts/release.mjs"
   },
   "devDependencies": {
     "esbuild": "^0.25.0",
-    "jsdom": "^26.0.0"
+    "jsdom": "^26.0.0",
+    "typescript": "^5.9.3"
   },
   "license": "MIT",
-  "author": "Ravi Klaassens",
+  "author": {
+    "name": "Ravi Klaassens",
+    "url": "https://occluze.com"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ravi-klaassens/tether.git"
@@ -36,24 +63,38 @@
     "url": "https://github.com/ravi-klaassens/tether/issues"
   },
   "keywords": [
+    "astro",
+    "astro-integration",
     "cart",
     "ecommerce",
     "headless",
+    "headless-commerce",
     "headless-shopify",
     "selling-plans",
     "shopify",
     "shopify-subscriptions",
     "shopyflow-alternative",
     "smootify-alternative",
+    "ssr",
     "storefront-api",
     "storesynk-alternative",
     "subscriptions",
     "webflow",
     "webflow-cms",
     "webflow-ecommerce",
-    "webflow-shopify"
+    "webflow-shopify",
+    "withastro"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "types": "types/index.d.ts",
+  "peerDependencies": {
+    "astro": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": true
+    }
   }
 }

package/src/astro.js

@@ -0,0 +1,73 @@
+/**
+ * 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';",
+          `Tether.init({ ...${JSON.stringify({ autoMount: false, ...config })}, ...(window.TETHER_CONFIG || {}) }).then(() => Tether.mount(document));`,
+        ].join('\n'));
+      },
+    },
+  };
+}

package/src/cart.js

@@ -29,11 +29,28 @@ 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 } }
 }
 ${cartFragment()}`;
 }
 
+const FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+let returnFocus = null;
+
+/** Focusable elements inside an open drawer, in order (visible ones only). */
+export const focusables = (d) => qsa(d, FOCUSABLE).filter((el) => el.offsetParent !== null || el === document.activeElement);
+
+/** aria-expanded on the open buttons; dialog semantics on drawers (unless the markup has its own). */
+function ariaState(open) {
+  qsa(document, sel('cart-open')).forEach((b) => b.setAttribute('aria-expanded', String(open)));
+  qsa(document, sel('cart-drawer')).forEach((d) => {
+    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');
+  });
+}
+
 const isMissingCart = (err) => /does not exist|not found|invalid id/i.test(err?.message || '');
 
 export const Cart = {
@@ -52,6 +69,17 @@ export const Cart = {
   get count() { return this.state?.totalQuantity || 0; },
 
   lastError: null,
+  /** 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);
+    this.warnings = p.warnings || [];
+    if (this.warnings.length) emit('cart-warning', { warnings: this.warnings });
+    return p.cart;
+  },
 
   _queue(fn) {
     const run = this._chain.then(fn, fn).then((value) => {
@@ -78,7 +106,7 @@ 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; }
     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;
@@ -89,7 +117,9 @@ 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;
   },
 
@@ -99,7 +129,7 @@ export const Cart = {
       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. */
@@ -108,7 +138,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');
@@ -203,7 +233,8 @@ export const Cart = {
   },
 
   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. */
@@ -226,7 +257,7 @@ 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 */ } }
 
@@ -255,6 +286,16 @@ export const Cart = {
     if (this.isOpen()) return;
     const ds = this.drawers().filter((d) => get(d, 'cart-drawer') !== 'manual');
     ds.forEach((d) => { 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).
+      returnFocus = document.activeElement;
+      setTimeout(() => {
+        const target = focusables(ds[0])[0] || ds[0];
+        if (target === ds[0] && !ds[0].hasAttribute('tabindex')) ds[0].tabIndex = -1;
+        target.focus?.({ preventScroll: true });
+      }, 60);
+    }
     if (typeof cfg.onCartOpen === 'function') cfg.onCartOpen(ds);
     emit('cart-toggled', { open: true });
   },
@@ -262,13 +303,29 @@ export const Cart = {
   close() {
     if (!this.isOpen()) return;
     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'); });
+    ariaState(false);
+    if (hadFocus && returnFocus?.isConnected) returnFocus.focus({ preventScroll: true });
+    returnFocus = null;
     if (typeof cfg.onCartClose === 'function') cfg.onCartClose(ds);
     emit('cart-toggled', { open: false });
   },
 
   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() {
@@ -276,6 +333,7 @@ export const Cart = {
     const count = cart ? cart.totalQuantity : 0;
     const money = (k) => (cart ? formatMoney(cart.cost?.[k]) : '');
 
+    ariaState(this.isOpen());
     qsa(document, sel('cart-count')).forEach((el) => setTextTracked(el, count));
     qsa(document, sel('cart-subtotal')).forEach((el) => setTextTracked(el, money('subtotalAmount')));
     qsa(document, sel('cart-total')).forEach((el) => setTextTracked(el, money('totalAmount')));
@@ -289,11 +347,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 || '';
@@ -356,7 +420,15 @@ 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;

package/src/client.js

@@ -15,8 +15,8 @@ export class TetherError extends Error {
   }
 }
 
-export function endpoint() {
-  return `https://${cfg.domain}/api/${cfg.apiVersion}/graphql.json`;
+export function endpoint(conf = cfg) {
+  return `https://${conf.domain}/api/${conf.apiVersion}/graphql.json`;
 }
 
 /**
@@ -31,42 +31,46 @@ export function withContext(query, ctx = cfg) {
   if (ctx.language) args.push(`language: ${String(ctx.language).toUpperCase().replace('-', '_')}`);
   if (!args.length || /@inContext/.test(query)) return query;
 
-  return query.replace(
-    /^(\s*(?:query|mutation)\s+\w+\s*(?:\([^)]*\))?)/,
-    `$1 @inContext(${args.join(', ')})`,
-  );
+  const tag = `@inContext(${args.join(', ')})`;
+  // Named (query Name($x: T)), anonymous (query { … }) and shorthand ({ … }) queries.
+  if (/^\s*\{/.test(query)) return `query ${tag} ${query.trimStart()}`;
+  return query.replace(/^(\s*(?:query|mutation)(?:\s+\w+)?\s*(?:\([^)]*\))?)/, `$1 ${tag}`);
 }
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-export async function gql(query, variables = {}, { context = true } = {}) {
-  if (!cfg.domain || !cfg.token) {
+/**
+ * One Storefront API request with retries, for any config object (the browser's shared config,
+ * or the server module's own). gql() below is the browser version.
+ */
+export async function request(conf, query, variables = {}, { context = true } = {}) {
+  if (!conf.domain || !conf.token) {
     throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
   }
 
-  const body = JSON.stringify({ query: context ? withContext(query) : query, variables });
+  const body = JSON.stringify({ query: context ? withContext(query, conf) : query, variables });
   let attempt = 0;
 
   for (;;) {
     let res;
     try {
-      res = await fetch(endpoint(), {
+      res = await (conf.fetch || fetch)(endpoint(conf), {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          'X-Shopify-Storefront-Access-Token': cfg.token,
+          'X-Shopify-Storefront-Access-Token': conf.token,
         },
         body,
       });
     } catch (err) {
-      if (attempt++ < cfg.retries) { await sleep(300 * 2 ** attempt); continue; }
+      if (attempt++ < conf.retries) { await sleep(300 * 2 ** attempt); continue; }
       throw new TetherError(`Network error: ${err.message}`, { code: 'NETWORK' });
     }
 
     if (res.status === 430) throw new TetherError('Shopify security rejection (430)', { status: 430 });
 
     const retryable = res.status === 429 || res.status >= 500;
-    if (retryable && attempt++ < cfg.retries) {
+    if (retryable && attempt++ < conf.retries) {
       log('retry', res.status, attempt);
       await sleep(300 * 2 ** attempt);
       continue;
@@ -82,10 +86,14 @@ export async function gql(query, variables = {}, { context = true } = {}) {
       const inventoryDenied = json.errors.some((e) => /quantityAvailable/.test(e.message || ''));
       if (inventoryDenied && /\bquantityAvailable\b/.test(body)) {
         log('no inventory permission, retrying without quantityAvailable');
-        return gql(query.replace(/\bquantityAvailable\b/g, ''), variables, { context });
+        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 });
       }
       const throttled = json.errors.some((e) => e.extensions?.code === 'THROTTLED');
-      if (throttled && attempt++ < cfg.retries) { await sleep(500 * 2 ** attempt); continue; }
+      if (throttled && attempt++ < conf.retries) { await sleep(500 * 2 ** attempt); continue; }
       throw new TetherError(json.errors.map((e) => e.message).join(' | '), {
         status: res.status, errors: json.errors,
       });
@@ -96,6 +104,8 @@ export async function gql(query, variables = {}, { context = true } = {}) {
   }
 }
 
+export const gql = (query, variables, opts) => request(cfg, query, variables, opts);
+
 /** Throws on mutation userErrors, returns the payload otherwise. */
 export function unwrap(payload, name) {
   if (!payload) throw new TetherError(`${name}: empty response`);

package/src/config.js

@@ -25,11 +25,13 @@ export const DEFAULTS = {
   sellingPlansFirst: 25,
   collectionFirst: 24,
   retries: 2,
+  revalidate: true,           // products from the server (tether/server hydrate()): refresh once in the background
 
   // Cart
   storageKey: null,           // defaults to `tether:cart:<domain>`
   cartDrawerOpenClass: 'is-open',
   openCartOnAdd: true,
+  cartFocus: true,            // move focus into the open cart, keep Tab inside it, restore it on close
   checkoutTarget: '_self',    // '_self' or '_blank'
 
   // Subscriptions
@@ -38,6 +40,8 @@ export const DEFAULTS = {
   // Mounting
   autoMount: true,            // mount document on DOMContentLoaded
   observe: false,             // auto-mount nodes added later (CMS load-more, filters)
+  astro: true,                // mount on Astro View Transitions (astro:page-load); false if you do it yourself
+  partsUrl: null,             // folder of tether.markets/diagnose(.min).js for the <script> build (default: next to it)
 
   // Formatting
   formatMoney: null,          // (money, locale) => string

package/src/diagnose.js

@@ -66,7 +66,7 @@ export function checkMarkup(root = document) {
     'in-stock', 'out-of-stock', 'backorder', 'low-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-empty', 'cart-filled', 'cart-has-subscription', 'cart-no-subscription', 'cart-has-discount', 'cart-error', 'cart-warning',
     'list-empty', 'list-filled',
   ]);
   qsa(root, sel('show')).forEach((el) => {

package/src/dom.js

@@ -53,24 +53,37 @@ export function formatDate(iso) {
 }
 
 /** Shopify CDN resize via max-width / max-height / crop attributes on the element. */
-export function cdnUrl(url, el) {
-  if (!url || !el) return url;
-  const w = el.getAttribute('max-width');
-  const h = el.getAttribute('max-height');
-  const crop = el.getAttribute('crop');
-  if (!w && !h) return url;
+/**
+ * Shopify CDN image at a size: imageUrl(url, { width: 800 }). Use the same width as the element's
+ * max-width attribute, so the browser script keeps the image instead of loading it again.
+ */
+export function imageUrl(url, { width, height, crop } = {}) {
+  if (!url) return url;
   try {
     const u = new URL(url);
-    if (w) u.searchParams.set('width', w);
-    if (h) u.searchParams.set('height', h);
+    if (width) u.searchParams.set('width', String(width));
+    if (height) u.searchParams.set('height', String(height));
     if (crop) u.searchParams.set('crop', crop);
     return u.toString();
   } catch { return url; }
 }
 
+export function cdnUrl(url, el) {
+  if (!url || !el) return url;
+  const g = (k) => el.getAttribute(k);
+  return imageUrl(url, { width: g('max-width'), height: g('max-height'), crop: g('max-width') || g('max-height') ? g('crop') : null });
+}
+
+/** Same image, whatever size parameters: the server-rendered one is kept (no second download). */
+export const sameImage = (a, b) => Boolean(a && b) && a.split('?')[0] === b.split('?')[0];
+
 export function setImage(el, url, alt) {
   if (!url) return;
   const src = cdnUrl(url, el);
+  if (el.tagName === 'IMG' && sameImage(el.getAttribute('src'), src)) {
+    if (alt != null && !el.getAttribute('alt')) el.setAttribute('alt', alt);
+    return;
+  }
   if (el.tagName === 'IMG') {
     el.removeAttribute('srcset');
     el.removeAttribute('sizes');
@@ -104,14 +117,24 @@ export function setTextTracked(el, v) {
 export function show(el, visible) {
   const k = 'tetherPrevDisplay';
   if (visible) {
+    if (el.dataset.tetherShown !== undefined) return; // already visible, nothing to check
+    el.dataset.tetherShown = '';
+    el.removeAttribute('hidden');
     if (el.dataset[k] !== undefined) {
       el.style.display = el.dataset[k];
       delete el.dataset[k];
     } else if (el.style.display === 'none') {
       el.style.display = '';
     }
+    // Hidden before the script ran (a class, an inline display:none, a hidden attribute): show it
+    // as block or the value of tether-display.
+    if (typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
+      el.style.display = el.getAttribute(`${cfg.prefix}-display`) || 'block';
+    }
   } else {
-    if (el.dataset[k] === undefined) el.dataset[k] = el.style.display || '';
+    delete el.dataset.tetherShown;
+    // Remember a real display value to restore, never 'none'.
+    if (el.dataset[k] === undefined && el.style.display !== 'none') el.dataset[k] = el.style.display || '';
     el.style.display = 'none';
   }
 }

package/src/fragments.js

@@ -7,8 +7,8 @@ import { cfg } from './config.js';
 const MONEY = 'amount currencyCode';
 const IMAGE = 'url altText width height';
 
-export function metafieldIdentifiers() {
-  return (cfg.metafields || []).map((m) => {
+export function metafieldIdentifiers(o = cfg) {
+  return (o.metafields || []).map((m) => {
     if (typeof m === 'string') {
       const i = m.indexOf('.');
       return { namespace: m.slice(0, i), key: m.slice(i + 1) };
@@ -17,8 +17,8 @@ export function metafieldIdentifiers() {
   }).filter((m) => m.namespace && m.key);
 }
 
-function metafieldsField() {
-  const ids = metafieldIdentifiers();
+function metafieldsField(o = cfg) {
+  const ids = metafieldIdentifiers(o);
   if (!ids.length) return '';
   const list = ids
     .map((m) => `{namespace: ${JSON.stringify(m.namespace)}, key: ${JSON.stringify(m.key)}}`)
@@ -53,26 +53,27 @@ export const ALLOCATION_FIELDS = `
     unitPrice { ${MONEY} }
   }`;
 
-export function productFragment() {
+/** The product fields Tether renders. `o` = config (counts, metafields); the server module passes its own. */
+export function productFragment(o = cfg) {
   return `
 fragment TetherProduct on Product {
   id handle title description descriptionHtml productType vendor tags
   availableForSale publishedAt onlineStoreUrl requiresSellingPlan
   seo { title description }
   featuredImage { ${IMAGE} }
-  images(first: ${cfg.imagesFirst}) { nodes { ${IMAGE} } }
+  images(first: ${o.imagesFirst}) { nodes { ${IMAGE} } }
   options { name optionValues { name swatch { color image { previewImage { ${IMAGE} } } } } }
   priceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
   compareAtPriceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
-  ${metafieldsField()}
-  sellingPlanGroups(first: ${cfg.sellingPlanGroupsFirst}) {
+  ${metafieldsField(o)}
+  sellingPlanGroups(first: ${o.sellingPlanGroupsFirst}) {
     nodes {
       name appName
       options { name values }
-      sellingPlans(first: ${cfg.sellingPlansFirst}) { nodes { ${SELLING_PLAN_FIELDS} } }
+      sellingPlans(first: ${o.sellingPlansFirst}) { nodes { ${SELLING_PLAN_FIELDS} } }
     }
   }
-  variants(first: ${cfg.variantsFirst}) {
+  variants(first: ${o.variantsFirst}) {
     nodes {
       id title availableForSale currentlyNotInStock quantityAvailable sku barcode
       selectedOptions { name value }
@@ -80,7 +81,7 @@ fragment TetherProduct on Product {
       price { ${MONEY} }
       compareAtPrice { ${MONEY} }
       unitPrice { ${MONEY} }
-      sellingPlanAllocations(first: ${cfg.sellingPlansFirst}) { nodes { ${ALLOCATION_FIELDS} } }
+      sellingPlanAllocations(first: ${o.sellingPlansFirst}) { nodes { ${ALLOCATION_FIELDS} } }
     }
   }
 }`;