@meddleware/frontend-config 0.0.0-stage → 0.0.1

package/package.json

@@ -1,6 +1,161 @@
 {
   "name": "@meddleware/frontend-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Shared frontend tooling for MeddleWare apps: browser support, ESLint, Stylelint, html-validate, PostCSS, Playwright, axe, screenshots, Lighthouse and the Vite target.",
+  "license": "0BSD",
+  "author": "MeddleWare <dev@meddleware.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meddleware-org/frontend-config.git"
+  },
+  "keywords": [
+    "browserslist",
+    "eslint",
+    "stylelint",
+    "html-validate",
+    "playwright",
+    "accessibility",
+    "wcag",
+    "vue"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./browserslist-config": "./src/browserslist-config.cjs",
+    "./eslint": {
+      "types": "./dist/eslint.d.ts",
+      "default": "./src/eslint.js"
+    },
+    "./stylelint": {
+      "types": "./dist/stylelint.d.ts",
+      "default": "./src/stylelint.js"
+    },
+    "./html-validate": {
+      "types": "./dist/html-validate.d.ts",
+      "default": "./src/html-validate.js"
+    },
+    "./postcss": {
+      "types": "./dist/postcss.d.ts",
+      "default": "./src/postcss.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright.d.ts",
+      "default": "./src/playwright.js"
+    },
+    "./look": {
+      "types": "./dist/look.d.ts",
+      "default": "./src/look.js"
+    },
+    "./axe": {
+      "types": "./dist/axe.d.ts",
+      "default": "./src/axe.js"
+    },
+    "./a11y": {
+      "types": "./dist/a11y.d.ts",
+      "default": "./src/a11y.js"
+    },
+    "./shots": {
+      "types": "./dist/shots.d.ts",
+      "default": "./src/shots.js"
+    },
+    "./lighthouserc": {
+      "types": "./dist/lighthouserc.d.ts",
+      "default": "./src/lighthouserc.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./src/vite.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.ts",
+      "default": "./src/vitest.js"
+    },
+    "./wallet": {
+      "types": "./dist/wallet.d.ts",
+      "default": "./src/wallet.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "~4.14.0",
+    "@double-great/stylelint-a11y": "^3.8.1",
+    "@meddleware/eslint-config": "^0.0.4",
+    "@vue/eslint-config-typescript": "^14.9.0",
+    "autoprefixer": "^10.6.2",
+    "browserslist-to-esbuild": "^2.1.1",
+    "eslint-plugin-compat": "^7.0.2",
+    "eslint-plugin-vue": "^10.12.0",
+    "eslint-plugin-vuejs-accessibility": "^2.6.3",
+    "html-validate-vue": "^9.3.1",
+    "postcss-html": "^2.0.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-declaration-strict-value": "^1.12.1",
+    "stylelint-no-unsupported-browser-features": "^8.1.2",
+    "typescript-eslint": "^8.72.1",
+    "vue-eslint-parser": "^10.4.1"
+  },
+  "peerDependencies": {
+    "@playwright/test": "~1.64.1",
+    "eslint": "^10.0.0",
+    "html-validate": "^11.0.0",
+    "postcss": "^8.5.0",
+    "stylelint": "^17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "html-validate": {
+      "optional": true
+    },
+    "postcss": {
+      "optional": true
+    },
+    "stylelint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "~1.64.1",
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "~26.6.5",
+    "browserslist": "^4.29.1",
+    "eslint": "^10.13.0",
+    "globals": "^17.0.0",
+    "html-validate": "^11.17.0",
+    "jsdom": "^30.1.3",
+    "postcss": "^8.5.32",
+    "stylelint": "^17.16.0",
+    "typescript": "~6.0.3",
+    "vitest": "~5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "browserslist": [
+    "last 2 Chrome versions",
+    "last 2 ChromeAndroid versions",
+    "last 2 Edge versions",
+    "last 2 Firefox versions",
+    "last 2 FirefoxAndroid versions",
+    "last 2 Safari versions",
+    "last 2 iOS versions",
+    "last 2 Samsung versions",
+    "Firefox ESR",
+    "not dead"
+  ]
+}

