@meddleware/frontend-config 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.3] - 2026-11-07
+
+### Added
+
+- `mw-audit-gate`, `mw-third-party-licenses` and `mw-check-csp-inline`: the dependency-audit gate, the licence bundle and the inline-script
+  CSP check that every app repository carried as its own copy of a script.
+- `/csp`: `buildCsp`, `cspForProfile` and six named profiles that reproduce, byte for byte, the policies the app images served.
+- `meddlewareApp` (`/vite`), `vueTestConfig` (`/vitest`) and `tsconfig/vue-app.json`: the Vite, Vitest and TypeScript configuration that eleven
+  apps each repeated.
+- `mw-sync --check|--write` and `templates/`: the files that cannot be shared by reference stay identical across repositories, and the
+  Dockerfile's `ARG CSP` is held equal to the repository's profile.
+
+## [0.0.2] - 2026-11-01
+
+### Added
+
+- `check-prod-bundle` (and `scanBundle` at `/bundle`): the production-artefact scan for the e2e harness, moved here from token-issuance-ui so
+  every wallet app runs the same one (the mock-wallet hooks; `--also` / `--also-regex` add an app's own stand-in marker).
+
+- `expectKeyboardFocusVisible` (and so `defineA11ySuite`) now also fails a stop that is entirely hidden behind sticky or fixed content when it
+  takes focus (WCAG 2.4.11 focus not obscured; axe has no rule for it), going forward and then backwards through the tab order; the message names the covering element, and the pointer is parked first so a stale hover tooltip cannot cover the walk; each stop is judged after the scroll has settled (WebKit animates the scroll that focus causes).
+
+- `defineA11ySuite` takes `noKeyboard: [state names]` for states with nothing to operate (they skip the keyboard pass; every other state must
+  have a stop). `expectKeyboardFocusVisible` no longer reports "no keyboard stops" for a page reached with focus on its last control.
+
+### Changed
+
+- The keyboard walk follows element identity (a repeated link label no longer ends it early), stops at 300 stops and fails when it is capped (`maxStops` raises the cap); its test limit scales with the cap (WebKit needs about half a minute for a page of a hundred stops).
+- `SECURITY.md` is part of the published files.
+
 ## [0.0.1] - 2026-10-31
 
 ### Added

package/README.md

@@ -10,14 +10,22 @@ same accessibility and browser-support bar.
 | `/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. |
+| `/vite` | `viteTarget()` — Vite `build.target` derived from the browserslist; `meddlewareApp({ plugins, theme?, wallet?, config? })` — the whole Vite configuration of a tool app (target, theme-init, e2e guard, wallet-adapter kept out of pre-bundling); `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. |
+| `/vitest` | `vueTestConfig({ plugins, test? })` — the whole Vitest configuration of a Vue repository (jsdom, `tests/**/*.test.ts`, one copy of Vue, the UI packages processed through Vite); `inlineMeddleware` — those packages on their own; `installDialogShim()` — jsdom's missing `<dialog>` modality. |
+| `/bundle` + `check-prod-bundle` | `scanBundle(dist, { also })` and the `check-prod-bundle [dist] [--also TEXT]... [--also-regex PATTERN]...` command: fails when the e2e harness (the mock-wallet hooks, or an app's own stand-in marker) is found in a production build. Run it after the production build in CI and in the Dockerfile. |
+| `/wallet` | `connectMockWallet(page)`, `exposeSigner(page, signer)`, `E2E_ADDRESS` — the Playwright side of the mock wallet. |
 | `/lighthouserc` | `lighthouseConfig({ port, paths?, … })` — Lighthouse CI (accessibility must score 100). |
+| `/tsconfig/vue-app.json` | The compiler options of a Vue app (`"extends": "@meddleware/frontend-config/tsconfig/vue-app.json"`); the repository keeps only its `include`. |
+| `/csp` | `buildCsp(options)`, `cspForProfile(name, current?)`, `PROFILES`, `scriptHashesOf(csp)` — the Content-Security-Policy every app image serves, as six named profiles (`static`, `static-strict`, `console`, `chain`, `chain-wasm`, `docs`), so the policy is written once. |
+| `mw-sync` | `mw-sync --check` / `--write` in a repository root: the files every frontend repository copies (dependabot.yml, .dockerignore, postcss/stylelint configs, the Lighthouse allowlist) equal this package's `templates/`, and the Dockerfile's `ARG CSP` equals its profile. Declared in package.json: `"meddleware": { "kind": "app", "csp": "chain-wasm", "lhci": true }`. |
+| `mw-audit-gate` | CI dependency gate: `npm audit` at high/critical minus the dated, reasoned entries of `.github/audit-allowlist.json` (an entry with no reason or an expired date fails). |
+| `mw-third-party-licenses` | Writes `dist/THIRD_PARTY_LICENSES` from the lockfile's production packages and their installed licence texts; `--check` fails when none can be written. |
+| `mw-check-csp-inline` | `mw-check-csp-inline <policy or @Dockerfile> [dist]`: every inline script in the built pages is allowed by a `sha256` source in the policy, and the policy never allows `'unsafe-inline'` scripts. |
 
 ## Use
 
@@ -108,6 +116,14 @@ 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.
 
+## Keeping the e2e harness out of production
+
+An app's end-to-end build (`vite build --mode e2e`) registers a mock wallet and a stub chain. Three things keep that out of every
+other build: the app's entry loads it only when `import.meta.env.MODE === 'e2e' && import.meta.env.VITE_E2E === '1'` (both static, so
+the block is removed); `assertE2eOnlyInE2eMode(mode)` from `/vite` fails a build with `VITE_E2E` set in any other mode; and
+`check-prod-bundle dist` (`/bundle`) scans the built files for the harness's hooks and fails if any is present. An app whose e2e build also
+swaps a module for a stand-in adds a marker of that stand-in: `check-prod-bundle dist --also 'a string only the stand-in contains'` (`--also-regex` takes a pattern).
+
 ## Peers
 
 `eslint` ^10 (required for `/eslint`), and optional peers per subpath: `stylelint` ^17, `html-validate` ^11, `postcss` ^8,

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Scope
+
+This policy covers `@meddleware/frontend-config`: lint, build and test configuration for MeddleWare frontends. It runs only in a
+consumer's development and CI processes (ESLint, Stylelint, html-validate, PostCSS, Vite, Playwright, Lighthouse); it ships nothing
+to end users and makes no network requests of its own.
+
+It does not cover a consuming application, or the tools and plugins it configures.
+
+## What it guarantees
+
+The rules are a **guard rail**: they catch accidents and shortcuts, not deliberate evasion (a `stylelint-disable` or
+`eslint-disable` comment defeats them). Accessibility checks are automated and cover only what axe and the linters can detect;
+they are not a substitute for manual testing with assistive technology.
+
+## Supply chain
+
+Releases are published from this repository's `npm-publish.yml` with npm trusted publishing (OIDC and provenance); tokens are not
+used. A compromised release could weaken the lint, accessibility and browser-support gates in every consumer, or run code in their
+build, so report anything that suggests tampering.
+
+## Supported versions
+
+Only the latest published npm version receives fixes.
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities. Use GitHub's private vulnerability reporting for this
+repository, or email dev@meddleware.co.uk.

package/dist/a11y.d.ts

@@ -1,4 +1,5 @@
-/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} State */
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} Open */
+/** @typedef {Open | { open: Open, disableRules?: string[] }} State A state is how to open it, or that and the axe rules that do not apply to it (a lone dialog has no landmarks). */
 /**
  * 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
@@ -10,7 +11,9 @@ export function expectNoHorizontalScroll(page: import("@playwright/test").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).
+ * Tab through the page: every stop is visible, shows a focus indicator (an outline or a shadow) and is not hidden behind sticky or fixed
+ * content, and the tab order ends (no trap). Then Shift+Tab back through it, so a stop reached from below is checked as well (browsers
+ * scroll a stop into view from the side it arrives from, so a sticky header or a bottom bar can cover it in only one direction).
  * @param {import('@playwright/test').Page} page
  * @param {{ maxStops?: number }} [options]
  */
