thevoidforge 21.0.11 → 21.0.13

package/dist/docs/patterns/browser-review.ts

@@ -0,0 +1,292 @@
+/**
+ * Pattern: Browser-Based Agent Review
+ *
+ * Purpose: Give review agents (Batman, Galadriel, Kenobi, Thanos) browser eyes
+ * during ad-hoc review passes. NOT E2E testing (see e2e-test.ts for that).
+ *
+ * E2E tests vs browser review — separate concerns:
+ *   - E2E tests: deterministic, CI, assert pass/fail. Owned by test suites.
+ *   - Browser review: exploratory, during /qa /ux /security /gauntlet. Evidence for triage.
+ *
+ * Three capabilities:
+ *   1. Console capture — catch uncaught exceptions and JS errors passively.
+ *   2. Behavioral walkthrough — click buttons, fill forms, verify responses.
+ *   3. Screenshot evidence — capture viewport state for triage reports.
+ *
+ * Screenshots: good for triage (blank page? modal open?) and evidence (attach to findings).
+ * NOT good for design review. Riker's dissent: "A screenshot tells you what rendered, not
+ * whether it looks right. Design review requires a designer's eye, not a pixel grid."
+ *
+ * Agents: Batman (QA walkthrough), Galadriel (responsive), Kenobi (security),
+ *   Hawkeye (Gauntlet smoke), Riker (dissent on screenshot-as-design-review)
+ *
+ * === Framework Adaptations (baseURL + startup) ===
+ *   Next.js:  `next dev -p 3199`, baseURL = 'http://127.0.0.1:3199'
+ *   Express:  `PORT=3199 npx tsx src/server.ts`, same baseURL
+ *   Django:   `python manage.py runserver 3199 --settings=project.settings.test`
+ *   Rails:    `RAILS_ENV=test bin/rails server -p 3199`
+ *   All: start the dev server BEFORE calling launchReviewBrowser(). The review
+ *   browser connects to a running server — it does NOT manage the lifecycle.
+ *
+ * Dependencies: playwright (already available if using e2e-test.ts)
+ */
+
+import { chromium, type Browser, type BrowserContext, type Page } from 'playwright';
+// Type-only import for axe — actual usage is dynamic import (not all projects have it)
+type AxeResults = { violations: Array<{ id: string; impact?: string; description: string; nodes: unknown[] }> };
+
+// ── Types ───────────────────────────────────────────
+
+export interface ConsoleError {
+  url: string;
+  type: 'uncaught-exception' | 'console-error';
+  message: string;
+  stack: string | null;
+}
+
+export interface PageStateReport {
+  route: string;
+  title: string;
+  headings: string[];
+  screenshotPath: string;
+  consoleErrors: ConsoleError[];
+  a11yViolations: Array<{ id: string; impact: string | undefined; description: string; nodeCount: number }>;
+}
+
+export interface ViewportCapture {
+  viewport: { width: number; height: number; label: string };
+  screenshotPath: string;
+  consoleErrors: ConsoleError[];
+}
+
+export interface ResponsiveReport { route: string; captures: ViewportCapture[] }
+
+export interface InteractionReport {
+  route: string;
+  buttons: Array<{ text: string; responded: boolean; error: string | null }>;
+  links: Array<{ text: string; href: string | null }>;
+  formFields: Array<{ label: string; type: string; acceptedInput: boolean; validationMessage: string | null }>;
+}
+
+export interface CookieReport {
+  cookies: Array<{ name: string; domain: string; secure: boolean; httpOnly: boolean; sameSite: string; expires: number }>;
+  findings: string[];
+}
+
+export interface CORSReport {
+  url: string;
+  allowOrigin: string | null;
+  allowCredentials: string | null;
+  allowMethods: string | null;
+  allowHeaders: string | null;
+  findings: string[];
+}
+
+export interface CSPViolation { blockedURI: string; violatedDirective: string; originalPolicy: string }
+
+// ── Review Browser Launcher ─────────────────────────
+// Network-isolated Chromium. Fixed viewport (1440x900, 1x DPI, light mode).
+
+export async function launchReviewBrowser(baseURL: string): Promise<{
+  browser: Browser; context: BrowserContext; page: Page;
+}> {
+  const browser = await chromium.launch({
+    args: [
+      '--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1', // Block external DNS
+      '--disable-extensions',
+    ],
+  });
+  const context = await browser.newContext({
+    viewport: { width: 1440, height: 900 },
+    deviceScaleFactor: 1,
+    colorScheme: 'light',
+    baseURL,
+  });
+  const page = await context.newPage();
+  return { browser, context, page };
+}
+
+// ── Console Error Capture ───────────────────────────
+// pageerror = uncaught exception (always a finding).
+// console.error = filtered for noise (React dev, HMR, extensions).
+
+const CONSOLE_NOISE: RegExp[] = [
+  /Download the React DevTools/i, /Warning: ReactDOM/i,
+  /Warning: Each child in a list/i, /\[HMR\]/i, /\[vite\]/i,
+  /webpack.*hot/i, /chrome-extension:\/\//i, /moz-extension:\/\//i,
+  /Failed to load resource.*favicon/i,
+];
+
+export function attachConsoleCapture(page: Page): {
+  errors: ConsoleError[]; getErrors: () => ConsoleError[];
+} {
+  const errors: ConsoleError[] = [];
+  page.on('pageerror', (error) => {
+    errors.push({ url: page.url(), type: 'uncaught-exception', message: error.message, stack: error.stack ?? null });
+  });
+  page.on('console', (msg) => {
+    if (msg.type() !== 'error') return;
+    const text = msg.text();
+    if (CONSOLE_NOISE.some((p) => p.test(text))) return;
+    errors.push({ url: page.url(), type: 'console-error', message: text, stack: null });
+  });
+  return { errors, getErrors: () => [...errors] };
+}
+
+// ── Page State Capture ──────────────────────────────
+// Navigate, wait for ready, screenshot, headings, a11y. The workhorse.
+
+export async function capturePageState(
+  page: Page, route: string,
+  options?: { readySelector?: string; screenshotDir?: string; runA11y?: boolean }
+): Promise<PageStateReport> {
+  const readySelector = options?.readySelector ?? '[data-ready]';
+  const screenshotDir = options?.screenshotDir ?? 'review-captures';
+  const runA11y = options?.runA11y ?? true;
+
+  await page.goto(route);
+  // Wait for ready selector; fall back to networkidle (lenient for review, not E2E)
+  try { await page.waitForSelector(readySelector, { timeout: 3000 }); }
+  catch { await page.waitForLoadState('networkidle'); }
+
+  const slug = route.replace(/\//g, '-').replace(/^-/, '') || 'index';
+  const screenshotPath = `${screenshotDir}/${slug}.jpg`;
+  await page.screenshot({ path: screenshotPath, type: 'jpeg', quality: 80 });
+
+  const title = await page.title();
+  const headings = await page.locator('h1, h2, h3').allTextContents();
+
+  // a11y scan — dynamic import so pattern doesn't hard-depend on axe
+  let a11yViolations: PageStateReport['a11yViolations'] = [];
+  if (runA11y) {
+    try {
+      const { default: Builder } = await import('@axe-core/playwright');
+      const results: AxeResults = await new (Builder as unknown as new (opts: { page: Page }) => { analyze: () => Promise<AxeResults> })({ page }).analyze();
+      a11yViolations = results.violations.map((v) => ({
+        id: v.id, impact: v.impact, description: v.description, nodeCount: v.nodes.length,
+      }));
+    } catch { /* axe not installed — skip */ }
+  }
+
+  return { route, title, headings, screenshotPath, consoleErrors: [], a11yViolations };
+}
+
+// ── Responsive Capture ──────────────────────────────
+// Three viewports: mobile (375x812), tablet (768x1024), desktop (1440x900).
+
+const VIEWPORTS = [
+  { width: 375, height: 812, label: 'mobile' },
+  { width: 768, height: 1024, label: 'tablet' },
+  { width: 1440, height: 900, label: 'desktop' },
+] as const;
+
+export async function captureResponsiveSet(
+  page: Page, route: string, options?: { screenshotDir?: string }
+): Promise<ResponsiveReport> {
+  const screenshotDir = options?.screenshotDir ?? 'review-captures';
+  const captures: ViewportCapture[] = [];
+  for (const vp of VIEWPORTS) {
+    await page.setViewportSize({ width: vp.width, height: vp.height });
+    const capture = attachConsoleCapture(page);
+    await page.goto(route);
+    await page.waitForLoadState('networkidle');
+    const slug = route.replace(/\//g, '-').replace(/^-/, '') || 'index';
+    const path = `${screenshotDir}/${slug}-${vp.label}.jpg`;
+    await page.screenshot({ path, type: 'jpeg', quality: 80 });
+    captures.push({ viewport: { width: vp.width, height: vp.height, label: vp.label }, screenshotPath: path, consoleErrors: capture.getErrors() });
+  }
+  await page.setViewportSize({ width: 1440, height: 900 }); // Restore default
+  return { route, captures };
+}
+
+// ── Behavioral Walkthrough ──────────────────────────
+// Click everything, fill every form, see what breaks. Exploratory, not deterministic.
+
+export async function walkInteractiveElements(page: Page): Promise<InteractionReport> {
+  const route = page.url();
+  const buttons: InteractionReport['buttons'] = [];
+  const btnLocators = page.locator('button:visible, [role="button"]:visible, [role="tab"]:visible');
+  for (let i = 0; i < await btnLocators.count(); i++) {
+    const btn = btnLocators.nth(i);
+    const text = ((await btn.textContent()) ?? '[no text]').trim();
+    const before = await page.content();
+    try {
+      await btn.click({ timeout: 2000 });
+      await page.waitForTimeout(500); // Brief wait for async response
+      buttons.push({ text, responded: (await page.content()) !== before, error: null });
+    } catch (err) { buttons.push({ text, responded: false, error: String(err) }); }
+  }
+
+  const links: InteractionReport['links'] = [];
+  const linkLocators = page.locator('a:visible');
+  for (let i = 0; i < await linkLocators.count(); i++) {
+    const link = linkLocators.nth(i);
+    links.push({ text: ((await link.textContent()) ?? '').trim(), href: await link.getAttribute('href') });
+  }
+
+  const formFields: InteractionReport['formFields'] = [];
+  const inputs = page.locator('input:visible, textarea:visible, select:visible');
+  for (let i = 0; i < await inputs.count(); i++) {
+    const input = inputs.nth(i);
+    const label = (await input.getAttribute('aria-label')) ?? (await input.getAttribute('placeholder'))
+      ?? (await input.getAttribute('name')) ?? '[unlabeled]';
+    const type = (await input.getAttribute('type')) ?? 'text';
+    try {
+      await input.fill('test-review-input');
+      await input.blur();
+      const msg = await input.evaluate((el) => (el as HTMLInputElement).validationMessage || null);
+      formFields.push({ label, type, acceptedInput: true, validationMessage: msg });
+    } catch (err) { formFields.push({ label, type, acceptedInput: false, validationMessage: String(err) }); }
+  }
+  return { route, buttons, links, formFields };
+}
+
+// ── Security Inspection ─────────────────────────────
+// Kenobi's toolkit: cookies, CORS, CSP. Runtime security inspection.
+
+export async function inspectCookies(context: BrowserContext): Promise<CookieReport> {
+  const raw = await context.cookies();
+  const findings: string[] = [];
+  const cookies = raw.map((c) => {
+    if (!c.secure) findings.push(`Cookie "${c.name}" missing Secure flag`);
+    if (!c.httpOnly && /sess|token|auth/i.test(c.name)) findings.push(`Session cookie "${c.name}" missing HttpOnly`);
+    if (c.sameSite === 'None' && !c.secure) findings.push(`Cookie "${c.name}" SameSite=None without Secure`);
+    if (c.expires === -1 && /sess|token|auth/i.test(c.name)) findings.push(`Session cookie "${c.name}" no expiry`);
+    return { name: c.name, domain: c.domain, secure: c.secure, httpOnly: c.httpOnly, sameSite: c.sameSite, expires: c.expires };
+  });
+  return { cookies, findings };
+}
+
+export async function captureCORSHeaders(page: Page, apiPattern: string): Promise<CORSReport> {
+  const report: CORSReport = { url: apiPattern, allowOrigin: null, allowCredentials: null, allowMethods: null, allowHeaders: null, findings: [] };
+  const respPromise = page.waitForResponse((r) => r.url().includes(apiPattern), { timeout: 5000 }).catch(() => null);
+  await page.evaluate(async (p) => { try { await fetch(p, { method: 'OPTIONS', mode: 'cors' }); } catch { /* expected */ } }, apiPattern);
+  const resp = await respPromise;
+  if (resp) {
+    const h = resp.headers();
+    report.allowOrigin = h['access-control-allow-origin'] ?? null;
+    report.allowCredentials = h['access-control-allow-credentials'] ?? null;
+    report.allowMethods = h['access-control-allow-methods'] ?? null;
+    report.allowHeaders = h['access-control-allow-headers'] ?? null;
+  }
+  if (report.allowOrigin === '*') report.findings.push('CORS allows all origins (*)');
+  if (report.allowOrigin === '*' && report.allowCredentials === 'true') report.findings.push('CRITICAL: Wildcard origin + credentials');
+  if (report.allowMethods?.includes('*')) report.findings.push('CORS allows all methods');
+  return report;
+}
+
+export async function captureCSPViolations(page: Page): Promise<CSPViolation[]> {
+  // Inject listener BEFORE navigating — call this, then goto(), then read violations
+  await page.addInitScript(() => {
+    const v: Array<{ blockedURI: string; violatedDirective: string; originalPolicy: string }> = [];
+    document.addEventListener('securitypolicyviolation', (e) => {
+      v.push({ blockedURI: e.blockedURI, violatedDirective: e.violatedDirective, originalPolicy: e.originalPolicy });
+    });
+    Object.defineProperty(window, '__cspViolations', { get: () => v, configurable: true });
+  });
+  // Read accumulated violations (call after navigation)
+  return page.evaluate(() => {
+    const w = window as unknown as Record<string, unknown>;
+    return (w.__cspViolations as CSPViolation[] | undefined) ?? [];
+  });
+}

package/dist/docs/patterns/combobox.tsx

@@ -0,0 +1,300 @@
+/**
+ * Pattern: Accessible Combobox with Value Source Management
+ *
+ * Key principles:
+ * - Two distinct value sources: display value (closed) and search query (open)
+ * - Never let dropdown close events switch the value source mid-keystroke
+ * - ARIA combobox role with listbox, proper focus management
+ * - Keyboard nav: arrow keys, Enter to select, Escape to close
+ *
+ * The trap: A controlled combobox shows `displayValue` when closed and
+ * `searchQuery` when open. If the search function closes the dropdown
+ * (e.g., on short queries or no results), the input switches from
+ * `searchQuery` back to `displayValue` — wiping the user's keystrokes.
+ *
+ * Agents: Legolas (code), Samwise (a11y), Bilbo (copy)
+ *
+ * Framework adaptations:
+ *   React: This file (hooks, controlled input)
+ *   Vue: v-model with computed get/set for value source switching
+ *   Svelte: Reactive declarations with $: for value derivation
+ *   Django + HTMX: Server-filtered results via hx-get, debounced hx-trigger
+ *
+ * Field report #259: Combobox value source switching caused keystroke loss
+ * when dropdown closed during typing.
+ */
+
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+// ── Types ────────────────────────────────────────────────
+
+interface ComboboxOption {
+  id: string;
+  label: string;          // Display text
+  searchText?: string;    // Optional: separate text for search matching
+}
+
+interface ComboboxProps {
+  options: ComboboxOption[];
+  value: string | null;           // Selected option ID
+  onChange: (id: string | null) => void;
+  onSearch?: (query: string) => void;  // For async/server-side search
+  placeholder?: string;
+  label: string;                  // Required — a11y
+  disabled?: boolean;
+  minSearchLength?: number;       // Min chars before showing results (default: 1)
+}
+
+// ── The Value Source Rule ────────────────────────────────
+//
+// WRONG: Derive input value from isOpen
+//   value={isOpen ? searchQuery : displayValue}
+//   // Closing the dropdown wipes searchQuery with displayValue
+//
+// RIGHT: Track value source explicitly, only switch on user actions
+//   - User types → source = 'search'
+//   - User selects option → source = 'display', close dropdown
+//   - User clicks away (blur) → source = 'display', close dropdown
+//   - User presses Escape → source = 'display', close dropdown
+//   - Dropdown closes from search logic → DO NOT switch source
+//
+// The key insight: the dropdown's open/closed state should NOT
+// control the input's value source. Only explicit user intent should.
+
+type ValueSource = 'search' | 'display';
+
+export function Combobox({
+  options,
+  value,
+  onChange,
+  onSearch,
+  placeholder = 'Search...',
+  label,
+  disabled = false,
+  minSearchLength = 1,
+}: ComboboxProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [valueSource, setValueSource] = useState<ValueSource>('display');
+  const [activeIndex, setActiveIndex] = useState(-1);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+  const listboxId = useRef(`combobox-listbox-${Math.random().toString(36).slice(2)}`);
+
+  // Derive display value from selected option
+  const selectedOption = options.find(o => o.id === value);
+  const displayValue = selectedOption?.label ?? '';
+
+  // The input shows search query OR display value based on explicit source
+  const inputValue = valueSource === 'search' ? searchQuery : displayValue;
+
+  // Filter options locally (skip if onSearch handles it server-side)
+  const filteredOptions = onSearch
+    ? options  // Server-side search — show whatever options are provided
+    : options.filter(o => {
+        if (searchQuery.length < minSearchLength) return false;
+        const text = o.searchText ?? o.label;
+        return text.toLowerCase().includes(searchQuery.toLowerCase());
+      });
+
+  // ── User types → switch to search source, open dropdown ──
+  const handleInputChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const query = e.target.value;
+    setSearchQuery(query);
+    setValueSource('search');  // Explicit: user is searching
+    setActiveIndex(-1);
+
+    if (query.length >= minSearchLength) {
+      setIsOpen(true);
+      onSearch?.(query);
+    }
+    // NOTE: Do NOT close the dropdown here even if query is short.
+    // Closing here would switch value source and wipe keystrokes.
+    // Let the empty results state handle "no results" display.
+  }, [minSearchLength, onSearch]);
+
+  // ── User selects → switch to display source, close ──
+  const handleSelect = useCallback((optionId: string) => {
+    onChange(optionId);
+    setValueSource('display');  // Explicit: user made a selection
+    setIsOpen(false);
+    setSearchQuery('');
+    setActiveIndex(-1);
+    inputRef.current?.focus();
+  }, [onChange]);
+
+  // ── User blurs → switch to display source, close ──
+  const handleBlur = useCallback((e: React.FocusEvent) => {
+    // Don't close if focus moved to the listbox
+    if (listboxRef.current?.contains(e.relatedTarget as Node)) return;
+    setValueSource('display');
+    setIsOpen(false);
+    setSearchQuery('');
+    setActiveIndex(-1);
+  }, []);
+
+  // ── Keyboard navigation ──
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        if (!isOpen) {
+          setIsOpen(true);
+          setActiveIndex(0);
+        } else {
+          setActiveIndex(i => Math.min(i + 1, filteredOptions.length - 1));
+        }
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        setActiveIndex(i => Math.max(i - 1, 0));
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (isOpen && activeIndex >= 0 && filteredOptions[activeIndex]) {
+          handleSelect(filteredOptions[activeIndex].id);
+        }
+        break;
+      case 'Escape':
+        e.preventDefault();
+        setValueSource('display');  // Explicit: user cancelled
+        setIsOpen(false);
+        setSearchQuery('');
+        setActiveIndex(-1);
+        break;
+      case 'Home':
+        if (isOpen) { e.preventDefault(); setActiveIndex(0); }
+        break;
+      case 'End':
+        if (isOpen) { e.preventDefault(); setActiveIndex(filteredOptions.length - 1); }
+        break;
+    }
+  }, [isOpen, activeIndex, filteredOptions, handleSelect]);
+
+  // Scroll active option into view
+  useEffect(() => {
+    if (activeIndex >= 0 && listboxRef.current) {
+      const activeEl = listboxRef.current.children[activeIndex] as HTMLElement;
+      activeEl?.scrollIntoView({ block: 'nearest' });
+    }
+  }, [activeIndex]);
+
+  const activeDescendant = activeIndex >= 0
+    ? `${listboxId.current}-option-${activeIndex}`
+    : undefined;
+
+  return (
+    <div className="relative" onBlur={handleBlur}>
+      <label id={`${listboxId.current}-label`} className="block text-sm font-medium">
+        {label}
+      </label>
+      <input
+        ref={inputRef}
+        role="combobox"
+        aria-expanded={isOpen}
+        aria-controls={listboxId.current}
+        aria-labelledby={`${listboxId.current}-label`}
+        aria-activedescendant={activeDescendant}
+        aria-autocomplete="list"
+        value={inputValue}
+        onChange={handleInputChange}
+        onKeyDown={handleKeyDown}
+        onFocus={() => {
+          if (displayValue) {
+            // Pre-fill search with current value so user can refine
+            setSearchQuery(displayValue);
+            setValueSource('search');
+            setIsOpen(true);
+          }
+        }}
+        placeholder={placeholder}
+        disabled={disabled}
+        className="w-full border rounded px-3 py-2 focus-visible:ring-2 focus-visible:ring-blue-500"
+      />
+      {isOpen && (
+        <ul
+          ref={listboxRef}
+          id={listboxId.current}
+          role="listbox"
+          aria-labelledby={`${listboxId.current}-label`}
+          className="absolute z-10 w-full mt-1 bg-white border rounded shadow-lg max-h-60 overflow-auto"
+        >
+          {filteredOptions.length === 0 ? (
+            <li className="px-3 py-2 text-gray-500" role="option" aria-selected={false}>
+              No results found
+            </li>
+          ) : (
+            filteredOptions.map((option, index) => (
+              <li
+                key={option.id}
+                id={`${listboxId.current}-option-${index}`}
+                role="option"
+                aria-selected={option.id === value}
+                className={`px-3 py-2 cursor-pointer ${
+                  index === activeIndex ? 'bg-blue-100' : ''
+                } ${option.id === value ? 'font-semibold' : ''}`}
+                onMouseDown={(e) => {
+                  e.preventDefault(); // Prevent blur before select
+                  handleSelect(option.id);
+                }}
+                onMouseEnter={() => setActiveIndex(index)}
+              >
+                {option.label}
+              </li>
+            ))
+          )}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+// ── Server-Side Search Example (async) ──────────────────
+//
+// function CityCombobox() {
+//   const [cities, setCities] = useState<ComboboxOption[]>([]);
+//   const [selected, setSelected] = useState<string | null>(null);
+//
+//   const handleSearch = useCallback(async (query: string) => {
+//     const results = await fetch(`/api/cities?q=${encodeURIComponent(query)}`);
+//     const data = await results.json();
+//     setCities(data.map((c: any) => ({ id: c.id, label: c.displayName })));
+//   }, []);
+//
+//   return (
+//     <Combobox
+//       options={cities}
+//       value={selected}
+//       onChange={setSelected}
+//       onSearch={handleSearch}
+//       label="City"
+//       placeholder="Search cities..."
+//       minSearchLength={2}
+//     />
+//   );
+// }
+//
+// ── Django + HTMX Adaptation ────────────────────────────
+//
+// Server-filtered combobox without client-side JS framework:
+//
+//   <input
+//     type="text"
+//     name="city"
+//     hx-get="/api/cities/"
+//     hx-trigger="input changed delay:300ms"
+//     hx-target="#city-results"
+//     hx-swap="innerHTML"
+//     role="combobox"
+//     aria-expanded="false"
+//     aria-controls="city-results"
+//     autocomplete="off"
+//   />
+//   <ul id="city-results" role="listbox"></ul>
+//
+// Server returns <li role="option"> fragments. Client-side JS
+// (minimal, not a framework) handles: aria-expanded toggle,
+// aria-activedescendant on arrow keys, selection on Enter.
+// The value source trap still applies — use a hidden input for
+// the selected ID and keep the visible input for display/search.