@luigisbox/luma 0.0.0-stage → 0.1.0

package/src/widgets/autocomplete/index.ts

@@ -0,0 +1,1367 @@
+// Autocomplete without touching the host's input or its framework:
+//  - document-level capture listeners matched against event.target, so the
+//    host can re-render / duplicate / replace its input freely;
+//  - the dropdown lives in the top layer (popover) outside the host tree, so
+//    no z-index wars, no layout shift and no framework can remove it. By
+//    default its markup and CSS are ours, in a shadow root (the house design:
+//    a wide panel under the input, a full-screen sheet on a phone); with
+//    dom: 'light' it is a light-DOM element the site's own CSS styles (a 1:1
+//    port of the site's existing dropdown design);
+//  - one search request per configured type (products, categories, brands),
+//    in parallel, on the autocomplete's search surface;
+//  - plain Enter is left to the host, so its own router performs the
+//    navigation to its search page (SPA-friendly by construction); on our
+//    search page, its form's submit is a new query in place (search/in-place.ts).
+// Loaded by the entry on the first interaction with the search input.
+
+import { borrow, liveRegion, useContrast } from '../../core/a11y';
+import { luminanceOf, readable } from '../../core/color';
+import { onOwnBack } from '../../core/entries';
+import { mark, reportError } from '../../core/health';
+import { modalOf } from '../../core/own';
+import { byName, view } from '../../core/templates';
+import { first, navigable, plain, safeUrl } from '../../core/result';
+import { afterFrame } from '../../core/scheduler';
+import { onUrlChange } from '../../core/sense';
+import { cspNonce, setCss } from '../../core/styles';
+import type { WidgetContext } from '../../main';
+import type { AutocompleteConfigType, AutocompleteScope, Result } from '../../types';
+import css from './style-autocomplete.css?raw';
+
+export const templates = byName(import.meta.glob('./template-*.ts', { eager: true, import: 'default' }));
+
+/** Result pictures kept loaded, so a batch renders with them. */
+const PRELOAD_MAX = 60;
+/** How long a batch waits for its pictures. */
+const PICTURE_WAIT = 100;
+
+type CloseReason = NonNullable<Parameters<NonNullable<AutocompleteConfigType['onClose']>>[0]>;
+
+/** How far up from the input its visible field is looked for (never past its form). */
+const FIELD_LEVELS = 4;
+/** The dropdown's narrowest width where the screen has room for it. */
+const MIN_WIDTH = 360;
+/** The house panel: its widest, the list-only panel's width, the gutter it keeps from the screen's edges, and the width below which the top product has no column. */
+const PANEL_MAX = 1200;
+const PANEL_LIST = 560;
+const PANEL_GUTTER = 24;
+const PANEL_WIDE = 1000;
+/** Products beside the top product on the panel (2 x 3). */
+const GRID_MAX = 6;
+/** Phones (the viewport up to this width): the house design is a full-screen sheet. */
+const SHEET_MEDIA = '(max-width: 600px)';
+
+/** A computed colour that paints nothing (`rgba(0, 0, 0, 0)`, `transparent`, `color(srgb 0 0 0 / 0)`). */
+const clear = (c: string) => !c || c === 'transparent' || /(?:,|\/)\s*0(?:\.0*)?\)$/.test(c);
+
+/**
+ * The box draws a field: a visible border on any side, a shadow, or (an
+ * ancestor of the input only) a background. An input reset to `border: 0;
+ * background: none` inside a bordered wrapper draws nothing itself.
+ */
+const paints = (cs: CSSStyleDeclaration, background: boolean) =>
+  (['Top', 'Right', 'Bottom', 'Left'] as const).some((d) => parseFloat(cs[`border${d}Width`]) > 0 && !/^(?:none|hidden)$/.test(cs[`border${d}Style`]) && !clear(cs[`border${d}Color`])) ||
+  cs.boxShadow !== 'none' ||
+  (background && (!clear(cs.backgroundColor) || cs.backgroundImage !== 'none'));
+
+/** The parent across a shadow boundary (a web component's search box) and into a slot. */
+const up = (el: Element): Element | null => el.assignedSlot ?? el.parentElement ?? ((el.getRootNode() as ShadowRoot).host as Element | undefined) ?? null;
+
+/**
+ * The element the dropdown lines up with (left edge and width, just below
+ * it), read once per opening (styles and boxes, before anything of ours is
+ * written in that task):
+ * - `alignTo: 'input'`: the input;
+ * - `alignTo: '<selector>'`: the input's nearest ancestor matching it (across
+ *   shadow roots), else the input;
+ * - by default, the visible search field: the input when it draws its own
+ *   border or shadow; else the nearest ancestor, up to its form or
+ *   FIELD_LEVELS levels, that draws one (a border, a shadow or a background)
+ *   and is the field, not the bar it sits in: at least the input's width, not
+ *   much taller than it, not as wide as the page. Else the input.
+ */
+export const fieldOf = (input: HTMLInputElement, alignTo?: string): Element => {
+  if (alignTo === 'input') return input;
+  if (alignTo) {
+    for (let el = up(input); el; el = up(el)) {
+      try {
+        if (el.matches(alignTo)) return el;
+      } catch {
+        return input; // not a selector: reported by nobody, aligned as before
+      }
+    }
+    return input;
+  }
+  if (paints(getComputedStyle(input), false)) return input;
+  const r = input.getBoundingClientRect();
+  const vw = document.documentElement.clientWidth;
+  let el: Element | null = input;
+  for (let n = 0; n < FIELD_LEVELS; n++) {
+    el = up(el);
+    if (!el || el === document.body || el === document.documentElement) break;
+    const b = el.getBoundingClientRect();
+    if (b.width >= r.width && b.height <= r.height * 2 + 16 && b.width < vw - 16 && paints(getComputedStyle(el), true)) return el;
+    if (el.localName === 'form' || el.localName === 'dialog') break;
+  }
+  return input;
+};
+
+/**
+ * Where a light-DOM dropdown goes for a field's box in a viewport `vw` wide:
+ * its left edge and width the field's, at least MIN_WIDTH (a narrow field's
+ * dropdown still has room for a product row), lined up with the field's
+ * right edge instead when it would leave the screen. On a phone (narrower
+ * than 480 px): a field spanning most of the screen exactly, else the
+ * screen's width. Never closer than 8 px to an edge.
+ */
+export const dropdownBox = (r: { left: number; right: number; width: number }, vw: number) => {
+  const full = { left: 8, width: Math.max(0, vw - 16) };
+  if (vw < 480) return r.width >= vw * 0.75 ? { left: Math.max(8, r.left), width: Math.min(r.width, vw - 8 - Math.max(8, r.left)) } : full;
+  const width = Math.max(r.width, MIN_WIDTH);
+  if (width > vw - 16) return full;
+  const left = r.left + width <= vw - 8 ? Math.max(8, r.left) : Math.max(8, r.right - width);
+  return { left, width };
+};
+
+/**
+ * Where the house panel goes: `min(1200px, 100vw - 48px)` wide (560
+ * for a batch without products), centred under the field, kept 24 px from
+ * the screen's edges; its caret under the field's left edge + 30 px (inside
+ * the panel's corners). `wide`: the top product has its own column.
+ */
+export const panelBox = (r: { left: number; width: number }, vw: number, listOnly = false) => {
+  const width = Math.max(0, Math.min(listOnly ? PANEL_LIST : PANEL_MAX, vw - 2 * PANEL_GUTTER));
+  const left = Math.max(PANEL_GUTTER, Math.min(r.left + r.width / 2 - width / 2, vw - PANEL_GUTTER - width));
+  const caret = Math.max(16, Math.min(r.left + 30 - left, width - 30));
+  return { left, width, caret, wide: width >= PANEL_WIDE };
+};
+
+/** The house tokens a config may set (`autocomplete.tokens`), as their custom properties. */
+const TOKEN_PROPS: Record<string, string> = {
+  font: 'font',
+  fg: 'fg',
+  bg: 'bg',
+  accent: 'accent',
+  radius: 'radius',
+  muted: 'muted',
+  line: 'line',
+  soft: 'soft',
+  tint: 'tint',
+  tintStrong: 'tint-strong',
+  onAccent: 'on-accent',
+  ok: 'ok',
+  radiusRow: 'radius-row',
+  radiusTile: 'radius-tile',
+};
+/** `autocomplete.tokens` as a `:host` rule after ours (a value that could end the rule is dropped). */
+export const tokenCss = (tokens: AutocompleteConfigType['tokens']) => {
+  const decl = Object.entries(tokens ?? {})
+    .filter(([k, v]) => TOKEN_PROPS[k] && typeof v === 'string' && v.trim() && !/[;{}<>\\]/.test(v))
+    .map(([k, v]) => `--lbx-${TOKEN_PROPS[k]}: ${v!.trim()};`);
+  return decl.length ? `:host { ${decl.join(' ')} }` : '';
+};
+/** Text on an accent fill: white, or near-black on a light accent (luminance over 0.4). */
+export const onAccent = (accent: string) => ((luminanceOf(accent) ?? 0) > 0.4 ? '#0a0f12' : '#fff');
+
+export const start = (ctx: WidgetContext<AutocompleteConfigType>) => {
+  const ac = ctx.config;
+  const light = ac.dom === 'light';
+  const ORDER = ac.types.map((x) => x.type);
+  const PRODUCT = ctx.global.itemType ?? 'product';
+  const selector = ctx.global.inputSelector!;
+  // An empty phrase never asks (it closes the dropdown), whatever minChars says:
+  // the default 0 means the first letter asks.
+  const minChars = Math.max(1, ac.minChars ?? 0);
+  const t = ctx.t;
+  const empty = ac.emptyState ?? {};
+
+  let host: HTMLElement | null = null;
+  let box: HTMLElement | ShadowRoot;
+  let v: ReturnType<typeof view>;
+  let input: HTMLInputElement | null = null;
+  /** The batch's results (config order), what "Suggestions: N" counts. */
+  let results: Result[] = [];
+  /** The options on screen: the results, or with none, the "No results" layout's (phrases to try, links, fallback products). */
+  let items: Result[] = [];
+  /** The arrow keys' order over `items` (the house design's reading order: pills, lists, the top product, products). */
+  let order: number[] = [];
+  let lastQuery = '';
+  let active = -1;
+  let open = false;
+  let raf = 0;
+  let suppressInput = false;
+  /** Focus handed back to the input by us (Escape or Tab on "Show all products"): not the visitor coming back, nothing reopens. */
+  let quietFocus = false;
+  /** The phrase the dropdown is for (normalised input), '' while closed by the visitor or below minChars. */
+  let want = '';
+  /** Per type, what the dropdown shows. */
+  const shown = new Map<string, Result[]>();
+  /** The house panel: wide enough for the top product's column; a batch without products (the list alone, narrower). */
+  let wide = true;
+  let listOnly = false;
+  /** The phone sheet is what is open (house design, phone viewport); its input, its tab, our history entry. */
+  let sheet = false;
+  let mirror: HTMLInputElement | null = null;
+  let tab = '';
+  let entry = false;
+  let afterBack: (() => void) | null = null;
+  // Accessibility (docs/ACCESSIBILITY.md, "Autocomplete"): the host's input is
+  // the combobox. Its ARIA is borrowed while it has focus and put back when
+  // focus leaves it; the result count is announced politely, once typing pauses.
+  let aria: ReturnType<typeof borrow> | null = null;
+  const live = liveRegion();
+  /** What the region last said in this opening (a pause with the same count says nothing new). */
+  let said = '';
+  useContrast();
+
+  // Integration hooks: one that throws must not leave the dropdown half-open.
+  const hook = <A extends unknown[]>(name: string, fn: ((...a: A) => void) | undefined, ...args: A) => {
+    try {
+      fn?.(...args);
+    } catch (e) {
+      reportError(`autocomplete ${name}`, e);
+    }
+  };
+
+  /** The house design's phone sheet applies here (shadow DOM, a phone's viewport). */
+  const phone = () => !light && typeof matchMedia === 'function' && matchMedia(SHEET_MEDIA).matches;
+
+  /** Our shadow root on `el` with our CSS; the box templates render into. */
+  const shadowBox = (el: HTMLElement, ...before: Node[]) => {
+    const root = el.attachShadow({ mode: 'open' });
+    // Elements, not innerHTML: sites enforcing Trusted Types reject string HTML.
+    const style = document.createElement('style');
+    style.nonce = cspNonce();
+    // Ours, then the config's tokens, then the integration's CSS (which may set the same properties).
+    style.textContent = [css, tokenCss(ac.tokens), ...ctx.styles].join('\n');
+    const b = document.createElement('div');
+    b.className = 'lbx-root'; // the sheet fills the host (style-autocomplete.css)
+    root.append(style, ...before, b);
+    return b;
+  };
+
+  const ensureHost = () => {
+    if (host) return;
+    host = document.createElement('div');
+    host.setAttribute('data-lbx', 'ac-overlay');
+    host.setAttribute('popover', 'manual');
+    host.id = (light && ac.hostId) || 'lbx-ac-overlay';
+    if (light) {
+      // The site's CSS positions and paints it (their classes); only the UA
+      // popover styles the site's CSS does not expect are neutralised.
+      if (ac.hostClass) host.className = ac.hostClass;
+      host.style.cssText = 'position:fixed;inset:auto;border:0;color:inherit;pointer-events:auto;display:none !important;';
+      // The UA popover's height: fit-content makes a fixed panel the site pins
+      // with top + bottom (a full-height sheet on phones) grow past the screen
+      // instead of scrolling. Zero specificity: any site rule still wins.
+      setCss('ac:light', ':where([data-lbx="ac-overlay"]) { height: auto; }');
+      ctx.styles.forEach((c, i) => setCss(`itg:autocomplete:${i}`, c));
+      box = host;
+      host.append(live.el); // the templates render after it
+    } else {
+      // Neutralise UA popover styles; we position it ourselves. pointer-events:
+      // a modal library may set `pointer-events: none` on body, which inherits.
+      host.style.cssText = 'position:fixed;inset:auto;margin:0;padding:0;border:0;background:transparent;overflow:visible;pointer-events:auto;display:none !important;';
+      box = shadowBox(host, live.el);
+    }
+    v = view(box, ctx.templates);
+    // Keep focus in the host input (also keeps Bootstrap/Angular focus traps happy).
+    // A touch keeps it by its compatibility mousedown instead: WebKit (iOS)
+    // sends no click for a tap whose pointerdown was cancelled, so a tapped
+    // suggestion did nothing. In the phone sheet focus stays in its own
+    // input the same way (the keyboard stays up over a tab or a clear), and
+    // a press into that input itself places its caret.
+    const intoMirror = (e: Event) => sheet && e.composedPath()[0] === mirror;
+    box.addEventListener('pointerdown', (e) => e.pointerType !== 'touch' && !intoMirror(e) && e.preventDefault());
+    box.addEventListener('mousedown', (e) => !intoMirror(e) && e.preventDefault());
+    // "Show all products" has focus (Tab from the input): Shift+Tab goes back
+    // to the input, Escape closes and goes back, Tab moves on as from the
+    // input (focus put back on it, the browser's own Tab then leaves it: the
+    // page's next control after the input, wherever our dropdown sits). In
+    // the sheet, Tab is the browser's (back, input, clear, tabs, show all),
+    // the arrow keys move between tabs, Escape is its back button.
+    box.addEventListener('keydown', (e) => {
+      const el = e.composedPath()[0] as Element;
+      if (!inOverlay(el) || e.ctrlKey || e.metaKey) return;
+      if (sheet) {
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          e.stopPropagation();
+          leave('back');
+        } else if ((e.key === 'ArrowLeft' || e.key === 'ArrowRight') && el.getAttribute?.('role') === 'tab') {
+          e.preventDefault();
+          const tabs = [...(el.parentElement?.children ?? [])] as HTMLElement[];
+          const next = tabs[(tabs.indexOf(el as HTMLElement) + (e.key === 'ArrowRight' ? 1 : tabs.length - 1)) % tabs.length];
+          next?.click();
+          next?.focus();
+        }
+        return;
+      }
+      if (e.key !== 'Tab' && e.key !== 'Escape') return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation(); // ours, not a host modal's
+        close('escape');
+        backToInput();
+      } else if (e.shiftKey) {
+        e.preventDefault();
+        backToInput();
+      } else {
+        close('blur');
+        backToInput();
+      }
+    });
+    // Focus leaving the dropdown for anywhere but the input: closed, as when
+    // it leaves the input. Not the sheet: it covers the page, and its input
+    // lets go whenever the shopper puts the keyboard away to read.
+    box.addEventListener('focusout', () =>
+      setTimeout(() => {
+        if (sheet) return;
+        const f = focused();
+        if (f === input || inOverlay(f)) return;
+        close('blur');
+        release();
+      }, 0),
+    );
+  };
+
+  const sampleTokens = (i: HTMLInputElement, at: Element) => {
+    const cs = getComputedStyle(i);
+    const body = getComputedStyle(document.body);
+    const radius = at === i ? cs.borderRadius : getComputedStyle(at).borderRadius;
+    const accentEl = ac.accentFrom ? document.querySelector(ac.accentFrom) : null;
+    const accentCs = accentEl ? getComputedStyle(accentEl) : null;
+    const sampled = accentCs && !clear(accentCs.backgroundColor) ? accentCs.backgroundColor : accentCs?.color || body.color;
+    const s = host!.style;
+    // On our white panel, the host's colours only where they read (WCAG 1.4.3):
+    // a dark site's light body text, or a pale brand colour, would not.
+    const fg = readable(body.color, '#fff', '#1a1a1a');
+    const accent = ac.tokens?.accent ?? readable(sampled, '#fff', fg);
+    // The house design's five site tokens (style-autocomplete.css derives the
+    // rest; the config's and the integration's CSS override either).
+    s.setProperty('--lbx-s-font', cs.fontFamily);
+    s.setProperty('--lbx-s-fg', fg);
+    s.setProperty('--lbx-s-bg', '#fff');
+    s.setProperty('--lbx-s-accent', accent);
+    s.setProperty('--lbx-s-on-accent', onAccent(accent));
+    s.setProperty('--lbx-s-radius', `${Math.max(0, parseFloat(radius) || 0)}px`);
+  };
+
+  /** What the dropdown lines up with for this opening (`alignTo`): the visible search field, else the input. */
+  let field: Element | null = null;
+
+  /** Where the field is (null: hidden), read before anything of ours is written in the task. */
+  const measure = () => {
+    if (!input) return null;
+    // checkVisibility: not in Safari before 17.4.
+    if (!input.isConnected || input.getBoundingClientRect().width === 0 || (input.checkVisibility && !input.checkVisibility({ checkVisibilityCSS: true }))) return null;
+    const at = (field?.isConnected ? field : input).getBoundingClientRect();
+    return { r: at.width ? at : input.getBoundingClientRect(), vw: document.documentElement.clientWidth };
+  };
+  /**
+   * Where the dropdown is, every frame while open; `frame`: from the frame
+   * loop (else ahead of a render, which follows); `m`: the field measured
+   * before this task's writes (an opening: read after showing the popover,
+   * it forced a layout).
+   */
+  const position = (frame = false, m?: ReturnType<typeof measure>) => {
+    if (!open || !input) return;
+    const s = host!.style;
+    if (sheet) {
+      // Full screen: what shows of the page (the visual viewport, above the
+      // on-screen keyboard), so the sticky "Show all" sits above the keys.
+      const vv = window.visualViewport;
+      s.top = `${Math.round(vv?.offsetTop ?? 0)}px`;
+      s.left = `${Math.round(vv?.offsetLeft ?? 0)}px`;
+      s.width = `${Math.round(vv?.width ?? innerWidth)}px`;
+      s.height = `${Math.round(vv?.height ?? innerHeight)}px`;
+      raf = requestAnimationFrame(() => position(true));
+      return;
+    }
+    const got = m === undefined ? measure() : m;
+    if (!got) return close('hidden');
+    const { r, vw } = got;
+    s.top = `${Math.round(r.bottom + 4)}px`;
+    if (light) {
+      const { left, width } = dropdownBox(r, vw);
+      s.left = `${Math.round(left)}px`;
+      s.width = `${Math.round(width)}px`;
+    } else {
+      const p = panelBox(r, vw, listOnly);
+      s.left = `${Math.round(p.left)}px`;
+      s.width = `${Math.round(p.width)}px`;
+      s.setProperty('--lbx-caret', `${Math.round(p.caret)}px`);
+      s.setProperty('--lbx-max-h', `${Math.max(240, Math.round(innerHeight - r.bottom - 32))}px`);
+      // The window crossed the top product's breakpoint: drawn again for it (from the frame, not a layout read after a render).
+      if (p.wide !== wide) {
+        wide = p.wide;
+        if (frame) render();
+      }
+    }
+    raf = requestAnimationFrame(() => position(true));
+  };
+
+  /**
+   * The (hidden) dropdown into the document, ahead of showing it: inserting a
+   * node into <body> restyles the whole host page, and showPopover() would
+   * force that into the task that shows our results. Done on focus, it is part
+   * of the next frame's own rendering.
+   */
+  const place = () => {
+    ensureHost();
+    const parent = modalOf(input!) ?? document.body;
+    if (host!.parentNode !== parent) parent.append(host!);
+    watchRoots(input!);
+    if (!sheet) adopt(input!);
+  };
+
+  /**
+   * The input as a combobox (WAI-ARIA APG, list autocomplete): role, its
+   * popup, open or not. Set while the input has focus, put back as it was
+   * once focus leaves it (or another input takes over); attributes the host
+   * changes meanwhile are its own and stay.
+   */
+  const adopt = (i: HTMLInputElement) => {
+    if (aria?.el === i) return;
+    aria?.restore();
+    aria = borrow(i);
+    if (i.getAttribute('role') !== 'combobox') aria.set('role', 'combobox');
+    aria.set('aria-autocomplete', 'list');
+    aria.set('aria-expanded', String(open));
+    aria.set('aria-controls', host!.id);
+  };
+  const release = () => {
+    aria?.restore();
+    aria = null;
+  };
+  /**
+   * The selected row (the screen reader's focus stays on the input). An id
+   * reference resolves only in the input's own tree, never across a shadow
+   * boundary:
+   * - light DOM, the input in the document: aria-activedescendant, its id;
+   * - light DOM, the input in a shadow root (a web-component header): our
+   *   dropdown is in the document, which encloses that root, so the option is
+   *   referenced by element reflection (`ariaActiveDescendantElement`) where
+   *   the engine has it; never an id that would name nothing there;
+   * - the phone sheet: its own input is the combobox, in the same shadow root
+   *   as the options: aria-activedescendant, its id;
+   * - our shadow root (default), or no reflection: nothing can reference the
+   *   row, so it is announced through the dropdown's status region instead
+   *   (not for a row the pointer is over: `say` false).
+   */
+  const markActive = (say = true) => {
+    const row = active >= 0 ? (box.getRootNode() as Document | ShadowRoot).getElementById(`lbx-ac-${active}`) : null;
+    if (sheet && mirror) {
+      if (row) mirror.setAttribute('aria-activedescendant', row.id);
+      else mirror.removeAttribute('aria-activedescendant');
+    } else if (light && aria && (!row || row.getRootNode() === aria.el.getRootNode())) aria.set('aria-activedescendant', row?.id ?? null);
+    else if (light && aria && 'ariaActiveDescendantElement' in aria.el) {
+      // Reflection writes the attribute as '': borrowed, so it is put back as the host had it.
+      aria.set('aria-activedescendant', '');
+      (aria.el as any).ariaActiveDescendantElement = row;
+    } else if (row) {
+      if (light) aria?.set('aria-activedescendant', null);
+      if (say) live.say((row.textContent ?? '').replace(/\s+/g, ' ').trim(), 0);
+    }
+    return row;
+  };
+
+  const show = () => {
+    place();
+    if (!open) {
+      // The field and the site's colours: read after the focus's frame (prepare), else now.
+      // Reads first (the field, where it is, the colours), then our writes.
+      const fresh = prepared !== input;
+      if (fresh) field = fieldOf(input!, ac.alignTo);
+      const m = measure();
+      if (fresh && !light) sampleTokens(input!, field!);
+      prepared = null;
+      // Never trust UA popover styles for visibility: host CSS can override
+      // [popover]:not(:popover-open){display:none} (some sites do). Inline
+      // !important beats any host stylesheet.
+      host!.style.setProperty('display', 'block', 'important');
+      host!.style.removeProperty('visibility'); // a rehearsal's, still going on
+      host!.showPopover();
+      open = true;
+      aria?.set('aria-expanded', 'true');
+      hook('onOpen', ac.onOpen);
+      cancelAnimationFrame(raf);
+      // A hook may move the field (a storefront's opens its search strip, the
+      // input lower): placed from where it is now, not from `m`, read before
+      // it (otherwise the dropdown opens at the old place, then jumps).
+      position(false, ac.onOpen ? undefined : m);
+    }
+  };
+
+  /**
+   * The field the dropdown lines up with and the site's colours, read once
+   * the focus's frame has rendered (layout clean then), ahead of the first
+   * opening: read at the opening, after the page and our render had changed,
+   * they forced a style and layout into the task that shows the results.
+   */
+  let prepared: HTMLInputElement | null = null;
+  const prepare = (i: HTMLInputElement) =>
+    afterFrame(() => {
+      if (open || input !== i || !i.isConnected || sheet) return;
+      field = fieldOf(i, ac.alignTo);
+      if (!light) sampleTokens(i, field);
+      prepared = i;
+      place(); // after the reads: it dirties the page's style
+      rehearse();
+    });
+
+  /**
+   * The first results drawn twice as fast: a page's first opening paid
+   * one-time costs (lit preparing every template, the first style and
+   * layout of each text style: font matching, shaping) in the task that
+   * showed them and in the next frame, which a keystroke then waited for (on
+   * a production storefront at 4x CPU: a 91 ms render and a 38-48 ms layout; a later opening
+   * of the same page: 42 and 12 ms). Paid ahead, while the visitor starts
+   * typing and the first answers are on their way: a rehearsal renders the
+   * dropdown once, in steps (a few types at a time, each its own idle task),
+   * with placeholder rows of every configured type, laid out but invisible,
+   * then hidden and emptied: the real render finds lit's templates prepared
+   * and the browser's style and font work for each text style done (its rows
+   * would be new nodes anyway: keyed by result). The phone sheet is on
+   * screen when it renders (empty until the first results): rehearsed in an
+   * invisible twin of it, removed once done. The house design only (a
+   * light-DOM integration's host is their markup). Given up when the real
+   * results come first, or a template throws on the placeholders.
+   */
+  let rehearsed = false;
+  const rehearse = () => {
+    if (rehearsed || light || !host || results.length || (open && !sheet)) return;
+    rehearsed = true;
+    const fill = (f: string): unknown => (/price/i.test(f) ? 1290 : /image|img/i.test(f) ? '' : /url/i.test(f) ? '/' : /avail|stock/i.test(f) ? 1 : 'Lorem ipsum dolor sit amet');
+    const fake = ac.types.flatMap((x) =>
+      Array.from({ length: Math.min(x.size, 12) }, (_, n) =>
+        ctx.result({ ...Object.fromEntries((x.fields ?? []).map((f) => [f, fill(f)])), '@id': `rehearsal/${x.type}/${n}`, '@type': x.type, '@title': 'Lorem ipsum dolor sit amet consectetur' }),
+      ),
+    );
+    // A type at a time (the lists' small rows first), the products a third at a time.
+    const lists = fake.filter((r) => r.type !== PRODUCT);
+    const products = fake.filter((r) => r.type === PRODUCT);
+    const steps: Result[][] = [];
+    for (const type of ORDER.filter((x) => x !== PRODUCT)) steps.push([...(steps.at(-1) ?? []), ...lists.filter((r) => r.type === type)]);
+    const third = Math.ceil(products.length / 3);
+    for (let n = third; products.length && n < products.length + third; n += third) steps.push([...lists, ...products.slice(0, n)]);
+    // The sheet is on screen (open, empty until the first results): an
+    // invisible twin of it, the same CSS and the site's tokens, full screen.
+    const mode = sheet;
+    let twin: HTMLElement | null = null;
+    let tv: ReturnType<typeof view> | null = null;
+    const st = host.style;
+    const done = () => {
+      if (twin) twin.remove();
+      else {
+        st.removeProperty('visibility');
+        // Its rows emptied: showing them again would style placeholders the
+        // first results replace (in showPopover's forced style, the opening's task).
+        // Not real results drawn meanwhile, to be shown a frame later (an
+        // integration with onOpen, `later` in paint): it never draws once they
+        // are here, and emptying them opened an empty dropdown (2026-10-12).
+        if (!open) {
+          st.setProperty('display', 'none', 'important');
+          if (!results.length) v.clear();
+        }
+      }
+      mark('ac rehearsed');
+    };
+    const step = (k: number) => {
+      // Real results since (or the dropdown shown, the sheet closed): theirs from now on.
+      if (results.length || !input || sheet !== mode || (mode ? !open : open)) return done();
+      const was = { results, items, lastQuery, active, order, tab, v };
+      try {
+        if (k === 0) {
+          if (mode) {
+            twin = document.createElement('div');
+            twin.style.cssText = `${st.cssText};position:fixed;left:0;top:0;width:${innerWidth}px;height:${innerHeight}px;visibility:hidden;pointer-events:none;display:block !important`;
+            twin.setAttribute('aria-hidden', 'true');
+            tv = view(shadowBox(twin), ctx.templates);
+            document.body.append(twin);
+          } else {
+            const m = measure();
+            if (!m) return done();
+            st.setProperty('visibility', 'hidden');
+            st.top = '0px';
+            st.left = '0px';
+            st.width = `${Math.round(panelBox(m.r, m.vw).width)}px`;
+            st.setProperty('display', 'block', 'important');
+          }
+        }
+        if (tv) v = tv;
+        results = items = steps[k];
+        lastQuery = 'Lorem ipsum';
+        active = -1;
+        render();
+      } catch (e) {
+        reportError('autocomplete rehearsal', e);
+        return done();
+      } finally {
+        ({ results, items, lastQuery, active, order, tab, v } = was);
+      }
+      // The next step once this one is laid out (its frame), when the browser is idle again.
+      if (k + 1 < steps.length) idle(() => step(k + 1));
+      else afterFrame(done);
+    };
+    idle(() => step(0));
+  };
+  const idle = (f: () => void) => afterFrame(() => (typeof requestIdleCallback === 'function' ? requestIdleCallback(f, { timeout: 300 }) : setTimeout(f, 0)));
+
+  /**
+   * The phone sheet (house design): full screen over the page,
+   * opened when the site's input gets focus. Its own input takes the focus
+   * at once (in the tap's task: iOS shows its keyboard only for a focus in
+   * the gesture) with what the site's input holds; it is the combobox there.
+   * A history entry of ours (null state, the same URL) stands for it: Back
+   * closes it first (core/entries.ts `onOwnBack`). The page behind does not
+   * scroll while it is open.
+   */
+  const openSheet = () => {
+    const i = input!;
+    if (!open) {
+      sheet = true;
+      tab = '';
+      place();
+      sampleTokens(i, i);
+      host!.style.setProperty('display', 'block', 'important');
+      host!.showPopover();
+      open = true;
+      hook('onOpen', ac.onOpen);
+      setCss('ac:sheet', ':root { overflow: hidden !important; }');
+      try {
+        history.pushState(null, '', location.href);
+        entry = true;
+      } catch {}
+      cancelAnimationFrame(raf);
+      position();
+      render(); // with what the site's input holds
+      mirror = (box as ShadowRoot | HTMLElement).querySelector<HTMLInputElement>('[data-lbx-sheet-input]');
+    }
+    if (mirror) {
+      mirror.focus();
+      // The caret or selection the site's input has (where a tap put it, all
+      // of it after a Tab): typing goes on as it would have there.
+      const end = mirror.value.length;
+      try {
+        mirror.setSelectionRange(Math.min(i.selectionStart ?? end, end), Math.min(i.selectionEnd ?? end, end));
+      } catch {}
+    }
+    query(mirror?.value ?? i.value);
+    rehearse(); // the first results' one-time costs, while the visitor starts typing
+  };
+
+  // Back on our entry (the browser's Back, our back button's history.back()): the sheet closes, then what was waiting for it.
+  onOwnBack(() => {
+    if (!entry) return false;
+    entry = false;
+    const then = afterBack;
+    afterBack = null;
+    close(then ? pendingReason : 'back');
+    // After the frame: the browser restores the entry's scroll position
+    // after its popstate, which would undo a scroll of what follows (a new
+    // query in place goes to the top).
+    if (then) requestAnimationFrame(() => setTimeout(then, 0));
+    return true;
+  });
+  let pendingReason: CloseReason = 'back';
+  /**
+   * Close the sheet: our history entry first (history.back()), then `then`
+   * (a navigation, the site's search) once it is gone, so the shopper's Back
+   * from what follows is the page they were on, not our entry. Without one
+   * (or anywhere but the sheet): closed now, then `then`.
+   */
+  const leave = (reason: CloseReason, then?: () => void) => {
+    if (!sheet || !entry) {
+      close(reason);
+      then?.();
+      return;
+    }
+    const done = then ?? (() => {});
+    afterBack = done;
+    pendingReason = reason;
+    history.back();
+    // A Back the browser does not deliver (an entry it dropped): on after a while.
+    setTimeout(() => {
+      if (afterBack !== done) return;
+      afterBack = null;
+      entry = false;
+      close(reason);
+      done();
+    }, 600);
+  };
+
+  const close = (reason: CloseReason = 'api') => {
+    // Answers still on their way fill the cache but do not reopen it: only the
+    // visitor does (typing, focus, a press into the input).
+    want = '';
+    clearTimeout(timer); // a debounce still pending asks for nothing
+    timer = waiting = 0;
+    if (!open) return;
+    open = false;
+    active = -1;
+    cancelAnimationFrame(raf);
+    const wasSheet = sheet;
+    // The sheet had the focus: a browser that hands it back to the site's
+    // input as the popover hides must not reopen it (and its keyboard).
+    quietFocus = wasSheet;
+    try {
+      host!.hidePopover();
+    } catch {}
+    quietFocus = false;
+    host!.style.setProperty('display', 'none', 'important');
+    if (wasSheet) {
+      sheet = false;
+      entry = false; // left in history (the same URL) unless Back took it
+      setCss('ac:sheet', null);
+      host!.style.height = '';
+      mirror?.blur();
+      if (focused() === input) input?.blur();
+    }
+    aria?.set('aria-expanded', 'false');
+    aria?.set('aria-activedescendant', null);
+    live.clear();
+    said = '';
+    hook('onClose', ac.onClose, reason);
+  };
+
+  /** The sheet input's value the last render drew (its clear button). */
+  let drawnValue = '';
+  /** Rows as templates get them: the result and its index in `items`. */
+  const rowsOf = (pred: (r: Result) => boolean) => items.map((r, i) => ({ r, i })).filter(({ r }) => pred(r));
+
+  const render = () => {
+    if (!host) return;
+    const rows = items.map((r, i) => ({ r, i }));
+    const state: AutocompleteScope['state'] = results.length ? 'results' : lastQuery || !sheet ? 'empty' : 'idle';
+    const inResults = state === 'results';
+    const byType = (type: string) => (inResults ? rows.filter(({ r }) => r.type === type) : []);
+    const groups = inResults ? ORDER.map((kind) => ({ kind, label: t(`types.${kind}`), rows: byType(kind) })).filter((g) => g.rows.length) : [];
+    const products = byType(PRODUCT);
+    const lists = groups.filter((g) => g.kind !== PRODUCT && g.kind !== 'query');
+    // The sheet's tabs: one per type with results, products first.
+    const kinds = [...(products.length ? [PRODUCT] : []), ...lists.map((g) => g.kind)];
+    if (!kinds.includes(tab)) tab = kinds[0] ?? '';
+    const hero = products[0] ?? null;
+    const grid = sheet ? products.slice(1) : products.slice(wide ? 1 : 0, (wide ? 1 : 0) + GRID_MAX);
+    const emptyRows = (kind: string) => (state === 'empty' ? rowsOf((r) => (r as any).__empty === kind) : []);
+    const tries = emptyRows('try');
+    const browse = emptyRows('browse');
+    const fallback = emptyRows('fallback');
+    // The arrow keys' order: pills, the lists in config order, the
+    // top product, the products in reading order; in the sheet, the pills and
+    // the open tab's options; with no results, phrases to try, links, picks.
+    // A light-DOM integration's own markup keeps the config order.
+    const phrases = byType('query');
+    order = light
+      ? rows.map((x) => x.i)
+      : state === 'empty'
+        ? [...tries, ...browse, ...fallback].map((x) => x.i)
+        : sheet
+          ? [...phrases, ...(tab === PRODUCT ? products : byType(tab))].map((x) => x.i)
+          : [...phrases, ...lists.flatMap((g) => g.rows), ...(wide && hero ? [hero] : []), ...grid].map((x) => x.i);
+    if (active >= 0 && !order.includes(active)) active = -1;
+    const phoneNumber = t('help.phone');
+    const help = phoneNumber && phoneNumber !== 'help.phone' ? { title: t('help.title'), phone: phoneNumber, tel: phoneNumber.replace(/[^\d+]/g, ''), hours: t('help.hours').replace(/^help\.hours$/, '') } : null;
+    const value = (drawnValue = mirror?.value ?? input?.value ?? '');
+    const pick = (r: Result, name: string) => {
+      const x = first(r.c[name] ?? r.a[name]);
+      return x == null ? '' : x;
+    };
+    v.render('autocomplete-box', {
+      ...ctx.helpers,
+      query: lastQuery,
+      groups,
+      byType,
+      count: results.length,
+      active,
+      choose,
+      submitAll: () => submitAll(),
+      allHref: searchHref(input, sheet ? (mirror?.value ?? '') : undefined),
+      state,
+      sheet,
+      wide,
+      phrases,
+      lists,
+      hero: sheet || wide ? hero : null,
+      products: grid,
+      tabs: kinds.map((kind) => ({ kind, label: t(`types.${kind}`), selected: kind === tab, select: () => ((tab = kind), active >= 0 && (active = -1), render(), markActive()) })),
+      tab,
+      empty: { tries, browse, fallback, help },
+      hover,
+      unhover,
+      heroVariant: ac.hero?.variant === 'spec' ? 'spec' : 'image',
+      productLayout: ac.productLayout === 'list' ? 'list' : 'grid',
+      field: (r: Result, name: string) => {
+        const f = name === 'badge' ? ac.hero?.badgeField : (ac.productFields as Record<string, string | undefined> | undefined)?.[name];
+        if (!f) return '';
+        const x = pick(r, f);
+        if (name === 'availability') return typeof x === 'string' ? x : x === true || (typeof x === 'number' && x > 0) ? t('inStock') : '';
+        return x === '' || x === false ? '' : x;
+      },
+      specs: (r: Result) =>
+        (ac.hero?.specFields ?? [])
+          .map((f) => {
+            const label = t(`specs.${f}`);
+            return { label: label === `specs.${f}` ? f : label, value: String(pick(r, f) ?? '') };
+          })
+          .filter((x) => x.value)
+          .slice(0, 4),
+      value,
+      placeholder: input?.placeholder ?? '',
+      inputLabel: input?.getAttribute('aria-label') || input?.placeholder || t('label'),
+      clear: () => {
+        if (!mirror) return;
+        mirror.value = '';
+        mirror.focus();
+        typed();
+        query('');
+      },
+      back: () => leave('back'),
+    });
+  };
+
+  /**
+   * The search page of what the input holds: its GET form's action with the
+   * form's fields ('' for another form, a POST, a non-web action). The link's
+   * target only: its click still hands the query to the host (submitViaHost).
+   * `value`: the phrase instead of the input's (the phone sheet's own input).
+   */
+  const searchHref = (i: HTMLInputElement | null, value?: string) => {
+    const f = i?.form;
+    if (!f || (f.getAttribute('method') || 'get').trim().toLowerCase() !== 'get') return '';
+    try {
+      const u = new URL(f.getAttribute('action')?.trim() || location.href, document.baseURI);
+      const p = new URLSearchParams();
+      for (const [k, v] of new FormData(f)) if (typeof v === 'string') p.append(k, v);
+      if (value !== undefined && i!.name) p.set(i!.name, value);
+      u.search = p.toString();
+      return u.protocol === 'https:' || u.protocol === 'http:' ? u.href : '';
+    } catch {
+      return '';
+    }
+  };
+  /** "Show all products" (`data-lbx-all`), the dropdown's one tab stop, while it is open. */
+  const allLink = () => (open ? (box.querySelector('[data-lbx-all]') as HTMLElement | null) : null);
+  /** Inside our dropdown (its shadow root too). */
+  const inOverlay = (el: Element | null) => !!el && !!host && (host.contains(el) || !!host.shadowRoot?.contains(el));
+  /** Focus back on the input from our dropdown, without it counting as the visitor's focus. */
+  const backToInput = () => {
+    const i = input;
+    if (!i?.isConnected) return;
+    quietFocus = true;
+    try {
+      i.focus();
+    } finally {
+      quietFocus = false;
+    }
+  };
+
+  // --- Requests and renders: one batch per query.
+  // A query fires the requests for every type in parallel, waits for all of
+  // them, then renders once: everything in the dropdown comes from one batch,
+  // one query. The first characters (up to instantChars) fire on the
+  // keystroke; longer phrases once typing pauses for debounceMs, but a steady
+  // typist still gets a batch every maxWaitMs (the box neither freezes during
+  // a long burst nor redraws on every key). At most MAX_BATCHES batches are in
+  // flight: a query that finds no slot waits, and when one frees only the
+  // latest waiting query fires (those typed in between are skipped). Nothing
+  // is aborted while typing.
+  const INSTANT_CHARS = ac.instantChars ?? 3;
+  const DEBOUNCE = ac.debounceMs ?? 300;
+  const MAX_WAIT = ac.maxWaitMs ?? 800;
+  const MAX_BATCHES = 2;
+  const CACHE_MAX = 300;
+  /** One phrase, however it is spaced: "red  s " asks what "red s" asked. */
+  const norm = (s: string) => s.trim().replace(/\s+/g, ' ');
+
+  // Answers per (type, filters as sent, phrase) for the page's life, least
+  // recently used out first: a query whose types are all here resolves at once
+  // (backspace, retype, reopen). A failed request is not kept (asked again).
+  // The filters are in the key because an integration may make them follow
+  // the page (a getter on the URL's shop section): after an in-app navigation
+  // the same phrase is another question (otherwise the previous section's
+  // suggestions would come from the cache).
+  const cache = new Map<string, Result[]>();
+  const pending = new Map<string, Promise<Result[]>>();
+  type Type = AutocompleteConfigType['types'][number];
+  const keyOf = (slot: string, filters: Type['filters'], q: string) => `${slot}\n${JSON.stringify(filters) ?? ''}\n${q}`;
+  const cached = (k: string) => {
+    const v = cache.get(k);
+    if (v) cache.delete(k), cache.set(k, v);
+    return v;
+  };
+  const allCached = (q: string) => ac.types.every((x) => cached(keyOf(x.type, x.filters, q)));
+
+  let nav = new AbortController();
+  /** One type's answer for a phrase; `slot` keys the cache (the fallback's products apart from the typed ones). */
+  const answer = (x: Type, q: string, slot = x.type): Promise<Result[]> => {
+    // Read once: what is sent is what keys it.
+    const filters = x.filters;
+    const k = keyOf(slot, filters, q);
+    const hit = cached(k);
+    if (hit) return Promise.resolve(hit);
+    const known = pending.get(k);
+    if (known) return known;
+    const signal = nav.signal;
+    const p = ctx.api
+      .search({ endpoint: 'search', surface: ac.surface, type: x.type, query: q, size: x.size, fields: x.fields, filters }, signal)
+      .then(
+        (page) => {
+          const rs = page.hits.map(ctx.result).filter(navigable);
+          cache.set(k, rs);
+          if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value!);
+          return rs;
+        },
+        (e) => {
+          if (!signal.aborted) reportError(`autocomplete ${x.type}`, e);
+          throw e;
+        },
+      )
+      .finally(() => pending.delete(k));
+    pending.set(k, p);
+    return p;
+  };
+
+  /**
+   * "No results" fallback products (`emptyState.fallback`: a fixed product
+   * search), part of the batch that found nothing. Asked once per page (the
+   * cache); none on a failure.
+   */
+  const fallbackFor = (): Promise<Result[]> => {
+    const fb = empty.fallback;
+    if (!fb?.query) return Promise.resolve([]);
+    const product = ac.types.find((x) => x.type === PRODUCT);
+    return answer({ type: PRODUCT, size: fb.size ?? 4, fields: product?.fields }, norm(fb.query), '\nfallback').catch(() => []);
+  };
+  /** The "No results" layout's options: phrases to try, links to browse, fallback products. */
+  const emptyOptions = (fallback: Result[]) => {
+    const tag = (r: Result, kind: string) => Object.assign(r, { __empty: kind });
+    return [
+      ...(empty.tryQueries ?? []).filter((q) => typeof q === 'string' && q.trim()).map((q) => tag(ctx.result({ '@id': `try/${q}`, '@type': 'query', '@title': q }), 'try')),
+      ...(empty.browse ?? []).filter((b) => b && safeUrl(b.url)).map((b) => tag(ctx.result({ '@id': `browse/${b.url}`, '@type': 'browse', '@title': b.title, url: b.url }), 'browse')),
+      ...fallback.map((r) => tag({ ...r }, 'fallback')),
+    ];
+  };
+
+  // Pictures belong to the batch, so a row's title and picture change
+  // together. Bounded: a slow picture does not hold the batch past PICTURE_WAIT.
+  const images = new Map<string, HTMLImageElement>();
+  const pictures = (rs: Result[]) => {
+    const loading: Promise<unknown>[] = [];
+    for (const r of rs) {
+      const src = typeof r.c.image === 'string' ? r.c.image : '';
+      if (!src) continue;
+      let img = images.get(src);
+      if (!img) {
+        img = new Image();
+        img.decoding = 'async';
+        img.src = src;
+        images.set(src, img);
+        if (images.size > PRELOAD_MAX) images.delete(images.keys().next().value!);
+      }
+      if (!img.complete) loading.push(img.decode().catch(() => {}));
+    }
+    return loading.length ? Promise.race([Promise.all(loading), new Promise((r) => setTimeout(r, PICTURE_WAIT))]) : null;
+  };
+
+  let issued = 0; // batches, in the order they were issued
+  let onScreen = 0; // the batch the dropdown shows
+  let inFlight = 0; // batches waiting for the network
+  const flying = new Set<string>();
+  let queued = ''; // the latest query waiting for a slot
+  let timer = 0;
+  let waiting = 0; // since when a batch is being put off
+
+  const batch = async (q: string) => {
+    const id = ++issued;
+    const signal = nav.signal;
+    const network = !allCached(q);
+    if (network) inFlight++, flying.add(q), mark(`ac ask ${q}`);
+    const settled = await Promise.allSettled(ac.types.map((x) => answer(x, q)));
+    // Every type answered nothing: the "No results" layout's fallback products belong to this batch.
+    const none = !light && settled.every((s) => s.status === 'fulfilled' && !s.value.length);
+    const fallback = none ? await fallbackFor() : [];
+    // Its answers are here: the query waiting for a slot goes now, not after
+    // this one's pictures and render (up to PICTURE_WAIT later, and its
+    // requests' cost in the task that shows these).
+    if (network) inFlight--, flying.delete(q);
+    if (queued && inFlight < MAX_BATCHES) launch(queued);
+    const wait = pictures([...settled.flatMap((s) => (s.status === 'fulfilled' ? s.value : [])), ...fallback]);
+    if (wait) await wait;
+    if (signal.aborted) return;
+    paint(id, q, settled, fallback);
+  };
+
+  const launch = (q: string) => {
+    if (!q || flying.has(q)) return;
+    if (inFlight >= MAX_BATCHES && !allCached(q)) return void (queued = q);
+    queued = '';
+    void batch(q);
+  };
+
+  const fire = () => {
+    timer = waiting = 0;
+    launch(want);
+  };
+
+  const query = (value: string) => {
+    const q = norm(value);
+    clearTimeout(timer);
+    timer = 0;
+    if (q.length < minChars) {
+      waiting = 0;
+      queued = '';
+      shown.clear();
+      if (!sheet) return close('empty');
+      // The sheet stays (it is where the shopper types), empty below minChars.
+      want = lastQuery = '';
+      results = items = order = [];
+      active = -1;
+      live.clear();
+      said = '';
+      return render();
+    }
+    want = q;
+    // From the cache: at once (backspacing, retyping, reopening).
+    if (allCached(q)) return void ((waiting = 0), launch(q));
+    const now = performance.now();
+    waiting ||= now;
+    const d = q.length <= INSTANT_CHARS ? 0 : Math.min(DEBOUNCE, waiting + MAX_WAIT - now);
+    if (d > 0) timer = window.setTimeout(fire, d);
+    else fire();
+  };
+
+  // A completed batch renders, once, if it was issued after the one on screen
+  // and the input still starts with its query; otherwise it is dropped. A type
+  // that failed keeps what the previous render showed for it; "No results"
+  // only when every type of the batch answered empty.
+  const paint = (id: number, q: string, settled: PromiseSettledResult<Result[]>[], fallback: Result[] = []) => {
+    if (!want || !input || id <= onScreen || !want.startsWith(q)) return;
+    if (settled.every((s) => s.status === 'rejected')) return; // nothing came back: keep what is shown
+    const lists = new Map<string, Result[]>();
+    ORDER.forEach((type, i) => {
+      const s = settled[i];
+      lists.set(type, s.status === 'fulfilled' ? s.value : (shown.get(type) ?? []));
+    });
+    const list = ORDER.flatMap((type) => lists.get(type)!);
+    if (!list.length && settled.some((s) => s.status === 'rejected')) return;
+    // The same rows as on screen, for a phrase the visitor has already typed
+    // past: nothing to redraw. The batch for what the input holds always
+    // renders (its query is the one announced).
+    const same = open && q !== want && list.length === results.length && list.every((r, i) => r.type === results[i].type && r.id === results[i].id);
+    onScreen = id;
+    if (same) return;
+    shown.clear();
+    lists.forEach((rs, type) => shown.set(type, rs));
+    // The keyboard selection follows its item, wherever the new list puts it.
+    const sel = items[active];
+    results = list;
+    items = list.length || light ? list : emptyOptions(fallback);
+    active = sel ? items.findIndex((r) => r.type === sel.type && r.id === sel.id) : -1;
+    lastQuery = q;
+    listOnly = results.length > 0 && !results.some((r) => r.type === PRODUCT);
+    // The sheet takes what arrives while its input has let go (the keyboard put away to read).
+    if (!sheet && focused() !== input) return;
+    // The first opening with an onOpen (the site's own code: one storefront opens its
+    // search strip, 9 ms of jQuery and layout reads at 4x CPU) was one task of
+    // 20 ms with our render: the rows drawn now into the hidden dropdown, shown
+    // (the hook, the placing) in the next frame.
+    const later = !sheet && !open && !!ac.onOpen;
+    if (later) place();
+    else if (!sheet) show();
+    render();
+    // Shown unless closed meanwhile (close() clears want) or focus left: a newer
+    // batch in between does not stop it (Firefox: neither showed, 2026-10-12).
+    if (later) afterFrame(() => !open && !!want && !!input && focused() === input && show());
+    mark(`ac shown ${q}`); // with the ask's: a phrase's wait, in the timeline (docs/INTEGRATION-PERFORMANCE.md)
+    markActive();
+    // Status (WCAG 4.1.3): how many, or none, once the visitor pauses; not per keystroke.
+    const msg = results.length ? t('count', { count: results.length, query: q }) : t('empty', { query: q });
+    if (msg !== said) (said = msg), live.say(msg, 700);
+  };
+
+  /** Hand a query to the host so its own router/form performs navigation. */
+  const submitViaHost = (q: string) => {
+    const i = input!;
+    hook('onSelect', ac.onSelect, null);
+    // Paint our close first; the host's router render then runs in its own task.
+    if (sheet) return leave('select', () => handToHost(i, q));
+    close('select');
+    setTimeout(() => handToHost(i, q), 0);
+  };
+  const submitAll = () => submitViaHost(sheet && mirror ? mirror.value : input!.value);
+  /**
+   * What is typed into the sheet's input, into the site's as well (its value
+   * and an `input` event, as typing there would): the site's form, its own
+   * scripts and our search prefetch (search/speculate.ts) see the phrase as
+   * on a desktop. Ours ignores that event (suppressInput).
+   */
+  const typed = () => {
+    const i = input;
+    if (!i || !mirror || i.value === mirror.value) return;
+    suppressInput = true;
+    try {
+      Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(i, mirror.value);
+      i.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    } finally {
+      suppressInput = false;
+    }
+  };
+  const handToHost = (from: HTMLInputElement, q: string) => {
+    // A host that re-rendered its header meanwhile: its input as it is now.
+    const i = from.isConnected ? from : (document.querySelector(selector) as HTMLInputElement | null) ?? from;
+    suppressInput = true;
+    Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(i, q);
+    // composed: listeners outside a shadow root around the input hear them too.
+    i.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    i.dispatchEvent(new Event('change', { bubbles: true, composed: true })); // lazy bindings (v-model.lazy, updateOn: 'change')
+    suppressInput = false;
+    const opts = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true, composed: true } as KeyboardEventInit;
+    const notCancelled = i.dispatchEvent(new KeyboardEvent('keydown', opts));
+    i.dispatchEvent(new KeyboardEvent('keyup', opts));
+    if (notCancelled && i.form) i.form.requestSubmit();
+  };
+
+  function choose(idx: number) {
+    const r = items[idx];
+    if (!r) return;
+    if (r.type === 'query') submitViaHost(plain(r.c.title));
+    else if (safeUrl(r.c.url)) {
+      const url = safeUrl(r.c.url);
+      hook('onSelect', ac.onSelect, (r as any).__empty ? null : r);
+      leave('select', () => location.assign(url));
+    }
+  }
+
+  /** The arrow keys: the next option in `order`, or back to the input (-1) past either end. */
+  const step = (by: 1 | -1) => {
+    const n = order.length + 1; // positions: -1 (back in input) .. order.length-1
+    const at = order.indexOf(active);
+    const next = ((at + by + 1 + n) % n) - 1;
+    active = next < 0 ? -1 : order[next];
+    byPointer = false;
+    render();
+    // Into view once the frame with it has rendered (layout clean then): in
+    // the key's task, right after our render, it forced a style and layout of
+    // the page (most of typing's forced layout; the key's response waited).
+    const row = markActive();
+    if (row) afterFrame(() => row.isConnected && row.id === `lbx-ac-${active}` && row.scrollIntoView({ block: 'nearest' }));
+  };
+  /** The pointer over an option: the same selection the arrow keys move. A
+   *  touch is not a hover (a tap's pointerenter would leave the row lit). */
+  let byPointer = false;
+  function hover(i: number, e?: PointerEvent) {
+    if (e && e.pointerType === 'touch') return;
+    if (i === active || !open || !order.includes(i)) return;
+    active = i;
+    byPointer = true;
+    render();
+    markActive(false);
+  }
+  /** The pointer leaves the option it selected: the selection goes with it (a
+   *  keyboard selection stays): no card stays lit once the pointer has left
+   *  the panel. */
+  function unhover(i: number, e?: PointerEvent) {
+    if (e && e.pointerType === 'touch') return;
+    if (!byPointer || i !== active || !open) return;
+    active = -1;
+    byPointer = false;
+    render();
+    markActive(false);
+  }
+
+  // Window capture: the earliest point in dispatch, ahead of any host listener
+  // on document/body/the input itself.
+  // The event's real target: an input inside a shadow root (web-component
+  // storefronts) reaches window with its host as event.target.
+  const listener = <K extends keyof WindowEventMap>(fn: (e: WindowEventMap[K], target: EventTarget | null) => void) =>
+    ((e: Event) => fn(e as WindowEventMap[K], e.composedPath?.()[0] ?? e.target)) as EventListener;
+  const on = <K extends keyof WindowEventMap>(type: K, fn: (e: WindowEventMap[K], target: EventTarget | null) => void) => addEventListener(type, listener(fn), true);
+  const matches = (x: EventTarget | null): x is HTMLInputElement => x instanceof HTMLInputElement && x.matches(selector);
+  const focused = () => {
+    let a = document.activeElement;
+    while (a?.shadowRoot?.activeElement) a = a.shadowRoot.activeElement;
+    return a;
+  };
+
+  on('input', (_, target) => {
+    // The phone sheet's own input.
+    if (sheet && mirror && target === mirror) {
+      typed();
+      query(mirror.value);
+      // Drawn again only for the clear button (the next batch's render brings "Show all"'s link up to date).
+      if (!mirror.value !== !drawnValue) render();
+      return;
+    }
+    // Not one being typed into: a value set for the visitor (search/in-place.ts
+    // on back/forward) asks for nothing; a focus later asks for what it holds.
+    if (suppressInput || !matches(target) || target !== focused()) return;
+    input = target;
+    query(input.value);
+  });
+
+  // Focus moving within a shadow root never reaches window: a focusout or
+  // focusin whose relatedTarget is in the same shadow root stops at that root
+  // (past it, target and relatedTarget would both be the host). Tab from a
+  // shadow-root input to a button beside it (a web-component header) left our
+  // dropdown open and the borrowed ARIA on their input. So the shadow roots
+  // around an input we serve (its own, and any enclosing it) get the same
+  // listeners once it is used. An event that reaches both (focus leaving the
+  // shadow root altogether) is handled once.
+  const handled = new WeakSet<Event>();
+  const once = <K extends keyof WindowEventMap>(fn: (e: WindowEventMap[K], target: EventTarget | null) => void) =>
+    listener<K>((e, target) => {
+      if (handled.has(e)) return;
+      handled.add(e);
+      fn(e, target);
+    });
+  const roots = new WeakSet<ShadowRoot>();
+  function watchRoots(i: Element) {
+    for (let r = i.getRootNode(); r instanceof ShadowRoot && !roots.has(r); r = r.host.getRootNode()) {
+      roots.add(r);
+      r.addEventListener('focusin', onFocusIn, true);
+      r.addEventListener('focusout', onFocusOut, true);
+    }
+  }
+
+  /** The visitor is at the site's input: the sheet on a phone, else the dropdown for what it holds. */
+  const engage = (i: HTMLInputElement) => {
+    input = i;
+    if (sheet || (!open && phone())) return openSheet();
+    // The combobox now (its popup created, detached: aria-controls names
+    // it); our dropdown into the page a frame later (prepare): inserting it
+    // restyles the host page, in the task of the click.
+    ensureHost();
+    watchRoots(i);
+    adopt(i);
+    prepare(i);
+    if (input.value.trim().length >= minChars) query(input.value);
+  };
+
+  const onFocusIn = once<'focusin'>((_, target) => {
+    if (!matches(target) || quietFocus) return;
+    engage(target);
+  });
+  addEventListener('focusin', onFocusIn, true);
+
+  // Leaving the page (a navigation, or into the back/forward cache): closed, so a
+  // page the browser restores from memory never comes back with our dropdown open.
+  addEventListener('pagehide', () => close('blur'));
+
+  // The phone sheet prepared ahead (on a touch screen the entry starts us
+  // once the page is idle, src/main.ts): the dropdown in the page, hidden,
+  // the empty sheet drawn once (lit's templates for it prepared). The tap
+  // that opens it then shows, draws and focuses it, nothing more (a production storefront at
+  // 4x CPU: its task 78 ms with these in it).
+  if (phone())
+    idle(() => {
+      if (open || host) return;
+      ensureHost();
+      document.body.append(host!);
+      const was = sheet;
+      sheet = true;
+      try {
+        render();
+      } catch (e) {
+        reportError('autocomplete sheet', e);
+      } finally {
+        sheet = was;
+      }
+      mark('ac sheet prepared');
+    });
+
+  // Also any focusout dispatched by script (an integration's re-dispatch, no
+  // relatedTarget): what counts is where focus is a task later.
+  const onFocusOut = once<'focusout'>((_, target) => {
+    if (target !== input) return;
+    setTimeout(() => {
+      const f = focused();
+      // Into our dropdown ("Show all products" by Tab, the sheet's input): still open.
+      if (f === input || inOverlay(f)) {
+        if (sheet) release(); // the sheet's own input is the combobox now
+        return;
+      }
+      close('blur');
+      release(); // nothing of ours left on their input
+    }, 0);
+  });
+  addEventListener('focusout', onFocusOut, true);
+
+  // A key we act on is consumed as a whole gesture (keydown + keypress + keyup).
+  // Letting half of it through leaves the host in an inconsistent state: a
+  // modal that closes on keydown Escape while the component inside it resets
+  // on keyup Escape.
+  const consumed = new Set<string>();
+  const consume = (e: KeyboardEvent) => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    consumed.add(e.key);
+  };
+
+  on('keydown', (e, target) => {
+    if (!open || !(target === input || (sheet && target === mirror))) return;
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      consume(e); // also keeps the host's hidden suggestion list from moving
+      step(e.key === 'ArrowDown' ? 1 : -1);
+    } else if (e.key === 'Enter') {
+      if (active >= 0) {
+        consume(e); // our selection wins over the host's Enter handler
+        choose(active);
+      } else if (sheet) {
+        // The sheet's own input: its phrase goes to the site's search.
+        consume(e);
+        if (mirror && norm(mirror.value)) submitViaHost(mirror.value);
+      } else close('enter'); // plain Enter: the host performs its own search navigation
+    } else if (e.key === 'Escape') {
+      consume(e); // close us first, not the host modal
+      if (sheet) leave('back');
+      else close('escape');
+    } else if (e.key === 'Tab' && !e.shiftKey && !e.ctrlKey && !e.metaKey && !sheet) {
+      // "Show all products" is the dropdown's tab stop: Tab reaches it (it sits
+      // at the end of <body> or in the top layer, never next to the input in
+      // the page's own order). Alt+Tab too (Safari's Option+Tab).
+      const all = allLink();
+      if (!all) return;
+      consume(e);
+      all.focus();
+    }
+  });
+  const finishGesture = (e: KeyboardEvent) => {
+    if (!consumed.has(e.key)) return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    if (e.type === 'keyup') consumed.delete(e.key);
+  };
+  on('keypress', finishGesture);
+  on('keyup', finishGesture);
+
+  on('pointerdown', (e, target) => {
+    // Click into an already-focused input (no focusin) reopens the dropdown.
+    if (matches(target) && !open && target === focused()) {
+      if (phone()) return engage(target);
+      input = target;
+      if (input.value.trim().length >= minChars) query(input.value);
+      return;
+    }
+    if (!open || target === input || (host && e.composedPath().includes(host))) return;
+    close('outside');
+  });
+
+  // Host SPA navigations (pushState or popstate): never leave a dropdown
+  // hanging over a new route.
+  onUrlChange(() => {
+    clearTimeout(timer);
+    timer = waiting = 0;
+    queued = '';
+    nav.abort(); // answers for the old page's input are not wanted
+    nav = new AbortController();
+    close('navigate');
+  });
+
+  hook('onReady', ac.onReady, { close: () => (sheet ? leave('api') : close('api')), reposition: () => (cancelAnimationFrame(raf), input && (field = fieldOf(input, ac.alignTo)), position()) });
+
+  // The interaction that loaded us has already happened: pick it up.
+  const now = focused();
+  if (matches(now)) engage(now);
+};