@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/core/takeover.ts

@@ -0,0 +1,220 @@
+// Takeover of a host page (search results, category listing), per route:
+//   native   their listing visible, ours hidden (we booted after first paint:
+//            swap in one frame once ours render; on failure theirs just stay)
+//   hold     their listing hidden before it ever paints, space reserved, a
+//            loading indicator shown (the early-hold snippet held it, we
+//            booted before first paint, or an SPA route change into the route)
+//   ours     our listing visible
+//   released fail-safe or a URL we cannot serve: theirs shown, ours hidden
+//
+// Server-rendered pages (Luigi's Box's server-side rendering) start as `ours` when the page arrived
+// with our listing in it, and as `released` when their server fell back to
+// their own listing (our marker is there, our listing is not).
+//
+// In lbx-nav (core/listings.ts creates it), loaded with the listing's chunks
+// on a page of its route. Until it arrives the entry holds their listing
+// (main.ts: the early hold claimed, or its own hold CSS, in the same task as an
+// SPA's URL change into the route); the takeover continues that hold.
+
+import { earlyHold } from './early-rules';
+import { canon, isOwnEntry } from './entries';
+import { mark } from './health';
+import { failKey, failures as storedFailures, holding, LOADING, MAX_FAILURES, painted, reserveCss } from './hold';
+import { onUrlChange } from './sense';
+import { session } from './storage';
+import { setCss, whenApplied } from './styles';
+
+export type State = 'native' | 'hold' | 'ours' | 'released';
+
+export interface TakeoverRoute {
+  id: string;
+  tag: string;
+  accepts: (url: URL) => boolean;
+  /** style-host.css of the route's folder: hides the host's listing. */
+  hostCss: string;
+  reserveSelector: string;
+  holdTimeoutMs: number;
+  /** Pages of the route that are separate visits (another category = hold again). */
+  visitKey?: (url: URL) => string;
+  /** The entry already holds their listing for this visit (main.ts, before this chunk arrived): continue that hold. */
+  held?: boolean;
+}
+
+export interface Takeover {
+  readonly state: State;
+  /** Our first render is on screen. */
+  reveal(): void;
+  /** Hand the page back to the host; `failed`: because something went wrong (not a page we decline). */
+  release(failed?: boolean): void;
+  /** A slow step completed: re-arm the fail-safe (up to 3x the timeout in total). */
+  progressed(): void;
+  /** Set by the listing: a URL it can render synchronously from cache (no hold needed). */
+  cached?: (url: URL) => boolean;
+  /** The server rendering of the current visit: ours in the HTML, their fallback, or none (a later visit). */
+  readonly ssr: 'rendered' | 'fellback' | null;
+  /** The listing adopted a server-rendered element on the booted visit (the include arrived after our boot). */
+  serverRendered(): void;
+  /** Failed too often this session: no hold (and no early-hold rule), theirs shows while ours loads. */
+  readonly failing: boolean;
+}
+
+/**
+ * Server rendering of the page we booted on. The page template puts a marker
+ * after our include: `<template data-lbx-ssr="plp">`. Marker without our
+ * element = their server declined or failed and served their own listing.
+ */
+const ssrOf = (r: TakeoverRoute): Takeover['ssr'] =>
+  document.querySelector(`${r.tag}[data-lbx-ssr]`) ? 'rendered' : document.querySelector(`template[data-lbx-ssr="${r.id}"]`) ? 'fellback' : null;
+
+
+export const takeover = (r: TakeoverRoute): Takeover => {
+  let state: State = 'ours';
+  /** Pages of this visit's route we showed ours on, in this document. */
+  const shown = new Set<string>();
+  let timer = 0;
+  /** When the current visit started waiting for us (hold or native). */
+  let enteredAt = 0;
+  let failures = storedFailures(r.id);
+  const countFailures = (n: number) => {
+    failures = n;
+    session.set(failKey(r.id), n || undefined);
+  };
+  const fail = () => {
+    countFailures(failures + 1);
+    set('released');
+  };
+  const arm = () => {
+    clearTimeout(timer);
+    // A prerendered page (Speculation Rules) is not shown yet: its hold's time starts at the activation.
+    if ((document as any).prerendering) return document.addEventListener('prerenderingchange', () => state === 'hold' && ((enteredAt = performance.now()), arm()), { once: true });
+    timer = window.setTimeout(() => state === 'hold' && fail(), r.holdTimeoutMs);
+  };
+  const set = (s: State) => {
+    clearTimeout(timer);
+    if (s === 'hold' || s === 'native') enteredAt = performance.now();
+    state = s;
+    mark(`${r.id} takeover ${s}`);
+    if (s === 'ours') shown.add(canon(location.href));
+    if (s === 'hold') arm();
+    css();
+  };
+  // Route-scoped host CSS, plus the height we had last time on this URL: the
+  // browser restores scroll on reload/back before our results exist.
+  const css = () => {
+    // A server-rendered fragment carries its own CSS hiding their listing (for
+    // pages without JavaScript). Once we write ours, per state, it goes: theirs
+    // must come back when we hand the page back.
+    for (const el of document.querySelectorAll(`style[data-lbx-ssr-host="${r.id}"]`)) el.remove();
+    const key = `host-${r.id}`;
+    if (!r.accepts(new URL(location.href))) return setCss(key, null);
+    const reserve = reserveCss(r.reserveSelector);
+    // A server-rendered listing is never hidden: it is the page's own content.
+    const hideOurs = `${r.tag}:not([data-lbx-ssr]) { display: none !important; }`;
+    if (state === 'native' || state === 'released') setCss(key, hideOurs);
+    // Held: theirs hidden but keeping its height (holding()), ours not shown yet.
+    else if (state === 'hold') setCss(key, `${holding(r.hostCss)}${reserve}\n${hideOurs}\n${LOADING(r.reserveSelector)}`);
+    else setCss(key, r.hostCss + reserve);
+  };
+
+  let ssr = ssrOf(r);
+  let visitStartedAtBoot = true;
+  const t: Takeover = {
+    get state() {
+      return state;
+    },
+    get ssr() {
+      return ssr;
+    },
+    serverRendered: () => {
+      if (ssr === 'rendered' || !visitStartedAtBoot) return;
+      ssr = 'rendered';
+      countFailures(0); // the page is ours after all (a late include is not a failure)
+      if (state !== 'ours') set('ours');
+    },
+    get failing() {
+      return failures >= MAX_FAILURES;
+    },
+    // A success is a render shown within the hold's time (a late one, after
+    // the hold gave up or while theirs shows, does not end the failures).
+    reveal: () => {
+      if (state !== 'native' && state !== 'hold') return;
+      const failed = failures;
+      if (performance.now() - enteredAt < r.holdTimeoutMs) countFailures(0);
+      set('ours');
+      // Shown, if ours is in the page: a render can finish while the host has
+      // taken ours out (a host fighting ours, the reconciler backing off), and
+      // theirs would stay hidden with nothing of ours there. Theirs comes back
+      // if ours is not placed (again) within the hold's time.
+      if (!document.querySelector(`${r.tag}[data-lbx]`)) {
+        countFailures(failed);
+        timer = window.setTimeout(() => state === 'ours' && !document.querySelector(`${r.tag}[data-lbx]`) && fail(), r.holdTimeoutMs);
+      }
+    },
+    release: (failed = false) => {
+      if (state === 'native' || state === 'released') return;
+      // A server-rendered visit whose listing is on the page (the server's, or
+      // ours after hydration) keeps it: with SSI there is no listing of theirs
+      // in the page to hand back to.
+      if (ssr === 'rendered' && document.querySelector(`${r.tag}[data-lbx]`)?.childElementCount) return;
+      if (failed) fail();
+      else set('released');
+    },
+    progressed: () => state === 'hold' && performance.now() - enteredAt < r.holdTimeoutMs * 2 && arm(),
+  };
+
+  let wasActive = false;
+  let visit = '';
+  const visitOf = (url: URL) => r.visitKey?.(url) ?? '';
+  onUrlChange((url) => {
+    const active = r.accepts(url);
+    const another = active && wasActive && visitOf(url) !== visit;
+    // Another visit whose page is ours to show while ours is on screen: an
+    // entry we created (a new query in place) or a page we showed in this
+    // document (back/forward between them). Nothing of theirs renders there,
+    // so no hold: ours stays (dimmed while busy) until the new results replace
+    // it, instead of blanking. A visit the host navigates to holds as before.
+    const continuing = another && state === 'ours' && (isOwnEntry(url.href) || shown.has(canon(url.href)));
+    const entering = active && (!wasActive || another) && !continuing;
+    // The server's rendering (or fallback) was about the page we booted on.
+    if (entering || continuing) {
+      ssr = null;
+      visitStartedAtBoot = false;
+    }
+    // Entering the route, or another page of it: hold (their page has not
+    // painted yet). Moving within a page (filters, sort, paging, a #hash) keeps
+    // what is shown: ours, or theirs once handed back (their own filter clicks
+    // must not blank their listing again). After failures in a row, no hold:
+    // theirs shows while ours loads (and replaces it if it renders).
+    if (entering && t.cached?.(url)) {
+      set('ours');
+      // Shown from cache, if our element gets placed: when it does not (no
+      // anchor, the reconciler backing off), theirs comes back.
+      timer = window.setTimeout(() => state === 'ours' && !document.querySelector(`${r.tag}[data-lbx]`) && fail(), r.holdTimeoutMs);
+    } else if (entering) set(t.failing ? 'native' : 'hold');
+    else {
+      if (!active) clearTimeout(timer); // left during a hold: not a failure of ours
+      css();
+    }
+    wasActive = active;
+    if (active) visit = visitOf(url);
+  });
+
+  // Boot: the early-hold snippet may have hidden their listing before first paint;
+  // then we continue its hold (our CSS is written before its CSS is removed, in
+  // the same task: no gap frame). Otherwise hold only if nothing painted yet.
+  const url = new URL(location.href);
+  wasActive = r.accepts(url);
+  visit = visitOf(url);
+  const early = earlyHold();
+  // Failing: an early hold is not continued (it ends below, with drop()).
+  const claimed = wasActive && !t.failing && !!early?.claim?.(r.id);
+  if (wasActive && ssr) set(ssr === 'rendered' ? 'ours' : 'released');
+  else if (wasActive) set(!t.failing && (claimed || r.held || !painted()) ? 'hold' : 'native');
+  else css();
+  if (claimed) {
+    // Theirs is dropped once ours applies (ours may wait for the end of <head>): no gap.
+    whenApplied(() => early!.drop());
+    mark(`${r.id} early hold claimed (it began at ${Math.round(early!.t)}ms)`);
+  }
+  return t;
+};

