@occluze/tether 0.6.7 → 0.7.0

package/src/diagnose.ts

@@ -0,0 +1,294 @@
+/**
+ * `Tether.diagnose()`: one call in the browser console that explains what's wrong on a page. Logs a readable report
+ * and returns it as an object. The markup checks are in diagnose-markup.ts.
+ *
+ *   await Tether.diagnose()
+ *   await Tether.diagnose({ silent: true })   // just the object
+ */
+import { cfg, isConfigured } from './config.ts';
+import { gql, endpoint, shaped } from './client.ts';
+import { sel, get, qsa } from './dom.ts';
+import { getProduct } from './loader.ts';
+import { allPlans } from './selling-plans.ts';
+import { resolveProductKey } from './status.ts';
+import { apiVersionStatus } from './api-version.ts';
+import { loadPart } from './lazy.ts';
+import { checkMarkup, didYouMean } from './diagnose-markup.ts';
+import type { ApiVersionStatus } from './api-version.ts';
+import type { DetectedMarket } from './markets.ts';
+import type { Problem } from './diagnose-markup.ts';
+import type { Product } from './fragments.ts';
+
+export { apiVersionStatus, checkMarkup, didYouMean };
+
+/** The market in use (a visitor's choice included), and what detection would pick. */
+interface MarketReport {
+  country: string | null;
+  language: string | null;
+  locale: string | null;
+  /** `null` without `markets.detect`. */
+  detected: DetectedMarket | null;
+}
+
+interface ShopReport {
+  name: string;
+  url: string;
+  currency: string;
+}
+
+type ProductReport =
+  | { key: string; handle: string; title: string; plans: number; requiresSellingPlan: boolean }
+  | { key: string; error: string | undefined };
+
+interface SellingPlanReport {
+  product: string;
+  group: string;
+  plan: string;
+  id: string;
+}
+
+export interface DiagnoseReport {
+  /** Tether's version, `''` when the caller didn't say. */
+  version: string;
+  /** The config, with the token masked. */
+  config: Record<string, unknown>;
+  apiVersion: ApiVersionStatus;
+  market: MarketReport;
+  reachable: boolean;
+  shop: ShopReport | null;
+  latencyMs: number | null;
+  products: ProductReport[];
+  sellingPlans: SellingPlanReport[];
+  problems: Problem[];
+}
+
+type StorefrontCheck =
+  | { kind: 'not-configured' }
+  | { kind: 'reachable'; shop: ShopReport; latencyMs: number }
+  | { kind: 'unreachable'; error: unknown; latencyMs: number };
+
+export interface DiagnoseOptions {
+  root?: ParentNode;
+  /** Return the report without logging it. */
+  silent?: boolean;
+  /** Tether's version, for the report. */
+  version?: string;
+  /** The date the API version's support is measured against. */
+  now?: Date;
+}
+
+/** Products checked at most, so a long CMS page doesn't send a request per card. */
+const MAX_PRODUCTS_CHECKED = 20;
+/** Matches the warning window of `apiVersionStatus`. */
+const API_UPGRADE_WARNING_MONTHS = 3;
+const TOKEN_EDGE_CHARACTERS = 4;
+
+function maskToken(token: string): string {
+  if (!token) return '(missing)';
+  return `${token.slice(0, TOKEN_EDGE_CHARACTERS)}…${token.slice(-TOKEN_EDGE_CHARACTERS)} (${token.length} chars)`;
+}
+
+/** The error's message, else its code (a `TetherError` has one), else `fallback`. */
+function errorText(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message) return error.message;
+  const code: unknown = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+  return typeof code === 'string' && code ? code : fallback;
+}
+
+function configSummary(): Record<string, unknown> {
+  return {
+    domain: cfg.domain || '(missing)',
+    token: maskToken(cfg.token),
+    apiVersion: cfg.apiVersion,
+    endpoint: cfg.domain ? endpoint() : null,
+    country: cfg.country,
+    language: cfg.language,
+    locale: cfg.locale,
+    markets: cfg.markets,
+    prefix: cfg.prefix,
+    productPath: cfg.productPath,
+    metafields: cfg.metafields,
+    autoMount: cfg.autoMount,
+    observe: cfg.observe,
+    onError: typeof cfg.onError === 'function',
+  };
+}
+
+/**
+ * Detection runs in the markets part, which init has already loaded whenever `markets.detect` is set.
+ */
+async function marketSummary(): Promise<MarketReport> {
+  return {
+    country: cfg.country || null,
+    language: cfg.language || null,
+    locale: cfg.locale || null,
+    detected: cfg.markets?.detect ? (await loadPart('markets')).detectMarket(cfg.markets) : null,
+  };
+}
+
+/** An error for an unsupported version, a warning when support ends soon. */
+function apiVersionProblem({ ok, monthsLeft, note }: ApiVersionStatus): Problem | null {
+  if (ok && (monthsLeft === undefined || monthsLeft >= API_UPGRADE_WARNING_MONTHS)) return null;
+  return { level: ok ? 'warn' : 'error', message: `apiVersion ${cfg.apiVersion}: ${note}` };
+}
+
+const isShopAnswer = shaped<{
+  shop: { name: string; primaryDomain: { url: string }; paymentSettings: { currencyCode: string } };
+}>({ shop: { name: 'string', primaryDomain: { url: 'string' }, paymentSettings: { currencyCode: 'string' } } });
+
+async function checkStorefront(): Promise<StorefrontCheck> {
+  if (!isConfigured()) return { kind: 'not-configured' };
+  const startedAt = Date.now();
+  try {
+    const data = await gql(
+      'query TetherDiagnose { shop { name primaryDomain { url } paymentSettings { currencyCode } } }',
+      {},
+      isShopAnswer,
+      { context: false },
+    );
+    const shop = {
+      name: data.shop.name,
+      url: data.shop.primaryDomain.url,
+      currency: data.shop.paymentSettings.currencyCode,
+    };
+    return { kind: 'reachable', shop, latencyMs: Date.now() - startedAt };
+  } catch (error) {
+    return { kind: 'unreachable', error, latencyMs: Date.now() - startedAt };
+  }
+}
+
+/**
+ * Options a visitor can't choose on this page get the first available variant's value.
+ */
+function checkOptions(root: ParentNode, key: string, product: Product): Problem[] {
+  const problems: Problem[] = [];
+  const names = product.options.map((option) => option.name);
+  const roots = qsa(root, sel('product')).filter(
+    (el) => resolveProductKey(el).key === key && el.querySelector(sel('add-to-cart')),
+  );
+  for (const el of roots) {
+    const shown = new Set(
+      qsa(el, `${sel('option-list')},select${sel('option')}`).map(
+        (list) => get(list, 'option-list') || get(list, 'option'),
+      ),
+    );
+    if (!shown.size && qsa(el, `select${sel('variant-select')}`).length) continue;
+    // Translated option names (a language in the market) don't match the names in the markup.
+    if (!cfg.language) {
+      for (const name of shown) {
+        if (!name || names.includes(name)) continue;
+        problems.push({
+          level: 'warn',
+          message: `Product "${product.handle}" has no option "${name}" (its options: ${names.join(', ') || 'none'}).${didYouMean(name, names)}`,
+        });
+      }
+    }
+    for (const option of product.options) {
+      if (option.optionValues.length <= 1 || shown.has(option.name)) continue;
+      problems.push({
+        level: 'warn',
+        message: `Product "${product.handle}": option "${option.name}" (${option.optionValues.length} values) has no tether-option-list, so visitors can't choose it.`,
+      });
+    }
+  }
+  return problems;
+}
+
+/**
+ * Loads the page's products and adds what it finds about each to `report`.
+ */
+async function checkProducts(root: ParentNode, report: DiagnoseReport): Promise<void> {
+  const allKeys = qsa(root, sel('product')).map((el) => resolveProductKey(el).key);
+  const keys = [...new Set(allKeys.filter((key) => key !== null && key !== ''))].slice(0, MAX_PRODUCTS_CHECKED);
+  const results = await Promise.allSettled(keys.map((key) => getProduct(key)));
+  results.forEach((result, index) => {
+    const key = keys[index] ?? '';
+    if (result.status === 'rejected') {
+      const reason = errorText(result.reason, 'not loaded');
+      report.products.push({ key, error: result.reason instanceof Error ? result.reason.message : undefined });
+      report.problems.push({
+        level: 'error',
+        message: `Product "${key}": ${reason}. Is it published to the Headless channel?`,
+      });
+      return;
+    }
+    const product = result.value;
+    const plans = allPlans(product);
+    report.products.push({
+      key,
+      handle: product.handle,
+      title: product.title,
+      plans: plans.length,
+      requiresSellingPlan: product.requiresSellingPlan,
+    });
+    for (const plan of plans) {
+      report.sellingPlans.push({ product: product.handle, group: plan.group.name, plan: plan.name, id: plan.id });
+    }
+    report.problems.push(...checkOptions(root, key, product));
+  });
+}
+
+/** What's wrong on the page: config, token, API version, products, plans, markup. */
+export async function diagnose({
+  root = document,
+  silent = false,
+  version = '',
+  now = new Date(),
+}: DiagnoseOptions = {}): Promise<DiagnoseReport> {
+  const storefront = await checkStorefront();
+  const report: DiagnoseReport = {
+    version,
+    config: configSummary(),
+    apiVersion: apiVersionStatus(cfg.apiVersion, now),
+    market: await marketSummary(),
+    reachable: storefront.kind === 'reachable',
+    shop: storefront.kind === 'reachable' ? storefront.shop : null,
+    latencyMs: storefront.kind === 'not-configured' ? null : storefront.latencyMs,
+    products: [],
+    sellingPlans: [],
+    problems: [],
+  };
+  switch (storefront.kind) {
+    case 'not-configured':
+      report.problems.push({ level: 'error', message: 'TETHER_CONFIG needs domain and token.' });
+      break;
+    case 'unreachable':
+      report.problems.push({
+        level: 'error',
+        message: `Storefront API not reachable: ${errorText(storefront.error, 'unknown error')}`,
+      });
+      break;
+    case 'reachable':
+      await checkProducts(root, report);
+      break;
+  }
+  const versionProblem = apiVersionProblem(report.apiVersion);
+  if (versionProblem) report.problems.push(versionProblem);
+  if (typeof document !== 'undefined') report.problems.push(...checkMarkup(root));
+  if (!silent) print(report);
+  return report;
+}
+
+function print(report: DiagnoseReport): void {
+  const errors = report.problems.filter((problem) => problem.level === 'error').length;
+  const warnings = report.problems.length - errors;
+  console.group(`[${cfg.prefix}] diagnose: ${errors ? `${errors} error(s)` : 'no errors'}, ${warnings} warning(s)`);
+  console.log('version', report.version, '| API', report.apiVersion.version, `(${report.apiVersion.note})`);
+  console.log('config', report.config);
+  const { country, language, detected } = report.market;
+  const inUse = [country, language].filter(Boolean).join(' / ') || 'the store default';
+  console.log('market', `in use: ${inUse}`, detected ? `(detection picks ${JSON.stringify(detected)})` : '');
+  console.log(
+    report.shop
+      ? `Storefront API reachable: ${report.shop.name} (${report.latencyMs ?? 0} ms)`
+      : 'Storefront API NOT reachable',
+  );
+  if (report.products.length) console.table(report.products);
+  if (report.sellingPlans.length) console.table(report.sellingPlans);
+  else if (report.reachable) console.log('No selling plans on the products of this page.');
+  for (const problem of report.problems) {
+    if (problem.level === 'error') console.error(problem.message, problem.el ?? '');
+    else console.warn(problem.message, problem.el ?? '');
+  }
+  console.groupEnd();
+}

