@burdenoff/fe-libs 2026.1022.3 → 2026.1023.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/fe-libs",
-  "version": "2026.1022.3",
+  "version": "2026.1023.2",
   "description": "Burdenoff frontend primitives and domain libraries",
   "type": "module",
   "bin": {

package/scripts/a11y-audit/README.md

@@ -110,6 +110,69 @@ how you point the same config at alpha or prod.
 
 Per route you can also set `waitForSelector` and a route-specific `settleMs`.
 
+### Signed-in routes: `fixtures`
+
+External requests are blocked, so a signed-in page cannot reach its gateway and
+the shell bounces to `/auth/login`. A **fixture** gives a route a deterministic
+session instead of a live one:
+
+```jsonc
+// a11y-audit.config.json
+"routes": [
+  { "path": "/vibecontrols", "name": "signed-in-overview", "fixture": "signed-in",
+    "waitForSelector": "main#main-content h1", "minTextLength": 1500 }
+],
+"fixtures": { "signed-in": "a11y/fixtures/signed-in.json" }   // or the object inline
+```
+
+```jsonc
+// a11y/fixtures/signed-in.json
+{
+  "localStorage": {
+    "bf-p-<profile>-tokens": {
+      "accessToken": { "$jwt": { "sub": "<user>", "exp": { "$fromNow": 3600 } } },
+      "expiresAt": { "$fromNowMs": 3600000 }
+    }
+  },
+  "cookies": { "bf-sso": { "id": "<profile>", "origin": null } },
+  "graphql": {
+    "endpoints": ["/global/graphql", "/workspaces/graphql"],
+    "operations": { "ValidateAuthToken": { "data": { "validateTokens": { "valid": true } } } }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `localStorage` | Seeded before any page script runs (same-origin documents only). Strings are stored as-is, anything else as JSON. |
+| `cookies` | Set on the app origin before the page opens. Strings as-is, anything else as URL-encoded JSON. |
+| `graphql.endpoints` | Path suffixes that identify a GraphQL endpoint on **any** origin. Matching requests never leave the browser. |
+| `graphql.operations` | Response body per operation name. Batched requests get a batched answer in order. |
+
+Markers, resolved when each page opens:
+
+- `{ "$jwt": { ...claims } }` becomes an **unsigned** (`alg: none`) token. Never
+  put a real or real-looking credential in a fixture.
+- `{ "$fromNow": seconds }` becomes unix seconds from now (JWT `exp`/`iat`);
+  `{ "$fromNowMs": ms }` becomes epoch milliseconds from now (`expiresAt`). Do
+  not use a fixed far-future expiry: shells schedule refresh timers off it, and
+  a delay past setTimeout's 2^31-1 ms ceiling fires immediately.
+
+Guarantees:
+
+- Every route runs in its own browser context, so a fixture's session never
+  leaks into the signed-out routes (or the other way round).
+- A fixture route that ends anywhere other than its `path` (the query string is
+  ignored) is a failed attempt: landing on `/auth/login` means the fixture did
+  not sign in, and auditing the login page again would be a false pass. Set
+  `allowRedirect` on the route only if the redirect is the page.
+- An operation the fixture has no answer for gets a GraphQL error response
+  (code `A11Y_FIXTURE_UNMOCKED`), never a live call, and is listed under the
+  route in the console and step-summary report. Keep that list empty: an
+  unmocked query usually means part of the page rendered its error state.
+- Fixture data is synthetic. Use obviously fake ids and names, never an export
+  of a real account.
+
 ### `failOn`
 
 Defaults to `["critical", "serious"]`. It may be **widened** (adding `moderate`),

package/scripts/a11y-audit/audit.ts

@@ -9,9 +9,16 @@
  */
 
 import { partitionNodes, flattenViolations } from './allowlist';
+import {
+  materializeCookies,
+  materializeLocalStorage,
+  matchesGraphqlEndpoint,
+  respondToGraphql,
+  seedLocalStorageScript,
+} from './fixtures';
 import type { AxeViolationLike } from './allowlist';
 import type { RunningApp } from './server';
-import type { AuditReport, ResolvedConfig, RouteResult } from './types';
+import type { AuditReport, FixtureSpec, ResolvedConfig, RouteResult } from './types';
 
 /* eslint-disable @typescript-eslint/no-explicit-any -- dynamically imported
    third-party modules have no static types available inside this script. */
@@ -124,14 +131,73 @@ export async function runAudit(
   const usedEntries = new Set<number>();
   const navigationErrors: string[] = [];
 
-  /** Fresh page with request routing applied — used for the first try and every retry. */
-  const openPage = async (context: AnyRecord): Promise<AnyRecord> => {
+  /**
+   * Fresh page with request routing applied — used for the first try and every
+   * retry. With a fixture, its session is seeded before any page script runs
+   * and its GraphQL endpoints are answered from the fixture (recording any
+   * operation it has no answer for in `unmocked`).
+   */
+  const openPage = async (
+    context: AnyRecord,
+    fixture: FixtureSpec | undefined,
+    unmocked: Set<string>
+  ): Promise<AnyRecord> => {
+    if (fixture?.cookies) {
+      await context.addCookies(
+        materializeCookies(fixture).map((cookie) => ({
+          ...cookie,
+          url: baseUrl,
+        }))
+      );
+    }
     const page = await context.newPage();
-    if (config.blockExternalRequests || resolveAsset) {
+    if (fixture?.localStorage) {
+      await page.addInitScript(seedLocalStorageScript, {
+        origin: new URL(baseUrl).origin,
+        entries: materializeLocalStorage(fixture),
+      });
+    }
+    if (config.blockExternalRequests || resolveAsset || fixture?.graphql) {
       await page.route('**/*', (route: AnyRecord) => {
-        const requestUrl: string = route.request().url();
+        const request = route.request();
+        const requestUrl: string = request.url();
         const isOwnOrigin = requestUrl.startsWith(baseUrl);
 
+        // Fixture GraphQL first: on any origin, a matching endpoint is answered
+        // from the fixture and never reaches a live gateway.
+        if (fixture?.graphql && matchesGraphqlEndpoint(requestUrl, fixture)) {
+          if (request.method() === 'OPTIONS') {
+            void route.fulfill({
+              status: 204,
+              headers: {
+                'access-control-allow-origin': new URL(baseUrl).origin,
+                'access-control-allow-credentials': 'true',
+                'access-control-allow-methods': 'GET, POST, OPTIONS',
+                'access-control-allow-headers': '*',
+              },
+              body: '',
+            });
+            return;
+          }
+          const answer = respondToGraphql(
+            fixture,
+            request.method() as string,
+            requestUrl,
+            (request.postData() as string | null) ?? null
+          );
+          answer.unmocked.forEach((name) => unmocked.add(name));
+          void route.fulfill({
+            status: answer.status,
+            contentType: 'application/json',
+            headers: {
+              'access-control-allow-origin': new URL(baseUrl).origin,
+              'access-control-allow-credentials': 'true',
+            },
+            body: answer.body,
+          });
+          return;
+        }
+
         // Serve the build's own files straight from disk. Chromium never opens
         // a socket for them, so a spurious network-change notification cannot
         // cancel a hundred in-flight chunk loads and leave the shell blank.
@@ -146,7 +212,11 @@ export async function runAudit(
             });
             return;
           }
-          void route.fulfill({ status: 404, contentType: 'text/plain', body: 'Not found' });
+          void route.fulfill({
+            status: 404,
+            contentType: 'text/plain',
+            body: 'Not found',
+          });
           return;
         }
 
@@ -162,27 +232,34 @@ export async function runAudit(
     return page;
   };
 
+  // Every route gets its own browser context, so a fixture's seeded session
+  // can never leak into the signed-out routes audited after it (or the other
+  // way round), and route order cannot change what axe sees.
+  const newContext = async (viewport: { width: number; height: number }): Promise<AnyRecord> =>
+    browser.newContext({
+      viewport: { width: viewport.width, height: viewport.height },
+      // Deterministic rendering: no OS locale/timezone drift between the dev
+      // machine and the CI runner changing what axe sees.
+      locale: 'en-US',
+      timezoneId: 'UTC',
+      reducedMotion: 'reduce',
+      // A service worker caching the shell across routes would make the audit
+      // depend on which route ran first.
+      serviceWorkers: 'block',
+    });
+
   try {
     for (const viewport of config.viewports) {
-      const context = await browser.newContext({
-        viewport: { width: viewport.width, height: viewport.height },
-        // Deterministic rendering: no OS locale/timezone drift between the dev
-        // machine and the CI runner changing what axe sees.
-        locale: 'en-US',
-        timezoneId: 'UTC',
-        reducedMotion: 'reduce',
-        // A service worker caching the shell across routes would make the audit
-        // depend on which route ran first.
-        serviceWorkers: 'block',
-      });
-
       for (const route of config.routes) {
         const url = `${baseUrl}${route.path}`;
         const attemptFailures: string[] = [];
         let result: RouteResult | null = null;
+        const fixture = route.fixture ? config.fixtures[route.fixture] : undefined;
 
         for (let attempt = 1; attempt <= config.routeAttempts && result === null; attempt += 1) {
-          const page = await openPage(context);
+          const context = await newContext(viewport);
+          const unmocked = new Set<string>();
+          const page = await openPage(context, fixture, unmocked);
           try {
             const response = await page.goto(url, {
               waitUntil: 'load',
@@ -203,6 +280,18 @@ export async function runAudit(
               config.domQuietMs,
               config.navigationTimeoutMs
             );
+            if (fixture && !route.allowRedirect) {
+              const landed = new URL(page.url() as string).pathname.replace(/\/+$/, '') || '/';
+              const expected = new URL(url).pathname.replace(/\/+$/, '') || '/';
+              if (landed !== expected) {
+                throw new Error(
+                  `fixture "${route.fixture}" route ended on ${landed} instead of ${expected} — ` +
+                    'the fixture did not produce the page, so auditing where it landed would be ' +
+                    'a false pass' +
+                    (unmocked.size > 0 ? ` (unmocked operations: ${[...unmocked].join(', ')})` : '')
+                );
+              }
+            }
             const floor = route.minTextLength ?? config.minTextLength;
             if (stability.snapshot.textLength < floor) {
               throw new Error(
@@ -237,11 +326,18 @@ export async function runAudit(
               renderedTextLength: stability.snapshot.textLength,
               domSettled: stability.settled,
               attempts: attempt,
+              ...(route.fixture
+                ? {
+                    fixture: route.fixture,
+                    unmockedOperations: [...unmocked].sort(),
+                  }
+                : {}),
             };
           } catch (error) {
             attemptFailures.push(`attempt ${attempt}: ${(error as Error).message}`);
           } finally {
             await page.close();
+            await context.close();
           }
         }
 
@@ -259,8 +355,6 @@ export async function runAudit(
         }
         results.push(result);
       }
-
-      await context.close();
     }
   } finally {
     await browser.close();
@@ -279,7 +373,11 @@ export async function runAudit(
     .filter((entry) => !usedEntries.has(entry.index));
 
   const expiredAllowlistEntries = config.allowlist
-    .map((entry, index) => ({ index, rule: entry.rule, expires: entry.expires ?? '' }))
+    .map((entry, index) => ({
+      index,
+      rule: entry.rule,
+      expires: entry.expires ?? '',
+    }))
     .filter((entry) => {
       if (!entry.expires) return false;
       return now.getTime() > new Date(`${entry.expires}T23:59:59.999Z`).getTime();

package/scripts/a11y-audit/cli.ts

@@ -26,7 +26,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { runAudit } from './audit';
-import { ConfigError, resolveConfig } from './config';
+import { ConfigError, inlineFixtureFiles, resolveConfig } from './config';
 import { renderConsole, renderMarkdown } from './report';
 import { findUnreachableRouteScopes } from './allowlist';
 import { startApp } from './server';
@@ -40,7 +40,11 @@ interface CliArgs {
 }
 
 export function parseArgs(argv: string[]): CliArgs {
-  const args: CliArgs = { configPath: 'a11y-audit.config.json', routes: [], quiet: false };
+  const args: CliArgs = {
+    configPath: 'a11y-audit.config.json',
+    routes: [],
+    quiet: false,
+  };
   let positionalSeen = false;
   for (const arg of argv) {
     if (arg.startsWith('--base-url=')) args.baseUrl = arg.slice('--base-url='.length);
@@ -77,7 +81,10 @@ async function main(): Promise<number> {
 
   let config;
   try {
-    config = resolveConfig(JSON.parse(readFileSync(configPath, 'utf8')));
+    const raw: unknown = JSON.parse(readFileSync(configPath, 'utf8'));
+    config = resolveConfig(
+      inlineFixtureFiles(raw, dirname(configPath), (path) => readFileSync(path, 'utf8'))
+    );
   } catch (error) {
     if (error instanceof ConfigError) console.error(`[a11y-audit] ${error.message}`);
     else console.error(`[a11y-audit] Failed to read ${configPath}: ${(error as Error).message}`);

package/scripts/a11y-audit/config.ts

@@ -11,6 +11,7 @@ import { IMPACT_LEVELS } from './types';
 import type {
   A11yAuditConfig,
   AllowlistEntry,
+  FixtureSpec,
   ImpactLevel,
   ResolvedConfig,
   RouteSpec,
@@ -187,6 +188,73 @@ function validateRoute(route: unknown, index: number, issues: string[]): void {
   }
 }
 
+function validateFixture(name: string, fixture: unknown, issues: string[]): void {
+  const where = `fixtures.${name}`;
+  if (typeof fixture === 'string') {
+    issues.push(
+      `${where} is still a file reference ("${fixture}") — load the config with ` +
+        'inlineFixtureFiles() before resolving it'
+    );
+    return;
+  }
+  if (!isPlainObject(fixture)) {
+    issues.push(`${where} must be an object`);
+    return;
+  }
+  for (const key of Object.keys(fixture)) {
+    if (key !== 'localStorage' && key !== 'cookies' && key !== 'graphql') {
+      issues.push(
+        `${where}.${key} is not a fixture field (allowed: localStorage, cookies, graphql)`
+      );
+    }
+  }
+  if (
+    fixture.localStorage === undefined &&
+    fixture.cookies === undefined &&
+    fixture.graphql === undefined
+  ) {
+    issues.push(
+      `${where} must set localStorage, cookies and/or graphql — an empty fixture changes nothing`
+    );
+  }
+  for (const key of ['localStorage', 'cookies'] as const) {
+    if (fixture[key] !== undefined && !isPlainObject(fixture[key])) {
+      issues.push(`${where}.${key} must be an object of name → value`);
+    }
+  }
+  if (fixture.graphql !== undefined) {
+    const graphql = fixture.graphql;
+    if (!isPlainObject(graphql)) {
+      issues.push(`${where}.graphql must be { endpoints, operations }`);
+      return;
+    }
+    if (
+      !Array.isArray(graphql.endpoints) ||
+      graphql.endpoints.length === 0 ||
+      !graphql.endpoints.every(isNonEmptyString)
+    ) {
+      issues.push(`${where}.graphql.endpoints must be a non-empty array of path suffixes`);
+    } else {
+      graphql.endpoints.forEach((endpoint, i) => {
+        if (!endpoint.startsWith('/')) {
+          issues.push(`${where}.graphql.endpoints[${i}] "${endpoint}" must start with "/"`);
+        }
+      });
+    }
+    if (!isPlainObject(graphql.operations) || Object.keys(graphql.operations).length === 0) {
+      issues.push(`${where}.graphql.operations must be a non-empty object of operation → response`);
+    } else {
+      for (const [operation, result] of Object.entries(graphql.operations)) {
+        if (!isPlainObject(result) || (!('data' in result) && !('errors' in result))) {
+          issues.push(
+            `${where}.graphql.operations.${operation} must be a GraphQL response ({ data } or { errors })`
+          );
+        }
+      }
+    }
+  }
+}
+
 function validateServe(serve: unknown, issues: string[]): void {
   if (!isPlainObject(serve)) {
     issues.push('serve is required and must be an object');
@@ -286,6 +354,28 @@ export function resolveConfig(raw: unknown): ResolvedConfig {
     }
   }
 
+  const fixtureNames = new Set<string>();
+  if (raw.fixtures !== undefined) {
+    if (!isPlainObject(raw.fixtures)) {
+      issues.push('fixtures must be an object of name → fixture when present');
+    } else {
+      for (const [name, fixture] of Object.entries(raw.fixtures)) {
+        fixtureNames.add(name);
+        validateFixture(name, fixture, issues);
+      }
+    }
+  }
+  if (Array.isArray(raw.routes)) {
+    raw.routes.forEach((route, i) => {
+      if (!isPlainObject(route) || route.fixture === undefined) return;
+      if (!isNonEmptyString(route.fixture)) {
+        issues.push(`routes[${i}].fixture must be a non-empty fixture name when present`);
+      } else if (!fixtureNames.has(route.fixture)) {
+        issues.push(`routes[${i}].fixture "${route.fixture}" is not defined in fixtures`);
+      }
+    });
+  }
+
   if (issues.length > 0) throw new ConfigError(issues);
 
   const config = raw as unknown as A11yAuditConfig;
@@ -315,5 +405,38 @@ export function resolveConfig(raw: unknown): ResolvedConfig {
     domQuietMs: config.domQuietMs ?? 1500,
     minTextLength: config.minTextLength ?? 100,
     routeAttempts: config.routeAttempts ?? 3,
+    // Validated above: no string (file) entries survive to this point.
+    fixtures: (config.fixtures ?? {}) as Record<string, FixtureSpec>,
   };
 }
+
+/**
+ * Replace every fixture given as a file path with the parsed file. Paths
+ * resolve against `baseDir` (the config file's directory). `readFile` is
+ * injected so this stays pure and testable.
+ *
+ * @throws ConfigError when a referenced file is missing or is not JSON.
+ */
+export function inlineFixtureFiles(
+  raw: unknown,
+  baseDir: string,
+  readFile: (absolutePath: string) => string
+): unknown {
+  if (!isPlainObject(raw) || !isPlainObject(raw.fixtures)) return raw;
+  const issues: string[] = [];
+  const fixtures: Record<string, unknown> = {};
+  for (const [name, fixture] of Object.entries(raw.fixtures)) {
+    if (typeof fixture !== 'string') {
+      fixtures[name] = fixture;
+      continue;
+    }
+    const path = fixture.startsWith('/') ? fixture : `${baseDir.replace(/\/+$/, '')}/${fixture}`;
+    try {
+      fixtures[name] = JSON.parse(readFile(path));
+    } catch (error) {
+      issues.push(`fixtures.${name}: cannot load "${fixture}" (${(error as Error).message})`);
+    }
+  }
+  if (issues.length > 0) throw new ConfigError(issues);
+  return { ...raw, fixtures };
+}