@luigisbox/luma 0.4.0 → 0.6.0

package/src/widgets/listing/element.ts

@@ -13,14 +13,16 @@
 // (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 { borrow, liveRegion, useContrast } from '../../core/a11y';
 import { activateByKey, byKeyboard, focusables, trapTab } from '../../core/a11y-keys';
+import { CONTENT_VISIBILITY, DRAWER, DROPDOWN, MENU, NAMED_FADE, NAMED_PRECONNECT_IMAGES, NAMED_PREFETCH_FILTERS, NAMED_PREFETCH_NEXT_PAGE, NAMED_PRELOAD, NAMED_RESTORE_ON_BACK, ON_RENDER, SEARCH, SSR } from '../../core/features';
 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 { preloadImages } from '../../core/image-preload';
+import { firstRowCount, firstRowImages, imageHelpers, imageOf, settleImages, warmImages } from '../../core/support';
 import { view } from '../../core/templates';
 import { afterFrame, isPromise } from '../../core/scheduler';
 import { onUrlChange } from '../../core/sense';
@@ -31,19 +33,25 @@ 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 { facetFields, handsBack, nextState, queryKey, stateOf, type Query, type Route, type UiState } from './state';
+import { specKey } from '../../core/stash';
 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 { firstPages, SETTLE_MS, 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, peekStash, readStash, writeStash, type Stash } from './stash';
+import { dropStash, peekStash, readStash, removeStash, writeStash, type Stash } from './stash';
 import { adoptScroll, holdScroll, keepViewport, leavingLink, nearEnd, preconnectImages, releaseScroll, 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;
+/** An Apply's status (./applied.ts) shows this long; its new tiles come in up to SWAP_TILES (those in view). */
+const APPLIED_MS = 2500;
+const SWAP_TILES = 16;
+/** Reduced motion asked for (read when needed: the setting may change). */
+const reduced = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
 /** 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. */
@@ -88,7 +96,7 @@ const sameUrl = (u: unknown, href: string) => {
     return false;
   }
 };
-const keyOf = (q: Query) => JSON.stringify([q.q, q.scope, q.filters, q.flags, q.sort]);
+const keyOf = queryKey;
 
 type Hydrate = (v: unknown, c: HTMLElement | ShadowRoot) => void;
 
@@ -100,7 +108,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   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));
+    const p = listingQuery(ctx.api, ctx.global, cfg, route, q, signal, pre, onProducts, SEARCH ? quickChannel(route.id) : undefined);
     // 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;
@@ -158,8 +166,23 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   };
   // 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 prefetchFilters = (NAMED_PREFETCH_FILTERS ? ctx.global.prefetchFilters !== false : true);
+  // The high-contrast toggle (`_global.contrastToggle`, off by default): its
+  // own chunk (lbx-contrast), asked for now where it is on, so a site without
+  // it does not download it with every listing.
+  const toggle = ctx.global.contrastToggle ? import('../../core/contrast-toggle') : null;
   const visitOf = (q: Query) => JSON.stringify([q.q, q.scope]);
+  const prefetchFailed = (e: unknown) => reportError(`${route.id} filter prefetch`, e);
+  /** What a render says it shows: the count found, or nothing found. */
+  const found = (q: Query, res: ListingResult) => (res.total ? t('results', { count: res.total, query: q.title }) : t('empty', { query: q.title }));
+  // An Apply's cue (./applied.ts, its own chunk): asked for when a drawer opens where it stages.
+  let applied: typeof import('./applied') | null = null;
+  let appliedAsked = false;
+  const askApplied = () => {
+    if (appliedAsked) return;
+    appliedAsked = true;
+    import('./applied').then((m) => (m.prepare(), (applied = m)), (e) => reportError(`${route.id} applied cue`, e));
+  };
   const earlyKey = (q: Query) => {
     const r = firstRequest(ctx.global, cfg, route, q);
     return r && JSON.stringify(r);
@@ -190,7 +213,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       return false;
     }
   };