package/src/dom.ts

@@ -0,0 +1,268 @@
+/**
+ * The browser modules' DOM toolkit: what Shopify values look like on the page (money, dates, text, images, lists)
+ * and how elements show, hide and report layout changes. Attribute names go through `attr()` so the prefix is
+ * configurable. The optional parts import all of it from here (`window.Tether.__core['dom.ts']`).
+ */
+import { cfg, reportError, warn } from './config.ts';
+import { attr, emit, get } from './markup.ts';
+import { storeHtmlFragment } from './store-html.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import { formatMoney as formatMoneyIn, productUrl as productUrlFor } from './shopify-values.ts';
+import type { Money } from './shopify-values.ts';
+
+export { attr, sel, get, has, qsa, scoped, emit, ownEvent, isOwnEvent, ANALYTICS_EVENTS } from './markup.ts';
+export { imageUrl, cdnUrl, sameImage, setImage } from './images.ts';
+export { hasTemplate, repeat, repeatKeyed } from './repeaters.ts';
+
+/**
+ * State Tether keeps on elements, as `data-tether-*` attributes whatever the prefix: sites style and test against
+ * these names, so they stay fixed where the `tether-*` markup attributes follow `prefix`.
+ */
+const SEEN = 'data-tether-seen';
+const SHOWN = 'data-tether-shown';
+const PREVIOUS_DISPLAY = 'data-tether-prev-display';
+
+/** Async renders change the page height in bursts; one notification per burst. */
+const LAYOUT_DEBOUNCE_MS = 120;
+
+/**
+ * The product page of a product (`productPath`).
+ *
+ * @returns `null` without the handle or id the path needs.
+ */
+export function productUrl(handle: string | null | undefined, id?: string | null): string | null {
+  return productUrlFor(cfg.productPath || '/product', handle, id);
+}
+
+/** `Intl` throws a RangeError for a locale or currency it doesn't know; the caller then shows a plain fallback. */
+function formatOr<T>(format: () => T, fallback: T): T {
+  try {
+    return format();
+  } catch (error) {
+    if (error instanceof RangeError) return fallback;
+    throw error;
+  }
+}
+
+/**
+ * `30` → `30%` (en, nl) or `30 %` (de, fr), in the configured locale.
+ *
+ * @returns `''` for no or a zero percentage.
+ */
+export function formatPercent(percentage: number | null | undefined, locale: string | undefined = cfg.locale): string {
+  if (!percentage) return '';
+  const format = () =>
+    new Intl.NumberFormat(locale || undefined, { style: 'percent', maximumFractionDigits: 0 }).format(percentage / 100);
+  return formatOr(format, `${percentage}%`);
+}
+
+/** Money in the configured locale, through the site's `formatMoney` when it has one. */
+export function formatMoney(money: Money | null | undefined): string {
+  if (!money) return '';
+  if (cfg.formatMoney) return cfg.formatMoney(money, cfg.locale);
+  return formatMoneyIn(money, cfg.locale);
+}
+
+/** @returns The date in the configured locale, `''` without one. */
+export function formatDate(iso: string | null | undefined): string {
+  if (!iso) return '';
+  return formatOr(() => new Date(iso).toLocaleDateString(cfg.locale || undefined), '');
+}
+
+/**
+ * Writes HTML from the Shopify admin (product and collection descriptions) into `el`, with script removed
+ * (`store-html.ts`). Everything else from Shopify is written as text (`setText`).
+ */
+export function setStoreHtml(el: Element, html: string | null | undefined): void {
+  el.replaceChildren(storeHtmlFragment(html, el.ownerDocument, cfg.embedOrigins));
+}
+
+const isTextField = (el: Element): el is HTMLInputElement | HTMLTextAreaElement =>
+  el.tagName === 'INPUT' || el.tagName === 'TEXTAREA';
+
+const isInput = (el: Element): el is HTMLInputElement => el.tagName === 'INPUT';
+
+/**
+ * Sets the text of `el`, or its value when it is a form field.
+ *
+ * @param value `null` and `undefined` clear it.
+ */
+export function setText(el: Element, value: string | number | boolean | null | undefined): void {
+  const text = value == null ? '' : String(value);
+  if (isTextField(el)) el.value = text;
+  else el.textContent = text;
+}
+
+const readText = (el: Element) => (isTextField(el) ? el.value : el.textContent);
+
+/** `setText` that hands a change after the first render to `onValueChange`, for scramble and roll effects. */
+export function setTextTracked(el: HTMLElement, value: string | number | boolean | null | undefined): void {
+  const before = readText(el);
+  setText(el, value);
+  if (before !== readText(el) && el.hasAttribute(SEEN) && cfg.onValueChange) {
+    try {
+      cfg.onValueChange(el, before);
+    } catch (error) {
+      reportError(error, 'onValueChange');
+    }
+  }
+  el.setAttribute(SEEN, '1');
+}
+
+/**
+ * Shows an element hidden before the script ran (a class, an inline `display: none`, a `hidden` attribute), as
+ * `block` or the value of `tether-display`.
+ */
+function reveal(el: HTMLElement): void {
+  if (el.hasAttribute(SHOWN)) return;
+  el.setAttribute(SHOWN, '');
+  el.removeAttribute('hidden');
+  const previous = el.getAttribute(PREVIOUS_DISPLAY);
+  if (previous !== null) {
+    el.style.display = previous;
+    el.removeAttribute(PREVIOUS_DISPLAY);
+  } else if (el.style.display === 'none') {
+    el.style.display = '';
+  }
+  if (typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
+    el.style.display = el.getAttribute(attr('display')) || 'block';
+  }
+}
+
+/** Shows or hides `el`, restoring its own display value when shown again. */
+export function show(el: HTMLElement, visible: boolean): void {
+  if (visible) {
+    reveal(el);
+    return;
+  }
+  el.removeAttribute(SHOWN);
+  // The display value to restore is a real one, never 'none'.
+  if (!el.hasAttribute(PREVIOUS_DISPLAY) && el.style.display !== 'none') {
+    el.setAttribute(PREVIOUS_DISPLAY, el.style.display);
+  }
+  el.style.display = 'none';
+}
+
+/** Marks an option button or input as chosen: `is-selected`, `aria-pressed`, and its own or inner radio/checkbox. */
+export function setSelected(el: Element, selected: boolean): void {
+  el.classList.toggle('is-selected', selected);
+  el.setAttribute('aria-pressed', selected ? 'true' : 'false');
+  if (isInput(el) && (el.type === 'radio' || el.type === 'checkbox')) el.checked = selected;
+  const input = el.querySelector('input[type="radio"],input[type="checkbox"]');
+  if (input && isInput(input)) input.checked = selected;
+}
+
+let layoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * A global the page's own scripts set on `window`: `TETHER_CONFIG`, the site's config, `TETHER_INTEGRATION`, set by a
+ * framework integration (Astro) that starts Tether itself, and GSAP's `ScrollTrigger`. Another script wrote it, so it
+ * is read as unknown and checked where it is used.
+ */
+export const pageGlobal = (name: 'TETHER_CONFIG' | 'TETHER_INTEGRATION' | 'ScrollTrigger'): unknown =>
+  Reflect.get(window, name);
+
+/** Refreshes GSAP's ScrollTrigger, when the site has it: it measures positions that a height change makes stale. */
+function refreshScrollTrigger(): void {
+  // ScrollTrigger is a class, and `refresh` a static method of it.
+  const scrollTrigger = pageGlobal('ScrollTrigger');
+  if (typeof scrollTrigger !== 'function') return;
+  const refresh: unknown = Reflect.get(scrollTrigger, 'refresh');
+  if (typeof refresh === 'function') Reflect.apply(refresh, scrollTrigger, []);
+}
+
+/**
+ * Async renders change the page height after the site's page-transition hooks ran. After a burst of them this calls
+ * `onLayoutChange` (else refreshes ScrollTrigger) and emits `tether:layout-changed`, also when either of those throws.
+ */
+export function notifyLayoutChanged(reason: string): void {
+  clearTimeout(layoutTimer);
+  layoutTimer = setTimeout(() => {
+    try {
+      if (cfg.onLayoutChange) cfg.onLayoutChange(reason);
+      else refreshScrollTrigger();
+    } catch (error) {
+      reportError(error, 'layout-changed');
+    }
+    emit('layout-changed', { reason });
+  }, LAYOUT_DEBOUNCE_MS);
+}
+
+/** Notifies a layout change (`<reason>:images`) once every image in `root` that is still loading has loaded or failed. */
+export function watchImages(root: ParentNode, reason: string): void {
+  const loading = [...root.querySelectorAll('img')].filter((img) => !img.complete);
+  let left = loading.length;
+  const done = () => {
+    left -= 1;
+    if (left === 0) notifyLayoutChanged(`${reason}:images`);
+  };
+  loading.forEach((img) => {
+    img.addEventListener('load', done, { once: true });
+    img.addEventListener('error', done, { once: true });
+  });
+}
+
+/**
+ * Runs `task` with `aria-busy` on `el`; does nothing while `el` is already busy.
+ *
+ * @returns The task's result, `undefined` when it didn't run.
+ */
+export function busy<T>(el: Element, task: () => T | Promise<T>): Promise<T | undefined> {
+  if (el.getAttribute('aria-busy') === 'true') return Promise.resolve(undefined);
+  el.setAttribute('aria-busy', 'true');
+  return Promise.resolve()
+    .then(task)
+    .finally(() => {
+      el.removeAttribute('aria-busy');
+    });
+}
+
+/** @returns The attribute's JSON, `null` when it is missing or not JSON (with a warning). */
+export function parseJSONAttr(el: Element | null | undefined, name: string): unknown {
+  const raw = el ? get(el, name) : null;
+  if (!raw) return null;
+  try {
+    const json: unknown = JSON.parse(raw);
+    return json;
+  } catch {
+    warn(`invalid JSON in ${attr(name)}`, el);
+    return null;
+  }
+}
+
+export type AttributeValue = string | number | boolean | null | undefined;
+
+/** @returns A JSON value as attribute text: `''` for none, an object or array as its JSON. */
+function attributeText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  // What else parsed JSON holds: objects and arrays.
+  return JSON.stringify(value);
+}
+
+/**
+ * `tether-line-attributes`, JSON the site writes: `{ a: 1 }` or `[{ key, value }]`. An array entry that isn't an
+ * object is skipped.
+ */
+export function attributesFromJson(json: unknown): { key: string; value: string }[] {
+  if (Array.isArray(json)) {
+    const entries: unknown[] = json;
+    return entries
+      .filter(isRecord)
+      .map((entry) => ({ key: attributeText(entry['key']), value: attributeText(entry['value']) }));
+  }
+  if (!isRecord(json)) return [];
+  return Object.entries(json).map(([key, value]) => ({ key, value: attributeText(value) }));
+}
+
+/** `{ a: 1 }` or `[{ key, value }]` → `[{ key, value }]` as Shopify wants cart and line attributes. */
+export function toAttributes(
+  attributes: Record<string, AttributeValue> | { key: string | number; value?: AttributeValue }[] | null | undefined,
+): { key: string; value: string }[] {
+  if (!attributes) return [];
+  if (Array.isArray(attributes)) {
+    return attributes.map((attribute) => ({ key: String(attribute.key), value: String(attribute.value ?? '') }));
+  }
+  return Object.entries(attributes).map(([key, value]) => ({ key, value: String(value ?? '') }));
+}

