@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/widgets/plp/route.ts

@@ -0,0 +1,263 @@
+// Category listing: a collection. The host's category URL becomes the page's
+// scope (collection_filters), either from a category record looked up in the
+// catalog by URL (through the listing's own collection surface), or straight
+// from the URL (fromUrl, in _init.ts).
+//
+// URL compatibility, both ways:
+//  - reading: the host's own filter/sort params are mapped to our state
+//    (params in _config.ts). A URL with a param we cannot express is not taken
+//    over: the host renders it natively, so no URL ever loses a filter.
+//  - writing: our UI writes the host's own params where a mapping exists, so
+//    URLs we produce are the host's URLs and keep working without us.
+// No DOM: the edge render service resolves URLs with it too.
+
+import type { Api, Hit } from '../../api';
+import { isPromise } from '../../core/scheduler';
+import { flagId, has, P, paramValues, plpAccepts, TRACKING, withoutTracking } from '../../core/routes';
+import { lru, session } from '../../core/storage';
+import type { CategoryFilter, FacetLayout, GlobalConfigType, PlpConfigType } from '../../types';
+import { reportError } from '../../core/health';
+import { readOwn, type Query, type Route, type UiState } from '../listing/state';
+import { parseRange } from '../listing/query';
+
+/** "Salt & Pepper" -> "salt-and-pepper". */
+export const slugify = (s: string) =>
+  s
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+export const plpRoute = (pc: PlpConfigType, api: Api, g: GlobalConfigType): Route => {
+  const channel = g.channelId;
+  const pm = pc.params ?? {};
+  const sep = pm.separator;
+  const flags = (pm.flags ?? []).map((f) => ({ ...f, id: flagId(f) }));
+  // Our own flags (config.flags) have no host param: always lbx.flag=<id>.
+  const ownFlags = pc.flags ?? [];
+  const facetParams = pm.facetParams ?? {};
+  const mapped = Object.entries(facetParams);
+  const order = new Map(mapped.map(([facet], i) => [facet, i]));
+  const mappedParams = new Set(mapped.map(([, fp]) => fp.param));
+  // Our value -> their value, per facet with a value map.
+  const inverse = Object.fromEntries(Object.entries(facetParams).map(([facet, fp]) => [facet, fp.values ? new Map(Object.entries(fp.values).map(([h, v]) => [v, h])) : null]));
+  const ignore = new RegExp(pm.ignore ?? TRACKING);
+  const values = (url: URL, param: string) => paramValues(url, param, sep);
+
+  /**
+   * A catalog lookup: memo, then the session cache (revisits and back
+   * navigation resolve without a round trip), then the API. The session holds
+   * what the API returned (`raw`), not what we make of it: a new toFilter (a
+   * deploy) applies at once. A failed lookup is retried next time.
+   */
+  const lookup = <R, V>(memo: ReturnType<typeof lru<V | Promise<V>>>, k: string, fetch: () => Promise<R>, make: (raw: R) => V): V | Promise<V> => {
+    const m = memo.get(k);
+    if (m !== undefined) return m;
+    const stored = session.get<R>(k);
+    if (stored !== undefined) {
+      const v = make(stored);
+      memo.set(k, v);
+      return v;
+    }
+    const p = fetch().then((raw) => {
+      const v = make(raw);
+      memo.set(k, v);
+      session.set(k, raw);
+      return v;
+    });
+    memo.set(k, p);
+    p.catch(() => memo.delete(k));
+    return p;
+  };
+
+  // --- category for a URL: from the URL itself, or a catalog record
+  const catMemo = lru<CategoryFilter | Promise<CategoryFilter>>(500);
+  const category = (url: URL): CategoryFilter | Promise<CategoryFilter> => {
+    if (pc.fromUrl) return pc.fromUrl(url);
+    const lk = pc.lookup!;
+    const value = (lk.absolute ? url.origin : '') + (url.pathname.replace(/\/$/, '') || '/');
+    return lookup(
+      catMemo,
+      `lbx:cat2:${channel}:${value}`,
+      () =>
+        api
+          .search({ endpoint: 'collections', surface: pc.surface!, type: lk.type ?? 'category', scope: { [lk.field]: { eq: value } }, size: 1 })
+          .then((r): Hit | null => r.hits[0] ?? null),
+      (hit) => (hit ? pc.toFilter!(hit) : null),
+    );
+  };
+
+  // --- facet slug -> value, per category (only for slug-valued host params):
+  // a slug needs the full list of the category's values
+  const valueMemo = lru<string[] | Promise<string[]>>(500);
+  const facetValues = (cat: NonNullable<CategoryFilter>, facet: string): string[] | Promise<string[]> =>
+    lookup(
+      valueMemo,
+      `lbx:fv:${channel}:${JSON.stringify(cat.scope)}:${facet}`,
+      () =>
+        api
+          .search({ endpoint: 'collections', surface: pc.surface!, type: g.itemType ?? 'product', scope: cat.scope, size: 1 })
+          .then((r) => api.facets(r.guid, [{ field: facet, size: 200 }]))
+          .then((f) => (f[facet]?.values ?? []).map(String)),
+      (vals) => vals,
+    );
+
+  /** Build the query once the category (and any slug lookups) are known; sync when memoised. */
+  const build = (url: URL, cat: CategoryFilter): Query | null | Promise<Query | null> => {
+    if (!cat) return null;
+    const own = readOwn(url);
+    const q: Query = { scope: cat.scope, title: cat.title, ...own };
+    if (pm.sort) {
+      const hv = url.searchParams.get(pm.sort.param);
+      if (hv && has(pm.sort.values, hv)) q.sort = pm.sort.values[hv];
+    }
+    const flagged = url.searchParams.getAll(P + 'flag');
+    q.flags = [...flags.filter((f) => values(url, f.param).includes(f.value) || flagged.includes(f.id)), ...ownFlags.filter((f) => flagged.includes(f.id))].map((f) => f.id);
+    // Their range params (a price range) are a filter of ours, in their format both ways.
+    for (const r of pm.ranges ?? []) {
+      const min = url.searchParams.get(r.min);
+      const max = url.searchParams.get(r.max);
+      if (min || max) q.filters = { ...q.filters, [r.field]: [`${min ?? ''}|${max ?? ''}`] };
+    }
+
+    const pending: Promise<void>[] = [];
+    let unknownSlug = false;
+    const add = (facet: string, vs: string[]) => {
+      q.filters = { ...q.filters, [facet]: [...new Set([...(q.filters[facet] ?? []), ...vs])] };
+    };
+    for (const [facet, fp] of Object.entries(facetParams)) {
+      const mine = url.searchParams.getAll(P + facet);
+      if (mine.length) add(facet, mine);
+      const hv = values(url, fp.param);
+      if (!hv.length) continue;
+      if (fp.values) {
+        // Mapped values; with slug: false the others pass through as they are.
+        // A value mapped to '' (or unknown) is one we cannot express: the page is theirs.
+        const vs = hv.map((v) => (has(fp.values!, v) ? fp.values![v] : fp.slug === false ? v : ''));
+        if (vs.some((v) => !v)) unknownSlug = true;
+        add(facet, vs);
+      } else if (fp.slug === false) add(facet, hv);
+      else {
+        const apply = (vals: string[]) => {
+          const picked = hv.map((s) => vals.find((v) => slugify(v) === s));
+          if (picked.some((v) => v === undefined)) unknownSlug = true;
+          add(facet, picked as string[]);
+        };
+        const vals = facetValues(cat, facet);
+        if (isPromise(vals)) pending.push(vals.then(apply));
+        else apply(vals);
+      }
+    }
+    // A slug the catalog does not know: we cannot reproduce the host's filter.
+    if (!pending.length) return unknownSlug ? null : withFacets(url, q);
+    return Promise.all(pending).then(() => (unknownSlug ? null : withFacets(url, q)));
+  };
+
+  /** The page's own facet list (`facetsFor`, _init.ts): e.g. the category's parameters. */
+  const withFacets = (url: URL, q: Query): Query | Promise<Query> => {
+    if (!pc.facetsFor) return q;
+    const apply = (l: FacetLayout | null | undefined): Query => (l?.facets ? { ...q, facets: l.facets, layout: l.layout } : q);
+    const failed = (e: unknown) => (reportError('plp facetsFor', e), q);
+    try {
+      const l = pc.facetsFor(url, { scope: q.scope, title: q.title, filters: q.filters });
+      return isPromise(l) ? (l as Promise<FacetLayout | null>).then(apply, failed) : apply(l as FacetLayout | null);
+    } catch (e) {
+      return failed(e);
+    }
+  };
+
+  // Keyed without tracking params: every campaign link is the same page.
+  const resolved = lru<Query | null>(500);
+  const keyOf = (url: URL) => withoutTracking(url.href, ignore).href;
+  const resolve = (url: URL): Query | null | Promise<Query | null> => {
+    const key = keyOf(url);
+    const memo = resolved.get(key);
+    if (memo !== undefined) return memo;
+    const cat = category(url);
+    const done = (q: Query | null) => {
+      resolved.set(key, q);
+      return q;
+    };
+    if (isPromise(cat)) return cat.then((c) => build(url, c)).then(done);
+    const q = build(url, cat);
+    return isPromise(q) ? q.then(done) : done(q);
+  };
+
+  type Params = Pick<URLSearchParams, 'delete' | 'append' | 'set'>;
+  /** Write a multi-valued host param in the host's own format. */
+  const put = (sp: Params, param: string, vs: string[]) => {
+    sp.delete(param);
+    if (!vs.length) return;
+    if (sep) sp.set(param, vs.join(sep));
+    else for (const v of vs) sp.append(param, v);
+  };
+
+  const write = (url: URL, next: UiState) => {
+    // On a detached copy of the query, written back once: every change through
+    // url.searchParams serialises the whole query again, and a listing writes
+    // a link for every facet value, each over every mapped host param. Written
+    // back as the URL would have (only if something was changed).
+    const list = new URLSearchParams(url.search);
+    let changed = false;
+    const sp: Params = {
+      delete: (k: string) => void ((changed = true), list.delete(k)),
+      append: (k: string, v: string) => void ((changed = true), list.append(k, v)),
+      set: (k: string, v: string) => void ((changed = true), list.set(k, v)),
+    };
+    for (const k of [...list.keys()]) if (k.startsWith(P)) sp.delete(k); // clearOwn
+    if (pm.page) sp.delete(pm.page); // our UI never opens a page: their page param goes
+    if (pm.sort) sp.delete(pm.sort.param);
+    // Range params (a price range): theirs, written in their format.
+    const rangeFields = new Set((pm.ranges ?? []).map((r) => r.field));
+    for (const r of pm.ranges ?? []) sp.delete(r.min), sp.delete(r.max);
+
+    for (const f of ownFlags) if (next.flags.includes(f.id)) sp.append(P + 'flag', f.id);
+    for (const param of new Set(flags.map((f) => f.param)))
+      put(sp, param, flags.filter((f) => f.param === param && next.flags.includes(f.id)).map((f) => f.value));
+    // Every mapped param is rewritten, in the map's order. A large map (most
+    // params neither on the URL nor selected): those on it go first, then the
+    // selected facets are written; the same as one by one while no two facets
+    // share a param.
+    if (mapped.length) changed = true;
+    const shared = mappedParams.size < mapped.length;
+    if (!shared) for (const k of new Set(list.keys())) if (mappedParams.has(k)) list.delete(k);
+    const picked = shared ? mapped : Object.keys(next.filters).filter((f) => order.has(f) && next.filters[f].length).sort((a, b) => order.get(a)! - order.get(b)!).map((f) => [f, facetParams[f]] as const);
+    for (const [facet, fp] of picked) {
+      const theirs: string[] = [];
+      for (const v of next.filters[facet] ?? []) {
+        const h = inverse[facet]?.get(v) ?? (fp.slug === false ? v : inverse[facet] ? undefined : slugify(v));
+        // A value their param cannot carry (not in the map, a slug of nothing):
+        // ours, rather than dropping the shopper's click.
+        if (h) theirs.push(h);
+        else sp.append(P + facet, v);
+      }
+      put(sp, fp.param, theirs);
+    }
+    for (const r of pm.ranges ?? []) {
+      const { from, to } = parseRange(next.filters[r.field]?.[0]);
+      if (from != null) sp.set(r.min, String(from));
+      if (to != null) sp.set(r.max, String(to));
+    }
+    for (const [facet, vs] of Object.entries(next.filters)) if (!facetParams[facet] && !rangeFields.has(facet)) for (const v of vs) sp.append(P + facet, v);
+    if (next.sort) {
+      const hostValue = pm.sort && Object.entries(pm.sort.values).find(([, api]) => api === next.sort)?.[0];
+      if (hostValue) sp.set(pm.sort!.param, hostValue);
+      else sp.set(P + 'sort', next.sort);
+    }
+    if (changed) url.search = list.toString();
+    return url;
+  };
+
+  return {
+    id: 'plp',
+    tag: 'lbx-plp',
+    endpoint: 'collections',
+    flagDefs: [...flags, ...ownFlags],
+    accepts: plpAccepts(pc),
+    resolve,
+    write,
+    releaseOnEmpty: true,
+  };
+};