package/src/a11y.js

@@ -0,0 +1,129 @@
+// @ts-check
+// The accessibility sweep every app runs, in one call: each state of the app (a route, a dialog open, an error page) in every colour mode
+// × season at WCAG 2.2 AA and AAA, then at a 320 px reflow width, at 200% text size, in forced colours and with reduced motion, and a
+// keyboard pass (every Tab stop is visible and shows where focus is). The assertions are exported on their own for specs that need one.
+//
+//   // e2e/a11y.spec.ts
+//   defineA11ySuite({ home: async (page) => { await page.goto('/') }, empty: openEmpty }, { aaa: 'gate' })
+import { expect, test } from '@playwright/test'
+import { expectAccessible } from './axe.js'
+import { applyLook, looks, offline } from './look.js'
+
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} State */
+
+/**
+ * The page has no horizontal scroll: nothing is wider than the viewport (WCAG 1.4.10 reflow, and 1.4.4 at a larger text size).
+ * @param {import('@playwright/test').Page} page
+ */
+export async function expectNoHorizontalScroll(page) {
+  const overflow = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)
+  expect(overflow, 'the page scrolls sideways by this many CSS pixels').toBeLessThanOrEqual(0)
+}
+
+/**
+ * No animation is running: with `prefers-reduced-motion: reduce` the page holds still (WCAG 2.3.3).
+ * @param {import('@playwright/test').Page} page
+ */
+export async function expectNoRunningAnimations(page) {
+  await page.waitForTimeout(250)
+  const running = await page.evaluate(() => document.getAnimations().filter((a) => a.playState === 'running').map((a) => (/** @type {KeyframeEffect | null} */ (a.effect)?.target?.className || 'animation')))
+  expect(running, 'animations still running under reduced motion').toEqual([])
+}
+
+/**
+ * Tab through the page: every stop is visible and shows a focus indicator (an outline or a shadow), and the tab order ends (no trap).
+ * @param {import('@playwright/test').Page} page
+ * @param {{ maxStops?: number }} [options]
+ */
+export async function expectKeyboardFocusVisible(page, { maxStops = 120 } = {}) {
+  /** @type {string[]} */
+  const problems = []
+  let stops = 0
+  const seen = new Set()
+  for (let i = 0; i < maxStops; i++) {
+    await page.keyboard.press('Tab')
+    const stop = await page.evaluate(() => {
+      const el = document.activeElement
+      if (!el || el === document.body) return null
+      // A visually hidden control (a radio or checkbox inside its label) shows focus on its label, so that is what is checked.
+      const tiny = el.getBoundingClientRect().width < 4 || el.getBoundingClientRect().height < 4
+      const target = tiny ? (el.closest('label') ?? el.parentElement ?? el) : el
+      const box = target.getBoundingClientRect()
+      const shows = (/** @type {Element} */ node) => {
+        const style = getComputedStyle(node)
+        return (style.outlineStyle !== 'none' && parseFloat(style.outlineWidth) > 0) || style.boxShadow !== 'none'
+      }
+      const indicator = shows(target) || (!tiny && shows(el)) || ['::before', '::after'].some((p) => {
+        const s = getComputedStyle(target, p)
+        return (s.outlineStyle !== 'none' && parseFloat(s.outlineWidth) > 0) || s.boxShadow !== 'none'
+      })
+      const label = `${el.tagName.toLowerCase()}${el.id ? `#${el.id}` : ''}${el.getAttribute('aria-label') ? `[${el.getAttribute('aria-label')}]` : ''} "${(target.textContent ?? '').trim().slice(0, 24)}"`
+      return { label, visible: box.width > 0 && box.height > 0, indicator }
+    })
+    if (!stop) break // focus left the document: the cycle is complete
+    const key = stop.label
+    if (seen.has(key) && seen.size > 1 && i > seen.size + 1) break
+    seen.add(key)
+    stops++
+    if (!stop.visible) problems.push(`${stop.label} takes focus but is not visible`)
+    if (!stop.indicator) problems.push(`${stop.label} shows no focus indicator`)
+  }
+  expect(stops, 'the page has no keyboard stops').toBeGreaterThan(0)
+  expect(problems).toEqual([])
+}
+
+/**
+ * @param {Record<string, State>} states Opens each state of the app (navigates, mocks, opens the dialog).
+ * @param {{ aaa?: 'gate' | 'report' | 'off' }} [options] How WCAG AAA findings are treated (default `report`; a repo moves to `gate`
+ *   in the release that clears them).
+ */
+export function defineA11ySuite(states, { aaa = 'report' } = {}) {
+  for (const [name, open] of Object.entries(states)) {
+    test.describe(name, () => {
+      test.beforeEach(async ({ page }) => {
+        await offline(page)
+      })
+
+      for (const { theme, season } of looks().filter((l) => l.viewport === 'desktop')) {
+        test(`WCAG 2.2 AA and AAA (${theme} · ${season})`, async ({ page }) => {
+          await page.emulateMedia({ colorScheme: /** @type {'light' | 'dark'} */ (theme), reducedMotion: 'reduce' })
+          await open(page)
+          await applyLook(page, theme, season)
+          await expectAccessible(page, { aaa })
+        })
+      }
+
+      test('reflows at 320 CSS pixels', async ({ page }) => {
+        await page.setViewportSize({ width: 320, height: 640 })
+        await open(page)
+        await expectNoHorizontalScroll(page)
+        await expectAccessible(page, { aaa: 'off' })
+      })
+
+      test('holds at 200% text size', async ({ page }) => {
+        await open(page)
+        await page.addStyleTag({ content: 'html { font-size: 200% !important; }' })
+        await expectNoHorizontalScroll(page)
+        await expectAccessible(page, { aaa: 'off' })
+      })
+
+      test('works in forced colours', async ({ page }) => {
+        await page.emulateMedia({ forcedColors: 'active' })
+        await open(page)
+        // The browser chooses the colours in forced-colours mode, so axe's contrast arithmetic on the declared ones does not apply.
+        await expectAccessible(page, { aaa: 'off', disableRules: ['color-contrast'] })
+      })
+
+      test('holds still with reduced motion', async ({ page }) => {
+        await page.emulateMedia({ reducedMotion: 'reduce' })
+        await open(page)
+        await expectNoRunningAnimations(page)
+      })
+
+      test('can be used from the keyboard, and shows where focus is', async ({ page }) => {
+        await open(page)
+        await expectKeyboardFocusVisible(page)
+      })
+    })
+  }
+}

