@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/widgets/listing/flow.ts

@@ -0,0 +1,30 @@
+// Where a listing's later parts sit, learnt from a view of the route at about
+// this width (localStorage, per 100 px), and the channel the quick types land
+// by. Here (no DOM but localStorage) for the listing and for a search page's
+// first request, which the entry starts before the listing exists (search/first.ts).
+import type { ListingResult } from './query';
+
+/**
+ * The parts that may come after the products: the facets, and on a search
+ * page the quick types (`[data-lbx-part="quick"]`, often a row of category
+ * and brand tiles above the grid). Not waited for only where they do not sit
+ * above the products: arriving after, they would push them down (a layout
+ * shift, found on a phone layout, 2026-10-11). Not known yet: waited for.
+ */
+export type Part = 'facets' | 'quick';
+
+export const flowKey = (route: string, part: Part = 'facets') => `lbx:${part === 'facets' ? 'pf' : 'pq'}:${route}:${Math.round(innerWidth / 100)}`;
+
+export const notAbove = (route: string, part: Part = 'facets') => {
+  try {
+    return localStorage.getItem(flowKey(route, part)) === '1';
+  } catch {
+    return false;
+  }
+};
+
+/** Per route: the listing element's, called when the quick types land in a result shown without them. */
+const landed: Record<string, (r: ListingResult) => void> = {};
+export const onQuickLanded = (route: string, f: (r: ListingResult) => void) => void (landed[route] = f);
+/** listingQuery's `onQuick` for a route, where its quick types are not waited for. */
+export const quickChannel = (route: string) => (notAbove(route, 'quick') ? (r: ListingResult) => landed[route]?.(r) : undefined);

package/src/widgets/listing/instant.ts