@@ -19,10 +22,20 @@ export function expectKeyboardFocusVisible(page: import("@playwright/test").Page
 }): 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).
+ * @param {{ aaa?: 'gate' | 'report' | 'off', noKeyboard?: string[], maxStops?: number }} [options] How WCAG AAA findings are treated (default `report`; a repo
+ *   moves to `gate` in the release that clears them); `noKeyboard` names states with nothing to operate (a static summary, a modal that
+ *   only reports progress), which skip the keyboard pass: every other state must have at least one keyboard stop; `maxStops` (default 300) caps the keyboard walk, and a page with more stops fails rather than passing unchecked.
  */
-export function defineA11ySuite(states: Record<string, State>, { aaa }?: {
+export function defineA11ySuite(states: Record<string, State>, { aaa, noKeyboard, maxStops }?: {
     aaa?: "gate" | "report" | "off";
+    noKeyboard?: string[];
+    maxStops?: number;
 }): void;
-export type State = (page: import("@playwright/test").Page) => Promise<void>;
+export type Open = (page: import("@playwright/test").Page) => Promise<void>;
+/**
+ * A state is how to open it, or that and the axe rules that do not apply to it (a lone dialog has no landmarks).
+ */
+export type State = Open | {
+    open: Open;
+    disableRules?: string[];
+};

package/dist/audit-gate.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bundle.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Scan the built files under `dist` for the harness.
+ * @param {string} dist The build output directory.
+ * @param {{ also?: (string | RegExp)[] }} [options] Extra markers: an app's own stand-in (a string is matched literally).
+ * @returns {{ scanned: number, hits: string[] }}
+ * @throws When `dist` cannot be read.
+ */
+export function scanBundle(dist: string, { also }?: {
+    also?: (string | RegExp)[];
+}): {
+    scanned: number;
+    hits: string[];
+};
+/**
+ * What the shared harness (`@meddleware/wallet-adapter/testing` `installE2eWallet`, `@meddleware/frontend-config/wallet`) leaves in a
+ * bundle that includes it: the hooks it puts on `window`. Property names survive minification.
+ */
+export const E2E_MARKERS: readonly {
+    name: string;
+    re: RegExp;
+}[];

package/dist/check-csp-inline.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/check-prod-bundle.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/csp.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @param {CspOptions} options
+ * @returns {string}
+ */
+export function buildCsp(options?: CspOptions): string;
+/** The `'sha256-…'` hashes in a policy's script-src (kept when a profile such as `docs` is rebuilt). */
+export function scriptHashesOf(csp: string): string[];
+/** @param {string} name @param {string} [current] the policy now in the Dockerfile (its script hashes are kept) */
+export function cspForProfile(name: string, current?: string): string;
+/**
+ * @typedef {object} CspOptions
+ * @property {boolean} [wasm] allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+ * @property {boolean} [chain] chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+ * @property {boolean} [worker] allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+ * @property {boolean} [strict] `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+ * @property {'self' | 'none'} [frameAncestors] who may frame the page (default `'self'`)
+ * @property {string[]} [scriptHashes] `'sha256-…'` sources for the inline scripts a static-site generator emits
+ */
+/** @type {Record<string, CspOptions>} */
+export const PROFILES: Record<string, CspOptions>;
+export type CspOptions = {
+    /**
+     * allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+     */
+    wasm?: boolean | undefined;
+    /**
+     * chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+     */
+    chain?: boolean | undefined;
+    /**
+     * allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+     */
+    worker?: boolean | undefined;
+    /**
+     * `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+     */
+    strict?: boolean | undefined;
+    /**
+     * who may frame the page (default `'self'`)
+     */
+    frameAncestors?: "none" | "self" | undefined;
+    /**
+     * `'sha256-…'` sources for the inline scripts a static-site generator emits
+     */
+    scriptHashes?: string[] | undefined;
+};

package/dist/sync.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @param {string} root repository root
+ * @param {{ write?: boolean }} [options]
+ * @returns {{ file: string, ok: boolean, note: string }[]}
+ */
+export function sync(root: string, options?: {
+    write?: boolean;
+}): {
+    file: string;
+    ok: boolean;
+    note: string;
+}[];

package/dist/third-party-licenses.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/vite.d.ts

@@ -41,3 +41,28 @@ export function themeInit({ default: mode, scriptPath, colors }?: {
  * @param {Record<string, string | undefined>} env The environment (default: the process's).
  */
 export function assertE2eOnlyInE2eMode(mode: string, env?: Record<string, string | undefined>): void;
+/**
+ * The Vite configuration every MeddleWare tool app shares: the browserslist build target, the colour mode and season before first paint
+ * ({@link themeInit}), the e2e-build guard ({@link assertE2eOnlyInE2eMode}), and `@meddleware/wallet-adapter` excluded from dependency
+ * pre-bundling. The wallet adapter ships TS and `.vue` source and holds the shared wallet singleton; pre-bundling would put its TS in
+ * `.vite/deps` while its `.vue` files (which esbuild cannot bundle) are served raw and import the raw module, so dev would run two
+ * singletons and the guard and the app would see different connection state.
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default meddlewareApp({ plugins: [vue()] })
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The app's plugins (`vue()` …); `themeInit` is added after them.
+ * @param {'light' | 'dark' | 'system'} [options.theme] The mode a first visit gets (default `dark`, the brand default).
+ * @param {boolean} [options.wallet] The app uses `@meddleware/wallet-adapter` (default true): keep it out of pre-bundling.
+ * @param {import('vite').UserConfig} [options.config] Anything else (`base`, `build.rollupOptions`, `server` …); `build` is merged.
+ * @returns {import('vite').UserConfigFnObject}
+ */
+export function meddlewareApp({ plugins, theme, wallet, config }: {
+    plugins: import("vite").PluginOption[];
+    theme?: "light" | "dark" | "system" | undefined;
+    wallet?: boolean | undefined;
+    config?: import("vite").UserConfig | undefined;
+}): import("vite").UserConfigFnObject;

package/dist/vitest.d.ts

@@ -4,6 +4,26 @@
  * renders a dialog; the browser's real behaviour (top layer, inert background) is checked by the Playwright suites, not jsdom.
  */
 export function installDialogShim(): void;
+/**
+ * The Vitest configuration of a MeddleWare Vue repository: jsdom, `tests/**\/*.test.ts`, a single copy of Vue for the code under test and
+ * `@vue/test-utils`, and the UI packages processed through Vite ({@link inlineMeddleware}).
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default defineConfig(vueTestConfig({ plugins: [vue()] }))
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The Vue plugin (and any other the tests need).
+ * @param {import('vitest/config').TestUserConfig} [options.test] Overrides merged into `test` (`include`, `setupFiles`, `environment` …).
+ * @returns {import('vitest/config').ViteUserConfig & { test: import('vitest/config').TestUserConfig }}
+ */
+export function vueTestConfig({ plugins, test }: {
+    plugins: import("vite").PluginOption[];
+    test?: import("vitest/node").TestUserConfig | undefined;
+}): import("vitest/config").ViteUserConfig & {
+    test: import("vitest/config").TestUserConfig;
+};
 /**
  * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/frontend-config",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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",
@@ -22,7 +22,10 @@
   "files": [
     "src",
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "templates",
+    "tsconfig"
   ],
   "exports": {
     ".": {
@@ -81,7 +84,16 @@
     "./wallet": {
       "types": "./dist/wallet.d.ts",
       "default": "./src/wallet.js"
-    }
+    },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "default": "./src/bundle.js"
+    },
+    "./csp": {
+      "types": "./dist/csp.d.ts",
+      "default": "./src/csp.js"
+    },
+    "./tsconfig/vue-app.json": "./tsconfig/vue-app.json"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
@@ -157,5 +169,12 @@
     "last 2 Samsung versions",
     "Firefox ESR",
     "not dead"
-  ]
+  ],
+  "bin": {
+    "check-prod-bundle": "./src/check-prod-bundle.js",
+    "mw-audit-gate": "./src/audit-gate.js",
+    "mw-third-party-licenses": "./src/third-party-licenses.js",
+    "mw-check-csp-inline": "./src/check-csp-inline.js",
+    "mw-sync": "./src/sync.js"
+  }
 }

package/src/a11y.js

@@ -9,7 +9,8 @@ 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 */
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} Open */
+/** @typedef {Open | { open: Open, disableRules?: string[] }} State A state is how to open it, or that and the axe rules that do not apply to it (a lone dialog has no landmarks). */
 
 /**
  * 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).
@@ -31,54 +32,154 @@ export async function expectNoRunningAnimations(page) {
 }
 
 /**
- * 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).
+ * What the focused element looks like: visible, shows an indicator, and is not hidden behind other content. Runs in the page.
+ * @param {import('@playwright/test').Page} page
+ */
+async function probeFocus(page) {
+  // A browser may animate the scroll that brings the focused control into view (WebKit does, and `scroll-behavior: smooth` makes the
+  // others): judge where it comes to rest, not where it passes through.
+  await page.evaluate(
+    () =>
+      new Promise((done) => {
+        let last = [scrollX, scrollY]
+        let still = 0
+        let frames = 0
+        const tick = () => {
+          const now = [scrollX, scrollY]
+          if (now[0] === last[0] && now[1] === last[1]) still++
+          else {
+            still = 0
+            last = now
+          }
+          if (still >= 3 || ++frames > 60) done(undefined)
+          else requestAnimationFrame(tick)
+        }
+        requestAnimationFrame(tick)
+      }),
+  )
+  return page.evaluate(() => {
+    const el = document.activeElement
+    // Once Tab has left the last control, Firefox hands focus to the browser's own chrome: the document no longer has focus, yet
+    // `activeElement` still names the control it left. That is the end of the tab order, not a stop.
+    if (!el || el === document.body || !document.hasFocus()) 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'
+    })
+    // WCAG 2.4.11 (focus not obscured): once focus has scrolled the stop into view, it is not entirely hidden behind sticky or fixed
+    // content. Five points are sampled (the centre and four inset corners of the part inside the viewport); hidden means all are covered.
+    const x0 = Math.max(box.left, 0)
+    const x1 = Math.min(box.right, innerWidth)
+    const y0 = Math.max(box.top, 0)
+    const y1 = Math.min(box.bottom, innerHeight)
+    const inView = x1 > x0 && y1 > y0
+    const samples = [[0.5, 0.5], [0.1, 0.1], [0.9, 0.1], [0.1, 0.9], [0.9, 0.9]]
+    /** @type {Element | null} */
+    let cover = null
+    const obscured = inView && samples.every(([fx, fy]) => {
+      const top = document.elementFromPoint(x0 + (x1 - x0) * /** @type {number} */ (fx), y0 + (y1 - y0) * /** @type {number} */ (fy))
+      cover = top
+      return !!top && !target.contains(top) && !top.contains(target)
+    })
+    const coveredBy = obscured && cover ? `${/** @type {Element} */ (cover).tagName.toLowerCase()}${/** @type {Element} */ (cover).id ? `#${/** @type {Element} */ (cover).id}` : ''}${/** @type {Element} */ (cover).className && typeof (/** @type {Element} */ (cover).className) === 'string' ? `.${String(/** @type {Element} */ (cover).className).trim().split(/\s+/).slice(0, 2).join('.')}` : ''}` : ''
+    // The walk is complete when focus comes back to an element it has already stopped on: elements are compared by identity (two links can
+    // share a label, as the same link often appears in a menu and in a sidebar), through a set the walk resets at its start.
+    const seen = /** @type {{ __mwSeen?: WeakSet<Element> }} */ (/** @type {unknown} */ (window)).__mwSeen
+    const repeat = !!seen && seen.has(el)
+    seen?.add(el)
+    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, obscured, coveredBy, repeat }
+  })
+}
+
+/**
+ * Put the keyboard at the start of the document: nothing focused, the pointer out of the way, and the point sequential navigation continues
+ * from at the top (a button that was just clicked is where the next Tab would otherwise start).
+ * @param {import('@playwright/test').Page} page
+ */
+async function startAtTop(page) {
+  // The pointer where an earlier click left it would keep a hover tooltip open over the controls the keyboard walk is about to reach.
+  await page.mouse.move(0, 0)
+  await page.evaluate(() => {
+    ;/** @type {{ __mwSeen?: WeakSet<Element> }} */ (/** @type {unknown} */ (window)).__mwSeen = new WeakSet()
+    const active = document.activeElement
+    if (active instanceof HTMLElement && active !== document.body) active.blur()
+    const selection = getSelection()
+    if (!selection) return
+    selection.removeAllRanges()
+    const range = document.createRange()
+    range.setStart(document.body, 0)
+    range.collapse(true)
+    selection.addRange(range)
+  })
+}
+
+/**
+ * Tab through the page: every stop is visible, shows a focus indicator (an outline or a shadow) and is not hidden behind sticky or fixed
+ * content, and the tab order ends (no trap). Then Shift+Tab back through it, so a stop reached from below is checked as well (browsers
+ * scroll a stop into view from the side it arrives from, so a sticky header or a bottom bar can cover it in only one direction).
  * @param {import('@playwright/test').Page} page
  * @param {{ maxStops?: number }} [options]
  */
-export async function expectKeyboardFocusVisible(page, { maxStops = 120 } = {}) {
+export async function expectKeyboardFocusVisible(page, { maxStops = 300 } = {}) {
   /** @type {string[]} */
   const problems = []
   let stops = 0
-  const seen = new Set()
+  let wrapped = false
+  let finished = false
+  await startAtTop(page)
   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 stop = await probeFocus(page)
+    if (!stop) {
+      // Focus left the document: the cycle is complete. But a page that is reached with focus already on its last control (a button just
+      // clicked) leaves on the first Tab, before any stop was seen: that press only wraps round to the start.
+      if (stops === 0 && !wrapped) {
+        wrapped = true
+        continue
       }
-      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)
+      finished = true
+      break
+    }
+    if (stop.repeat) {
+      finished = true // back at a stop already seen: a focus cycle (a modal dialog holds focus inside itself), so the walk is complete
+      break
+    }
     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`)
+    if (stop.obscured) problems.push(`${stop.label} is hidden behind ${stop.coveredBy || 'other content'} when focused (WCAG 2.4.11: add scroll-padding for sticky chrome)`)
   }
   expect(stops, 'the page has no keyboard stops').toBeGreaterThan(0)
-  expect(problems).toEqual([])
+  // A walk that hit its cap has not seen the rest of the page: say so instead of passing it.
+  if (!finished) problems.push(`the tab order has more than ${maxStops} stops, so the rest of the page was not checked (raise maxStops for this state)`)
+  for (let i = 0; i < Math.min(stops, maxStops); i++) {
+    await page.keyboard.press('Shift+Tab')
+    const stop = await probeFocus(page)
+    if (!stop) break
+    if (stop.obscured) problems.push(`${stop.label} is hidden behind ${stop.coveredBy || 'other content'} when reached backwards (WCAG 2.4.11: add scroll-padding for sticky chrome)`)
+  }
+  expect([...new Set(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).
+ * @param {{ aaa?: 'gate' | 'report' | 'off', noKeyboard?: string[], maxStops?: number }} [options] How WCAG AAA findings are treated (default `report`; a repo
+ *   moves to `gate` in the release that clears them); `noKeyboard` names states with nothing to operate (a static summary, a modal that
+ *   only reports progress), which skip the keyboard pass: every other state must have at least one keyboard stop; `maxStops` (default 300) caps the keyboard walk, and a page with more stops fails rather than passing unchecked.
  */
-export function defineA11ySuite(states, { aaa = 'report' } = {}) {
-  for (const [name, open] of Object.entries(states)) {
+export function defineA11ySuite(states, { aaa = 'report', noKeyboard = [], maxStops } = {}) {
+  for (const [name, state] of Object.entries(states)) {
+    const open = typeof state === 'function' ? state : state.open
+    const disableRules = typeof state === 'function' ? [] : (state.disableRules ?? [])
     test.describe(name, () => {
       test.beforeEach(async ({ page }) => {
         await offline(page)
@@ -89,7 +190,7 @@ export function defineA11ySuite(states, { aaa = 'report' } = {}) {
           await page.emulateMedia({ colorScheme: /** @type {'light' | 'dark'} */ (theme), reducedMotion: 'reduce' })
           await open(page)
           await applyLook(page, theme, season)
-          await expectAccessible(page, { aaa })
+          await expectAccessible(page, { aaa, disableRules })
         })
       }
 
@@ -97,21 +198,21 @@ export function defineA11ySuite(states, { aaa = 'report' } = {}) {
         await page.setViewportSize({ width: 320, height: 640 })
         await open(page)
         await expectNoHorizontalScroll(page)
-        await expectAccessible(page, { aaa: 'off' })
+        await expectAccessible(page, { aaa: 'off', disableRules })
       })
 
       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' })
+        await expectAccessible(page, { aaa: 'off', disableRules })
       })
 
       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'] })
+        await expectAccessible(page, { aaa: 'off', disableRules: [...disableRules, 'color-contrast'] })
       })
 
       test('holds still with reduced motion', async ({ page }) => {
@@ -120,10 +221,15 @@ export function defineA11ySuite(states, { aaa = 'report' } = {}) {
         await expectNoRunningAnimations(page)
       })
 
-      test('can be used from the keyboard, and shows where focus is', async ({ page }) => {
-        await open(page)
-        await expectKeyboardFocusVisible(page)
-      })
+      if (!noKeyboard.includes(name)) {
+        test('can be used from the keyboard, and shows where focus is', async ({ page }) => {
+          // The walk probes every stop twice (forward, then backward), and WebKit animates the scroll each one causes: a page of a
+          // hundred stops takes about half a minute there, longer than the default 30 s. Scale the limit with the cap.
+          test.setTimeout(Math.max(60_000, (maxStops || 300) * 400))
+          await open(page)
+          await expectKeyboardFocusVisible(page, maxStops ? { maxStops } : {})
+        })
+      }
     })
   }
 }

package/src/audit-gate.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// mw-audit-gate — CI dependency gate: `npm audit` at high/critical, minus advisories listed in
+// .github/audit-allowlist.json. Each entry needs a reason and an expiry date, so an
+// accepted advisory is re-reviewed instead of being ignored forever.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+
+const ALLOWLIST = '.github/audit-allowlist.json'
+const LEVELS = new Set(['high', 'critical'])
+const GHSA = /^GHSA(-[23456789cfghjmpqrvwx]{4}){3}$/
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+let failed = false
+/** @param {string} msg */
+const fail = (msg) => {
+  console.log(`::error::${msg}`)
+  failed = true
+}
+
+const entries = existsSync(ALLOWLIST) ? JSON.parse(readFileSync(ALLOWLIST, 'utf8')) : []
+if (!Array.isArray(entries)) throw new Error(`${ALLOWLIST} must be an array`)
+const today = new Date().toISOString().slice(0, 10)
+const allowed = new Map()
+for (const e of entries) {
+  if (!GHSA.test(e?.id) || typeof e.reason !== 'string' || !e.reason || !DATE.test(e.expires)) {
+    fail(`invalid allowlist entry ${JSON.stringify(e)} (needs id, reason, expires YYYY-MM-DD)`)
+  } else if (e.expires < today) {
+    fail(`allowlist entry ${e.id} expired on ${e.expires}; re-review it`)
+  } else {
+    allowed.set(e.id, e)
+  }
+}
+
+let raw
+try {
+  raw = execFileSync('npm', ['audit', '--json'], { encoding: 'utf8', maxBuffer: 64 << 20 })
+} catch (err) {
+  // npm audit exits non-zero whenever it reports anything; the JSON is still on stdout.
+  raw = /** @type {{ stdout: string }} */ (err).stdout
+}
+const report = JSON.parse(raw)
+if (report.error) throw new Error(`npm audit failed: ${JSON.stringify(report.error)}`)
+
+const found = new Map()
+for (const vuln of Object.values(report.vulnerabilities ?? {})) {
+  for (const via of vuln.via) {
+    if (typeof via === 'object' && LEVELS.has(via.severity)) {
+      found.set(via.url.split('/').pop(), via)
+    }
+  }
+}
+
+for (const [id, via] of found) {
+  const entry = allowed.get(id)
+  if (entry) {
+    console.log(`::warning::${id} (${via.name}, ${via.severity}) allowed until ${entry.expires}: ${entry.reason}`)
+  } else {
+    fail(`${id} (${via.name}, ${via.severity}): ${via.title}`)
+  }
+}
+for (const id of allowed.keys()) {
+  if (!found.has(id)) console.log(`::warning::allowlist entry ${id} no longer matches an advisory; remove it`)
+}
+
+const open = [...found.keys()].filter((id) => !allowed.has(id)).length
+console.log(`${found.size} high/critical advisories, ${open} not allowlisted`)
+process.exit(failed ? 1 : 0)

package/src/bundle.js

@@ -0,0 +1,57 @@
+// @ts-check
+// Production-artefact scan for the end-to-end harness. An app's e2e build (`vite build --mode e2e`) registers a mock wallet, a stub chain
+// and sometimes a stand-in for a module that needs a live service; none of it may reach a production build. The app's entry loads the
+// harness only when the mode is `e2e` and `VITE_E2E` is `1` (both statically replaced), so every other build drops the block. This scan
+// proves it on the built files instead of trusting that: it fails when a hook or marker is found in `dist/`.
+//
+//   // package.json: "check:bundle": "check-prod-bundle dist"
+//   // CI, after the production build; and in the Dockerfile, right after `npm run build`
+//   // an app with its own stand-in adds a marker: "check-prod-bundle dist --also 'e2e session key'"
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/**
+ * What the shared harness (`@meddleware/wallet-adapter/testing` `installE2eWallet`, `@meddleware/frontend-config/wallet`) leaves in a
+ * bundle that includes it: the hooks it puts on `window`. Property names survive minification.
+ */
+export const E2E_MARKERS = Object.freeze([
+  { name: '__registerMockWallet hook', re: /__registerMockWallet/ },
+  { name: '__unregisterMockWallet hook', re: /__unregisterMockWallet/ },
+  { name: '__e2eAddress hook', re: /__e2eAddress/ },
+  { name: '__e2eWalletAddress hook', re: /__e2eWalletAddress/ },
+  { name: '__e2eSignTransaction hook', re: /__e2eSignTransaction/ },
+  { name: '__e2eSignPersonalMessage hook', re: /__e2eSignPersonalMessage/ },
+  { name: '__getSuiClient hook', re: /__getSuiClient/ },
+])
+
+/** @param {string} dir @returns {Generator<string>} */
+function* files(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) yield* files(path)
+    else if (/\.(m?js|html)$/.test(name)) yield path
+  }
+}
+
+/**
+ * Scan the built files under `dist` for the harness.
+ * @param {string} dist The build output directory.
+ * @param {{ also?: (string | RegExp)[] }} [options] Extra markers: an app's own stand-in (a string is matched literally).
+ * @returns {{ scanned: number, hits: string[] }}
+ * @throws When `dist` cannot be read.
+ */
+export function scanBundle(dist, { also = [] } = {}) {
+  const markers = [
+    ...E2E_MARKERS,
+    ...also.map((m) => ({ name: `marker ${String(m)}`, re: typeof m === 'string' ? new RegExp(m.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) : m })),
+  ]
+  let scanned = 0
+  /** @type {string[]} */
+  const hits = []
+  for (const file of files(dist)) {
+    scanned++
+    const text = readFileSync(file, 'utf8')
+    for (const { name, re } of markers) if (re.test(text)) hits.push(`${relative(dist, file)}: ${name}`)
+  }
+  return { scanned, hits }
+}

package/src/check-csp-inline.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Fails the build when dist/ contains an inline <script> that the CSP's script-src does not allow, or when script-src allows
+// 'unsafe-inline'. VitePress inlines a couple of small scripts (the appearance/theme bootstrap and the page-hash map); the image serves a
+// hash-based CSP, so a VitePress upgrade (or a change of the `appearance` option) that changes them must update the Dockerfile's CSP ARG
+// in the same change — this check makes that impossible to miss, in CI as well as in the image build.
+//
+// Usage: mw-check-csp-inline "<csp>" [distDir]
+//        mw-check-csp-inline @Dockerfile [distDir]   (reads the Dockerfile's `ARG CSP="…"` default)
+import { createHash } from 'node:crypto'
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const [source, dist = 'dist'] = process.argv.slice(2)
+if (!source) {
+  console.error('usage: mw-check-csp-inline "<csp>"|@Dockerfile [distDir]')
+  process.exit(2)
+}
+
+let csp = source
+if (source.startsWith('@')) {
+  const m = readFileSync(source.slice(1), 'utf8').match(/^ARG CSP="([^"]*)"/m)
+  if (!m?.[1]) {
+    console.error(`CSP check: no 'ARG CSP="…"' default found in ${source.slice(1)}`)
+    process.exit(2)
+  }
+  csp = m[1]
+}
+
+const scriptSrc = (csp.split(';').map((d) => d.trim()).find((d) => d.startsWith('script-src ')) ?? '').split(/\s+/)
+if (scriptSrc.includes("'unsafe-inline'")) {
+  console.error("CSP check: script-src allows 'unsafe-inline'; the page must not.")
+  process.exit(1)
+}
+const allowed = new Set(scriptSrc.filter((t) => t.startsWith("'sha256-")).map((t) => t.slice(1, -1)))
+
+/**
+ * @param {string} dir
+ * @returns {Generator<string>}
+ */
+function* htmlFiles(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) yield* htmlFiles(p)
+    else if (name.endsWith('.html')) yield p
+  }
+}
+
+const missing = new Map()
+let files = 0
+for (const file of htmlFiles(dist)) {
+  files++
+  const html = readFileSync(file, 'utf8')
+  for (const m of html.matchAll(/<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/g)) {
+    if (!m[1].trim()) continue
+    const hash = 'sha256-' + createHash('sha256').update(m[1]).digest('base64')
+    if (!allowed.has(hash)) missing.set(hash, file)
+  }
+}
+if (files === 0) {
+  console.error(`CSP check: no HTML file found in ${dist}; build first.`)
+  process.exit(2)
+}
+if (missing.size) {
+  console.error(`CSP check: ${missing.size} inline script(s) not allowed by script-src:`)
+  for (const [hash, file] of missing) console.error(`  '${hash}'  (first seen in ${file})`)
+  process.exit(1)
+}
+console.log(`CSP check: every inline script in ${files} HTML file(s) is allowed by script-src.`)

package/src/check-prod-bundle.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// @ts-check
+// CLI for `scanBundle`: `check-prod-bundle [dist] [--also TEXT]... [--also-regex PATTERN]...` (text is matched literally). Exit 1 when the harness is found, when `dist` is missing or when it
+// holds no .js/.html file (a build that has not run must not pass).
+import { scanBundle } from './bundle.js'
+
+const args = process.argv.slice(2)
+/** @type {(string | RegExp)[]} */
+const also = []
+/** @type {string[]} */
+const rest = []
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--also' || args[i] === '--also-regex') {
+    const flag = args[i]
+    const marker = args[++i]
+    if (!marker) {
+      console.error(`check-prod-bundle: ${flag} needs a marker`)
+      process.exit(2)
+    }
+    try {
+      also.push(flag === '--also' ? marker : new RegExp(marker))
+    } catch {
+      console.error(`check-prod-bundle: ${marker} is not a valid pattern`)
+      process.exit(2)
+    }
+  } else rest.push(/** @type {string} */ (args[i]))
+}
+const dist = rest[0] ?? 'dist'
+
+let result
+try {
+  result = scanBundle(dist, { also })
+} catch (e) {
+  console.error(`check-prod-bundle: cannot read ${dist}/ (${/** @type {Error} */ (e).message}) — build first.`)
+  process.exit(1)
+}
+if (result.scanned === 0) {
+  console.error(`check-prod-bundle: no .js/.html files under ${dist}/ — build first.`)
+  process.exit(1)
+}
+if (result.hits.length > 0) {
+  console.error(`check-prod-bundle: the e2e harness is in the production bundle:\n  ${result.hits.join('\n  ')}`)
+  process.exit(1)
+}
+console.log(`check-prod-bundle: ${result.scanned} files clean (no e2e hooks${also.length ? ` or the ${also.length} extra marker(s)` : ''}).`)

package/src/csp.js

@@ -0,0 +1,67 @@
+// @ts-check
+// The Content-Security-Policy of a MeddleWare static site, built from a named profile. Every frontend image serves one (the Dockerfile's `ARG CSP`,
+// handed to static-server): twelve hand-copied strings drifted in small ways, so the profiles live here and `mw-sync` checks each Dockerfile against its
+// profile. A policy has no 'unsafe-inline' for scripts (`mw-check-csp-inline` fails the build on an inline script that is not allowed by hash).
+
+/**
+ * @typedef {object} CspOptions
+ * @property {boolean} [wasm] allow WebAssembly (`'wasm-unsafe-eval'`): the Walrus and Move-bytecode clients
+ * @property {boolean} [chain] chain-facing app: https images, https connections (RPC, relay, aggregator and key-server hosts are partly configured), blob workers
+ * @property {boolean} [worker] allow `worker-src 'self' blob:` without the rest of `chain` (VitePress sites)
+ * @property {boolean} [strict] `base-uri` and `form-action` are `'none'` (a page with no forms and no `<base>`)
+ * @property {'self' | 'none'} [frameAncestors] who may frame the page (default `'self'`)
+ * @property {string[]} [scriptHashes] `'sha256-…'` sources for the inline scripts a static-site generator emits
+ */
+
+/** @type {Record<string, CspOptions>} */
+export const PROFILES = {
+  /** Same-origin only: the landing page. */
+  static: {},
+  /** Same-origin only, no forms and no `<base>`: the status page and the public roadmap. */
+  'static-strict': { strict: true },
+  /** An operator console: same-origin only and never framed. */
+  console: { frameAncestors: 'none' },
+  /** A chain-facing tool: https connections and images, blob workers. */
+  chain: { chain: true },
+  /** A chain-facing tool that runs WebAssembly (Walrus, Move bytecode). */
+  'chain-wasm': { chain: true, wasm: true },
+  /** A VitePress site: same-origin connections, https images, blob workers, inline scripts allowed by hash (the hashes are kept from the current policy). */
+  docs: { worker: true },
+}
+
+/**
+ * @param {CspOptions} options
+ * @returns {string}
+ */
+export function buildCsp(options = {}) {
+  const { wasm = false, chain = false, worker = false, strict = false, frameAncestors = 'self', scriptHashes = [] } = options
+  const script = ["'self'", ...(wasm ? ["'wasm-unsafe-eval'"] : []), ...scriptHashes.map((h) => `'${h.replace(/^'|'$/g, '')}'`)]
+  const richImages = chain || worker
+  const directives = [
+    ["default-src", "'self'"],
+    ['script-src', script.join(' ')],
+    ['style-src', "'self' 'unsafe-inline'"],
+    ['img-src', richImages ? "'self' data: blob: https:" : "'self' data:"],
+    ['font-src', "'self' data:"],
+    ['connect-src', chain ? "'self' https:" : "'self'"],
+    ...(chain || worker ? [['worker-src', "'self' blob:"]] : []),
+    ['object-src', "'none'"],
+    ['base-uri', strict ? "'none'" : "'self'"],
+    ['form-action', strict ? "'none'" : "'self'"],
+    ['frame-ancestors', `'${frameAncestors}'`],
+  ]
+  return [...directives.map(([d, v]) => `${d} ${v}`), 'upgrade-insecure-requests'].join('; ')
+}
+
+/** The `'sha256-…'` hashes in a policy's script-src (kept when a profile such as `docs` is rebuilt). */
+export function scriptHashesOf(/** @type {string} */ csp) {
+  const src = csp.split(';').map((d) => d.trim()).find((d) => d.startsWith('script-src ')) ?? ''
+  return src.split(/\s+/).filter((t) => t.startsWith("'sha256-")).map((t) => t.slice(1, -1))
+}
+
+/** @param {string} name @param {string} [current] the policy now in the Dockerfile (its script hashes are kept) */
+export function cspForProfile(name, current = '') {
+  const profile = PROFILES[name]
+  if (!profile) throw new Error(`unknown CSP profile "${name}" (known: ${Object.keys(PROFILES).join(', ')})`)
+  return buildCsp({ ...profile, ...(name === 'docs' ? { scriptHashes: scriptHashesOf(current) } : {}) })
+}

package/src/sync.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// @ts-check
+// mw-sync — keep the files that every MeddleWare frontend repository copies from this package identical to the package's templates, and the
+// Dockerfile's Content-Security-Policy equal to its named profile. Run in a repository root:
+//
+//   mw-sync --check    fail (exit 1) when a file differs; print which and how to fix
+//   mw-sync --write    overwrite the files with the templates / the profile's policy
+//
+// The repository declares what it is in package.json:
+//   "meddleware": { "kind": "app", "csp": "chain-wasm", "lhci": true }
+//   kind  "app"  → .github/dependabot.yml, .dockerignore, postcss.config.js, stylelint.config.js are the templates
+//   csp   a profile of ./csp.js → the Dockerfile's `ARG CSP="…"` is that profile's policy (`docs` keeps the script hashes already there)
+//   lhci  true   → .github/audit-allowlist.json is the template (the dated allowlist for the Lighthouse CI tool chain; one expiry, reviewed together)
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cspForProfile } from './csp.js'
+
+const templates = join(dirname(fileURLToPath(import.meta.url)), '..', 'templates')
+const tpl = (/** @type {string} */ name) => readFileSync(join(templates, name), 'utf8')
+
+/**
+ * @param {string} root repository root
+ * @param {{ write?: boolean }} [options]
+ * @returns {{ file: string, ok: boolean, note: string }[]}
+ */
+export function sync(root, options = {}) {
+  const pkgPath = join(root, 'package.json')
+  const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : {}
+  const cfg = pkg.meddleware ?? {}
+  /** @type {{ file: string, ok: boolean, note: string }[]} */
+  const out = []
+  /** @param {string} file @param {string} want */
+  const expectFile = (file, want) => {
+    const p = join(root, file)
+    const have = existsSync(p) ? readFileSync(p, 'utf8') : null
+    if (have === want) return out.push({ file, ok: true, note: 'matches the template' })
+    if (options.write) {
+      mkdirSync(dirname(p), { recursive: true })
+      writeFileSync(p, want)
+      return out.push({ file, ok: true, note: have === null ? 'created' : 'rewritten' })
+    }
+    out.push({ file, ok: false, note: have === null ? 'missing (mw-sync --write creates it)' : 'differs from the template (mw-sync --write restores it)' })
+  }
+  if (cfg.kind === 'app') {
+    expectFile('.github/dependabot.yml', tpl('dependabot.app.yml'))
+    expectFile('.dockerignore', tpl('dockerignore'))
+    expectFile('postcss.config.js', tpl('postcss.config.js'))
+    expectFile('stylelint.config.js', tpl('stylelint.config.js'))
+  }
+  if (cfg.lhci === true) expectFile('.github/audit-allowlist.json', tpl('audit-allowlist.lhci.json'))
+  if (cfg.csp) {
+    const df = join(root, 'Dockerfile')
+    const text = existsSync(df) ? readFileSync(df, 'utf8') : ''
+    const m = text.match(/^ARG CSP="([^"]*)"/m)
+    if (!m) out.push({ file: 'Dockerfile', ok: false, note: `no 'ARG CSP="…"' default found (profile ${cfg.csp})` })
+    else {
+      const want = cspForProfile(cfg.csp, m[1])
+      if (m[1] === want) out.push({ file: 'Dockerfile', ok: true, note: `CSP equals the "${cfg.csp}" profile` })
+      else if (options.write) {
+        writeFileSync(df, text.replace(/^ARG CSP="[^"]*"/m, () => `ARG CSP="${want}"`))
+        out.push({ file: 'Dockerfile', ok: true, note: `CSP rewritten to the "${cfg.csp}" profile` })
+      } else out.push({ file: 'Dockerfile', ok: false, note: `CSP differs from the "${cfg.csp}" profile:\n    have ${m[1]}\n    want ${want}` })
+    }
+  }
+  if (out.length === 0) out.push({ file: 'package.json', ok: false, note: 'no "meddleware" section: nothing to check (add kind / csp / lhci)' })
+  return out
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const args = process.argv.slice(2)
+  const write = args.includes('--write')
+  if (!write && !args.includes('--check')) {
+    console.error('usage: mw-sync --check | --write')
+    process.exit(2)
+  }
+  const results = sync(process.cwd(), { write })
+  for (const r of results) console.log(`${r.ok ? 'ok  ' : 'FAIL'} ${r.file}: ${r.note}`)
+  process.exit(results.every((r) => r.ok) ? 0 : 1)
+}

package/src/third-party-licenses.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Writes dist/THIRD_PARTY_LICENSES: the licence and NOTICE texts of every production dependency in
+// package-lock.json. The site ships a bundle, so the packages' own files do not travel with it;
+// Apache-2.0 (§4), MIT and BSD all require the notice to accompany a redistribution. The file is served
+// with the site (/THIRD_PARTY_LICENSES) and read by licence audits.
+//
+//   mw-third-party-licenses            write the file
+//   mw-third-party-licenses --check    also fail when the file would be empty
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+// The project root is the directory the command runs in (an app's npm script), not this package.
+const root = process.cwd()
+const lock = JSON.parse(readFileSync(join(root, 'package-lock.json'), 'utf8'))
+const check = process.argv.includes('--check')
+const LICENSE_FILE = /^(licen[cs]e|notice|copying|unlicense)(\.|$|-)/i
+
+const out = []
+const missing = []
+const apacheMissing = []
+/** @param {any} pkg */
+const declared = (pkg) => (typeof pkg.license === 'string' ? pkg.license : JSON.stringify(pkg.license ?? pkg.licenses ?? 'unknown'))
+/** @param {any} pkg */
+const holder = (pkg) =>
+  [pkg.author && (typeof pkg.author === 'string' ? pkg.author : pkg.author.name), pkg.repository && (typeof pkg.repository === 'string' ? pkg.repository : pkg.repository.url)]
+    .filter(Boolean)
+    .join(' · ')
+const names = Object.keys(lock.packages)
+  .filter((p) => p.startsWith('node_modules/') && !lock.packages[p].dev && !lock.packages[p].optional)
+  .sort()
+for (const p of names) {
+  const dir = join(root, p)
+  if (!existsSync(dir)) continue
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  const files = readdirSync(dir).filter((f) => LICENSE_FILE.test(f)).sort()
+  out.push(`${'='.repeat(78)}\n${pkg.name}@${pkg.version}  (${declared(pkg)})\n${'='.repeat(78)}`)
+  if (files.length === 0) {
+    missing.push(`${pkg.name}@${pkg.version}`)
+    if (/Apache-2\.0/.test(declared(pkg))) apacheMissing.push(`${pkg.name}@${pkg.version}`)
+  }
+  for (const f of files) out.push(`--- ${f} ---\n${readFileSync(join(dir, f), 'utf8').trim()}\n`)
+  if (files.length === 0) {
+    const apache = /Apache-2\.0/.test(declared(pkg))
+    out.push(`(the package ships no licence file; declared licence: ${declared(pkg)}${holder(pkg) ? `; ${holder(pkg)}` : ''}${apache ? '; the Apache License 2.0 text follows at the end of this file' : ''})\n`)
+  }
+}
+// Apache-2.0 §4(a) asks that a recipient gets a copy of the License. A package that declares it but ships no
+// file is covered by the canonical text, taken from any installed package that carries it.
+if (apacheMissing.length > 0) {
+  let text = null
+  for (const p of Object.keys(lock.packages).filter((k) => k.startsWith('node_modules/'))) {
+    const dir = join(root, p)
+    if (!existsSync(dir)) continue
+    for (const f of readdirSync(dir).filter((x) => LICENSE_FILE.test(x))) {
+      const t = readFileSync(join(dir, f), 'utf8')
+      if (/Apache License\s+Version 2\.0, January 2004/.test(t) && /END OF TERMS AND CONDITIONS/.test(t)) {
+        text = t.slice(0, t.indexOf('END OF TERMS AND CONDITIONS') + 'END OF TERMS AND CONDITIONS'.length).trim()
+        break
+      }
+    }
+    if (text) break
+  }
+  out.push(`${'='.repeat(78)}\nApache License 2.0 — applies to: ${apacheMissing.join(', ')}\n${'='.repeat(78)}`)
+  out.push(text ?? '(canonical text not found in the installed packages: see https://www.apache.org/licenses/LICENSE-2.0)')
+  if (check && text === null) {
+    console.error('Apache-2.0 packages without a licence file, and no canonical Apache License text installed')
+    process.exit(1)
+  }
+}
+mkdirSync(join(root, 'dist'), { recursive: true })
+writeFileSync(join(root, 'dist', 'THIRD_PARTY_LICENSES'), `${out.join('\n')}\n`)
+console.log(`THIRD_PARTY_LICENSES: ${names.length} production packages, ${missing.length} without a licence file`)
+if (missing.length) console.log(`  no licence file: ${missing.join(', ')}`)
+if (check && out.length === 0) {
+  console.error('no production packages found in package-lock.json')
+  process.exit(1)
+}

package/src/vite.js

@@ -85,3 +85,34 @@ export function assertE2eOnlyInE2eMode(mode, env = process.env) {
     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.`)
   }
 }
