@luigisbox/luma 0.1.0 → 0.2.0

package/src/analytics/setup.ts

@@ -0,0 +1,41 @@
+// The page's analytics state: the global config, what the integration's
+// `_analytics.ts` reads for every event (user.identify), what only the entry
+// knows (env), and the moment the page is shown (a prerendered page:
+// once activated), when chains start to listen. Every other module reads it
+// here; none runs anything at its top level, so what a setup does not import
+// is left out of the build.
+
+import { reportError } from '../core/health';
+import type { GlobalConfigType } from '../types';
+
+export const state: { g: GlobalConfigType | null } = { g: null };
+/** Read on every event (./user.ts). */
+export const stamps: { user: (() => string | number | null | undefined) | null } = { user: null };
+
+/** A hook of the integration's: its value, or null when it threw (reported). */
+export const call = <T>(f: () => T, where: string): T | null => {
+  try {
+    return f() ?? null;
+  } catch (e) {
+    reportError(where, e);
+    return null;
+  }
+};
+
+/** What only the entry knows: which of the site's services Luma runs here, URL changes, one listing visit. */
+export const env: {
+  owns: (surface: string) => boolean;
+  onUrlChange: (l: (u: URL) => void) => void;
+  visit: (u: URL) => string | null;
+  /** This page's dataLayer pushes the entry kept already (left, then restored from the back/forward cache): not read again. */
+  kept: () => number;
+} = { owns: () => false, onUrlChange: () => {}, visit: () => null, kept: () => 0 };
+
+const waiting: (() => void)[] = [];
+let shown = false;
+/** Now if the page is shown, else once it is (a chain registered as the setup runs listens then). */
+export const whenShown = (f: () => void) => (shown ? f() : void waiting.push(f));
+export const pageShown = () => {
+  shown = true;
+  for (const f of waiting.splice(0)) f();
+};

package/src/analytics/start.ts

@@ -0,0 +1,53 @@
+// Analytics on a page (lbx-analytics: the entry loads it once the page has
+// loaded, or with the first widget, where the integration has an
+// `_analytics.ts`; README "Analytics"). The setup is in this chunk: its chains
+// (./collect.ts, ./triggers.ts) register as it runs, and what it does not
+// import is not built in. Nothing is sent that a chain does not say.
+//
+// To the Luigi's Box AI events API (POST /analytics/v1/events, ./outbox.ts):
+// `pv`, `interaction` (click, add_to_cart), `transaction`, and `list` for a
+// service of the site's own (ours the API records itself). Never anything
+// speculative: a prerendered page counts and sends once shown.
+
+import { reportError } from '../core/health';
+import type { LumaConfigType } from '../types';
+import { flush } from './outbox';
+import { env, pageShown, state } from './setup';
+
+export interface StartOptions {
+  config: LumaConfigType;
+  /** The integration's `_analytics.ts` files (lazy; in this chunk), `_global`'s first. */
+  files: Record<string, () => Promise<any>>;
+  /** Whether Luma runs this service of the site's on this page (`search`, `autocomplete`, `recommender:<name>`). */
+  owns: (surface: string) => boolean;
+  /** One listing visit (a category, a query) is one page, whatever its filters write. */
+  visit: (u: URL) => string | null;
+  onUrlChange: (l: (u: URL) => void) => void;
+  /** This page's dataLayer pushes the entry kept for the next page already (core/kept.ts). */
+  kept: () => number;
+}
+
+let started = false;
+/** The page's analytics (the entry, once per page). */
+export const start = async (o: StartOptions) => {
+  if (started) return;
+  started = true;
+  state.g = o.config._global;
+  env.owns = o.owns;
+  env.visit = o.visit;
+  env.onUrlChange = o.onUrlChange;
+  env.kept = o.kept;
+  // The setup (`_global` first). Its chains register as it runs.
+  for (const [p, f] of Object.entries(o.files).sort(([a], [b]) => (a.includes('/_global/') ? -1 : b.includes('/_global/') ? 1 : 0)))
+    try {
+      await f();
+    } catch (e) {
+      reportError(`analytics ${p}`, e);
+    }
+  const shown = () => {
+    pageShown();
+    void flush();
+  };
+  if ((document as any).prerendering) document.addEventListener('prerenderingchange', shown, { once: true });
+  else shown();
+};

