@occluze/tether 0.4.0 → 0.5.0

package/src/initial.js

@@ -0,0 +1,66 @@
+/**
+ * What the browser script will show first for a product, so a server can render the same
+ * (no flash when Tether takes over): the selected variant, price, purchase mode and conditions.
+ * Same rules as src/product.js: first available variant (or the one in ?variant=), subscription
+ * when the product requires a plan or defaultPurchase is 'subscription', low stock at 5 or fewer.
+ */
+import { GID, allPlans, allocationFor, findPlan, planPrice, planSavings } from './selling-plans.js';
+
+export function initialState(product, { variant, sellingPlan, defaultPurchase = 'one-time' } = {}) {
+  const vs = product?.variants?.nodes || [];
+  const gid = variant ? GID.variant(variant) : null;
+  const v = (gid && vs.find((x) => x.id === gid)) || vs.find((x) => x.availableForSale) || vs[0] || null;
+  if (!v) return null;
+  const selected = Object.fromEntries((v.selectedOptions || []).map((o) => [o.name, o.value]));
+
+  const plans = allPlans(product);
+  const fromUrl = findPlan(product, sellingPlan);
+  let plan = plans.length ? (fromUrl || plans[0]) : null;
+  if (plan && !allocationFor(v, plan.id)) plan = plans.find((p) => allocationFor(v, p.id)) || plan;
+  const wantsSub = product.requiresSellingPlan || fromUrl || defaultPurchase === 'subscription';
+  const subscriptionAvailable = plans.some((p) => allocationFor(v, p.id));
+  const purchase = plans.length && wantsSub ? 'subscription' : 'one-time';
+  const sub = purchase === 'subscription' && subscriptionAvailable;
+
+  const price = sub ? planPrice(v, plan.id) : v.price;
+  const compareAt = sub ? (allocationFor(v, plan.id)?.priceAdjustments?.[0]?.compareAtPrice || v.compareAtPrice) : v.compareAtPrice;
+  const onSale = Boolean(compareAt && parseFloat(compareAt.amount) > parseFloat(price.amount));
+  const q = v.quantityAvailable;
+
+  return {
+    variant: v,
+    selected,
+    purchase,
+    plan: sub ? plan : null,
+    /** The plan list (tether-plan-list="all"): selected one gets is-selected, unavailable ones is-unavailable. */
+    plans: plans.map((p) => ({
+      id: p.id, name: p.name, price: planPrice(v, p.id), savings: planSavings(v, p.id).percentage,
+      selected: sub && p.id === plan.id, available: Boolean(allocationFor(v, p.id)),
+    })),
+    /** Savings of the selected plan in % (tether-bind="subscription-savings"), 0 without one. */
+    savings: plan ? planSavings(v, plan.id).percentage : 0,
+    price,
+    compareAtPrice: onSale ? compareAt : null,
+    available: v.availableForSale,
+    /** The tether-show conditions, e.g. hidden={!state.show['out-of-stock']}. */
+    show: {
+      'in-stock': v.availableForSale,
+      'out-of-stock': !v.availableForSale,
+      backorder: Boolean(v.availableForSale && v.currentlyNotInStock),
+      'on-sale': onSale,
+      'not-on-sale': !onSale,
+      'has-variants': vs.length > 1,
+      'single-variant': vs.length === 1,
+      'low-stock': q != null && q > 0 && q <= 5,
+      'subscription-available': subscriptionAvailable,
+      'subscription-unavailable': !subscriptionAvailable,
+      'subscription-only': Boolean(product.requiresSellingPlan),
+      'one-time-available': !product.requiresSellingPlan,
+      'subscription-selected': sub,
+      'one-time-selected': !sub,
+    },
+    /** Option values with no available variant (given the other selected options): class is-unavailable. */
+    isUnavailable: (name, value) => !vs.some((x) => x.availableForSale && x.selectedOptions.every((o) =>
+      (o.name === name ? o.value === value : selected[o.name] === o.value))),
+  };
+}

package/src/loader.js