package/src/widgets/recommender/index.ts

@@ -0,0 +1,261 @@
+// Recommender widgets. Nothing is requested on page load: the entry places an
+// inline widget as a placeholder and loads this chunk when the placeholder is
+// near the viewport (attach), or when the add-to-cart trigger fires (openPopup).
+//  - Inline: inputs (e.g. the basket's items) are read from the page on every
+//    reconcile; a change (item removed, added) re-fetches.
+//  - Popup: lives on its own terms (top layer, outside the host tree), not the
+//    host notice's: theirs may go away on its own, ours stays until dismissed.
+
+import type { Hit } from '../../api';
+import { useContrast } from '../../core/a11y';
+import { mark, reportError } from '../../core/health';
+import { untilAborted } from '../../api/token';
+import { afterLayout, rememberWidgetHeight } from '../../core/hold';
+import { lru } from '../../core/storage';
+import { byName, view } from '../../core/templates';
+import { onFlush, scheduleIn } from '../../core/scheduler';
+import { onUrlChange } from '../../core/sense';
+import { setCss } from '../../core/styles';
+import { settleImages } from '../../core/support';
+import type { WidgetContext } from '../../main';
+import type { RecommenderConfigType, Result } from '../../types';
+import { watch } from '../../core/tiles';
+
+export { default as css } from './style-recommender.css?raw';
+export const templates = byName(import.meta.glob('./template-*.ts', { eager: true, import: 'default' }));
+
+type Ctx = WidgetContext<RecommenderConfigType>;
+
+// Same inputs -> same answer for the life of the page (back/forward, re-renders).
+const cache = lru<Hit[]>(50);
+/** Requests in flight, by the same key: a prefetch (the popup's, at the click) and its use share one. */
+const flying = new Map<string, Promise<Hit[]>>();
+const fetchHits = (ctx: Ctx, items: string[], signal?: AbortSignal) => {
+  const rc = ctx.config;
+  const type = rc.type ?? ctx.global.itemType ?? 'product';
+  const k = JSON.stringify([rc.surface, type, rc.size, rc.fields, !!rc.excludeItems, items]);
+  const hit = cache.get(k);
+  if (hit) return Promise.resolve(hit);
+  let p = flying.get(k);
+  if (!p) {
+    mark(`reco request ${rc.surface}`);
+    // Not aborted with a caller: another may be waiting on it (a request the
+    // shopper's click started is answered once, whoever asked).
+    p = ctx.api.recommend({ surface: rc.surface, type, anchors: items, exclude: rc.excludeItems ? items : undefined, size: rc.size, fields: rc.fields }).then(
+      (hits) => (flying.delete(k), cache.set(k, hits), hits),
+      (e) => {
+        flying.delete(k);
+        throw e;
+      },
+    );
+    flying.set(k, p);
+  }
+  return signal ? untilAborted(p, signal) : p;
+};
+
+/** Our list, for its tiles' clicks and add-to-carts (core/tiles.ts). */
+const listOf = (ctx: Ctx) => ({ list: `lbx_reco_${ctx.id.slice(5)}`, global: ctx.global });
+
+const applyStyles = (ctx: Ctx) => {
+  ctx.styles.forEach((c, i) => setCss(`itg:${ctx.id}:${i}`, c));
+  useContrast();
+};
+
+// --- inline
+interface State {
+  near: boolean;
+  key: string | null;
+  ctl?: AbortController;
+  v: ReturnType<typeof view>;
+  /** The inputs last requested, its failures in a row, and when the next try may run. */
+  tried: string | null;
+  failures: number;
+  retryAt: number;
+  /** What the tiles show (analytics: a click's result). */
+  results: Result[];
+}
+
+/** Retry a failed widget after 2, 4, 8, 16 s, then only when its inputs change. */
+const MAX_TRIES = 5;
+const attached = new Map<Element, { ctx: Ctx; s: State }>();
+const io = new IntersectionObserver(
+  (entries) => {
+    for (const e of entries) {
+      const a = attached.get(e.target);
+      if (a) a.s.near = e.isIntersecting;
+    }
+  },
+  { rootMargin: '0px 0px 200% 0px' },
+);
+
+const load = (ctx: Ctx, el: HTMLElement, s: State, items: string[], key: string) => {
+  s.key = s.tried = key;
+  s.ctl?.abort();
+  const ctl = (s.ctl = new AbortController());
+  el.dataset.state = 'loading';
+  fetchHits(ctx, items, ctl.signal)
+    .then((hits) => {
+      if (ctl.signal.aborted) return;
+      s.results = hits.map(ctx.result);
+      s.v.render('recommender-box-default', { ...ctx.helpers, results: s.results });
+      settleImages(el, ctx.global.images?.fade !== false);
+      el.style.minHeight = '';
+      el.dataset.state = hits.length ? 'ready' : 'empty';
+      s.failures = 0;
+      if (hits.length) afterLayout(el, (h) => rememberWidgetHeight(ctx.id, h));
+      mark(`reco render ${ctx.id} ${hits.length} hits`);
+    })
+    .catch((e) => {
+      if (ctl.signal.aborted) return;
+      el.dataset.state = 'empty';
+      el.style.minHeight = '';
+      reportError(`reco ${ctx.id}`, e);
+      // Not on every reconcile (any host mutation): a failing API would get a request per frame.
+      if (++s.failures >= MAX_TRIES) return; // key stays: tried again when the inputs change
+      const wait = 1000 * 2 ** s.failures;
+      s.retryAt = performance.now() + wait;
+      s.key = null;
+      scheduleIn(wait + 10);
+    });
+};
+
+/** Called by the entry once the placeholder is near the viewport. */
+export const attach = (ctx: Ctx, el: HTMLElement) => {
+  applyStyles(ctx);
+  const s: State = { near: true, key: null, v: view(el, ctx.templates), tried: null, failures: 0, retryAt: 0, results: [] };
+  attached.set(el, { ctx, s });
+  watch(el, { ...listOf(ctx), results: () => s.results });
+  io.observe(el);
+  sync();
+};
+
+// After each reconcile: (re)load attached widgets near the viewport whose inputs changed.
+const sync = () => {
+  for (const [el, { ctx, s }] of attached) {
+    if (!el.isConnected) {
+      // Removed for good (the rule left the page: a new placeholder next time),
+      // or for a moment by a host re-render (the reconciler puts this same
+      // element back): kept, unless too many have piled up.
+      if (attached.size > 20) {
+        attached.delete(el);
+        io.unobserve(el);
+      }
+      continue;
+    }
+    if (!s.near) continue;
+    let items: string[] = [];
+    try {
+      items = ctx.config.items?.() ?? [];
+    } catch (e) {
+      reportError(`reco ${ctx.id} items`, e);
+      continue;
+    }
+    const key = JSON.stringify(items);
+    if (key === s.key) continue;
+    if (key !== s.tried) s.failures = s.retryAt = 0; // new inputs: no backoff
+    if (performance.now() < s.retryAt) continue;
+    load(ctx, el as HTMLElement, s, items, key);
+  }
+};
+onFlush(sync);
+
+// --- popup
+/**
+ * Where the popup must live to be usable: inside what makes the rest of the
+ * page inert or closes on a press outside it (a modal dialog, a dialog or
+ * drawer around their notice, which may itself be an aria-modal drawer, or
+ * a role=dialog while a modal library has locked the page: a Radix modal
+ * dialog). Not inside a notice that is a plain dialog or toast: it goes away
+ * on its own.
+ */
+const modalAround = (notice?: Element): Element | null => {
+  let open: Element | null = null;
+  try {
+    open = [...document.querySelectorAll('dialog:modal')].pop() ?? null; // the topmost
+  } catch {} // no :modal (older Safari)
+  // A plain [role=dialog] (a toast, a flyout) counts only while a modal library
+  // has disabled the rest of the page (Radix sets no aria-modal).
+  const locked = document.body.style.pointerEvents === 'none';
+  // An auto popover around the notice (a press on ours would light-dismiss it
+  // otherwise); a non-modal <dialog> or plain role=dialog only under a lock
+  // (otherwise it may be a toast that goes away on its own, taking ours along).
+  const around = `:is([popover=""], [popover=auto i]):popover-open, [aria-modal=true]${locked ? ', dialog[open], [role=dialog]' : ''}`;
+  // The notice itself under a lock (a Radix modal is a role=dialog without
+  // aria-modal): outside it, a press on ours is "outside" and closes it.
+  return open ?? notice?.parentElement?.closest(around) ?? notice?.closest(locked ? '[aria-modal=true], [role=dialog]' : '[aria-modal=true]') ?? null;
+};
+let pop: HTMLElement | null = null;
+let popView: ReturnType<typeof view> | null = null;
+let isOpen = false;
+let popCtl: AbortController | null = null;
+let popResults: Result[] = [];
+
+const close = () => {
+  popCtl?.abort();
+  if (!isOpen) return;
+  isOpen = false;
+  try {
+    pop!.hidePopover();
+  } catch {}
+  pop!.style.setProperty('display', 'none', 'important');
+  mark('reco popup close');
+};
+
+/**
+ * Called by the entry on an add-to-cart click (the intent), before the host's
+ * notice confirms it: the request starts now, so the popup opens as soon as
+ * the notice appears rather than a request later. One request per click that
+ * does not end in the cart (a failed add): what the popup costs.
+ */
+export const prefetchPopup = (ctx: Ctx, item: string) => void fetchHits(ctx, [item]).catch(() => {});
+
+/** Called by the entry when "added to cart" was confirmed by the host's notice. */
+export const openPopup = (ctx: Ctx, item: string, near: DOMRect, notice?: Element) => {
+  applyStyles(ctx);
+  popCtl?.abort();
+  const c = (popCtl = new AbortController());
+  fetchHits(ctx, [item], c.signal)
+    .then((hits) => {
+      if (c.signal.aborted || !hits.length) return;
+      if (!pop) {
+        pop = document.createElement('lbx-reco-pop');
+        pop.setAttribute('data-lbx', ctx.id);
+        pop.setAttribute('popover', 'manual');
+        pop.setAttribute('role', 'dialog');
+        pop.style.setProperty('display', 'none', 'important');
+        // A modal library may set pointer-events: none on body, which inherits.
+        pop.style.pointerEvents = 'auto';
+        popView = view(pop, ctx.templates);
+        watch(pop, { ...listOf(ctx), results: () => popResults });
+        // Dismissal: close button, Escape, a press outside, or leaving the page.
+        addEventListener('keydown', (e) => isOpen && e.key === 'Escape' && close(), true);
+        addEventListener('pointerdown', (e) => isOpen && !pop!.contains(e.target as Node) && close(), true);
+        onUrlChange(close);
+      }
+      // Inside what makes the rest of the page inert (a modal dialog, an
+      // aria-modal drawer, which may be their notice itself), or ours could not
+      // be used. Not inside a plain toast: it goes away on its own, ours stays.
+      const parent = modalAround(notice) ?? document.body;
+      if (pop.parentNode !== parent) {
+        parent.append(pop); // moving a popover closes it: shown again below
+        isOpen = false;
+      }
+      pop.setAttribute('aria-label', ctx.t('title'));
+      popResults = hits.map(ctx.result);
+      popView!.render('recommender-popup', { ...ctx.helpers, results: popResults, close });
+      settleImages(pop, ctx.global.images?.fade !== false);
+      pop.querySelector('[data-lbx-list]')?.scrollTo(0, 0);
+      // Just below the host's notice, right-aligned with it.
+      const vw = document.documentElement.clientWidth;
+      const gap = 12;
+      pop.style.top = `${Math.round(Math.max(gap, near.bottom + 8))}px`;
+      pop.style.right = `${Math.round(Math.max(gap, vw - near.right))}px`;
+      pop.style.setProperty('display', 'block', 'important');
+      if (!isOpen) pop.showPopover();
+      isOpen = true;
+      mark(`reco popup open ${hits.length} hits`);
+    })
+    .catch((e) => {
+      if (!c.signal.aborted) reportError('reco popup', e);
+    });
+};

