@luigisbox/luma 0.0.0-stage → 0.2.0

package/src/api/token.ts

@@ -0,0 +1,312 @@
+// The browser token of the Luigi's Box AI discovery client (./ai.ts). Its own
+// chunk (lbx-token): the entry loads it at boot only when sessionStorage has
+// no valid token (./token-key.ts), i.e. on a session's first page; the widgets'
+// requests (lbx-core) import it.
+//
+// Auth: the publishable key is exchanged for a short-lived, origin-bound
+// browser token (GET /browser-challenge -> proof of work -> POST
+// /browser-token). The token is shared by every widget and kept in
+// sessionStorage, so a multi-page site solves the challenge once per session,
+// not once per page. The proof of work runs in a Web Worker (a blob worker;
+// on the main thread if the site's CSP forbids that). Minting starts at boot
+// (warm()), not on the first keystroke.
+//
+// Every discovery call carries X-Lbx-Visitor-Id: Luma's first-party
+// `_lbx_vid` cookie, so requests and analytics events join on one visitor.
+//
+// Also runs in Node (the edge render service): there the
+// storefront origin is sent explicitly and nothing touches the DOM.
+
+import { health } from '../core/health';
+import { session } from '../core/storage';
+import { challengeUrl, storedToken, takeChallenge, tokenKey, type StoredToken } from './token-key';
+import type { GlobalConfigType } from '../types';
+
+export const browser = typeof document !== 'undefined';
+
+// --- visitor id: a first-party cookie
+const VID = '_lbx_vid';
+let vid = '';
+const newId = () =>
+  crypto.randomUUID?.() ?? // secure contexts only
+  [...crypto.getRandomValues(new Uint8Array(16))].map((b) => b.toString(16).padStart(2, '0')).join('');
+export const visitorId = () => {
+  if (vid) return vid;
+  if (!browser) return (vid = 'lbx-ssr'); // server renders are shared, not personal
+  // Only an id we could have written: anything else (a cookie set by a sibling
+  // subdomain) is replaced, and could not even be sent as a header.
+  vid = /^[\w-]{1,64}$/.exec(document.cookie.match(/(?:^|;\s*)_lbx_vid=([^;]+)/)?.[1] ?? '')?.[0] ?? '';
+  if (!vid) {
+    vid = newId();
+    document.cookie = `${VID}=${vid}; Max-Age=${60 * 60 * 24 * 365}; Path=/; SameSite=Lax${location.protocol === 'https:' ? '; Secure' : ''}`;
+  }
+  return vid;
+};
+
+// --- proof of work: the smallest n with SHA-256(nonce + n) starting with `difficulty` zero bits
+// Self-contained (no imports, no closure): its source also becomes the worker.
+// Gives up at `until` (ms epoch): an abandoned solve must not keep a core busy.
+// SHA-256 here, not crypto.subtle: a digest awaited per attempt costs a task
+// each (a typical difficulty takes tens of milliseconds, on a listing's
+// critical path at the first visit). The nonce's whole blocks are hashed once, each attempt hashes
+// only its last one or two: challenge to token request 290 -> 170 ms in
+// Chrome (medians of 10 cold loads, 2026-10-10; Node: 15-20 times faster).
+// `slice` (on the main thread, where no worker runs): it yields every `slice` ms.
+export async function solveHere(nonce: string, difficulty: number, until: number, slice = 0): Promise<number> {
+  // FIPS 180-4's constants, derived as it defines them: the fractional parts
+  // of the first primes' square roots (H) and cube roots (K).
+  const K = new Int32Array(64);
+  const H = new Int32Array(8);
+  for (let p = 2, i = 0; i < 64; p++) {
+    let q = 2;
+    while (q * q <= p && p % q) q++;
+    if (q * q <= p) continue;
+    if (i < 8) H[i] = (Math.sqrt(p) % 1) * 2 ** 32;
+    K[i++] = (Math.cbrt(p) % 1) * 2 ** 32;
+  }
+  const W = new Int32Array(64);
+  const r = (x: number, n: number) => (x >>> n) | (x << (32 - n));
+  const block = (st: Int32Array, m: Uint8Array, o: number) => {
+    for (let i = 0; i < 16; i++) W[i] = (m[o++] << 24) | (m[o++] << 16) | (m[o++] << 8) | m[o++];
+    for (let i = 16; i < 64; i++) {
+      const x = W[i - 15];
+      const y = W[i - 2];
+      W[i] = (r(x, 7) ^ r(x, 18) ^ (x >>> 3)) + W[i - 7] + (r(y, 17) ^ r(y, 19) ^ (y >>> 10)) + W[i - 16];
+    }
+    let [a, b, c, d, e, f, g, h] = st;
+    for (let i = 0; i < 64; i++) {
+      const t = (h + (r(e, 6) ^ r(e, 11) ^ r(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + W[i]) | 0;
+      const u = (r(a, 2) ^ r(a, 13) ^ r(a, 22)) + ((a & b) ^ (a & c) ^ (b & c));
+      h = g;
+      g = f;
+      f = e;
+      e = (d + t) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t + u) | 0;
+    }
+    st.set([st[0] + a, st[1] + b, st[2] + c, st[3] + d, st[4] + e, st[5] + f, st[6] + g, st[7] + h]);
+  };
+  const pre = new TextEncoder().encode(nonce);
+  const whole = pre.length & ~63;
+  const mid = H.slice();
+  for (let o = 0; o < whole; o += 64) block(mid, pre, o);
+  const rest = pre.length - whole;
+  const tail = new Uint8Array(192);
+  tail.set(pre.subarray(whole));
+  const st = new Int32Array(8);
+  let t0 = Date.now();
+  for (let n = 0; ; n++) {
+    if ((n & 1023) === 0 && Date.now() - t0 > (slice || 50)) {
+      if (Date.now() > until) throw new Error('proof of work: no answer in time');
+      if (slice) await new Promise((r) => setTimeout(r));
+      t0 = Date.now();
+    }
+    // nonce + n, padded: 0x80, zeros, its length in bits (big-endian) at the end of a block.
+    const digits = String(n);
+    let len = rest;
+    for (let i = 0; i < digits.length; i++) tail[len++] = digits.charCodeAt(i);
+    const end = (len + 72) & ~63;
+    tail[len] = 0x80;
+    tail.fill(0, len + 1, end - 4);
+    const bits = (pre.length + digits.length) * 8;
+    tail[end - 4] = bits >>> 24;
+    tail[end - 3] = bits >>> 16;
+    tail[end - 2] = bits >>> 8;
+    tail[end - 1] = bits;
+    st.set(mid);
+    for (let o = 0; o < end; o += 64) block(st, tail, o);
+    let zeros = 0;
+    for (let i = 0; i < 8 && zeros === 32 * i; i++) zeros += Math.clz32(st[i]);
+    if (zeros >= difficulty) return n;
+  }
+}
+const POW_TIMEOUT_MS = 20_000;
+const solve = (nonce: string, difficulty: number): Promise<number> => {
+  const until = Date.now() + POW_TIMEOUT_MS;
+  if (!browser || typeof Worker === 'undefined') return solveHere(nonce, difficulty, until, browser ? 8 : 0);
+  return new Promise((resolve, reject) => {
+    let w: Worker | undefined;
+    let timer = 0;
+    const src = `const solve = ${solveHere.toString()};\nonmessage = async (e) => { try { postMessage(await solve(e.data[0], e.data[1], e.data[2])); } catch { postMessage(null); } };`;
+    const url = URL.createObjectURL(new Blob([src], { type: 'text/javascript' }));
+    // Revoked once the worker is done, not right after new Worker(): WebKit
+    // fetches the worker's script later, and a revoked URL fails it
+    // (WebKitBlobResource error 1), so every Safari solved on the main thread.
+    const done = () => (clearTimeout(timer), w?.terminate(), URL.revokeObjectURL(url));
+    const here = () => (done(), solveHere(nonce, difficulty, until, 8).then(resolve, reject));
+    try {
+      w = new Worker(url);
+    } catch {
+      return here(); // CSP worker-src
+    }
+    // A worker that never answers is stopped.
+    timer = window.setTimeout(() => (done(), reject(new Error('proof of work: no answer in time'))), POW_TIMEOUT_MS);
+    w.onmessage = (e) => (done(), e.data == null ? reject(new Error('proof of work failed')) : resolve(e.data));
+    w.onerror = here;
+    w.postMessage([nonce, difficulty, until]);
+  });
+};
+
+type Token = StoredToken;
+
+/** A challenge harder than this is not one we solve (it would spin a core for minutes). */
+const MAX_DIFFICULTY = 24;
+export const TIMEOUT_MS = 8000;
+/** After a failed mint, requests fail at once for this long instead of each starting a new one. */
+const MINT_BACKOFF_MS = 15_000;
+
+/** `signal` plus a deadline: no request may leave a widget, or a server render, waiting forever. */
+const within = (ms: number, signal?: AbortSignal) => {
+  const c = new AbortController();
+  const timer = setTimeout(() => c.abort(new DOMException(`no answer in ${ms} ms`, 'TimeoutError')), ms);
+  (timer as any).unref?.();
+  const stop = () => c.abort(signal!.reason);
+  if (signal?.aborted) stop();
+  else signal?.addEventListener('abort', stop, { once: true });
+  return {
+    signal: c.signal,
+    done: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', stop);
+    },
+  };
+};
+
+/** A promise, or the abort of `signal`, whichever comes first. */
+export const untilAborted = <T>(p: Promise<T>, signal?: AbortSignal) =>
+  !signal
+    ? p
+    : new Promise<T>((resolve, reject) => {
+        if (signal.aborted) return reject(signal.reason);
+        signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        p.then(resolve, reject);
+      });
+
+/** fetch + JSON within a deadline (the body is read under the same deadline). `started`: its fetch, already asked. */
+export const fetchJson = async (url: string, init: RequestInit, ms: number, signal?: AbortSignal, started?: Promise<Response>) => {
+  const d = within(ms, signal);
+  try {
+    const r = await (started ? untilAborted(started, d.signal) : fetch(url, { ...init, signal: d.signal }));
+    const body = await untilAborted(r.text(), d.signal);
+    let json: any = null;
+    try {
+      json = body ? JSON.parse(body) : null;
+    } catch {}
+    return { status: r.status, ok: r.ok, json, body };
+  } finally {
+    d.done();
+  }
+};
+
+/** One channel's token (per key, region and server origin): shared by every request, and by main.ts's warm(). */
+export interface Tokens {
+  get(): Promise<string>;
+  /** The token held now (a request's 401 compares it with the one it sent). */
+  current(): string | undefined;
+  /** Drop it (expired or revoked early): the next get() mints anew. */
+  clear(): void;
+  AUTH: string;
+  API: string;
+  originHeaders: Record<string, string>;
+}
+const all = new Map<string, Tokens>();
+/** `origin`: the storefront origin, for server-side callers (browsers send their own). */
+export const tokensFor = (g: GlobalConfigType, origin?: string): Tokens => {
+  const k = `${g.channelId}|${g.region ?? 'eu1'}|${origin ?? ''}`;
+  let t = all.get(k);
+  if (!t) all.set(k, (t = tokens(g, origin)));
+  return t;
+};
+/** Mint the browser token now, so the first request does not wait for it. */
+export const warmToken = (g: GlobalConfigType) => void tokensFor(g).get().catch(() => {});
+
+const tokens = (g: GlobalConfigType, origin?: string): Tokens => {
+  const region = g.region ?? 'eu1';
+  const AUTH = `https://auth.${region}.luigisbox.ai`;
+  const API = `https://api.${region}.luigisbox.ai`;
+  // Browsers set Origin themselves (and forbid setting it); a server must say which storefront it renders.
+  const originHeaders: Record<string, string> = !browser && origin ? { Origin: origin, Referer: `${origin}/` } : {};
+  const key = tokenKey(g);
+  let token: Token | null = browser ? storedToken(g) : null;
+  let minting: Promise<string> | null = null;
+
+  const mint = async (retries = 1): Promise<Token> => {
+    const url = challengeUrl(g);
+    // The one the entry asked while this chunk loaded (the first try only: a retry needs a new one).
+    const ch = await fetchJson(url, { headers: originHeaders }, TIMEOUT_MS, undefined, browser && retries ? takeChallenge(url) : undefined);
+    if (!ch.ok) throw new Error(`browser-challenge: HTTP ${ch.status}`);
+    const { nonce, difficulty } = ch.json ?? {};
+    if (typeof nonce !== 'string' || !(difficulty >= 0 && difficulty <= MAX_DIFFICULTY)) throw new Error('browser-challenge: unexpected challenge');
+    const solution = await solve(nonce, difficulty);
+    const r = await fetchJson(
+      `${AUTH}/browser-token`,
+      {
+        method: 'POST',
+        headers: { ...originHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          api_key: g.publishableKey,
+          pow_nonce: nonce,
+          pow_solution: solution,
+          channel_id: g.channelId,
+          // One token for discovery and analytics events. Any other audience mints a token without
+          // permissions (docs.luigisbox.ai/authentication/browser-tokens): `/events` did, every event a 403.
+          audience: [`${API}/discovery`, `${API}/analytics`],
+        }),
+      },
+      TIMEOUT_MS,
+    );
+    if (!r.ok) {
+      const detail = r.json?.detail;
+      if (retries > 0 && detail === 'Nonce expired') return mint(retries - 1);
+      throw new Error(`browser-token: HTTP ${r.status} ${typeof detail === 'string' ? detail : ''}`);
+    }
+    const { access_token, expires_in } = r.json ?? {};
+    if (typeof access_token !== 'string' || !(expires_in > 30)) throw new Error('browser-token: unexpected response');
+    return { token: access_token, exp: Date.now() + (expires_in - 30) * 1000 };
+  };
+
+  // Tokens live minutes. A server (the edge render service) renders inside a
+  // tight budget, so it re-mints ahead of expiry instead of on the next
+  // request; a browser mints on demand (an idle tab should not keep solving).
+  let refresh: ReturnType<typeof setTimeout> | undefined;
+  const later = (ms: number) => {
+    clearTimeout(refresh);
+    refresh = setTimeout(() => void renew(true).catch(() => {}), ms);
+    (refresh as any).unref?.();
+  };
+  let failed: { at: number; e: unknown } | null = null;
+  const renew = (background = false): Promise<string> => {
+    if (!background && failed && Date.now() - failed.at < MINT_BACKOFF_MS) return Promise.reject(failed.e);
+    return (minting ??= mint()
+      .then(
+        (t) => {
+          token = t;
+          failed = null;
+          if (browser) session.set(key, t);
+          else later(Math.max(10_000, (t.exp - Date.now()) * 0.8)); // the current token keeps serving until the new one is in
+          return t.token;
+        },
+        (e) => {
+          failed = { at: Date.now(), e };
+          if (!browser) later(MINT_BACKOFF_MS); // a server keeps trying in the background
+          throw e;
+        },
+      )
+      .finally(() => (minting = null)));
+  };
+  const getToken = (): Promise<string> => (token && token.exp > Date.now() ? Promise.resolve(token.token) : renew());
+
+  return {
+    get: getToken,
+    current: () => token?.token,
+    clear: () => {
+      token = null;
+      if (browser) session.set(key, undefined);
+    },
+    AUTH,
+    API,
+    originHeaders,
+  };
+};