@@ -90,7 +90,11 @@ async function flush() {
     handles.forEach((h, i) => { if (data[`h${i}`]) got.set(h, data[`h${i}`]); });
 
     keys.forEach((k) => settle(k, (r) => {
-      if (got.has(k)) { if (gen === generation) primeProduct(got.get(k)); r.resolve(got.get(k)); } else {
+      if (got.has(k)) {
+        const p = got.get(k);
+        if (gen === generation) { primeProduct(p); freshAt.set(p.handle, Date.now()); freshAt.set(p.id, Date.now()); }
+        r.resolve(p);
+      } else {
         if (gen === generation) productCache.delete(k); // don't cache misses: a fix in Shopify works on next load
         r.reject(new TetherError(`Product not found: ${k}`, { code: 'NOT_FOUND' }));
       }
@@ -100,7 +104,44 @@ async function flush() {
   }
 }
 
-export function clearProductCache() { productCache.clear(); generation++; }
+export function clearProductCache() { productCache.clear(); generation++; stale.clear(); freshAt.clear(); }
+
+// ---------------------------------------------------------------------------
+// Hydration: products rendered on the server (tether/server hydrate()) are used at once and
+// refreshed once in the background, so prices and stock are live without a loading state.
+// ---------------------------------------------------------------------------
+
+const stale = new Set(); // keys of products that came from the server and weren't refreshed yet
+const freshAt = new Map(); // key -> when it was last loaded live (this page session)
+const FRESH_MS = 60000;
+
+export function hydrateProducts(products) {
+  (products || []).forEach((p) => {
+    if (!p?.id || !p.handle) return;
+    // Loaded live in the last minute (an earlier page of a View Transition visit): that copy is newer.
+    if (Date.now() - (freshAt.get(p.handle) || 0) < FRESH_MS && productCache.has(p.handle)) return;
+    primeProduct(p);
+    stale.add(p.handle);
+    stale.add(p.id);
+  });
+}
+
+/** True once per server-provided product: the caller refreshes it. */
+export function takeStale(key) {
+  const k = normalizeProductKey(key);
+  if (!stale.has(k)) return false;
+  const p = productCache.get(k);
+  stale.delete(k);
+  // Both keys point to the same product: refresh it once.
+  p?.then?.((x) => { stale.delete(x.handle); stale.delete(x.id); });
+  return true;
+}
+
+/** Fetch these products again (bypassing the cache). */
+export function refreshProducts(keys) {
+  keys.forEach((k) => productCache.delete(normalizeProductKey(k)));
+  return keys.map((k) => getProduct(k));
+}
 
 /**
  * A page of products from a collection (by handle) or from a search query.
@@ -141,11 +182,13 @@ ${fragment}`, { first, after, query: query || undefined, sortKey: sortKey || und
   return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
 }
 
-export async function getRecommendations(productId, intent = 'RELATED') {
-  const data = await gql(`query TetherRecs($id: ID!, $intent: ProductRecommendationIntent) {
-  productRecommendations(productId: $id, intent: $intent) { ...TetherProduct }
+export async function getRecommendations(product, intent = 'RELATED') {
+  const key = normalizeProductKey(typeof product === 'object' ? product?.id : product);
+  const byId = key?.startsWith('gid://');
+  const data = await gql(`query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
 }
-${productFragment()}`, { id: productId, intent });
+${productFragment()}`, byId ? { id: key, intent } : { handle: key, intent });
   const list = data.productRecommendations || [];
   list.forEach(primeProduct);
   return list;

package/src/markets-ui.js

@@ -30,11 +30,14 @@ function renderCountrySelects(root = document) {
       .replace(/\{currency\}/g, c.currency?.isoCode || '').replace(/\{symbol\}/g, c.currency?.symbol || '');
     selects.forEach((s) => {
       const tpl = s.getAttribute(attr('country-label')) || '{name} ({currency})';
+      // tether-countries="NL,DE,BE": only these (in your order); otherwise every country of the store.
+      const only = (s.getAttribute(attr('countries')) || '').toUpperCase().split(/[\s,]+/).filter(Boolean);
+      const list = only.length ? only.map((c) => countries.find((x) => x.isoCode === c)).filter(Boolean) : countries;
       s.innerHTML = '';
-      countries.forEach((c) => s.appendChild(new Option(fill(tpl, c), c.isoCode)));
+      list.forEach((c) => s.appendChild(new Option(fill(tpl, c), c.isoCode)));
       s.value = current;
       if (s.value !== current) s.selectedIndex = -1; // a country the store doesn't sell to
-      s.disabled = countries.length < 2 && !s.hasAttribute(attr('always-enabled'));
+      s.disabled = list.length < 2 && !s.hasAttribute(attr('always-enabled'));
     });
     binds.forEach((el) => {
       const k = get(el, 'country-bind') || 'name';
@@ -49,14 +52,19 @@ function renderCountrySelects(root = document) {
  * buyerIdentity.countryCode is updated, and every product and list on the page re-renders.
  *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
  */
-export async function setCountry(code, { language, remember = true } = {}) {
+export async function setCountry(code, { language, locale, remember = true } = {}) {
   const country = toCountry(code);
   if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
+  // Money format: the option, else a markets.locales entry for this country, else unchanged.
+  const entry = Object.values(cfg.markets?.locales || {}).find((m) => toCountry(m?.country) === country);
+  const own = locale || entry?.locale;
+  const loc = own || cfg.locale;
   const lang = language === undefined ? cfg.language : toLanguage(language);
-  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language;
+  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language || loc !== cfg.locale;
   cfg.country = country;
   cfg.language = lang || undefined;
-  if (remember) rememberMarket({ country, language: lang });
+  cfg.locale = loc;
+  if (remember) rememberMarket({ country, language: lang, locale: own });
   if (!changed) { renderCountrySelects(); return Cart.state; }
 
   clearProductCache();

package/src/markets.js

@@ -112,7 +112,7 @@ export function detectMarket(markets = cfg.markets, env = defaultEnv()) {
 
 export function rememberMarket(market) {
   if (cfg.markets?.remember === false) return;
-  try { localStorage.setItem(storageKey(), JSON.stringify({ country: market.country, language: market.language || undefined })); } catch { /* private mode */ }
+  try { localStorage.setItem(storageKey(), JSON.stringify({ country: market.country, language: market.language || undefined, locale: market.locale || undefined })); } catch { /* private mode */ }
 }
 
 let localizationPromise = null;

package/src/mounting.js

@@ -1,8 +1,8 @@
 /** Product scopes and lists that are mounted, shared by index.js and the optional markets part. */
 import { cfg, log, warn, reportError } from './config.js';
-import { ProductScope, scopes } from './product.js';
+import { ProductScope, scopes, rememberOptionNames } from './product.js';
 import { listSelector } from './collection.js';
-import { getProduct } from './loader.js';
+import { getProduct, takeStale, refreshProducts, hydrateProducts } from './loader.js';
 import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
 import { attr, get, qsa, emit } from './dom.js';
 
@@ -53,6 +53,7 @@ function mountProduct(el) {
       // eslint-disable-next-line no-new
       else new ProductScope(el, p);
       applyPageTitle(el, p);
+      if (cfg.revalidate !== false && takeStale(key)) queueRefresh(key);
     })
     .catch((err) => {
       if (!current()) return;
@@ -87,3 +88,42 @@ export function retryFailed() {
     mountProduct(el);
   });
 }
+
+// Server-rendered products: one batched background request refreshes them all.
+let refreshQueue = new Set();
+function queueRefresh(key) {
+  if (!refreshQueue.size) setTimeout(flushRefresh, 0);
+  refreshQueue.add(key);
+}
+function flushRefresh() {
+  const keys = [...refreshQueue];
+  refreshQueue = new Set();
+  refreshProducts(keys).forEach((promise, i) => promise.then((fresh) => {
+    liveProducts.forEach((el) => {
+      const scope = scopes.get(el);
+      if (!scope || !el.isConnected) return;
+      const k = resolveProductKey(el).key;
+      if (k !== keys[i] && k !== fresh.handle && k !== fresh.id) return;
+      if (JSON.stringify(scope.product) !== JSON.stringify(fresh)) scope.update(fresh);
+    });
+  }).catch((err) => reportError(err, `refresh ${keys[i]}`)));
+}
+
+/**
+ * <script type="application/json" data-tether-hydrate> tags written by tether/server's hydrate():
+ * their products are used without a request. Ignored when they were made for another market.
+ */
+const readScripts = new WeakSet();
+export function hydrateFromPage(root = document) {
+  qsa(root.ownerDocument || root, 'script[type="application/json"][data-tether-hydrate]').forEach((s) => {
+    if (readScripts.has(s)) return;
+    readScripts.add(s);
+    try {
+      const data = JSON.parse(s.textContent);
+      rememberOptionNames(data.products); // the build's option names, also for other languages
+      const same = (a, b) => String(a || '').toUpperCase() === String(b || '').toUpperCase();
+      if (same(data.country, cfg.country) && same(data.language, cfg.language)) hydrateProducts(data.products);
+      else log('hydration skipped: other market');
+    } catch (err) { warn('bad data-tether-hydrate', err); }
+  });
+}

package/src/product.js

@@ -5,7 +5,7 @@
 import { cfg, reportError } from './config.js';
 import {
   attr, sel, get, has, qsa, scoped, emit, formatMoney, formatDate, setText, setImage, show,
-  setSelected, repeat, productUrl, notifyLayoutChanged, watchImages, busy, parseJSONAttr, toAttributes,
+  setSelected, repeat, productUrl, notifyLayoutChanged, watchImages, busy, parseJSONAttr, toAttributes, sameImage, hasTemplate,
 } from './dom.js';
 import { Cart } from './cart.js';
 import { STATUS_KEYS, ownedBy } from './status.js';
@@ -25,6 +25,13 @@ function metafieldValue(product, ref) {
   return mf || null;
 }
 
+// Option names as written in the markup (the build's language), by product handle. With another
+// language Shopify translates them (Size -> Größe), so attributes are matched by position instead.
+const knownOptionNames = new Map();
+export function rememberOptionNames(products) {
+  (products || []).forEach((p) => { if (p?.handle && !knownOptionNames.has(p.handle)) knownOptionNames.set(p.handle, (p.options || []).map((o) => o.name)); });
+}
+
 export class ProductScope {
   constructor(root, product) {
     this.root = root;
@@ -76,6 +83,14 @@ export class ProductScope {
 
   // ------------------------------------------------------------ state
 
+  /** The product's option name for a name used in the markup (same name, or same position). */
+  optName(authored) {
+    const opts = this.product?.options || [];
+    if (!authored || opts.some((o) => o.name === authored)) return authored;
+    const i = (knownOptionNames.get(this.product.handle) || []).indexOf(authored);
+    return i >= 0 && opts[i] ? opts[i].name : authored;
+  }
+
   initSelection() {
     const vs = this.product.variants.nodes;
     const first = vs.find((v) => v.availableForSale) || vs[0];
@@ -208,7 +223,7 @@ export class ProductScope {
       const opt = t.closest(sel('option-value'));
       if (own(opt) && opt.closest(sel('option-list'))) {
         e.preventDefault();
-        this.select(get(opt.closest(sel('option-list')), 'option-list'), get(opt, 'option-value'));
+        this.select(this.optName(get(opt.closest(sel('option-list')), 'option-list')), get(opt, 'option-value'));
         return;
       }
 
@@ -234,7 +249,7 @@ export class ProductScope {
     this.root.addEventListener('change', (e) => {
       const t = e.target;
       if (!own(t)) return;
-      if (t.matches(`select${sel('option')}`)) this.select(get(t, 'option'), t.value);
+      if (t.matches(`select${sel('option')}`)) this.select(this.optName(get(t, 'option')), t.value);
       else if (t.matches(`select${sel('variant-select')}`)) this.selectVariant(t.value);
       else if (t.matches(`select${sel('plan')}`)) {
         if (t.value) this.selectPlan(t.value); else this.setPurchase('one-time');
@@ -266,6 +281,11 @@ export class ProductScope {
   // ------------------------------------------------------------ render
 
   renderProduct() {
+    const p0 = this.product;
+    if (!knownOptionNames.has(p0.handle)) {
+      const authored = this.$(`${sel('option-list')},select${sel('option')}`).map((e) => get(e, 'option-list') || get(e, 'option'));
+      if (authored.some((n) => p0.options.some((o) => o.name === n))) rememberOptionNames([p0]);
+    }
     const p = this.product;
 
     this.$(sel('bind')).forEach((el) => {
@@ -289,7 +309,11 @@ export class ProductScope {
           el.setAttribute('href', productUrl(p.handle, p.id));
           if (key === 'url' && !el.firstElementChild && !el.textContent.trim()) setText(el, p.title);
           return undefined;
-        case 'images':
+        case 'images': {
+          // Server-rendered gallery with the same images: keep it as it is.
+          const imgs = [...el.children].map((n) => (n.tagName === 'IMG' ? n : n.querySelector('img')));
+          if (!hasTemplate(el) && imgs.length === p.images.nodes.length && imgs.every((im, i) => sameImage(im?.getAttribute('src'), p.images.nodes[i].url))) return undefined;
+        }
           return repeat(el, p.images.nodes, (node, img) => {
             const target = node.matches(`img,${sel('bind', 'image')}`) ? node : node.querySelector('img') || node;
             setImage(target, img.url, img.altText || p.title);
@@ -316,7 +340,7 @@ export class ProductScope {
     });
 
     this.$(sel('option-list')).forEach((container) => {
-      const name = get(container, 'option-list');
+      const name = this.optName(get(container, 'option-list'));
       const opt = p.options.find((o) => o.name === name);
       if (!opt || (opt.optionValues.length <= 1 && has(container, 'hide-single'))) return show(container, false);
       return repeat(container, opt.optionValues, (node, v) => {
@@ -330,7 +354,7 @@ export class ProductScope {
     });
 
     this.$(`select${sel('option')}`).forEach((s) => {
-      const opt = p.options.find((o) => o.name === get(s, 'option'));
+      const opt = p.options.find((o) => o.name === this.optName(get(s, 'option')));
       if (!opt) return show(s, false);
       s.innerHTML = '';
       opt.optionValues.forEach((v) => s.appendChild(new Option(v.name, v.name)));
@@ -425,10 +449,10 @@ export class ProductScope {
       else if (text[k]) setText(el, text[k]());
     });
 
-    this.$(sel('option-selected')).forEach((el) => setText(el, this.selected[get(el, 'option-selected')] || ''));
+    this.$(sel('option-selected')).forEach((el) => setText(el, this.selected[this.optName(get(el, 'option-selected'))] || ''));
 
     this.$(sel('option-list')).forEach((container) => {
-      const name = get(container, 'option-list');
+      const name = this.optName(get(container, 'option-list'));
       qsa(container, sel('option-value')).forEach((node) => {
         const value = get(node, 'option-value');
         setSelected(node, this.selected[name] === value);
@@ -438,7 +462,7 @@ export class ProductScope {
       });
     });
 
-    this.$(`select${sel('option')}`).forEach((s) => { s.value = this.selected[get(s, 'option')] || ''; });
+    this.$(`select${sel('option')}`).forEach((s) => { s.value = this.selected[this.optName(get(s, 'option'))] || ''; });
     this.$(`select${sel('variant-select')}`).forEach((s) => { s.value = v.id; });
 
     // Subscription UI

package/src/server.js

@@ -0,0 +1,179 @@
+/**
+ * @occluze/tether/server: Shopify product data at build time or on the server (Astro, Eleventy,
+ * Node, Cloudflare Workers). No browser APIs. Uses the same queries as the browser script, so
+ * products handed over with hydrate() are exactly what Tether expects and need no extra request.
+ *
+ *   import { createStorefront } from '@occluze/tether/server';
+ *   const shop = createStorefront({ domain, token, country: 'NL' });
+ *   const product = await shop.getProduct('coffee-box');
+ *   const all = await shop.allProducts();
+ */
+import { DEFAULTS } from './config.js';
+import { request, withContext, TetherError } from './client.js';
+import { productFragment, collectionFields } from './fragments.js';
+import * as plans from './selling-plans.js';
+import { imageUrl } from './dom.js';
+import { initialState } from './initial.js';
+
+export { imageUrl, initialState };
+
+export { TetherError, plans, withContext };
+
+const isGid = (v) => typeof v === 'string' && v.startsWith('gid://');
+
+/** Handle, numeric id, gid or product URL -> handle or gid. */
+export function productKey(raw) {
+  const v = String(raw ?? '').trim();
+  if (!v) return null;
+  if (isGid(v)) return v;
+  if (/^\d+$/.test(v)) return `gid://shopify/Product/${v}`;
+  const m = v.match(/\/products\/([^/?#]+)/);
+  return m ? m[1] : v;
+}
+
+/** Money as text, e.g. formatMoney({ amount: '30.0', currencyCode: 'EUR' }, 'nl-NL') -> "€ 30,00". */
+export function formatMoney(money, locale) {
+  if (!money) return '';
+  const amount = parseFloat(money.amount);
+  if (Number.isNaN(amount)) return '';
+  try {
+    return new Intl.NumberFormat(locale || undefined, { style: 'currency', currency: money.currencyCode }).format(amount);
+  } catch {
+    return `${money.currencyCode} ${amount.toFixed(2)}`;
+  }
+}
+
+/** productPath '/products' -> /products/<handle>; templates '/p?handle={handle}' and '{id}' work too. */
+export function productUrl(handle, { productPath = '/product', id } = {}) {
+  if (!/\{(handle|id)\}/.test(productPath)) return `${productPath.replace(/\/$/, '')}/${handle}`;
+  return productPath.replace(/\{handle\}/g, encodeURIComponent(handle || '')).replace(/\{id\}/g, encodeURIComponent(id ? String(id).split('/').pop() : ''));
+}
+
+/** JSON for a <script> tag: escapes < so product text can never close the tag. */
+const safeJson = (v) => JSON.stringify(v).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+
+// createStorefront(import.meta.env) works too: these env names map to domain and token.
+const ENV = {
+  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
+  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
+};
+
+export function createStorefront(options = {}) {
+  const known = Object.fromEntries(Object.entries(options).filter(([k]) => k in DEFAULTS || k === 'fetch' || k === 'pageSize'));
+  const conf = { ...DEFAULTS, ...known };
+  for (const [key, names] of Object.entries(ENV)) if (!conf[key]) conf[key] = names.map((n) => options[n]).find(Boolean) || '';
+  conf.domain = String(conf.domain || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  if (!conf.domain || !conf.token) {
+    throw new TetherError('createStorefront needs domain and token: pass them, or import.meta.env with PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN', { code: 'NOT_CONFIGURED' });
+  }
+  const pageSize = options.pageSize || 25;
+  const q = (query, variables, opts) => request(conf, query, variables, opts);
+  const fragment = () => productFragment(conf);
+
+  async function getProduct(raw) {
+    const key = productKey(raw);
+    if (!key) return null;
+    const data = isGid(key)
+      ? await q(`query TetherServerProductById($id: ID!) { node(id: $id) { ... on Product { ...TetherProduct } } }\n${fragment()}`, { id: key })
+      : await q(`query TetherServerProduct($handle: String!) { product(handle: $handle) { ...TetherProduct } }\n${fragment()}`, { handle: key });
+    const p = isGid(key) ? data.node : data.product;
+    return p && p.id ? p : null;
+  }
+
+  async function getProducts({ collection, query, first = pageSize, after = null, sortKey, reverse = false, filters } = {}) {
+    if (collection) {
+      const data = await q(`query TetherServerCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
+  collection(handle: $handle) {
+    ${collectionFields()}
+    products(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, filters: $filters) {
+      nodes { ...TetherProduct }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}
+${fragment()}`, { handle: collection, first, after, sortKey: sortKey || undefined, reverse, filters: filters || undefined });
+      if (!data.collection) return { collection: null, products: [], pageInfo: { hasNextPage: false, endCursor: null } };
+      const { products, ...rest } = data.collection;
+      return { collection: rest, products: products.nodes, pageInfo: products.pageInfo };
+    }
+    const data = await q(`query TetherServerProducts($first: Int!, $after: String, $query: String, $sortKey: ProductSortKeys, $reverse: Boolean) {
+  products(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
+    nodes { ...TetherProduct }
+    pageInfo { hasNextPage endCursor }
+  }
+}
+${fragment()}`, { first, after, query: query || undefined, sortKey: sortKey || undefined, reverse });
+    return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
+  }
+
+  /** Every product (of a collection or a search), page by page. For getStaticPaths(). */
+  async function allProducts(opts = {}) {
+    const out = [];
+    let after = null;
+    for (let i = 0; i < 500; i++) {
+      const page = await getProducts({ ...opts, first: pageSize, after });
+      out.push(...page.products);
+      if (!page.pageInfo.hasNextPage) break;
+      after = page.pageInfo.endCursor;
+    }
+    return out;
+  }
+
+  async function getCollection(handle, opts = {}) {
+    const page = await getProducts({ ...opts, collection: handle });
+    return page.collection ? { ...page.collection, products: page.products, pageInfo: page.pageInfo } : null;
+  }
+
+  async function allCollections() {
+    const out = [];
+    let after = null;
+    for (let i = 0; i < 100; i++) {
+      const data = await q(`query TetherServerCollections($first: Int!, $after: String) {
+  collections(first: $first, after: $after) { nodes { ${collectionFields()} } pageInfo { hasNextPage endCursor } }
+}`, { first: 100, after });
+      out.push(...data.collections.nodes);
+      if (!data.collections.pageInfo.hasNextPage) break;
+      after = data.collections.pageInfo.endCursor;
+    }
+    return out;
+  }
+
+  /** By product id (gid or numeric) or handle, so it can run next to getProduct(handle). */
+  async function getRecommendations(product, intent = 'RELATED') {
+    const key = productKey(typeof product === 'object' ? product?.id : product);
+    const byId = key?.startsWith('gid://');
+    const data = await q(`query TetherServerRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
+}
+${fragment()}`, byId ? { id: key, intent } : { handle: key, intent });
+    return data.productRecommendations || [];
+  }
+
+  /**
+   * A <script> tag that hands products to the browser script: Tether renders them at once,
+   * without its own request, then refreshes prices and stock in the background.
+   * Put it anywhere in the page (Astro: <Fragment set:html={shop.hydrate(products)} />).
+   */
+  function hydrate(products) {
+    const list = (Array.isArray(products) ? products : [products]).filter(Boolean);
+    const payload = { v: 1, at: new Date().toISOString(), country: conf.country || null, language: conf.language || null, products: list };
+    return `<script type="application/json" data-tether-hydrate>${safeJson(payload)}</script>`;
+  }
+
+  return {
+    config: conf,
+    query: q,
+    getProduct,
+    getProducts,
+    allProducts,
+    getCollection,
+    allCollections,
+    getRecommendations,
+    hydrate,
+    formatMoney: (money, locale = conf.locale) => formatMoney(money, locale),
+    imageUrl,
+    initialState: (product, opts = {}) => initialState(product, { defaultPurchase: conf.defaultPurchase, ...opts }),
+    productUrl: (handle, opts = {}) => productUrl(handle, { productPath: conf.productPath, ...opts }),
+    plans,
+  };
+}

package/src/status.js

@@ -53,12 +53,7 @@ export function setScopeStatus(root, status, err) {
   scoped(root, sel('show'), boundary()).forEach((el) => {
     const k = get(el, 'show');
     if (!STATUS_KEYS.includes(k)) return;
-    const visible = k === status;
-    show(el, visible);
-    // Blocks hidden by a Webflow class (display: none) still need to appear.
-    if (visible && typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
-      el.style.display = el.getAttribute(attr('display')) || 'block';
-    }
+    show(el, k === status);
   });
 
   if (status === 'error' || notFound) {

package/types/astro.d.ts

@@ -0,0 +1,15 @@
+import type { TetherConfig } from './index.js';
+
+type Serializable<T> = { [K in keyof T as T[K] extends ((...args: any[]) => any) | null | undefined ? (Exclude<T[K], null | undefined> extends (...args: any[]) => any ? never : K) : K]: T[K] };
+
+export interface TetherAstroOptions extends Partial<Serializable<TetherConfig>> {
+  /** Add the Tether script to every page (default true). False: import and init it yourself. */
+  inject?: boolean;
+}
+
+/**
+ * Astro integration: Tether on every page, store and token from .env
+ * (PUBLIC_SHOPIFY_DOMAIN, PUBLIC_SHOPIFY_STOREFRONT_TOKEN). Functions (onError, hooks) go in
+ * window.TETHER_CONFIG in your layout.
+ */
+export default function tether(options?: TetherAstroOptions): { name: string; hooks: Record<string, (...args: any[]) => unknown> };

package/types/index.d.ts

@@ -60,7 +60,7 @@ export interface ShopifyCartLine {
   merchandise: ShopifyVariant & { product: Pick<ShopifyProduct, 'id' | 'handle' | 'title'> & Record<string, unknown> };
   sellingPlanAllocation?: { sellingPlan: { id: string; name: string } } | null;
   attributes?: { key: string; value: string }[];
-  cost: Record<string, Money | null | undefined>;
+  cost: { totalAmount: Money; subtotalAmount: Money; amountPerQuantity: Money; compareAtAmountPerQuantity?: Money | null };
   [k: string]: unknown;
 }
 
@@ -117,6 +117,10 @@ export interface TetherConfig {
   sellingPlansFirst?: number;
   collectionFirst?: number;
   retries?: number;
+  /** Products handed over by the server (tether/server hydrate()): refresh once in the background (default true). */
+  revalidate?: boolean;
+  /** Mount on Astro View Transitions (astro:page-load) and close the cart on navigation (default true). */
+  astro?: boolean;
   storageKey?: string | null;
   cartDrawerOpenClass?: string;
   openCartOnAdd?: boolean;
@@ -163,11 +167,17 @@ export interface LineInput {
   attributes?: Attributes;
 }
 
+export interface CartWarning { code: string; message: string }
+
 export interface Cart {
   readonly state: ShopifyCart | null;
   readonly lines: ShopifyCartLine[];
   readonly count: number;
   lastError: Error | null;
+  /** Shopify's notes on the last change, e.g. less stock than asked (code MERCHANDISE_NOT_ENOUGH_STOCK). */
+  readonly warnings: CartWarning[];
+  /** true once the saved cart (or the absence of one) is known. */
+  readonly loaded: boolean;
   id(): string | null;
   init(): Promise<ShopifyCart | null>;
   /** add(variantId, qty) · add({ variantId, quantity, sellingPlanId, attributes }) · add([line, line]) */
@@ -189,6 +199,8 @@ export interface Cart {
   isOpen(): boolean;
   drawers(): HTMLElement[];
   render(): void;
+  /** For framework islands: fn(cart, meta) now, when the saved cart has loaded and after every change. Returns unsubscribe. */
+  subscribe(fn: (cart: ShopifyCart | null, meta: { open: boolean; count: number; loaded: boolean; warnings: CartWarning[] }) => void): () => void;
 }
 
 export interface ProductScope {
@@ -262,6 +274,7 @@ export interface TetherEvents {
   'product-added': { product: ShopifyProduct; variant: ShopifyVariant; line: LineInput };
   added: { cart: ShopifyCart; lines: LineInput[] };
   'group-added': { group: string | null; lines: LineInput[] };
+  'cart-warning': { warnings: CartWarning[] };
   'cart-updated': { cart: ShopifyCart | null; reason: string };
   'cart-toggled': { open: boolean };
   'cart-error': { error: Error };
@@ -290,13 +303,15 @@ export interface Tether {
   cart: Cart;
   getProduct(handleOrId: string): Promise<ShopifyProduct>;
   getProducts(opts?: { collection?: string; query?: string; first?: number; after?: string | null; sortKey?: string; reverse?: boolean; filters?: unknown[] }): Promise<ProductPage>;
-  getRecommendations(productId: string, intent?: 'RELATED' | 'COMPLEMENTARY'): Promise<ShopifyProduct[]>;
+  getRecommendations(product: string | Pick<ShopifyProduct, 'id'>, intent?: 'RELATED' | 'COMPLEMENTARY'): Promise<ShopifyProduct[]>;
   getScope(el: Element | null | undefined): ProductScope | null;
   addGroup(button: Element): Promise<ShopifyCart | null>;
   primeProduct(product: ShopifyProduct): void;
   normalizeProductKey(raw: string | number): string | null;
   clearProductCache(): void;
   formatMoney(money: Money | null | undefined): string;
+  /** Shopify CDN image at a size: imageUrl(line.merchandise.image?.url, { width: 160 }). */
+  imageUrl(url: string | null | undefined, size?: { width?: number; height?: number; crop?: string }): string;
   plans: SellingPlanHelpers;
   TetherError: typeof TetherError;
   resolveProductKey(el: Element, location?: Location | URL): { key: string | null; fromUrl: boolean; raw: string };