-  if (document.querySelector(`${route.tag}[data-lbx-ssr]`)) adopt();
+  if (SSR && 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
@@ -199,7 +222,11 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   /** The page's templates prepared ahead (`rehearse`), once. */
   let rehearsed = false;
   if (!seeded.size) {
-    stashed = readStash(route.id, location.href);
+    // A typed query's stash is under the query: this page's, as the search
+    // route reads it (sync for search; a category's lookup is not asked here).
+    const here = new URL(location.href);
+    const resolved = route.id === 'search' && route.accepts(here) ? route.resolve(here) : null;
+    stashed = readStash(route.id, location.href, resolved instanceof Promise ? null : resolved);
     if (stashed?.sr) adoptScroll();
     // Too old to render from: where the shopper was only (the results are asked for as on any load).
     if (stashed?.stale) mark(`${route.id} back: stash too old, its scroll only`);
@@ -209,12 +236,12 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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 key = specKey(route.id, stashed.query.q ?? '');
+      if (stashed.kind === 'spec' && (document as any).prerendering) document.addEventListener('prerenderingchange', () => removeStash(key), { once: true });
     }
   }
-  const restoreOn = cfg.restoreOnBack !== false;
-  const skipOut = cfg.contentVisibility === true;
+  const restoreOn = (NAMED_RESTORE_ON_BACK ? cfg.restoreOnBack !== false : true);
+  const skipOut = CONTENT_VISIBILITY ? cfg.contentVisibility === true : false;
 
   // The request for the URL we loaded on starts now, before the element exists.
   const bootUrl = new URL(location.href);
@@ -235,7 +262,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   // 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 preloadOn = (NAMED_PRELOAD ? imgs.preload !== false : true);
   const warm = imgs.warm ?? 0;
   const preloadRow = (res: ListingResult | null | undefined) => {
     if (res?.hits.length) preloadImages(firstRowImages(imgs, res.hits.map(ctx.result)));
@@ -323,6 +350,14 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      */
     private staged: UiState | null = null;
     private stagedMode = false;
+    /**
+     * The held state fetched in the background (prefetchHeld()): the timer
+     * waiting for the changes to pause, the held state's URL (a query
+     * resolved late is for it only), and the request it started (its key in
+     * `early`), aborted by a newer held state while it is out.
+     */
+    private heldTimer = 0;
+    private heldKey: string | null = null;
     /** Stops watching the `facetsApply` breakpoints of the open drawer (watchApply()). */
     private unwatchApply: (() => void) | null = null;
     /** Renders started: a render in chunks stops when a newer one has started. */
@@ -398,19 +433,30 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     };
 
     connectedCallback() {
-      onQuickLanded(route.id, (r) => this.quickIn(r));
+      // 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. A
+      // search page's only (core/features.ts): here, not a method, so a build
+      // without search/ leaves it out.
+      if (SEARCH)
+        onQuickLanded(route.id, (r) => {
+          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();
+        });
       // 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();
+        this.ssr = SSR ? this.hasAttribute('data-lbx-ssr') && adopt() : false;
         // 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')) {
+        else if (SSR && 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 }));
@@ -427,20 +473,23 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (!this.hasAttribute('tabindex')) this.tabIndex = -1;
       // Moved on within this document (an SPA's navigation): its scroll is the host's again.
       this.unsub = onUrlChange(() => (releaseScroll(), this.urlMoved(), this.resync()));
-      this.unBack ??= onOwnBack(this.onBack);
+      // The drawer's own history entry: only where a template has a drawer (core/features.ts DRAWER).
+      if (DRAWER) this.unBack ??= onOwnBack(this.onBack);
       // 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);
+      if (MENU || DROPDOWN) {
+        document.addEventListener('click', this.onOutside, true);
+        document.addEventListener('pointerdown', this.onOutside, true);
+      }
       addEventListener('pagehide', this.onPageHide);
       addEventListener('pageshow', this.onPageShow);
       addEventListener('scroll', this.onScroll, { passive: true });
       if (prefetchFilters) this.intent ??= watchIntent(this, (el) => this.onIntent(el));
       // Put back by a host re-render with its drawer open: still watched.
-      if (this.hasAttribute('data-drawer-open') && !this.unwatchApply) this.watchApply();
+      if (DRAWER && this.hasAttribute('data-drawer-open') && !this.unwatchApply) this.watchApply();
       // Microtask: runs before paint (no empty frame) but outside the
       // reconciler's placement pass.
       queueMicrotask(() => this.resync());
