@meddleware/frontend-config 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.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

@@ -17,6 +17,8 @@ same accessibility and browser-support bar.
 | `/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. |
+| `/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). |
 
 ## Use
@@ -108,6 +110,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/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-prod-bundle.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meddleware/frontend-config",
-  "version": "0.0.1",
+  "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",
@@ -22,7 +22,8 @@
   "files": [
     "src",
     "dist",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "exports": {
     ".": {
@@ -81,6 +82,10 @@
     "./wallet": {
       "types": "./dist/wallet.d.ts",
       "default": "./src/wallet.js"
+    },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "default": "./src/bundle.js"
     }
   },
   "scripts": {
@@ -157,5 +162,8 @@
     "last 2 Samsung versions",
     "Firefox ESR",
     "not dead"
-  ]
+  ],
+  "bin": {
+    "check-prod-bundle": "./src/check-prod-bundle.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/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)` : ''}).`)