package/src/core/templates.ts

@@ -0,0 +1,74 @@
+// Templates are lit-html functions: `(s) => html\`…\``, one per template-*.ts
+// file, registered by name (the file name without `template-`). A widget's
+// built-in templates are overridden by the integration's files of the same
+// name. include(name, props) renders another template with the current
+// scope plus props; lit does the DOM updates (only changed bindings touch
+// the DOM, so images, focus and open <details> survive re-renders).
+
+import { nothing, render } from 'lit-html';
+
+export type Template<S = any> = (s: S) => unknown;
+export type Templates = Record<string, Template>;
+
+/** A widget's built-in templates from an eager import.meta.glob of './template-*.ts'. */
+export const byName = (modules: Record<string, unknown>): Templates =>
+  Object.fromEntries(Object.entries(modules).map(([p, t]) => [p.split('/').pop()!.replace(/^template-/, '').replace(/\.\w+$/, ''), t as Template]));
+
+/**
+ * What an include for a result drew (`include(name, { r, i, … })`, a tile
+ * or a row), by its result, template and index: the scope values it read
+ * and its lit value. A render where every one of them is the same (===)
+ * gets that value back without running the template: lit then finds the
+ * same values and touches nothing. A listing's view-state redraw (a facet
+ * group opened, a letter typed in a facet's search) ran every tile's
+ * template again: 31-92 ms a keystroke on a production storefront at 4x CPU.
+ */
+const drawn = new WeakMap<object, Map<string, { reads: [string, unknown][]; out: unknown }>>();
+
+/** Template `name` applied to `data` (with include()), as a lit value. */
+export const templateOf = (templates: Templates, name: string, data: Record<string, unknown>) => {
+  const scope = (d: Record<string, unknown>): any => {
+    const s: any = { ...d };
+    s.include = (n: string, props?: Record<string, unknown>) => {
+      const t = templates[n];
+      if (!t) throw new Error(`template "${n}" not found`);
+      if (!props) return t(s);
+      const r = props.r;
+      if (!r || typeof r !== 'object') return t(scope({ ...s, ...props }));
+      const id = `${n}\n${String(props.i)}`;
+      let byR = drawn.get(r);
+      const was = byR?.get(id);
+      if (was && was.reads.every(([k, v]) => (k in props ? props[k] : s[k]) === v)) return was.out;
+      // Run, recording what it reads (`include` is made anew per scope: not a dependency).
+      const reads = new Map<string, unknown>();
+      const child = scope({ ...s, ...props });
+      const out = t(
+        new Proxy(child, {
+          get(o, k, rcv) {
+            const v = Reflect.get(o, k, rcv);
+            if (typeof k === 'string' && k !== 'include') reads.set(k, v);
+            return v;
+          },
+        }),
+      );
+      if (!byR) drawn.set(r, (byR = new Map()));
+      byR.set(id, { reads: [...reads], out });
+      return out;
+    };
+    return s;
+  };
+  return scope(data).include(name);
+};
+
+export const view = (root: HTMLElement | ShadowRoot, templates: Templates) => ({
+  /** Render template `name` with `data` into the root. */
+  render: (name: string, data: Record<string, unknown>) => render(templateOf(templates, name, data), root),
+  /** Empty the root (lit's templates stay prepared: the next render builds from them). */
+  clear: () => render(nothing, root),
+  /**
+   * Adopt server-rendered markup of the same template and data (lit SSR,
+   * server-side rendering): binds to the existing DOM instead of re-creating it.
+   * `hydrate` is @lit-labs/ssr-client's, loaded only on server-rendered pages.
+   */
+  hydrate: (name: string, data: Record<string, unknown>, hydrate: (v: unknown, c: HTMLElement | ShadowRoot) => void) => hydrate(templateOf(templates, name, data), root),
+});

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);
+  }
+};

