Add wallet chooser screenshot gallery and document testing.

Add `npm run gallery`, which screenshots the first party wallet
chooser across wallet counts, themes, and engines (collapsed and
expanded) via the harness route, then builds an `index.html` contact
sheet for quick visual review. Output lands in the git-ignored
`test/e2e/gallery/`. Document both the regression suite and the
gallery in the README, including the Brave/mobile coverage caveats.
Also git-ignore the local `scratchpad/` working directory.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: djscruggs

.gitignore

@@ -24,3 +24,6 @@ static/images/logo-*.png
 /playwright-report
 /blob-report
 /test/e2e/gallery
+
+# local working notes / manual-test artifacts
+scratchpad

README.md

@@ -83,6 +83,40 @@ Access the server at the following URL:
 
 * https://authn.localhost:33443/
 
+## Testing
+
+The first party wallet chooser dialog has an automated visual/layout test
+suite. It drives a dev-only harness route
+(`/test/wallet-chooser?hints=N&qr=1`) that renders the dialog with fake state,
+so the layout can be exercised across wallet counts (0, 1, 5, 15) and the
+cross-device QR section without any CHAPI registration, wallets, or popups. The
+harness route is excluded from production builds.
+
+Install the browser engines once:
+
+    npx playwright install chromium webkit firefox
+
+Run the layout regression suite (Chromium, WebKit, Firefox):
+
+    npm run test:e2e
+
+This asserts structural invariants — the expected wallets render, no horizontal
+or window scrollbar appears, the header stays pinned while the list scrolls, and
+the panel fills the popup — rather than comparing pixels. It starts the dev
+server automatically.
+
+Generate a browsable screenshot gallery of every state (wallet count × theme ×
+engine, collapsed and expanded), with an `index.html` contact sheet:
+
+    npm run gallery
+
+Output is written to `test/e2e/gallery/` (git-ignored).
+
+> **Brave:** the Chromium engine covers Brave's rendering (Brave is Chromium
+> plus "shields", which do not affect the dialog CSS). Brave's storage/shields
+> behavior is a CHAPI plumbing concern, verified in the manual mobile pass, not
+> by this layout suite. Real mobile/Safari-on-iOS is likewise a manual pass.
+
 ## Production
 
 Full instructions for running this code in production are beyond the scope of

package.json

@@ -9,7 +9,8 @@
   "scripts": {
     "start": "node authn.localhost.js",
     "lint": "eslint",
-    "test:e2e": "playwright test wallet-chooser"
+    "test:e2e": "playwright test wallet-chooser",
+    "gallery": "playwright test gallery && node test/e2e/build-gallery-index.js"
   },
   "repository": {
     "type": "git",

test/e2e/build-gallery-index.js

@@ -0,0 +1,71 @@
+/*!
+ * New BSD License (3-clause)
+ * Copyright (c) 2026, Digital Bazaar, Inc.
+ * All rights reserved.
+ */
+import {fileURLToPath} from 'node:url';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/* Builds an `index.html` contact sheet from the PNGs the gallery spec wrote
+to `test/e2e/gallery/<engine>/<theme>/`. Run after `playwright test gallery`
+(the `gallery` npm script chains them). Filesystem-driven so it sees every
+engine's output regardless of which Playwright worker produced it. */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GALLERY_DIR = path.join(__dirname, 'gallery');
+
+async function findPngs(dir, base = dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = await fs.readdir(dir, {withFileTypes: true});
+  } catch {
+    return out;
+  }
+  for(const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()) {
+      out.push(...await findPngs(full, base));
+    } else if(entry.name.endsWith('.png')) {
+      out.push(path.relative(base, full));
+    }
+  }
+  return out;
+}
+
+const pngs = (await findPngs(GALLERY_DIR)).sort((a, b) => a.localeCompare(b));
+if(pngs.length === 0) {
+  console.error('No gallery PNGs found. Run `playwright test gallery` first.');
+  process.exit(1);
+}
+
+const cards = pngs.map(rel => {
+  // rel = <engine>/<theme>/<state>.png
+  const [engine, theme, file] = rel.split(path.sep);
+  const label = file.replace(/\.png$/, '').replace(/-/g, ' ');
+  return `
+    <figure>
+      <img src="${rel}" alt="${label}" loading="lazy">
+      <figcaption>${engine} / ${theme} — ${label}</figcaption>
+    </figure>`;
+}).join('');
+
+const html = `<!doctype html>
+<meta charset="utf-8">
+<title>authn.io wallet chooser gallery</title>
+<style>
+  body {font: 14px system-ui, sans-serif; margin: 24px; background: #fafafa;}
+  h1 {font-size: 18px;}
+  .grid {display: flex; flex-wrap: wrap; gap: 16px;}
+  figure {margin: 0; background: #fff; border: 1px solid #ddd;
+    border-radius: 6px; padding: 8px;}
+  img {display: block; width: 250px; height: auto; border: 1px solid #eee;}
+  figcaption {font-size: 12px; color: #444; padding-top: 6px; max-width: 250px;}
+</style>
+<h1>authn.io wallet chooser — ${pngs.length} shots</h1>
+<div class="grid">${cards}</div>`;
+
+const indexPath = path.join(GALLERY_DIR, 'index.html');
+await fs.writeFile(indexPath, html);
+console.log(`Gallery contact sheet: ${indexPath}`);

