@meddleware/frontend-config 0.0.0-stage → 0.0.2

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

package/src/playwright.js

@@ -0,0 +1,62 @@
+// @ts-check
+// Playwright config for browser tests of a BUILT app, gallery or VitePress site. A repo's playwright.config.ts becomes
+//   import { definePlaywrightConfig } from '@meddleware/frontend-config/playwright'
+//   export default definePlaywrightConfig({ port: 4281 })
+//
+// Browsers: Chromium locally (fast); all five projects in CI — Chromium, Firefox, WebKit and a Pixel 7 / iPhone 14 viewport
+// (Chromium and WebKit engines). Override with E2E_BROWSERS=chromium|all (or the `browsers` option).
+// Screenshot capture (`npm run shots`, SHOTS=1) is for looking, not asserting: screens specs only run when asked, and then alone.
+import { defineConfig, devices } from '@playwright/test'
+
+/** @typedef {'chromium' | 'all'} BrowserSet */
+
+/**
+ * @param {object} options
+ * @param {number} options.port Preview server port (unique per repo, so repos can run side by side).
+ * @param {'app' | 'gallery' | 'vitepress'} [options.kind] What is served. `app`: `npm run build` then `vite preview`.
+ *   `gallery`: `npm run build:gallery` then `vite preview --config vite.gallery.config.ts`. `vitepress`: `vitepress preview docs`
+ *   (the site must already be built, so the repo's `test:e2e` script builds first).
+ * @param {string} [options.command] Full server command; replaces the one `kind` implies.
+ * @param {BrowserSet} [options.browsers] Browser set; default from E2E_BROWSERS, else `all` in CI and `chromium` otherwise.
+ * @param {string} [options.testDir]
+ * @param {import('@playwright/test').PlaywrightTestConfig} [options.extra] Merged over the defaults.
+ */
+export function definePlaywrightConfig({ port, kind = 'app', command, browsers, testDir = './e2e', extra = {} }) {
+  const server = {
+    app: `npm run build && npx vite preview --port ${port} --strictPort`,
+    gallery: `npm run build:gallery && npx vite preview --config vite.gallery.config.ts --port ${port} --strictPort`,
+    vitepress: `npx vitepress preview docs --port ${port}`,
+  }[kind]
+  const requested = browsers ?? process.env.E2E_BROWSERS ?? (process.env.CI && !process.env.SHOTS ? 'all' : 'chromium')
+  const all = requested === 'all'
+  const projects = [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    ...(all
+      ? [
+          { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+          { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+          { name: 'mobile-chrome', use: { ...devices['Pixel 7'] } },
+          { name: 'mobile-safari', use: { ...devices['iPhone 14'] } },
+        ]
+      : []),
+  ]
+  return defineConfig({
+    testDir,
+    // A screenshot run loads only the screens specs; a normal run never loads them. (Tests are attributed to the file that calls
+    // `test()`, which for `defineShots` is shots.js, so a `playwright test e2e/screens.spec.ts` file filter would find none.)
+    ...(process.env.SHOTS ? { testMatch: '**/screens.spec.ts' } : { testIgnore: ['**/screens.spec.ts'] }),
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 1 : 0,
+    reporter: process.env.CI ? [['list'], ['html', { open: 'never' }]] : 'list',
+    use: { baseURL: `http://localhost:${port}`, viewport: { width: 1280, height: 900 }, trace: 'retain-on-failure' },
+    webServer: {
+      command: command ?? server,
+      url: `http://localhost:${port}/`,
+      reuseExistingServer: !process.env.CI,
+      timeout: 180_000,
+    },
+    projects,
+    ...extra,
+  })
+}

package/src/postcss.js

@@ -0,0 +1,7 @@
+// @ts-check
+// Autoprefixer over the CSS a build ships, targeting the repo's browserslist (which should extend
+// `@meddleware/frontend-config/browserslist-config`). A repo's postcss.config.js becomes
+//   export { default } from '@meddleware/frontend-config/postcss'
+import autoprefixer from 'autoprefixer'
+
+export default { plugins: [autoprefixer()] }

package/src/shots.js

@@ -0,0 +1,33 @@
+// @ts-check
+// Screenshot matrix for LOOKING at the UI (not assertions): one PNG per state × viewport × theme × season, written to SHOTS_OUT
+// (default test-results/shots). Excluded from `npm run test:e2e` (definePlaywrightConfig ignores screens specs unless SHOTS is
+// set); nothing is compared against a baseline (baselines drift across machines and fonts). Compare runs by eye: shoot before
+// and after a change and read both sets.
+import { test } from '@playwright/test'
+import { VIEWPORTS, applyLook, looks, offline } from './look.js'
+
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} State */
+
+/**
+ * Register one test per state × look. Call once, at the top level of an `e2e/screens.spec.ts`.
+ * @param {Record<string, State>} states
+ * @param {{ out?: string }} [options]
+ */
+export function defineShots(states, options = {}) {
+  const out = options.out ?? process.env.SHOTS_OUT ?? 'test-results/shots'
+  for (const { viewport, theme, season } of looks()) {
+    for (const [name, go] of Object.entries(states)) {
+      test(`${name} · ${viewport} · ${theme} · ${season}`, async ({ page }) => {
+        await page.setViewportSize(VIEWPORTS[viewport])
+        await page.emulateMedia({ colorScheme: /** @type {'light' | 'dark'} */ (theme), reducedMotion: 'reduce' })
+        await offline(page)
+        await go(page)
+        await applyLook(page, theme, season)
+        // chromium keeps the plain name; other browsers get a suffix so runs never overwrite each other
+        const project = test.info().project.name
+        const tag = project === 'chromium' ? '' : `.${project}`
+        await page.screenshot({ path: `${out}/${name}.${viewport}.${theme}.${season}${tag}.png`, fullPage: true })
+      })
+    }
+  }
+}

package/src/stylelint.js

@@ -0,0 +1,107 @@
+// @ts-check
+// Stylelint over CSS and the <style> blocks of Vue SFCs: the standard config tuned for a token-driven codebase, no hex colours,
+// token-only values for colour and layering, accessibility rules (@double-great/stylelint-a11y) and browser-support linting
+// against the shared browserslist (stylelint-no-unsupported-browser-features). A repo's stylelint.config.js becomes
+//   import { stylelintConfig } from '@meddleware/frontend-config/stylelint'
+//   export default stylelintConfig()
+import { fileURLToPath } from 'node:url'
+import postcssHtml from 'postcss-html'
+
+// Resolve plugins and the base config from THIS package, not the consumer's directory, so they are found however the consumer's
+// package manager lays out node_modules (stylelint otherwise resolves names relative to the consumer's config file).
+/** @param {string} name */
+const here = (name) => fileURLToPath(import.meta.resolve(name))
+
+/** Colour-bearing properties: a literal colour here bypasses the design tokens (and so the seasons). */
+const COLOUR_PROPERTIES = ['/color$/', 'fill', 'stroke', 'outline-color', 'text-decoration-color', 'caret-color', 'accent-color']
+
+/** Values that carry no colour of their own, so they are allowed where a token is expected. */
+const NEUTRAL_VALUES = ['transparent', 'inherit', 'currentColor', 'currentcolor', 'none', 'initial', 'unset', 'revert', 'auto', '0']
+
+/**
+ * @param {object} [options]
+ * @param {'error' | 'warning' | false} [options.tokens] Severity of the token-only rule. Default `error`; a repo with
+ *   literals still to fix starts at `warning` and moves to `error` in the same release as the fixes.
+ * @param {'error' | 'warning'} [options.compat] Severity of unsupported-browser-feature findings. Default `error`.
+ * @param {string[]} [options.browsers] Browsers to check against. Default: the repo's browserslist (the shared support promise).
+ * @param {Record<string, unknown>} [options.rules] Rule overrides.
+ */
+export function stylelintConfig({ tokens = 'error', compat = 'error', browsers, rules = {} } = {}) {
+  return {
+    extends: [here('stylelint-config-standard')],
+    plugins: [
+      here('stylelint-no-unsupported-browser-features'),
+      here('@double-great/stylelint-a11y'),
+      here('stylelint-declaration-strict-value'),
+    ],
+    overrides: [{ files: ['**/*.vue', '**/*.html'], customSyntax: postcssHtml }],
+    rules: {
+      // The design system leans heavily on custom properties and deliberate ordering; these standard rules are too noisy for
+      // a token-driven codebase.
+      'custom-property-empty-line-before': null,
+      'declaration-empty-line-before': null,
+      'comment-empty-line-before': null,
+      'rule-empty-line-before': null,
+      'at-rule-empty-line-before': null,
+      'no-descending-specificity': null,
+      // BEM-style class names (block__element--modifier) are intentional.
+      'selector-class-pattern': null,
+      // Some presentational SFCs use compact single-line multi-declaration rules.
+      'declaration-block-single-line-max-declarations': null,
+      // Preserve camelCase CSS keyword values (for example text-rendering: optimizeLegibility).
+      'value-keyword-case': null,
+      // Vue SFC scoped-style pseudo-classes.
+      'selector-pseudo-class-no-unknown': [true, { ignorePseudoClasses: ['deep', 'slotted', 'global'] }],
+      // Private panel vars use a leading-underscore convention (--_bg, --_text).
+      'custom-property-pattern': null,
+      // Vendor-prefixed properties are emitted by autoprefixer at build time; the hand-written -webkit-/-moz-
+      // font-smoothing pair is intentional.
+      'property-no-vendor-prefix': null,
+      'value-no-vendor-prefix': null,
+
+      // Colours come from the design tokens, never a literal.
+      'color-no-hex': true,
+
+      ...(tokens
+        ? {
+            'scale-unlimited/declaration-strict-value': [
+              [...COLOUR_PROPERTIES, 'z-index'],
+              { ignoreValues: NEUTRAL_VALUES, disableFix: true, severity: tokens },
+            ],
+          }
+        : {}),
+
+      // Browser support against the shared browserslist. Partial support is accepted: the feature degrades, it does not break.
+      // Three more degrade harmlessly and are ignored on purpose: `resize` (touch Safari has no resizable fields), non-standard
+      // `cursor` values (a pointer-device nicety), and the extended system font keywords (every use has a fallback stack).
+      'plugin/no-unsupported-browser-features': [
+        true,
+        {
+          severity: compat,
+          ignorePartialSupport: true,
+          ignore: ['css-resize', 'css3-cursors', 'extended-system-fonts'],
+          ...(browsers ? { browsers } : {}),
+        },
+      ],
+
+      // Accessibility.
+      // (`a11y/media-prefers-reduced-motion` is off: @meddleware/ui's reset applies one global reduced-motion rule to every app,
+      // so a per-rule media query is redundant noise.)
+      'a11y/media-prefers-reduced-motion': null,
+      'a11y/no-outline-none': true,
+      // (`a11y/selector-pseudo-class-focus` is off: it asks for a `:focus` twin of every `:hover`, but the reset gives every focusable
+      // element a visible `:focus-visible` ring and `a11y/no-outline-none` below stops anything removing it, so a hover-only cosmetic
+      // needs no twin.)
+      'a11y/selector-pseudo-class-focus': null,
+      'a11y/content-property-no-static-value': true,
+      'a11y/font-size-is-readable': true,
+      'a11y/no-obsolete-attribute': true,
+      'a11y/no-obsolete-element': true,
+      'a11y/no-text-align-justify': true,
+
+      ...rules,
+    },
+  }
+}
+
+export default stylelintConfig()

package/src/vite.js

@@ -0,0 +1,87 @@
+// @ts-check
+// Vite build target derived from the repo's browserslist, so the shipped JS and CSS are transformed for exactly the browsers the
+// support promise names (instead of `esnext`, or Vite's own default). In vite.config.ts:
+//   import { viteTarget } from '@meddleware/frontend-config/vite'
+//   export default defineConfig({ build: { target: viteTarget() } })
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import browserslistToEsbuild from 'browserslist-to-esbuild'
+
+/** @param {string | string[]} [queries] Browserslist queries; default: the repo's own configuration. */
+export function viteTarget(queries) {
+  return browserslistToEsbuild(queries)
+}
+
+/** Resolve a package file from the app's own directory, where `@meddleware/ui` and the tokens are installed. */
+function resolveFromApp(/** @type {string} */ specifier) {
+  return createRequire(join(process.cwd(), 'noop.js')).resolve(specifier)
+}
+
+/**
+ * The colour mode and the browser chrome, before the first paint: a Vite plugin for an app's `index.html`.
+ *
+ * - Serves `@meddleware/ui`'s `theme-init.js` at `/theme-init.js` (dev) and emits it into the build, and loads it as the first,
+ *   render-blocking script in `<head>`. It applies the saved (or default) colour mode and the season to `<html>` before anything
+ *   paints, so a page never flashes the wrong theme while its JavaScript loads. It is a same-origin file, so the CSP needs no hash
+ *   and no `'unsafe-inline'`.
+ * - Adds `<meta name="color-scheme" content="light dark">` (native controls and scrollbars follow the theme) and the browser-chrome
+ *   `theme-color` for each colour mode, from the design tokens' page background.
+ *
+ * ```ts
+ * plugins: [vue(), themeInit({ default: 'dark' })]
+ * ```
+ *
+ * @param {object} [options]
+ * @param {'light' | 'dark' | 'system'} [options.default] The mode a first visit gets (a saved choice always wins). Default `system`.
+ * @param {string} [options.scriptPath] The script to serve (default: `@meddleware/ui/theme-init.js` as installed in the app).
+ * @param {{ light: string, dark: string }} [options.colors] The `theme-color` values (default: the tokens' page backgrounds).
+ * @returns {import('vite').Plugin}
+ */
+export function themeInit({ default: mode = 'system', scriptPath, colors } = {}) {
+  const read = () => readFileSync(scriptPath ?? resolveFromApp('@meddleware/ui/theme-init.js'), 'utf8')
+  const chrome = () => {
+    if (colors) return colors
+    const { semantic } = JSON.parse(readFileSync(resolveFromApp('@meddleware/design-tokens/tokens.json'), 'utf8'))
+    return { light: semantic.light.bg, dark: semantic.dark.bg }
+  }
+  return {
+    name: 'meddleware:theme-init',
+    configureServer(server) {
+      server.middlewares.use('/theme-init.js', (_req, res) => {
+        res.setHeader('content-type', 'text/javascript')
+        res.end(read())
+      })
+    },
+    generateBundle() {
+      this.emitFile({ type: 'asset', fileName: 'theme-init.js', source: read() })
+    },
+    transformIndexHtml() {
+      const { light, dark } = chrome()
+      return [
+        { tag: 'script', attrs: { src: '/theme-init.js', 'data-default': mode }, injectTo: 'head-prepend' },
+        { tag: 'meta', attrs: { name: 'color-scheme', content: 'light dark' }, injectTo: 'head' },
+        { tag: 'meta', attrs: { name: 'theme-color', content: light, media: '(prefers-color-scheme: light)' }, injectTo: 'head' },
+        { tag: 'meta', attrs: { name: 'theme-color', content: dark, media: '(prefers-color-scheme: dark)' }, injectTo: 'head' },
+      ]
+    },
+  }
+}
+
+/**
+ * The end-to-end build mode registers a mock wallet and a stub chain client in the app (`@meddleware/wallet-adapter/testing`), which must
+ * never reach a production build. The app's entry loads it only when `import.meta.env.MODE === 'e2e' && import.meta.env.VITE_E2E === '1'`
+ * (both static, so every other build drops the block); this makes `VITE_E2E=1` outside `--mode e2e` a build error instead of a silent no-op.
+ *
+ * ```ts
+ * export default defineConfig(({ mode }) => { assertE2eOnlyInE2eMode(mode, process.env); return { … } })
+ * ```
+ *
+ * @param {string} mode Vite's mode.
+ * @param {Record<string, string | undefined>} env The environment (default: the process's).
+ */
+export function assertE2eOnlyInE2eMode(mode, env = process.env) {
+  if (env.VITE_E2E && mode !== 'e2e') {
+    throw new Error(`VITE_E2E is set but the build mode is "${mode}": the end-to-end build is \`vite build --mode e2e\`, and nothing else may include the test wallet.`)
+  }
+}

package/src/vitest.js

@@ -0,0 +1,52 @@
+// @ts-check
+// Vitest settings for a repo whose code imports the Meddleware UI libraries. Those packages ship ES modules that import their own `.css`
+// files (each component brings its CSS), and Node cannot import a `.css` file. Vitest runs `node_modules` dependencies through Node by
+// default, so the import fails: the libraries have to go through Vite instead, which also gives them the SAME copy of Vue as the code
+// under test (a second copy breaks reactivity across the boundary, which is why tests used to mock `@meddleware/ui`).
+//
+//   // vitest.config.ts (and, in a jsdom test that renders a dialog: beforeAll(installDialogShim))
+//   import { inlineMeddleware } from '@meddleware/frontend-config/vitest'
+//   export default defineConfig({
+//     plugins: [vue()],
+//     resolve: { dedupe: ['vue', '@vue/test-utils'] },
+//     test: { server: { deps: { inline: inlineMeddleware } } },
+//   })
+
+/**
+ * Packages to process through Vite in tests: the ones that import CSS or `.vue` files. Vitest matches these against the module's resolved
+ * file path (`…/node_modules/@meddleware/ui/dist/…`), not the package name, so the patterns match the path.
+ */
+export const inlineMeddleware = [/[\\/]@meddleware[\\/](ui|wallet-adapter|walrus-storage-kit|design-tokens)[\\/]/]
+
+/**
+ * jsdom does not implement `<dialog>` modality (`showModal`, `close`, `returnValue`). This minimal shim models the parts `UiDialog` relies on:
+ * the `open` attribute, `returnValue`, and a `close` event on closing. Call it once (`beforeAll(installDialogShim)`) in a jsdom test that
+ * renders a dialog; the browser's real behaviour (top layer, inert background) is checked by the Playwright suites, not jsdom.
+ */
+export function installDialogShim() {
+  if (typeof HTMLDialogElement === 'undefined') return // a node-environment test file: there is no DOM to patch
+  const proto = /** @type {HTMLDialogElement & { _rv?: string }} */ (HTMLDialogElement.prototype)
+  if (typeof proto.showModal === 'function') return
+  if (!('returnValue' in proto)) {
+    Object.defineProperty(proto, 'returnValue', {
+      configurable: true,
+      get: /** @this {{ _rv?: string }} */ function () {
+        return this._rv ?? ''
+      },
+      set: /** @this {{ _rv?: string }} */ function (/** @type {string} */ v) {
+        this._rv = v
+      },
+    })
+  }
+  proto.showModal = /** @this {HTMLDialogElement} */ function () {
+    this.returnValue = ''
+    this.setAttribute('open', '')
+  }
+  proto.show = proto.showModal
+  proto.close = /** @this {HTMLDialogElement} */ function (returnValue) {
+    if (!this.hasAttribute('open')) return
+    if (returnValue !== undefined) this.returnValue = returnValue
+    this.removeAttribute('open')
+    this.dispatchEvent(new Event('close'))
+  }
+}

package/src/wallet.js

@@ -0,0 +1,38 @@
+// @ts-check
+// Playwright side of the shared mock wallet (`@meddleware/wallet-adapter/testing`, registered by an app's e2e build): connect it
+// through the app's own wallet dialog, or give it a signer that lives in Node, so a key never enters the page.
+
+/** The address the mock wallet connects with (`MOCK_ADDRESS` in wallet-adapter's testing module). */
+export const E2E_ADDRESS = `0x${'a'.repeat(64)}`
+
+/**
+ * Connect the mock wallet as a visitor would: open the wallet dialog, choose the wallet, and wait for the dialog to close.
+ * @param {import('@playwright/test').Page} page
+ * @param {{ wallet?: string, trigger?: string | RegExp }} [options] The wallet's name in the picker; the name of the button that opens the dialog.
+ */
+export async function connectMockWallet(page, { wallet = 'Test Wallet', trigger = 'Connect wallet' } = {}) {
+  await page.getByRole('button', { name: trigger }).first().click()
+  const dialog = page.getByRole('dialog')
+  await dialog.getByRole('button', { name: wallet }).click()
+  await dialog.waitFor({ state: 'hidden' })
+}
+
+/**
+ * @typedef {object} NodeSigner
+ * @property {(transactionJson: string, chain: string) => Promise<{ bytes: string, signature: string }>} [signTransaction]
+ *   Build and sign a transaction (`Transaction.from(json)`); resolves base64 bytes and signature.
+ * @property {(message: string) => Promise<{ signature: string }>} [signPersonalMessage] Sign a personal message (base64 bytes).
+ */
+
+/**
+ * Let the page's mock wallet sign in this Node process. Call it before `page.goto`: the functions are exposed to every page load, and
+ * `installE2eWallet` uses them when they exist.
+ * @param {import('@playwright/test').Page} page
+ * @param {NodeSigner} signer
+ * @param {{ address?: string }} [options] The address the wallet connects with: the signer's own, so the transaction's sender and its signature agree.
+ */
+export async function exposeSigner(page, signer, { address } = {}) {
+  if (address) await page.addInitScript((a) => Object.assign(window, { __e2eWalletAddress: a }), address)
+  if (signer.signTransaction) await page.exposeFunction('__e2eSignTransaction', signer.signTransaction)
+  if (signer.signPersonalMessage) await page.exposeFunction('__e2eSignPersonalMessage', signer.signPersonalMessage)
+}