package/src/core/turbo.ts

@@ -0,0 +1,64 @@
+// Turbo Drive (Hotwire) on the host: history and prefetching. In the entry
+// (a back/forward must be handled in its own popstate, before any chunk).
+//
+// Turbo answers every popstate. Our history entries (null state, core/url.ts)
+// are foreign to it: Turbo <= 8.0.20 ignores them, 8.0.21+ stamps the one
+// landed on (caching a snapshot: turbo:before-cache takes our nodes out of the
+// live page) and makes a back to an entry it stamped a restore visit (their
+// page fetched or a snapshot rendered, the body swapped). So, in a popstate
+// listener of ours that runs before Turbo's:
+// - a move between states of the page Turbo has rendered, while ours shows
+//   it (filters, sort, another query in place): ours alone. Nothing of
+//   theirs changes on such a move; host popstate handlers (a jQuery reload on
+//   filter state, a storefront's own namespaced popstate handler) do not run either;
+// - a move onto one of our entries of another page (back across a Turbo
+//   visit): Turbo would leave the other page in the document under this URL.
+//   Turbo renders it with a replace visit (their page for this URL; the entry
+//   becomes Turbo's, so its later restores, snapshot keys and same-page
+//   checks are right: a restore visit without a history write would leave
+//   Turbo's location at the other page); ours renders in it.
+// Turbo 8 also prefetches a link's page on hover: our in-place links (the
+// same path: a filter, a sort, taken on click) are not
+// prefetched; links of ours to other pages (products) stay Turbo's.
+import { isOwnEntry } from './entries';
+import { mark } from './health';
+import type { Takeover } from './takeover';
+
+export const startTurbo = (listings: { tk: Takeover; accepts: (u: URL) => boolean }[]) => {
+  const turbo = () => {
+    const t = (window as any).Turbo;
+    return typeof t?.visit === 'function' ? t : null;
+  };
+  // The page Turbo has in the document: the one we booted on, then its renders.
+  let rendered = location.pathname;
+  addEventListener('turbo:load', () => (rendered = location.pathname));
+  addEventListener(
+    'popstate',
+    (e) => {
+      const t = turbo();
+      if (!t) return;
+      const to = new URL(location.href);
+      if (to.pathname === rendered && listings.some((l) => l.accepts(to) && (l.tk.state === 'ours' || l.tk.state === 'hold'))) {
+        e.stopImmediatePropagation();
+        mark('turbo: popstate ours');
+      } else if (e.state == null && isOwnEntry(to.href)) {
+        e.stopImmediatePropagation();
+        mark(`turbo: visit ${to.pathname}`);
+        t.visit(to.href, { action: 'replace' });
+      }
+    },
+    true,
+  );
+  // Window listeners run in the order they were added (capture or not): a
+  // Turbo that started before us gets its listener added again, after ours.
+  // (One that starts later adds it after ours anyway.)
+  const h = turbo()?.session?.history;
+  if (h?.started && typeof h.onPopState === 'function') {
+    removeEventListener('popstate', h.onPopState, false);
+    addEventListener('popstate', h.onPopState, false);
+  }
+  document.addEventListener('turbo:before-prefetch', (e) => {
+    const a = e.target;
+    if (a instanceof HTMLAnchorElement && a.pathname === location.pathname && a.closest('[data-lbx]')) e.preventDefault();
+  });
+};