package/src/axe.js

@@ -0,0 +1,43 @@
+// @ts-check
+// Accessibility assertion for Playwright: WCAG 2.2 AA is always a hard gate. WCAG AAA (enhanced contrast and so on) is
+// `report` (attached to the test as annotations; the default while a repo still has findings) or `gate` (fails the run; a repo
+// switches to it in the release that clears its AAA findings, which is the target) or `off`.
+import AxeBuilder from '@axe-core/playwright'
+import { expect, test } from '@playwright/test'
+import { AXE_TAGS_AA, AXE_TAGS_AAA } from './index.js'
+
+/** @param {import('axe-core').Result[]} violations */
+function describe(violations) {
+  return violations.map((v) => ({
+    rule: v.id,
+    impact: v.impact,
+    help: v.help,
+    nodes: v.nodes.slice(0, 6).map((n) => `${n.target.join(' ')} — ${n.failureSummary?.split('\n').slice(0, 3).join(' | ')}`),
+  }))
+}
+
+/**
+ * Fail on any WCAG 2.2 A/AA (or best-practice) violation. AAA findings: `aaa: 'gate'` fails on them, `'report'` (default)
+ * attaches them to the test as `aaa` annotations, `'off'` skips the AAA run.
+ * @param {import('@playwright/test').Page} page
+ * @param {{ include?: string, exclude?: string[], disableRules?: string[], aaa?: 'gate' | 'report' | 'off' }} [options]
+ */
+export async function expectAccessible(page, options = {}) {
+  const build = (/** @type {readonly string[]} */ tags) => {
+    let b = new AxeBuilder({ page }).withTags([...tags]).disableRules(options.disableRules ?? [])
+    if (options.include) b = b.include(options.include)
+    for (const e of options.exclude ?? []) b = b.exclude(e)
+    return b
+  }
+  const { violations } = await build(AXE_TAGS_AA).analyze()
+  expect(describe(violations), 'WCAG 2.2 AA violations').toEqual([])
+  if (options.aaa === 'off') return
+  const aaa = await build(AXE_TAGS_AAA).analyze()
+  if (options.aaa === 'gate') {
+    expect(describe(aaa.violations), 'WCAG AAA violations').toEqual([])
+    return
+  }
+  for (const v of describe(aaa.violations)) {
+    test.info().annotations.push({ type: 'aaa', description: `${v.rule}: ${v.help} (${v.nodes.length} node(s))` })
+  }
+}