+
+/**
+ * The Vite configuration every MeddleWare tool app shares: the browserslist build target, the colour mode and season before first paint
+ * ({@link themeInit}), the e2e-build guard ({@link assertE2eOnlyInE2eMode}), and `@meddleware/wallet-adapter` excluded from dependency
+ * pre-bundling. The wallet adapter ships TS and `.vue` source and holds the shared wallet singleton; pre-bundling would put its TS in
+ * `.vite/deps` while its `.vue` files (which esbuild cannot bundle) are served raw and import the raw module, so dev would run two
+ * singletons and the guard and the app would see different connection state.
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default meddlewareApp({ plugins: [vue()] })
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The app's plugins (`vue()` …); `themeInit` is added after them.
+ * @param {'light' | 'dark' | 'system'} [options.theme] The mode a first visit gets (default `dark`, the brand default).
+ * @param {boolean} [options.wallet] The app uses `@meddleware/wallet-adapter` (default true): keep it out of pre-bundling.
+ * @param {import('vite').UserConfig} [options.config] Anything else (`base`, `build.rollupOptions`, `server` …); `build` is merged.
+ * @returns {import('vite').UserConfigFnObject}
+ */
+export function meddlewareApp({ plugins, theme = 'dark', wallet = true, config = {} }) {
+  return ({ mode }) => {
+    assertE2eOnlyInE2eMode(mode)
+    return {
+      ...config,
+      build: { target: viteTarget(), ...config.build },
+      plugins: [...plugins, themeInit({ default: theme })],
+      ...(wallet ? { optimizeDeps: { ...config.optimizeDeps, exclude: ['@meddleware/wallet-adapter', ...(config.optimizeDeps?.exclude ?? [])] } } : {}),
+    }
+  }
+}

