@luigisbox/luma 0.0.0-stage → 0.1.0

package/src/core/image-load.ts

@@ -0,0 +1,102 @@
+// The page side of product images (./images.ts builds the attributes):
+// - load marks: `data-lbx-loaded` on an `img[data-lbx-img]` and its
+//   `[data-lbx-ph]` box once it has loaded (or failed: the alt text shows), so
+//   the placeholder goes and a lazy image fades in (style-search.css). One
+//   capture listener on the document for every widget; an image already
+//   complete when a render puts it in (the memory cache, a persisted tile, a
+//   server-rendered one loaded before hydration) is marked in that task:
+//   no placeholder flash, no fade;
+// - preloads of a listing's first row (<link rel=preload as=image>), as soon
+//   as the bundle has the result;
+// - warming the first images of results fetched ahead (typing, a hovered
+//   filter), at low priority, behind a cap.
+// Browser only, in the widgets' chunks: never in the entry or the server renderer.
+
+import type { ImageInfo } from './images';
+
+const SEL = 'img[data-lbx-img]:not([data-lbx-loaded])';
+/** A load this soon after the render that put the image in came from a cache: shown at once, not faded. */
+const CACHED_MS = 50;
+let renderedAt = -Infinity;
+
+const loaded = (img: Element, how: '' | 'fade') => {
+  img.setAttribute('data-lbx-loaded', how);
+  img.closest('[data-lbx-ph]')?.setAttribute('data-lbx-loaded', how);
+};
+
+let watching = false;
+const watch = () => {
+  if (watching) return;
+  watching = true;
+  const on = (e: Event) => {
+    const t = e.target as Element;
+    if (t?.nodeType !== 1 || t.localName !== 'img' || !t.hasAttribute('data-lbx-img') || t.hasAttribute('data-lbx-loaded')) return;
+    loaded(t, performance.now() - renderedAt < CACHED_MS ? '' : 'fade');
+  };
+  // load and error do not bubble: capture sees every image of the document.
+  document.addEventListener('load', on, true);
+  document.addEventListener('error', on, true);
+};
+
+/**
+ * After a render into `root`: images that are already there are marked
+ * (complete: no layout read), then the root opts into fading (`data-lbx-fade`)
+ * when `fade` is on. Server-rendered markup without JavaScript has no fade.
+ */
+export const settleImages = (root: Element, fade = true) => {
+  watch();
+  renderedAt = performance.now();
+  for (const img of root.querySelectorAll<HTMLImageElement>(SEL)) if (img.complete && img.getAttribute('src')) loaded(img, '');
+  if (fade && !root.hasAttribute('data-lbx-fade')) root.setAttribute('data-lbx-fade', '');
+};
+
+const preloaded = new Set<string>();
+/** <link rel=preload as=image> for these images (their srcset and sizes, so the candidate the <img> picks is the one fetched), at high priority. */
+export const preloadImages = (list: ImageInfo[]) => {
+  try {
+    for (const im of list) {
+      const key = im.srcset || im.src;
+      if (!im.src || preloaded.has(key)) continue;
+      preloaded.add(key);
+      const l = document.createElement('link');
+      l.rel = 'preload';
+      l.setAttribute('as', 'image');
+      l.href = im.src;
+      if (im.srcset) {
+        l.setAttribute('imagesrcset', im.srcset);
+        if (im.sizes) l.setAttribute('imagesizes', im.sizes);
+      }
+      l.setAttribute('fetchpriority', 'high');
+      l.setAttribute('data-lbx', 'preload');
+      document.head.append(l);
+    }
+    // Bounded: the oldest of ours go (a long session of filters and queries).
+    const ours = document.head.querySelectorAll('link[data-lbx="preload"]');
+    for (let k = 0; k < ours.length - 24; k++) ours[k].remove();
+  } catch {}
+};
+
+const warmed = new Set<string>();
+/**
+ * The first `cap` images of results fetched ahead, at low priority (the
+ * shopper may never ask for them): an image element that is never attached
+ * picks its candidate from srcset and sizes as the tile will, so the request
+ * is the tile's.
+ */
+export const warmImages = (list: ImageInfo[], cap: number) => {
+  try {
+    for (const im of list.slice(0, Math.max(0, cap))) {
+      const key = im.srcset || im.src;
+      if (!im.src || warmed.has(key)) continue;
+      warmed.add(key);
+      const img = new Image();
+      img.setAttribute('fetchpriority', 'low');
+      img.decoding = 'async';
+      if (im.srcset) {
+        img.sizes = im.sizes;
+        img.srcset = im.srcset;
+      }
+      img.src = im.src;
+    }
+  } catch {}
+};

package/src/core/image-tags.ts

@@ -0,0 +1,26 @@
+// The image template helpers every scope gets (`image()`, `img()`), from
+// `_global.images` (./images.ts builds the attributes). Shared by the bundle
+// and the server renderer: no DOM.
+
+import { html, nothing } from 'lit-html';
+import { imageOf, type ImageInfo, type ImageOptions } from './images';
+import type { ImagesConfig, Result } from '../types';
+
+/**
+ * A complete `<img>` (data-lbx-img: load marks, the fade-in). The placeholder
+ * goes on its box: put `data-lbx-ph` and `style=${image(r, i).ph}` on the
+ * element around it (the `img` helper does).
+ */
+export const imgOf = (im: ImageInfo, o: ImageOptions = {}) =>
+  html`<img data-lbx-img src=${im.src} srcset=${im.srcset || nothing} sizes=${im.sizes || nothing} width=${im.width} height=${im.height} alt=${o.alt ?? ''} class=${o.class ?? nothing} title=${o.title ?? nothing} loading=${im.loading} fetchpriority=${im.fetchpriority ?? nothing} decoding="async" />`;
+
+/** The template helpers: `image(r, i, opts)` (the attributes) and `img(r, i, opts)` (an `<img>` in its placeholder box). */
+export const imageHelpers = (cfg: ImagesConfig = {}, lazy = false) => ({
+  image: (r: Result, i: number, o?: ImageOptions) => imageOf(cfg, r, i, o, lazy),
+  img: (r: Result, i: number, o?: ImageOptions) => {
+    const im = imageOf(cfg, r, i, o, lazy);
+    // The box's aspect ratio from the configured size: fixed before and after the image arrives (object-fit: contain).
+    return im.src ? html`<span class="lbx-img" data-lbx-part="image" data-lbx-ph style=${`aspect-ratio:${im.width}/${im.height}${im.ph ? `;${im.ph}` : ''}`}>${imgOf(im, o)}</span>` : nothing;
+  },
+});
+

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,120 @@
+// 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>;
+}
+
+/** 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/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);