@@ -454,8 +503,10 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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);
+      if (MENU || DROPDOWN) {
+        document.removeEventListener('click', this.onOutside, true);
+        document.removeEventListener('pointerdown', this.onOutside, true);
+      }
       removeEventListener('pagehide', this.onPageHide);
       removeEventListener('pageshow', this.onPageShow);
       removeEventListener('scroll', this.onScroll);
@@ -463,6 +514,10 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.ahead?.();
       this.intent?.stop();
       this.intent = null;
+      clearTimeout(this.heldTimer);
+      this.heldTimer = 0;
+      this.endCue();
+      this.removeAttribute('data-lbx-swap');
       this.sized?.ro.disconnect();
       this.sized = null;
       this.unwatchApply?.();
@@ -487,7 +542,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       // 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]');
+      const tg = MENU ? target.closest?.('[data-lbx-toggle]') : null;
       if (tg && this.contains(tg)) {
         e.preventDefault();
         // Ours alone: host code delegating on the same (their) dropdown classes must not toggle it too.
@@ -497,7 +552,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
         if (menu) setMenu(menu, !menu.hasAttribute('data-lbx-open'), byKeyboard(e));
         return;
       }
-      const d = target.closest?.('[data-lbx-drawer]');
+      const d = DRAWER ? target.closest?.('[data-lbx-drawer]') : null;
       if (!d || !this.contains(d)) {
         // A link to another page (a product): remembered for Back.
         const away = restoreOn && leavingLink(e, this);
@@ -547,14 +602,14 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (this.href) this.scrolls.set(this.href, this.y);
       const y = this.scrolls.get(href);
       this.restoreY = y == null ? null : { href, y };
-      if (this.hasAttribute('data-drawer-open') && !this.drawerBack) this.setDrawer(false);
+      if (DRAWER && this.hasAttribute('data-drawer-open') && !this.drawerBack) this.setDrawer(false);
     }
 
     /**
      * Where the shopper was in each state of the visit left by a change of
      * ours or a traversal (canonical href → scrollY), and the one a traversal
      * goes back to: drawn whole (not in steps) and placed there. Bug (a
-     * bicycle shop's QA round 4, 2026-10-15): Back after a drawer filter
+     * production storefront, 2026-10-15): Back after a drawer filter
      * drew the list in steps, the browser's restored scroll was clamped to
      * the first step's short page, and Chromium's scroll anchoring kept the
      * footer in view as the tiles went in above it.
@@ -567,7 +622,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
 
     /** 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');
+      return DRAWER ? this.stagedMode && this.hasAttribute('data-drawer-open') : false;
     }
 
     /**
@@ -577,24 +632,52 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * middle, the count and the first tiles above the viewport.
      */
     private applyStaged(from?: HTMLElement) {
+      if (!DRAWER) return;
       const next = this.staged;
       this.staged = null;
-      this.setDrawer(false, from, next ? () => (this.navigate(next), (this.topFor = this.wantedHref), this.toListTop()) : undefined);
+      // Changes not fetched yet (Apply within SETTLE_MS of the last): their
+      // request starts in the next task (the drawer closes first), while the
+      // drawer's entry is taken back, and the navigation joins it.
+      if (next && this.heldTimer) setTimeout(() => this.prefetchHeld(next), 0);
+      // Another state to show: the list it replaces dims now, as the drawer closes (./applied.ts).
+      const cue = (this.applyCue = next && canon(route.write(new URL(location.href), next).href) !== this.href ? { href: '' } : null);
+      this.toggleAttribute('data-lbx-swap', !!cue);
+      this.setDrawer(false, from, next ? () => {
+        this.navigate(next);
+        this.topFor = this.wantedHref;
+        if (cue) cue.href = this.wantedHref ?? '';
+        if (cue && !cue.href) this.removeAttribute('data-lbx-swap'), (this.applyCue = null); // nothing to fetch after all
+        this.toListTop();
+      } : undefined);
     }
 
     /** The state an Apply asked for: its render brings the listing's top into view again (late layout, a smooth scroll cut short). */
     private topFor: string | null = null;