@@ -0,0 +1,133 @@
+// The listing's "already there" helpers, outside its render path:
+// - where the shopper was when they followed a link (back lands there again);
+// - the next page, prefetched as the shopper nears the end of the loaded tiles;
+// - the product image host, preconnected on later page loads.
+// Nothing here is required: every failure leaves the listing as it would be.
+
+import { reportError } from '../../core/health';
+
+const sameDoc = (a: HTMLAnchorElement) => a.origin === location.origin;
+
+/**
+ * The link a click follows away from this page, as the browser will: a plain
+ * primary click on a same-origin link to another page, in this tab, that no
+ * handler (ours: filters, sort, pages) has taken. null for anything else.
+ */
+export const leavingLink = (e: MouseEvent, root: Element): HTMLAnchorElement | null => {
+  if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return null;
+  const a = (e.target as Element | null)?.closest?.('a[href]') as HTMLAnchorElement | null;
+  if (!a || !root.contains(a) || !sameDoc(a) || a.hasAttribute('download') || (a.target && a.target !== '_self')) return null;
+  // Host handlers that turn the link into a request (rails-ujs) do not leave.
+  if (a.matches('[data-remote], [data-method]')) return null;
+  const here = new URL(location.href);
+  if (a.pathname === here.pathname && a.search === here.search) return null; // a #fragment on this page
+  return a;
+};
+
+/** The first link to `href` in root (a tile has several: its image, its title). */
+const linkTo = (root: Element, href: string) => {
+  for (const a of root.querySelectorAll<HTMLAnchorElement>('a[href]')) if (a.href === href) return a;
+  return null;
+};
+
+/** Where the shopper is, pinned to the link they follow (layout above it may differ on the way back). */
+export const scrollSpot = (root: Element, a: HTMLAnchorElement) => ({ y: Math.round(scrollY), href: a.href, top: Math.round((linkTo(root, a.href) ?? a).getBoundingClientRect().top) });
+
+const scroll = (top: number) => scrollTo({ top, left: scrollX, behavior: 'instant' as ScrollBehavior });
+
+/**
+ * Back where the shopper was: the followed link at the same place in the
+ * viewport (scrollY when it is gone). Late layout above us (their images,
+ * banners, fonts) moves it: followed for a while, until the shopper scrolls,
+ * taps or types themselves.
+ */
+export const restoreScroll = (root: Element, s: { y: number; href?: string; top?: number }) => {
+  let done = false;
+  const place = () => {
+    if (done) return;
+    const a = s.href ? linkTo(root, s.href) : null;
+    if (a) {
+      const d = a.getBoundingClientRect().top - (s.top ?? 0);
+      if (Math.abs(d) >= 1) scroll(scrollY + d);
+    } else if (Math.abs(scrollY - s.y) >= 1) scroll(s.y);
+  };
+  const STOP = ['wheel', 'touchstart', 'keydown', 'pointerdown'];
+  const ro = new ResizeObserver(() => place());
+  const stop = () => {
+    done = true;
+    ro.disconnect();
+    for (const t of STOP) removeEventListener(t, stop, true);
+  };
+  for (const t of STOP) addEventListener(t, stop, { capture: true, passive: true });
+  place();
+  ro.observe(document.documentElement);
+  setTimeout(stop, 2500);
+};
+
+/**
+ * Keep what the shopper is looking at in place across a re-render (a
+ * revalidated result): the first tile link in the viewport stays where it is.
+ */
+export const keepViewport = (root: Element, f: () => void) => {
+  let pin: { href: string; top: number } | null = null;
+  for (const a of root.querySelectorAll<HTMLAnchorElement>('[data-lbx-list] a[href]')) {
+    const top = a.getBoundingClientRect().top;
+    if (top >= 0) {
+      pin = { href: a.href, top };
+      break;
+    }
+  }
+  f();
+  if (!pin) return;
+  const a = linkTo(root, pin.href);
+  if (a) {
+    const d = a.getBoundingClientRect().top - pin.top;
+    if (Math.abs(d) >= 1) scroll(scrollY + d);
+  }
+};
+
+/**
+ * Calls `near` once, when the tile at ~70% of the loaded ones comes within
+ * reach of the viewport. Returns the cancel.
+ */
+export const nearEnd = (root: Element, near: () => void) => {
+  const tiles = root.querySelector('[data-lbx-list]')?.children;
+  if (!tiles?.length) return () => {};
+  const at = tiles[Math.min(tiles.length - 1, Math.floor(tiles.length * 0.7))];
+  const io = new IntersectionObserver(
+    (es) => {
+      if (!es.some((e) => e.isIntersecting)) return;
+      io.disconnect();
+      try {
+        near();
+      } catch (e) {
+        reportError('next page prefetch', e);
+      }
+    },
+    { rootMargin: '0px 0px 50% 0px' },
+  );
+  io.observe(at);
+  // And the last: a jump to the end (an anchor, a fling on a phone: the tile
+  // above was out of view by the next frame) never intersects the first.
+  io.observe(tiles[tiles.length - 1]);
+  return () => io.disconnect();
+};
+
+/** localStorage: the product image host, preconnected at boot (src/main.ts). */
+export const IMG_HOST = 'lbx:img';
+const hinted = new Set<string>();
+export const preconnectImages = (src: unknown) => {
+  try {
+    if (typeof src !== 'string' || !src) return;
+    const o = new URL(src, location.href).origin;
+    if (o === location.origin || !/^https?:/.test(o) || hinted.has(o)) return;
+    hinted.add(o);
+    if (localStorage.getItem(IMG_HOST) !== o) localStorage.setItem(IMG_HOST, o);
+    if (document.querySelector(`link[rel="preconnect"][href="${o}"]`)) return;
+    const l = document.createElement('link');
+    l.rel = 'preconnect';
+    l.href = o;
+    l.setAttribute('data-lbx', 'preconnect');
+    document.head.append(l);
+  } catch {}
+};

package/src/widgets/listing/intent.ts

