@meddleware/frontend-config 0.0.0-rename.0 → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-10-31
+
+### Added
+
+- First release. Shared browserslist config, ESLint (`vueApp`), Stylelint, html-validate, PostCSS, Vite target, Playwright config,
+  axe helper (WCAG 2.2 AA gate, AAA reported), screenshot matrix and Lighthouse CI config, extracted from the per-repo copies in
+  the frontend repos.

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 MeddleWare
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @meddleware/frontend-config
+
+Shared frontend tooling for MeddleWare apps and libraries, so a repo's config files are one-liners and every repo is held to the
+same accessibility and browser-support bar.
+
+| Subpath | What it gives you |
+| --- | --- |
+| `/browserslist-config` | The browser support promise (below), as a browserslist shared config. |
+| `/eslint` | `vueApp({ name, sui?, ignores?, controlComponents?, labelComponents?, extra? })` — Vue + TypeScript, `eslint-plugin-vuejs-accessibility`, `eslint-plugin-compat`, optionally the Sui boundary from `@meddleware/eslint-config`. |
+| `/stylelint` | `stylelintConfig({ tokens?, compat?, browsers?, rules? })` — standard config, no hex, token-only colour and `z-index`, `@double-great/stylelint-a11y`, `stylelint-no-unsupported-browser-features`. |
+| `/html-validate` | `htmlValidateConfig({ elements?, rules? })` — recommended + `html-validate:a11y` + Vue, with `@meddleware/ui` components described as the native element they render. |
+| `/postcss` | Autoprefixer for the repo's browserslist. |
+| `/vite` | `viteTarget()` — Vite `build.target` derived from the browserslist; `themeInit({ default })` — a Vite plugin that loads ui's `theme-init.js` first in `<head>` (the saved or default colour mode and the season applied before first paint, no inline script, no CSP hash) and adds `color-scheme` and the browser-chrome `theme-color` from the tokens. |
+| `/playwright` | `definePlaywrightConfig({ port, kind?, command?, browsers?, extra? })`. |
+| `/axe` | `expectAccessible(page, options)` — WCAG 2.2 AA gate; AAA as `aaa: 'gate'`, `'report'` or `'off'`. |
+| `/look` | `looks()`, `applyLook(page, theme, season)`, `offline(page)`, `VIEWPORTS`, `THEMES`, `SEASONS` — the viewport × colour mode × season matrix. |
+| `/shots` | `defineShots(states)` — one screenshot per state × look, for looking at the UI. |
+| `/a11y` | `defineA11ySuite(states, { aaa })` — the sweep every app runs, one call: each state in every colour mode × season at WCAG 2.2 AA and AAA, a 320 px reflow, 200% text size, forced colours, reduced motion and a keyboard pass. `expectNoHorizontalScroll`, `expectNoRunningAnimations` and `expectKeyboardFocusVisible` are exported on their own. |
+| `/vitest` | `inlineMeddleware` — the packages a test must process through Vite (they import `.css`/`.vue`), which also gives them the test's single copy of Vue; `installDialogShim()` — jsdom's missing `<dialog>` modality. |
+| `/lighthouserc` | `lighthouseConfig({ port, paths?, … })` — Lighthouse CI (accessibility must score 100). |
+
+## Use
+
+```jsonc
+// package.json
+"browserslist": ["extends @meddleware/frontend-config/browserslist-config"]
+```
+
+```ts
+// eslint.config.ts
+import { vueApp } from '@meddleware/frontend-config/eslint'
+export default vueApp({ name: 'treasury-ui', sui: true })
+```
+
+```js
+// stylelint.config.js
+import { stylelintConfig } from '@meddleware/frontend-config/stylelint'
+export default stylelintConfig()
+```
+
+```js
+// .htmlvalidate.mjs
+import { htmlValidateConfig } from '@meddleware/frontend-config/html-validate'
+export default htmlValidateConfig()
+```
+
+```js
+// postcss.config.js
+export { default } from '@meddleware/frontend-config/postcss'
+```
+
+```ts
+// playwright.config.ts
+import { definePlaywrightConfig } from '@meddleware/frontend-config/playwright'
+export default definePlaywrightConfig({ port: 4281 })
+```
+
+```ts
+// e2e/screens.spec.ts — run with `SHOTS=1 playwright test` (a screenshot run loads only the screens specs)
+import { defineShots } from '@meddleware/frontend-config/shots'
+defineShots({ overview: async (page) => { await page.goto('/') } })
+```
+
+```ts
+// e2e/a11y.spec.ts
+import { test } from '@playwright/test'
+import { expectAccessible } from '@meddleware/frontend-config/axe'
+import { applyLook, looks } from '@meddleware/frontend-config/look'
+for (const { theme, season } of looks()) {
+  test(`home is accessible · ${theme} · ${season}`, async ({ page }) => {
+    await page.goto('/')
+    await applyLook(page, theme, season)
+    await expectAccessible(page)
+  })
+}
+```
+
+## The support promise
+
+`last 2` of Chrome, Chrome for Android, Edge, Firefox, Firefox for Android, Safari, iOS Safari and Samsung Internet, plus Firefox
+ESR, minus dead browsers. It is deliberately **not** `last 2 versions`, which also selects Opera Mini, KaiOS, Baidu and QQ: every
+app is a Vue SPA and the wallet apps need browser extensions, so those engines cannot run them, and fallbacks for them would cost
+CSS and complexity for no working user. Features newer than the oldest browser in the list still need `@supports` or progressive
+enhancement; the compat linters enforce that.
+
+## Accessibility bar
+
+WCAG 2.2 AA is always a hard gate: `expectAccessible` fails on any `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa` or axe
+best-practice violation. WCAG AAA (`wcag2aaa`, including enhanced contrast) is the target: `aaa: 'gate'` fails the run on it,
+`'report'` (the default, while a repo still has findings) attaches it to the test as `aaa` annotations, `'off'` skips it. A repo
+switches to `gate` in the release that clears its AAA findings. `@meddleware/design-tokens` already guarantees 7:1 for every
+text and label role in every theme × season, so remaining AAA findings are local colours and sizes, not the palette.
+
+## Browsers in tests
+
+`definePlaywrightConfig` runs Chromium locally and five projects in CI: Chromium, Firefox, WebKit, a Pixel 7 and an iPhone 14
+viewport. `E2E_BROWSERS=all` runs all five locally (install them first: `npx playwright install chromium firefox webkit`).
+`SHOTS=1` keeps a screenshot run on Chromium and runs only `screens.spec.ts` (which a normal run ignores): use `SHOTS=1 playwright test` with no file filter, since the tests are attributed to `shots.js`.
+
+## Mock wallet in Playwright (`/wallet`)
+
+```ts
+import { connectMockWallet, exposeSigner, E2E_ADDRESS } from '@meddleware/frontend-config/wallet'
+await exposeSigner(page, { signTransaction, signPersonalMessage }) // optional: sign in Node (call before page.goto)
+await page.goto('/')
+await connectMockWallet(page) // the app's wallet dialog → "Test Wallet"
+```
+
+The page side is `@meddleware/wallet-adapter/testing` (`installE2eWallet`), registered by an app's e2e build.
+
+## Peers
+
+`eslint` ^10 (required for `/eslint`), and optional peers per subpath: `stylelint` ^17, `html-validate` ^11, `postcss` ^8,
+`@playwright/test` ~1.64. The lint plugins are dependencies of this package and are resolved from it, so a consumer needs none of
+them.