package/src/vitest.js

@@ -50,3 +50,32 @@ export function installDialogShim() {
     this.dispatchEvent(new Event('close'))
   }
 }
+
+/**
+ * The Vitest configuration of a MeddleWare Vue repository: jsdom, `tests/**\/*.test.ts`, a single copy of Vue for the code under test and
+ * `@vue/test-utils`, and the UI packages processed through Vite ({@link inlineMeddleware}).
+ *
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * export default defineConfig(vueTestConfig({ plugins: [vue()] }))
+ * ```
+ *
+ * @param {object} options
+ * @param {import('vite').PluginOption[]} options.plugins The Vue plugin (and any other the tests need).
+ * @param {import('vitest/config').TestUserConfig} [options.test] Overrides merged into `test` (`include`, `setupFiles`, `environment` …).
+ * @returns {import('vitest/config').ViteUserConfig & { test: import('vitest/config').TestUserConfig }}
+ */
+export function vueTestConfig({ plugins, test = {} }) {
+  const inline = test.server?.deps?.inline
+  return {
+    plugins,
+    resolve: { dedupe: ['vue', '@vue/test-utils'] },
+    test: {
+      environment: 'jsdom',
+      include: ['tests/**/*.test.ts'],
+      exclude: ['node_modules/**'],
+      ...test,
+      server: { ...test.server, deps: { ...test.server?.deps, inline: inline === true ? true : [...inlineMeddleware, ...(inline ?? [])] } },
+    },
+  }
+}