package/src/analytics/triggers.ts

@@ -0,0 +1,239 @@
+// Triggers of the builder (./chain.ts): when a chain's `.read()` runs, with
+// what. Luma's own (lumaPages, lumaClicks, lumaCarts) and the site's (dl,
+// domClick, urlChange, manual, mutationOf, xhrMatching). Each is its own export: a setup brings only the ones it imports (the
+// XMLHttpRequest and fetch wrapper, the mutation observer, the click
+// listeners only where a chain uses them).
+
+import { reportError } from '../core/health';
+import { session } from '../core/storage';
+import { TILES, type TileEvent } from '../core/tiles';
+import type { Trigger } from './chain';
+import { onDl } from './datalayer';
+import { onPage, type Page } from './page';
+import { env } from './setup';
+
+export interface DlContext {
+  event: string;
+  /** The same as `event`. */
+  eventType: string;
+  /** The entry as pushed (gtag's: `{ event, ...params }`). */
+  data: Record<string, any>;
+  /** GA4's ecommerce object (gtag's: its parameters), or null. */
+  ecommerce: Record<string, any> | null;
+  /** A push of a page left before analytics ran there: that page, and when (the event is sent as of them). */
+  url?: string;
+  at?: number;
+}
+/** The site's dataLayer event `name` (object or gtag form), the ones pushed before Luma loaded too. */
+export const dl = (name: string): Trigger<DlContext> => ({
+  key: `dl:${name}`,
+  sub: (h) => onDl(name, (e) => h({ ...e, eventType: e.event })),
+});
+
+export interface DomClickContext {
+  /** The element matching `selector` (the click's target or an ancestor). */
+  element: Element;
+  event: MouseEvent;
+}
+/** A click (or a middle click) on an element of the site's matching `selector`: never on ours (`lumaClicks()`). */
+export const domClick = (selector: string): Trigger<DomClickContext> => ({
+  key: `domClick:${selector}`,
+  sub: (h) => {
+    const on = (e: Event) => {
+      const me = e as MouseEvent;
+      if (e.type === 'auxclick' && me.button !== 1) return;
+      const t = e.composedPath()[0];
+      const el = t instanceof Element ? t.closest(selector) : null;
+      if (el && !el.closest('[data-lbx]')) h({ element: el, event: me });
+    };
+    addEventListener('click', on, true);
+    addEventListener('auxclick', on, true);
+  },
+});
+
+export interface UrlChangeContext {
+  url: string;
+  previousUrl: string;
+}
+/** The page's URL changed (an SPA navigation, ours too). */
+export const urlChange = (): Trigger<UrlChangeContext> => ({
+  key: 'url',
+  sub: (h) => {
+    let previousUrl = location.href;
+    env.onUrlChange((u) => {
+      h({ url: u.href, previousUrl });
+      previousUrl = u.href;
+    });
+  },
+});
+
+/**
+ * Luma's pages, as analytics counts them (./page.ts): the first once shown, an
+ * SPA's next page, a back/forward cache restore; not our own filters or sort.
+ * The context is the page, `{ url, referrer }`: `collect.pageView.on(lumaPages())`.
+ */
+export const lumaPages = (): Trigger<Page> => ({ key: 'pages', sub: (h) => onPage(h) });
+
+/**
+ * Luma's own tiles (core/tiles.ts): a product click on them (`lumaClicks()`,
+ * the autocomplete's picks too), an add-to-cart by their `[data-lbx-cart]`
+ * (`lumaCarts()`). The context is a TileEvent, `{ reference, result, index,
+ * list, count?, price?, url, at }`, read by fromLuma.click / .addToCart.
+ * Every one, whenever it happened: queued before analytics listened (on this
+ * page or the last), claimed now, sent as of its page and time.
+ */
+const tiles = (kind: TileEvent['kind']): Trigger<TileEvent> => ({
+  key: `tiles:${kind}`,
+  sub: (h) => {
+    // Claimed from the queue (core/tiles.ts): each once, whenever analytics listens.
+    const claim = (id: string) => {
+      const q = session.get<TileEvent[]>(TILES) ?? [];
+      const i = q.findIndex((x) => x.id === id);
+      if (i < 0) return false;
+      q.splice(i, 1);
+      session.set(TILES, q.length ? q : undefined);
+      return true;
+    };
+    for (const d of session.get<TileEvent[]>(TILES) ?? []) if (d.kind === kind && claim(d.id)) h(d);
+    document.addEventListener('lbx:tile', (e) => {
+      const d = (e as CustomEvent<TileEvent>).detail;
+      if (d.kind === kind && claim(d.id)) h(d);
+    });
+  },
+});
+export const lumaClicks = () => tiles('click');
+export const lumaCarts = () => tiles('add_to_cart');
+
+export interface MutationContext {
+  /** The element matching the selector: added, or with nodes added inside it. */
+  element: Element;
+}
+/**
+ * The site's element `selector`, once in the page and each time it (or what
+ * is inside it) is added: a service of theirs that renders its results with
+ * no dataLayer event. Read when the browser is idle (the render has settled);
+ * never ours. `root`: only inside the first element it matches (default the document).
+ */
+export const mutationOf = (selector: string, opts?: { root?: string }): Trigger<MutationContext> => ({
+  key: `mutation:${selector}:${opts?.root ?? ''}`,
+  sub: (h) => {
+    const due = new Set<Element>();
+    let asked = false;
+    const fire = () => {
+      asked = false;
+      const els = [...due];
+      due.clear();
+      for (const element of els) if (element.isConnected) h({ element });
+    };
+    const add = (el: Element | null) => {
+      if (!el || el.closest('[data-lbx]')) return;
+      due.add(el);
+      if (asked) return;
+      asked = true;
+      if (typeof requestIdleCallback === 'function') requestIdleCallback(fire, { timeout: 1000 });
+      else setTimeout(fire, 50);
+    };
+    const look = (n: Node) => {
+      if (!(n instanceof Element)) return;
+      if (n.matches(selector)) add(n);
+      n.querySelectorAll(selector).forEach(add);
+    };
+    const root = (opts?.root && document.querySelector(opts.root)) || document.documentElement;
+    new MutationObserver((ms) => {
+      for (const m of ms) {
+        if (!m.addedNodes.length) continue;
+        add(m.target instanceof Element ? m.target.closest(selector) : null);
+        m.addedNodes.forEach(look);
+      }
+    }).observe(root, { childList: true, subtree: true });
+    root.querySelectorAll(selector).forEach(add);
+  },
+});
+
+export interface XhrContext {
+  url: string;
+  method: string;
+  /** Its JSON body (the text, where it is not JSON). */
+  response: any;
+}
+type XhrTest = (r: { url: string; method: string }) => boolean;
+const xhrs: { test: XhrTest; h: (c: XhrContext) => void }[] = [];
+const matching = (url: string, method: string) =>
+  xhrs.filter((x) => {
+    try {
+      return x.test({ url, method });
+    } catch (e) {
+      reportError('analytics xhrMatching', e);
+      return false;
+    }
+  });
+const answered = (hs: typeof xhrs, url: string, method: string, text: string) => {
+  let response: any = text;
+  try {
+    response = JSON.parse(text);
+  } catch {}
+  for (const x of hs) x.h({ url, method, response });
+};
+let wrapped = false;
+/** XMLHttpRequest and fetch, watched once: only a response a trigger asks for is read. */
+const wrapXhr = () => {
+  if (wrapped) return;
+  wrapped = true;
+  const open = XMLHttpRequest.prototype.open;
+  XMLHttpRequest.prototype.open = function (this: XMLHttpRequest, method: string, url: string | URL, ...rest: unknown[]) {
+    const u = new URL(url, location.href).href;
+    const m = method.toUpperCase();
+    this.addEventListener('load', () => {
+      const hs = this.status >= 200 && this.status < 300 ? matching(u, m) : [];
+      if (!hs.length) return;
+      const t = this.responseType === '' || this.responseType === 'text' ? this.responseText : this.responseType === 'json' ? JSON.stringify(this.response) : null;
+      if (t != null) answered(hs, u, m, t);
+    });
+    return (open as (...a: unknown[]) => void).call(this, method, url, ...rest);
+  } as typeof open;
+  const f = window.fetch;
+  window.fetch = function (input: RequestInfo | URL, init?: RequestInit) {
+    const p = f.call(window, input, init);
+    const u = new URL(input instanceof Request ? input.url : String(input), location.href).href;
+    const m = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    const hs = matching(u, m);
+    if (hs.length)
+      p.then((r) => (r.ok ? r.clone().text() : null))
+        .then((t) => t != null && answered(hs, u, m, t))
+        .catch(() => {});
+    return p;
+  };
+};
+/**
+ * A response to one of the site's own requests (XMLHttpRequest or fetch)
+ * that `test` matches (`url` absolute, `method` upper case): a service of
+ * theirs that asks its own API (their suggestions). Requests made before the
+ * page loaded are not seen.
+ */
+export const xhrMatching = (test: XhrTest): Trigger<XhrContext> => ({
+  key: 'xhr',
+  sub: (h) => {
+    wrapXhr();
+    xhrs.push({ test, h });
+  },
+});
+
+export interface ManualContext<D = any> {
+  data: D;
+}
+/** A trigger the integration fires itself: `const { trigger, fire } = manual(); …on(trigger)…; fire(data)`. */
+export const manual = <D = any>(): { trigger: Trigger<ManualContext<D>>; fire(data?: D): void } => {
+  const hs: ((c: ManualContext<D>) => void)[] = [];
+  return {
+    trigger: { key: 'manual', sub: (h) => void hs.push(h) },
+    fire: (data = {} as D) =>
+      hs.forEach((h) => {
+        try {
+          h({ data });
+        } catch (e) {
+          reportError('analytics manual', e);
+        }
+      }),
+  };
+};
+

