@luigisbox/luma 0.5.0 → 0.7.0

package/src/widgets/listing/applied.ts

@@ -0,0 +1,87 @@
+// Apply in a staged drawer, marked (element.ts swapIn): a change the shopper
+// confirmed with the drawer closing over the list must read as one. On an
+// iPhone the quiet fade of a prefetched result read as a flicker: had the
+// filters been taken? (2026-10-19) The list it replaces dims at the tap
+// (`data-lbx-swap`, as busy's dim: `--lbx-c-dim` holds it in the contrast
+// mode), the new tiles come in, and a status at the listing's top says what
+// was applied. Its own chunk (lbx-applied), asked for when a drawer opens
+// where it stages: a listing page that never applies one does not load it.
+import { cspNonce, layered, setCss } from '../../core/styles';
+
+const SWAP_MS = 300;
+export const CSS =
+  ':is(lbx-search,lbx-plp)[data-lbx-swap] [data-lbx-list]{opacity:var(--lbx-c-dim,.15)}' +
+  '@media (forced-colors:active){:is(lbx-search,lbx-plp)[data-lbx-swap] [data-lbx-list]{opacity:.6}}' +
+  // The contrast mode (core/a11y.ts): the pill opaque, nothing of the page through it.
+  ':root[data-lbx-contrast="more"] [data-lbx-applied-cue]{--lbx-applied-opaque:1}' +
+  '@media (prefers-contrast:more){:root:not([data-lbx-contrast="off"]) [data-lbx-applied-cue]{--lbx-applied-opaque:1}}';
+// The pill is the one element with Luma's own look in the site's light
+// DOM: a site's reset (`div,span{margin:0;padding:0}`, unlayered, so
+// above Luma's layered CSS) took its padding and centring (a production storefront,
+// 2026-10-19). Its wrapper's layout is its inline style (`!important`, as the
+// status region's); the pill is in the wrapper's shadow root, with its own
+// sheet. A site restyles it through `::part(pill)` or the `--lbx-applied-*`
+// properties, which inherit into it.
+// Sticky, 0 px high, the pill out of flow: margins collapse through it, nothing moves (a flex wrapper moved the list 16 px).
+// What else a site's rule on `div` could set and break: clipped (overflow), given height (min-height: the list moves), narrowed (float, width).
+export const WRAP =
+  'display:block!important;position:sticky!important;top:var(--lbx-applied-top,8px)!important;z-index:3!important;height:0!important;min-height:0!important;max-height:none!important;' +
+  'width:auto!important;max-width:none!important;float:none!important;margin:0!important;padding:0!important;border:0!important;overflow:visible!important;transform:none!important;filter:none!important;' +
+  'opacity:1!important;visibility:visible!important;contain:none!important;pointer-events:none!important';
+export const PILL =
+  // Wraps (a long query, a long language) rather than cut: its words are shown nowhere else. A tap goes through it
+  // (all:initial put pointer-events back: it took taps on what it overlaps). Its font the site's; its size at least the reader's default's 15/16.
+  // `--lbx-applied-offset`: below the listing's top by this much (a template whose heading sits there).
+  '.p{all:initial;display:block;position:absolute;top:var(--lbx-applied-offset,0px);left:0;right:0;box-sizing:border-box;width:fit-content;max-width:calc(100% - 16px);margin:0 auto;padding:8px 16px;border-radius:18px;pointer-events:none;' +
+  'background:var(--lbx-applied-bg,#1d2433);color:var(--lbx-applied-fg,#fff);font-family:inherit;font-size:max(15px,.9375rem);font-weight:500;line-height:1.3;text-align:center;overflow-wrap:anywhere;box-shadow:0 2px 12px rgb(0 0 0/.25)}' +
+  // A little of the page through it, blurred (white text at least 10:1 over any page behind); opaque in the contrast mode (--lbx-applied-opaque).
+  '@supports (backdrop-filter:blur(1px)) or (-webkit-backdrop-filter:blur(1px)){.p{background:var(--lbx-applied-bg,rgb(29 36 51/calc(.88 + .12 * var(--lbx-applied-opaque,0))));' +
+  '-webkit-backdrop-filter:blur(calc(8px - 8px * var(--lbx-applied-opaque,0)));backdrop-filter:blur(calc(8px - 8px * var(--lbx-applied-opaque,0)))}}' +
+  '@media (forced-colors:active){.p{border:1px solid CanvasText;background:Canvas;color:CanvasText}}';
+let sheet: CSSStyleSheet | null = null;
+
+/** Its styles, before the first Apply (the drawer's opening restyles the page anyway). */
+export const prepare = () => setCss('listing-applied', layered(CSS));
+
+/**
+ * The applied state's first tiles come in (rising row after row, only fading
+ * under reduced motion), and the status's pill goes after `after` (Luma's
+ * status region, which says the same words: the pill is hidden from
+ * assistive technology). Returns what takes the pill away (faded, or at once).
+ */
+export const swapIn = (host: HTMLElement, tiles: Element[], say: string, after: Element | null, reduce: boolean) => {
+  tiles.forEach((el, i) =>
+    el.animate(reduce ? [{ opacity: 0 }, { opacity: 1 }] : [{ opacity: 0, transform: 'translateY(12px)' }, { opacity: 1, transform: 'none' }], {
+      duration: SWAP_MS,
+      delay: reduce ? 0 : Math.min(i, 7) * 35,
+      easing: 'cubic-bezier(.2,0,0,1)',
+      fill: 'backwards',
+    }),
+  );
+  const el = document.createElement('div');
+  el.setAttribute('data-lbx-applied-cue', '');
+  el.setAttribute('aria-hidden', 'true');
+  el.style.cssText = WRAP;
+  const root = el.attachShadow({ mode: 'open' });
+  // Safari before 16.4 has no constructed sheets (its constructor throws): a <style>, with the page's nonce.
+  if ('adoptedStyleSheets' in ShadowRoot.prototype) {
+    if (!sheet) (sheet = new CSSStyleSheet()), sheet.replaceSync(PILL);
+    root.adoptedStyleSheets = [sheet];
+  } else {
+    const st = root.appendChild(document.createElement('style'));
+    st.nonce = cspNonce();
+    st.textContent = PILL;
+  }
+  const pill = root.appendChild(document.createElement('span'));
+  pill.className = 'p';
+  pill.setAttribute('part', 'pill');
+  pill.textContent = `✓ ${say}`;
+  if (after) after.after(el);
+  else host.prepend(el);
+  pill.animate([{ opacity: 0 }, { opacity: 1 }], 200);
+  return (fade: boolean) => {
+    if (!fade) return el.remove();
+    // A cancelled animation rejects `finished`: removed either way.
+    pill.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 300, fill: 'forwards' }).finished.then(() => el.remove(), () => el.remove());
+  };
+};