@@ -0,0 +1,193 @@
+// Filter clicks that render at once (`_global.prefetchFilters`, default on).
+// When the shopper shows intent on one of our controls that leads to another
+// state of this listing (a facet value, a flag, a sort, a chip, "clear all",
+// the next page), the request that control's click would make starts then:
+// - pointer: it rests on the control for DWELL_MS (a cursor sweeping over a
+//   list of values crosses each in less);
+// - touch (no hover): pointerdown, about 100 ms before the click;
+// - keyboard: focus on the control, for DWELL_MS (Tab passing through a list
+//   does not stop on each).
+// Which state a control leads to is its URL: a link's href, or
+// `data-lbx-href` on any other element (a checkbox's label, a button), as the
+// templates write them from the scope's links. Range sliders have no such URL
+// (their value is known on release, which is the click itself): never prefetched.
+//
+// What is fetched: the first page of products for that state, exactly the
+// request listingQuery() starts with (`firstRequest`), keyed by that request
+// (the exact query state). The click takes it, done or in flight (never a
+// second request), renders the products with the sidebar it had, and then asks
+// the facets of the new result set (they need its guid): the request a
+// shopper hovers without clicking costs one search, not a search and its facets.
+// Results are never rendered by the prefetch itself: only a click whose
+// request is the same takes them.
+//
+// Limits: two in flight (a newer intent aborts the oldest), the state
+// changing aborts those still out (their controls now lead elsewhere), kept
+// TTL_MS, PER_VISIT per category or query, none with Save-Data, offline or on
+// 2G. The listing adds its own (element.ts): none while a click or a request
+// of the current state is pending, none for a state it has cached.
+//
+// Analytics: Luigi's Box counts searches and impressions from the tracker's
+// events about a rendered result (its guid); a prefetch renders nothing and
+// runs no hook (`onRender`), so it reports nothing.
+
+import type { Page } from '../../api';
+import { reportError } from '../../core/health';
+
+/** Hover or focus this long counts as intent (Chrome's speculation rules wait ~200 ms on hover for a whole page; this is one request). */
+export const DWELL_MS = 100;
+const TTL_MS = 30_000;
+/** First pages kept (done or in flight). */
+const KEEP = 6;
+const IN_FLIGHT = 2;
+/** Prefetches per visit (a category, a query): a shopper browsing the sidebar for long stops costing requests. */
+export const PER_VISIT = 20;
+
+/** No speculative requests: offline, Save-Data, a 2G connection. */
+export const thrifty = () => {
+  const c = (navigator as any).connection;
+  return navigator.onLine === false || !!c?.saveData || /(^|-)2g$/.test(c?.effectiveType ?? '');
+};
+
+const CONTROL = 'a[href], [data-lbx-href]';
+/** The URL a control leads to ('' or null: none). */
+export const targetOf = (el: Element) => el.getAttribute('data-lbx-href') ?? el.getAttribute('href');
+
+/**
+ * Delegated listeners on `root` (ours): `intent(control)` after DWELL_MS of
+ * hover or focus, at once on pointerdown. A pointerover where the pointer was
+ * already (the page scrolled or re-rendered under a still pointer) is not
+ * intent. `cancel()` drops a pending dwell (a click: the control's state is
+ * being fetched).
+ */
+export const watchIntent = (root: HTMLElement, intent: (el: Element) => void) => {
+  let timer = 0;
+  let armed: Element | null = null;
+  let at = '';
+  const controlOf = (t: EventTarget | null) => {
+    const el = (t as Element | null)?.closest?.(CONTROL);
+    return el && root.contains(el) ? el : null;
+  };
+  const fire = (el: Element) => {
+    try {
+      intent(el);
+    } catch (e) {
+      reportError('filter prefetch', e);
+    }
+  };
+  const cancel = () => {
+    clearTimeout(timer);
+    armed = null;
+  };
+  /** The control whose dwell fired, while the pointer or focus stays on it (its children's events are not new intent). */
+  let fired: Element | null = null;
+  const arm = (el: Element | null) => {
+    if (el && (el === armed || el === fired)) return;
+    cancel();
+    fired = null;
+    if (!el) return;
+    armed = el;
+    timer = window.setTimeout(() => {
+      armed = null;
+      fired = el;
+      fire(el);
+    }, DWELL_MS);
+  };
+  const over = (e: PointerEvent) => {
+    const spot = `${e.clientX},${e.clientY}`;
+    const still = spot === at;
+    at = spot;
+    if (e.pointerType === 'touch') return; // pointerdown
+    arm(still ? null : controlOf(e.target));
+  };
+  const out = (e: PointerEvent) => {
+    if (e.relatedTarget && root.contains(e.relatedTarget as Node)) return;
+    arm(null);
+    // Left us: coming back to the same spot is a move.
+    at = '';
+  };
+  const down = (e: PointerEvent) => {
+    at = `${e.clientX},${e.clientY}`;
+    const el = e.button === 0 ? controlOf(e.target) : null;
+    cancel();
+    fired = el;
+    if (el) fire(el);
+  };
+  const focus = (e: FocusEvent) => arm(controlOf(e.target));
+  const blur = (e: FocusEvent) => {
+    const el = controlOf(e.target);
+    if (el && (el === armed || el === fired)) arm(null);
+  };
+  const on: [string, (e: any) => void][] = [
+    ['pointerover', over],
+    ['pointerout', out],
+    ['pointerdown', down],
+    ['focusin', focus],
+    ['focusout', blur],
+  ];
+  for (const [t, f] of on) root.addEventListener(t, f, { passive: true });
+  return {
+    cancel,
+    stop: () => {
+      cancel();
+      for (const [t, f] of on) root.removeEventListener(t, f);
+    },
+  };
+};
+
+type Entry = { p: Promise<Page>; ctrl: AbortController; settled: boolean; at: number };
+
+/** First pages prefetched on intent, by their request (JSON): in flight or done, for TTL_MS, consumed once. */
+export const firstPages = () => {
+  const m = new Map<string, Entry>();
+  let visit = '';
+  let count = 0;
+  const fresh = (e: Entry) => performance.now() - e.at < TTL_MS;
+  const live = (k: string) => {
+    const e = m.get(k);
+    if (e && !fresh(e)) m.delete(k);
+    return e && fresh(e) ? e : undefined;
+  };
+  return {
+    has: (k: string) => !!live(k),
+    /** The first page for this request, done or in flight (consumed). */
+    take(k: string) {
+      const e = live(k);
+      m.delete(k);
+      return e?.p;
+    },
+    /** Starts `run` for this request unless it is there already or the visit's cap is reached. True: started. */
+    start(k: string, visitKey: string, run: (signal: AbortSignal) => Promise<Page>) {
+      if (visitKey !== visit) (visit = visitKey), (count = 0);
+      if (live(k) || count >= PER_VISIT) return false;
+      count++;
+      // The latest intent wins: the oldest still out goes.
+      const out = [...m].filter(([, e]) => !e.settled);
+      if (out.length >= IN_FLIGHT) {
+        const [ok, oe] = out[0];
+        oe.ctrl.abort();
+        m.delete(ok);
+      }
+      const ctrl = new AbortController();
+      const e: Entry = { ctrl, settled: false, at: performance.now(), p: run(ctrl.signal) };
+      e.p.then(
+        () => void (e.settled = true),
+        () => {
+          e.settled = true;
+          if (m.get(k) === e) m.delete(k); // failed or aborted: the click asks itself
+        },
+      );
+      m.set(k, e);
+      while (m.size > KEEP) m.delete(m.keys().next().value!);
+      return true;
+    },
+    /** The state changed: requests still out were for controls that now lead elsewhere. */
+    abortInFlight() {
+      for (const [k, e] of m)
+        if (!e.settled) {
+          e.ctrl.abort();
+          m.delete(k);
+        }
+    },
+  };
+};