+    /**
+     * An Apply's swap (./applied.ts): the state it asked for ('' until its
+     * navigation; the old list dimmed meanwhile, `data-lbx-swap`); its words
+     * and state while its render puts the new tiles in (swapIn(), from the
+     * step that draws them); then the status shown for the state applied,
+     * what takes it away, and when.
+     */
+    private applyCue: { href: string } | null = null;
+    private swapping: { say: string; href: string } | null = null;
+    private cue: { end: (fade: boolean) => void; href: string; timer: number } | null = null;
+    /** What the applied state's render announces (the status's words). */
+    private appliedSay: string | null = null;
     /** The top of the listing in view when it is above the viewport (smooth, unless reduced motion is asked for). */
     private toListTop() {
       if (!this.isConnected || this.getBoundingClientRect().top >= 0) return;
-      const reduce = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
-      this.scrollIntoView({ block: 'start', behavior: (reduce ? 'instant' : 'smooth') as ScrollBehavior });
+      this.scrollIntoView({ block: 'start', behavior: (reduced() ? 'instant' : 'smooth') as ScrollBehavior });
     }
 
     /** The drawer's held changes dropped: it shows the applied state again. */
     private discardStaged() {
       if (!this.staged) return;
       this.staged = null;
+      // A fetch of what it held, started already, is left to expire (./intent.ts); one not started yet is not.
+      clearTimeout(this.heldTimer);
+      this.heldTimer = 0;
       this.redraw();
     }
 
@@ -610,6 +693,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * takes the entry back first, then runs `then`.
      */
     private setDrawer(open: boolean, from?: HTMLElement, then?: () => void) {
+      if (!DRAWER) return;
       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));