package/templates/audit-allowlist.lhci.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "GHSA-jmr9-qjv8-65gv",
+    "reason": "extract-zip has no patched release. It is a dev-only transitive of @lhci/cli (lighthouse > puppeteer-core > @puppeteer/browsers) and only unpacks browser archives that Lighthouse CI downloads itself; nothing from it ships in the image.",
+    "expires": "2027-01-31"
+  },
+  {
+    "id": "GHSA-7pqw-9j4j-h8q3",
+    "reason": "extract-zip has no patched release. It is a dev-only transitive of @lhci/cli (lighthouse > puppeteer-core > @puppeteer/browsers) and only unpacks browser archives that Lighthouse CI downloads itself; nothing from it ships in the image.",
+    "expires": "2027-01-31"
+  }
+]

package/templates/dependabot.app.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "typescript"
+        update-types: ["version-update:semver-major"]
+    groups:
+      npm-minor-patch:
+        update-types: [minor, patch]
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "golang"
+        update-types: ["version-update:semver-minor", "version-update:semver-major"]
+    groups:
+      docker:
+        patterns: ['*']
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns: ['*']

package/templates/dockerignore

@@ -0,0 +1,13 @@
+# Build context: sources only. The image runs its own `npm ci` and production build, so local
+# installs and build output never enter it — and local-only env files (Vite loads `.env*.local` in
+# every mode) can never be baked into the production bundle. Committed `.env` / `.env.production`
+# defaults stay in the context on purpose.
+node_modules
+dist
+.git
+.github
+.env*.local
+*.log
+test-results
+playwright-report
+coverage

package/templates/postcss.config.js

@@ -0,0 +1 @@
+export { default } from '@meddleware/frontend-config/postcss'

package/templates/stylelint.config.js

@@ -0,0 +1,3 @@
+import { stylelintConfig } from '@meddleware/frontend-config/stylelint'
+
+export default stylelintConfig()

package/tsconfig/vue-app.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "jsx": "preserve",
+    "types": ["node"],
+    "noEmit": true
+  }
+}