package/src/widgets/listing/element.ts

@@ -15,7 +15,7 @@
 
 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 { 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, VARIANTS } from '../../core/features';
 import { mark, reportError } from '../../core/health';
 import { claim } from '../../core/reconciler';
 import { afterLayout, rememberHeight } from '../../core/hold';
@@ -37,16 +37,22 @@ import { facetFields, handsBack, nextState, queryKey, stateOf, type Query, type
 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 type { Page } from '../../api';
-import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, viewport, type ListingView, type SsrState } from './view';
+import { firstPages, SETTLE_MS, targetOf, thrifty, watchIntent } from './intent';
+import type { Page, VariantGroup } from '../../api';
+import { atWidth, CV_CSS, DIM_MS, LOADING_CSS, listingData, ssrStateId, withGroups, viewport, type ListingView, type SsrState } from './view';
 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';
+import { askVariants, groupsOf, seedGroups, stashGroups } from './variants';
 
 /** 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. */
@@ -103,7 +109,8 @@ 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, SEARCH ? quickChannel(route.id) : undefined);
+    // `variants`: the first page's groups asked for as soon as it is here, with its facets' request.
+    const p = listingQuery(ctx.api, ctx.global, cfg, route, q, signal, pre, onProducts, SEARCH ? quickChannel(route.id) : undefined, VARIANTS && cfg.variants ? (f) => void askVariants(ctx.api, cfg, f, signal) : 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;
@@ -167,6 +174,17 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
   // 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);
@@ -217,6 +235,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     else if (stashed) {
       seeded.set(pageKey(location.href), stashed.query);
       cache.set(keyOf(stashed.query), stashed.result);
+      // `variants`: the groups it was left with, drawn with it (nothing asked).
+      if (VARIANTS) seedGroups(stashed.result, stashed.groups);
       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.
@@ -334,6 +354,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. */
@@ -490,6 +518,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?.();
@@ -581,7 +613,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
      * 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.
@@ -607,22 +639,49 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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();
     }
 
@@ -647,6 +706,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);
@@ -696,8 +756,8 @@ 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
@@ -839,12 +899,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));
@@ -1027,7 +1093,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;
@@ -1099,6 +1165,7 @@ 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. */
@@ -1124,7 +1191,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.leftAt = Math.round(scrollY);
       // The browser's own restoration off for this entry: Luma places the page after its render (holdScroll).
       const sr = holdScroll();