package/src/widgets/listing/query.ts

@@ -0,0 +1,298 @@
+// A listing's API requests, from (route, query) and nothing else: the entry
+// (a search page's request starts before any widget chunk), the listing
+// element and the edge render service share it.
+
+import { isPromise } from '../../core/scheduler';
+import type { Api, FacetData, FilterNode, Hit, ListingRequest, Page, Sort } from '../../api';
+import type { GlobalConfigType, ListingConfigType, SearchConfigType } from '../../types';
+import { facetFields, type Query, type Route } from './state';
+import { lru } from '../../core/storage';
+import { reportError } from '../../core/health';
+import { MAX_PAGE } from '../../core/routes';
+
+const num = (s: string | undefined) => (s === undefined || s === '' ? null : Number(s));
+/** A range filter value `min|max` (either end may be empty). */
+export const parseRange = (v: string | undefined) => {
+  const [a, b] = (v ?? '').split('|');
+  return { from: num(a), to: num(b) };
+};
+
+export type ListingConfig = ListingConfigType & { quick?: SearchConfigType['quick'] };
+
+/** What a listing renders: the pages loaded of one result set (the first, and each "show more"), its facets, and the quick types. */
+export interface ListingResult {
+  /** Every hit loaded, in order: the first page, then each page "show more" appended. */
+  hits: Hit[];
+  total: number;
+  guid: string;
+  /** Pages loaded: 1, plus one per "show more". */
+  page: number;
+  /** Something optional failed (the facets): shown, not cached. */
+  partial?: boolean;
+  /** The products alone, their facets still being asked for (`onProducts`): shown, busy, not cached. */
+  pending?: boolean;
+  cursor: string | null;
+  status: string;
+  facets: Record<string, FacetData>;
+  /** `emptyValues`: the facets of the page without the shopper's filters (values the filtered set lacks show as empty). */
+  facetsAll?: Record<string, FacetData>;
+  quick: Record<string, Hit[]>;
+  /** The quick types are on their way (not waited for): they land in `quick` later. */
+  quickPending?: boolean;
+  /** Ranges over fields holding numbers as text, as the values the first page was asked with: the next pages ask the same tree. */
+  asValues?: Record<string, string[]>;
+}
+
+/** 'lbx:price:asc' -> { field: 'lbx:price', direction: 'asc' } (the field may contain ':'). */
+const toSort = (s: string): Sort | undefined => {
+  const i = s.lastIndexOf(':');
+  if (!s || i < 1) return undefined;
+  const direction = s.slice(i + 1);
+  return direction === 'asc' || direction === 'desc' ? { field: s.slice(0, i), direction } : undefined;
+};
+
+/**
+ * The shopper's narrowing as a filter tree: one condition per faceted field
+ * (`in` over the selected values; a `min|max` value is a range), plus the
+ * active flags and the listing's base filters. Fields in a fixed order, values in selection order: a cursor
+ * is bound to the tree exactly as written. `omit` leaves one field out (its
+ * own facet values must not be narrowed by itself).
+ */
+const filterTree = (route: Route, q: Query, omit?: string, base?: FilterNode, asValues: Record<string, string[]> = {}): FilterNode | undefined => {
+  const clauses: FilterNode[] = [];
+  for (const field of Object.keys(q.filters).sort()) {
+    const vs = q.filters[field];
+    if (field === omit || !vs?.length) continue;
+    // A range over a field that holds its numbers as text: the values within it.
+    if (asValues[field]) clauses.push({ [field]: { in: asValues[field].length ? asValues[field] : [NONE] } });
+    else if (isRange(vs)) {
+      const { from, to } = parseRange(vs[0]);
+      const node: Record<string, number> = {};
+      if (from != null && Number.isFinite(from)) node.gte = from;
+      if (to != null && Number.isFinite(to)) node.lte = to;
+      if (Object.keys(node).length) clauses.push({ [field]: node });
+    } else clauses.push({ [field]: { in: [...vs] } });
+  }
+  for (const f of route.flagDefs) if (q.flags.includes(f.id)) clauses.push(f.filter);
+  if (base && Object.keys(base).length) clauses.push(base);
+  return clauses.length === 0 ? undefined : clauses.length === 1 ? clauses[0] : { $and: clauses };
+};
+
+const isRange = (vs: string[] | undefined) => vs?.length === 1 && vs[0].includes('|');
+/** A value no field holds: an `in` that must match nothing. */
+const NONE = '\u0000';
+/** Faceted fields by kind, as the API reported them ('range' or 'terms'). */
+const kinds = lru<string>(500);
+/** The facets of a scope or query without the shopper's filters (`emptyValues`), per its fields. */
+const unfiltered = lru<Promise<Record<string, FacetData>>>(50);
+/** Numeric text values of a field in a scope or query (a range over them is those values). */
+const textValues = lru<Promise<Record<string, FacetData>>>(50);
+/** Within a `min|max` range, numerically: "50.0", "201 - 500" (its first number). */
+export const inRange = (v: string, sel: string) => {
+  const n = parseFloat(v);
+  const { from, to } = parseRange(sel);
+  return Number.isFinite(n) && (from == null || n >= from) && (to == null || n <= to);
+};
+
+/** The next page after the pages loaded, without hits already shown (Luma de-duplicates results across pages). */
+const append = (shown: Hit[], page: Hit[]) => {
+  const ids = new Set(shown.map((h) => h['@id']));
+  return [...shown, ...page.filter((h) => !ids.has(h['@id']))];
+};
+
+// The quick types depend on the query only, not on filters, sort or page.
+const quickMemo = lru<Promise<Record<string, Hit[]>>>(20);
+const remember = (k: string, p: Promise<Record<string, Hit[]>>) => (quickMemo.set(k, p), p);
+/**
+ * Quick tiles are extras: a slow one never holds back the listing. In a
+ * browser they get 1.5 s; on a server (no document) less than its render budget.
+ */
+const server = typeof document === 'undefined';
+const QUICK_GRACE_MS = server ? 300 : 1500;
+const LATE = Symbol('late');
+const soon = <T>(p: Promise<T>) => {
+  let timer: ReturnType<typeof setTimeout>;
+  const late = new Promise<typeof LATE>((r) => (timer = setTimeout(() => r(LATE), QUICK_GRACE_MS)));
+  return Promise.race([p, late]).finally(() => clearTimeout(timer));
+};
+
+/** Range selections over fields not known to be numeric: their values are looked up before the search (`asValues`). */
+const unknownRanges = (cfg: ListingConfig, q: Query) => Object.keys(q.filters).filter((f) => isRange(q.filters[f]) && !cfg.facets.includes(f) && kinds.get(f) !== 'range');
+
+/** The products request of q (`omit`: without that field's selection, for its own facet values). */
+const listingRequest = (g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query, omit?: string, size = cfg.size, asValues: Record<string, string[]> = {}): ListingRequest => ({
+  endpoint: route.endpoint,
+  surface: cfg.surface,
+  type: g.itemType ?? 'product',
+  query: q.q,
+  scope: q.scope,
+  filters: filterTree(route, q, omit, cfg.baseFilters, asValues),
+  sort: toSort(q.sort),
+  size,
+  fields: cfg.fields,
+});
+
+/**
+ * The first request listingQuery() makes for q (page 1 of its products),
+ * exactly: a prefetch of it (./intent.ts) comes back as `pre`. null when that
+ * request depends on a lookup first (a range over a field holding its numbers
+ * as text).
+ */
+export const firstRequest = (g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query): ListingRequest | null => (unknownRanges(cfg, q).length ? null : listingRequest(g, cfg, route, q));
+
+/**
+ * The listing's data for a query: its first page, the facets of that result
+ * set, and on a search page the quick types. A selected facet's values come
+ * from the result set without its own selection, so it stays multi-select.
+ * `pre`: the first page of products, fetched already (firstRequest(),
+ * prefetched on intent): not asked again. Later pages are appended to a
+ * result by listingMore(), one cursor request each: no request ever follows a
+ * chain of cursors.
+ *
+ * `onProducts`: called with the
+ * products as soon as they are here (`pending`), before the facets, which
+ * need their result set's guid and so a request after them. `onQuick`: the
+ * quick types never wait for (where they do not sit above the products):
+ * the result comes without them if they are not here yet (`quickPending`),
+ * and they land in it later, `onQuick` called with it then.
+ */
+export const listingQuery = async (api: Api, g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query, signal?: AbortSignal, pre?: Page, onProducts?: (r: ListingResult) => void, onQuick?: (r: ListingResult) => void): Promise<ListingResult> => {
+  // A range selection over a field that may not be a numeric one (a page's
+  // own facet, e.g. a parameter holding its numbers as text): if the API facets
+  // it as terms, the range is the values within it, from the values of the
+  // whole scope or query (a superset is harmless in an `in`). Asked once per
+  // scope; the configured facets' ranges are taken as numeric.
+  const asValues: Record<string, string[]> = {};
+  const unknown = unknownRanges(cfg, q);
+  if (unknown.length) {
+    const k = JSON.stringify([cfg.surface, q.q, q.scope, unknown]);
+    const fx =
+      textValues.get(k) ??
+      (() => {
+        const p = api
+          .search({ endpoint: route.endpoint, surface: cfg.surface, type: g.itemType ?? 'product', query: q.q, scope: q.scope, filters: cfg.baseFilters, size: 1 }, signal)
+          .then((r) => api.facets(r.guid, unknown.map((field) => ({ field, size: 1000 })), signal));
+        textValues.set(k, p);
+        p.catch(() => textValues.delete(k));
+        return p;
+      })();
+    const data = await fx;
+    for (const f of unknown) {
+      if (data[f]?.type) kinds.set(f, data[f].type);
+      if (data[f]?.type === 'terms') asValues[f] = (data[f].values ?? []).map(String).filter((v) => inRange(v, q.filters[f][0]));
+    }
+  }
+  const req = (omit?: string, size = cfg.size): ListingRequest => listingRequest(g, cfg, route, q, omit, size, asValues);
+  const quickKey = JSON.stringify([cfg.surface, q.q]);
+  const wantsQuick = route.endpoint === 'search' && !!q.q && !!cfg.quick?.length;
+  const quick =
+    wantsQuick && cfg.quick
+      ? quickMemo.get(quickKey) ?? remember(quickKey, (() => {
+          let failed = false;
+          let aborted = false;
+          const p: Promise<Record<string, Hit[]>> = Promise.all(
+            cfg.quick.map((x) =>
+              api
+                // Shared across renders of the query: not aborted with one (a server
+                // render's budget does bound them: nothing runs past its answer).
+                .search({ endpoint: 'search', surface: cfg.surface, type: x.type, query: q.q, size: x.size, fields: x.fields }, server ? signal : undefined)
+                .then((p) => [x.type, p.hits] as const)
+                .catch((e) => {
+                  if ((e as Error)?.name === 'AbortError') aborted = true; // a render's budget: not the lookup failing
+                  else failed = true;
+                  return [x.type, [] as Hit[]] as const; // quick tiles are optional
+                }),
+            ),
+          ).then((pairs) => {
+            const mine = () => quickMemo.get(quickKey) === p;
+            // Cut short: the next render asks again. Failed: again in a few seconds (not on every render in an outage).
+            if (aborted) mine() && quickMemo.delete(quickKey);
+            else if (failed) (setTimeout(() => mine() && quickMemo.delete(quickKey), 5000) as any).unref?.();
+            return Object.fromEntries(pairs);
+          });
+          return p;
+        })())
+      : Promise.resolve({});
+  // The quick types as they are when the products are shown early: not later (they sit above the grid).
+  let quickNow: Record<string, Hit[]> | undefined = wantsQuick ? undefined : {};
+  quick.then((v) => (quickNow = v), () => {});
+  const first = pre ?? (await api.search(req(), signal));
+  const facetsOf = async (): Promise<Record<string, FacetData>> => {
+    const size = cfg.facetSize ?? 50;
+    const fields = facetFields(cfg, q);
+    const own = fields.filter((f) => !q.filters[f]?.length);
+    const selected = fields.filter((f) => q.filters[f]?.length);
+    const parts = await Promise.all([
+      own.length ? api.facets(first.guid, own.map((field) => ({ field, size })), signal) : {},
+      ...selected.map(async (field) => {
+        const without = await api.search(req(field, 1), signal);
+        return api.facets(without.guid, [{ field, size }], signal);
+      }),
+    ]);
+    const out: Record<string, FacetData> = Object.assign({}, ...parts);
+    for (const [f, d] of Object.entries(out)) if (d?.type) kinds.set(f, d.type);
+    return out;
+  };
+  // `emptyValues`: the page's values without the shopper's filters, from its
+  // unfiltered result (remembered), else asked once per scope or query.
+  const allKey = JSON.stringify([cfg.surface, q.q, q.scope, facetFields(cfg, q)]);
+  const narrowed = Object.keys(q.filters).length > 0 || q.flags.length > 0;
+  const allOf = (): Promise<Record<string, FacetData>> => {
+    const memo = unfiltered.get(allKey);
+    if (memo) return memo;
+    const size = cfg.facetSize ?? 50;
+    const p = api
+      .search({ endpoint: route.endpoint, surface: cfg.surface, type: g.itemType ?? 'product', query: q.q, scope: q.scope, filters: cfg.baseFilters, size: 1 }, signal)
+      .then((r) => api.facets(r.guid, facetFields(cfg, q).map((field) => ({ field, size })), signal));
+    unfiltered.set(allKey, p);
+    p.catch(() => unfiltered.delete(allKey));
+    return p;
+  };
+  // Facets are extras too: without them the results still show.
+  let partial = false;
+  const facets =
+    first.hits.length || Object.keys(q.filters).length
+      ? facetsOf().catch((e) => ((partial = true), (e as Error)?.name === 'AbortError' || reportError('facets', e), {}))
+      : {};
+  // Optional too: without them no value shows as empty.
+  const all = cfg.emptyValues && narrowed ? allOf().catch(() => undefined) : undefined;
+  // The products now, the facets when they come: a request (theirs needs
+  // this result set's guid) the shopper would otherwise wait for.
+  const early: ListingResult | null =
+    onProducts && isPromise(facets)
+      ? { hits: first.hits, total: first.total, guid: first.guid, page: 1, cursor: first.cursor, status: first.status, facets: {}, quick: quickNow ?? {}, pending: true, ...(quickNow ? {} : { quickPending: true }) }
+      : null;
+  if (early) onProducts!(early);
+  // Not waited for (onQuick): the facets alone hold the result.
+  const [facetData, quickHits, facetsAll] = await Promise.all([facets, onQuick ? quickNow ?? LATE : soon(quick), all]);
+  if (cfg.emptyValues && !narrowed && !partial && Object.keys(facetData).length) unfiltered.set(allKey, Promise.resolve(facetData));
+  // Shown early without them and not where they may come late: they come
+  // with a later render, not this one (above the grid, they would push it down).
+  const late = quickHits === LATE || (!onQuick && !!early && !Object.keys(early.quick).length && quickHits !== early.quick);
+  const result: ListingResult = { hits: first.hits, total: first.total, guid: first.guid, page: 1, cursor: first.cursor, status: first.status, facets: facetData, facetsAll, quick: late ? early?.quick ?? {} : (quickHits as Record<string, Hit[]>), partial: partial || undefined, ...(unknown.length ? { asValues } : {}) };
+  // Late tiles land in this result, which the listing caches: a render from
+  // the cache shows them; onQuick renders them as they come.
+  if (late && onQuick) result.quickPending = true;
+  if (late)
+    quick.then((qh) => {
+      result.quick = qh;
+      if (!result.quickPending) return;
+      delete result.quickPending;
+      onQuick!(result);
+    });
+  return result;
+};
+
+/** Another page can be appended to `res` ("show more"): the set goes on, and it holds fewer than MAX_PAGE pages. */
+export const hasMore = (res: Pick<ListingResult, 'status' | 'cursor' | 'page'>) => res.status === 'more' && !!res.cursor && res.page < MAX_PAGE;
+
+/**
+ * "Show more": `res` with its next page appended, from its cursor (one
+ * request, the same filter tree, sort and fields as its first page: a cursor
+ * is bound to them). The facets and quick types are the result set's, kept.
+ */
+export const listingMore = async (api: Api, g: GlobalConfigType, cfg: ListingConfig, route: Route, q: Query, res: ListingResult, signal?: AbortSignal): Promise<ListingResult> => {
+  if (!hasMore(res)) return res;
+  const p = await api.search({ ...listingRequest(g, cfg, route, q, undefined, cfg.size, res.asValues), cursor: res.cursor! }, signal);
+  return { ...res, hits: append(res.hits, p.hits), page: res.page + 1, cursor: p.cursor, status: p.status };
+};