@luigisbox/luma 0.0.0-stage → 0.2.0

package/a11y/run.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// yarn luma a11y [path...]: does this integration pass WCAG 2.2 AA (EN 301 549
+// V4.1.1, the European Accessibility Act)? Run from the integration
+// repository (Luma as the @luigisbox/luma package, or an older luma/ submodule):
+//
+//   yarn luma a11y                  (the integration's one `luma` script: bin/luma.mjs)
+//   yarn luma a11y                  the home page (autocomplete, then the search page
+//                                   through the header's form), the fixtures' category and
+//                                   product pages (luma.config.mjs fixtures)
+//   yarn luma a11y /search?q=shoe /sneakers /some-product
+//
+// It builds the integration (yarn build), opens Chromium on the storefront's
+// host name (LBX_HOST) with Luma as a customer installs it (the early-hold
+// snippet first in <head>, then the build, as the platform's loader would
+// import it), and drives the real widgets (a11y/audit.mjs). The page is the
+// integration's stub page (luma.config.mjs `stubPage`) by default, or the live
+// storefront (--origin live, or LBX_ORIGIN=https://…); a storefront that
+// answers with a bot challenge is never worked around: the run falls back to
+// the stub page and says so. Exit code: 0 pass, 1 failures, 2 nothing could
+// be checked (or the run broke). docs/ACCESSIBILITY.md, "Checking an integration".
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const LUMA = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const USAGE = `usage: yarn luma a11y [options] [path...]
+
+  path...            storefront paths to check (default: /, then the fixtures' category and product pages)
+  --origin stub|live the integration's stub page (default) or the live storefront (LBX_ORIGIN)
+  --host <name>      the storefront host name (LBX_HOST; default www.shop.example)
+  --query <text>     what to type into the search input (default: luma.config.mjs fixtures.query)
+  --only <widgets>   autocomplete,search,plp,recommender (comma-separated)
+  --dev              load the integration from the dev server (https://localhost:8069, yarn dev) instead of building it
+  --no-build         use the integration's dist/ as it is
+  --html [file.html] also write an HTML report (default a11y-report.html)
+  --json <file>      also write the findings as JSON
+  --headed           show the browser
+  --site-dir <dir>   the integration repository (default: the current directory, LBX_SITE_DIR)`;
+
+// ------------------------------------------------------------------ options
+
+const args = process.argv.slice(2);
+const opt = { paths: [], html: '', json: '', build: true, dev: false, headed: false, origin: '', host: '', query: '', only: [], siteDir: '' };
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  const next = () => {
+    const v = args[++i];
+    if (v === undefined || v.startsWith('--')) die(`${a} needs a value\n\n${USAGE}`);
+    return v;
+  };
+  if (a === '--help' || a === '-h') {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (a === '--origin') opt.origin = next();
+  else if (a === '--host') opt.host = next();
+  else if (a === '--query') opt.query = next();
+  else if (a === '--only') opt.only = next().split(',').map((s) => s.trim()).filter(Boolean);
+  else if (a === '--dev') opt.dev = true;
+  else if (a === '--no-build') opt.build = false;
+  else if (a === '--headed') opt.headed = true;
+  else if (a === '--json') opt.json = next();
+  else if (a === '--site-dir') opt.siteDir = next();
+  else if (a === '--html') opt.html = args[i + 1] && /\.html?$/i.test(args[i + 1]) ? args[++i] : 'a11y-report.html';
+  else if (a.startsWith('--html=')) opt.html = a.slice(7);
+  else if (a.startsWith('--json=')) opt.json = a.slice(7);
+  else if (a.startsWith('/')) opt.paths.push(a);
+  else die(`unknown argument "${a}" (paths start with "/")\n\n${USAGE}`);
+}
+
+function die(msg, code = 2) {
+  console.error(msg);
+  process.exit(code);
+}
+
+// The integration repository: --site-dir, LBX_SITE_DIR, the current directory, or luma/'s parent.
+const SITE_DIR = [opt.siteDir, process.env.LBX_SITE_DIR, process.cwd(), dirname(LUMA)].filter(Boolean).map((d) => resolve(d)).find((d) => existsSync(join(d, 'integration')));
+if (!SITE_DIR) die('No integration found: run yarn luma a11y in the integration repository (the folder with integration/), or pass --site-dir.');
+process.env.LBX_SITE_DIR = SITE_DIR;
+if (opt.host) process.env.LBX_HOST = opt.host;
+const originOpt = opt.origin || process.env.LBX_ORIGIN || 'stub';
+if (!/^(stub|live|https?:\/\/.+)$/.test(originOpt)) die(`--origin must be stub, live or a storefront URL, not "${originOpt}"`);
+
+// Luma's dev dependencies (playwright-core, axe-core, parse5) live in luma/node_modules.
+for (const dep of ['playwright-core', 'axe-core', 'parse5']) {
+  try {
+    await import(dep);
+  } catch {
+    die(`Luma's dependencies are not installed (${dep} is missing): run \`yarn install\`.`);
+  }
+}
+const { chromium } = await import('playwright-core');
+const { loadConfig } = await import('../bin/config.mjs');
+const config = await loadConfig(SITE_DIR);
+const { host: HOST, stubPage } = config;
+const { audit } = await import('./audit.mjs');
+const { SNIPPET, holdInit } = await import('../parity/hold.mjs');
+const { Results, formatHtml, formatText, summarize } = await import('./report.mjs');
+
+const F = config.fixtures;
+const ORIGIN = originOpt === 'stub' || originOpt === 'live' ? `https://${HOST}` : new URL(originOpt).origin;
+const HOSTNAME = new URL(ORIGIN).host;
+const QUERY = opt.query || F.query || 'a';
+const paths = opt.paths.length ? opt.paths : ['/', F.category, F.product].filter((p, i, a) => p && a.indexOf(p) === i);
+const DIST = join(SITE_DIR, 'dist');
+const DEV = 'https://localhost:8069/integration/__integration.ts';
+const BUNDLE = opt.dev ? DEV : `${ORIGIN}/__lbx/a11y/luma-integration.js`;
+
+// ------------------------------------------------------------------ build
+
+if (!opt.dev && opt.build) {
+  process.stderr.write(`building ${relative(process.cwd(), SITE_DIR) || '.'} (yarn build)… `);
+  try {
+    execFileSync('yarn', ['build'], { cwd: SITE_DIR, stdio: ['ignore', 'pipe', 'pipe'] });
+    process.stderr.write('done\n');
+  } catch (e) {
+    process.stderr.write('failed\n');
+    die(`yarn build failed:\n${e.stdout ?? ''}${e.stderr ?? ''}`);
+  }
+}
+if (!opt.dev && !existsSync(join(DIST, 'luma-integration.js'))) die(`${DIST}/luma-integration.js is missing: run yarn build (or drop --no-build).`);
+
+// ------------------------------------------------------------------ browser
+
+const launch = async () => {
+  const o = { headless: !opt.headed };
+  // Full Chromium in its new headless mode (as the browser suites), else the installed Chrome.
+  const tries = [...(process.env.LBX_CHROMIUM_PATH ? [{ ...o, executablePath: process.env.LBX_CHROMIUM_PATH }] : []), { ...o, channel: 'chromium' }, { ...o, channel: 'chrome' }];
+  let err;
+  for (const t of tries) {
+    try {
+      return await chromium.launch(t);
+    } catch (e) {
+      err = e;
+    }
+  }
+  die(`No Chromium to run: install Chrome, or \`yarn playwright-core install chromium\`, or set LBX_CHROMIUM_PATH.\n${err?.message?.split('\n')[0] ?? ''}`);
+};
+
+const TYPES = { '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.map': 'application/json', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };
+
+/** A context on the storefront's host name: the build served at /__lbx/a11y/, Luigi's Box's CDNs blocked, the stub page or the live site. */
+const newContext = async (browser, stub) => {
+  const ctx = await browser.newContext({ viewport: { width: 1280, height: 800 }, ignoreHTTPSErrors: opt.dev, serviceWorkers: 'block' });
+  // The site's own Luigi's Box scripts (the platform's loader, previous-generation widgets) never run: ours is the build under test.
+  await ctx.route(/^https:\/\/(cdn\.luigisbox\.(com|tech)|cdn\.eu1\.luigisbox\.ai|scripts\.luigisbox\.(com|tech))\//, (r) => r.abort('blockedbyclient'));
+  await ctx.route(`${ORIGIN}/**`, async (route) => {
+    const req = route.request();
+    const url = new URL(req.url());
+    if (url.pathname.startsWith('/__lbx/a11y/')) {
+      const file = normalize(join(DIST, decodeURIComponent(url.pathname.slice('/__lbx/a11y/'.length))));
+      if (!file.startsWith(DIST) || !existsSync(file) || !statSync(file).isFile()) return route.fulfill({ status: 404, body: '' });
+      return route.fulfill({ status: 200, body: readFileSync(file), headers: { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-store' } });
+    }
+    if (!stub) return route.fallback();
+    if (req.resourceType() === 'document') return route.fulfill({ status: 200, contentType: 'text/html; charset=utf-8', body: await stubPage(url) });
+    return route.fulfill({ status: 404, body: '' });
+  });
+  // As a customer installs it, once, in the top document of the storefront: the early-hold snippet
+  // first in <head>, then the bundle as the platform's loader imports it (parity/hold.mjs).
+  await ctx.addInitScript(holdInit, { origin: ORIGIN, bundle: BUNDLE, snippet: SNIPPET, tag: 'a11y' });
+  return ctx;
+};
+
+/** A bot challenge, a block or a rate limit instead of the storefront's page. */
+const challenged = async (res, page) => {
+  if (!res) return 'no response';
+  const h = res.headers();
+  if (h['cf-mitigated'] === 'challenge') return `a Cloudflare challenge (HTTP ${res.status()})`;
+  if (res.status() === 429) return 'HTTP 429 (rate limited)';
+  if (res.status() === 403 || res.status() === 503) {
+    const text = await page.content().catch(() => '');
+    if (/challenge-platform|cf-chl|Just a moment|captcha|Attention Required/i.test(text)) return `a bot challenge (HTTP ${res.status()})`;
+    return `HTTP ${res.status()}`;
+  }
+  return '';
+};
+
+const browser = await launch();
+const results = new Results();
+let stub = originOpt === 'stub';
+let ctx = await newContext(browser, stub);
+let page = await ctx.newPage();
+let fellBack = '';
+if (!stub) {
+  const res = await page.goto(`${ORIGIN}${paths[0]}`, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => null);
+  const why = await challenged(res, page);
+  if (why) {
+    fellBack = `The live storefront ${ORIGIN} answered with ${why}: not worked around; checked on the integration's stub page (luma.config.mjs stubPage) instead.`;
+    console.error(fellBack);
+    results.note(fellBack);
+    await ctx.close();
+    stub = true;
+    ctx = await newContext(browser, true);
+    page = await ctx.newPage();
+  }
+}
+if (stub && !config.ownStubPage) results.note('The integration has no luma.config.mjs stubPage: checked on Luma\'s neutral stub page, without the site\'s own markup and CSS (add one: Luma\'s README, "Tools for an integration repository").');
+
+const errors = [];
+page.on('pageerror', (e) => errors.push(e.message));
+try {
+  await audit(page, {
+    results,
+    paths,
+    query: QUERY,
+    only: opt.only,
+    log: (s) => process.stderr.write(`${s}\n`),
+    goto: async (p) => {
+      const res = await page.goto(`${ORIGIN}${p}`, { waitUntil: 'load', timeout: 45000 }).catch((e) => (results.note(`${p}: ${e.message.split('\n')[0]}`), null));
+      if (!stub && res) {
+        const why = await challenged(res, page);
+        if (why) results.note(`${p}: the live storefront answered with ${why}`);
+      }
+    },
+  });
+} catch (e) {
+  results.note(`the run stopped: ${e.stack ?? e}`);
+  process.exitCode = 2;
+}
+await browser.close();
+for (const e of [...new Set(errors)].slice(0, 5)) results.note(`page error: ${e.slice(0, 300)}`);
+
+// ------------------------------------------------------------------ report
+
+const walk = (dir, out = []) => {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (/^(template-.*\.ts|style-.*\.css|_init\.ts)$/.test(e.name)) out.push(p);
+  }
+  return out;
+};
+// The integration's templates and styles first, then Luma's built-in ones (a node from a built-in template).
+const files = [...walk(join(SITE_DIR, 'integration')), ...walk(join(LUMA, 'src/widgets'))].map((p) => ({ path: relative(SITE_DIR, p), text: readFileSync(p, 'utf8') }));
+const summary = summarize(results, { files });
+const meta = {
+  integration: SITE_DIR,
+  page: stub ? `${ORIGIN} (the integration's stub page${config.ownStubPage ? '' : ': Luma\'s neutral one'})` : `${ORIGIN} (live)`,
+  bundle: opt.dev ? DEV : 'dist/ (yarn build)',
+  axe: `axe-core ${JSON.parse(readFileSync(createRequire(import.meta.url).resolve('axe-core/package.json'), 'utf8')).version}, WCAG 2.0–2.2 A/AA`,
+  date: new Date().toISOString().slice(0, 16).replace('T', ' '),
+};
+console.log(formatText(summary, { color: process.stdout.isTTY && !process.env.NO_COLOR, meta }));
+if (opt.html) {
+  const out = resolve(opt.html);
+  writeFileSync(out, formatHtml(summary, { meta }));
+  console.log(`\nHTML report: ${out}`);
+}
+if (opt.json) {
+  writeFileSync(resolve(opt.json), JSON.stringify({ meta, ...summary }, null, 1));
+  console.log(`JSON: ${resolve(opt.json)}`);
+}
+process.exit(process.exitCode || summary.exitCode);

package/a11y/wcag.mjs

@@ -0,0 +1,233 @@
+// WCAG 2.2 success criteria at levels A and AA (what EN 301 549 V4.1.1 asks
+// of web content for the European Accessibility Act), how axe-core's tags map
+// to them, and how to fix what `yarn luma a11y` finds in a Luma integration.
+// docs/ACCESSIBILITY.md has the background; §5 what templates must do.
+import { relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** axe-core tags for WCAG 2.0–2.2 A and AA. */
+export const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+
+/**
+ * Every WCAG 2.2 A/AA success criterion (4.1.1 Parsing is obsolete in 2.2).
+ * `auto`: what the command can decide by itself (axe or its own checks) on
+ * Luma's widgets; the others need a person (a screen reader pass, captions,
+ * the meaning of a text) and are listed as "check by hand".
+ */
+export const CRITERIA = {
+  '1.1.1': { title: 'Non-text content', level: 'A', auto: true },
+  '1.2.1': { title: 'Audio-only and video-only (prerecorded)', level: 'A' },
+  '1.2.2': { title: 'Captions (prerecorded)', level: 'A' },
+  '1.2.3': { title: 'Audio description or media alternative (prerecorded)', level: 'A' },
+  '1.2.4': { title: 'Captions (live)', level: 'AA' },
+  '1.2.5': { title: 'Audio description (prerecorded)', level: 'AA' },
+  '1.3.1': { title: 'Info and relationships', level: 'A', auto: true },
+  '1.3.2': { title: 'Meaningful sequence', level: 'A' },
+  '1.3.3': { title: 'Sensory characteristics', level: 'A' },
+  '1.3.4': { title: 'Orientation', level: 'AA', auto: true },
+  '1.3.5': { title: 'Identify input purpose', level: 'AA', auto: true },
+  '1.4.1': { title: 'Use of color', level: 'A', auto: true },
+  '1.4.2': { title: 'Audio control', level: 'A' },
+  '1.4.3': { title: 'Contrast (minimum)', level: 'AA', auto: true },
+  '1.4.4': { title: 'Resize text', level: 'AA', auto: true },
+  '1.4.5': { title: 'Images of text', level: 'AA' },
+  '1.4.10': { title: 'Reflow', level: 'AA', auto: true },
+  '1.4.11': { title: 'Non-text contrast', level: 'AA', auto: true },
+  '1.4.12': { title: 'Text spacing', level: 'AA', auto: true },
+  '1.4.13': { title: 'Content on hover or focus', level: 'AA' },
+  '2.1.1': { title: 'Keyboard', level: 'A', auto: true },
+  '2.1.2': { title: 'No keyboard trap', level: 'A', auto: true },
+  '2.1.4': { title: 'Character key shortcuts', level: 'A' },
+  '2.2.1': { title: 'Timing adjustable', level: 'A', auto: true },
+  '2.2.2': { title: 'Pause, stop, hide', level: 'A', auto: true },
+  '2.3.1': { title: 'Three flashes or below threshold', level: 'A' },
+  '2.4.1': { title: 'Bypass blocks', level: 'A', auto: true },
+  '2.4.2': { title: 'Page titled', level: 'A', auto: true },
+  '2.4.3': { title: 'Focus order', level: 'A', auto: true },
+  '2.4.4': { title: 'Link purpose (in context)', level: 'A', auto: true },
+  '2.4.5': { title: 'Multiple ways', level: 'AA' },
+  '2.4.6': { title: 'Headings and labels', level: 'AA' },
+  '2.4.7': { title: 'Focus visible', level: 'AA', auto: true },
+  '2.4.11': { title: 'Focus not obscured (minimum)', level: 'AA' },
+  '2.5.1': { title: 'Pointer gestures', level: 'A' },
+  '2.5.2': { title: 'Pointer cancellation', level: 'A' },
+  '2.5.3': { title: 'Label in name', level: 'A', auto: true },
+  '2.5.4': { title: 'Motion actuation', level: 'A' },
+  '2.5.7': { title: 'Dragging movements', level: 'AA' },
+  '2.5.8': { title: 'Target size (minimum)', level: 'AA', auto: true },
+  '3.1.1': { title: 'Language of page', level: 'A', auto: true },
+  '3.1.2': { title: 'Language of parts', level: 'AA', auto: true },
+  '3.2.1': { title: 'On focus', level: 'A' },
+  '3.2.2': { title: 'On input', level: 'A' },
+  '3.2.3': { title: 'Consistent navigation', level: 'AA' },
+  '3.2.4': { title: 'Consistent identification', level: 'AA' },
+  '3.2.6': { title: 'Consistent help', level: 'A' },
+  '3.3.1': { title: 'Error identification', level: 'A' },
+  '3.3.2': { title: 'Labels or instructions', level: 'A', auto: true },
+  '3.3.3': { title: 'Error suggestion', level: 'AA' },
+  '3.3.4': { title: 'Error prevention (legal, financial, data)', level: 'AA' },
+  '3.3.7': { title: 'Redundant entry', level: 'A' },
+  '3.3.8': { title: 'Accessible authentication (minimum)', level: 'AA' },
+  '4.1.2': { title: 'Name, role, value', level: 'A', auto: true },
+  '4.1.3': { title: 'Status messages', level: 'AA', auto: true },
+};
+
+/** Sorts success criteria numerically (1.4.3 before 1.4.10). */
+export const bySc = (a, b) => {
+  const x = a.split('.').map(Number);
+  const y = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  return 0;
+};
+
+/**
+ * The success criteria of an axe rule, from its tags (`wcag143` -> 1.4.3,
+ * `wcag2411` -> 2.4.11). Only criteria of the catalogue above: an AAA tag
+ * (`wcag146`) is not a failure at AA.
+ */
+export const scOfTags = (tags = []) => {
+  const out = new Set();
+  for (const t of tags) {
+    const m = /^wcag(\d)(\d)(\d{1,2})$/.exec(t);
+    if (!m) continue;
+    const sc = `${m[1]}.${m[2]}.${Number(m[3])}`;
+    if (CRITERIA[sc]) out.add(sc);
+  }
+  return [...out].sort(bySc);
+};
+
+/** docs/ACCESSIBILITY.md as a path from where the command runs (luma/…, node_modules/@luigisbox/luma/…). */
+export const DOC = relative(process.cwd(), fileURLToPath(new URL('../docs/ACCESSIBILITY.md', import.meta.url)));
+
+/**
+ * How to fix a finding in an integration: per axe rule id or per check of
+ * the command's own. Templates are lit (`integration/<widget>/template-*.ts`),
+ * styles `integration/<widget>/style-*.css`.
+ */
+export const FIX = {
+  // axe-core rules
+  'color-contrast': 'Text needs 4.5:1 against its background (3:1 at 24 px, or 19 px bold). Darken the colour in the integration\'s style-*.css; if the site\'s palette is fixed, at least adopt the high-contrast mode (' + DOC + ' §4: rules under :root[data-lbx-contrast="more"]).',
+  'link-in-text-block': 'A link inside text must not be told apart by colour alone: underline it (or 3:1 against the text and a non-colour cue on hover and focus).',
+  'image-alt': 'Give the <img> an alt: alt="" when the product title is in the same link (the picture is decorative), else a short description.',
+  'role-img-alt': 'An element with role="img" needs aria-label (or drop the role if it is decorative and add aria-hidden="true").',
+  'svg-img-alt': 'An <svg role="img"> needs a <title> or aria-label; a decorative icon gets aria-hidden="true" instead.',
+  'input-image-alt': 'An <input type="image"> needs alt text naming its action.',
+  'button-name': 'A button needs a name: visible text, or aria-label=${t(\'…\')} when it is an icon (e.g. the close "×" or a slider arrow).',
+  'link-name': 'A link needs a name: its text, or aria-label when it holds only an image or icon. A tile\'s link reads as its title (the image alt="").',
+  'label': 'A form control needs a label: <label> around it or for= its id, or aria-label. Filters: a fieldset with a legend and a label per checkbox; range thumbs "Price min" / "Price max".',
+  'select-name': 'A <select> (e.g. the sort) needs a label or aria-label.',
+  'aria-input-field-name': 'An element with an input role (combobox, slider, spinbutton, …) needs aria-label or aria-labelledby.',
+  'aria-toggle-field-name': 'A role="checkbox" / "switch" / "menuitemcheckbox" needs a name (its text or aria-label).',
+  'aria-command-name': 'A role="button" / "link" / "menuitem" needs a name (its text or aria-label).',
+  'aria-meter-name': 'A role="meter" needs a name.',
+  'aria-progressbar-name': 'A role="progressbar" needs a name.',
+  'aria-tooltip-name': 'A role="tooltip" needs a name.',
+  'aria-dialog-name': 'A dialog needs a name (aria-label or aria-labelledby its heading). Luma names the drawer panel "Filters" unless the markup names it.',
+  'aria-required-children': 'A listbox may hold only role="option" and role="group" (with options): wrappers in between get role="presentation", headings go in a group\'s aria-label, and "Show all results" goes outside the listbox (or aria-hidden="true" if it repeats Enter). ' + DOC + ' §5.',
+  'aria-required-parent': 'role="option" must be inside role="listbox" (or a group in one); role="listitem" inside a list; role="tab" inside a tablist. Put the role on the container, or drop the child\'s role.',
+  'aria-required-attr': 'The role is missing an attribute it requires (e.g. aria-checked on role="checkbox", aria-valuenow on a slider, aria-selected on an option in a listbox).',
+  'aria-allowed-attr': 'The attribute is not allowed on this role (e.g. aria-checked on a plain link: make it role="checkbox" with aria-checked, or use a native checkbox).',
+  'aria-prohibited-attr': 'aria-label is not allowed on this element\'s role (a <div> or <span> without a role): give it a role, or put the text in the content.',
+  'aria-valid-attr-value': 'An ARIA attribute has an invalid value (e.g. aria-controls or aria-labelledby pointing at an id that is not there, aria-expanded other than true/false).',
+  'aria-valid-attr': 'A misspelt or unknown aria-* attribute: fix the name.',
+  'aria-roles': 'An unknown role value: use a WAI-ARIA role.',
+  'aria-allowed-role': 'This role is not allowed on this element (e.g. role="button" on a link that navigates): use the matching element instead.',
+  'aria-hidden-focus': 'Something focusable is inside aria-hidden="true": add tabindex="-1" to it, or do not hide it.',
+  'aria-hidden-body': 'aria-hidden must never be on <body>.',
+  'aria-braille-equivalent': 'aria-braillelabel needs an aria-label too.',
+  'aria-conditional-attr': 'An ARIA attribute is used where the role does not support it in this state (e.g. aria-checked on a native checkbox: remove it, the input has its own state).',
+  'aria-deprecated-role': 'A deprecated ARIA role: use its replacement.',
+  'nested-interactive': 'An interactive element is inside another (a button in a link, a link in a role="option"): screen readers announce only the outer one. Move the inner control out, or make it non-interactive.',
+  'list': 'A <ul>/<ol> may contain only <li> (and script/template): wrap other children in an <li>, or use a <div>.',
+  'listitem': 'An <li> must be inside a <ul> or <ol> (or role="list").',
+  'definition-list': 'A <dl> may contain only <dt>/<dd> groups.',
+  'dlitem': '<dt>/<dd> must be inside a <dl>.',
+  'duplicate-id-aria': 'Two elements share an id that ARIA refers to: ids in a template that repeats (tiles, facets) need a unique suffix.',
+  'duplicate-id-active': 'Two focusable elements share an id: make ids unique per tile/facet.',
+  'heading-order': 'Heading levels skip a level.',
+  'empty-heading': 'A heading has no text: remove the heading element or give it text.',
+  'empty-table-header': 'A table header cell has no text.',
+  'frame-title': 'An <iframe> needs a title.',
+  'td-headers-attr': 'A table cell\'s headers attribute points at missing header cells.',
+  'th-has-data-cells': 'A table header has no data cells; layout tables get role="presentation".',
+  'scrollable-region-focusable': 'A scrolling container must be reachable by keyboard: tabindex="0" on it (with a name), unless every item in it is focusable.',
+  'target-size': 'Targets need 24 x 24 CSS px, or 24 px of space around them (WCAG 2.5.8): padding or min-height/min-width on the control in style-*.css (range thumbs, chips\' ×, pager links, small checkboxes).',
+  'autocomplete-valid': 'An autocomplete attribute has an invalid value.',
+  'avoid-inline-spacing': 'Inline style with !important on letter/word spacing or line height prevents users\' text spacing overrides: move it to CSS without !important.',
+  'meta-viewport': 'The page\'s viewport meta disables zoom (user-scalable=no or maximum-scale<2): the host page\'s.',
+  'html-has-lang': 'The page needs <html lang>: the host page\'s.',
+  'html-lang-valid': 'The page\'s lang value is invalid: the host page\'s.',
+  'valid-lang': 'A lang attribute has an invalid value.',
+  'document-title': 'The page needs a <title>: the host page\'s.',
+  'bypass': 'The page needs a skip link or landmarks: the host page\'s.',
+  'blink': '<blink> must not be used.',
+  'marquee': '<marquee> must not be used.',
+  'server-side-image-map': 'Server-side image maps are not keyboard-accessible.',
+  'area-alt': 'An image map area needs alt text.',
+  'object-alt': 'An <object> needs alternative text.',
+  'video-caption': 'A video needs captions.',
+  'audio-caption': 'Audio needs a transcript.',
+  'no-autoplay-audio': 'Audio must not play automatically for more than 3 s without a control.',
+  'form-field-multiple-labels': 'A control has more than one label: keep one.',
+  'input-button-name': 'An <input type="button|submit|reset"> needs a value or aria-label.',
+  'p-as-heading': 'Bold or large text used as a heading should be a heading element.',
+  'identical-links-same-purpose': 'Links with the same name go to different places.',
+  'label-content-name-mismatch': 'The visible label must be part of the accessible name (aria-label starts with the visible text).',
+
+  // The command's own checks
+  'combobox-role': 'Luma sets role="combobox", aria-expanded, aria-controls and aria-autocomplete on _global.inputSelector while it has focus. Missing ones mean the input Luma binds is not the one the shopper types into (check inputSelector), or the host\'s code removes them.',
+  'combobox-controls': 'aria-controls must name the dropdown that is on the page. Light DOM: the integration\'s autocomplete-box template keeps Luma\'s host (no id of its own on another element with the same id).',
+  'combobox-active-option': 'The keyboard selection must be exposed: in light DOM (dom: "light") options need id="lbx-ac-<i>" (from the template scope) and aria-selected, so aria-activedescendant points at them (from an input in a shadow root, where an id cannot reach the document, Luma sets ariaActiveDescendantElement instead). ' + DOC + ' §5.',
+  'combobox-restore':
+    'Once focus leaves the input, Luma puts its ARIA back as the host had it. When the summary says the input is in a shadow root and focus moved within it (a web-component header: Tab to the button beside the input), Luma did not see focus leave (the dropdown also stays open there): update Luma, which sees a focusout that stays inside a shadow root; a focusout re-dispatched by an _init.ts is then not needed. Otherwise a host script that copies or freezes attributes on focus interferes: report it with the page.',
+  'combobox-focus': 'Focus must stay in the input while the arrows move the selection: options are tabindex="-1", nothing in the dropdown takes focus on pointerdown.',
+  'combobox-escape': 'Escape must close the dropdown (aria-expanded="false").',
+  'status-message': 'Changes must be announced without moving focus (WCAG 4.1.3). Luma announces them in its own [data-lbx-a11y] status region; a template must not remove it, nor wrap it in aria-hidden or a hidden container. Do not add aria-live of your own (two would speak).',
+  'focus-lost': 'After a filter, sort or "show more", focus must not fall back to <body>. Luma moves it to the listing when the focused control is gone; a template that re-creates the control (a key that changes on every render) loses it: give repeated controls a stable key (repeat(list, (x) => x.id, …)).',
+  'not-focusable': 'This element acts as a control (a role="button"/"checkbox"/"option" or a click handler on a div) but cannot get keyboard focus: use a <button>/<a href>/<input>, or add tabindex="0" (Luma then adds Enter/Space to role="button").',
+  'hidden-control': 'A checkbox or radio is display:none or visibility:hidden behind a custom-drawn box: keyboard users cannot reach it. Hide it visually instead (opacity:0; position:absolute; or the .lbx-sr-only class) so it keeps focus, and draw the focus ring on the custom box (input:focus-visible + .checkmark).',
+  'focus-visible': 'Keyboard focus must be visible: the site\'s CSS removes the outline (e.g. *:focus { outline: none }) on this control. Add a :focus-visible style in the integration\'s style-*.css (an outline of at least 2 px in a colour at 3:1).',
+  'keyboard-filter': 'A filter could not be applied from the keyboard (Space on its checkbox or Enter on its link changed nothing): keep filters native checkboxes or links, or role="checkbox" with tabindex="0".',
+  'menu-expanded': 'The sort/menu button must say whether it is open: Luma sets aria-expanded on the [data-lbx-toggle] with aria-haspopup (else the first one). Mark the menu [data-lbx-menu] and its button [data-lbx-toggle].',
+  'menu-focus': 'Opened from the keyboard, focus must move into the menu (its selected item, else the first): the items must be focusable (links, buttons, or role="option" with tabindex="0").',
+  'menu-escape': 'Escape must close the menu and return focus to its button.',
+  'drawer-dialog': 'While open, the filter drawer must be a named modal dialog: mark its panel [data-lbx-drawer-panel] (Luma adds role="dialog", aria-modal and the name), the openers [data-lbx-drawer="open"].',
+  'drawer-focus': 'Opening the drawer must move focus into it, and Tab must stay inside while it is open: the panel must be [data-lbx-drawer-panel] and contain the drawer\'s controls (its close button included).',
+  'drawer-escape': 'Escape must close the drawer and return focus to the button that opened it.',
+  'reflow': 'At 320 CSS px wide (400 % zoom) nothing may need horizontal scrolling: a fixed width or min-width in style-*.css, a wide table or a nowrap row. Use max-width:100%, flex-wrap and minmax(0,1fr) grids; a deliberate scrolling row (a recommender carousel) needs overflow-x:auto on its own container.',
+  'region-name': 'The listing / recommender must be a named region: Luma sets role="region" and aria-label (search.label, plp.label; the recommender\'s title). A template must not override them with an empty name.',
+  'forced-colors-selection': 'In Windows contrast themes (forced-colors: active) backgrounds and shadows are replaced: draw a selected or checked state with an outline or border, or with forced-color-adjust:none and system colours (Highlight / HighlightText). ' + DOC + ' §4.',
+  'contrast-mode': 'Under the OS "increase contrast" setting (prefers-contrast: more) Luma\'s high-contrast mode is on; the integration\'s own colours must follow: rules under :root[data-lbx-contrast="more"] in style-*.css. ' + DOC + ' §4.',
+  'reduced-motion': 'Under prefers-reduced-motion: reduce, motion of ours should stop (transitions of transform/position, animations, smooth scrolling): wrap them in @media (prefers-reduced-motion: no-preference). WCAG 2.3.3 is AAA: advisory, not an AA failure.',
+};
+
+/** The SC each of the command's own checks tests. */
+export const CHECK_SC = {
+  'combobox-role': ['4.1.2'],
+  'combobox-controls': ['4.1.2'],
+  'combobox-active-option': ['4.1.2'],
+  'combobox-restore': ['4.1.2'],
+  'combobox-focus': ['2.4.3', '2.1.1'],
+  'combobox-escape': ['2.1.1'],
+  'status-message': ['4.1.3'],
+  'focus-lost': ['2.4.3'],
+  'not-focusable': ['2.1.1'],
+  'hidden-control': ['2.1.1'],
+  'focus-visible': ['2.4.7'],
+  'keyboard-filter': ['2.1.1'],
+  'menu-expanded': ['4.1.2'],
+  'menu-focus': ['2.4.3'],
+  'menu-escape': ['2.1.1', '2.4.3'],
+  'drawer-dialog': ['4.1.2', '1.3.1'],
+  'drawer-focus': ['2.4.3', '2.1.2'],
+  'drawer-escape': ['2.1.2', '2.4.3'],
+  'reflow': ['1.4.10'],
+  'region-name': ['1.3.1'],
+  'forced-colors-selection': ['1.4.11', '1.4.1'],
+  'contrast-mode': ['1.4.3', '1.4.11'],
+  // AAA: reported, never fails the run
+  'reduced-motion': [],
+};
+
+/** Checks whose findings are advice, not AA failures. */
+export const ADVISORY = new Set(['reduced-motion']);

package/bin/config.mjs

@@ -0,0 +1,60 @@
+// An integration's settings for Luma's tools: its luma.config.mjs, with Luma's
+// defaults for what it leaves out. Every tool loads it (yarn luma <tool>), the
+// server-side rendering rig too (not in the published package). The integration's file may export:
+//
+//   host      the storefront's host name: the tools open it      LBX_HOST overrides it
+//   site      the site's name (the rig's fragment URLs)           LBX_SITE overrides it; default: package.json's name
+//   stubPage  (url) => HTML: a page in the site's markup when the live storefront is not used
+//   fixtures  a category, a query, a product… the tools' scenarios use
+//   perf      { pages }: the pages footprint and tasks measure
+//   anchors, routeOf, headExtra   the server-side rendering rig's template change
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const CONFIG_FILE = 'luma.config.mjs';
+/** Its name before 2026-10-12: the edge rig's, though every tool reads it. */
+export const OLD_CONFIG_FILE = 'edge/rig.mjs';
+/** The host the stub page is served as when the storefront's is not known. */
+export const STUB_HOST = 'www.shop.example';
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+/** A neutral storefront page: a header search form, and on /search the search anchor, elsewhere a category listing. */
+export const neutralStubPage = (url) => {
+  const search = url.pathname === '/search';
+  const q = search ? (url.searchParams.get('q') ?? '') : '';
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>stub ${esc(url.pathname)}</title></head>
+<body>
+<header><form action="/search" method="get" role="search"><input name="q" autocomplete="off" value="${esc(q)}"><button>Search</button></form></header>
+<main>
+${search ? '<div id="lbx-search-anchor"></div>' : `<h1>${esc(url.pathname.slice(1))}</h1><div id="lbx-listing"><p class="their-listing" style="min-height:400px">their listing</p></div>`}
+</main></body></html>`;
+};
+
+/**
+ * The integration's settings: its luma.config.mjs (none: Luma's defaults), the environment's LBX_HOST and LBX_SITE first.
+ * `hostKnown`: the storefront's host is named (else `host` is the stub's); `ownStubPage`: the integration has a stub page of its own.
+ * @param {string} dir  the integration repository ('': none, Luma's defaults)
+ * @param {Record<string, string | undefined>} [env]
+ */
+export const loadConfig = async (dir, env = process.env) => {
+  const file = dir && join(dir, CONFIG_FILE);
+  if (file && !existsSync(file) && existsSync(join(dir, OLD_CONFIG_FILE)))
+    throw new Error(`${OLD_CONFIG_FILE} is now ${CONFIG_FILE}: rename it (yarn luma tooling --write does)`);
+  const own = file && existsSync(file) ? await import(pathToFileURL(file).href) : {};
+  let name = '';
+  try {
+    if (dir) name = String(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name ?? '').replace(/^@[^/]+\//, '');
+  } catch {}
+  const host = env.LBX_HOST || own.host || '';
+  return {
+    ...own,
+    host: host || STUB_HOST,
+    hostKnown: !!host,
+    site: env.LBX_SITE || own.site || name || (dir && basename(dir)) || 'site',
+    stubPage: own.stubPage ?? neutralStubPage,
+    ownStubPage: !!own.stubPage,
+    fixtures: own.fixtures ?? {},
+  };
+};