@luigisbox/luma 0.0.0-stage → 0.1.0

package/src/api/ai.ts

@@ -0,0 +1,98 @@
+// Luigi's Box AI discovery client: the requests (search, facets, recommend).
+// Authentication (publishable key -> browser token, the visitor id) is
+// ./token.ts, in the entry so that every page mints the token at boot.
+//
+// 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 type { GlobalConfigType } from '../types';
+import type { Api, FacetData, Hit, Page } from '.';
+import { fetchJson, TIMEOUT_MS, tokensFor, untilAborted, visitorId } from './token';
+
+export { untilAborted };
+
+export const aiApi = (g: GlobalConfigType, origin?: string): Api => {
+  const tk = tokensFor(g, origin);
+  const { API, originHeaders } = tk;
+  const getToken = tk.get;
+
+  // A 401 re-mints, but not on every request when a fresh token is refused too
+  // (an origin the key does not allow): at most once a minute. A request whose
+  // token was already replaced (a parallel one re-minted) just retries once.
+  let reminted = -Infinity;
+  const post = async (path: string, params: Record<string, string>, body: unknown, signal?: AbortSignal, retried = false): Promise<any> => {
+    health.apiCalls++;
+    // The caller's signal bounds the wait for a token too (a server render's budget).
+    const t = await untilAborted(getToken(), signal);
+    const qs = new URLSearchParams(params).toString();
+    const r = await fetchJson(
+      `${API}/discovery/v1/${path}?${qs}`,
+      {
+        method: 'POST',
+        headers: { ...originHeaders, Authorization: `Bearer ${t}`, 'X-Lbx-Visitor-Id': visitorId(), 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+      TIMEOUT_MS,
+      signal,
+    );
+    if (r.status === 401 && !retried) {
+      if (tk.current() !== t) return post(path, params, body, signal, true);
+      if (Date.now() - reminted > 60e3) {
+        // Expired or revoked early: mint a new one.
+        reminted = Date.now();
+        tk.clear();
+        return post(path, params, body, signal, true);
+      }
+    }
+    if (!r.ok) throw new Error(`${path}: HTTP ${r.status} ${r.body.slice(0, 300)}`);
+    if (r.json == null) throw new Error(`${path}: not JSON`);
+    return r.json;
+  };
+
+  /** Drops undefined fields: unknown or empty ones are a 422. */
+  const compact = (o: Record<string, unknown>) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+  const nonEmpty = (f?: Record<string, unknown>) => (f && Object.keys(f).length ? f : undefined);
+
+  return {
+    warm: () => void getToken().catch(() => {}),
+
+    search: async (r, signal): Promise<Page> => {
+      const body = compact({
+        type: r.type,
+        size: r.size,
+        query: r.endpoint === 'search' ? (r.query ?? '') : undefined,
+        collection_filters: r.endpoint === 'collections' ? nonEmpty(r.scope) : undefined,
+        filters: nonEmpty(r.filters),
+        sort: r.sort,
+        cursor: r.cursor || undefined,
+        return_fields: r.fields?.length ? r.fields : undefined,
+      });
+      const j = await post(r.endpoint, { channel_id: g.channelId, surface_id: r.surface }, body, signal);
+      return { hits: j.hits ?? [], total: j.total ?? j.total_approx ?? 0, guid: j.guid, cursor: j.next_page_cursor ?? null, status: j.pagination_status ?? 'exhausted' };
+    },
+
+    facets: async (guid, facets, signal): Promise<Record<string, FacetData>> =>
+      (await post('facets', { channel_id: g.channelId }, { guid, facets: facets.map((f) => compact(f)) }, signal)).facets ?? {},
+
+    recommend: async (r, signal): Promise<Hit[]> =>
+      (
+        await post(
+          'recommender',
+          { channel_id: g.channelId, surface_id: r.surface },
+          compact({
+            type: r.type,
+            size: r.size,
+            anchor_ids: r.anchors.length ? r.anchors.slice(0, 50) : undefined,
+            exclude_ids: r.exclude?.length ? r.exclude.slice(0, 50) : undefined,
+            filters: nonEmpty(r.filters),
+            return_fields: r.fields?.length ? r.fields : undefined,
+          }),
+          signal,
+        )
+      ).hits ?? [],
+  };
+};

package/src/api/index.ts

@@ -0,0 +1,87 @@
+// The data API behind every widget: Luigi's Box AI discovery
+// (api.<region>.luigisbox.ai/discovery/v1). Widgets only see this interface;
+// the implementation (./ai.ts) owns authentication (publishable key ->
+// browser token), the visitor id and the wire format.
+
+import type { GlobalConfigType } from '../types';
+import { aiApi } from './ai';
+
+/** A catalog object as discovery returns it: flat, `@id` and `@type` always present. */
+export interface Hit {
+  '@id': string;
+  '@type': string;
+  [field: string]: any;
+}
+
+/** A discovery filter tree: condition and group nodes. */
+export type FilterNode = Record<string, unknown>;
+
+export interface Sort {
+  field: string;
+  direction: 'asc' | 'desc';
+}
+
+/** One page of /search or /collections. */
+export interface Page {
+  hits: Hit[];
+  /** Exact when known, else the API's approximation. */
+  total: number;
+  /** Identifies the result set; /facets takes it. */
+  guid: string;
+  /** Cursor of the next page; null when there is none (see status). */
+  cursor: string | null;
+  /** more | exhausted | unsupported | unavailable */
+  status: string;
+}
+
+export interface ListingRequest {
+  /** search: a query; collections: a scope (collection_filters). */
+  endpoint: 'search' | 'collections';
+  surface: string;
+  type: string;
+  query?: string;
+  scope?: FilterNode;
+  filters?: FilterNode;
+  sort?: Sort;
+  size: number;
+  /** From the previous page; every other field must be unchanged. */
+  cursor?: string;
+  fields?: string[];
+}
+
+export interface FacetData {
+  field: string;
+  type: 'terms' | 'range' | 'hierarchy' | string;
+  values?: any[];
+  min?: number;
+  max?: number;
+}
+
+export interface RecoRequest {
+  surface: string;
+  type: string;
+  /** Typed identities ("product/<id>") the slate is about; [] = none. */
+  anchors: string[];
+  exclude?: string[];
+  size: number;
+  filters?: FilterNode;
+  fields?: string[];
+}
+
+export interface Api {
+  search(r: ListingRequest, signal?: AbortSignal): Promise<Page>;
+  /** Facets of a result set (its guid): values, no counts. */
+  facets(guid: string, facets: { field: string; size?: number }[], signal?: AbortSignal): Promise<Record<string, FacetData>>;
+  recommend(r: RecoRequest, signal?: AbortSignal): Promise<Hit[]>;
+  /** Mint the browser token now, so the first request does not wait for it. */
+  warm(): void;
+}
+
+const apis = new Map<string, Api>();
+/** `origin`: the storefront origin, for server-side callers (browsers send their own). */
+export const getApi = (g: GlobalConfigType, origin?: string): Api => {
+  const k = `${g.channelId}|${g.region ?? 'eu1'}|${origin ?? ''}`;
+  let api = apis.get(k);
+  if (!api) apis.set(k, (api = aiApi(g, origin)));
+  return api;
+};

package/src/api/token-key.ts

@@ -0,0 +1,42 @@
+// Where the browser token is kept (sessionStorage), and whether a fresh one is
+// there: the entry asks this at boot and loads the minting code (./token.ts,
+// its own chunk) only when there is none. No DOM.
+
+import { session } from '../core/storage';
+import type { GlobalConfigType } from '../types';
+
+export interface StoredToken {
+  token: string;
+  /** ms epoch; refreshed 30 s early. */
+  exp: number;
+}
+
+/** Per key too: a rotated publishable key must not keep using a stored token of the old one. */
+export const tokenKey = (g: GlobalConfigType) => `lbx:tok:${g.publishableKey}:${g.channelId}:${g.region ?? 'eu1'}`;
+
+/** The stored token of this channel while it is valid. */
+export const storedToken = (g: GlobalConfigType): StoredToken | null => {
+  const t = session.get<StoredToken>(tokenKey(g));
+  return t && t.exp > Date.now() ? t : null;
+};
+
+const challenges = new Map<string, Promise<Response>>();
+/** The browser challenge of this channel's key. */
+export const challengeUrl = (g: GlobalConfigType) => `https://auth.${g.region ?? 'eu1'}.luigisbox.ai/browser-challenge?api_key=${encodeURIComponent(g.publishableKey)}`;
+/**
+ * The challenge asked by the entry (main.ts warm()) while the minting code,
+ * its own chunk, loads: the mint starts a round trip earlier. Taken once by
+ * ./token.ts (a challenge expires in seconds).
+ */
+export const askChallenge = (g: GlobalConfigType) => {
+  const url = challengeUrl(g);
+  if (challenges.has(url)) return;
+  const p = fetch(url);
+  p.catch(() => {}); // the mint that takes it reports a failure
+  challenges.set(url, p);
+};
+export const takeChallenge = (url: string) => {
+  const p = challenges.get(url);
+  challenges.delete(url);
+  return p;
+};

package/src/api/token.ts

@@ -0,0 +1,311 @@
+// 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.
+          audience: [`${API}/discovery`, `${API}/events`],
+        }),
+      },
+      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 === '';
+