@@ -618,6 +702,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       if (!open) this.discardStaged();
       if (open && !was) {
         this.stagedMode = atWidth(cfg.facetsApply, 'instant', viewport) === 'staged';
+        if (this.stagedMode) askApplied();
         if (this.stagedMode && !this.drawerEntry)
           try {
             history.pushState(null, '', location.href);
@@ -667,14 +752,15 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     /**
      * The open drawer closes when the viewport crosses into another
      * `facetsApply` mode (a phone rotated, a window widened): the drawer was a
-     * phone's, and what it held was never confirmed. Regression (a bicycle
-     * shop, `{ 0: 'staged', 992: 'instant' }`, 2026-10-14): a value ticked in
+     * phone's, and what it held was never confirmed. Regression (a production
+     * storefront, `{ 0: 'staged', 992: 'instant' }`, 2026-10-14): a value ticked in
      * the drawer at 820 px stayed ticked in the 992 px sidebar with the
      * results unfiltered and no apply button there, and rotating back showed
      * the full-screen drawer again (`data-drawer-open` had stayed). Dropping
      * is safer than applying: the shopper never pressed Apply.
      */
     private watchApply() {
+      if (!DRAWER) return;
       const v = cfg.facetsApply;
       if (!v || typeof v !== 'object' || typeof matchMedia !== 'function') return;
       const mode = atWidth(v, 'instant', viewport);
@@ -693,14 +779,14 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      */
     private onKey = (e: KeyboardEvent) => {
       const target = e.target as Element;
-      const menu = target.closest?.('[data-lbx-menu][data-lbx-open]');
+      const menu = MENU ? target.closest?.('[data-lbx-menu][data-lbx-open]') : null;
       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')) {
+        } else if (DRAWER && this.hasAttribute('data-drawer-open')) {
           e.preventDefault();
           e.stopPropagation();
           this.setDrawer(false);
@@ -716,7 +802,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
         items[next].focus();
         return;
       }
-      if (e.key === 'Tab' && this.hasAttribute('data-drawer-open')) {
+      if (DRAWER && e.key === 'Tab' && this.hasAttribute('data-drawer-open')) {
         const panel = this.querySelector('[data-lbx-drawer-panel]');
         if (panel) trapTab(e, panel);
         return;
@@ -726,7 +812,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
 
     /** 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]');
+      const menu = MENU ? (e.target as Element).closest?.('[data-lbx-menu][data-lbx-open]') : null;
       if (menu && !(e.relatedTarget && menu.contains(e.relatedTarget as Node))) setMenu(menu, false);
     };
 
@@ -737,12 +823,12 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
         root.setAttribute('data-lbx-a11y', '');
         const live = liveRegion();
         root.append(live.el);
-        if (ctx.global.contrastToggle) root.append(contrastToggle(t('contrast')));
+        toggle?.then((m) => root.append(m.contrastToggle(t('contrast'))), (e) => reportError(`${route.id} contrast toggle`, e));
         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')));
+      if (MENU) for (const m of this.querySelectorAll('[data-lbx-menu]')) setMenu(m, m.hasAttribute('data-lbx-open'));
+      if (DRAWER) 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;
@@ -770,8 +856,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * 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);
+      if (DROPDOWN) for (const d of this.querySelectorAll('details[data-lbx-dropdown][open]')) if (!d.contains(e.target as Node)) d.removeAttribute('open');
+      if (MENU) for (const d of this.querySelectorAll('[data-lbx-menu][data-lbx-open]')) if (!d.contains(e.target as Node)) setMenu(d, false);
     };
 
     /**
@@ -809,12 +895,18 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       return w;
     }
 
-    /** UI -> URL. The resulting URL change drives sync(). In a drawer that stages: held there, nothing fetched. */
+    /**
+     * UI -> URL. The resulting URL change drives sync(). In a drawer that
+     * stages: held there, its state fetched in the background once the
+     * changes pause (nothing drawn from it until Apply).
+     */
     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);
+        clearTimeout(this.heldTimer);
+        if (DRAWER && prefetchFilters) this.heldTimer = window.setTimeout(() => this.staging() && this.staged && this.prefetchHeld(this.staged), SETTLE_MS);
         return this.redraw();
       }
       this.navigate(nextState(this.wanted ?? stateOf(this.current), this.shown ?? stateOf(this.current), patch));
@@ -930,7 +1022,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       // 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) {
+      if (SSR && 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 {
@@ -962,6 +1054,9 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       const ek = !pf && prefetchFilters ? earlyKey(q) : null;
       const pre = ek ? early.take(ek) : undefined;
       early.abortInFlight();
+      // Server markup still being parsed (a streamed include): decided out
+      // here, not in the try below (Rollup folds no flag in a try).
+      const serverParsing = SSR ? () => !!this.ssr && document.readyState === 'loading' : () => false;
       try {
         let res: ListingResult;
         let shownEarly = false;
@@ -994,7 +1089,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
             this.message = null;
             // Another state of the visit shown (a filter, a sort): its sidebar
             // stays until the new facets come, as from the intent prefetch.
-            // Bug (a bicycle shop's QA round 3, 2026-10-15): drawn with no
+            // Bug (a production storefront, 2026-10-15): drawn with no
             // facets, the sidebar collapsed to one group for ~250 ms and
             // Chromium's scroll anchoring threw the page to its top.
             const last = this.last;
@@ -1013,7 +1108,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
         }
         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') {
+        if (serverParsing()) {
           await new Promise((r) => document.addEventListener('DOMContentLoaded', r, { once: true }));
           if (this.href !== href) return;
         }
@@ -1066,11 +1161,12 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       }
       this.images();
       if (tk.state === 'ours') this.watch();
+      if (DRAWER) this.swapIn(); // an Apply's new tiles, if these are they
     }
 
     /** 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);
+      settleImages(this, (NAMED_FADE ? imgs.fade !== false : true));
     }
 
     /** Render anew, dropping the state lit keeps on the container (or it reuses it and paints nothing). */
@@ -1155,11 +1251,11 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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)) {
+      if ((NAMED_PREFETCH_NEXT_PAGE ? cfg.prefetchNextPage !== false : true) && 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);
+      if (res.hits[0] && (NAMED_PRECONNECT_IMAGES ? ctx.global.preconnectImages !== false : true)) preconnectImages(ctx.result(res.hits[0]).c.image);
     }
 
     /**
@@ -1227,25 +1323,89 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     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;
+      if (this.staging() || !this.settled(cur)) 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);
+      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;
+      this.prefetchState(url, 'on intent');
+    }
+
+    /**
+     * What the open staged drawer holds, fetched in the background (its
+     * changes paused for SETTLE_MS, or Apply came first): its first page into
+     * `early`, which Apply's sync() takes, done or in flight. Nothing is drawn
+     * from it, no hook runs, no URL is written: the results change on Apply
+     * only. A newer held state aborts the older one still out; back at the
+     * state shown, nothing is fetched. Limits as on intent (thrifty(), the
+     * visit's cap; none with `prefetchFilters` off: no timer is set).
+     */
+    private prefetchHeld(st: UiState) {
+      if (!DRAWER) return;
+      clearTimeout(this.heldTimer);
+      this.heldTimer = 0;
+      const cur = this.current;
+      if (!this.settled(cur)) return;
+      const why = "of the drawer's held state";
+      // The request this held state starts (or finds cached, or none): the older one still out goes.
+      const keyed = (k: string | null) => {
+        const was = this.heldKey;
+        if (was && was !== k) early.drop(was);
+        this.heldKey = k;
+      };
+      // From a timer: a route hook that throws (fromUrl) must not reach the
+      // site. Nothing is fetched; the drawer keeps what it holds, and Apply
+      // reports the hook's failure as any navigation does.
+      try {
+        const url = route.write(new URL(location.href), st);
+        if (canon(url.href) === this.href) return keyed(null);
+        // The query Apply's sync() will resolve from that URL: the same
+        // request, to the order of the values (a value map puts some in the
+        // site's param, the others in ours, read back first). When the route
+        // has it at hand (memoised), that one. Else the state held, at once
+        // (resolving the URL's slugs may ask the category's values first:
+        // two requests in a row), and once resolved, the URL's own query
+        // supersedes it if its request differs (the same: nothing more).
+        const r = route.resolve(url);
+        if (!isPromise(r)) return this.prefetchState(r, why, keyed);
+        this.prefetchState({ ...cur, ...st }, why, keyed);
+        r.then((q) => void (this.staged === st && this.prefetchState(q, why, keyed))).catch(prefetchFailed);
+      } catch (e) {
+        prefetchFailed(e);
+      }
+    }
+
+    /** A listing of ours to fetch ahead from: the current state shown, nothing pending for it, a connection that allows it. */
+    private settled(cur: Query | null): cur is Query {
+      return !!cur && !!this.last && this.lastQ === cur && !this.inFlight && !this.wanted && tk.state === 'ours' && !thrifty();
+    }
+
+    /**
+     * Another state of this visit (a control's URL, or a held state's
+     * query), not cached: its first page, the request sync() starts with
+     * (`firstRequest`), fetched ahead into `early` and never rendered from
+     * here. `keyed`: told the request's key (null: none) before it starts,
+     * also when there is nothing to start (cached).
+     */
+    private prefetchState(to: URL | Query | null, why: string, keyed?: (k: string | null) => void) {
+      const cur = this.current!;
       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;
+        if (!q || this.href !== from || this.inFlight || this.wanted || visitOf(q) !== visitOf(cur)) return;
         const req = firstRequest(ctx.global, cfg, route, q);
+        const k = req && JSON.stringify(req);
+        keyed?.(k);
+        if (!k || cache.get(keyOf(q))) return;
         // 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`);
+        if (early.start(k, visitOf(q), fetch)) mark(`${route.id} prefetch ${why}`);
       };
-      const r = route.resolve(url);
-      if (isPromise(r)) r.then(then).catch((e) => reportError(`${route.id} filter prefetch`, e));
+      if (!(to instanceof URL)) return then(to);
+      if (canon(to.href) === from) return;
+      const r = route.resolve(to);
+      if (isPromise(r)) r.then(then).catch(prefetchFailed);
       else then(r);
     }
 