package/src/analytics/user.ts

@@ -0,0 +1,12 @@
+// user.identify(fn): the signed-in shopper's own id, read on every event and
+// sent as `user_id` (omitted when null).
+//
+//   user.identify(() => window.shop?.customerId ?? null);
+
+import { stamps } from './setup';
+
+export const user = {
+  identify(fn: () => string | number | null | undefined) {
+    stamps.user = fn;
+  },
+};

package/src/analytics/wire.ts

@@ -0,0 +1,67 @@
+// What analytics events are made of, without the page: object references,
+// the site's dataLayer entries, the page a URL is (one pageview per page, not per filter). Pure: unit-tested
+// (test/unit/analytics-wire.test.ts).
+//
+// The wire format is the Luigi's Box AI events API
+// (docs.luigisbox.ai/analytics/event-reference): `interaction` (click,
+// add_to_cart), `transaction`, and, as the legacy Luma sends them, `pv` and
+// `list` (an original service's results: ours the API records itself).
+
+import { P, TRACKING, withoutTracking } from '../core/routes';
+
+/**
+ * An object reference, `<type>/<field>:<value>`
+ * (docs.luigisbox.ai/analytics/references). An `@id` value carries its type
+ * ("product/123"): a bare one is prefixed.
+ */
+export const ref = (type: string, field: string, value: unknown) => {
+  const v = String(value);
+  return `${type}/${field}:${field === '@id' && !v.startsWith(`${type}/`) ? `${type}/${v}` : v}`;
+};
+
+/** A reference as the API accepts it: three non-empty parts, no `/` or `:` in the first two. */
+export const isRef = (r: unknown): r is string => typeof r === 'string' && /^[^/:]+\/[^/:]+:.+/.test(r);
+
+/** An event of the site's dataLayer, read (object form or gtag's). */
+export interface DlEntry {
+  event: string;
+  data: Record<string, any>;
+  ecommerce: Record<string, any> | null;
+  /** A push of a page left before analytics ran there: that page, and when it was left. */
+  url?: string;
+  at?: number;
+}
+
+/** gtag's `arguments` (or one kept by a page left before analytics ran: `{ 0: 'event', 1: … }`). */
+const isArgs = (x: any): x is ArrayLike<any> => !!x && typeof x === 'object' && typeof x[0] === 'string';
+
+/**
+ * `{ event: 'purchase', ecommerce: {…} }` (GTM) or `gtag('event', 'purchase',
+ * {…})` (an `arguments` object: gtag's parameters are the ecommerce data).
+ */
+export const readDl = (x: any): DlEntry | null => {
+  if (isArgs(x)) {
+    if (x[0] === 'event' && typeof x[1] === 'string') {
+      const params = x[2] && typeof x[2] === 'object' ? x[2] : {};
+      return { event: x[1], data: { event: x[1], ...params }, ecommerce: params };
+    }
+    return null;
+  }
+  if (x && typeof x === 'object' && typeof x.event === 'string') return { event: x.event, data: x, ecommerce: x.ecommerce && typeof x.ecommerce === 'object' ? x.ecommerce : null };
+  return null;
+};
+
+const IGNORE = new RegExp(`${TRACKING}|^${P.replace('.', '\\.')}`);
+/**
+ * The page a URL shows, for pageviews: without tracking params, the hash and
+ * our own `lbx.*` (a filter, a sort on our listing is the same page). A
+ * listing's own visit (its category, its query: the caller's `visit`) is one
+ * page whatever its filters write into the site's params.
+ */
+export const pageOf = (href: string, visit?: (u: URL) => string | null) => {
+  const u = withoutTracking(href, IGNORE);
+  return visit?.(u) ?? u.href;
+};
+
+/** The URL sent with events: without tracking params (gclid, utm_…) and the hash. */
+export const eventUrl = (href: string) => withoutTracking(href).href;

