@occluze/tether 0.3.5 → 0.4.0

package/package.json

@@ -1,32 +1,49 @@
 {
   "name": "@occluze/tether",
-  "version": "0.3.5",
+  "version": "0.4.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"
+    },
+    "./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"
   ],
   "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"
@@ -55,5 +72,6 @@
   ],
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "types": "types/index.d.ts"
 }

package/src/cart.js

@@ -34,6 +34,23 @@ function mutation(name, args, inner) {
 ${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 = {
@@ -255,6 +272,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,7 +289,11 @@ 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 });
   },
@@ -276,6 +307,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')));

package/src/config.js

@@ -30,6 +30,7 @@ export const DEFAULTS = {
   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 +39,7 @@ export const DEFAULTS = {
   // Mounting
   autoMount: true,            // mount document on DOMContentLoaded
   observe: false,             // auto-mount nodes added later (CMS load-more, filters)
+  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/index.js

@@ -9,38 +9,23 @@
  */
 import { cfg, configure, isConfigured, log, warn, reportError } from './config.js';
 import { gql, TetherError, withContext } from './client.js';
-import { Cart } from './cart.js';
-import { ProductScope, scopes } from './product.js';
+import { Cart, focusables } from './cart.js';
+import { scopes } from './product.js';
 import { ListScope, listSelector } from './collection.js';
 import {
   getProduct, getProducts, getRecommendations, clearProductCache, primeProduct, normalizeProductKey,
 } from './loader.js';
 import * as plans from './selling-plans.js';
-import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
-import { diagnose } from './diagnose.js';
-import { detectMarket, rememberMarket, getLocalization, clearLocalization, toCountry, toLanguage } from './markets.js';
+import { resolveProductKey } from './status.js';
 import { attr, sel, get, qsa, emit, formatMoney, busy, parseJSONAttr, toAttributes } from './dom.js';
+import { loadPart, coreModules } from './lazy.js';
+import { mountedLists, liveLists, pruneLive, within, mountProduct, retryFailed } from './mounting.js';
 
-export const VERSION = '0.3.5';
+export const VERSION = '0.4.0';
 
-const mountedProducts = new WeakSet();
-const mountedLists = new WeakSet();
-// Live roots, for re-rendering after a country switch (pruned when disconnected).
-const liveProducts = new Set();
-const liveLists = new Set();
-const requestToken = new WeakMap(); // product root -> latest request, so a slow old response can't win
-
-function pruneLive() {
-  liveProducts.forEach((el) => { if (!el.isConnected) liveProducts.delete(el); });
-  liveLists.forEach((l) => { if (!l.root.isConnected) liveLists.delete(l); });
-}
 let initPromise = null;
 let observer = null;
 
-function within(root, selector) {
-  return [...(root.matches?.(selector) ? [root] : []), ...qsa(root, selector)];
-}
-
 /** Mount every product scope and product list inside `root`. Safe to call repeatedly. */
 export function mount(root = document) {
   if (!isConfigured()) return 0;
@@ -59,7 +44,10 @@ export function mount(root = document) {
 
   within(root, sel('product')).forEach((el) => { if (mountProduct(el)) count++; });
 
-  renderCountrySelects(root);
+  // The country select lives in the optional markets part: load it only when the page uses it.
+  if (within(root, `${sel('country-select')},${sel('country-bind')}`).length) {
+    loadPart('markets').then((m) => m.renderCountrySelects(root)).catch((err) => reportError(err, 'markets'));
+  }
 
   qsa(root, sel('account-link')).forEach((a) => {
     a.setAttribute('href', `https://${cfg.domain}/account`);
@@ -70,132 +58,10 @@ export function mount(root = document) {
   return count;
 }
 
-/** Mounts one product root. Returns true when a product request was started. */
-function mountProduct(el) {
-  if (mountedProducts.has(el)) return false;
-  const { key, fromUrl, raw } = resolveProductKey(el);
-  if (!key) {
-    if (fromUrl) {
-      // Dynamic product page opened without ?handle= (or an empty path).
-      mountedProducts.add(el);
-      setScopeStatus(el, 'not-found');
-      emit('product-not-found', { key: null, source: raw }, el);
-    } else if (!el.closest(listSelector())) {
-      // List cards get their handle when the list renders.
-      warn(`[${attr('product')}] without a value. Bind it to the Shopify handle field, or use "url:handle".`, el);
-    }
-    return false;
-  }
-  mountedProducts.add(el);
-  liveProducts.add(el);
-  const token = {};
-  requestToken.set(el, token);
-  const current = () => requestToken.get(el) === token;
-  // A rendered scope keeps showing its content while it refreshes (e.g. country switch).
-  if (!scopes.get(el)) setScopeStatus(el, 'loading');
-  else el.setAttribute(attr('state'), 'updating');
-  getProduct(key)
-    .then((p) => {
-      if (!current()) return;
-      const existing = scopes.get(el);
-      if (existing) existing.update(p);
-      // eslint-disable-next-line no-new
-      else new ProductScope(el, p);
-      applyPageTitle(el, p);
-    })
-    .catch((err) => {
-      if (!current()) return;
-      const notFound = isNotFound(err);
-      setScopeStatus(el, notFound ? 'not-found' : 'error', err);
-      if (notFound) {
-        emit('product-not-found', { key, source: raw }, el);
-        // A typo in a URL isn't worth an alert; a CMS item pointing at a deleted product is.
-        if (fromUrl) log(`product not found: ${key}`); else reportError(err, `product ${key}`);
-      } else {
-        reportError(err, `product ${key}`);
-        emit('error', { error: err, context: 'product', key }, el);
-      }
-    });
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // Markets: country select + switching
 // ---------------------------------------------------------------------------
 
-/**
- * select[tether-country-select]: countries the store sells to (Shopify Markets).
- * tether-country-label="{name} ({currency})" sets the option text ({name}, {code}, {currency}, {symbol}).
- * tether-country-bind="name|code|currency|symbol" shows the current country anywhere.
- */
-function renderCountrySelects(root = document) {
-  const selects = within(root, `select${sel('country-select')}`);
-  const binds = within(root, sel('country-bind'));
-  if (!selects.length && !binds.length) return Promise.resolve();
-  return getLocalization().then((loc) => {
-    const current = (cfg.country || loc.country?.isoCode || '').toUpperCase();
-    const countries = [...(loc.availableCountries || [])].sort((a, b) => a.name.localeCompare(b.name, cfg.locale || undefined));
-    const info = countries.find((c) => c.isoCode === current) || loc.country;
-    const fill = (tpl, c) => tpl.replace(/\{name\}/g, c.name).replace(/\{code\}/g, c.isoCode)
-      .replace(/\{currency\}/g, c.currency?.isoCode || '').replace(/\{symbol\}/g, c.currency?.symbol || '');
-    selects.forEach((s) => {
-      const tpl = s.getAttribute(attr('country-label')) || '{name} ({currency})';
-      s.innerHTML = '';
-      countries.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'));
-    });
-    binds.forEach((el) => {
-      const k = get(el, 'country-bind') || 'name';
-      const v = { name: info?.name, code: info?.isoCode, currency: info?.currency?.isoCode, symbol: info?.currency?.symbol }[k];
-      el.textContent = v || '';
-    });
-  }).catch((err) => reportError(err, 'country select'));
-}
-
-/**
- * Switches the market: prices, currency and translations follow (@inContext), the cart's
- * 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 } = {}) {
-  const country = toCountry(code);
-  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
-  const lang = language === undefined ? cfg.language : toLanguage(language);
-  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language;
-  cfg.country = country;
-  cfg.language = lang || undefined;
-  if (remember) rememberMarket({ country, language: lang });
-  if (!changed) { renderCountrySelects(); return Cart.state; }
-
-  clearProductCache();
-  const jobs = [];
-  if (language !== undefined) clearLocalization(); // country names follow the language
-  // Only an existing cart moves; switching country never creates one.
-  if (Cart.id()) jobs.push(Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((err) => reportError(err, 'cart country')));
-
-  pruneLive();
-  liveLists.forEach((list) => jobs.push(list.load()));
-  liveProducts.forEach((el) => {
-    if (el.closest(listSelector())) return; // re-rendered by its list
-    mountedProducts.delete(el);
-    mountProduct(el);
-  });
-
-  renderCountrySelects();
-  emit('country-changed', { country, language: cfg.language });
-  await Promise.all(jobs);
-  return Cart.state;
-}
-
-/** tether-page-title="{title} | My shop" on a product root sets document.title (dynamic product pages). */
-function applyPageTitle(el, p) {
-  const tpl = get(el, 'page-title');
-  if (!tpl || typeof document === 'undefined') return;
-  document.title = tpl.replace(/\{title\}/g, p.title).replace(/\{vendor\}/g, p.vendor || '').replace(/\{type\}/g, p.productType || '');
-}
-
 /** Call before a page transition removes `root` (closes the drawer etc.). */
 export function unmount() {
   Cart.close();
@@ -285,7 +151,27 @@ function bindControls() {
     });
   });
 
-  document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && Cart.isOpen()) Cart.close(); });
+  // Back online after a failed load: try the failed products and lists again.
+  window.addEventListener('online', () => {
+    retryFailed();
+    liveLists.forEach((l) => { if (l.root.getAttribute(attr('state')) === 'error') l.load(); });
+  });
+
+  document.addEventListener('keydown', (e) => {
+    if (!Cart.isOpen()) return;
+    if (e.key === 'Escape') { Cart.close(); return; }
+    if (e.key !== 'Tab' || cfg.cartFocus === false) return;
+    // Keep Tab inside the open cart.
+    const d = Cart.drawers().find((x) => x.classList.contains(cfg.cartDrawerOpenClass));
+    const f = d ? focusables(d) : [];
+    if (!f.length) return;
+    const first = f[0];
+    const last = f[f.length - 1];
+    if (!d.contains(document.activeElement) || (e.shiftKey && document.activeElement === first) || (!e.shiftKey && document.activeElement === last)) {
+      e.preventDefault();
+      (e.shiftKey ? last : first).focus();
+    }
+  });
 }
 
 function dataKeySel() { return `[data-${cfg.prefix}-key]`; }
@@ -333,17 +219,10 @@ export function init(overrides = {}) {
     return initPromise;
   }
 
-  // Detected market (saved choice, server hint, Webflow locale) wins over the static config.
-  const market = detectMarket(cfg.markets);
-  if (market.country) cfg.country = market.country;
-  if (market.language) cfg.language = market.language;
-  if (market.locale && !overrides.locale && !window.TETHER_CONFIG?.locale) cfg.locale = market.locale;
-  if (market.sources && Object.keys(market.sources).length) log('market', market);
-
   bindControls();
   if (cfg.observe) startObserver();
 
-  initPromise = Cart.init().then(async (cart) => {
+  initPromise = applyMarket(overrides).then(() => Cart.init()).then(async (cart) => {
     // A saved cart from another market: move it to this one, so prices match the page.
     const want = cfg.country ? String(cfg.country).toUpperCase() : null;
     if (cart && want && cart.buyerIdentity?.countryCode && cart.buyerIdentity.countryCode !== want) {
@@ -355,6 +234,33 @@ export function init(overrides = {}) {
   return initPromise;
 }
 
+/**
+ * Detected market (saved choice, server hint, Webflow locale) wins over the static config.
+ * Without markets.detect only the visitor's saved choice applies, read here without loading
+ * the markets part.
+ */
+async function applyMarket(overrides) {
+  const m = cfg.markets || {};
+  if (m.detect === false) return;
+  let market = null;
+  if (m.detect) {
+    try { market = (await loadPart('markets')).detectMarket(m); } catch (err) { reportError(err, 'markets'); return; }
+  } else if (m.remember !== false) {
+    try { market = JSON.parse(localStorage.getItem(`${cfg.prefix}:market:${cfg.domain}`) || 'null'); } catch { /* none */ }
+    if (market && !/^[A-Z]{2}$/.test(market.country || '')) market = null;
+  }
+  if (!market) return;
+  if (market.country) cfg.country = market.country;
+  if (market.language) cfg.language = market.language;
+  if (market.locale && !overrides.locale && !window.TETHER_CONFIG?.locale) cfg.locale = market.locale;
+  log('market', market);
+}
+
+/** Tether.setCountry('DE'): loads the markets part on first use. */
+export function setCountry(code, opts) {
+  return loadPart('markets').then((m) => m.setCountry(code, opts));
+}
+
 function startObserver() {
   if (observer || typeof MutationObserver === 'undefined') return;
   let t = null;
@@ -390,9 +296,11 @@ export const api = {
   TetherError,
   resolveProductKey,
   setCountry,
-  detectMarket: (markets) => detectMarket(markets || cfg.markets),
-  getLocalization,
-  diagnose: (opts) => diagnose({ ...opts, version: VERSION }),
+  detectMarket: (markets) => loadPart('markets').then((m) => m.detectMarket(markets || cfg.markets)),
+  getLocalization: () => loadPart('markets').then((m) => m.getLocalization()),
+  diagnose: (opts) => loadPart('diagnose').then((m) => m.diagnose({ ...opts, version: VERSION })),
+  __core: coreModules,
+  __parts: {},
   on(name, fn) {
     const h = (e) => fn(e.detail, e);
     document.addEventListener(`${cfg.prefix}:${name}`, h);

package/src/lazy-iife.js

@@ -0,0 +1,43 @@
+/**
+ * <script> build: optional parts are separate files next to tether(.min).js, e.g.
+ * tether.markets.min.js, loaded on first use. Override the folder with config.partsUrl.
+ */
+import * as config from './config.js';
+import * as client from './client.js';
+import * as dom from './dom.js';
+import * as fragments from './fragments.js';
+import * as loader from './loader.js';
+import * as sellingPlans from './selling-plans.js';
+import * as status from './status.js';
+import * as cart from './cart.js';
+import * as product from './product.js';
+import * as collection from './collection.js';
+import * as mounting from './mounting.js';
+
+const { cfg } = config;
+
+/** The modules a part may use, shared instead of bundled twice (scripts/build.mjs maps imports to these). */
+export const coreModules = {
+  'config.js': config, 'client.js': client, 'dom.js': dom, 'fragments.js': fragments, 'loader.js': loader,
+  'selling-plans.js': sellingPlans, 'status.js': status, 'cart.js': cart, 'product.js': product,
+  'collection.js': collection, 'mounting.js': mounting,
+};
+
+const self = typeof document !== 'undefined' ? document.currentScript?.src || '' : '';
+const parts = {};
+
+export function loadPart(name) {
+  if (parts[name]) return parts[name];
+  const base = cfg.partsUrl || self.replace(/[^/]*$/, '');
+  const min = /\.min\.js(\?|$)/.test(self) || !self ? '.min' : '';
+  const url = `${base.replace(/\/?$/, '/')}tether.${name}${min}.js`;
+  parts[name] = new Promise((resolve, reject) => {
+    const s = document.createElement('script');
+    s.src = url;
+    s.async = true;
+    s.onload = () => (window.Tether?.__parts?.[name] ? resolve(window.Tether.__parts[name]) : reject(new Error(`${url} did not register`)));
+    s.onerror = () => { delete parts[name]; reject(new Error(`Could not load ${url}. Host it next to the Tether script, or set partsUrl.`)); };
+    document.head.appendChild(s);
+  });
+  return parts[name];
+}

package/src/lazy.js

@@ -0,0 +1,9 @@
+/**
+ * Optional parts that most pages never need, loaded on first use.
+ * ESM / Node: dynamic import (bundlers split these into their own chunks).
+ * The <script> build swaps this file for lazy-iife.js (see scripts/build.mjs).
+ */
+export const loadPart = (name) => (name === 'diagnose' ? import('./diagnose.js') : import('./markets-ui.js'));
+
+// Only the <script> build shares its modules with separately loaded parts.
+export const coreModules = undefined;

package/src/loader.js

@@ -74,7 +74,7 @@ async function flush() {
     parts.push(`h${i}: product(handle: $h${i}) { ...TetherProduct }`);
   });
 
-  const query = `query TetherProducts(${defs.join(', ')}) {\n  ${parts.join('\n  ')}\n}\n${productFragment()}`;
+  const query = `query TetherProducts(${defs.join(',')}) { ${parts.join(' ')} } ${productFragment()}`;
   log('fetch products', keys);
 
   const settle = (k, fn) => {

package/src/markets-ui.js

@@ -0,0 +1,81 @@
+/**
+ * Optional part, loaded on first use: market detection, select[tether-country-select],
+ * tether-country-bind and Tether.setCountry(). See markets.js for the detection rules.
+ */
+import { cfg, reportError } from './config.js';
+import { TetherError } from './client.js';
+import { Cart } from './cart.js';
+import { listSelector } from './collection.js';
+import { clearProductCache } from './loader.js';
+import { attr, sel, get, emit } from './dom.js';
+import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.js';
+import { rememberMarket, getLocalization, clearLocalization, toCountry, toLanguage } from './markets.js';
+
+export { detectMarket, getLocalization } from './markets.js';
+
+export /**
+ * select[tether-country-select]: countries the store sells to (Shopify Markets).
+ * tether-country-label="{name} ({currency})" sets the option text ({name}, {code}, {currency}, {symbol}).
+ * tether-country-bind="name|code|currency|symbol" shows the current country anywhere.
+ */
+function renderCountrySelects(root = document) {
+  const selects = within(root, `select${sel('country-select')}`);
+  const binds = within(root, sel('country-bind'));
+  if (!selects.length && !binds.length) return Promise.resolve();
+  return getLocalization().then((loc) => {
+    const current = (cfg.country || loc.country?.isoCode || '').toUpperCase();
+    const countries = [...(loc.availableCountries || [])].sort((a, b) => a.name.localeCompare(b.name, cfg.locale || undefined));
+    const info = countries.find((c) => c.isoCode === current) || loc.country;
+    const fill = (tpl, c) => tpl.replace(/\{name\}/g, c.name).replace(/\{code\}/g, c.isoCode)
+      .replace(/\{currency\}/g, c.currency?.isoCode || '').replace(/\{symbol\}/g, c.currency?.symbol || '');
+    selects.forEach((s) => {
+      const tpl = s.getAttribute(attr('country-label')) || '{name} ({currency})';
+      s.innerHTML = '';
+      countries.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'));
+    });
+    binds.forEach((el) => {
+      const k = get(el, 'country-bind') || 'name';
+      const v = { name: info?.name, code: info?.isoCode, currency: info?.currency?.isoCode, symbol: info?.currency?.symbol }[k];
+      el.textContent = v || '';
+    });
+  }).catch((err) => reportError(err, 'country select'));
+}
+
+/**
+ * Switches the market: prices, currency and translations follow (@inContext), the cart's
+ * 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 } = {}) {
+  const country = toCountry(code);
+  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
+  const lang = language === undefined ? cfg.language : toLanguage(language);
+  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language;
+  cfg.country = country;
+  cfg.language = lang || undefined;
+  if (remember) rememberMarket({ country, language: lang });
+  if (!changed) { renderCountrySelects(); return Cart.state; }
+
+  clearProductCache();
+  const jobs = [];
+  if (language !== undefined) clearLocalization(); // country names follow the language
+  // Only an existing cart moves; switching country never creates one.
+  if (Cart.id()) jobs.push(Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((err) => reportError(err, 'cart country')));
+
+  pruneLive();
+  liveLists.forEach((list) => jobs.push(list.load()));
+  liveProducts.forEach((el) => {
+    if (el.closest(listSelector())) return; // re-rendered by its list
+    mountedProducts.delete(el);
+    mountProduct(el);
+  });
+
+  renderCountrySelects();
+  emit('country-changed', { country, language: cfg.language });
+  await Promise.all(jobs);
+  return Cart.state;
+}
+

package/src/mounting.js

@@ -0,0 +1,89 @@
+/** 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 { listSelector } from './collection.js';
+import { getProduct } from './loader.js';
+import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
+import { attr, get, qsa, emit } from './dom.js';
+
+export const mountedProducts = new WeakSet();
+export const mountedLists = new WeakSet();
+// Live roots, for re-rendering after a country switch (pruned when disconnected).
+export const liveProducts = new Set();
+export const liveLists = new Set();
+const requestToken = new WeakMap(); // product root -> latest request, so a slow old response can't win
+
+export function pruneLive() {
+  liveProducts.forEach((el) => { if (!el.isConnected) liveProducts.delete(el); });
+  liveLists.forEach((l) => { if (!l.root.isConnected) liveLists.delete(l); });
+}
+export function within(root, selector) {
+  return [...(root.matches?.(selector) ? [root] : []), ...qsa(root, selector)];
+}
+
+export /** Mounts one product root. Returns true when a product request was started. */
+function mountProduct(el) {
+  if (mountedProducts.has(el)) return false;
+  const { key, fromUrl, raw } = resolveProductKey(el);
+  if (!key) {
+    if (fromUrl) {
+      // Dynamic product page opened without ?handle= (or an empty path).
+      mountedProducts.add(el);
+      setScopeStatus(el, 'not-found');
+      emit('product-not-found', { key: null, source: raw }, el);
+    } else if (!el.closest(listSelector())) {
+      // List cards get their handle when the list renders.
+      warn(`[${attr('product')}] without a value. Bind it to the Shopify handle field, or use "url:handle".`, el);
+    }
+    return false;
+  }
+  mountedProducts.add(el);
+  liveProducts.add(el);
+  const token = {};
+  requestToken.set(el, token);
+  const current = () => requestToken.get(el) === token;
+  // A rendered scope keeps showing its content while it refreshes (e.g. country switch).
+  if (!scopes.get(el)) setScopeStatus(el, 'loading');
+  else el.setAttribute(attr('state'), 'updating');
+  getProduct(key)
+    .then((p) => {
+      if (!current()) return;
+      const existing = scopes.get(el);
+      if (existing) existing.update(p);
+      // eslint-disable-next-line no-new
+      else new ProductScope(el, p);
+      applyPageTitle(el, p);
+    })
+    .catch((err) => {
+      if (!current()) return;
+      const notFound = isNotFound(err);
+      setScopeStatus(el, notFound ? 'not-found' : 'error', err);
+      if (notFound) {
+        emit('product-not-found', { key, source: raw }, el);
+        // A typo in a URL isn't worth an alert; a CMS item pointing at a deleted product is.
+        if (fromUrl) log(`product not found: ${key}`); else reportError(err, `product ${key}`);
+      } else {
+        reportError(err, `product ${key}`);
+        emit('error', { error: err, context: 'product', key }, el);
+      }
+    });
+  return true;
+}
+
+/** tether-page-title="{title} | My shop" on a product root sets document.title (dynamic product pages). */
+function applyPageTitle(el, p) {
+  const tpl = get(el, 'page-title');
+  if (!tpl || typeof document === 'undefined') return;
+  document.title = tpl.replace(/\{title\}/g, p.title).replace(/\{vendor\}/g, p.vendor || '').replace(/\{type\}/g, p.productType || '');
+}
+
+
+/** Product scopes that failed on a network/API error: loaded again when the browser is back online. */
+export function retryFailed() {
+  pruneLive();
+  liveProducts.forEach((el) => {
+    if (el.getAttribute(attr('state')) !== 'error' || el.getAttribute(attr('error')) === 'not-found') return;
+    mountedProducts.delete(el);
+    mountProduct(el);
+  });
+}