package/src/extras.ts

@@ -0,0 +1,136 @@
+/**
+ * Optional part with features that load when first needed: bundles (on the first "add set" click), tab sync (on the
+ * first change in another tab) and shareable variant links (on the first variant change, with `variantUrl` or
+ * `tether-variant-url`).
+ */
+import { cfg, warn, reportError } from './config.ts';
+import { sel, get, has, qsa, emit, parseJSONAttr, attributesFromJson } from './dom.ts';
+import { scopes } from './product.ts';
+import { Cart } from './cart.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import type { ShopifyCart } from './cart/store.ts';
+
+interface StoredMarket {
+  country: string;
+  language: string | null;
+  locale: string | undefined;
+}
+
+type SetCountry = (
+  country: string,
+  options: { language: string | null; locale: string | undefined; remember: boolean },
+) => Promise<unknown>;
+
+/** @param name The group's `tether-group` value. */
+function groupAttributes(group: Element, name: string | null) {
+  const extra = attributesFromJson(parseJSONAttr(group, 'line-attributes'));
+  return name ? [{ key: '_group', value: name }, ...extra] : extra;
+}
+
+/**
+ * `[tether-group]` with `[tether-group-add]`: adds every product scope inside the group in one request, for bundles,
+ * build-a-box and "complete the set". The lines get the attribute `_group` and the group's `tether-line-attributes`.
+ *
+ * @returns The cart, `null` with nothing to add or after a reported failure.
+ */
+export async function addGroup(button: Element): Promise<ShopifyCart | null> {
+  const group = button.closest(sel('group'));
+  if (!group) return null;
+  const name = get(group, 'group');
+  const attributes = groupAttributes(group, name);
+  const lines = qsa(group, sel('product')).flatMap((el) => {
+    const scope = scopes.get(el);
+    if (!scope?.variant?.availableForSale || scope.quantity <= 0) return [];
+    const line = scope.getLine();
+    return line ? [{ ...line, attributes: [...(line.attributes ?? []), ...attributes] }] : [];
+  });
+  if (!lines.length) {
+    warn('group-add: nothing selected');
+    return null;
+  }
+  try {
+    const cart = await Cart.add(lines);
+    emit('group-added', { group: name, lines }, group);
+    return cart;
+  } catch (error) {
+    reportError(error, 'group add');
+    return null;
+  }
+}
+
+/** Another tab writes the market as JSON; a value that isn't (written by something else under the key) is skipped. */
+function parseStoredMarket(text: string): StoredMarket | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isRecord(value)) return null;
+  const { country, language, locale } = value;
+  if (typeof country !== 'string' || !country) return null;
+  return {
+    country,
+    language: typeof language === 'string' ? language : null,
+    locale: typeof locale === 'string' ? locale : undefined,
+  };
+}
+
+/** Another tab changed the cart (it is loaded again here) or the visitor's market (this tab follows it). */
+export function onStorage(event: StorageEvent): void {
+  if (event.key === cfg.storageKey || event.key === `${cfg.storageKey}:seen`) {
+    Cart.init().catch((error: unknown) => {
+      reportError(error, 'cart from another tab');
+    });
+    return;
+  }
+  if (event.key !== `${cfg.prefix}:market:${cfg.domain}` || !event.newValue) return;
+  const market = parseStoredMarket(event.newValue);
+  // The core's `setCountry` takes the `null` language and `undefined` locale stored here, which the public type of
+  // `window.Tether` leaves out.
+  const tether = Reflect.get(window, 'Tether') as { setCountry: SetCountry } | undefined;
+  if (!market || !tether) return;
+  const options = { language: market.language, locale: market.locale, remember: false };
+  tether.setCountry(market.country, options).catch((error: unknown) => {
+    reportError(error, 'market from another tab');
+  });
+}
+
+/** Scope root → its last variant and plan, so the first render doesn't write. */
+const urlKeys = new WeakMap<Element, string>();
+
+const numericId = (gid: string) => gid.split('/').pop() ?? gid;
+
+/**
+ * Safari throws a SecurityError past 100 history changes in 10 seconds; the address then keeps the previous choice
+ * until the next one.
+ */
+function replaceUrlIfAllowed(url: URL) {
+  try {
+    window.history.replaceState(window.history.state, '', url);
+  } catch {
+    // Too many changes in a row: see the function's comment.
+  }
+}
+
+/**
+ * `?variant=` (and `selling_plan=`) follow the visitor's choice.
+ *
+ * @param root The product scope's root.
+ */
+export function writeVariantUrl(
+  root: Element,
+  { variant, sellingPlanId }: { variant: { id: string }; sellingPlanId: string | null | undefined },
+): void {
+  const key = `${variant.id}|${sellingPlanId ?? ''}`;
+  const before = urlKeys.get(root);
+  urlKeys.set(root, key);
+  if (!before || before === key) return;
+  const isMainProduct = cfg.variantUrl && document.querySelector(sel('product')) === root;
+  if (!has(root, 'variant-url') && !isMainProduct) return;
+  const url = new URL(window.location.href);
+  url.searchParams.set('variant', numericId(variant.id));
+  if (sellingPlanId) url.searchParams.set('selling_plan', numericId(sellingPlanId));
+  else url.searchParams.delete('selling_plan');
+  replaceUrlIfAllowed(url);
+}