@meddleware/frontend-config 0.0.0-stage → 0.0.2

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

package/package.json

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

package/src/a11y.js

@@ -0,0 +1,235 @@
+// @ts-check
+// The accessibility sweep every app runs, in one call: each state of the app (a route, a dialog open, an error page) in every colour mode
+// × season at WCAG 2.2 AA and AAA, then at a 320 px reflow width, at 200% text size, in forced colours and with reduced motion, and a
+// keyboard pass (every Tab stop is visible and shows where focus is). The assertions are exported on their own for specs that need one.
+//
+//   // e2e/a11y.spec.ts
+//   defineA11ySuite({ home: async (page) => { await page.goto('/') }, empty: openEmpty }, { aaa: 'gate' })
+import { expect, test } from '@playwright/test'
+import { expectAccessible } from './axe.js'
+import { applyLook, looks, offline } from './look.js'
+
+/** @typedef {(page: import('@playwright/test').Page) => Promise<void>} 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
+ */
+export async function expectNoHorizontalScroll(page) {
+  const overflow = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)
+  expect(overflow, 'the page scrolls sideways by this many CSS pixels').toBeLessThanOrEqual(0)
+}
+
+/**
+ * No animation is running: with `prefers-reduced-motion: reduce` the page holds still (WCAG 2.3.3).
+ * @param {import('@playwright/test').Page} page
+ */
+export async function expectNoRunningAnimations(page) {
+  await page.waitForTimeout(250)
+  const running = await page.evaluate(() => document.getAnimations().filter((a) => a.playState === 'running').map((a) => (/** @type {KeyframeEffect | null} */ (a.effect)?.target?.className || 'animation')))
+  expect(running, 'animations still running under reduced motion').toEqual([])
+}
+
+/**
+ * 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 = 300 } = {}) {
+  /** @type {string[]} */
+  const problems = []
+  let stops = 0
+  let wrapped = false
+  let finished = false
+  await startAtTop(page)
+  for (let i = 0; i < maxStops; i++) {
+    await page.keyboard.press('Tab')
+    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
+      }
+      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)
+  // 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', 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', 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)
+      })
+
+      for (const { theme, season } of looks().filter((l) => l.viewport === 'desktop')) {
+        test(`WCAG 2.2 AA and AAA (${theme} · ${season})`, async ({ page }) => {
+          await page.emulateMedia({ colorScheme: /** @type {'light' | 'dark'} */ (theme), reducedMotion: 'reduce' })
+          await open(page)
+          await applyLook(page, theme, season)
+          await expectAccessible(page, { aaa, disableRules })
+        })
+      }
+
+      test('reflows at 320 CSS pixels', async ({ page }) => {
+        await page.setViewportSize({ width: 320, height: 640 })
+        await open(page)
+        await expectNoHorizontalScroll(page)
+        await expectAccessible(page, { aaa: 'off', 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', 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: [...disableRules, 'color-contrast'] })
+      })
+
+      test('holds still with reduced motion', async ({ page }) => {
+        await page.emulateMedia({ reducedMotion: 'reduce' })
+        await open(page)
+        await expectNoRunningAnimations(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/axe.js

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

package/src/browserslist-config.cjs

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

package/src/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-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)` : ''}).`)