test/e2e/gallery.spec.js

@@ -0,0 +1,59 @@
+/*!
+ * New BSD License (3-clause)
+ * Copyright (c) 2026, Digital Bazaar, Inc.
+ * All rights reserved.
+ */
+import {expect, test} from '@playwright/test';
+import {fileURLToPath} from 'node:url';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+/* Generates a labelled, human-viewable gallery of the first party wallet
+chooser dialog across wallet counts, the cross-device QR section, themes, and
+viewports — the screenshots we otherwise capture by hand for review. Output
+goes to `test/e2e/gallery/<engine>/<theme>/<state>.png` plus an `index.html`
+contact sheet. This is NOT a regression gate (see `wallet-chooser.spec.js` for
+that); run it with `npm run gallery`. */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GALLERY_DIR = path.join(__dirname, 'gallery');
+
+const STATES = [
+  {name: 'hints-0-qr', query: 'hints=0&qr=1', label: '0 wallets + QR'},
+  {name: 'hints-1-qr', query: 'hints=1&qr=1', label: '1 wallet + QR'},
+  {name: 'hints-5-qr', query: 'hints=5&qr=1', label: '5 wallets + QR'},
+  {name: 'hints-5-noqr', query: 'hints=5&qr=0', label: '5 wallets, no QR'},
+  {name: 'hints-15-qr', query: 'hints=15&qr=1', label: '15 wallets + QR'}
+];
+const THEMES = ['light', 'dark'];
+
+test.describe('gallery', () => {
+  for(const theme of THEMES) {
+    test.describe(theme, () => {
+      test.use({colorScheme: theme});
+
+      for(const state of STATES) {
+        test(`${state.label}`, async ({page}, testInfo) => {
+          const engine = testInfo.project.name;
+          await page.goto(`/test/wallet-chooser?${state.query}`);
+          await page.locator('.wrm-modal-1p .wrm-modal-content').waitFor();
+
+          const dir = path.join(GALLERY_DIR, engine, theme);
+          await fs.mkdir(dir, {recursive: true});
+
+          // collapsed (default) shot
+          await page.screenshot({path: path.join(dir, `${state.name}.png`)});
+
+          // for states with the expander, also capture it expanded
+          const toggle = page.locator('.cross-device-toggle');
+          if(await toggle.count() > 0) {
+            await toggle.click();
+            await expect(page.locator('img[alt*="QR"]')).toBeVisible();
+            await page.screenshot(
+              {path: path.join(dir, `${state.name}-expanded.png`)});
+          }
+        });
+      }
+    });
+  }
+});