package/src/browserslist-config.cjs

@@ -0,0 +1,21 @@
+// The workspace browser support promise, as a browserslist shared config. A repo uses it with
+//   "browserslist": ["extends @meddleware/frontend-config/browserslist-config"]
+// (browserslist resolves `@scope/pkg/browserslist-config`). It drives autoprefixer, eslint-plugin-compat,
+// stylelint-no-unsupported-browser-features and the Vite build target, so one list decides all four.
+//
+// Deliberately NOT "last 2 versions": that also selects Opera Mini, KaiOS, Baidu and QQ. Every app here is a Vue SPA and the
+// wallet apps need wallet-standard browser extensions, so none of those engines can run them; fallbacks for them would
+// cost CSS and complexity for no working user. Newer-than-the-oldest-browser features still need @supports / progressive
+// enhancement, which the compat linters enforce.
+module.exports = [
+  'last 2 Chrome versions',
+  'last 2 ChromeAndroid versions',
+  'last 2 Edge versions',
+  'last 2 Firefox versions',
+  'last 2 FirefoxAndroid versions',
+  'last 2 Safari versions',
+  'last 2 iOS versions',
+  'last 2 Samsung versions',
+  'Firefox ESR',
+  'not dead',
+]

package/src/eslint.js

@@ -0,0 +1,88 @@
+// @ts-check
+// Flat ESLint config for a Vue 3 + TypeScript app or library: Vue and TypeScript recommended rules, WAI-ARIA template linting
+// (eslint-plugin-vuejs-accessibility), browser-API compatibility against the shared browserslist (eslint-plugin-compat), and
+// optionally the Sui chain-access boundary (@meddleware/eslint-config). A repo's eslint.config.ts becomes
+//   import { vueApp } from '@meddleware/frontend-config/eslint'
+//   export default vueApp({ name: 'treasury-ui', sui: true })
+import { suiBoundary } from '@meddleware/eslint-config'
+import { defineConfigWithVueTs, vueTsConfigs } from '@vue/eslint-config-typescript'
+import { globalIgnores } from 'eslint/config'
+import pluginCompat from 'eslint-plugin-compat'
+import pluginVue from 'eslint-plugin-vue'
+import pluginA11y from 'eslint-plugin-vuejs-accessibility'
+
+/** `@meddleware/ui` components that render a native control, so the label rules see through them. */
+export const CONTROL_COMPONENTS = Object.freeze(['UiSelect', 'UiInput', 'UiTextarea'])
+/** `@meddleware/ui` components that render the `<label for>` for the control in their default slot. */
+export const LABEL_COMPONENTS = Object.freeze(['UiFormField'])
+
+/**
+ * One flat-config object. Declared structurally (rather than as ESLint's own type) because ESLint's type refers to internal
+ * packages that TypeScript cannot name in a declaration file; ESLint accepts this shape.
+ * @typedef {{ name?: string, files?: (string | string[])[], ignores?: string[], rules?: Record<string, unknown>, [key: string]: unknown }} FlatConfig
+ */
+
+const TESTS = ['**/*.{test,spec}.{ts,tsx}', 'tests/**', 'e2e/**']
+
+/**
+ * @param {object} options
+ * @param {string} options.name Prefix for the config object names (usually the repo name).
+ * @param {boolean} [options.sui] Append the Sui chain-access boundary (apps and tool libraries; not ui, tokens or sites).
+ * @param {string[]} [options.ignores] Extra global ignores (for example `docs/api/**`).
+ * @param {string[]} [options.controlComponents] Extra components that render a native form control.
+ * @param {string[]} [options.labelComponents] Extra components that render a label.
+ * @param {FlatConfig[]} [options.extra] Extra config objects, placed before the boundary.
+ * @returns {FlatConfig[]}
+ */
+export function vueApp({ name, sui = false, ignores = [], controlComponents = [], labelComponents = [], extra = [] }) {
+  return /** @type {FlatConfig[]} */ (defineConfigWithVueTs(
+    { name: `${name}/files-to-lint`, files: ['**/*.{vue,ts,mts,tsx}'] },
+
+    globalIgnores(['**/dist/**', '**/gallery-dist/**', '**/coverage/**', '**/*.d.ts', '**/test-results/**', '**/playwright-report/**', '**/.lighthouseci/**', '**/lighthouserc.cjs', ...ignores]),
+
+    ...pluginVue.configs['flat/essential'],
+    ...pluginA11y.configs['flat/recommended'],
+    vueTsConfigs.recommended,
+
+    {
+      name: `${name}/a11y-overrides`,
+      rules: {
+        // <ol role="list"> is an intentional workaround: Safari/VoiceOver drops list semantics when list-style is
+        // removed, so the explicit role stays.
+        'vuejs-accessibility/no-redundant-roles': 'off',
+        // Accept both valid label-association patterns: a label wrapping its control (nesting) or a label[for] pointing at a
+        // control[id]. UiSelect and UiInput render a native control, so a label nesting one is labelling a control.
+        'vuejs-accessibility/label-has-for': [
+          'error',
+          { required: { some: ['nesting', 'id'] }, controlComponents: [...CONTROL_COMPONENTS, ...controlComponents] },
+        ],
+        // UiFormField renders the <label for> for the control in its default slot.
+        'vuejs-accessibility/form-control-has-label': [
+          'error',
+          { labelComponents: [...LABEL_COMPONENTS, ...labelComponents] },
+        ],
+        // Underscore-prefixed args and variables are an intentional "unused" marker.
+        '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      },
+    },
+
+    {
+      // Browser-API compatibility against the shared browserslist. Source only: tests and e2e run in Node or in the test browser.
+      name: `${name}/compat`,
+      files: ['src/**/*.{vue,ts,mts,tsx,js}'],
+      ignores: TESTS,
+      ...pluginCompat.configs['flat/recommended'],
+    },
+
+    {
+      // Tests use deliberately loose typing for mocks and stubs.
+      name: `${name}/test-overrides`,
+      files: TESTS,
+      rules: { '@typescript-eslint/no-explicit-any': 'off' },
+    },
+
+    ...(/** @type {any[]} */ (extra)),
+
+    ...(sui ? suiBoundary() : []),
+  ))
+}

package/src/html-validate.js

@@ -0,0 +1,49 @@
+// @ts-check
+// html-validate over the Vue SFC templates (via html-validate-vue): element nesting and content models (no <p> inside <ul>, no
+// button inside a label), the a11y preset (alt text, labels, landmarks, heading order) and the Vue naming style. A repo's
+// .htmlvalidate.mjs becomes
+//   import { htmlValidateConfig } from '@meddleware/frontend-config/html-validate'
+//   export default htmlValidateConfig()
+// The Vue plugin is passed as an object, so it is found from THIS package however the consumer's node_modules is laid out.
+import htmlValidateVue from 'html-validate-vue'
+
+/**
+ * `@meddleware/ui` components that render a single native element, described to the validator so content models and form
+ * rules see through them (keys are lowercased tag names).
+ */
+export const UI_ELEMENTS = Object.freeze({
+  uibutton: { inherit: 'button' },
+  uitoolbarbutton: { inherit: 'button' },
+  uiselect: { inherit: 'select' },
+  uinotice: { inherit: 'p' },
+})
+
+/**
+ * @param {object} [options]
+ * @param {Record<string, unknown>} [options.elements] Extra element descriptions.
+ * @param {Record<string, unknown>} [options.rules] Rule overrides.
+ * @returns {import('html-validate').ConfigData}
+ */
+export function htmlValidateConfig({ elements = {}, rules = {} } = {}) {
+  return {
+    plugins: [/** @type {import('html-validate').Plugin} */ (/** @type {unknown} */ (htmlValidateVue))],
+    extends: ['html-validate:recommended', 'html-validate:a11y', 'html-validate-vue:recommended'],
+    elements: ['html5', ({ ...UI_ELEMENTS, ...elements })],
+    transform: { '^.*\\.vue$': 'html-validate-vue' },
+    rules: {
+      // Vue components are written in PascalCase (<UiStatusDot>, <KeepAlive>).
+      'element-case': ['error', { style: ['lowercase', 'pascalcase'] }],
+      'element-name': ['error', { pattern: '^(?:[a-z][a-z0-9\\-._]*-[a-z0-9\\-._]*|[A-Z][A-Za-z0-9]*)$' }],
+      // role="list" on styled lists is a deliberate Safari/VoiceOver workaround: WebKit drops list semantics when list-style is
+      // removed, so the explicit role must stay (matches the eslint vuejs-accessibility/no-redundant-roles override).
+      'no-redundant-role': 'off',
+      'prefer-native-element': ['error', { exclude: ['list'] }],
+      // html-validate 11 crashes in this rule (`valueMatches` on a dynamic value) for any Vue `:href="…"` binding, and nothing here links to
+      // a `tel:` URL, so the rule has nothing to check.
+      'tel-non-breaking': 'off',
+      ...rules,
+    },
+  }
+}
+
+export default htmlValidateConfig()

package/src/index.js

@@ -0,0 +1,12 @@
+// @ts-check
+// @meddleware/frontend-config — shared frontend tooling. Each concern has its own subpath export (see package.json
+// "exports"); this entry holds the constants the others agree on.
+
+/** axe tags that gate a build: WCAG 2.0, 2.1 and 2.2 level A and AA, plus axe's best practices. */
+export const AXE_TAGS_AA = Object.freeze(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice'])
+
+/** axe tags reported but never gating: WCAG AAA (enhanced contrast and so on). */
+export const AXE_TAGS_AAA = Object.freeze(['wcag2aaa'])
+
+/** Playwright projects for the browsers the support promise names (engines: Chromium, Gecko, WebKit; two mobile viewports). */
+export const BROWSER_PROJECTS = Object.freeze(['chromium', 'firefox', 'webkit', 'mobile-chrome', 'mobile-safari'])

package/src/lighthouserc.js

@@ -0,0 +1,39 @@
+// @ts-check
+// Lighthouse CI config (free, filesystem upload): accessibility must score 100; best practices and SEO are floors; performance and
+// bundle weight are warnings with budgets. Lighthouse CI loads its config with `require`, so a repo's file is a `lighthouserc.cjs`
+// (Node loads the ES module through `require`); a `lighthouserc.js` in an ES-module package is silently ignored (defaults run):
+//   const { lighthouseConfig } = require('@meddleware/frontend-config/lighthouserc')
+//   module.exports = lighthouseConfig({ port: 4181, paths: ['/', '/blockchain'] })
+
+/**
+ * @param {object} options
+ * @param {number} options.port Port `vite preview` (or `vitepress preview`) serves on.
+ * @param {string[]} [options.paths] Routes to audit.
+ * @param {string} [options.startServerCommand] Command that serves the built site (default `npx vite preview`).
+ * @param {number} [options.maxScriptKb] Warn above this much JavaScript on a route.
+ * @param {number} [options.maxStylesheetKb] Warn above this much CSS on a route.
+ */
+export function lighthouseConfig({ port, paths = ['/'], startServerCommand, maxScriptKb = 300, maxStylesheetKb = 60 }) {
+  return {
+    ci: {
+      collect: {
+        url: paths.map((p) => `http://localhost:${port}${p}`),
+        startServerCommand: startServerCommand ?? `npx vite preview --port ${port} --strictPort`,
+        startServerReadyPattern: 'Local',
+        numberOfRuns: 1,
+        settings: { chromeFlags: '--no-sandbox', onlyCategories: ['accessibility', 'best-practices', 'seo', 'performance'] },
+      },
+      assert: {
+        assertions: {
+          'categories:accessibility': ['error', { minScore: 1 }],
+          'categories:best-practices': ['error', { minScore: 0.95 }],
+          'categories:seo': ['warn', { minScore: 0.9 }],
+          'categories:performance': ['warn', { minScore: 0.9 }],
+          'resource-summary:script:size': ['warn', { maxNumericValue: maxScriptKb * 1024 }],
+          'resource-summary:stylesheet:size': ['warn', { maxNumericValue: maxStylesheetKb * 1024 }],
+        },
+      },
+      upload: { target: 'filesystem', outputDir: 'test-results/lighthouse' },
+    },
+  }
+}

package/src/look.js

@@ -0,0 +1,59 @@
+// @ts-check
+// The "looks" a page is checked in: viewport × colour mode × season. Shared by the screenshot matrix and the axe sweeps so a
+// look added here is covered by both. Seasons come from @meddleware/design-tokens (seasons.css, `data-season` on <html>).
+
+export const VIEWPORTS = Object.freeze({
+  phone: Object.freeze({ width: 390, height: 844 }),
+  tablet: Object.freeze({ width: 768, height: 1024 }),
+  desktop: Object.freeze({ width: 1280, height: 900 }),
+})
+export const THEMES = Object.freeze(['light', 'dark'])
+export const SEASONS = Object.freeze(['none', 'spring', 'summer', 'autumn', 'winter'])
+
+/** Desktop covers every theme × season; tablet and phone cover each theme with no season. */
+export function looks() {
+  /** @type {{ viewport: keyof typeof VIEWPORTS, theme: string, season: string }[]} */
+  const out = []
+  for (const viewport of /** @type {(keyof typeof VIEWPORTS)[]} */ (Object.keys(VIEWPORTS))) {
+    for (const theme of THEMES) {
+      for (const season of viewport === 'desktop' ? SEASONS : ['none']) out.push({ viewport, theme, season })
+    }
+  }
+  return out
+}
+
+/**
+ * Refuse every request that leaves localhost, so a run needs no network. Failed fetches are expected and are not page errors.
+ * @param {import('@playwright/test').Page} page
+ */
+export async function offline(page) {
+  await page.route(/^https?:\/\/(?!(localhost|127\.0\.0\.1)[:/])/, (route) => route.abort())
+}
+
+/**
+ * Put the page in a look. Uses the real colour-mode control when the page has one and is not behind a modal dialog (as a visitor would, so
+ * the control's own state matches the page); otherwise sets the attribute (galleries; VitePress, which themes with a `.dark` class).
+ * @param {import('@playwright/test').Page} page
+ * @param {string} theme `light` | `dark`
+ * @param {string} season `none` | a season name
+ */
+export async function applyLook(page, theme, season) {
+  const control = page.getByRole('button', { name: theme === 'dark' ? 'Dark' : 'Light', exact: true })
+  // An open modal dialog makes the rest of the page inert (its colour-mode control cannot be clicked), so the look is set directly then.
+  if ((await control.count()) && !(await page.locator('dialog[open]').count())) await control.first().click()
+  else {
+    await page.evaluate((t) => {
+      const root = document.documentElement
+      root.setAttribute('data-theme', t)
+      root.classList.toggle('dark', t === 'dark')
+    }, theme)
+  }
+  await page.evaluate((s) => {
+    const root = document.documentElement
+    if (s === 'none') root.removeAttribute('data-season')
+    else root.setAttribute('data-season', s)
+  }, season)
+  // Let colour transitions and the like finish, so a check or a screenshot sees the look and not a frame on the way to it.
+  await page.evaluate(() => Promise.all(document.getAnimations().map((a) => a.finished.catch(() => undefined))).then(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)))))
+  await page.waitForTimeout(150)
+}