@luigisbox/luma 0.0.0-stage → 0.1.0

package/src/core/a11y.ts

@@ -0,0 +1,160 @@
+// Accessibility helpers shared by the widgets (docs/ACCESSIBILITY.md): live
+// regions, attributes borrowed on the host's elements, focus moves and traps,
+// colour contrast, and the high-contrast mode. Widget chunks only: never the
+// entry, never the server renderer.
+
+import { layered, setCss } from './styles';
+
+/** Visually hidden, still read by screen readers (inline: no stylesheet needed). */
+export const SR_ONLY =
+  'position:absolute!important;width:1px!important;height:1px!important;margin:-1px!important;padding:0!important;border:0!important;overflow:hidden!important;clip-path:inset(50%)!important;white-space:nowrap!important;';
+
+/**
+ * A polite status region (WCAG 4.1.3). `say(text)` announces it once the
+ * caller has been quiet for `delay` ms (a burst of renders is one message);
+ * the same text twice is announced twice (it is cleared first).
+ */
+export const liveRegion = () => {
+  const el = document.createElement('div');
+  el.setAttribute('role', 'status');
+  el.setAttribute('aria-live', 'polite');
+  el.setAttribute('aria-atomic', 'true');
+  el.style.cssText = SR_ONLY;
+  let timer = 0;
+  return {
+    el,
+    say(text: string, delay = 150) {
+      clearTimeout(timer);
+      el.textContent = '';
+      // In a later task: a region whose text is replaced in the same task as it appears is not announced.
+      timer = window.setTimeout(() => void (el.textContent = text), delay);
+    },
+    clear() {
+      clearTimeout(timer);
+      el.textContent = '';
+    },
+  };
+};
+
+/**
+ * Attributes we put on an element that is not ours (the host's search input).
+ * `restore()` puts back what was there, except where the host has changed an
+ * attribute since we set it: then the host's value is the current truth and
+ * stays (a framework that manages its own ARIA keeps it).
+ */
+export const borrow = (el: Element) => {
+  const saved = new Map<string, { was: string | null; ours: string | null }>();
+  return {
+    el,
+    set(name: string, value: string | null) {
+      const now = el.getAttribute(name);
+      const s = saved.get(name);
+      if (!s) saved.set(name, { was: now, ours: value });
+      else s.ours = value;
+      if (value == null) now != null && el.removeAttribute(name);
+      else if (now !== value) el.setAttribute(name, value);
+    },
+    restore() {
+      for (const [name, { was, ours }] of saved) {
+        if (el.getAttribute(name) !== ours) continue; // the host's own write since ours
+        if (was == null) el.removeAttribute(name);
+        else el.setAttribute(name, was);
+      }
+      saved.clear();
+    },
+  };
+};
+
+/**
+ * Its palette, as custom properties on the root: every rule of ours reads
+ * them with its normal value as the fallback (`var(--lbx-c-line, #ccc)`), and
+ * so can an integration's CSS. On with the visitor's OS setting
+ * (`prefers-contrast: more`), unless they switched ours off, or with our
+ * toggle (`data-lbx-contrast` on <html>). Forced colours (Windows contrast
+ * themes) are the browser's: our CSS only keeps state visible there (system
+ * colours, outlines). Pure CSS: no script runs for the OS setting.
+ */
+// Written minified, a rule per line (the build joins the lines): every widget's.
+const PALETTE =
+  '--lbx-c:1;--lbx-c-fg:#000;--lbx-c-bg:#fff;--lbx-c-line:#000;--lbx-c-muted:#000;--lbx-c-accent:#000;' +
+  '--lbx-c-sel-fg:#fff;--lbx-c-sel-bg:#000;--lbx-c-ring:3px;--lbx-c-border:2px;--lbx-c-dim:1;--lbx-c-underline:underline';
+const OURS = ':where(lbx-search,lbx-plp,lbx-reco,lbx-reco-pop,[data-lbx="ac-overlay"]) :focus-visible';
+export const CONTRAST_CSS =
+  `\n@media (prefers-contrast:more){:root:not([data-lbx-contrast="off"]){${PALETTE}}}` +
+  `:root[data-lbx-contrast="more"]{${PALETTE}}` +
+  `.lbx-sr-only:not(:focus):not(:focus-within){${SR_ONLY}}` +
+  '.lbx-contrast-toggle{font:inherit;margin:0 0 8px;padding:4px 10px;min-height:24px;border:2px solid currentColor;border-radius:4px;background:Canvas;color:CanvasText;cursor:pointer}' +
+  `@media (prefers-contrast:no-preference){:root:not([data-lbx-contrast="more"]) .lbx-contrast-toggle:not(:focus){${SR_ONLY}}}` +
+  `${OURS}{outline:var(--lbx-c-ring,2px) solid;outline-offset:2px}` +
+  `@media (forced-colors:active){${OURS}{outline:3px solid Highlight!important;outline-offset:2px!important}}` +
+  `@media (prefers-contrast:more){:root:not([data-lbx-contrast="off"]) ${OURS}{outline:3px solid!important;outline-offset:2px!important}}` +
+  `:root[data-lbx-contrast="more"] ${OURS}{outline:3px solid!important;outline-offset:2px!important}\n`;
+
+const KEY = 'lbx:contrast';
+const stored = () => {
+  try {
+    const v = localStorage.getItem(KEY);
+    return v === 'more' || v === 'off' ? v : null;
+  } catch {
+    return null;
+  }
+};
+const more = () => (typeof matchMedia === 'function' ? matchMedia('(prefers-contrast: more)') : null);
+const prefersMore = () => !!more()?.matches;
+
+/** The mode's state: the visitor's toggle, else their OS setting ('more'), else none. */
+const state = () => stored() ?? (prefersMore() ? 'more' : null);
+/** The high-contrast mode is on. */
+export const contrastOn = () => state() === 'more';
+
+/**
+ * On <html>, for integrations' CSS: `data-lbx-contrast="more"` while the mode
+ * is on (the toggle, or the OS setting: one selector for both), `"off"` when
+ * the visitor switched it off against their OS setting.
+ */
+const apply = () => {
+  const v = state();
+  const html = document.documentElement;
+  if (!v) html.removeAttribute('data-lbx-contrast');
+  else if (html.getAttribute('data-lbx-contrast') !== v) html.setAttribute('data-lbx-contrast', v);
+  for (const b of document.querySelectorAll('.lbx-contrast-toggle')) b.setAttribute('aria-pressed', String(v === 'more'));
+};
+let watching = false;
+/** The mode's sheet and state, applied (every widget, at its start), and kept in step with the OS setting. */
+export const useContrast = () => {
+  setCss('lbx:contrast', layered(CONTRAST_CSS));
+  if (!watching) {
+    watching = true;
+    more()?.addEventListener?.('change', apply);
+  }
+  apply();
+};
+
+/** Switch it (our toggle): remembered for this browser; back to "as the OS says" when that matches. */
+export const setContrast = (on: boolean) => {
+  const v = on === prefersMore() ? null : on ? 'more' : 'off';
+  try {
+    if (v) localStorage.setItem(KEY, v);
+    else localStorage.removeItem(KEY);
+  } catch {}
+  apply();
+};
+
+/**
+ * Modelled on the previous-generation Luma's switch (`_global.contrastToggle`): a button that turns the
+ * mode on and off. Visually hidden until focused unless the visitor's OS asks
+ * for a contrast preference or the mode is on (as that one was), so a
+ * keyboard user who reaches it always sees it.
+ */
+export const contrastToggle = (label: string) => {
+  const b = document.createElement('button');
+  b.type = 'button';
+  b.className = 'lbx-contrast-toggle';
+  b.textContent = label;
+  b.setAttribute('aria-pressed', String(contrastOn()));
+  b.addEventListener('click', (e) => {
+    e.stopPropagation();
+    setContrast(!contrastOn());
+  });
+  return b;
+};