-      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a), sr })) mark(`${route.id} stashed for back`);
+      if (writeStash(location.href, { kind: 'back', route: route.id, query: this.lastQ, result: { ...this.last, quickPending: undefined }, scroll: scrollSpot(this, a), sr, groups: VARIANTS && cfg.variants ? stashGroups(this.last) : undefined })) mark(`${route.id} stashed for back`);
       else releaseScroll();
     }
 
@@ -1260,25 +1327,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);
     }
 
@@ -1287,6 +1418,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       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
+      // `variants`: its products' groups too (more() asks once), so "show more" draws them with its tiles.
+      if (VARIANTS && cfg.variants) more(q, res).then((r) => askVariants(ctx.api, cfg, r, this.ctrl?.signal), () => {});
     }
 
     private render(q: Query, res: ListingResult, url: URL) {
@@ -1299,14 +1432,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)' });
     }
@@ -1318,6 +1500,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$;
@@ -1401,7 +1585,7 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       const self = this;
       return {
         ...ctx.helpers,
-        ...listingData(ctx, route, url, q, res, this.message, this.view()),
+        ...listingData(ctx, route, url, q, res, this.message, VARIANTS && cfg.variants ? { ...this.view(), variants: (this.groups$?.res === res ? this.groups$ : (this.groups$ = { res, map: groupsOf(res) })).map } : this.view()),
         facetsOpen: matchMedia('(min-width: 768px)').matches,
         // actions
         go: (link: Link | null) => (e: Event) => {
@@ -1450,6 +1634,9 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     }
 
     private draw(q: Query, res: ListingResult, url: URL) {
+      // `variants`: the groups of these products, asked for now (those not
+      // asked yet), never waited for: finish() draws them when they land.
+      if (VARIANTS && cfg.variants) askVariants(ctx.api, cfg, res, this.ctrl?.signal);
       // 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);
@@ -1461,7 +1648,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).
@@ -1783,6 +1970,8 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
     }
     /** 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>();
+    /** `variants`: the groups the last scope of a result was built with (its map grows in steps as they land: finish()). */
+    declare private groups$: { res: ListingResult; map?: ReadonlyMap<string, VariantGroup> } | undefined;
     private past = false;
     private cols = 1;
     private io: IntersectionObserver | null = null;