package/src/core/url.ts

@@ -0,0 +1,164 @@
+// Polite URL writes.
+//
+// 1. If the host's router is detectable, navigate through it, so the router's
+//    own idea of the current location includes our params. A raw pushState
+//    behind its back leaves it stale, and its next internal replace() puts its
+//    stale URL back (Vue Router, e.g. under Nuxt, reverts params written
+//    behind its back). Vue exposes the app on its mount element
+//    in production builds too; Next.js (pages router) exposes window.next.
+//
+// 2. Otherwise, new entries get a NULL state. Every SPA router must already
+//    handle null-state entries (hash links and third-party scripts create them)
+//    and treats them as foreign: Vue Router rebuilds its bookkeeping via
+//    replace(), Angular navigates to the URL. Copying the current state instead
+//    is wrong: it carries that entry's router bookkeeping (current URL,
+//    position, navigationId) onto an entry with a different URL, which has made
+//    a router later navigate to a URL of its own invention. The exceptions
+//    are SvelteKit and Astro (entryState, below): their routers ignore
+//    null-state entries altogether.
+
+import { canon, markOwnEntry } from './entries';
+
+interface HostRouter {
+  push(to: string): unknown;
+  /** The router's base path (it prefixes every path it is given). */
+  base?: string;
+}
+
+export { canon, isOwnEntry } from './entries';
+export { pageKey } from './page';
+
+const usable = (r: any) => typeof r?.push === 'function' && typeof r?.replace === 'function';
+
+/** A path as a router and the browser may each spell it (encoded or not, a trailing slash). */
+const samePath = (a: string, b: string) => {
+  const norm = (p: string) => {
+    try {
+      p = decodeURI(p);
+    } catch {}
+    return p.replace(/\/+$/, '').toLowerCase() || '/';
+  };
+  return norm(a) === norm(b);
+};
+
+const vueRouter = (): HostRouter | null => {
+  // Vue 3 (the app on its mount element: every one, a widget app may come first), Vue 2 (the root instance), Nuxt 2.
+  const candidates = [
+    ...[...document.querySelectorAll('#__nuxt, #app, [data-v-app]')].map((el: any) => el.__vue_app__?.config?.globalProperties?.$router ?? el.__vue__?.$router),
+    (window as any).$nuxt?.$router,
+  ];
+  for (const r of candidates) {
+    if (!usable(r)) continue;
+    // Vue Router 3 resolves its base from <base href> into history.base.
+    const raw: string = r.options?.history?.base ?? r.history?.base ?? r.options?.base ?? '';
+    const base = raw.replace(/\/$/, '');
+    // Hash mode (paths in the #fragment): writing through it would not change the URL.
+    if (raw.includes('#') || r.mode === 'hash') {
+      settled = true;
+      return null;
+    }
+    // A memory / abstract history (a widget app): not the page's router.
+    const own = r.options?.history?.location; // Vue 3: the history's current path
+    if (r.mode === 'abstract' || (typeof own === 'string' && !samePath(own.split(/[?#]/)[0], location.pathname.slice(base.length)))) continue;
+    settled = true;
+    return { push: (to) => r.push(to), base };
+  }
+  return null;
+};
+
+/** Next.js pages router. The app router (it sets window.next.router too) follows raw history writes by itself. */
+const nextRouter = (): HostRouter | null => {
+  const w = window as any;
+  if (w.next?.appDir || !w.__NEXT_DATA__) return null;
+  const r = w.next?.router;
+  if (!usable(r)) return null;
+  const base = (r.basePath ?? '').replace(/\/$/, '');
+  return { push: (to) => r.push(to, undefined, { shallow: true, scroll: false }), base };
+};
+
+const hostRouter = () => vueRouter() ?? nextRouter();
+
+/** A mounted router found (usable, or hash mode), or waited for one in vain: writes are not queued from then on. */
+let settled = false;
+/** A server-rendered Vue app whose client app has not mounted yet (no router to talk to). vueRouter() may settle it (a hash-mode router: null, settled), hence `settled` is read again after it. */
+const vueNotMountedYet = () => !settled && !!((window as any).__NUXT__ || document.querySelector('#__nuxt, [data-server-rendered]')) && !vueRouter() && !settled;
+
+/** The router's own path for a URL: without its base, which it adds itself. */
+const routerPath = (r: HostRouter, url: URL) => {
+  const path = !r.base ? url.pathname : url.pathname === r.base ? '/' : url.pathname.startsWith(`${r.base}/`) ? url.pathname.slice(r.base.length) : url.pathname;
+  return path + url.search + url.hash;
+};
+
+const viaRouter = (r: HostRouter, url: URL) => {
+  try {
+    const p = r.push(routerPath(r, url)) as any;
+    // A navigation the router itself redirected or cancelled (Vue Router 3
+    // rejects those) is its decision; only a broken router gets a raw write.
+    if (typeof p?.catch === 'function') p.catch((e: any) => e?._isRouter || raw(url));
+  } catch {
+    raw(url);
+  }
+};
+
+// A write that arrives before the host router exists is queued and handed to
+// the router once it mounts (latest write wins). A raw pushState would be
+// undone by the router's initial replace() when it starts.
+let queued: { url: URL; from: string } | null = null;
+const flushQueued = (tries = 0) => {
+  if (!queued) return;
+  const r = vueRouter();
+  // Waiting while the app is still to mount (~5 s at most, background tabs too).
+  if (!r && vueNotMountedYet() && tries < 300) return void setTimeout(() => flushQueued(tries + 1), 16);
+  const { url, from } = queued;
+  queued = null;
+  // The page moved on meanwhile (the shopper navigated): the write is stale.
+  // Compared canonically: the router's first replace() re-encodes the URL.
+  if (canon(location.href) !== canon(from) || canon(url.href) === canon(location.href)) return;
+  if (!r) {
+    settled = true; // it never mounted: plain history writes, now and later
+    return raw(url);
+  }
+  viaRouter(r, url);
+};
+
+/**
+ * Two routers with no handle on the page to write through ignore a null-state
+ * entry altogether, so Back into one of ours after one of their navigations
+ * left the other page on screen under our listing's URL. Our entry gets the
+ * router's own bookkeeping, built from the entry it is pushed over (only the
+ * keys the router reads, never the rest of its state):
+ *  - SvelteKit reads a null state as a hash link's (it only updates
+ *    `page.url`): ours carries the index pair of the entry below, the same
+ *    router entry for it (back/forward between the two is nothing to it),
+ *    which it renders anew when it comes back to it from another navigation;
+ *  - Astro's ClientRouter returns on a null state: ours carries its index and
+ *    the scroll position, so it fetches and swaps in our URL's page on a
+ *    traversal, as it does for its own entries.
+ */
+const SK_HISTORY = 'sveltekit:history';
+const SK_NAVIGATION = 'sveltekit:navigation';
+const entryState = () => {
+  const s = history.state;
+  if (!s || typeof s !== 'object') return null;
+  if (s[SK_HISTORY] && SK_NAVIGATION in s) return { [SK_HISTORY]: s[SK_HISTORY], [SK_NAVIGATION]: s[SK_NAVIGATION] };
+  if (typeof s.index === 'number' && document.querySelector('meta[name="astro-view-transitions-enabled"]')) return { index: s.index, scrollX, scrollY };
+  return null;
+};
+
+const raw = (url: URL) => history.pushState(entryState(), '', url.href);
+
+/** A new history entry for `url` (our listing's state). */
+export const writeUrl = (url: URL) => {
+  if (canon(url.href) === canon(location.href) && url.hash === location.hash) return;
+  markOwnEntry(url.href);
+  const same = url.origin === location.origin;
+  if (same && vueNotMountedYet()) {
+    const first = !queued;
+    queued = { url, from: location.href };
+    if (first) setTimeout(() => flushQueued(), 16);
+    return;
+  }
+  const router = same ? hostRouter() : null;
+  if (!router) return raw(url);
+  viaRouter(router, url);
+};