@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/widgets/listing/element.ts

@@ -0,0 +1,1772 @@
+// A result listing (search results, category listing) as a light-DOM custom
+// element. The URL is the single source of truth: UI actions write the URL
+// (in the host's own parameter format where the route defines one), URL
+// changes (ours, the host router's, back/forward) re-derive state. Element
+// lifecycle = cleanup, so a host framework destroying its page takes our
+// listeners with it. Markup comes from the widget's templates
+// (search-box and its includes); this file only owns state and behaviour.
+//
+// Server-rendered pages (the edge render service): the page arrives with our listing in
+// it, rendered from the same templates, plus its state (query + API result)
+// in a JSON script before the element. The element then adopts it: the state
+// seeds the result cache and the first render hydrates the server's markup
+// (lit SSR) instead of rebuilding it, so nothing is fetched or repainted on
+// load. From then on the listing is client-side as usual.
+
+import { borrow, contrastToggle, liveRegion, useContrast } from '../../core/a11y';
+import { activateByKey, byKeyboard, focusables, trapTab } from '../../core/a11y-keys';
+import { mark, reportError } from '../../core/health';
+import { claim } from '../../core/reconciler';
+import { afterLayout, rememberHeight } from '../../core/hold';
+import { hasPrefetch, observe, peekPrefetch, peekProducts, productsChannel, putPrefetch, takePrefetch, typicalMs, type Prefetch } from '../../core/prefetch';
+// Through the support chunk, which every widget loads with its own (src/main.ts load()).
+import { firstRowCount, firstRowImages, imageHelpers, imageOf, preloadImages, settleImages, warmImages } from '../../core/support';
+import { view } from '../../core/templates';
+import { afterFrame, isPromise } from '../../core/scheduler';
+import { onUrlChange } from '../../core/sense';
+import { layered, setCss } from '../../core/styles';
+import type { Takeover } from '../../core/takeover';
+import { canon, pageKey, writeUrl } from '../../core/url';
+import { lru } from '../../core/storage';
+import type { WidgetContext } from '../../main';
+import type { Link } from '../../types';
+import { facetFields, handsBack, nextState, stateOf, type Query, type Route, type UiState } from './state';
+import { firstRequest, hasMore, listingMore, listingQuery, type ListingConfig, type ListingResult } from './query';
+import { flowKey, notAbove, onQuickLanded, quickChannel } from './flow';
+import { firstPages, targetOf, thrifty, watchIntent } from './intent';
+import type { Page } from '../../api';
+import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, viewport, type ListingView, type SsrState } from './view';
+import { dropStash, readStash, writeStash, type Stash } from './stash';
+import { keepViewport, leavingLink, nearEnd, preconnectImages, restoreScroll, scrollSpot } from './instant';
+import { watch } from '../../core/tiles';
+
+/** A re-render answered within DIM_MS (no dim shown) fades its list in from this opacity, over FADE_MS. */
+const FADE_FROM = 0.6;
+const FADE_MS = 150;
+/** A hidden first render in frames: the first STEP tiles, then about BUDGET ms of rendering per frame. */
+const STEP = 4;
+/** Tiles drawn (with the facets) before ours shows, per 900 px of viewport height: two rows of four on a wide screen, four of two on a phone. */
+const SHOW_TILES = 8;
+/** A unit already drawn, run again by a render, against one it adds (a production storefront at 4x: ~0.1-0.3; 0.25 errs on the safe side). */
+const RERUN = 0.25;
+
+/**
+ * A step's rendering time (ms). A step is one render, sized from what a tile
+ * and a facet group cost so far, with what is there run again (RERUN). Its
+ * task holds more than the render (the scope, the hooks once complete): 16
+ * gave tasks of 18-21 ms on a production storefront at 4x CPU, 12 keeps them within a 16 ms
+ * frame (2026-10-12). 40 gave steps of 32-49 ms (tried 2026-10-11). Each
+ * step's time is in the "rendered in" / "drawn in" mark.
+ */
+const BUDGET = 12;
+/**
+ * Back after longer away than this (a page restored from the back/forward
+ * cache, or one rendered from our stash) revalidates its results; a quick
+ * round trip to a product shows them as left.
+ */
+const BFCACHE_STALE_MS = 60_000;
+/** The same products, whatever their order: an API that orders ties anew on every request is not a change. */
+export const sameHits = (a: ListingResult, b: ListingResult) => {
+  const ids = (r: ListingResult) => r.hits.map((h) => h['@id']).sort().join('\n');
+  return a.hits.length === b.hits.length && ids(a) === ids(b);
+};
+
+/**
+ * Per-page-session result cache, keyed by the resolved query: what is loaded
+ * for that state (its first page, and the pages "show more" appended since),
+ * so back/forward to it, or a host re-creating our element, shows it as left.
+ */
+const cache = lru<ListingResult>(30, Infinity);
+/** "Show more" fetched ahead (prefetchNextPage, intent on the button): the next result of a result, by the result. */
+const nextOf = new WeakMap<ListingResult, Promise<ListingResult>>();
+/** The same page (a result's URL, often relative, and a link's href). */
+const sameUrl = (u: unknown, href: string) => {
+  try {
+    return new URL(String(u ?? ''), location.href).href === href;
+  } catch {
+    return false;
+  }
+};
+const keyOf = (q: Query) => JSON.stringify([q.q, q.scope, q.filters, q.flags, q.sort]);
+
+type Hydrate = (v: unknown, c: HTMLElement | ShadowRoot) => void;
+
+export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeover, route: Route) => {
+  const cfg = ctx.config;
+  const t = ctx.t;
+  for (const [i, css] of ctx.styles.entries()) setCss(`itg:${route.id}:${i}`, css);
+  setCss('listing-loading', layered(LOADING_CSS));
+  useContrast();
+  const query = (q: Query, signal?: AbortSignal, pre?: Page, onProducts?: (r: ListingResult) => void) => {
+    const t0 = performance.now();
+    const p = listingQuery(ctx.api, ctx.global, cfg, route, q, signal, pre, onProducts, quickChannel(route.id));
+    // A whole listing (not a first page fetched already): how long a fresh one takes here.
+    if (!pre) p.then((r) => !r.partial && observe(performance.now() - t0), () => {});
+    return p;
+  };
+  /** "Show more": `res` with its next page, the one fetched ahead if there is one (never asked twice). */
+  const more = (q: Query, res: ListingResult) => {
+    let p = nextOf.get(res);
+    if (!p) {
+      p = listingMore(ctx.api, ctx.global, cfg, route, q, res);
+      nextOf.set(res, p);
+      p.catch(() => nextOf.delete(res)); // a failed one: the click asks again
+    }
+    return p;
+  };
+  /**
+   * The result a prefetch brings, or a fresh request's. A page's own
+   * prefetch (the entry's, started for this load) is the request: it is
+   * waited for. A speculation (a phrase typed) is reused while it is on time:
+   * once it is older than twice a fresh request's usual duration on this page
+   * (a stuck or slow answer), a fresh request starts next to it and the first
+   * answer wins; the shopper never waits on a speculation much longer than
+   * asking anew would take. A failed or empty one (null): asked anew.
+   */
+  const fromPrefetch = (pre: Prefetch | undefined, q: Query, signal: AbortSignal, onProducts?: (r: ListingResult) => void): Promise<ListingResult> => {
+    if (!pre) return query(q, signal, undefined, onProducts);
+    if (pre.done || !pre.spec) {
+      // Its products first, while its facets are still asked for.
+      if (!pre.done && onProducts) pre.products?.then((r) => !pre.done && onProducts(r));
+      return pre.p.then((r) => r ?? query(q, signal, undefined, onProducts));
+    }
+    return new Promise<ListingResult>((ok, fail) => {
+      let fresh: AbortController | undefined;
+      let over = false;
+      const win = (r: ListingResult, prefetched: boolean) => {
+        if (over) return;
+        over = true;
+        clearTimeout(timer);
+        if (prefetched) fresh?.abort(); // it came first after all: the fresh one is not needed
+        else pre.abort?.(); // the fresh one did: the speculation is not needed
+        ok(r);
+      };
+      const ask = () => {
+        if (fresh || over) return;
+        const f = (fresh = new AbortController());
+        signal.addEventListener('abort', () => f.abort(), { once: true });
+        mark(`${route.id} prefetch overdue: asking anew`);
+        query(q, f.signal).then(
+          (r) => win(r, false),
+          (e) => !over && ((over = true), fail(e)),
+        );
+      };
+      const timer = window.setTimeout(ask, Math.max(0, pre.at + 2 * typicalMs() - performance.now()));
+      pre.p.then((r) => (r ? win(r, true) : ask()), ask);
+    });
+  };
+  // Filter clicks that render at once (./intent.ts): first pages fetched on intent, by their request.
+  const early = firstPages();
+  const prefetchFilters = ctx.global.prefetchFilters !== false;
+  const visitOf = (q: Query) => JSON.stringify([q.q, q.scope]);
+  const earlyKey = (q: Query) => {
+    const r = firstRequest(ctx.global, cfg, route, q);
+    return r && JSON.stringify(r);
+  };
+
+  // Server-rendered listing: its state seeds the cache, its query skips
+  // resolve(). Adopted when the server's element connects: at our boot, or
+  // later when the bundle ran before the fragment was parsed (an async include).
+  const seeded = new Map<string, Query>();
+  let hydrate: Promise<Hydrate> | null = null;
+  const adopt = () => {
+    try {
+      // Our script by type too: an element of the host with that id (clobbering) is not our state.
+      const st = JSON.parse(document.querySelector(`script#${ssrStateId(route.id)}[type="application/json"]`)?.textContent || 'null') as SsrState | null;
+      if (!st || pageKey(st.href) !== pageKey(location.href)) return false;
+      if (seeded.has(pageKey(st.href))) return true; // this state, adopted already (at our start)
+      seeded.set(pageKey(st.href), st.query);
+      if (!st.result.partial) cache.set(keyOf(st.query), st.result);
+      hydrate ??= import('@lit-labs/ssr-client').then((m) => m.hydrate as Hydrate);
+      hydrate.catch(() => {}); // a failed chunk: the listing renders anew (sync())
+      mark(`${route.id} server-rendered, adopted`);
+      tk.serverRendered(); // the include may have arrived after our boot: this visit is the server's
+      // A client-side copy may already sit at the anchor: the server's wins.
+      for (const el of document.querySelectorAll(`${route.tag}:not([data-lbx-ssr])`)) el.remove();
+      return true;
+    } catch (e) {
+      reportError(`${route.id} ssr state`, e);
+      return false;
+    }
+  };
+  if (document.querySelector(`${route.tag}[data-lbx-ssr]`)) adopt();
+
+  // A result stashed for this page load (./stash.ts): the query typed on the
+  // previous page, or the listing as the shopper left it (Back). Seeded like a
+  // server-rendered state: the first render needs no request.
+  let stashed: Stash | null = null;
+  /** The page's templates prepared ahead (`rehearse`), once. */
+  let rehearsed = false;
+  if (!seeded.size) {
+    stashed = readStash(route.id, location.href);
+    if (stashed) {
+      seeded.set(pageKey(location.href), stashed.query);
+      cache.set(keyOf(stashed.query), stashed.result);
+      mark(`${route.id} from stash (${stashed.kind}, ${stashed.result.hits.length} hits)`);
+      // A prerendered page reads (and drops) it in a copy of sessionStorage; at
+      // its activation the opener's storage, still holding it, comes back: used once.
+      const at = location.href;
+      if (stashed.kind === 'spec' && (document as any).prerendering) document.addEventListener('prerenderingchange', () => dropStash(at), { once: true });
+    }
+  }
+  const restoreOn = cfg.restoreOnBack !== false;
+  const skipOut = cfg.contentVisibility === true;
+
+  // The request for the URL we loaded on starts now, before the element exists.
+  const bootUrl = new URL(location.href);
+  if (!seeded.size && route.accepts(bootUrl) && !hasPrefetch(bootUrl.href)) {
+    // No query for this URL (a category the catalog does not know): hand the page
+    // back now, even if our element was never placed (their page has no anchor),
+    // unless the shopper has moved on meanwhile.
+    const stillHere = () => canon(location.href) === canon(bootUrl.href);
+    const { products, onProducts } = productsChannel();
+    putPrefetch(
+      bootUrl.href,
+      new Promise<Query | null>((ok) => ok(route.resolve(bootUrl))).then((q) => (q ? query(q, undefined, undefined, onProducts) : (stillHere() && tk.release(), null))),
+      { products },
+    );
+  }
+  // The first row's images, preloaded as soon as the result is in hand: the
+  // request for this load (the entry's on a search page, or the one above)
+  // usually arrives while the chunk's templates, the fonts or the anchor are
+  // still on their way. A server-rendered page has them in its HTML (the server renderer).
+  const imgs = ctx.global.images ?? {};
+  const preloadOn = imgs.preload !== false;
+  const warm = imgs.warm ?? 0;
+  const preloadRow = (res: ListingResult | null | undefined) => {
+    if (res?.hits.length) preloadImages(firstRowImages(imgs, res.hits.map(ctx.result)));
+  };
+  // From its products, when they come first (they show before the facets): before their tiles.
+  if (preloadOn && !seeded.size) peekProducts(bootUrl.href)?.then(preloadRow, () => {});
+  if (preloadOn && !seeded.size) peekPrefetch(bootUrl.href)?.then(preloadRow, () => {});
+  // A Back restore lands at the followed tile, not at the top: the images
+  // around it (the HTTP cache has them; started now, not after the render,
+  // the scroll and the lazy images' own layout). A typed query's page: its first row.
+  if (preloadOn && stashed) {
+    const results = stashed.result.hits.map(ctx.result);
+    const cols = Math.max(1, firstRowCount(imgs));
+    const href = stashed.kind === 'back' ? stashed.scroll?.href : undefined;
+    const at = href ? results.findIndex((r) => sameUrl(r.c.url, href)) : -1;
+    if (at < 0) preloadRow(stashed.result);
+    else {
+      const from = Math.max(0, at - (at % cols) - cols);
+      preloadImages(results.slice(from, from + 3 * cols).map((r, k) => imageOf(imgs, r, from + k, { eager: true })).filter((im) => im.src));
+    }
+  }
+  // A URL we can show at once, from cache (no hold). Not an empty category on a
+  // route that hands those back: that one is released, never shown.
+  tk.cached = (url) => {
+    try {
+      const q = route.resolve(url);
+      if (isPromise(q)) q.catch(() => {}); // warms the memo; sync() reports failures
+      const hit = q && !isPromise(q) ? cache.get(keyOf(q)) : undefined;
+      return !!hit && !handsBack(route, q as Query, hit.total);
+    } catch {
+      return false;
+    }
+  };
+
+  class LbxListing extends HTMLElement {
+    private ctrl: AbortController | null = null;
+    private unsub: (() => void) | null = null;
+    private href = '';
+    private current: Query | null = null;
+    private last: ListingResult | null = null;
+    /** The query `last` was rendered for. */
+    private lastQ: Query | null = null;
+    /** A resolve or fetch of ours is running (busy is ours to clear). */
+    private inFlight = false;
+    /** The state the template's links were built from (the last render). */
+    private shown: UiState | null = null;
+    /** The latest state asked for by a click, until it is rendered. */
+    private wanted: UiState | null = null;
+    private wantedHref: string | null = null;
+    /** Server markup we are not hydrating, parsed completely (see connectedCallback). */
+    private cleared: Promise<void> | null = null;
+    /**
+     * The server's markup, kept until our first render has succeeded: stale but
+     * real content beats an empty box (with SSI their listing is not there).
+     */
+    private server: ChildNode[] | null = null;
+    /** The click waiting for its turn (one per task: the latest wins). */
+    private pending = 0;
+    private v = view(this, ctx.templates);
+    private message: string | null = null;
+    /** Server markup waiting to be hydrated by the first render. */
+    private ssr: boolean | null = null;
+    private hydrateWith: Hydrate | null = null;
+    /** Cancels the next page's prefetch trigger (./instant.ts nearEnd). */
+    private ahead: (() => void) | null = null;
+    /** Intent on our controls (./intent.ts): the request of the state they lead to starts early. */
+    private intent: ReturnType<typeof watchIntent> | null = null;
+    /** View state not in the URL (scope.ui), kept for the visit (a category, a query). */
+    private ui: Record<string, unknown> = {};
+    private uiVisit = '';
+    /** The last render's template data: a view state change re-renders it. */
+    private drawn: Record<string, unknown> | null = null;
+    /** The URL the last render was drawn for (a view state change draws it again). */
+    private drawnUrl: URL | null = null;
+    /** Facet groups the shopper opened or closed, and the text in a group's search box, for the visit. */
+    private groupOpen: Record<string, boolean> = {};
+    private groupText: Record<string, string> = {};
+    private groupSaid = 0;
+    /**
+     * The open drawer's held changes (`facetsApply: 'staged'`): the state its
+     * controls lead to, not applied yet; null: nothing held. `stagedMode`:
+     * the drawer was opened where it stages.
+     */
+    private staged: UiState | null = null;
+    private stagedMode = false;
+    /** Renders started: a render in chunks stops when a newer one has started. */
+    private renders = 0;
+    // Accessibility (docs/ACCESSIBILITY.md, "Listings"): our status region (and
+    // the contrast toggle) ahead of the templates' markup; what the next shown
+    // render announces; where focus goes once it has rendered.
+    private a11y: { root: HTMLElement; live: ReturnType<typeof liveRegion> } | null = null;
+    private toSay: string | null = null;
+    /** The next render is silent (a background revalidation). */
+    private quiet = false;
+    /** "Show more" from the keyboard: focus goes to the first new tile. */
+    private moreByKey = false;
+    private focusWas: Element | null = null;
+    private shownBefore = 0;
+    /** The drawer's opener (focus goes back to it) and the attributes lent to its panel. */
+    private drawerFrom: HTMLElement | null = null;
+    private panelAria: ReturnType<typeof borrow> | null = null;
+    /** Another state's results awaited (loading()): the timer that dims the list, and whether it has. */
+    private wait: { timer: number; dimmed: boolean } | null = null;
+    /** A wait that ended (loaded()) and whether it had dimmed the list: kept for the render that follows in the same task. */
+    private waited: { dimmed: boolean } | null = null;
+    /** The list's fade-in (fadeIn()). */
+    private fade: Animation | null = null;
+    /** A first render in steps under way: its products, and how a newer result of them (their facets) joins it. */
+    private stepping: { hits: unknown; take: (q: Query, res: ListingResult, url: URL) => void; again: () => void } | null = null;
+    /** Every tile's size, for while it is out of view (sizeTiles()). */
+    private sized: { ro: ResizeObserver; seen: WeakSet<Element> } | null = null;
+
+    /** When the page was hidden (pagehide): a restore from the back/forward cache after long is revalidated. */
+    private hiddenAt = 0;
+    private onPageHide = () => void (this.hiddenAt = Date.now());
+    /**
+     * Restored from the back/forward cache (pageshow, persisted): the page is as
+     * the shopper left it, from memory. Our own Back restore (./stash.ts) is not
+     * needed; after a while away, the results are revalidated in the background
+     * (re-rendered only if they changed, the viewport kept). A request in flight
+     * when the page froze needs nothing: Chrome evicts a cached page whose
+     * request completes there (its Back is then a page load), elsewhere it
+     * completes after the restore.
+     */
+    private onPageShow = (e: PageTransitionEvent) => {
+      if (!e.persisted) return;
+      dropStash(location.href);
+      mark(`${route.id} restored from the back/forward cache`);
+      const away = this.hiddenAt ? Date.now() - this.hiddenAt : 0;
+      if (away > BFCACHE_STALE_MS && this.last && this.lastQ && this.lastQ === this.current) this.revalidate(this.lastQ, this.last, new URL(location.href), this.href);
+    };
+
+    connectedCallback() {
+      onQuickLanded(route.id, (r) => this.quickIn(r));
+      // Not in the constructor: an element the parser creates after our class
+      // is defined (an async include) is constructed before its attributes are set.
+      if (this.ssr == null) {
+        // Every server element is checked against its own state (a later visit's page is another page).
+        this.ssr = this.hasAttribute('data-lbx-ssr') && adopt();
+        // Ours from now on, before it drops its marker (the reconciler keeps it).
+        if (this.ssr) claim(route.id, this);
+        // Server markup whose state we cannot use (another URL: a param the page
+        // stripped, another host name): ours replaces it once it has rendered.
+        // A parser-created element (an async bundle ran first) is still getting
+        // its children: kept once they are all there (sync() awaits that).
+        else if (this.hasAttribute('data-lbx-ssr')) {
+          claim(route.id, this);
+          const keep = () => void (this.server = [...this.childNodes]);
+          if (document.readyState === 'loading') this.cleared = new Promise<void>((r) => document.addEventListener('DOMContentLoaded', () => (keep(), r()), { once: true }));
+          else keep();
+        }
+        // A copy of our element (a Turbo snapshot restored): lit would render a second listing after it.
+        else this.replaceChildren();
+      }
+      if (!this.ssr && this.className !== (cfg.rootClass ?? '')) this.className = cfg.rootClass ?? '';
+      // A named region (WCAG 1.3.1, 2.4.1), focusable from script only: where
+      // focus goes when a render removed the focused control.
+      if (!this.hasAttribute('role')) this.setAttribute('role', 'region');
+      if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', t('label'));
+      if (!this.hasAttribute('tabindex')) this.tabIndex = -1;
+      this.unsub = onUrlChange(() => this.resync());
+      // Product clicks and add-to-carts on our tiles: the framework's, never a template's (core/tiles.ts).
+      watch(this, { list: `lbx_${route.id}`, global: ctx.global, results: () => this.last?.hits.map(ctx.result) ?? [] });
+      this.addEventListener('click', this.onClick);
+      this.addEventListener('keydown', this.onKey);
+      this.addEventListener('focusout', this.onFocusOut);
+      document.addEventListener('click', this.onOutside, true);
+      document.addEventListener('pointerdown', this.onOutside, true);
+      addEventListener('pagehide', this.onPageHide);
+      addEventListener('pageshow', this.onPageShow);
+      if (prefetchFilters) this.intent ??= watchIntent(this, (el) => this.onIntent(el));
+      // Microtask: runs before paint (no empty frame) but outside the
+      // reconciler's placement pass.
+      queueMicrotask(() => this.resync());
+    }
+
+    disconnectedCallback() {
+      mark(`${route.tag} disconnected`);
+      this.unsub?.();
+      this.removeEventListener('click', this.onClick);
+      this.removeEventListener('keydown', this.onKey);
+      this.removeEventListener('focusout', this.onFocusOut);
+      document.removeEventListener('click', this.onOutside, true);
+      document.removeEventListener('pointerdown', this.onOutside, true);
+      removeEventListener('pagehide', this.onPageHide);
+      removeEventListener('pageshow', this.onPageShow);
+      this.ctrl?.abort();
+      this.ahead?.();
+      this.intent?.stop();
+      this.intent = null;
+      this.sized?.ro.disconnect();
+      this.sized = null;
+      // Not the pending click: the reconciler puts this same element back after a
+      // host re-render, and the click's timer then still applies it.
+      this.href = ''; // re-sync if we are ever re-attached
+    }
+
+    /** sync(), never throwing into the page (it runs from timers and listeners). */
+    private resync(url?: URL) {
+      this.sync(url).catch((e) => reportError(`${route.id} sync`, e));
+    }
+
+    /**
+     * The filter drawer (narrow screens): [data-lbx-drawer="open|close"]
+     * links. Without JavaScript they work through :target; with it, a
+     * state attribute on the element, so the URL keeps no #fragment.
+     */
+    private onClick = (e: MouseEvent) => {
+      const target = e.target as Element;
+      // A menu in the host's markup (their dropdown classes): [data-lbx-toggle]
+      // opens/closes its [data-lbx-menu] ancestor by a data-lbx-open attribute
+      // (the integration's CSS maps it onto their open state).
+      const tg = target.closest?.('[data-lbx-toggle]');
+      if (tg && this.contains(tg)) {
+        e.preventDefault();
+        // Ours alone: host code delegating on the same (their) dropdown classes must not toggle it too.
+        e.stopPropagation();
+        const menu = tg.closest('[data-lbx-menu]');
+        // From the keyboard (a click without a pointer): focus into the menu.
+        if (menu) setMenu(menu, !menu.hasAttribute('data-lbx-open'), byKeyboard(e));
+        return;
+      }
+      const d = target.closest?.('[data-lbx-drawer]');
+      if (!d || !this.contains(d)) {
+        // A link to another page (a product): remembered for Back.
+        const away = restoreOn && leavingLink(e, this);
+        if (away) this.leave(away);
+        return;
+      }
+      e.preventDefault();
+      const what = d.getAttribute('data-lbx-drawer');
+      // "apply" commits what the drawer holds (staged) and closes; "close" (and the overlay) discards it.
+      if (what === 'apply') this.applyStaged();
+      this.setDrawer(what === 'open', d as HTMLElement);
+    };
+
+    /** Changes go to the drawer's held state instead of the URL: it is open, where it stages. */
+    private staging() {
+      return this.stagedMode && this.hasAttribute('data-drawer-open');
+    }
+
+    /** The drawer's held changes, applied: one request, one history entry. */
+    private applyStaged() {
+      const next = this.staged;
+      this.staged = null;
+      if (next) this.navigate(next);
+    }
+
+    /** The drawer's held changes dropped: it shows the applied state again. */
+    private discardStaged() {
+      if (!this.staged) return;
+      this.staged = null;
+      this.redraw();
+    }
+
+    /**
+     * The drawer as a modal dialog while it is open (WCAG 2.4.3, 2.1.2): its
+     * panel (`[data-lbx-drawer-panel]` in the integration's markup) gets the
+     * dialog's role and name, focus moves into it and stays there (Tab
+     * cycles), Escape closes it, and focus goes back to the button that opened
+     * it. On wide screens the same markup is a sidebar: the role is lent while
+     * open only. Without a panel: the buttons' state, Escape and the way back.
+     */
+    private setDrawer(open: boolean, from?: HTMLElement) {
+      const was = this.hasAttribute('data-drawer-open');
+      this.toggleAttribute('data-drawer-open', open);
+      for (const b of this.querySelectorAll('[data-lbx-drawer="open"]')) b.setAttribute('aria-expanded', String(open));
+      const panel = this.querySelector('[data-lbx-drawer-panel]');
+      // Closed other than by its apply button: what it held goes.
+      if (!open) this.discardStaged();
+      if (open && !was) {
+        this.stagedMode = atWidth(cfg.facetsApply, 'instant', viewport) === 'staged';
+        this.drawerFrom = (from?.getAttribute('data-lbx-drawer') === 'open' ? from : document.activeElement) as HTMLElement | null;
+        if (panel) {
+          const a = (this.panelAria = borrow(panel));
+          if (!panel.hasAttribute('role')) a.set('role', 'dialog');
+          a.set('aria-modal', 'true');
+          if (!panel.hasAttribute('aria-label') && !panel.hasAttribute('aria-labelledby')) a.set('aria-label', t('drawer'));
+          if (!panel.hasAttribute('tabindex')) a.set('tabindex', '-1');
+        }
+        // Once it is shown: focus() would force the page's style and layout in this task.
+        afterFrame(() => {
+          if (!this.hasAttribute('data-drawer-open')) return;
+          const root = panel ?? this;
+          (focusables(root).find((el) => el.getAttribute('data-lbx-drawer') !== 'open') ?? (root as HTMLElement)).focus();
+        });
+      } else if (!open && was) {
+        this.panelAria?.restore();
+        this.panelAria = null;
+        const back = this.drawerFrom;
+        this.drawerFrom = null;
+        const at = document.activeElement;
+        if (back?.isConnected && (!at || at === document.body || this.contains(at))) afterFrame(() => back.focus());
+      }
+    }
+
+    /**
+     * Keys: Escape closes our open menu (focus back on its button) or the
+     * drawer; the arrows move through an open menu's items; Tab stays inside
+     * the open drawer; Enter and Space work on role="button" markup.
+     */
+    private onKey = (e: KeyboardEvent) => {
+      const target = e.target as Element;
+      const menu = target.closest?.('[data-lbx-menu][data-lbx-open]');
+      if (e.key === 'Escape') {
+        if (menu && this.contains(menu)) {
+          e.preventDefault();
+          e.stopPropagation(); // ours, not a host modal's
+          setMenu(menu, false);
+          triggerOf(menu)?.focus();
+        } else if (this.hasAttribute('data-drawer-open')) {
+          e.preventDefault();
+          e.stopPropagation();
+          this.setDrawer(false);
+        }
+        return;
+      }
+      if (menu && (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+        const items = focusables(menu).filter((el) => !el.hasAttribute('data-lbx-toggle'));
+        if (!items.length) return;
+        e.preventDefault();
+        const i = items.indexOf(target as HTMLElement);
+        const next = i < 0 ? (e.key === 'ArrowDown' ? 0 : items.length - 1) : (i + (e.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length;
+        items[next].focus();
+        return;
+      }
+      if (e.key === 'Tab' && this.hasAttribute('data-drawer-open')) {
+        const panel = this.querySelector('[data-lbx-drawer-panel]');
+        if (panel) trapTab(e, panel);
+        return;
+      }
+      activateByKey(e, this);
+    };
+
+    /** Focus leaving an open menu (Tab past it) closes it. */
+    private onFocusOut = (e: FocusEvent) => {
+      const menu = (e.target as Element).closest?.('[data-lbx-menu][data-lbx-open]');
+      if (menu && !(e.relatedTarget && menu.contains(e.relatedTarget as Node))) setMenu(menu, false);
+    };
+
+    /** After a render: our status region in place, the menus' and drawer's state on their buttons, focus where it belongs. */
+    private afterA11y() {
+      if (!this.a11y) {
+        const root = document.createElement('div');
+        root.setAttribute('data-lbx-a11y', '');
+        const live = liveRegion();
+        root.append(live.el);
+        if (ctx.global.contrastToggle) root.append(contrastToggle(t('contrast')));
+        this.a11y = { root, live };
+      }
+      if (this.firstChild !== this.a11y.root) this.prepend(this.a11y.root);
+      for (const m of this.querySelectorAll('[data-lbx-menu]')) setMenu(m, m.hasAttribute('data-lbx-open'));
+      for (const b of this.querySelectorAll('[data-lbx-drawer="open"]')) b.setAttribute('aria-expanded', String(this.hasAttribute('data-drawer-open')));
+      const was = this.focusWas;
+      this.focusWas = null;
+      const tile = this.moreByKey ? this.querySelector('[data-lbx-list]')?.children[this.shownBefore] : null;
+      this.moreByKey = false;
+      // "Show more" from the keyboard: on to the first new tile (WCAG 2.4.3).
+      // A render that removed the focused control (a chip, the last "Show
+      // more"): the region, not the start of the page.
+      const to = tile
+        ? mainControl(tile)
+        : was && !was.isConnected
+          ? (this as HTMLElement)
+          : null;
+      if (to) afterFrame(() => to.isConnected && to.focus());
+    }
+
+    /** The pending announcement, once ours is shown (a hidden region is not read). */
+    private speak() {
+      if (this.toSay && this.a11y) this.a11y.live.say(this.toSay);
+      this.toSay = null;
+    }
+
+    /**
+     * Our menus (<details data-lbx-dropdown>, [data-lbx-menu]) close on a click
+     * or a press outside them: iOS Safari sends no click for a tap on what is
+     * not clickable (a heading, the page's background), only the pointer events.
+     */
+    private onOutside = (e: Event) => {
+      for (const d of this.querySelectorAll('details[data-lbx-dropdown][open]')) if (!d.contains(e.target as Node)) d.removeAttribute('open');
+      for (const d of this.querySelectorAll('[data-lbx-menu][data-lbx-open]')) if (!d.contains(e.target as Node)) setMenu(d, false);
+    };
+
+    /**
+     * Busy lives on our element itself, set directly and never bound in a
+     * template: instant feedback in an event handler without rendering anything.
+     */
+    private setBusy(b: boolean) {
+      this.setAttribute('aria-busy', String(b));
+      if (b) this.waited = null; // show more: its render is not a new state
+      else if (this.wait) this.waited = this.loaded(); // for the render that follows, in this task
+    }
+
+    /**
+     * Another state's results asked for while ours shows (a filter, a sort,
+     * back/forward): busy, and once the wait is longer than DIM_MS,
+     * `data-lbx-loading`, which dims the list (LOADING_CSS). From a timer, not
+     * a CSS transition-delay: a quick answer starts no transition at all
+     * (Chrome ran a delayed one on under the fade-in, the list dimming after
+     * it: a production storefront, 2026-10-12). Ends with the render of the new state, or busy's end.
+     */
+    private loading() {
+      this.setBusy(true);
+      if (tk.state !== 'ours' || !this.last || this.wait) return;
+      const w: { timer: number; dimmed: boolean } = (this.wait = { timer: 0, dimmed: false });
+      w.timer = window.setTimeout(() => ((w.dimmed = true), this.setAttribute('data-lbx-loading', '')), DIM_MS);
+    }
+
+    /** The wait ends: its dim, if shown, removed (CSS fades the list back). */
+    private loaded() {
+      const w = this.wait;
+      if (!w) return null;
+      clearTimeout(w.timer);
+      this.wait = null;
+      if (w.dimmed) this.removeAttribute('data-lbx-loading');
+      return w;
+    }
+
+    /** UI -> URL. The resulting URL change drives sync(). In a drawer that stages: held there, nothing fetched. */
+    go(patch: Partial<UiState>) {
+      if (!this.current) return;
+      this.intent?.cancel(); // a dwell still pending: this click's own state is what is fetched now
+      if (this.staging()) {
+        this.staged = nextState(this.staged ?? this.wanted ?? stateOf(this.current), this.shown ?? stateOf(this.current), patch);
+        return this.redraw();
+      }
+      this.navigate(nextState(this.wanted ?? stateOf(this.current), this.shown ?? stateOf(this.current), patch));
+    }
+
+    /** To a whole state: its URL written and fetched, in later tasks (respond first). */
+    private navigate(next: UiState) {
+      if (!this.current) return;
+      const url = route.write(new URL(location.href), next);
+      // Already what we show or are fetching (e.g. a drawer's Apply after its
+      // fields applied on Enter): nothing to do, and nothing would clear busy.
+      if (canon(url.href) === this.href) {
+        clearTimeout(this.pending);
+        this.wanted = this.wantedHref = null;
+        if (!this.inFlight) this.setBusy(false);
+        return;
+      }
+      this.wanted = next;
+      this.wantedHref = canon(url.href);
+      // Respond first, work later: the fetch and the history write run in later
+      // tasks, because host code wrapping fetch and pushState runs inside them.
+      // Several changes in one task (an Apply setting a range and a facet): only
+      // the last is fetched and becomes a history entry.
+      this.loading();
+      clearTimeout(this.pending);
+      this.pending = window.setTimeout(() => {
+        // The shopper has left the listing meanwhile: the click no longer applies.
+        if (!route.accepts(new URL(location.href))) return this.setBusy(false);
+        this.resync(url);
+        setTimeout(() => writeUrl(url), 0);
+      }, 0);
+    }
+
+    /** A "show more" in flight: the result it grows (a second click waits for it, never asks again). */
+    private growing: ListingResult | null = null;
+
+    /**
+     * "Show more": the next page appended to what is shown, from its cursor
+     * (the one fetched ahead when there is one). Not a state of the URL: no
+     * history entry, no URL change. The
+     * grown result is cached for its state, so back/forward to it or a host
+     * re-creating our element shows every page loaded. `byKey`: from the
+     * keyboard (focus moves on to the first new tile).
+     */
+    showMore(byKey = false) {
+      const q = this.current;
+      const res = this.last;
+      if (!q || !res || this.lastQ !== q || this.inFlight || this.wanted || !hasMore(res) || this.growing === res) return;
+      this.intent?.cancel();
+      this.growing = res;
+      const href = this.href;
+      this.setBusy(true);
+      const done = () => {
+        if (this.growing === res) this.growing = null;
+        return this.href === href && this.last === res; // else the shopper moved on meanwhile
+      };
+      // Respond first: the request (and the host's fetch wrappers) in a later task.
+      setTimeout(() => {
+        more(q, res).then(
+          (grown) => {
+            if (!done()) return;
+            if (!grown.partial) cache.set(keyOf(q), grown);
+            this.setBusy(false);
+            this.message = null;
+            this.moreByKey = byKey;
+            this.render(q, grown, new URL(location.href));
+          },
+          (e) => {
+            if (!done()) return;
+            reportError(`${route.id} show more`, e);
+            this.setBusy(false);
+            this.message = t('error');
+            this.render(q, res, new URL(location.href));
+          },
+        );
+      }, 0);
+    }
+
+    /** URL -> query -> fetch -> render. Idempotent. */
+    private async sync(url = new URL(location.href)) {
+      const href = canon(url.href);
+      // A URL change that is not the one we asked for (back/forward, the host):
+      // later clicks apply to what it shows, not to our last request.
+      if (this.wantedHref && href !== this.wantedHref) this.wanted = this.wantedHref = null;
+      if (!route.accepts(url) || href === this.href) return;
+      this.href = href;
+      this.staged = null; // another state (back/forward, an apply): nothing held for the one left
+      this.ctrl?.abort();
+      const c = (this.ctrl = new AbortController());
+      let q: Query | null;
+      this.inFlight = true;
+      try {
+        const r = seeded.get(pageKey(url.href)) ?? route.resolve(url);
+        if (isPromise(r)) {
+          this.loading();
+          q = await r;
+          if (c.signal.aborted || this.href !== href) return;
+          tk.progressed();
+        } else q = r;
+      } catch (e) {
+        if (this.href !== href) return;
+        return this.failed(`${route.id} resolve`, e, url);
+      }
+      if (!q) {
+        this.inFlight = false;
+        this.setBusy(false);
+        return tk.release(); // e.g. a category the catalog does not know
+      }
+      this.current = q;
+      const key = keyOf(q);
+      // A host re-render may destroy and re-create us for the same URL: render
+      // synchronously from cache so the replacement never shows an empty frame.
+      const hit = cache.get(key);
+      if (hit && this.ssr && !this.hydrateWith) {
+        // Hydrate complete markup only: a parser-created element connects before its children are parsed.
+        if (document.readyState === 'loading') await new Promise((r) => document.addEventListener('DOMContentLoaded', r, { once: true }));
+        try {
+          this.hydrateWith = await hydrate!; // a small chunk, already on its way
+        } catch (e) {
+          // No hydration chunk: the server's markup is replaced by a client render (once that succeeds).
+          reportError(`${route.id} hydrate chunk`, e);
+          this.ssr = false;
+          this.server = [...this.childNodes];
+        }
+        if (this.href !== href) return;
+      }
+      if (this.cleared) {
+        await this.cleared;
+        this.cleared = null;
+        if (this.href !== href) return;
+      }
+      if (hit) {
+        takePrefetch(url.href); // not needed: never left to block a later prefetch of this URL
+        this.inFlight = false;
+        this.setBusy(false);
+        this.message = null;
+        return this.render(q, hit, url);
+      }
+      this.loading();
+      // Prefetched on intent (./intent.ts): this state's first page, done or in
+      // flight. Requests still out for other controls are stale now.
+      const pf = takePrefetch(url.href);
+      const ek = !pf && prefetchFilters ? earlyKey(q) : null;
+      const pre = ek ? early.take(ek) : undefined;
+      early.abortInFlight();
+      try {
+        let res: ListingResult;
+        let shownEarly = false;
+        if (pre) {
+          const first = await pre.catch(() => null); // a failed prefetch: asked again below
+          if (c.signal.aborted || this.href !== href) return;
+          const last = this.last;
+          const lq = this.lastQ;
+          // The products at once, with the sidebar as it was (the clicked
+          // facet's own values are exact: they never depended on its
+          // selection); the facets of the new result set follow (they need its guid).
+          if (first && last && lq && tk.state === 'ours' && visitOf(lq) === visitOf(q)) {
+            mark(`${route.id} render from intent prefetch`);
+            this.setBusy(false);
+            this.message = null;
+            this.render(q, { hits: first.hits, total: first.total, guid: first.guid, page: 1, cursor: first.cursor, status: first.status, facets: last.facets, facetsAll: last.facetsAll, quick: last.quick, partial: true }, url);
+            shownEarly = true;
+          }
+          res = await query(q, c.signal, first ?? undefined);
+        } else {
+          // The products as soon as they are here, busy, the facets following
+          // (their request needs the products' result set): a facets request
+          // sooner on screen (2026-10-11).
+          let productsShown = false;
+          this.rehearse(q, url);
+          res = await fromPrefetch(pf, q, c.signal, !notAbove(route.id) ? undefined : (p) => {
+            // The quick types on their way and above the products: they wait together.
+            if (c.signal.aborted || this.href !== href || (p.quickPending && !notAbove(route.id, 'quick'))) return;
+            mark(`${route.id} products before their facets`);
+            this.message = null;
+            this.render(q, p, url);
+            productsShown = true;
+          });
+          if (productsShown) this.quiet = true; // said with the products
+        }
+        if (c.signal.aborted || this.href !== href) return;
+        if (shownEarly && res.partial) {
+          // The facets failed: the sidebar shown stays (not cached, asked again next time).
+          this.inFlight = false;
+          return;
+        }
+        if (shownEarly) this.quiet = true; // said with the products
+        // Server markup still being parsed (a streamed include): render once it is complete.
+        if (this.ssr && document.readyState === 'loading') {
+          await new Promise((r) => document.addEventListener('DOMContentLoaded', r, { once: true }));
+          if (this.href !== href) return;
+        }
+        this.inFlight = false;
+        if (!res.partial) cache.set(key, res); // a result missing its facets is asked for again next time
+        this.setBusy(false);
+        this.message = null;
+        this.render(q, res, url);
+      } catch (e) {
+        // A request for a URL we have left (a prefetch cannot be aborted) says nothing about this one.
+        if (c.signal.aborted || this.href !== href) return;
+        this.failed(route.id, e, url);
+      }
+    }
+
+    /**
+     * A resolve or fetch failed. Before the first reveal their listing is (or
+     * can be) showing: leave it rather than swapping to an error message. After
+     * it: the last results, as they were (their query and links), with the error.
+     */
+    private failed(where: string, e: unknown, url: URL) {
+      this.inFlight = false;
+      reportError(where, e);
+      this.setBusy(false);
+      this.href = ''; // the same click may retry: this URL is not what we show
+      if (tk.state === 'ours' && this.last && this.lastQ) {
+        this.message = t('error');
+        this.current = this.lastQ;
+        this.render(this.lastQ, this.last, url);
+      } else {
+        // Server markup kept on a visit that is not the server's (its include
+        // came late, for another URL): hidden with ours when we hand back.
+        if (tk.ssr !== 'rendered') this.removeAttribute('data-lbx-ssr');
+        tk.release(true);
+      }
+    }
+
+    /**
+     * Host code that rewrites our markup (jQuery `.text()` / `.html()` on one of
+     * the site's classes we reuse) ejects lit's markers, and every later render
+     * throws: the listing would stay frozen. Drop lit's state and render anew
+     * from the same data instead (tens of ms; images come from the cache).
+     */
+    private renderOrRebuild(data: Record<string, unknown>) {
+      try {
+        this.v.render('search-box', data);
+      } catch (e) {
+        reportError(`${route.id} render (host rewrote our markup, rebuilt)`, e);
+        this.rebuild(data);
+      }
+      this.images();
+      if (tk.state === 'ours') this.watch();
+    }
+
+    /** Images a render put in that are there already (cached, persisted tiles) lose their placeholder now: no flash, no fade. */
+    private images() {
+      settleImages(this, imgs.fade !== false);
+    }
+
+    /** Render anew, dropping the state lit keeps on the container (or it reuses it and paints nothing). */
+    private rebuild(data: Record<string, unknown>) {
+      delete (this as any)._$litPart$;
+      this.replaceChildren();
+      this.v.render('search-box', data);
+      this.images();
+      if (this.a11y) this.prepend(this.a11y.root);
+    }
+
+    /**
+     * The shopper follows a link to another page (a product): the listing as
+     * it is, and where they are, for Back (./stash.ts). Only what is shown.
+     */
+    private leave(a: HTMLAnchorElement) {
+      if (!this.last || !this.lastQ || this.lastQ !== this.current || this.inFlight) return;
+      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a) })) mark(`${route.id} stashed for back`);
+    }
+
+    /** After a render: back where the shopper was (a stashed page), the next page when they near the end, the image host. */
+    private afterRender(q: Query, res: ListingResult, url: URL) {
+      // Whether the facets sit above the products (notAbove): read a frame
+      // later, when layout is clean (the read costs only itself). Shown only.
+      // The quick types likewise (notAbove), where some are shown.
+      if (!res.partial && tk.state === 'ours')
+        afterFrame(() => {
+          const list = this.querySelector('[data-lbx-list]');
+          if (!list || !this.isConnected) return;
+          const b = list.getBoundingClientRect();
+          // The grid's columns (inView), and its tiles watched from now on (shown).
+          const tops = [...list.children].slice(0, 12).map((t) => t.getBoundingClientRect().top);
+          this.cols = Math.max(1, tops.filter((y) => Math.abs(y - tops[0]) < 1).length);
+          this.watch();
+          for (const part of ['facets', 'quick'] as const) {
+            const ps = [...this.querySelectorAll(`[data-lbx-part="${part}"]`)];
+            if (!ps.length) continue;
+            const above = ps.some((f) => {
+              const a = f.getBoundingClientRect();
+              return getComputedStyle(f).position !== 'fixed' && a.height > 0 && a.bottom <= b.top + 1;
+            });
+            try {
+              localStorage.setItem(flowKey(route.id, part), above ? '0' : '1');
+            } catch {}
+          }
+        });
+      const st = stashed;
+      stashed = null; // the first render only
+      if (st && pageKey(url.href) === pageKey(location.href) && keyOf(st.query) === keyOf(q)) {
+        if (st.kind === 'back') {
+          const href = this.href;
+          // After the reveal (a font wait may delay it): ours must be laid out to find the tile.
+          const at = (n = 0) =>
+            this.href === href && (tk.state === 'ours' ? (restoreScroll(this, st.scroll ?? { y: 0 }), mark(`${route.id} scroll restored`)) : n < 120 && requestAnimationFrame(() => at(n + 1)));
+          at();
+          // Silently fresh after a while away: asked again in the background,
+          // re-rendered only when the results changed. A quick round trip to
+          // a product shows the listing as left (a reshuffle in front of the
+          // shopper, on an API that orders ties anew, was the bug).
+          if (Date.now() - st.at > BFCACHE_STALE_MS) setTimeout(() => this.revalidate(q, st.result, url, href), 1500);
+          else mark(`${route.id} back: as left, not revalidated`);
+        }
+      }
+      this.ahead?.();
+      this.ahead = null;
+      if (skipOut) this.sizeTiles();
+      // Not while prerendered: a next page of a page nobody may open is a request for nothing.
+      if (cfg.prefetchNextPage !== false && hasMore(res)) {
+        const href = this.href;
+        whenShown(() => this.href === href && !this.ahead && (this.ahead = nearEnd(this, () => this.prefetchNext(q, res))));
+      }
+      if (res.hits[0] && ctx.global.preconnectImages !== false) preconnectImages(ctx.result(res.hits[0]).c.image);
+    }
+
+    /**
+     * Tiles out of view skip their style, layout and paint
+     * (`content-visibility: auto`, `contentVisibility`): a long list's
+     * re-render (a sort after "show more") laid out and painted every tile.
+     * Each tile keeps its own size while skipped: a ResizeObserver on every
+     * tile (after the frame's own layout: no read forced) writes its content
+     * box to its `contain-intrinsic-size`, and the first one measured stands
+     * in for tiles not measured yet. On only once the tiles drawn have been
+     * measured: a tile out of view at that moment is never laid out again
+     * until it comes near, and with one size for all (the first's) tiles of
+     * other heights lost their places (a production integration's stub page, tiles 445-531 px tall:
+     * found on its tiles, 2026-10-11). A hidden first render is as before.
+     */
+    private sizeTiles() {
+      const list = this.querySelector('[data-lbx-list]');
+      if (!list) return;
+      const s = (this.sized ??= {
+        seen: new WeakSet<Element>(),
+        ro: new ResizeObserver((es) => {
+          let first: ResizeObserverSize | undefined;
+          for (const e of es) {
+            // The content box: contain-intrinsic-size stands in for the contents (padding and border come on top).
+            // Not rounded: WebKit's tiles are fractional (a listing 1.4 px off with whole pixels).
+            const b = e.contentBoxSize?.[0];
+            if (!b?.blockSize || !b.inlineSize) continue; // hidden: no size to give
+            first ??= b;
+            (e.target as HTMLElement).style.setProperty('contain-intrinsic-size', `auto ${b.inlineSize}px auto ${b.blockSize}px`);
+          }
+          if (!first || this.hasAttribute('data-lbx-cv')) return;
+          this.style.setProperty('--lbx-tile-w', `${first.inlineSize}px`);
+          this.style.setProperty('--lbx-tile-h', `${first.blockSize}px`);
+          setCss('listing-cv', layered(CV_CSS));
+          this.setAttribute('data-lbx-cv', '');
+        }),
+      });
+      for (const t of list.children) if (!s.seen.has(t)) s.seen.add(t), s.ro.observe(t);
+    }
+
+    private revalidate(q: Query, old: ListingResult, url: URL, href: string) {
+      if (this.href !== href) return;
+      // Pages appended by "show more" are not asked again (a chain of cursor
+      // requests, and the shopper's place under them): shown as left. A first
+      // page only is one request.
+      if (old.page > 1) return mark(`${route.id} not revalidated: ${old.page} pages shown`);
+      query({ ...q }, this.ctrl?.signal)
+        .then((res) => {
+          if (this.href !== href || res.partial) return;
+          cache.set(keyOf(q), res);
+          // The same tiles: nothing to redraw (a total the API approximates anew, or ties it orders anew, are not a change).
+          if (sameHits(res, old)) return mark(`${route.id} revalidated: unchanged`);
+          mark(`${route.id} revalidated: changed`);
+          keepViewport(this, () => ((this.quiet = true), this.render(q, res, url)));
+        })
+        .catch((e) => (e as Error)?.name === 'AbortError' || reportError(`${route.id} revalidate`, e));
+    }
+
+    /**
+     * Intent on one of our controls (./intent.ts): the request its click would
+     * make starts now. Only from a settled listing (nothing pending for the
+     * current state: no click waiting, no request out), for another state of
+     * this visit (same category or query) that is not cached already.
+     */
+    private onIntent(el: Element) {
+      const cur = this.current;
+      // In a drawer that stages, a control leads nowhere until Apply: nothing to fetch ahead.
+      if (this.staging()) return;
+      if (!cur || !this.last || this.lastQ !== cur || this.inFlight || this.wanted || tk.state !== 'ours' || thrifty()) return;
+      // "Show more" (`data-lbx-more`): its next page, from the cursor, as nearing the end does.
+      if (el.matches('[data-lbx-more]')) return this.prefetchNext(cur, this.last);
+      const raw = targetOf(el);
+      if (!raw) return;
+      const url = new URL(raw, location.href);
+      if (url.origin !== location.origin || url.pathname !== location.pathname || !route.accepts(url)) return;
+      const from = this.href;
+      if (canon(url.href) === from) return;
+      const then = (q: Query | null) => {
+        if (!q || this.href !== from || this.inFlight || this.wanted || visitOf(q) !== visitOf(cur) || cache.get(keyOf(q))) return;
+        const req = firstRequest(ctx.global, cfg, route, q);
+        // Its first images too (`_global.images.warm`, low priority): the click then shows them at once.
+        const fetch = (signal: AbortSignal) => ctx.api.search(req!, signal).then((p) => (warm > 0 && warmImages(firstRowImages(imgs, p.hits.slice(0, warm).map(ctx.result), true), warm), p));
+        if (req && early.start(JSON.stringify(req), visitOf(q), fetch)) mark(`${route.id} prefetch on intent`);
+      };
+      const r = route.resolve(url);
+      if (isPromise(r)) r.then(then).catch((e) => reportError(`${route.id} filter prefetch`, e));
+      else then(r);
+    }
+
+    /** The next page ("show more") from the cursor of what is shown, ready before the click: one request, taken by showMore(). */
+    private prefetchNext(q: Query, res: ListingResult) {
+      if (res !== this.last || q !== this.lastQ || !hasMore(res) || nextOf.has(res)) return;
+      mark(`${route.id} prefetch page ${res.page + 1}`);
+      more(q, res).catch(() => {}); // a failed one: the click asks again
+    }
+
+    private render(q: Query, res: ListingResult, url: URL) {
+      // The new state's results: the list comes back from its dim (LOADING_CSS
+      // fades it back), or, asked and answered within DIM_MS (no dim shown:
+      // cached, prefetched), fades in from FADE_FROM. One calm change for the
+      // whole list: tiles moving to their new places (a View Transition's
+      // morph) read as chaos on a sort or a broad filter (2026-10-12).
+      const w = this.loaded() ?? this.waited;
+      this.waited = null;
+      const was = this.last;
+      const quiet = this.quiet;
+      this.guarded(() => this.draw(q, res, url));
+      if (w && !w.dimmed && was && !quiet && tk.state === 'ours' && !sameHits(res, was)) this.fadeIn();
+    }
+
+    /** The list fading in from FADE_FROM (Web Animations: no class to restart, no layout read); not under reduced motion. */
+    private fadeIn() {
+      const list = this.querySelector('[data-lbx-list]');
+      if (!list || typeof list.animate !== 'function' || matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+      this.fade?.cancel();
+      this.fade = list.animate([{ opacity: FADE_FROM }, { opacity: 1 }], { duration: FADE_MS, easing: 'cubic-bezier(.2,0,0,1)' });
+    }
+
+    /** A render that throws (a template, or a hit it does not expect) hands the page back rather than leaving it blank. */
+    private guarded(f: () => void) {
+      try {
+        f();
+      } catch (e) {
+        reportError(`${route.id} render`, e);
+        this.setBusy(false);
+        // The server's markup is still the page's: back it goes (the takeover keeps a listing that is there).
+        if (this.server) {
+          delete (this as any)._$litPart$;
+          this.replaceChildren(...this.server);
+          if (tk.ssr === 'rendered') this.setAttribute('data-lbx-ssr', '');
+          else this.removeAttribute('data-lbx-ssr');
+        }
+        tk.release(true);
+      }
+    }
+
+    /** afterRender(), once a render is complete (a render in chunks: its last one). */
+    private rendered(q: Query, res: ListingResult, url: URL) {
+      try {
+        this.afterRender(q, res, url);
+      } catch (e) {
+        reportError(`${route.id} after render`, e);
+      }
+    }
+
+    /** The state a render shows: the URL's, or what the open drawer holds. */
+    private shownQ(q: Query): Query {
+      return this.staged ? { ...q, ...this.staged } : q;
+    }
+
+    /** The view state templates see (not in the URL): the groups' accordion and search text, the drawer's mode and what it holds. */
+    private view(): ListingView {
+      const cur = this.current;
+      const at = (st: UiState) => canon(route.write(new URL(location.href), st).href);
+      return {
+        open: this.groupOpen,
+        openDefault: atWidth(cfg.facetGroups?.open, true, viewport),
+        text: this.groupText,
+        apply: atWidth(cfg.facetsApply, 'instant', viewport),
+        pending: !!this.staged && !!cur && at(this.staged) !== at(stateOf(cur)),
+        toggleGroup: (name) => this.toggleGroup(name),
+        searchGroup: (name, text) => this.searchGroup(name, text),
+        setRange: (name, from, to) => (this.drawn as { setRange?: (n: string, f: number | null, t: number | null) => void } | null)?.setRange?.(name, from, to),
+      };
+    }
+
+    /** A group opened or closed: drawn again, nothing fetched. */
+    private toggleGroup(name: string) {
+      const groups = [...((this.drawn?.facets ?? []) as { name: string; open: boolean }[]), ...((this.drawn?.ranges ?? []) as { name: string; open: boolean }[])];
+      const g = groups.find((x) => x.name === name);
+      if (!g) return;
+      this.groupOpen = { ...this.groupOpen, [name]: !g.open };
+      this.redraw();
+    }
+
+    /** A group's search text: its values filtered, drawn again (nothing fetched); how many match is said once typing pauses. */
+    private searchGroup(name: string, text: string) {
+      if ((this.groupText[name] ?? '') === text) return;
+      this.groupText = { ...this.groupText, [name]: text };
+      this.redraw();
+      clearTimeout(this.groupSaid);
+      this.groupSaid = window.setTimeout(() => {
+        const f = ((this.drawn?.facets ?? []) as { name: string; label: string; search: { text: string; matches: number } | null }[]).find((x) => x.name === name);
+        if (f?.search?.text.trim() && this.a11y) this.a11y.live.say(t('facetMatches', { count: f.search.matches, facet: f.label }));
+      }, 600);
+    }
+
+    /**
+     * The quick types landed in a result shown without them (where they do
+     * not sit above the products): drawn now, into the render in steps if it
+     * is still going on. No hook, no announcement: the same result.
+     */
+    private quickIn(r: ListingResult) {
+      if (this.stepping?.hits === r.hits) return void this.stepping.again();
+      if (this.last !== r) return; // not shown (yet): a render of it shows them
+      mark(`${route.id} quick types after the products`);
+      this.redraw();
+    }
+
+    /** The last render's data again with the current view state: no fetch, no announcement, focus where it is. */
+    private redraw() {
+      const q = this.lastQ;
+      const res = this.last;
+      const url = this.drawnUrl;
+      if (!q || !res || !url || !this.drawn) return;
+      this.drawn = this.dataFor(q, res, url);
+      this.renderOrRebuild(this.drawn);
+      this.afterA11y();
+    }
+
+    /** The template data of a render of (q, res) at url: the scope, its actions, the view state. Sets `shown`, the state its links build on. */
+    private dataFor(q: Query, res: ListingResult, url: URL): Record<string, unknown> {
+      q = this.shownQ(q);
+      this.shown = stateOf(q);
+      this.drawnUrl = url;
+      const self = this;
+      return {
+        ...ctx.helpers,
+        ...listingData(ctx, route, url, q, res, this.message, this.view()),
+        facetsOpen: matchMedia('(min-width: 768px)').matches,
+        // actions
+        go: (link: Link | null) => (e: Event) => {
+          const m = e as MouseEvent;
+          if (!link || m.button > 0 || m.metaKey || m.ctrlKey || m.shiftKey || m.altKey) return; // new tab etc.: the browser's
+          e.preventDefault();
+          const at = e.currentTarget as Element | null;
+          at?.closest('details[data-lbx-dropdown]')?.removeAttribute('open');
+          const menu = at?.closest('[data-lbx-menu]');
+          if (menu) {
+            setMenu(menu, false);
+            // Its item had focus: back to the menu's button, not lost with the closed menu.
+            if (menu.contains(document.activeElement)) triggerOf(menu)?.focus();
+          }
+          self.go(link.patch as Partial<UiState>);
+        },
+        toggleFacet(name: string, value: string) {
+          const cur = new Set(q.filters[name] || []);
+          cur.has(value) ? cur.delete(value) : cur.add(value);
+          self.go({ filters: { ...q.filters, [name]: [...cur] } });
+        },
+        toggleFlag(id: string) {
+          const flags = new Set(q.flags);
+          flags.has(id) ? flags.delete(id) : flags.add(id);
+          self.go({ flags: [...flags] });
+        },
+        setRange(name: string, from: number | null, to: number | null) {
+          const filters = { ...q.filters };
+          if (from == null && to == null) delete filters[name];
+          else filters[name] = [`${from ?? ''}|${to ?? ''}`];
+          self.go({ filters });
+        },
+        setSort: (sort: string) => self.go({ sort }),
+        showMore: (e?: Event) => {
+          e?.preventDefault();
+          self.showMore(!!e && byKeyboard(e));
+        },
+        ui: this.ui,
+        setUi(key: string, value: unknown) {
+          if (self.ui[key] === value || !self.drawn) return;
+          self.ui = { ...self.ui, [key]: value };
+          self.drawn = { ...self.drawn, ui: self.ui };
+          self.renderOrRebuild(self.drawn);
+        },
+      };
+    }
+
+    private draw(q: Query, res: ListingResult, url: URL) {
+      // A first render in steps of these same products (shown before their
+      // facets): it goes on with the facets, not a render of them all at once.
+      if (this.stepping?.hits === res.hits) return this.stepping.take(q, res, url);
+      this.stepping = null;
+      const n = ++this.renders;
+      if (canon(url.href) === this.wantedHref) this.wanted = this.wantedHref = null;
+      // What this render announces once shown (WCAG 4.1.3). Not the page's
+      // first render: the page itself is being read then.
+      const before = this.lastQ;
+      const grew = !!before && !!this.last && keyOf(q) === keyOf(before) && res.page > this.last.page && res.guid === this.last.guid;
+      this.shownBefore = grew ? (this.last?.hits.length ?? 0) : 0;
+      const said = this.message ?? (grew ? t('shown', { shown: res.hits.length, total: res.total, count: res.total }) : res.total ? t('results', { count: res.total, query: q.title }) : t('empty', { query: q.title }));
+      // A quiet render keeps what is still to be said: the facets' render (said
+      // with the products) cut short their redraw in steps, before it spoke,
+      // and a filter was never announced (found by Luma's accessibility tests on a phone, 2026-10-11).
+      this.toSay = n > 1 && !this.quiet ? said : this.quiet ? this.toSay : null;
+      this.quiet = false;
+      const at = document.activeElement;
+      this.focusWas = at && at !== this && this.contains(at) ? at : null;
+      if (!grew) this.moreByKey = false;
+      mark(`${route.id} render ${res.hits.length} hits`);
+      if (handsBack(route, q, res.total) && tk.state !== 'ours') return tk.release(), this.rendered(q, res, url);
+      this.dataset.q = q.title; // the query shown, for tests and debugging
+      // data-total also says "ours has rendered": integration CSS collapses
+      // their held listing on it (style-host.css). While ours is still hidden
+      // it is set at the reveal, or theirs would go a frame before ours shows.
+      const total = () => void (this.dataset.total = String(res.total));
+      if (tk.state !== 'hold') total();
+      const visit = JSON.stringify([q.q, q.scope]);
+      if (visit !== this.uiVisit) (this.uiVisit = visit), (this.ui = {}), (this.groupOpen = {}), (this.groupText = {}), (this.staged = null);
+      const d0 = performance.now();
+      let data = this.dataFor(q, res, url);
+      /** The scope's own time (ms): a re-render's first step goes to the next frame when the two would not fit BUDGET. */
+      const dataMs = performance.now() - d0;
+      let cut: number | undefined;
+      this.drawn = data;
+      // Server markup that is not hydrated (no cached result for it: its facets
+      // were missing) is replaced, not rendered after.
+      if (this.ssr && !this.hydrateWith) {
+        this.ssr = false;
+        this.server ??= [...this.childNodes];
+      }
+      if (this.ssr && this.hydrateWith) {
+        this.ssr = false;
+        const markup = [...this.childNodes];
+        try {
+          // Bound to the server's markup with the data the server rendered it
+          // from (no view state: the groups and the drawer's mode as
+          // configured for the narrowest width, the facets open), then drawn
+          // with this page's (its width): hydration never checks values, so
+          // hydrating with ours would leave the server's in place.
+          this.v.hydrate('search-box', { ...data, ...listingData(ctx, route, url, this.shownQ(q), res, this.message), facetsOpen: true }, this.hydrateWith);
+          this.renderOrRebuild(data);
+          mark(`${route.id} hydrated`);
+        } catch (e) {
+          // Markup that does not match the templates (a stale fragment from an
+          // older deploy): render it anew rather than bind to the wrong nodes.
+          reportError(`${route.id} hydrate`, e);
+          this.server = markup;
+          this.rebuild(data);
+          mark(`${route.id} re-rendered after a hydration mismatch`);
+        }
+      } else if (tk.state !== 'ours' && !this.server && (data.results as unknown[]).length > STEP) {
+        // A visit's first render, while ours is hidden: in steps, a frame
+        // apart (a page of tiles and a sidebar of facets are tens of ms of
+        // DOM work on a slow phone). Each step is one render of the same
+        // template with longer slices of `results` and `facets`: the first
+        // STEP tiles (with the skeleton), then the facet groups, then the
+        // other tiles, as many as BUDGET ms holds by what a tile and a group
+        // cost so far. Ours shows once what a screen holds is drawn (the
+        // facets and SHOW_TILES tiles), busy until the rest is; the hooks,
+        // the height and Back's scroll run when it is complete.
+        const href = this.href;
+        const tiles = data.results as unknown[];
+        let groups = Array.isArray(data.facets) ? (data.facets as unknown[]) : [];
+        const N = tiles.length;
+        let G = groups.length;
+        // The whole result (the facets) for these products, while this goes on.
+        this.stepping = {
+          hits: res.hits,
+          take: (q2, r2, u2) => {
+            q = q2;
+            res = r2;
+            url = u2;
+            this.drawn = data = this.dataFor(q, res, url);
+            groups = Array.isArray(data.facets) ? (data.facets as unknown[]) : [];
+            G = groups.length;
+            ng = Math.min(ng, G);
+            this.quiet = false;
+            if (res.pending || nt < N || ng < G) this.setBusy(true); // still drawing
+            mark(`${route.id} facets into the render in steps`);
+          },
+          // The quick types landed in res: drawn with its next step.
+          again: () => (this.drawn = data = this.dataFor(q, res, url)),
+        };
+        let nt = 0;
+        let ng = 0;
+        // A render's cost, ms: b per unit it adds, plus RERUN of that per unit
+        // already there (lit runs every tile's template again, creating DOM
+        // only for the new ones). b per kind, from the last render that added
+        // that kind (the first render's, with the skeleton, for both until
+        // then: an overestimate, the safe side).
+        let perTile = 0;
+        let perGroup = 0;
+        let frames = 0;
+        let shown = false;
+        /** Each step's time (ms): the mark says them (a step over BUDGET shows there). */
+        const spent: number[] = [];
+        let fonts: Fonts | undefined;
+        tk.progressed(); // the frames must not run into the hold's timeout
+        this.setBusy(true); // until the last step: ours may show before it
+        const draw = (t: number, g: number) => {
+          const t0 = performance.now();
+          // The quick types after the first step: the products' first tiles are never held back by them.
+          this.renderOrRebuild(t === N && g === G ? data : { ...data, results: tiles.slice(0, t), facets: groups.slice(0, g), quick: nt ? data.quick : {} });
+          const ms = performance.now() - t0;
+          if (!nt) perTile = perGroup = ms / t;
+          else if (t > nt && g === ng) perTile = ms / (t - nt + RERUN * (nt + ng));
+          else if (g > ng && t === nt) perGroup = ms / (g - ng + RERUN * (nt + ng));
+          nt = t;
+          ng = g;
+        };
+        const show = () => {
+          shown = true;
+          this.revealFirst(total, () => {}, fonts);
+        };
+        /**
+         * How many more fit BUDGET at `per` ms each, with what is there run
+         * again; where not even one does (a slow phone, heavy tiles), what
+         * is there again: one at a time would re-render the growing page N + G times.
+         */
+        const more = (per: number, have: number) => {
+          const n = Math.floor((BUDGET - RERUN * per * (nt + ng)) / per);
+          return n >= 1 ? n : Math.max(1, have);
+        };
+        const step = (first: boolean) => {
+          frames++;
+          const t0 = performance.now();
+          if (!first) {
+            // After a frame: styles and layout are clean, reading them costs only what we read.
+            if (nt && ng === G) fonts ??= fontsOf(this);
+            // What a screen holds is drawn (a taller one holds more rows;
+            // innerHeight is no layout read): ours shows now, at the start of
+            // this step, so the frame after it paints it (with this step's tiles).
+            if (!shown && ng === G && nt >= Math.ceil((SHOW_TILES * Math.max(900, innerHeight)) / 900)) {
+              show();
+              // A screen taller than the 900 px SHOW_TILES is measured on,
+              // with half of them or more drawn: the rest with this step.
+              // Its end may be in view there, and then the footer would move
+              // down after ours shows (ours is hidden until now: its layout
+              // cannot tell). Found when tiles came from the templates' cache
+              // and steps got cheaper: shown with 19 of 30 tiles at 1600 px,
+              // the rest a frame later (2026-10-11).
+              if (innerHeight > 900 && N - nt <= nt) draw(N, G);
+            }
+            // Shown, and the end of ours already in view (a first visit with
+            // no height reserved): the rest now, not a footer moving down a
+            // frame at a time.
+            else if (shown && this.getBoundingClientRect().bottom < innerHeight) draw(N, G);
+          }
+          if (first) draw(Math.min(STEP, N), 0);
+          else if (ng < G) {
+            draw(nt, Math.min(G, ng + more(perGroup, ng)));
+          } else if (nt < N) {
+            draw(Math.min(N, nt + more(perTile, nt)), G);
+          }
+          spent.push(Math.round(performance.now() - t0));
+          if (first) this.firstMs = performance.now() - t0;
+          if (nt === N && ng === G) {
+            mark(`${route.id} rendered in ${frames} frames (${spent.join('/')} ms)`);
+            this.tileMs = perTile;
+            this.stepping = null;
+            if (!res.pending) this.setBusy(false); // the products alone: busy until their facets
+            return this.finish(q, res, url, total, fonts, shown);
+          }
+          afterFrame(() => this.renders === n && this.href === href && this.guarded(() => step(false)));
+        };
+        // The scope and the first step in one task were 17-18 ms on a production storefront at 4x: apart when they would not fit.
+        if (dataMs + (this.firstMs || STEP * (this.tileMs || 3)) > BUDGET) afterFrame(() => this.renders === n && this.href === href && this.guarded(() => step(true)));
+        else step(true);
+        return;
+      } else if (tk.state === 'ours' && !this.server && (data.results as unknown[]).length > (cut ??= grew ? this.drawnOf(res) + 2 * Math.max(1, this.cols) : Math.max(this.inView(), this.drawnOf(res)))) {
+        // A shown listing drawn anew (a filter, a sort, Back to another
+        // state): every tile at once was one task of 180-290 ms on a production
+        // storefront at 4x CPU (styling and laying out all of them, under the View
+        // Transition there was then). The facets and the tiles down to the
+        // viewport's bottom first (counted on the tiles there now, a row
+        // more: the page never ends above the viewport, the scroll stays),
+        // the rest a frame at a time, as many as BUDGET holds; busy until then.
+        // "Show more" too: the tiles there kept (the templates' cache) and two
+        // rows of the new page, the rest a frame at a time (its end is in view,
+        // so the viewport's count was all of them: 72 tiles at once, 26 ms on
+        // a production storefront at 4x). They go under the last ones: nothing above moves.
+        const href = this.href;
+        const tiles = data.results as unknown[];
+        const N = tiles.length;
+        const had = this.drawnOf(res);
+        let nt = cut;
+        let t0 = 0;
+        let per = this.tileMs || 3;
+        const spent: number[] = [];
+        const first = () => {
+          if (this.renders !== n || this.href !== href) return;
+          t0 = performance.now();
+          this.renderOrRebuild({ ...data, results: tiles.slice(0, nt) });
+          this.drawn$ = { hits: res.hits, n: nt };
+          // A tile's cost (ms), learnt from the steps that added tiles (this
+          // element's earlier renders too): a step adding none tells nothing.
+          if (nt > had) per = (performance.now() - t0) / (nt - had + RERUN * had);
+          this.tileMs = per;
+          spent.push(Math.round(performance.now() - t0));
+          this.firstMs = performance.now() - t0;
+          afterFrame(() => this.guarded(step));
+        };
+        const step = () => {
+          if (this.renders !== n || this.href !== href) return;
+          t0 = performance.now();
+          const k = Math.floor((BUDGET - RERUN * per * nt) / per);
+          // Not even one within BUDGET (the tiles there run again cost it): a third of the rest, not one per frame.
+          const t = Math.min(N, nt + (k >= 1 ? k : Math.ceil((N - nt) / 3)));
+          this.renderOrRebuild(t === N ? data : { ...data, results: tiles.slice(0, t) });
+          const ms = performance.now() - t0;
+          spent.push(Math.round(ms));
+          this.tileMs = per = ms / (t - nt + RERUN * nt);
+          nt = t;
+          this.drawn$ = { hits: res.hits, n: nt };
+          if (nt < N) return void afterFrame(() => this.guarded(step));
+          mark(`${route.id} drawn in ${spent.length} frames (${spent.join('/')} ms)`);
+          if (!res.pending) this.setBusy(false);
+          this.finish(q, res, url, total);
+        };
+        this.setBusy(true);
+        // The scope and the first step in one task were 22-27 ms on a production
+        // storefront at 4x (the scope 7-8 ms of it, outside the step's own time): apart when
+        // they would not fit BUDGET together.
+        if (dataMs + Math.max(this.firstMs, per * Math.max(1, nt - had + RERUN * had)) > BUDGET) afterFrame(() => this.guarded(first));
+        else first();
+        return;
+      } else this.renderOrRebuild(data);
+      this.finish(q, res, url, total);
+    }
+
+    /**
+     * Of these products, how many are drawn already (the same ones in the
+     * same order: the products shown first, then with their facets): a
+     * re-render goes on from there, never cutting them back.
+     */
+    private drawnOf(res: ListingResult) {
+      const d = this.drawn$;
+      if (!d) return 0;
+      const id = (h: { [k: string]: unknown }) => String(h['@id']);
+      const n = Math.min(d.n, res.hits.length);
+      for (let i = 0; i < n; i++) if (id(d.hits[i]) !== id(res.hits[i])) return 0;
+      return n;
+    }
+    /**
+     * A page's first render prepared lit's templates (parsing each one's
+     * HTML, walking it for its parts): about half of its first step, 88 ms
+     * on a production storefront at 4x CPU, on every page load. Done while the products
+     * are on their way: once per page, in two idle tasks, the template drawn
+     * into a detached element, then again with two placeholder tiles, three
+     * values a facet and a next page (their pictures lazy and about:blank:
+     * nothing is requested; detached: no style or layout).
+     * Skipped once something is drawn; a template throwing on the
+     * placeholders only loses the head start (reported).
+     */
+    private rehearse(q: Query, url: URL) {
+      if (rehearsed || this.renders || this.ssr) return;
+      rehearsed = true;
+      // A picture's template too (its `<img>` was most of what was left: on a phone, the first step 35 -> 18 ms):
+      // the image helpers lazy (a detached lazy image is never fetched), about:blank for a template's own <img>.
+      const fill = (f: string): unknown => (/price/i.test(f) ? 1290 : /image|img/i.test(f) ? 'about:blank' : /url/i.test(f) ? '/' : 'Lorem ipsum dolor');
+      const lazy = imageHelpers(imgs, true);
+      const hits = [0, 1].map((i) => ({ ...Object.fromEntries((cfg.fields ?? []).map((f) => [f, fill(f)])), '@id': `rehearsal/${i}`, '@type': ctx.global.itemType ?? 'product', '@title': 'Lorem ipsum dolor sit amet' }));
+      const facets = Object.fromEntries(facetFields(cfg, q).map((f) => [f, /price/i.test(f) ? { field: f, type: 'range', min: 1, max: 1000 } : { field: f, type: 'terms', values: ['Lorem', 'Ipsum', 'Dolor'] }]));
+      // Three idle tasks: the page's frame (no tiles, no facets), the tiles and a
+      // next page ("show more"), then the facets (tiles and facets in one were
+      // 17 ms on a production storefront at 4x CPU, 2026-10-12).
+      const steps: ListingResult[] = [
+        { hits: [], total: 0, guid: '', page: 1, cursor: null, status: 'end', facets: {}, quick: {} },
+        { hits, total: 100, guid: '', page: 1, cursor: 'rehearsal', status: 'more', facets: {}, quick: {} },
+        { hits, total: 100, guid: '', page: 1, cursor: 'rehearsal', status: 'more', facets, quick: {} },
+      ];
+      const into = document.createElement('div');
+      const v = view(into, ctx.templates);
+      const step = (k: number) => {
+        if (this.renders) return;
+        const was = { shown: this.shown, drawnUrl: this.drawnUrl };
+        try {
+          v.render('search-box', { ...this.dataFor(q, steps[k], url), ...lazy });
+        } catch (e) {
+          return reportError(`${route.id} rehearsal`, e);
+        } finally {
+          ({ shown: this.shown, drawnUrl: this.drawnUrl } = was);
+        }
+        if (k + 1 < steps.length) idle(() => step(k + 1));
+        else mark(`${route.id} rehearsed`);
+      };
+      const idle = (f: () => void) => afterFrame(() => (typeof requestIdleCallback === 'function' ? requestIdleCallback(f, { timeout: 500 }) : setTimeout(f, 0)));
+      idle(() => step(0));
+    }
+
+    /** A tile's cost in a render, ms (re-renders in steps size their steps by it). */
+    private tileMs = 0;
+    /** The last first step's time (ms): the facets with the first tiles, what a render's first task costs besides its scope. */
+    private firstMs = 0;
+    /** The hits a render in steps drew, and how many of them (`drawnOf`). */
+    private drawn$: { hits: ListingResult['hits']; n: number } | null = null;
+
+    /**
+     * How many tiles a re-render draws first: those reaching the viewport's
+     * bottom now and a row more (whole rows); all of them when the list is
+     * not laid out (hidden) or ends in view.
+     */
+    private inView() {
+      const list = this.querySelector('[data-lbx-list]');
+      const tiles = list ? [...list.children] : [];
+      if (!tiles.length) return Infinity;
+      // From the tiles' IntersectionObserver, not their layout: read here (a
+      // render, the page's layout dirty) it forced a style and layout.
+      let last = -1;
+      for (const t of this.seen) last = Math.max(last, tiles.indexOf(t));
+      // None in view: the list is below the viewport (none needed yet), or above it (all of it: the page must not shorten under the scroll).
+      if (last < 0) return this.past ? Infinity : STEP;
+      if (last === tiles.length - 1) return Infinity;
+      const cols = this.cols;
+      return Math.max(STEP, (Math.ceil((last + 1) / cols) + 1) * cols);
+    }
+    /** Tiles in the viewport (an IntersectionObserver), whether the list's last one is above it, the grid's columns (read with layout clean). */
+    private seen = new Set<Element>();
+    private past = false;
+    private cols = 1;
+    private io: IntersectionObserver | null = null;
+    private watched = new Set<Element>();
+    /** After a render: its tiles watched (the new ones), the gone ones no longer. */
+    private watch() {
+      if (typeof IntersectionObserver !== 'function') return;
+      this.io ??= new IntersectionObserver((es) => {
+        const list = this.querySelector('[data-lbx-list]');
+        for (const e of es) {
+          if (e.isIntersecting) this.seen.add(e.target);
+          else this.seen.delete(e.target);
+          if (e.target === list?.lastElementChild) this.past = !e.isIntersecting && e.boundingClientRect.bottom <= 0;
+        }
+      });
+      const now = new Set(this.querySelector('[data-lbx-list]')?.children ?? []);
+      for (const t of this.watched) if (!now.has(t)) this.io.unobserve(t), this.watched.delete(t), this.seen.delete(t);
+      for (const t of now) if (!this.watched.has(t)) this.io.observe(t), this.watched.add(t);
+    }
+
+    /** After a render: the server's markup goes, the hook, the height and the first reveal. */
+    private finish(q: Query, res: ListingResult, url: URL, total: () => void, fonts?: Fonts, shown = false) {
+      // Ours rendered: the server's markup goes, and from now on this is a
+      // client element like any other (the takeover may hide it).
+      if (this.server) for (const n of this.server) n.remove();
+      this.server = null;
+      this.removeAttribute('data-lbx-ssr');
+      this.last = res;
+      this.drawn$ = { hits: res.hits, n: res.hits.length };
+      this.lastQ = q;
+      this.afterA11y();
+      const info = { route: route.id, query: q.title, total: res.total, shown: res.hits.length, page: res.page, url };
+      // A prerendered page (a search typed on the page before) is not seen
+      // yet: the hook (titles, and often the site's analytics) runs when it
+      // is shown, never for a prerender the shopper does not open.
+      // The products alone (`pending`): the hook once the facets are there too, once a visit.
+      if (!res.pending)
+        whenShown(() => {
+          try {
+            cfg.onRender?.(info);
+          } catch (e) {
+            reportError(`${route.id} onRender`, e);
+          }
+        });
+      // Our height on this URL, for the next visit's reserved space: measured
+      // once shown. The first page's only: a reload (or any new load of the
+      // URL) shows the first page, and the browser restores its scroll into
+      // that height (pages "show more" appended are not loaded again).
+      const remember = () => res.page === 1 && !res.pending && afterLayout(this, rememberHeight);
+      // Shown already (a render in steps, before its last): the height once complete.
+      if (shown) remember();
+      else this.revealFirst(total, remember, fonts);
+      // Back's scroll, the next page ahead: with the whole result.
+      if (!res.pending) this.rendered(q, res, url);
+    }
+
+    /**
+     * The first reveal of a visit (later renders are visible already), and the
+     * height remembered once shown. `fonts`: checked already (a render in chunks).
+     */
+    private revealFirst(total: () => void, remember: () => void, fonts?: Fonts) {
+      // First reveal: in the site's final font, not its fallback (their webfont
+      // may still be loading with font-display: swap). Then their listing and
+      // ours swap in one frame. Later renders are already visible: no wait.
+      // The fonts are read after a frame: right after a render the host page's
+      // styles are dirty, and the first computed style would restyle all of it.
+      if (tk.state === 'ours') return remember(), this.speak();
+      tk.progressed(); // the checks must not run into the hold's timeout
+      const shownHref = this.href;
+      const reveal = () => {
+        total();
+        tk.reveal();
+        remember();
+        this.speak();
+      };
+      const then = (f: Fonts) => {
+        if (!f.wait || f.done) return reveal();
+        tk.progressed();
+        f.wait.then(() => {
+          if (this.href !== shownHref) return;
+          mark(`${route.id} fonts waited ${Math.round(performance.now() - f.from)}ms`);
+          reveal();
+        });
+      };
+      if (fonts) return then(fonts);
+      // Every font face of the page loaded already (a later page view): nothing to wait for, no frame to wait.
+      if (facesLoaded()) return then({ wait: null, done: true, from: performance.now() });
+      afterFrame(() => {
+        if (this.href !== shownHref) return;
+        if (tk.state === 'ours') return total(), this.speak(); // shown meanwhile (a later render of this URL)
+        then(fontsOf(this));
+      });
+    }
+  }
+
+  // Defining the class upgrades the element the entry (or the server) has already placed.
+  if (!customElements.get(route.tag)) customElements.define(route.tag, LbxListing);
+};
+
+/**
+ * A menu (`[data-lbx-menu]` in the integration's markup) open or closed: the
+ * attribute its CSS shows it by, and the state on its button (WCAG 4.1.2):
+ * the toggle that says it has a popup (`aria-haspopup` or `aria-expanded`),
+ * else the menu's first toggle. `focusIn` (opened from the keyboard): focus
+ * goes to its selected item, else its first.
+ */
+const setMenu = (menu: Element, open: boolean, focusIn = false) => {
+  if (menu.hasAttribute('data-lbx-open') !== open) menu.toggleAttribute('data-lbx-open', open);
+  const b = triggerOf(menu);
+  if (b && b.getAttribute('aria-expanded') !== String(open)) b.setAttribute('aria-expanded', String(open));
+  if (open && focusIn)
+    afterFrame(() => {
+      if (!menu.hasAttribute('data-lbx-open')) return;
+      const at = document.activeElement;
+      if (at && menu.contains(at) && !at.hasAttribute('data-lbx-toggle')) return; // the visitor's arrows were first
+      const items = focusables(menu).filter((el) => !el.hasAttribute('data-lbx-toggle'));
+      (items.find((el) => el.matches('[aria-selected="true"], [aria-current="true"], [aria-current="page"], [aria-checked="true"]')) ?? items[0])?.focus();
+    });
+};
+/**
+ * A tile's main control, where focus goes after "show more": the tile itself
+ * when it is a link, else its first control in the Tab order that a screen
+ * reader names. Not a picture link marked `tabindex="-1"` /
+ * `aria-hidden="true"` (it repeats the title link): focus there was off the
+ * Tab order, on nothing announced (a Magento shop's tile, 2026-10-02).
+ */
+const mainControl = (tile: Element) =>
+  ([tile, ...tile.querySelectorAll('a[href], button, input, select, textarea, [tabindex]')] as HTMLElement[]).find(
+    (el) => el.matches('a[href], button, input, select, textarea, [tabindex]') && el.tabIndex >= 0 && !(el as HTMLButtonElement).disabled && !el.closest('[aria-hidden="true"], [inert]'),
+  ) ?? null;
+const triggerOf = (menu: Element) => (menu.querySelector('[data-lbx-toggle][aria-haspopup], [data-lbx-toggle][aria-expanded]') ?? menu.querySelector('[data-lbx-toggle]')) as HTMLElement | null;
+
+/** A font check: its wait (null: nothing pending), whether it has settled, and since when. */
+type Fonts = { wait: Promise<void> | null; done: boolean; from: number };
+const fontsOf = (root: Element): Fonts => {
+  const f: Fonts = { wait: fontsPending(root), done: false, from: performance.now() };
+  f.wait?.then(() => void (f.done = true));
+  return f;
+};
+
+/** Every font face of the document has loaded (no style read). */
+const facesLoaded = () => {
+  let settled = true;
+  document.fonts?.forEach((f) => void (f.status !== 'loaded' && (settled = false)));
+  return settled;
+};
+
+/** Now, or once a prerendered document is shown (activated). */
+const whenShown = (f: () => void) => {
+  if ((document as any).prerendering) document.addEventListener('prerenderingchange', f, { once: true });
+  else f();
+};
+
+/**
+ * Fonts our listing's text will use that are not loaded yet: a promise that
+ * settles when they are, capped at capMs so a slow font never holds the page.
+ * null when nothing is pending. Text is checked in its own computed font with
+ * its own characters (webfonts are split into unicode-range subsets).
+ * Computed styles work while we are still display:none, but each costs a style
+ * pass over the element: they are read for one element per kind of text
+ * (tag, class and parent class decide the font in practice; a listing repeats
+ * the same few dozen kinds for every tile), and not at all when every font
+ * face of the page has loaded already.
+ */
+const fontsPending = (root: Element, capMs = 800): Promise<void> | null => {
+  if (facesLoaded()) return null;
+  const kinds = new Map<string, { el: Element; chars: Set<string> }>();
+  const els = [root, ...root.querySelectorAll('*')].slice(0, 400);
+  for (const el of els) {
+    let text = '';
+    for (const n of el.childNodes) if (n.nodeType === 3) text += n.nodeValue;
+    text = text.replace(/\s+/g, '');
+    if (!text) continue;
+    const kind = `${el.localName}.${el.className}<${el.parentElement?.className ?? ''}`;
+    const k = kinds.get(kind) ?? (kinds.size < 60 ? { el, chars: new Set<string>() } : null);
+    if (!k) continue;
+    for (const c of text) k.chars.add(c);
+    kinds.set(kind, k);
+  }
+  const byFont = new Map<string, Set<string>>();
+  for (const { el, chars } of kinds.values()) {
+    const cs = getComputedStyle(el);
+    const font = `${cs.fontStyle} ${cs.fontWeight} 16px ${cs.fontFamily}`;
+    const all = byFont.get(font) ?? new Set<string>();
+    for (const c of chars) all.add(c);
+    byFont.set(font, all);
+  }
+  const missing: [string, string][] = [];
+  for (const [font, chars] of byFont) {
+    const sample = [...chars].join('').slice(0, 300);
+    try {
+      if (!document.fonts.check(font, sample)) missing.push([font, sample]);
+    } catch {}
+  }
+  if (!missing.length) return null;
+  const loads = Promise.all(missing.map(([f, t]) => document.fonts.load(f, t).catch(() => [])));
+  return Promise.race([loads, new Promise((r) => setTimeout(r, capMs))]).then(() => {});
+};