@luigisbox/luma 0.0.0-stage → 0.2.0

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;
+  };
+};

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;
+  },
+});
+