package/dist/a11y.d.ts

@@ -0,0 +1,28 @@
+/** @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 function expectNoHorizontalScroll(page: import("@playwright/test").Page): Promise<void>;
+/**
+ * No animation is running: with `prefers-reduced-motion: reduce` the page holds still (WCAG 2.3.3).
+ * @param {import('@playwright/test').Page} page
+ */
+export function expectNoRunningAnimations(page: import("@playwright/test").Page): Promise<void>;
+/**
+ * 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 function expectKeyboardFocusVisible(page: import("@playwright/test").Page, { maxStops }?: {
+    maxStops?: number;
+}): Promise<void>;
+/**
+ * @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: Record<string, State>, { aaa }?: {
+    aaa?: "gate" | "report" | "off";
+}): void;
+export type State = (page: import("@playwright/test").Page) => Promise<void>;

package/dist/axe.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 function expectAccessible(page: import("@playwright/test").Page, options?: {
+    include?: string;
+    exclude?: string[];
+    disableRules?: string[];
+    aaa?: "gate" | "report" | "off";
+}): Promise<void>;

package/dist/eslint.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @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, ignores, controlComponents, labelComponents, extra }: {
+    name: string;
+    sui?: boolean | undefined;
+    ignores?: string[] | undefined;
+    controlComponents?: string[] | undefined;
+    labelComponents?: string[] | undefined;
+    extra?: FlatConfig[] | undefined;
+}): FlatConfig[];
+/** `@meddleware/ui` components that render a native control, so the label rules see through them. */
+export const CONTROL_COMPONENTS: readonly string[];
+/** `@meddleware/ui` components that render the `<label for>` for the control in their default slot. */
+export const LABEL_COMPONENTS: readonly string[];
+/**
+ * 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.
+ */
+export type FlatConfig = {
+    name?: string;
+    files?: (string | string[])[];
+    ignores?: string[];
+    rules?: Record<string, unknown>;
+    [key: string]: unknown;
+};

