@luigisbox/luma 0.1.0 → 0.3.0

package/src/analytics/pageview.ts

@@ -0,0 +1,82 @@
+// collect.pageView: a `pv` event per page (./page.ts), with the page's object
+// when the chain reads one:
+//
+//   collect.pageView.on(lumaPages()).read(fromLuma.pageView);         // every page
+//   collect.pageView.on(lumaPages()).read(() => ref.product(window.sku)); // its reference, read at the page
+//   collect.pageView.on(dl('view_item')).timeout(1500).read(fromGa4.pageView);
+//                    // every page, its reference from a trigger, waited for (default 1000 ms, then without)
+//
+// One pageView chain per setup: a second one is an error, not a second pageview.
+
+import { reportError } from '../core/health';
+import { checked, type Read, type Trigger } from './chain';
+import { emit } from './outbox';
+import { onPage, type Page } from './page';
+import { whenShown } from './setup';
+import { isRef } from './wire';
+
+let chained = false;
+const send = (p: Page, reference?: string | null) => emit({ type: 'pv', url: p.url, ...(p.referrer ? { referrer: p.referrer } : {}), ...(isRef(reference) ? { reference } : {}) });
+
+export interface PageViewChain<C> {
+  /** lumaPages(): only the pages `f` says (the rest send none). Another trigger: only a context `f` says is the page's. */
+  when(f: (ctx: C) => boolean): PageViewChain<C>;
+  /** How long a page waits for its reference from the trigger (default 1000 ms), then goes without. Not for lumaPages(). */
+  timeout(ms: number): PageViewChain<C>;
+  /** The page's reference, read from the trigger's context (null: the page without one). */
+  read(r: Read<'pageView', C>): void;
+}
+
+export const pageView = {
+  on<C>(t: Trigger<C>): PageViewChain<C> {
+    let when: ((ctx: C) => boolean) | undefined;
+    let ms = 1000;
+    const b: PageViewChain<C> = {
+      when(f) {
+        when = f;
+        return b;
+      },
+      timeout(n) {
+        ms = n;
+        return b;
+      },
+      read(r) {
+        checked('pageView', r);
+        if (chained) throw new Error('analytics: one collect.pageView chain per setup');
+        chained = true;
+        const ref = (ctx: C) => {
+          try {
+            return r(ctx);
+          } catch (e) {
+            reportError('analytics pageView', e);
+            return null;
+          }
+        };
+        // lumaPages(): the page is the context, sent at once.
+        if (t.key === 'pages') return void t.sub((p) => (!when || when(p)) && send(p as Page, ref(p)));
+        /** The pageview waiting for its reference, if any. */
+        let waiting: ((r?: string | null) => void) | null = null;
+        onPage((p) => {
+          waiting?.(); // the previous page's, still waiting: sent without one
+          const timer = setTimeout(() => waiting?.(), ms);
+          waiting = (x) => {
+            clearTimeout(timer);
+            waiting = null;
+            send(p, x);
+          };
+        });
+        // After the first page waits (onPage's own whenShown runs first): what the
+        // trigger has already, the dataLayer's earlier pushes, completes it.
+        whenShown(() =>
+          t.sub((ctx) => {
+            // Not from another page (the last page's dataLayer, kept for us: `at`).
+            if (!waiting || typeof (ctx as { at?: unknown })?.at === 'number' || (when && !when(ctx))) return;
+            const x = ref(ctx);
+            if (x != null) waiting(x);
+          }),
+        );
+      },
+    };
+    return b;
+  },
+};

package/src/analytics/ref.ts

@@ -0,0 +1,19 @@
+// References (docs.luigisbox.ai/analytics/references), `<type>/<field>:<value>`:
+//
+//   ref.product('1234')           // product/@id:product/1234 (the type's field, default @id)
+//   ref.product('ean', '4006…')   // product/ean:4006…
+//   ref.product.by('id');         // the field ref.product(value) uses from now on
+//
+// Types: product, variant, category, brand.
+
+import { ref as reference } from './wire';
+
+const make = (type: string) => {
+  let field = '@id';
+  const f = (a: unknown, b?: unknown) => (b === undefined ? reference(type, field, a) : reference(type, String(a), b));
+  /** The catalog field `ref.<type>(value)` uses (default `@id`). */
+  f.by = (attribute: string) => void (field = attribute);
+  return f;
+};
+
+export const ref = { product: make('product'), variant: make('variant'), category: make('category'), brand: make('brand') };

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/entries.ts

@@ -16,10 +16,14 @@ export const isOwnEntry = (href: string) => own.has(canon(href));
 
 /**
  * A history entry of ours that only stands for something open (the
- * autocomplete's phone sheet): Back closes it, and no router of the host's
- * hears that popstate (the URL is the same). `back` returns true when the
- * popstate was that entry's (set by the widget that pushed it).
+ * autocomplete's phone sheet, the listing's staged filter drawer): Back
+ * closes it, and no router of the host's hears that popstate (the URL is the
+ * same). Each handler returns true when the popstate was its entry's (set by
+ * the widget that pushed it). Returns the removal.
  */
-let back: (() => boolean) | null = null;
-export const onOwnBack = (f: () => boolean) => void (back = f);
-export const ownBack = () => !!back?.();
+const backs = new Set<() => boolean>();
+export const onOwnBack = (f: () => boolean) => (backs.add(f), () => void backs.delete(f));
+export const ownBack = () => {
+  for (const f of backs) if (f()) return true;
+  return false;
+};

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/stash.ts

@@ -17,21 +17,41 @@ export const navigation = () => {
   }
 };
 
+/**
+ * A listing left for another page, loaded again within this long by a reload
+ * or a navigation from itself (a server round trip: a "compare" or "add to
+ * cart" link that redirects back to the page it came from): the listing as
+ * left, as for Back.
+ */
+export const ROUND_TRIP_MS = 60e3;
+
+/** The page loaded from itself: its referrer is this page (a redirect back keeps the referrer of the page that started it). */
+const fromItself = () => {
+  try {
+    return !!document.referrer && pageKey(document.referrer) === pageKey(location.href);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Which load a stash kind is for: a typed query's page by a navigation (or a
  * prerender of it, `prerender` from its start through its activation), a
- * listing left for a product by back/forward.
+ * listing left for a product by back/forward, or by a reload or a navigation
+ * from itself within ROUND_TRIP_MS of leaving (`at`: when it was written).
  */
-export const stashFits = (kind: string) => {
+export const stashFits = (kind: string, at = 0) => {
   const t = navigation().type;
-  return kind === 'back' ? t === 'back_forward' : t === 'navigate' || t === 'prerender';
+  if (kind !== 'back') return t === 'navigate' || t === 'prerender';
+  if (t === 'back_forward') return true;
+  return Date.now() - at < ROUND_TRIP_MS && (t === 'reload' || (t === 'navigate' && fromItself()));
 };
 
 /** A stash this load will likely use (the listing checks it fully). Reads only the start of the entry. */
 export const hasStash = (href: string) => {
   try {
     const head = sessionStorage.getItem(stashKey(href))?.slice(0, 60);
-    return !!head && stashFits(head.includes('"kind":"back"') ? 'back' : 'spec');
+    return !!head && stashFits(head.includes('"kind":"back"') ? 'back' : 'spec', Number(/"at":(\d+)/.exec(head)?.[1]) || 0);
   } catch {
     return false;
   }