@@ -1814,6 +2003,52 @@ export const startListing = async (ctx: WidgetContext<ListingConfig>, tk: Takeov
       this.drawn$ = { hits: res.hits, n: res.hits.length };
       this.lastQ = q;
       this.afterA11y();
+      // `variants`: drawn again once the groups of these products asked for
+      // have landed (now: during a render in steps), if they are still shown
+      // (a later render of other products draws its own).
+      if (VARIANTS && cfg.variants)
+        askVariants(ctx.api, cfg, res, this.ctrl?.signal).then(() => {
+          const got = groupsOf(res);
+          const had = this.groups$?.map;
+          if (!got || had === got) return;
+          // In steps, as a shown listing's re-render (each tile whose group
+          // landed runs its template again): the tiles in view first, then
+          // as many a frame as BUDGET holds by what one cost.
+          const tiles = this.querySelector('[data-lbx-list]')?.children;
+          const ids = res.hits.map((h, i) => [tiles && this.seen.has(tiles[i]) ? 0 : 1, h['@id']] as const).filter(([, id]) => got.has(id) && had?.get(id) !== got.get(id)).sort((a, b) => a[0] - b[0]).map(([, id]) => id);
+          const N = res.hits.length;
+          let n = 0;
+          let per = this.tileMs || 3;
+          let frames = 0;
+          const step = () => {
+            if (this.last !== res || this.drawn$?.hits !== res.hits || this.groups$?.res !== res || !this.drawn) return;
+            // STEP tiles first, to measure one (a tile drawn anew with its group
+            // costs what a new tile does: the tiles' cost learnt from a render
+            // in steps was 0.3 ms for 2 ms tiles, one step of all of them); then
+            // as a re-render in steps: as many as BUDGET holds with the tiles
+            // there run again, not even one, a third of the rest.
+            const room = Math.floor((BUDGET - RERUN * per * N) / per);
+            const k = Math.min(ids.length - n, !frames ? STEP : room >= 1 ? room : Math.ceil((ids.length - n) / 3));
+            const map = n + k >= ids.length ? got : new Map([...(this.groups$.map ?? []), ...ids.slice(n, n + k).map((id) => [id, got.get(id)!] as const)]);
+            n += k;
+            this.groups$ = { res, map };
+            // A tile's template may draw other markup with its group: focus in one replaced goes to the region, not the page's start.
+            const at = document.activeElement;
+            this.focusWas = at && at !== this && this.contains(at) ? at : null;
+            const t0 = performance.now();
+            // Only the results change: the scope is not built again (as setUi). A
+            // template throwing on the groups hands the page back, as a render does, and no step follows.
+            this.guarded(() => {
+              this.renderOrRebuild((this.drawn = { ...this.drawn!, results: res.hits.map(withGroups(ctx.result, map)) }));
+              this.afterA11y();
+              per = Math.max(0.5, (performance.now() - t0) / (k + RERUN * (N - k)));
+              frames++;
+              if (n < ids.length) afterFrame(step);
+              else mark(`${route.id} variants in ${frames} frames`);
+            });
+          };
+          step();
+        });
       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

package/src/widgets/listing/intent.ts

@@ -21,6 +21,12 @@
 // Results are never rendered by the prefetch itself: only a click whose
 // request is the same takes them.
 //
+// A drawer that stages (`facetsApply: 'staged'`) has no intent to watch: its
+// controls lead nowhere until Apply. There the held state itself is fetched
+// once the changes pause for SETTLE_MS (three quick ticks: one request), a
+// newer held state aborting the older one still out; Apply takes it as a
+// click does. Closing the drawer otherwise leaves it to expire.
+//
 // Limits: two in flight (a newer intent aborts the oldest), the state
 // changing aborts those still out (their controls now lead elsewhere), kept
 // TTL_MS, PER_VISIT per category or query, none with Save-Data, offline or on
@@ -36,6 +42,8 @@ import { reportError } from '../../core/health';
 
 /** Hover or focus this long counts as intent (Chrome's speculation rules wait ~200 ms on hover for a whole page; this is one request). */
 export const DWELL_MS = 100;
+/** A staged drawer's changes pause this long before its held state is fetched (element.ts `prefetchHeld`). */
+export const SETTLE_MS = 250;
 const TTL_MS = 30_000;
 /** First pages kept (done or in flight). */
 const KEEP = 6;
@@ -181,6 +189,13 @@ export const firstPages = () => {
       while (m.size > KEEP) m.delete(m.keys().next().value!);
       return true;
     },
+    /** One still out, no longer wanted (a staged drawer's older held state): aborted. A done one stays until it expires. */
+    drop(k: string) {
+      const e = m.get(k);
+      if (!e || e.settled) return;
+      e.ctrl.abort();
+      m.delete(k);
+    },
     /** The state changed: requests still out were for controls that now lead elsewhere. */
     abortInFlight() {
       for (const [k, e] of m)