package/dist/html-validate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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 }?: {
+    elements?: Record<string, unknown> | undefined;
+    rules?: Record<string, unknown> | undefined;
+}): import("html-validate").ConfigData;
+/**
+ * `@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: Readonly<{
+    uibutton: {
+        inherit: string;
+    };
+    uitoolbarbutton: {
+        inherit: string;
+    };
+    uiselect: {
+        inherit: string;
+    };
+    uinotice: {
+        inherit: string;
+    };
+}>;
+declare const _default: import("html-validate").ConfigData;
+export default _default;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** 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: readonly string[];
+/** axe tags reported but never gating: WCAG AAA (enhanced contrast and so on). */
+export const AXE_TAGS_AAA: readonly string[];
+/** Playwright projects for the browsers the support promise names (engines: Chromium, Gecko, WebKit; two mobile viewports). */
+export const BROWSER_PROJECTS: readonly string[];

package/dist/lighthouserc.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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, maxStylesheetKb }: {
+    port: number;
+    paths?: string[] | undefined;
+    startServerCommand?: string | undefined;
+    maxScriptKb?: number | undefined;
+    maxStylesheetKb?: number | undefined;
+}): {
+    ci: {
+        collect: {
+            url: string[];
+            startServerCommand: string;
+            startServerReadyPattern: string;
+            numberOfRuns: number;
+            settings: {
+                chromeFlags: string;
+                onlyCategories: string[];
+            };
+        };
+        assert: {
+            assertions: {
+                'categories:accessibility': (string | {
+                    minScore: number;
+                })[];
+                'categories:best-practices': (string | {
+                    minScore: number;
+                })[];
+                'categories:seo': (string | {
+                    minScore: number;
+                })[];
+                'categories:performance': (string | {
+                    minScore: number;
+                })[];
+                'resource-summary:script:size': (string | {
+                    maxNumericValue: number;
+                })[];
+                'resource-summary:stylesheet:size': (string | {
+                    maxNumericValue: number;
+                })[];
+            };
+        };
+        upload: {
+            target: string;
+            outputDir: string;
+        };
+    };
+};

package/dist/look.d.ts