package/src/api/token.ts

@@ -250,8 +250,9 @@ const tokens = (g: GlobalConfigType, origin?: string): Tokens => {
           pow_nonce: nonce,
           pow_solution: solution,
           channel_id: g.channelId,
-          // One token for discovery and analytics events.
-          audience: [`${API}/discovery`, `${API}/events`],
+          // One token for discovery and analytics events. Any other audience mints a token without
+          // permissions (docs.luigisbox.ai/authentication/browser-tokens): `/events` did, every event a 403.
+          audience: [`${API}/discovery`, `${API}/analytics`],
         }),
       },
       TIMEOUT_MS,

package/src/core/integration.ts

@@ -42,6 +42,12 @@ export interface IntegrationFiles {
    * lazy always (an eager one would be in the entry, where `_init.ts` is).
    */
   widgetInits?: Lazy<any>;
+  /**
+   * `_analytics.ts`, lazy (`import.meta.glob('./*\/_analytics.ts', { import: 'default' })`):
+   * the analytics setup (chains of `@/analytics`), run by the analytics chunk
+   * (it is in it) once the page has loaded.
+   */
+  analytics?: Lazy<any>;
 }
 
 /** A folder's style-host.css; a category page without its own uses the search page's. */

package/src/core/kept.ts

@@ -0,0 +1,25 @@
+// The site's dataLayer pushes of a page left before analytics ran on it (a
+// purchase on a thank-you page closed at once): kept for the next page's
+// analytics, which replays them as of this page and time (src/analytics/datalayer.ts).
+// In the entry: it runs on `pagehide`, when no chunk can load any more.
+
+import { session } from './storage';
+
+export const KEPT = 'lbx:dl';
+
+/** Keeps the pushes of the dataLayer `name` from index `from` on (the last 30, of the last 5 pages); the index kept up to. */
+export const keepDl = (name: string, from: number) => {
+  const dl = (window as any)[name];
+  if (!(dl?.length > from)) return from;
+  // Each on its own: one that does not serialize (a GTM click's element, cyclic) is left out, not the rest.
+  // gtag's `arguments` become `{ 0: 'event', 1: … }` (readDl reads them); functions (GTM's callbacks) are dropped.
+  const e = dl.slice(from - dl.length).slice(-30).flatMap((x: unknown) => {
+    try {
+      return [JSON.parse(JSON.stringify(x))];
+    } catch {
+      return [];
+    }
+  });
+  session.set(KEPT, [...(session.get<unknown[]>(KEPT) ?? []), { u: location.href, t: Date.now(), e }].slice(-5));
+  return dl.length;
+};

