@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/core/images.ts

@@ -0,0 +1,170 @@
+// Product images in templates, right by default. DOM-free: the server renderer builds the same
+// attributes, so a server-rendered tile hydrates as it was rendered.
+//
+// From `_global.images` (JSON, `_config.ts`), per image:
+// - `srcset` from a URL pattern of the site's image CDN (named sizes, or a
+//   resizer's width parameter), `sizes` from the config;
+// - the first row (its columns at the viewport's width, from `firstRow`) eager
+//   with fetchpriority=high, the rest lazy; decoding=async always;
+// - width/height always (the box's aspect ratio before the image arrives);
+// - a placeholder style for the image's box: a dominant colour or a tiny image
+//   when the catalog has one, else the neutral skeleton (style-search.css).
+// The page side (load marks, preloads, warming) is ./image-load.ts, the
+// template helpers (`img()`, lit) ./image-tags.ts: this file has no lit, so a
+// chunk that only warms images (search/speculate.ts) stays small.
+
+import type { ImagesConfig, Result } from '../types';
+import { first, safeUrl } from './result';
+
+/** What a template binds on an `<img>` (or its `<source>`), and on the image's box (`ph`). */
+export interface ImageInfo {
+  src: string;
+  /** '' when the URL does not match `images.srcset`. */
+  srcset: string;
+  sizes: string;
+  width: number;
+  height: number;
+  loading: 'eager' | 'lazy';
+  /** 'high' for the first row, else undefined (no attribute). */
+  fetchpriority: 'high' | undefined;
+  decoding: 'async';
+  /** In the first row: eager, high priority, preloaded, never faded in. */
+  eager: boolean;
+  /** Style for the box carrying `data-lbx-ph`: the catalog's placeholder (`--lbx-ph`), '' for the neutral one. */
+  ph: string;
+}
+
+export interface ImageOptions {
+  /** The image URL (default `r.c.image`). */
+  src?: string;
+  /** Overrides `images.sizes` (a smaller tile: a recommender). */
+  sizes?: string;
+  /** Force eager (true) or lazy (false); default: the first row is eager. */
+  eager?: boolean;
+  alt?: string;
+  class?: string;
+  title?: string;
+}
+
+const DEFAULT_ROW: Record<string, number> = { 0: 2, 768: 3, 1200: 4 };
+const res = new Map<string, RegExp | null>();
+const regex = (s: string) => {
+  if (!res.has(s))
+    try {
+      res.set(s, new RegExp(s));
+    } catch {
+      res.set(s, null);
+    }
+  return res.get(s)!;
+};
+
+/** The first-row breakpoints, ascending: [min-width px, columns]. */
+const rows = (cfg: ImagesConfig = {}): [number, number][] => {
+  const r = cfg.firstRow ?? DEFAULT_ROW;
+  return typeof r === 'number' ? [[0, r]] : Object.entries(r).map(([w, n]) => [Number(w) || 0, Number(n) || 0] as [number, number]).sort((a, b) => a[0] - b[0]);
+};
+
+/**
+ * A media query's live list, made once per query: img() asks for every image
+ * of every render, and a matchMedia() call per image and breakpoint was
+ * tens of ms of a listing's render on a slow phone (a production storefront, 4x CPU).
+ * `matches` stays current as the viewport changes.
+ */
+const lists = new Map<string, MediaQueryList>();
+export const media = (query: string) => {
+  let l = lists.get(query);
+  if (!l) lists.set(query, (l = matchMedia(query)));
+  return l.matches;
+};
+
+/**
+ * How many images of a listing are its first row: the columns at the
+ * viewport's width (matchMedia: no layout read), the widest row on a server
+ * (it cannot know the width; one extra eager image costs little).
+ */
+export const firstRowCount = (cfg: ImagesConfig = {}) => {
+  const bp = rows(cfg);
+  if (typeof matchMedia !== 'function') return Math.max(0, ...bp.map(([, n]) => n));
+  let n = bp[0]?.[1] ?? 0;
+  for (const [w, c] of bp) if (!w || media(`(min-width: ${w}px)`)) n = c;
+  return n;
+};
+
+/** For a preload made where the width is unknown (the server): the media query in which image `i` is in the first row, '' = always, null = never. */
+export const firstRowMedia = (cfg: ImagesConfig = {}, i: number): string | null => {
+  const at = rows(cfg).filter(([, n]) => n > i);
+  if (!at.length) return null;
+  // Columns grow with the width: from the narrowest breakpoint that has this column on.
+  const w = at[0][0];
+  return w ? `(min-width: ${w}px)` : '';
+};
+
+/** The srcset of `src` by `images.srcset` ('' when it does not match). */
+export const srcsetOf = (cfg: ImagesConfig = {}, src: string) => {
+  const s = cfg.srcset;
+  if (!s || !src) return '';
+  const re = regex(s.match ?? '^(.*)$');
+  if (!re || !re.test(src)) return '';
+  const out: string[] = [];
+  const add = (replacement: string, descriptor: string) => {
+    const u = safeUrl(src.replace(re, replacement.replace(/\{w\}/g, descriptor.replace(/\D/g, ''))));
+    // A URL with a space or comma would break the list: such a candidate is left out.
+    if (u && !/[\s,]/.test(u)) out.push(`${u} ${descriptor}`);
+  };
+  if (s.candidates) for (const [d, rep] of Object.entries(s.candidates)) /^\d+(?:\.\d+)?[wx]$/.test(d) && add(rep, d);
+  if (s.pattern && s.widths) for (const w of s.widths) Number.isFinite(w) && w > 0 && add(s.pattern, `${Math.round(w)}w`);
+  return out.join(', ');
+};
+
+const COLOR = /^(#[0-9a-f]{3,8}|(?:rgb|hsl)a?\([\d\s.,%/+-]+\))$/i;
+/** The box's style for the catalog's placeholder: a colour (strictly a colour), or a tiny image (a web URL, quoted). */
+export const placeholderOf = (cfg: ImagesConfig = {}, r: Result) => {
+  const p = cfg.placeholder;
+  if (!p) return '';
+  const val = (f?: string) => (f ? String(first(r.c[f] ?? r.a[f]) ?? '').trim() : '');
+  const color = val(p.color);
+  const img = safeUrl(val(p.image));
+  const parts: string[] = [];
+  if (img && !/["\\\n\r]/.test(img)) parts.push(`url("${img}") center / cover no-repeat`);
+  if (COLOR.test(color)) parts.push(color);
+  return parts.length ? `--lbx-ph:${parts.join(', ')}` : '';
+};
+
+/** Every attribute of result `r`'s image at position `i`; `lazy`: no eager first row (not a listing). */
+export const imageOf = (cfg: ImagesConfig = {}, r: Result, i: number, o: ImageOptions = {}, lazy = false): ImageInfo => {
+  const src = String(o.src ?? r.c.image ?? '');
+  const eager = o.eager ?? (!lazy && i < firstRowCount(cfg));
+  const srcset = srcsetOf(cfg, src);
+  return {
+    src,
+    srcset,
+    sizes: srcset ? (o.sizes ?? cfg.sizes ?? '') : '',
+    width: cfg.width ?? 400,
+    height: cfg.height ?? cfg.width ?? 400,
+    loading: eager ? 'eager' : 'lazy',
+    fetchpriority: eager ? 'high' : undefined,
+    decoding: 'async',
+    eager,
+    ph: placeholderOf(cfg, r),
+  };
+};
+
+/** The first row's images of a listing (what the server and the bundle preload). */
+export const firstRowImages = (cfg: ImagesConfig = {}, results: Result[], all = false) => {
+  const n = all ? Math.max(0, ...rows(cfg).map(([, c]) => c)) : firstRowCount(cfg);
+  return results.slice(0, n).map((r, i) => ({ ...imageOf(cfg, r, i, { eager: true }), i })).filter((im) => im.src);
+};
+
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+/** `<link rel=preload as=image>` markup for a server-rendered listing: every image of the widest first row, each for the widths it is in the first row at. */
+export const preloadMarkup = (cfg: ImagesConfig = {}, results: Result[]) => {
+  if (cfg.preload === false) return '';
+  return firstRowImages(cfg, results, true)
+    .map((im) => {
+      const media = firstRowMedia(cfg, im.i);
+      if (media == null) return '';
+      const set = im.srcset ? ` imagesrcset="${esc(im.srcset)}"${im.sizes ? ` imagesizes="${esc(im.sizes)}"` : ''}` : '';
+      return `<link rel="preload" as="image" href="${esc(im.src)}"${set}${media ? ` media="${esc(media)}"` : ''} fetchpriority="high" data-lbx="preload">`;
+    })
+    .join('');
+};

package/src/core/integration.ts

@@ -0,0 +1,126 @@
+// Turning an integration's files into a config (a widget's context from it:
+// ./context.ts, in the core chunk). No DOM:
+// the bundle (main.ts) and the edge render service (Luigi's Box's server-side rendering)
+// both use it, so a server-rendered listing sees exactly the config,
+// templates, translations and helpers the bundle would.
+
+import type { LumaApi, LumaConfigType, LumaInitType } from '../types';
+
+export type Lazy<T> = Record<string, () => Promise<T>>;
+
+export const folderOf = (path: string) => path.split('/').slice(-2)[0];
+export const nameOf = (path: string) => path.split('/').pop()!.replace(/^(template|style)-/, '').replace(/\.\w+$/, '');
+const KINDS = ['autocomplete', 'search', 'plp', 'recommender'];
+
+/**
+ * Each listing's folders (template and style precedence) and translation
+ * scopes. The bundle and the server renderer both read it: if they differed,
+ * a server-rendered listing would not hydrate.
+ */
+export const LISTINGS = {
+  search: { folders: ['_global', 'search'], scopes: ['search'] },
+  plp: { folders: ['_global', 'search', 'plp'], scopes: ['plp', 'search'] },
+} as const;
+
+/** What an integration hands to Luma: its folders' files, as Vite globs. */
+export interface IntegrationFiles {
+  configs: Record<string, any>;
+  inits: Record<string, any>;
+  /**
+   * `_translations.ts`, eager (needed by no boot code: on every page) or lazy
+   * (`import.meta.glob(…)` without `eager`: loaded with the widget of their
+   * folder, in its chunk). Lazy ones are not in the config `_init.ts` sees.
+   */
+  translations: Record<string, any> | Lazy<any>;
+  /** style-host.css, eager: needed in the same task as a route change. */
+  hostStyles: Record<string, string>;
+  templates: Lazy<any>;
+  styles: Lazy<any>;
+  /**
+   * `_widget.ts`, lazy (`import.meta.glob('./*\/_widget.ts', { import: 'default' })`):
+   * hooks only a widget calls, run when it loads (loadWidgetInits). Optional;
+   * lazy always (an eager one would be in the entry, where `_init.ts` is).
+   */
+  widgetInits?: Lazy<any>;
+  /**
+   * `_analytics.ts`, lazy (`import.meta.glob('./*\/_analytics.ts', { import: 'default' })`):
+   * the analytics setup (chains of `@/analytics`), run by the analytics chunk
+   * (it is in it) once the page has loaded.
+   */
+  analytics?: Lazy<any>;
+}
+
+/** A folder's style-host.css; a category page without its own uses the search page's. */
+export const hostStyle = (files: Pick<IntegrationFiles, 'hostStyles'>, folder: string): string => {
+  const css = Object.entries(files.hostStyles).find(([p]) => folderOf(p) === folder)?.[1] ?? '';
+  return css || (folder === 'plp' ? hostStyle(files, 'search') : '');
+};
+
+/** `_config.ts` is JSON by contract (checked at boot; code belongs in `_init.ts`). */
+const parseConfigJson = (value: any, file: string) => {
+  const check = (v: any, key: string): void => {
+    if (typeof v === 'function') console.error(`[lbx] ${file}: "${key}" is a function; _config.ts is parsed as JSON, set functions in _init.ts`);
+    else if (v && typeof v === 'object') for (const [k, x] of Object.entries(v)) check(x, k);
+  };
+  check(value, '');
+  return JSON.parse(JSON.stringify(value ?? {}));
+};
+
+/** Folder -> slot in the config: `recommender home` -> recommenders.home. */
+export const slot = (config: any, folder: string) => {
+  const [type, ...rest] = folder.split(' ');
+  if (type !== 'recommender') return (config[type] ??= {});
+  const name = rest.join(' ');
+  if (!name) throw new Error(`[lbx] "${folder}": a recommender folder needs a name, e.g. "recommender home"`);
+  return ((config.recommenders ??= {})[name] ??= {});
+};
+
+// Not `surface`: a category page is a collection surface, search a search surface.
+const LISTING = ['anchor', 'position', 'settleMs', 'reserveSelector', 'holdTimeoutMs', 'size', 'facets', 'facetSize', 'emptyValues', 'sorts', 'fields', 'baseFilters', 'rootClass', 'restoreOnBack', 'prefetchNextPage', 'facetsApply', 'facetGroups'] as const;
+
+/** Configs + translations + inits -> the config; null when the integration is off. */
+export const loadConfig = async (files: Pick<IntegrationFiles, 'configs' | 'inits' | 'translations'>, version: string) => {
+  const config = { _global: {} } as LumaConfigType;
+  let globalInit: LumaInitType | undefined;
+  for (const [p, v] of Object.entries(files.configs)) Object.assign(slot(config, folderOf(p)), parseConfigJson(v, p));
+  for (const [p, v] of Object.entries(files.translations)) if (typeof v !== 'function') slot(config, folderOf(p)).translations = parseConfigJson(v, p);
+  for (const [p, v] of Object.entries(files.inits)) {
+    if (folderOf(p) === '_global') globalInit = v;
+    else slot(config, folderOf(p)).initialize = v;
+  }
+  const Luma: LumaApi = { version, config };
+  if (globalInit && (await globalInit(config, Luma)) === false) return null;
+  if (config._global.disabled || !config._global.publishableKey || !config._global.channelId) return null;
+  const apps = [config.autocomplete, config.search, config.plp, ...Object.values(config.recommenders ?? {})];
+  for (const app of apps) if (app && !app.disabled && app.initialize && (await (app.initialize as any)(app, Luma)) === false) app.disabled = true;
+  // Anything a category page does not set is the search page's.
+  const { search, plp } = config;
+  if (plp) for (const k of LISTING) if (plp[k] == null && search?.[k] != null) (plp as any)[k] = search[k];
+  for (const l of [search, plp]) if (l && l.reserveSelector == null && l.anchor) l.reserveSelector = [l.anchor].flat()[0];
+  return config;
+};
+
+/** A widget's lazy `_translations.ts` (see IntegrationFiles), into their folders' slots before its context is built. */
+export const loadTranslations = (config: LumaConfigType, files: Pick<IntegrationFiles, 'translations'>, folders: readonly string[]) =>
+  Promise.all(
+    Object.entries(files.translations)
+      .filter(([p, v]) => typeof v === 'function' && folders.includes(folderOf(p)))
+      .map(async ([p, f]) => {
+        slot(config, folderOf(p)).translations = parseConfigJson(await f(), p);
+      }),
+  );
+
+/** A widget's files from a glob, in folder order; from _global/, files named after another widget stay out. */
+export const widgetFiles = <X>(kind: string, folders: string[], glob: Lazy<X>) => {
+  const uses = kind === 'plp' ? ['search', 'plp'] : [kind];
+  const mine = (p: string) => {
+    const prefix = nameOf(p).split('-')[0];
+    return folders.includes(folderOf(p)) && !p.endsWith('/style-host.css') && (folderOf(p) !== '_global' || !KINDS.includes(prefix) || uses.includes(prefix));
+  };
+  return Promise.all(
+    Object.entries(glob)
+      .filter(([p]) => mine(p))
+      .sort(([a], [b]) => folders.indexOf(folderOf(a)) - folders.indexOf(folderOf(b)))
+      .map(async ([p, f]) => [p, await f()] as const),
+  );
+};

package/src/core/kept.ts

@@ -0,0 +1,25 @@
+// The site's dataLayer pushes of a page left before analytics ran on it (a
+// purchase on a thank-you page closed at once): kept for the next page's
+// analytics, which replays them as of this page and time (src/analytics/datalayer.ts).
+// In the entry: it runs on `pagehide`, when no chunk can load any more.
+
+import { session } from './storage';
+
+export const KEPT = 'lbx:dl';
+
+/** Keeps the pushes of the dataLayer `name` from index `from` on (the last 30, of the last 5 pages); the index kept up to. */
+export const keepDl = (name: string, from: number) => {
+  const dl = (window as any)[name];
+  if (!(dl?.length > from)) return from;
+  // Each on its own: one that does not serialize (a GTM click's element, cyclic) is left out, not the rest.
+  // gtag's `arguments` become `{ 0: 'event', 1: … }` (readDl reads them); functions (GTM's callbacks) are dropped.
+  const e = dl.slice(from - dl.length).slice(-30).flatMap((x: unknown) => {
+    try {
+      return [JSON.parse(JSON.stringify(x))];
+    } catch {
+      return [];
+    }
+  });
+  session.set(KEPT, [...(session.get<unknown[]>(KEPT) ?? []), { u: location.href, t: Date.now(), e }].slice(-5));
+  return dl.length;
+};

package/src/core/listings.ts

@@ -0,0 +1,100 @@
+// The listings' boot: search results and category pages. In lbx-nav, not in
+// the entry: the entry (main.ts) decides from the URL alone (the routes'
+// accepts) and loads this with the listing's own chunks, on a page of a
+// listing route, so a page that is not one never downloads it. Until it is
+// here the entry holds their listing (the early hold claimed, or its own hold
+// CSS); each route's takeover continues that hold.
+
+import type { SearchConfigType, PlpConfigType, GlobalConfigType } from '../types';
+import { hasPrefetch, productsChannel, putPrefetch } from './prefetch';
+import type { Rule } from './reconciler';
+import { searchReadQuery } from './routes';
+import { onFlush } from './scheduler';
+import { onUrlChange } from './sense';
+import { hasStash } from './stash';
+import { whenApplied } from './styles';
+import { takeover, type Takeover } from './takeover';
+import { startTurbo } from './turbo';
+
+export interface ListingRoute {
+  kind: 'search' | 'plp';
+  cfg: SearchConfigType | PlpConfigType;
+  accepts: (u: URL) => boolean;
+  hostCss: string;
+}
+
+export interface ListingDeps {
+  g: GlobalConfigType;
+  /** The widget's chunks (main.ts load(): cached, so the entry's early call is the same load). */
+  load: (kind: 'search' | 'plp') => Promise<{ mod: any; ctx: any }>;
+  /** main.ts run(): a widget call whose errors are reported, never thrown. */
+  run: (where: string, p: Promise<{ mod: any; ctx: any }>, f: (m: { mod: any; ctx: any }) => unknown, onFail?: () => void) => unknown;
+  /** Routes the entry already holds the current visit of. */
+  held: Set<string>;
+  /**
+   * The reconciler's (lbx-place), handed in: the entry loads it in parallel
+   * with this chunk, which typing loads too (search while typing) and which
+   * must not pull placement code into a page without a listing.
+   */
+  addRule: (r: Rule) => unknown;
+}
+
+const toArray = <X>(v: X | X[] | undefined): X[] => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+const listing = ({ kind, cfg, accepts, hostCss }: ListingRoute, { g, load, run, held, addRule }: ListingDeps) => {
+  const tag = `lbx-${kind}`;
+  const tk: Takeover = takeover({
+    id: kind,
+    tag,
+    accepts,
+    hostCss,
+    reserveSelector: cfg.reserveSelector!,
+    holdTimeoutMs: cfg.holdTimeoutMs ?? 4000,
+    // Another category, another query: a new visit (hold, or hand back anew).
+    visitKey: kind === 'plp' ? (u) => u.pathname : searchReadQuery(cfg as SearchConfigType),
+    held: held.has(kind),
+  });
+  // The element is placed by the reconciler; its class arrives with the
+  // widget's chunk and upgrades it in place (custom elements are upgraded when
+  // defined). Where their server fell back to their own listing, the page is theirs.
+  const active = (u: URL) => accepts(u) && tk.ssr !== 'fellback';
+  addRule({ id: kind, active, anchors: toArray(cfg.anchor), position: cfg.position!, settleMs: cfg.settleMs, create: () => document.createElement(tag) });
+  // Search: the request starts here, in parallel with the widget's chunks
+  // (the entry asked for them with this one). Once our element is on the page
+  // it fetches URL changes itself (show more continues from a cursor): a
+  // prefetch then would be a second, full request. The slot is taken before
+  // the listing starts, so it waits for this request rather than asking twice.
+  // A failure (the chunk, the request) is the listing's, as a failed request is.
+  const prefetch = (url: URL) => {
+    // A result stashed for this load (typed on the previous page, or left for Back): the listing renders that.
+    if (kind !== 'search' || !active(url) || tk.ssr || hasPrefetch(url.href) || document.querySelector(tag) || hasStash(url.href)) return;
+    const { products, onProducts } = productsChannel();
+    putPrefetch(url.href, import('../widgets/search/first').then((m) => m.searchFirst(g, cfg as SearchConfigType, url, onProducts)), { products });
+  };
+  let started = false;
+  const ensure = (url: URL) => {
+    prefetch(url);
+    if (started || !active(url)) return;
+    started = true;
+    // Loading adds modulepreload links to <head>: not while it is being parsed.
+    whenApplied(() =>
+      run(kind, load(kind), ({ mod, ctx }) => mod.start(ctx, tk), () => {
+        started = false; // the next URL change into the route tries again
+        tk.release(true);
+      }),
+    );
+  };
+  ensure(new URL(location.href));
+  onUrlChange(ensure);
+  // A hook that reads the page (`active()` on their data layer) may accept it
+  // only later, without a URL change: looked at again on every reconcile until started.
+  onFlush(() => !started && ensure(new URL(location.href)));
+  return { tk, accepts: active };
+};
+
+/** Each route's takeover, placement rule and loading; Turbo Drive's history around ours (core/turbo.ts). */
+export const startListings = (routes: ListingRoute[], deps: ListingDeps, setUp: <X>(where: string, f: () => X) => X | null) => {
+  const listings = routes.map((r) => setUp(r.kind, () => listing(r, deps))).filter((l): l is NonNullable<typeof l> => !!l);
+  if (listings.length) setUp('turbo', () => startTurbo(listings));
+  return listings;
+};

package/src/core/locales.ts

@@ -0,0 +1,14 @@
+// Luma's dictionaries (src/locales/<locale>.json), each its own chunk, only
+// the site's locale ever loaded. In the entry (a few bytes: the glob's map),
+// so a widget's load asks for its dictionary in parallel with its chunks
+// rather than after lbx-core arrived. No DOM: the server renderer uses it too.
+
+import type { Dictionary } from '../types';
+
+const locales = import.meta.glob<Dictionary>('../locales/*.json', { import: 'default' });
+
+const cache = new Map<string, Promise<Dictionary>>();
+export const loadDictionary = (locale: string) => {
+  if (!cache.has(locale)) cache.set(locale, (locales[`../locales/${locale}.json`] ?? locales['../locales/en.json'])());
+  return cache.get(locale)!;
+};

package/src/core/own.ts

@@ -0,0 +1,49 @@
+// Everything we insert into the page is marked, so sensing can ignore our own
+// mutations and the reconciler can find its nodes.
+
+export const OWN_ATTR = 'data-lbx';
+
+/**
+ * Whether a node of ours the host removes is put back before the next paint
+ * (core/sense.ts, scheduleNow): from when we have something to put back, a
+ * sheet of ours (core/styles.ts) or the reconciler's elements. Until then a
+ * removal is not searched for ours: on a busy page (a carousel) that was a
+ * querySelector per removed node, every frame, where Luma had placed nothing.
+ */
+let removals = false;
+export const watchOwnRemovals = () => void (removals = true);
+export const ownRemovalsWatched = () => removals;
+
+/**
+ * The modal container around a host element (a dialog, a focus-trapped
+ * drawer, an open popover), across shadow roots. What we show for it goes
+ * inside: outside a modal we would be inert, and a press on us would count as
+ * outside it and close it.
+ */
+export const modalOf = (el: Element): Element | null => {
+  for (let n: Element | null = el; n; n = ((n.getRootNode() as ShadowRoot).host as Element | undefined) ?? null) {
+    const d = n.closest('dialog, [role=dialog], [aria-modal=true], [popover]:popover-open');
+    if (d) return d;
+  }
+  return null;
+};
+
+/** React hydrating the whole document (Next.js app router, Remix, React Router 7 / Hydrogen). */
+export const wholeDocument = () => {
+  const w = window as any;
+  return !!(w.__next_f || w.__remixContext || w.__reactRouterContext);
+};
+/**
+ * A page that may yet be hydrated as a whole: known whole-document React, or a
+ * Next.js page still parsing (its flag comes at the end of <body>, its assets
+ * show before). Anywhere else, nothing of ours has to wait for a framework.
+ */
+export const documentMayHydrate = () => wholeDocument() || (document.readyState === 'loading' && !!document.querySelector('script[src*="/_next/"]'));
+
+/** React has hydrated this element (claimed it: a fiber, or React 16's instance). */
+export const hasFiber = (n: object) => Object.keys(n).some((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactInternalInstance$'));
+
+export const isOwnNode = (n: Node | null): boolean => {
+  const el = n && (n.nodeType === 1 ? (n as Element) : n.parentElement);
+  return !!el?.closest(`[${OWN_ATTR}]`);
+};

package/src/core/page.ts

@@ -0,0 +1,14 @@
+// Which page a URL shows. Tiny and DOM-free, so the entry can key prefetched
+// and stashed results by page without pulling in core/url.ts (router writes),
+// which only the listing chunk needs. canon lives in core/entries.ts.
+
+import { canon } from './entries';
+import { withoutTracking } from './routes';
+
+export { canon };
+
+/**
+ * The page a URL shows, for matching server-rendered state to it: canonical and
+ * without tracking params (an include leaves those out, the browser's URL has them).
+ */
+export const pageKey = (href: string) => canon(withoutTracking(href).href);

package/src/core/prefetch.ts

@@ -0,0 +1,88 @@
+// Listing results requested before the listing asks for them, keyed by the
+// page they are for (pageKey: canonical, without tracking params), consumed once:
+// - the entry's request on a search page (the listing's chunk is still loading);
+// - a query the shopper is typing (widgets/search/speculate.ts): Enter on the
+//   search page renders it without a request;
+// - the next page, as the shopper nears the end of the loaded tiles ("show more").
+// Speculative ones expire (`ttlMs`): results a shopper did not ask for go stale.
+//
+// How long a listing's requests take on this page (`observe`, `typicalMs`):
+// the listing does not wait for a speculation forever (widgets/listing/element.ts).
+import type { ListingResult } from '../widgets/listing/query';
+import { pageKey } from './page';
+
+export interface Prefetch {
+  p: Promise<ListingResult | null>;
+  /** performance.now() when it was asked. */
+  at: number;
+  /** Answered (a result or null). */
+  done: boolean;
+  /** Speculative (a phrase typed, not a page asked for): the listing may ask anew when it is overdue. */
+  spec: boolean;
+  /** Stops it (a speculation whose result is no longer needed). */
+  abort?: () => void;
+  /** The products alone, before their facets (listingQuery's `onProducts`): the listing may show them first. */
+  products?: Promise<ListingResult>;
+}
+
+const pending = new Map<string, Prefetch & { until: number }>();
+
+/** Durations (ms) of the listing requests that answered on this page, the latest few. */
+const took: number[] = [];
+export const observe = (ms: number) => {
+  took.push(ms);
+  if (took.length > 9) took.shift();
+};
+/** A listing request's usual duration here (the median of the latest), or `fallback` before any answered. */
+export const typicalMs = (fallback = 1000) => {
+  if (!took.length) return fallback;
+  const s = [...took].sort((a, b) => a - b);
+  return s[s.length >> 1];
+};
+
+/** null: the URL has no query (the listing hands the page back), or a speculation that failed (the listing asks itself). */
+export const putPrefetch = (href: string, p: Promise<ListingResult | null>, { ttl = Infinity, spec = false, timed = true, abort, products }: { ttl?: number; spec?: boolean; timed?: boolean; abort?: () => void; products?: Promise<ListingResult> } = {}) => {
+  const at = performance.now();
+  const e = { p, at, done: false, spec, abort, products, until: at + ttl };
+  p.then(
+    // A whole listing's requests (not a next page's one) tell how long a fresh one takes.
+    (r) => ((e.done = true), r && timed && observe(performance.now() - at)),
+    () => void (e.done = true), // the listing reports errors when it consumes it
+  );
+  pending.set(pageKey(href), e);
+  // Speculative entries nobody consumed: a handful at most.
+  if (pending.size > 8) pending.delete(pending.keys().next().value!);
+};
+
+const live = (k: string) => {
+  const e = pending.get(k);
+  if (e && e.until < performance.now()) pending.delete(k);
+  return e && e.until >= performance.now() ? e : undefined;
+};
+
+export const takePrefetch = (href: string): Prefetch | undefined => {
+  const k = pageKey(href);
+  const e = live(k);
+  pending.delete(k);
+  return e;
+};
+
+export const hasPrefetch = (href: string) => !!live(pageKey(href));
+
+/** The pending result without consuming it (the listing preloads its first images when it arrives). */
+export const peekPrefetch = (href: string) => live(pageKey(href))?.p;
+/** Its products alone, when it was asked with `products` (before its facets). */
+export const peekProducts = (href: string) => live(pageKey(href))?.products;
+
+/** Drop one (an aborted speculation, or one superseded by newer phrases): the listing must not wait for it. */
+export const dropPrefetch = (href: string, p: Promise<unknown>) => {
+  const k = pageKey(href);
+  if (pending.get(k)?.p === p) pending.delete(k);
+};
+
+/** A promise for listingQuery's `onProducts` and the callback that settles it (a prefetch's `products`). */
+export const productsChannel = () => {
+  let got!: (r: ListingResult) => void;
+  const products = new Promise<ListingResult>((ok) => (got = ok));
+  return { products, onProducts: (r: ListingResult) => got(r) };
+};