@@ -1266,14 +1426,63 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.waited = null;
       const was = this.last;
       const quiet = this.quiet;
+      // An Apply's swap (./applied.ts): any render after its navigation ends
+      // it; the applied state's own render, not an error's, says what was
+      // applied, and its first step brings the new tiles in (swapIn()).
+      const href = DRAWER ? canon(url.href) : '';
+      const cue = DRAWER && this.applyCue?.href ? this.applyCue : null;
+      const say = cue && href === cue.href && !this.message ? t('applied', { results: found(q, res) }) : null;
+      if (cue) this.applyCue = null;
+      if (DRAWER && this.cue && this.cue.href !== href) this.endCue();
+      // A render of the same state before the swap's step drew its tiles (the
+      // facets, before a first step a frame late on a phone): it carries the
+      // swap on; it dropped it, and the list stayed dimmed for the visit.
+      if (DRAWER) (this.appliedSay = say), (this.swapping = say && tk.state === 'ours' ? { say, href } : this.swapping?.href === href ? this.swapping : null);
       this.guarded(() => this.draw(q, res, url));
-      if (w && !w.dimmed && was && !quiet && tk.state === 'ours' && !sameHits(res, was)) this.fadeIn();
+      if (DRAWER) (this.appliedSay = null), !this.swapping && this.removeAttribute('data-lbx-swap');
+      if (!say && w && !w.dimmed && was && !quiet && tk.state === 'ours' && !sameHits(res, was)) this.fadeIn();
+    }
+
+    /**
+     * The applied state's tiles are in (the render's first step): the old
+     * list's dim ends, those in view come in, and the status says what was
+     * applied for APPLIED_MS (`data-lbx-applied` on the element meanwhile,
+     * for the site's own cue). Without the cue's chunk (not loaded yet, or
+     * failed), only the dim ends: the status region still says it.
+     */
+    private swapIn() {
+      const s = DRAWER ? this.swapping : null;
+      if (!s) return;
+      this.swapping = null;
+      this.removeAttribute('data-lbx-swap');
+      if (!applied) return;
+      this.endCue();
+      const tiles = [...(this.querySelector('[data-lbx-list]')?.children ?? [])].slice(0, SWAP_TILES);
+      let end: (fade: boolean) => void;
+      try {
+        end = applied.swapIn(this, tiles, s.say, this.a11y?.root ?? null, reduced());
+      } catch (e) {
+        // In the render's step: a failure of the cue costs the cue, never the listing (guarded() would hand it back).
+        return reportError(`${route.id} applied cue`, e);
+      }
+      this.setAttribute('data-lbx-applied', '');
+      this.cue = { end, href: s.href, timer: window.setTimeout(() => this.endCue(true), APPLIED_MS) };
+    }
+
+    /** The status of an Apply taken away: faded out once its time is up, at once when another state renders. */
+    private endCue(fade = false) {
+      const c = DRAWER ? this.cue : null;
+      if (!c) return;
+      this.cue = null;
+      clearTimeout(c.timer);
+      this.removeAttribute('data-lbx-applied');
+      c.end(fade);
     }
 
     /** 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;
+      if (!list || typeof list.animate !== 'function' || reduced()) return;
       this.fade?.cancel();
       this.fade = list.animate([{ opacity: FADE_FROM }, { opacity: 1 }], { duration: FADE_MS, easing: 'cubic-bezier(.2,0,0,1)' });
     }
@@ -1285,6 +1494,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       } catch (e) {
         reportError(`${route.id} render`, e);
         this.setBusy(false);
+        // An Apply's swap under way: the list handed back is not left dimmed.
+        if (DRAWER) (this.swapping = null), this.removeAttribute('data-lbx-swap');
         // 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$;
@@ -1349,18 +1560,6 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       }, 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;
@@ -1388,8 +1587,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
           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 (DROPDOWN) at?.closest('details[data-lbx-dropdown]')?.removeAttribute('open');
+          const menu = MENU ? at?.closest('[data-lbx-menu]') : null;
           if (menu) {
             setMenu(menu, false);
             // Its item had focus: back to the menu's button, not lost with the closed menu.
@@ -1440,7 +1639,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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 }));
+      const said = this.message ?? this.appliedSay ?? (grew ? t('shown', { shown: res.hits.length, total: res.total, count: res.total }) : found(q, res));
       // 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).
@@ -1468,11 +1667,11 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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) {
+      if (SSR && this.ssr && !this.hydrateWith) {
         this.ssr = false;
         this.server ??= [...this.childNodes];
       }
-      if (this.ssr && this.hydrateWith) {
+      if (SSR && this.ssr && this.hydrateWith) {
         this.ssr = false;
         const markup = [...this.childNodes];
         try {
@@ -1605,6 +1804,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
             if (!res.pending) this.setBusy(false); // the products alone: busy until their facets
             return this.finish(q, res, url, total, fonts, shown);
           }
+          // The next step after a frame (afterFrame: a task soon where frames are stalled; each step's
+          // wait was 500 ms then, five steps 2.5 s of nothing shown, 2026-10-19).
           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.
@@ -1796,7 +1997,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       // 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)
+      if (ON_RENDER && !res.pending)
         whenShown(() => {
           try {
             cfg.onRender?.(info);