package/src/core/tiles.ts

@@ -0,0 +1,137 @@
+// Clicks and add-to-carts on our own tiles, seen by the framework: no template
+// says anything about them. Every widget that renders products calls
+// `watch()` on its root once (listings, recommenders, the popup) or `picked()`
+// (the autocomplete's own navigation); the rest follows from the markup:
+//
+// - a product click is a click (any button: a middle click, a modifier opens
+//   a tab, still a click) on a link to a result's URL inside a list of ours
+//   (`[data-lbx-list]`); the result is the one with that URL (the tile's own
+//   when two share it), else, where the integration's link is not `r.c.url`,
+//   the tile's at its position (tiles map to hits by position, as the view
+//   transitions and focus code assume). Other links in a tile (wishlist,
+//   compare) are not product clicks.
+// - an add-to-cart is a click on `[data-lbx-cart]` in a tile (its value: the
+//   quantity, default 1): `_global.addToCart(result, { count, el, event })`
+//   puts it in the site's cart. Without that hook nothing happens (and it
+//   says so).
+//
+// Each is announced as an `lbx:tile` event on document (TileEvent): analytics
+// listens only where the integration's _analytics.ts asks (its `lumaClicks()`,
+// `lumaCarts()` triggers), so a widget brings no analytics code. Analytics may
+// not be listening yet (its chunk and the setup come after the widget's), or
+// the click may leave the page: so each is first queued in sessionStorage, in
+// the click's own task, where analytics claims it, on this page or the next.
+// Not where the integration has no analytics (`_global.analytics` false: the
+// entry sets it where there is no _analytics.ts).
+
+import { reportError } from './health';
+import { session } from './storage';
+import type { GlobalConfigType, Result } from '../types';
+
+/** `detail` of an `lbx:tile` event. */
+export interface TileEvent {
+  /** Its id in the queue. */
+  id: string;
+  kind: 'click' | 'add_to_cart';
+  /** `<type>/@id:<id>`: the result's reference. */
+  reference: string;
+  result: Result;
+  /** Its position in the list (0-based). */
+  index: number;
+  /** Our list: `lbx_search`, `lbx_plp`, `lbx_reco_<name>`, `lbx_autocomplete`. */
+  list: string;
+  count?: number;
+  price?: number;
+  /** The page it happened on, and when (ms epoch): what the event carries, sent later or not. */
+  url: string;
+  at: number;
+}
+export interface Watched {
+  list: string;
+  /** The results the list shows now, in tile order. */
+  results: () => readonly Result[];
+  global: GlobalConfigType;
+}
+
+/** The queue analytics claims from (src/analytics/triggers.ts). */
+export const TILES = 'lbx:tiles';
+const announce = (g: GlobalConfigType, e: Omit<TileEvent, 'id' | 'url' | 'at'>) => {
+  if (g.analytics === false) return;
+  const d = { ...e, id: crypto.randomUUID(), url: location.href, at: Date.now() };
+  session.set(TILES, [...(session.get<TileEvent[]>(TILES) ?? []), d].slice(-20));
+  try {
+    document.dispatchEvent(new CustomEvent('lbx:tile', { detail: d }));
+  } catch (err) {
+    reportError('tile event', err);
+  }
+};
+const reference = (r: Result) => `${r.type || 'product'}/@id:${r.id}`;
+
+/** A result clicked (a link to it, or our own navigation: the autocomplete). */
+export const picked = (r: Result, index: number, list: string, g: GlobalConfigType) => announce(g, { kind: 'click', reference: reference(r), result: r, index, list });
+
+const watched = new WeakSet<Element>();
+/** Product clicks and add-to-carts inside `root` (once per root). */
+export const watch = (root: Element, w: Watched) => {
+  if (watched.has(root)) return;
+  watched.add(root);
+  const on = (e: MouseEvent) => {
+    if (e.type === 'auxclick' && e.button !== 1) return;
+    try {
+      const t = e.target instanceof Element ? e.target : null;
+      const tile = t?.closest('[data-lbx-list] > *');
+      if (!tile || !root.contains(tile)) return;
+      const results = w.results();
+      const tiles = [...tile.parentElement!.children];
+      const at = tiles.indexOf(tile);
+      const cart = t!.closest<HTMLElement>('[data-lbx-cart]');
+      if (cart && tile.contains(cart)) return void (e.type === 'click' && toCart(e, cart, tile, at, tiles.length, results, w));
+      const a = t!.closest<HTMLAnchorElement>('a[href]');
+      if (!a || !tile.contains(a)) return;
+      const r = resultOf(a, at, tiles.length, results);
+      if (r) picked(r.r, r.i, w.list, w.global);
+    } catch (err) {
+      reportError('tile click', err);
+    }
+  };
+  // Capture: before a handler of the tile (or the site's) stops it or navigates.
+  root.addEventListener('click', on as EventListener, true);
+  root.addEventListener('auxclick', on as EventListener, true);
+};
+
+const sameUrl = (r: Result, href: string) => {
+  try {
+    return !!r.c.url && new URL(r.c.url, location.href).href === href;
+  } catch {
+    return false;
+  }
+};
+
+/** The result a link in the tile at `at` leads to. */
+const resultOf = (a: HTMLAnchorElement, at: number, n: number, results: readonly Result[]) => {
+  const same = results.flatMap((r, i) => (sameUrl(r, a.href) ? [{ r, i }] : []));
+  if (same.length) return same.find((x) => x.i === at) ?? same[0];
+  // The integration's link is not r.c.url (its own params): the tile's, where tiles are the results.
+  if (n === results.length && results[at] && a.origin === location.origin && !a.matches('[data-remote], [data-method], [download]')) return { r: results[at], i: at };
+  return null;
+};
+
+const toCart = (e: MouseEvent, el: HTMLElement, tile: Element, at: number, n: number, results: readonly Result[], w: Watched) => {
+  // A cart button inside the tile's link must not follow it.
+  e.preventDefault();
+  e.stopPropagation();
+  const link = [...tile.querySelectorAll<HTMLAnchorElement>('a[href]')].map((a) => resultOf(a, at, n, results)).find(Boolean);
+  const hit = link ?? (n === results.length && results[at] ? { r: results[at], i: at } : null);
+  if (!hit) return reportError('add to cart', 'a [data-lbx-cart] in a tile whose result is unknown (its links lead to no result, and tiles are not the results)');
+  const hook = w.global.addToCart;
+  if (typeof hook !== 'function') return reportError('add to cart', '[data-lbx-cart] needs _global.addToCart (_init.ts or _global/_widget.ts) to put the product in the site\'s cart');
+  const count = Math.max(1, Math.round(Number(el.dataset.lbxCart) || 1));
+  const price = typeof hit.r.c.price === 'number' ? hit.r.c.price : undefined;
+  announce(w.global, { kind: 'add_to_cart', reference: reference(hit.r), result: hit.r, index: hit.i, list: w.list, count, ...(price !== undefined ? { price } : {}) });
+  try {
+    const p = hook(hit.r, { count, el, event: e });
+    if (p && typeof (p as Promise<unknown>).catch === 'function') (p as Promise<unknown>).catch((err) => reportError('addToCart', err));
+  } catch (err) {
+    reportError('addToCart', err);
+  }
+};