package/src/core/boot-state.ts

@@ -0,0 +1,6 @@
+// The page's state when the entry ran, for code that arrives later in a chunk
+// (core/reconciler.ts, in lbx-place): a chunk's own module code runs when the
+// chunk arrives, which may be after `load` even where the entry was not.
+
+/** Booting after `load` (a script the host injected late): the framework has hydrated already. */
+export const lateBoot = typeof document !== 'undefined' && document.readyState === 'complete';

package/src/core/color.ts

@@ -0,0 +1,42 @@
+// Colour contrast (WCAG 1.4.3 / 1.4.11): the autocomplete's house design reads
+// the site's colours with it. Only the autocomplete uses it: in its chunk
+// (build/vite.mjs), not lbx-core, which every widget loads.
+
+/** rgb()/rgba() (as getComputedStyle reports colours) or #rgb/#rrggbb → [r, g, b, a]; null otherwise. */
+export const parseColor = (c: string): [number, number, number, number] | null => {
+  const s = c.trim().toLowerCase();
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(s);
+  if (hex) {
+    const h = hex[1].length === 3 ? [...hex[1]].map((x) => x + x).join('') : hex[1];
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16), 1];
+  }
+  const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/.exec(s);
+  if (!m) return null;
+  const a = m[4] == null ? 1 : m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
+  return [+m[1], +m[2], +m[3], a];
+};
+
+const luminance = ([r, g, b]: number[]) => {
+  const ch = (v: number) => ((v /= 255) <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+};
+
+/** A colour's relative luminance (0 black .. 1 white); null for one we cannot read. */
+export const luminanceOf = (c: string) => {
+  const p = parseColor(c);
+  return p ? luminance(p) : null;
+};
+
+/** WCAG contrast ratio of two colours (a translucent foreground over the background); 1 for one we cannot read. */
+export const contrastRatio = (fg: string, bg: string) => {
+  const f = parseColor(fg);
+  const b = parseColor(bg);
+  if (!f || !b) return 1;
+  const over = f.slice(0, 3).map((x, i) => x * f[3] + b[i] * (1 - f[3]));
+  const [l1, l2] = [luminance(over), luminance(b)].sort((x, y) => y - x);
+  return (l1 + 0.05) / (l2 + 0.05);
+};
+
+/** `color` when it reads on `bg` (at least `min`: 4.5 for text), else `fallback`. */
+export const readable = (color: string, bg: string, fallback: string, min = 4.5) => (contrastRatio(color, bg) >= min ? color : fallback);
+

package/src/core/context.ts

@@ -0,0 +1,108 @@
+// A widget's context (config, translator, templates, helpers) once its chunk
+// has loaded. In the core chunk (core/support.ts re-exports it), not the
+// entry: nothing on a page without a widget needs it. No DOM: the edge render
+// service builds a server-rendered listing's context with it too.
+
+import type { Templates } from './templates';
+import type { LumaConfigType } from '../types';
+import type { WidgetContext } from '../main';
+import { nameOf, slot } from './integration';
+
+type Support = typeof import('./support');
+
+
+export const widgetContext = (
+  s: Support,
+  config: LumaConfigType,
+  w: { id: string; folders: string[]; app: any; scopes: string[] },
+  builtIn: Templates,
+  tpls: readonly (readonly [string, any])[],
+  css: readonly (readonly [string, any])[],
+  dict: any,
+  /** Server-side renders: the storefront origin the API calls are made for. */
+  origin?: string,
+): WidgetContext => {
+  const g = config._global;
+  const locale = g.locale ?? 'en';
+  // Precedence: the widget's built-in templates, then _global/, then its folders in order.
+  const templates: Templates = { ...builtIn };
+  for (const [path, t] of tpls) templates[nameOf(path)] = t;
+  const t = s.translator(dict, locale, [g.translations, ...w.folders.map((f) => (f === '_global' ? undefined : slot(config, f).translations))], w.scopes);
+  // One formatter, made again only if the currency or its format changes (an
+  // _init.ts may set them per page): a new Intl.NumberFormat per call was the
+  // costliest call of a listing's render (a production storefront, 4x CPU: 125 ms of 670 for
+  // a page of tiles, each step of the first render calling it again per tile).
+  let fmt: Intl.NumberFormat | null = null;
+  let fmtFor: [unknown, unknown] = [undefined, undefined];
+  // And each amount once: a render re-renders its tiles, each with its prices.
+  const formatted = new Map<number, string>();
+  // Whether this widget's templates print prices with the helper, from the
+  // last page with it (localStorage; unknown on a first visit).
+  const USED = `lbx:price:${w.id}`;
+  let called = false;
+  const price = (n: unknown) => {
+    if (!called) {
+      called = true;
+      try {
+        localStorage.setItem(USED, '1');
+      } catch {}
+    }
+    const x = s.first(n);
+    if (x == null || x === '') return ''; // Number('') would be 0
+    const v = Number(x);
+    if (!Number.isFinite(v)) return '';
+    if (!fmt || fmtFor[0] !== g.currency || fmtFor[1] !== g.priceFormat) {
+      fmt = new Intl.NumberFormat(locale, { ...(g.currency ? { style: 'currency', currency: g.currency } : {}), ...g.priceFormat });
+      fmtFor = [g.currency, g.priceFormat];
+      formatted.clear();
+    }
+    let out = formatted.get(v);
+    if (out === undefined) {
+      if (formatted.size >= 1000) formatted.clear();
+      formatted.set(v, (out = fmt.format(v)));
+    }
+    return out;
+  };
+  // The page's first Intl.NumberFormat loads the locale's data (~50 ms at 4x
+  // CPU, a production storefront): made while the browser is idle (a widget's first request
+  // is out), not in the render that shows its first results. Not when the
+  // last page with this widget never called the helper: a storefront that formats its
+  // own prices loaded the locale's data in one long idle task for nothing on
+  // every page. Built-in templates that use it may be in the
+  // widget's set unused, so it is what the page did, not what the templates say.
+  if (typeof requestIdleCallback === 'function') {
+    let used: string | null = null;
+    try {
+      used = localStorage.getItem(USED);
+    } catch {}
+    if (used !== '0')
+      requestIdleCallback(() => {
+        const was = called;
+        called = true; // warming is not a use
+        price(0);
+        called = was;
+      });
+    globalThis.addEventListener?.(
+      'pagehide',
+      () => {
+        if (called) return;
+        try {
+          localStorage.setItem(USED, '0');
+        } catch {}
+      },
+      { once: true },
+    );
+  }
+  return {
+    id: w.id,
+    config: w.app,
+    global: g,
+    api: s.getApi(g, origin),
+    t,
+    templates,
+    styles: css.map(([, c]) => c),
+    result: s.resultFactory({ ...g.computedAttributes, ...w.app.computedAttributes }),
+    // Images: a listing's first row is eager; elsewhere (recommenders, the autocomplete) every image is lazy.
+    helpers: { t, price, plain: s.plain, first: s.first, ...s.imageHelpers(g.images, w.id !== 'search' && w.id !== 'plp') },
+  };
+};

package/src/core/early-rules.ts

@@ -0,0 +1,96 @@
+// Rules for the inline early-hold snippet (snippet/early-hold.js).
+//
+// The snippet is generic and identical for every client: inline in <head>, it
+// reads these rules from localStorage and, on a matching URL, adds the route's
+// CSS before first paint (the host's listing hidden, a loading bar), with a
+// timeout; the bundle claims that hold at boot (core/takeover.ts). The
+// bundle writes the rules on every page view (only when they changed), so they
+// always match the build that is running; the first page view in a browser
+// has none (no hold: the async behaviour).
+//
+// The matchers are a conservative copy of the routes (path, required and
+// allowed params, no values): a URL they accept that the bundle does not is
+// dropped at boot. The CSS must only hit elements specific to the page type
+// (on sites where category and product URLs look alike).
+
+import { holdCss } from './hold';
+import { P, TRACKING } from './routes';
+import type { PlpConfigType, SearchConfigType } from '../types';
+
+const EARLY_KEY = 'lbx:early';
+// Short: when the bundle stops running (switched off, blocked), holds end soon after.
+const TTL = 2 * 24 * 3600e3;
+
+export interface EarlyRoute {
+  id: string;
+  /** Pathname regex. */
+  path: string;
+  /** Params that must be present and non-empty. */
+  need?: string[];
+  /** Param-name regex every non-empty param must match. */
+  allow?: string;
+  css: string;
+}
+
+const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// reserveSelector: set by loadConfig (default: the first anchor).
+
+/** Only what the snippet can express: a path regex and a query param (no custom readQuery/active). */
+export const searchRule = (c: SearchConfigType, hostCss: string): EarlyRoute | null =>
+  c.urlMatch && c.queryParam && !c.readQuery && !c.active ? { id: 'search', path: c.urlMatch, need: [c.queryParam], css: holdCss(hostCss, c.reserveSelector!) } : null;
+
+/**
+ * Param names the category route can express (values are checked by the bundle).
+ * An _init.ts `active` cannot be expressed: the rule then matches on urlMatch
+ * alone, so it also holds pages `active` rejects (a production storefront's product pages share
+ * the category URL shape). That is harmless where style-host.css only hits
+ * elements of the category page (nothing is hidden there) and the bundle drops
+ * the unclaimed hold at boot; `earlyHold: false` opts out where it is not.
+ */
+export const plpRule = (c: PlpConfigType, hostCss: string): EarlyRoute | null => {
+  if (c.earlyHold === false) return null;
+  const pm = c.params ?? {};
+  // Their page param too: their page 1 is ours. A later page of theirs is
+  // theirs (plpAccepts), a value the snippet does not check: held until the
+  // bundle boots and drops the hold.
+  const names = [
+    pm.page,
+    pm.sort?.param,
+    ...(pm.flags ?? []).map((f) => f.param),
+    ...(pm.ranges ?? []).flatMap((r) => [r.min, r.max]),
+    ...Object.values(pm.facetParams ?? {}).map((f) => f.param),
+  ].filter((n): n is string => !!n);
+  const allow = `(?:${pm.ignore ?? TRACKING})|^${esc(P)}${names.length ? `|^(?:${[...new Set(names)].map(esc).join('|')})$` : ''}`;
+  return { id: 'plp', path: c.urlMatch, allow, css: holdCss(hostCss, c.reserveSelector!) };
+};
+
+/** Store the rules for the snippet's next hard page load (only when they changed, or to renew them). */
+export const writeEarlyRules = (routes: EarlyRoute[], ms: number) => {
+  try {
+    if (!routes.length) return clearEarlyRules();
+    const rules = { v: 1, ms, routes };
+    const old = JSON.parse(localStorage.getItem(EARLY_KEY) || 'null');
+    // Unchanged and renewed within the last day: nothing to write.
+    if (old && JSON.stringify({ v: old.v, ms: old.ms, routes: old.routes }) === JSON.stringify(rules) && old.exp - Date.now() > TTL - 24 * 3600e3) return;
+    localStorage.setItem(EARLY_KEY, JSON.stringify({ ...rules, exp: Date.now() + TTL }));
+  } catch {}
+};
+
+/** The integration is off: the snippet holds nothing any more. */
+export const clearEarlyRules = () => {
+  try {
+    localStorage.removeItem(EARLY_KEY);
+  } catch {}
+};
+
+/** An early hold the inline snippet started on this page view: what the bundle claims or drops. */
+export interface EarlyHold {
+  t: number;
+  route: string;
+  snippet?: 1;
+  claim(id: string): boolean;
+  drop(): void;
+}
+
+/** The snippet's early hold, if it started one: `window.__lbx.early` (Luma's one global). */
+export const earlyHold = (): EarlyHold | undefined => (window as any).__lbx?.early;

package/src/core/entries.ts

@@ -0,0 +1,25 @@
+// Which pages of this document are ours: small enough for the entry (the
+// takeover needs it on every URL change), shared with core/url.ts.
+
+/** A URL as we compare it: routers re-encode (`|` or `%7C`) and reorder the query; the hash is not ours. */
+export const canon = (href: string) => {
+  const u = new URL(href);
+  const ps = [...u.searchParams].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `${u.origin}${u.pathname}?${new URLSearchParams(ps)}`;
+};
+
+/** Pages of this document whose history entry we created (writeUrl). */
+const own = new Set<string>();
+export const markOwnEntry = (href: string) => void own.add(canon(href));
+/** Did we create this page's history entry (our listing's state, a new query in place)? */
+export const isOwnEntry = (href: string) => own.has(canon(href));
+
+/**
+ * A history entry of ours that only stands for something open (the
+ * autocomplete's phone sheet): Back closes it, and no router of the host's
+ * hears that popstate (the URL is the same). `back` returns true when the
+ * popstate was that entry's (set by the widget that pushed it).
+ */
+let back: (() => boolean) | null = null;
+export const onOwnBack = (f: () => boolean) => void (back = f);
+export const ownBack = () => !!back?.();

package/src/core/fold.ts

@@ -0,0 +1,7 @@
+// Text folding for matching typed text (a facet group's search): case- and
+// accent-insensitive, offsets kept.
+
+/** Letters with a stroke, which NFD keeps whole: Polish ł, Croatian đ, Danish ø (one unit for one). */
+const STROKE: Record<string, string> = { ł: 'l', Ł: 'l', đ: 'd', Đ: 'd', ø: 'o', Ø: 'o', ħ: 'h', Ħ: 'h' };
+/** Lowercase without diacritics, one UTF-16 unit per unit (so offsets stay valid): "Łąka" -> "laka", "Žluťoučký" -> "zlutoucky". */
+export const fold = (s: string) => s.split('').map((c) => STROKE[c] ?? c.normalize('NFD')[0].toLowerCase()[0]).join('');

package/src/core/health.ts

@@ -0,0 +1,26 @@
+// Self-telemetry, exposed on window.__lbx.health (debugging, test harnesses):
+// placement counters, API calls, errors and a timeline of what happened when.
+
+export const health = {
+  reconciles: 0,
+  inserts: {} as Record<string, number>,
+  anchorMisses: {} as Record<string, number>,
+  fights: {} as Record<string, number>,
+  apiCalls: 0,
+  errors: [] as string[],
+  timeline: [] as [number, string][],
+};
+
+export const mark = (what: string) => {
+  if (health.timeline.length < 200) health.timeline.push([Math.round(performance.now()), what]);
+};
+
+export const bump = (bucket: Record<string, number>, key: string) => {
+  bucket[key] = (bucket[key] || 0) + 1;
+};
+
+export const reportError = (where: string, e: unknown) => {
+  if (health.errors.length < 50) health.errors.push(`${where}: ${e instanceof Error ? e.message : String(e)}`);
+  // Never throw into the host page.
+  console.warn('[lbx]', where, e);
+};

package/src/core/hold.ts

@@ -0,0 +1,74 @@
+// Hold-state helpers: remembered heights and the loading bar.
+
+import { session } from './storage';
+
+// Remembered heights: a per-viewer convenience only (storage may be unavailable).
+const recall = (k: string) => Number(session.get(k)) || 0;
+const remember = (k: string, h: number) => h > 0 && session.set(k, Math.round(h));
+
+const heightKey = () => `lbx:h:${location.pathname}${location.search}`;
+export const recallHeight = () => recall(heightKey());
+/** The height ours had last time on this URL, reserved on `sel` (the browser restores scroll on reload/back before our results exist). */
+export const reserveCss = (sel: string) => {
+  const h = recallHeight();
+  return h ? `\n${sel} { min-height: ${h}px !important; }` : '';
+};
+export const rememberHeight = (h: number) => remember(heightKey(), h);
+
+/**
+ * `f(height)` of `el` once the browser has laid it out anyway: a ResizeObserver
+ * reports after the frame's own layout, where reading offsetHeight right after
+ * a render would force style and layout of the whole page (tens of ms on a
+ * large host DOM). Once: the first report (its size then, 0 while hidden).
+ */
+export const afterLayout = (el: Element, f: (h: number) => void) => {
+  const ro = new ResizeObserver((es) => {
+    ro.disconnect();
+    f(es[0]?.borderBoxSize?.[0]?.blockSize ?? es[0]?.contentRect.height ?? 0);
+  });
+  ro.observe(el);
+};
+
+/**
+ * The host CSS (`style-host.css`) as a hold applies it: what it hides with
+ * `display: none` is hidden with `visibility: hidden` instead, so it keeps
+ * its box and the page keeps its height until ours renders (then the CSS as
+ * written applies, in the same frame ours shows). Regression (two shops,
+ * 2026-10-02): the early hold collapsed the page (their listing gone, the
+ * footer up), then ours pushed it down: CLS 0.48 and 0.52. The cost: their
+ * lazy images in view may load meanwhile; nothing of theirs is seen,
+ * reachable or hit-testable (unless their own CSS makes a descendant
+ * `visibility: visible`).
+ */
+export const holding = (hostCss: string) => hostCss.replace(/display\s*:\s*none\s*(?:!\s*important)?/gi, 'visibility: hidden !important');
+
+// Written minified, a rule per line (the build joins the lines): in the entry, every page.
+export const LOADING = (sel: string) =>
+  `\n${sel}::before{content:"";display:block;height:3px;margin-bottom:-3px;opacity:.4;` +
+  'background:linear-gradient(90deg,transparent,currentColor,transparent) no-repeat;' +
+  'background-size:40% 100%;animation:lbx-loading 1.1s linear infinite}' +
+  '@keyframes lbx-loading{from{background-position:-60% 0}to{background-position:160% 0}}' +
+  `@media (prefers-reduced-motion:reduce){${sel}::before{animation:none;background-size:100% 100%}}`;
+
+/** First paint already happened? (Paint Timing; readyState where unsupported.) */
+export const painted = () =>
+  PerformanceObserver.supportedEntryTypes?.includes('paint')
+    ? performance.getEntriesByType('paint').some((e) => e.name === 'first-contentful-paint')
+    : document.readyState !== 'loading';
+
+/**
+ * Visits in a row that failed (timed out, errored) before a listing route
+ * stops holding: theirs shows at once. Counted per session, so a multi-page
+ * site stops too, not only an SPA.
+ */
+export const MAX_FAILURES = 2;
+export const failKey = (id: string) => `lbx:fail:${id}`;
+export const failures = (id: string) => recall(failKey(id));
+
+/** The hold's CSS of a listing route: their listing kept in place but hidden, a loading bar on the reserve. */
+export const holdCss = (hostCss: string, reserveSelector: string) => `${holding(hostCss)}\n${LOADING(reserveSelector)}`;
+
+/** Height a widget measured last time at this viewport width (per session). */
+const widgetKey = (id: string) => `lbx:rh:${id}:${Math.round(innerWidth / 100)}`;
+export const recallWidgetHeight = (id: string) => recall(widgetKey(id));
+export const rememberWidgetHeight = (id: string, h: number) => remember(widgetKey(id), h);

package/src/core/i18n.ts

@@ -0,0 +1,66 @@
+// Translations: JSON dictionaries per locale (src/locales/<locale>.json, loaded
+// on demand, only the site's locale), overridden by the integration's
+// `_translations.ts` files: `_global` for every widget, a widget folder's own
+// for that widget. Keys are dotted paths, placeholders `{name}`.
+//
+// Plural forms: a key whose value is an object of `Intl.PluralRules`
+// categories (`zero`, `one`, `two`, `few`, `many`, `other`; `other` required)
+// picks the form for the `count` param in the dictionary's locale:
+//   "results": { "one": "{count} produkt", "few": "{count} produkty", "many": "{count} produktów", "other": "{count} produktu" }
+// t('results', { count: 83 }) -> "83 produkty" in pl, t('results', { count: 85 }) -> "85 produktów".
+// Without a numeric `count`, `other`. An override replaces a plural (or a
+// string) as a whole, never one form of it.
+
+import type { Dictionary, Translations } from '../types';
+
+export { loadDictionary } from './locales';
+
+const CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+/** A plural: an object of plural categories with `other`, every form a string. */
+export const isPlural = (v: unknown): v is Record<string, string> =>
+  !!v && typeof v === 'object' && typeof (v as Dictionary).other === 'string' && Object.entries(v).every(([k, s]) => CATEGORIES.has(k) && typeof s === 'string');
+
+const merge = (a: Dictionary, b?: Dictionary): Dictionary => {
+  if (!b) return a;
+  const out: Dictionary = { ...a };
+  for (const [k, v] of Object.entries(b)) out[k] = typeof v === 'object' && typeof a[k] === 'object' && !isPlural(v) && !isPlural(a[k]) ? merge(a[k] as Dictionary, v) : v;
+  return out;
+};
+
+export type T = (key: string, params?: Record<string, unknown>) => string;
+
+const rules = new Map<string, Intl.PluralRules>();
+const pluralOf = (locale: string) => {
+  let r = rules.get(locale);
+  if (!r) {
+    try {
+      r = new Intl.PluralRules(locale);
+    } catch {
+      r = new Intl.PluralRules('en'); // a locale tag Intl does not know
+    }
+    rules.set(locale, r);
+  }
+  return r;
+};
+
+/**
+ * A translate function. `scopes` are tried in order as key prefixes, then the
+ * bare key: with ['plp', 'search'], t('sort') reads plp.sort, then search.sort.
+ */
+export const translator = (base: Dictionary, locale: string, overrides: (Translations | undefined)[], scopes: string[] = []): T => {
+  const dict = overrides.reduce<Dictionary>((d, o) => merge(d, o?.[locale]), base);
+  const get = (path: string, params?: Record<string, unknown>) => {
+    let v: unknown = dict;
+    for (const k of path.split('.')) v = v && typeof v === 'object' ? (v as Dictionary)[k] : undefined;
+    if (typeof v === 'string') return v;
+    if (!isPlural(v)) return undefined;
+    const n = Number(params?.count);
+    return (params?.count != null && Number.isFinite(n) && v[pluralOf(locale).select(n)]) || v.other;
+  };
+  return (key, params) => {
+    let s: string | undefined;
+    for (const p of scopes) if ((s = get(`${p}.${key}`, params)) !== undefined) break;
+    s ??= get(key, params) ?? key;
+    return params ? s.replace(/\{(\w+)\}/g, (m, k) => (params[k] != null ? String(params[k]) : m)) : s;
+  };
+};