@@ -0,0 +1,35 @@
+/** Desktop covers every theme × season; tablet and phone cover each theme with no season. */
+export function looks(): {
+    viewport: keyof typeof VIEWPORTS;
+    theme: string;
+    season: string;
+}[];
+/**
+ * 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 function offline(page: import("@playwright/test").Page): Promise<void>;
+/**
+ * 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 function applyLook(page: import("@playwright/test").Page, theme: string, season: string): Promise<void>;
+export const VIEWPORTS: Readonly<{
+    phone: Readonly<{
+        width: 390;
+        height: 844;
+    }>;
+    tablet: Readonly<{
+        width: 768;
+        height: 1024;
+    }>;
+    desktop: Readonly<{
+        width: 1280;
+        height: 900;
+    }>;
+}>;
+export const THEMES: readonly string[];
+export const SEASONS: readonly string[];

package/dist/playwright.d.ts

@@ -0,0 +1,21 @@
+/** @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, command, browsers, testDir, extra }: {
+    port: number;
+    kind?: "app" | "gallery" | "vitepress" | undefined;
+    command?: string | undefined;
+    browsers?: BrowserSet | undefined;
+    testDir?: string | undefined;
+    extra?: import("playwright/test").PlaywrightTestConfig<{}, {}> | undefined;
+}): import("playwright/test").PlaywrightTestConfig<{}, {}>;
+export type BrowserSet = "chromium" | "all";

package/dist/postcss.d.ts

@@ -0,0 +1,5 @@
+declare namespace _default {
+    let plugins: (import("postcss").Plugin & autoprefixer.ExportedAPI)[];
+}
+export default _default;
+import autoprefixer from 'autoprefixer';

package/dist/shots.d.ts

@@ -0,0 +1,10 @@
+/** @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: Record<string, State>, options?: {
+    out?: string;
+}): void;
+export type State = (page: import("@playwright/test").Page) => Promise<void>;

package/dist/stylelint.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @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, compat, browsers, rules }?: {
+    tokens?: false | "error" | "warning" | undefined;
+    compat?: "error" | "warning" | undefined;
+    browsers?: string[] | undefined;
+    rules?: Record<string, unknown> | undefined;
+}): {
+    extends: string[];
+    plugins: string[];
+    overrides: {
+        files: string[];
+        customSyntax: ((options?: Record<string, any>) => import("postcss").Syntax) & import("postcss").Syntax<import("postcss").Document | import("postcss").Root>;
+    }[];
+    rules: {
+        'plugin/no-unsupported-browser-features': (boolean | {
+            browsers?: string[] | undefined;
+            severity: "error" | "warning";
+            ignorePartialSupport: boolean;
+            ignore: string[];
+        })[];
+        'a11y/media-prefers-reduced-motion': null;
+        'a11y/no-outline-none': boolean;
+        'a11y/selector-pseudo-class-focus': null;
+        'a11y/content-property-no-static-value': boolean;
+        'a11y/font-size-is-readable': boolean;
+        'a11y/no-obsolete-attribute': boolean;
+        'a11y/no-obsolete-element': boolean;
+        'a11y/no-text-align-justify': boolean;
+        'scale-unlimited/declaration-strict-value'?: (string[] | {
+            ignoreValues: string[];
+            disableFix: boolean;
+            severity: "error" | "warning";
+        })[] | undefined;
+        '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;
+        'selector-class-pattern': null;
+        'declaration-block-single-line-max-declarations': null;
+        'value-keyword-case': null;
+        'selector-pseudo-class-no-unknown': (boolean | {
+            ignorePseudoClasses: string[];
+        })[];
+        'custom-property-pattern': null;
+        'property-no-vendor-prefix': null;
+        'value-no-vendor-prefix': null;
+        'color-no-hex': boolean;
+    };
+};
+declare namespace _default {
+    let _extends: string[];
+    export { _extends as extends };
+    export let plugins: string[];
+    export let overrides: {
+        files: string[];
+        customSyntax: ((options?: Record<string, any>) => import("postcss").Syntax) & import("postcss").Syntax<import("postcss").Document | import("postcss").Root>;
+    }[];
+    export let rules: {
+        'plugin/no-unsupported-browser-features': (boolean | {
+            browsers?: string[] | undefined;
+            severity: "error" | "warning";
+            ignorePartialSupport: boolean;
+            ignore: string[];
+        })[];
+        'a11y/media-prefers-reduced-motion': null;
+        'a11y/no-outline-none': boolean;
+        'a11y/selector-pseudo-class-focus': null;
+        'a11y/content-property-no-static-value': boolean;
+        'a11y/font-size-is-readable': boolean;
+        'a11y/no-obsolete-attribute': boolean;
+        'a11y/no-obsolete-element': boolean;
+        'a11y/no-text-align-justify': boolean;
+        'scale-unlimited/declaration-strict-value'?: (string[] | {
+            ignoreValues: string[];
+            disableFix: boolean;
+            severity: "error" | "warning";
+        })[] | undefined;
+        '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;
+        'selector-class-pattern': null;
+        'declaration-block-single-line-max-declarations': null;
+        'value-keyword-case': null;
+        'selector-pseudo-class-no-unknown': (boolean | {
+            ignorePseudoClasses: string[];
+        })[];
+        'custom-property-pattern': null;
+        'property-no-vendor-prefix': null;
+        'value-no-vendor-prefix': null;
+        'color-no-hex': boolean;
+    };
+}
+export default _default;

package/dist/vite.d.ts

@@ -0,0 +1,43 @@
+/** @param {string | string[]} [queries] Browserslist queries; default: the repo's own configuration. */
+export function viteTarget(queries?: string | string[]): string[];
+/**
+ * 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, scriptPath, colors }?: {
+    default?: "light" | "dark" | "system" | undefined;
+    scriptPath?: string | undefined;
+    colors?: {
+        light: string;
+        dark: string;
+    } | undefined;
+}): import("vite").Plugin;
+/**
+ * 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: string, env?: Record<string, string | undefined>): void;

package/dist/vitest.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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(): void;
+/**
+ * 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: RegExp[];

package/dist/wallet.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 function connectMockWallet(page: import("@playwright/test").Page, { wallet, trigger }?: {
+    wallet?: string;
+    trigger?: string | RegExp;
+}): Promise<void>;
+/**
+ * @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 function exposeSigner(page: import("@playwright/test").Page, signer: NodeSigner, { address }?: {
+    address?: string;
+}): Promise<void>;
+/** The address the mock wallet connects with (`MOCK_ADDRESS` in wallet-adapter's testing module). */
+export const E2E_ADDRESS: string;
+export type NodeSigner = {
+    /**
+     * Build and sign a transaction (`Transaction.from(json)`); resolves base64 bytes and signature.
+     */
+    signTransaction?: ((transactionJson: string, chain: string) => Promise<{
+        bytes: string;
+        signature: string;
+    }>) | undefined;
+    /**
+     * Sign a personal message (base64 bytes).
+     */
+    signPersonalMessage?: ((message: string) => Promise<{
+        signature: string;
+    }>) | undefined;
+};