package/src/widgets/recommender/style-recommender.css

@@ -0,0 +1,26 @@
+lbx-reco { display: block; }
+lbx-reco[data-state="empty"] { display: none; }
+.lbx-r__list { display: flex; gap: 16px; overflow-x: auto; scroll-snap-type: x mandatory; }
+.lbx-r__list > * { scroll-snap-align: start; }
+.lbx-r__tile { flex: 0 0 180px; display: flex; flex-direction: column; gap: 6px; color: inherit; text-decoration: var(--lbx-c-underline, none); }
+/* Images (src/core/images.ts): the box keeps its size before the image arrives; its placeholder (the catalog's --lbx-ph, else a neutral skeleton) until it has loaded; lazy images fade in, never the first row, not under reduced motion. */
+.lbx-img { display: block; }
+.lbx-img > img { display: block; width: 100%; height: 100%; object-fit: contain; }
+[data-lbx-ph]:not([data-lbx-loaded]) { background: var(--lbx-ph, var(--lbx-c-ph, #efefef)); }
+@media (prefers-reduced-motion: no-preference) {
+  [data-lbx-fade] img[data-lbx-img][loading="lazy"]:not([data-lbx-loaded]) { opacity: 0; }
+  [data-lbx-fade] img[data-lbx-loaded="fade"] { animation: lbx-img-in .25s ease-out; }
+}
+@keyframes lbx-img-in { from { opacity: 0; } }
+/* dvh (vh before it): iOS Safari's 100vh is its viewport with the toolbars
+   hidden, taller than what shows while they are: the popup's end went under them. */
+lbx-reco-pop {
+  position: fixed; inset: auto; margin: 0; padding: 16px; border: var(--lbx-c-border, 0) solid var(--lbx-c-line, transparent); box-sizing: border-box;
+  width: min(680px, calc(100vw - 24px)); max-height: calc(100vh - 24px); max-height: calc(100dvh - 24px); overflow: auto;
+  background: var(--lbx-c-bg, #fff); color: var(--lbx-c-fg, inherit); border-radius: 8px; box-shadow: 0 12px 40px rgba(0,0,0,.25);
+}
+.lbx-r__head { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-bottom: 8px; }
+.lbx-r__close { font-size: 28px; line-height: 1; min-width: 44px; min-height: 44px; padding: 4px 10px; background: none; border: 0; color: inherit; cursor: pointer; }
+@media (prefers-reduced-motion: reduce) { .lbx-r__list { scroll-behavior: auto; } }
+/* Windows contrast themes drop the shadow: the popup keeps an edge. */
+@media (forced-colors: active) { lbx-reco-pop { border: 2px solid CanvasText; } }

package/src/widgets/recommender/template-recommender-box-default.ts

@@ -0,0 +1,11 @@
+import { html, repeat } from '../../lit';
+import type { RecommenderScope } from '../../types';
+
+export default (s: RecommenderScope) => html`
+  <section class="lbx-r" aria-label=${s.t('title')}>
+    <h2 class="lbx-r__title">${s.t('title')}</h2>
+    <div class="lbx-r__list" data-lbx-list data-lbx-part="list">
+      ${repeat(s.results, (r) => r.c.id, (r, i) => s.include('recommender-result-default', { r, i }))}
+    </div>
+  </section>
+`;

package/src/widgets/recommender/template-recommender-popup.ts

@@ -0,0 +1,12 @@
+import { html, repeat } from '../../lit';
+import type { RecommenderScope } from '../../types';
+
+export default (s: RecommenderScope) => html`
+  <div class="lbx-r__head">
+    <h2>${s.t('title')}</h2>
+    <button type="button" class="lbx-r__close" aria-label=${s.t('close')} @click=${() => s.close?.()}>×</button>
+  </div>
+  <div class="lbx-r__list" data-lbx-list>
+    ${repeat(s.results, (r) => r.c.id, (r, i) => s.include('recommender-result-default', { r, i }))}
+  </div>
+`;

package/src/widgets/recommender/template-recommender-result-default.ts

@@ -0,0 +1,10 @@
+import { html, nothing } from '../../lit';
+import type { RecommenderResultScope } from '../../types';
+
+export default ({ r, i, img, plain, price }: RecommenderResultScope) => html`
+  <a class="lbx-r__tile" data-lbx-part="tile" href=${r.c.url}>
+    ${r.c.image ? img(r, i, { sizes: '180px' }) : nothing}
+    <span class="lbx-r__tile-title" data-lbx-part="title">${plain(r.c.title)}</span>
+    ${r.c.price ? html`<span class="lbx-r__tile-price" data-lbx-part="price">${price(r.c.price)}</span>` : nothing}
+  </a>
+`;

package/src/widgets/search/assets.ts

@@ -0,0 +1,7 @@
+// Built-in listing templates and styles, shared by search and category pages.
+// An integration overrides any of them by name: integration/search/template-search-result-default.ts.
+import { byName } from '../../core/templates';
+import css from './style-search.css?raw';
+
+export const templates = byName(import.meta.glob('./template-*.ts', { eager: true, import: 'default' }));
+export { css };

package/src/widgets/search/first.ts

@@ -0,0 +1,15 @@
+// A search page's first result, asked by `listing()` in src/core/listings.ts
+// (lbx-nav) at boot, in parallel with the listing's chunks. Here rather than in the
+// entry: the query code (route, query building, the answer's shaping) is in
+// lbx-nav, which the listing imports anyway, and not on pages without a listing
+// (the API client's requests are in lbx-core, which the listing loads too).
+import { getApi } from '../../api';
+import type { GlobalConfigType, SearchConfigType } from '../../types';
+import { quickChannel } from '../listing/flow';
+import { listingQuery, type ListingResult } from '../listing/query';
+import { searchRoute } from './route';
+
+export const searchFirst = (g: GlobalConfigType, cfg: SearchConfigType, url: URL, onProducts?: (r: ListingResult) => void) => {
+  const route = searchRoute(cfg);
+  return listingQuery(getApi(g), g, cfg as any, route, route.resolve(url) as any, undefined, undefined, onProducts, quickChannel(route.id));
+};