package/src/core/a11y-keys.ts

@@ -0,0 +1,60 @@
+// Keyboard helpers of the listing (docs/ACCESSIBILITY.md): focus traps,
+// activation by key, keyboard-or-pointer. Only the listing uses them: in its
+// chunk (build/vite.mjs), not lbx-core, which every widget loads.
+
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), summary, [tabindex]:not([tabindex="-1"]), [contenteditable=""], [contenteditable=true]';
+
+/**
+ * What Tab reaches in `root`, in order. Reads computed visibility: only in
+ * response to the visitor (a key, opening a drawer), never after our renders.
+ */
+export const focusables = (root: Element) =>
+  [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => !el.closest('[inert], [hidden]') && (!el.checkVisibility || el.checkVisibility({ checkVisibilityCSS: true } as any)));
+
+/**
+ * Tab and Shift+Tab cycle inside `root` (a modal drawer): true when the key
+ * was ours. Every step is ours, not only the wrap at the ends: the browser's
+ * own next stop may lie outside `root`. Safari's Tab, by default, skips links,
+ * buttons and checkboxes (Option+Tab reaches them), so from the drawer's close
+ * button it went to the next text field of the page, out of the dialog.
+ */
+export const trapTab = (e: KeyboardEvent, root: Element) => {
+  if (e.key !== 'Tab') return false;
+  e.preventDefault();
+  const all = focusables(root);
+  if (!all.length) return true;
+  const n = all.length;
+  const i = all.indexOf(document.activeElement as HTMLElement);
+  all[i < 0 ? (e.shiftKey ? n - 1 : 0) : (i + (e.shiftKey ? n - 1 : 1)) % n].focus();
+  return true;
+};
+
+/**
+ * Widget roles a template may give an element that is not natively
+ * activatable (a `<div role=button tabindex=0>` copied from a site's markup):
+ * Enter and Space then click it, as they would a button (WCAG 2.1.1). A link
+ * keeps its Enter; only Space is added.
+ */
+const ACTIVATABLE = '[role=button], [role=checkbox], [role=radio], [role=switch], [role=option], [role=menuitem], [role=menuitemradio], [role=menuitemcheckbox], [role=tab]';
+export const activateByKey = (e: KeyboardEvent, within: Element) => {
+  if ((e.key !== 'Enter' && e.key !== ' ') || e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return false;
+  const el = (e.target as Element).closest?.(ACTIVATABLE);
+  if (!el || !within.contains(el) || el !== e.target) return false;
+  const tag = el.localName;
+  if (tag === 'button' || tag === 'input' || tag === 'select' || tag === 'textarea' || tag === 'summary') return false;
+  if (tag === 'a' && el.hasAttribute('href') && e.key === 'Enter') return false;
+  e.preventDefault();
+  (el as HTMLElement).click();
+  return true;
+};
+
+/**
+ * A click that came from the keyboard (Enter or Space on a link or button,
+ * or our activateByKey). `detail` is 0 for those in Chromium and WebKit, but
+ * Firefox reports 1 for Enter on a link: there the click is a PointerEvent
+ * whose pointerType is '' when no pointer made it (a mouse, pen or touch
+ * names itself). A browser whose click is a plain MouseEvent has no
+ * pointerType: `detail` alone.
+ */
+export const byKeyboard = (e: Event) => (e as MouseEvent).detail === 0 || (e as PointerEvent).pointerType === '';
+

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